Development
This page shows how to run, check and change the app environment and its shared UI, with the conventions to follow and a step list for each common change.

This page is for people and coding agents who change the code behind Seed Agents. That code is the app environment server in apps/, and the agents UI that the desktop app and the web app share. The page says how to run and check them, which conventions to follow, and which steps to take for each common change.

Read these first:

    The root AGENTS.md.

    apps/AGENTS.md, for the server. Its two main rules: use Bun only, never pnpm, and run bun check && bun test before every commit.

    frontend/AGENTS.md, for UI work.

Three other pages go with this one. Contributing has the setup of the repository. Code map says which file holds what. Testing the app environment explains the test suites and gates.

Commands

Start the whole stack in one mprocs window. It has one pane for each process: the Docker web backends, the desktop app, the web app, the app environment and others. q stops everything.

./dev up

Start the app environment alone:

direnv exec . bash -lc 'cd apps && bun src/main.ts' # plain direnv exec . bash -lc 'cd apps && bun run dev' # hot reload, dev web backends, subscription auth on

Check the server:

direnv exec . bash -lc 'cd apps && bun check && bun test' # typecheck + formatter, then the suite direnv exec . bash -lc 'cd apps && bun run test:build' # the compiled binary boots direnv exec . bash -lc 'cd apps && bun run test:docker' # the image boots direnv exec . bash -lc 'cd apps && bun run test:trigger' # the real server, mention trigger fires once direnv exec . bash -lc 'cd apps && bun run test:outbox' # the real server, effect outbox across kill -9, disk floor, ENOSPC direnv exec . bash -lc 'cd apps && bun run protocol:check' # the protocol surface did not change silently

Check the frontend:

direnv exec . bash -lc 'pnpm typecheck' direnv exec . bash -lc 'pnpm test' direnv exec . bash -lc 'pnpm format:check'

Build the deployment image and run the desktop app:

docker build -t seedhypermedia/apps:dev . -f ./apps/Dockerfile direnv exec . bash -lc './dev run-desktop'

CI publishes the image as seedhypermedia/apps, and it pushes each tag under the name seedhypermedia/agents too.

Local URLs

.env.vars sets SEED_APPS_HTTP_PORT=3051 in the development shell. So the development server never shares a port with a packaged build, which uses 3050.

The API is under the prefix /hm/api/apps. The same routes answer under /hm/api/agents, the older prefix that released clients and existing webhook URLs use. Endpoints and health lists every path, including the older ones with no prefix.

what

dev URL

server base

http://localhost:3051

health

http://localhost:3051/hm/api/apps/health

version

http://localhost:3051/hm/api/apps/version

signed API

POST http://localhost:3051/hm/api/apps/message

WebSocket

ws://localhost:3051/hm/api/apps/ws

latency snapshot

http://localhost:3051/hm/api/apps/perf and /hm/api/apps/perf/sessions/<sessionId>

metrics

http://localhost:3051/hm/api/apps/metrics

Conventions

    Normalize input from users and from the network where it enters the API. Internal code expects normalized values.

    Never hold a SQLite write transaction around a model, provider, or tool network call.

    Never log secrets, signed bodies, or full session or model content.

    The protocol types are in apps/protocol/src/index.ts. Do not write copies of them in the desktop app or the server. A change to the protocol must pass bun run protocol:check. A breaking change raises the protocol version, by the rules in apps/protocol/PROTOCOL.md.

    A response that describes a model provider never includes its secrets.

    Prefer broad tests that run real behaviour. Prefer an existing file over a new, very small module.

Adding an API action

    Add the request and response types to apps/protocol/src/index.ts.

    Handle it in Service.message(). Validate the input and check that the account owns what it touches.

    If a client retry could repeat a side effect, make the action safe to repeat.

    Emit service events if connected clients need the update.

    Add the hook in models.ts and any UI.

    Add tests, run protocol:check, and update the signed API.

Adding a WebSocket event

    Extend AgentWSEvent in the protocol package.

    Emit the service event where the change happens. Map it in main.ts, in the code that sends events to clients.

    Handle it in the subscription hook in models.ts.

Changing the database

    Edit sqlite-schema.sql, the fresh-install baseline.

    Add the migration at the start of the migrations array in sqlite.ts. The code reverses the array, so the newest entry runs last. Never edit or reorder a migration that has shipped.

    Keep the two equal: an old baseline plus every migration must produce the schema in sqlite-schema.sql. sqlite.test.ts builds an old baseline, applies the migrations, and checks the tables and columns that result. Add yours to those checks. The test does not compare the whole schema.

    Never accept an unknown or newer schema version without an error.

    Update persistence.

Changing the model-facing surface

The model-facing surface is everything the model sees as a tool. It is only the verbs: the five working verbs, plus status and continue_session. A new ability arrives as an address, an option or a callable. It never arrives as another verb without a design discussion.

    A new address form for read or write goes in two places: the description of the verb in the tool registry, and the address handling in api-service.ts. The description is prompt text, so edit it with that care.

    A new callable goes in callableToolRegistry, with runtimes that include agent-service. The model reaches it through call. Never add it to the provider payload directly. The next listing turns it into a tool document for every agent, and the change of its CID is the new version.

    Keep touch-expand working: a call that is wrong, or that names a tool the model has not opened, answers with the contract and never with an error.

    Filter anything promoted into the provider payload against the callables the agent has turned on. Promotion comes from durable events. Without the filter, a tool name that the model made up could turn on a real tool.

    Grants are the callable set, publish, and the enabled MCP servers. Do not add a grant for a verb.

    Update tools and security. If you made a new word for the mechanism, add a term page and list it in the glossary.

Adding a provider

    Add the PROVIDER_SPECS entry in api-service.ts and the matching PROVIDER_METADATA entry in the UI's provider-registry.ts.

    If the model has reasoning levels, add its generation to reasoning.ts, with a note on how you checked the levels. If it takes images, add it to model-capabilities.ts.

    Keep the session lifecycle and the WebSocket partials working. Check that the entries of the durable store become message, tool_call and tool_result events in the right order.

    Add tests with a fake network for these cases: success, streaming, text that comes before a tool call, tools, a missing key, and provider errors.

    Check that decrypted secrets stay in memory. They must never reach the durable store or a Pi auth file.

Changing a prompt

What an agent is told lists every source of model-facing text. When you change one:

    When the behaviour should apply everywhere, change the shared instructions first.

    Keep what #agentSystemPrompt() builds small and in order. Every part you add uses context on every turn.

    To remind the model of the state at this moment, use a part that lasts one turn. To record something that happened, use a durable event.

    If a new part wraps text that anyone but the server wrote, escape the text and add the part to the list of untrusted sources on that page.

    When the behaviour depends on tool use, update the tool descriptions in apps/protocol/src/tool-registry.ts.

    Look at a live session through GetSession.systemPromptMarkdown, or in the system prompt dialog of the session.

Security checks for new work

Security explains the security model that these steps protect.

For every new action:

    Check the signature.

    Check that the signer may act for the account.

    Normalize the input where it enters.

    Limit every database query to what the account owns.

    Remove sensitive data from what you return and log.

    Add tests for a caller with no right and for a caller from another account. For an action on one agent, also test reader against writer, and pending against accepted.

    Decide what happens when the same request arrives twice.

    Decide which WebSocket clients receive the event.

For every new tool or address form:

    Add or update the one registry entry in apps/protocol/src/tool-registry.ts. Then the prompt text, the input schema and the display data are reviewed together.

    Decide the grant: the callable set, publish, or no grant.

    Validate the input where it enters the runtime. If it does not fit, return the contract.

    Limit the size of the output.

    If the tool can be promoted, check that the promotion filter still works.

    If text that the model wrote goes back into the prompt inside a wrapper, escape it.

    Do not log sensitive data.

    Add tests for missing credentials and for provider or tool errors.

Which page to update

Documentation is part of the change. Update it in the same commit.

Manual smoke test

After a change to the core of the server, go through these steps by hand:

    Start a server and the app. Set up a provider and create an agent.

    Open a session and send a message. Check that it shows at once, that the subscription works, and that the reply streams as markdown.

    Ask the agent to read a Seed URL, and also a web URL on a custom domain. Check that the row shows the target it resolved to. Then ask it to read ~/tools/ and read ~/memory/.

    Check that a call of a tool the model has not opened comes back as the contract.

    Ask for a task with three or more steps and two delegations. Check four things. The pinned card shows the checklist with both children side by side. Each child is attached to the step that is running. The parent continues with the results. The card becomes a fixed part of the transcript when the run ends.

    Ask the agent to write a tool for itself and call it. Check that the row shows under Custom tools.

    Type / in the message box and run Read. Check that the row has the You chip, and that the agent refers to the read on its next turn.

    Reload. Check that the transcript, the run cards and the state of the cards come back.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Attributes
name
Development
summary
This page shows how to run, check and change the app environment and its shared UI, with the conventions to follow and a step list for each common change.