Code map
This page says which file holds what in the app environment under apps/, in its protocol package and in the shared agents UI, and which test file covers each area.

This page is a map of the code behind Seed Agents. Use it to find the file that holds a behaviour before you change it. The code has three parts:

Development has the commands and the step lists for common changes. The Seed software maps the rest of the repository.

The server, in apps/

apps/ is its own Bun workspace. It gets the frontend packages it uses through file: dependencies, which copy them at install time.

    src/main.ts: the Bun HTTP and WebSocket server, CORS, the webhook route, health and version, and the code that sends live events to clients.

    src/api-service.ts: the centre of the server. It holds the handling of actions, the database operations, the model turn on Pi Durable (#runPiAgent), the code of the verbs, the index of an agent's Space, the firing of triggers, and the check of subscriptions.

    src/durable-session.ts: the Pi Durable store of each session. It holds the file system that keeps the store in the database, the way a harness is opened over it, the sync document, and the tracker that turns saved partials into text deltas. See durable sessions.

    src/auth.ts: the check of the signed envelope of each request (see the signed API), the five-minute window for its timestamp, and delegation by capability.

    src/cbor.ts: the DAG-CBOR helpers for requests and responses, and the protocol version header.

    src/config.ts: every environment variable and CLI flag, with defaults.

    src/sqlite.ts and src/sqlite-schema.sql: opening the database, the schema version check and the migrations; and the schema itself.

    src/runs.ts: the durable run records and the run queue: leases, fair-share claiming, retries, cancelling a run with its children, and wake-ups by timer.

    src/run-events.ts: waiting runs and what wakes them.

    src/workflow-host.ts: the QuickJS engine that runs scripts: the lint, the setup code of the script realm, the loop that runs effects and writes them to the journal, and replay. src/workflow-worker-host.ts runs the engine on a worker thread when a flag is set.

    src/tool-documents.ts: tools as tool documents, each named by its CID. It holds the interface of authored tools, the code that turns built-in tools and MCP tools into tool documents, the validation of a tool that an agent writes, and the markdown of a contract.

    src/mcp.ts: remote MCP servers: connect, list tools, pass calls through, and the pool of connections that each run opens only when it needs one.

    src/web-tools.ts: web_search on a search backend that you host, and the web reader behind read https://…, which tries several methods in order.

    src/agent-memory.ts: the memory file system of each agent and the signed memory actions.

    src/code-exec.ts: code execution in microsandbox microVMs, with a new VM for each call or a pool of VMs that are already started.

    src/activity-monitor.ts, src/activity-triggers.ts, src/schedule-monitor.ts, src/schedule-triggers.ts: the monitors that watch for trigger events, and the code that matches an event to a trigger. See Triggers.

    src/provider-oauth.ts: the ChatGPT subscription sign-in flow.

    src/json-schema.ts: the JSON Schema validator, with fixed limits, for typed results and for the contracts of authored tools.

    src/perf.ts, src/session-perf.ts: the latency recorder behind the perf endpoints.

    src/protocol-compat.ts, src/protocol-surface.ts: the code that keeps clients on an older protocol version working, and the snapshot of the protocol that CI compares against.

    e2e/run.ts and e2e/live-gate.ts: the gate that replays recorded model answers, and the live gate against a real server and a real model.

The protocol package, in apps/protocol/

    protocol/src/index.ts: the one set of protocol types for actions, responses, session events and WebSocket events. It is the private package @seed-hypermedia/apps-protocol. protocol/PROTOCOL.md holds the versioning rules and the changelog.

    protocol/src/tool-registry.ts: the verbs and the callable tools, with the descriptions the model reads, the JSON schemas and the display data. Every word of a description is prompt text. The UI uses the same registry to draw tool rows and the forms a person fills in to run a tool themselves.

    protocol/src/write-guides.ts: the guides, one for each kind of resource, that an agent reads at ~/tools/write/<resource>.

    protocol/src/delegation.ts, protocol/src/reasoning.ts, protocol/src/model-capabilities.ts: the thoroughness presets, the table of reasoning levels for each model, and which models take images.

The shared UI

The desktop app and the web app show the same screens, from frontend/packages/ui/src/agents/. In the app describes what the screens do.

    Pages: detail.tsx, session.tsx, run.tsx (the run page, for a run with no session: its status, work, tool calls, code, and activity) and header.tsx.

    The assistant panel: assistant-panel.tsx with assistant-selection.ts, assistant-session-ref.ts, and assistant-window-context.ts.

    Pieces: dialogs.tsx, mcp-servers.tsx, memory.tsx, trigger-types.tsx, user-tool-commands.tsx, run-card.tsx, run-work.tsx, run-parked-actions.tsx, continuation.tsx, session-children.tsx, sessions-feed.tsx, new-session-composer.tsx, prompt-editor.tsx, and message-rendering.tsx.

    Data: models.ts holds every React Query hook and the signed subscriptions. client.ts signs and sends actions and builds server, WebSocket, and webhook URLs. agent-tools.ts holds the grant names and defaults. agent-session-rows.ts turns events into rows. provider-registry.ts holds the provider metadata. ../site-agents.ts, outside the agents folder, finds the agents of a space through its mount documents.

    platform.ts is the interface that each app fills in: signing, navigation, storage.

    The desktop app's version of that interface, frontend/apps/desktop/src/agents-platform.ts, signs through the daemon.

    On the web, frontend/apps/web/app/routes/hm.agents.$.tsx shows the pages and web-assistant-panel-content.tsx shows the panel. web-agents-platform.ts signs with the browser's session key and the capability that the vault gave it at sign-in.

    frontend/packages/shared/src/routes.ts defines the agent (with tab, triggerId, memoryPath), agent-session, and agent-run routes. frontend/packages/shared/src/utils/agents-routing.ts maps them to the web URLs /hm/agents/agent/<id>?server=&tab=&trigger=&file=, /hm/agents/session/<id>?server=&agent=, and /hm/agents/run/<id>?server=&agent=, and back, so a copied web link opens in the desktop app.

    frontend/packages/apps-ui/ packages these screens for apps outside the repository. One provider component fills in the platform interface from the server URL and the signer that the host app gives it, and the build bundles the shared code. See Embedding the agents UI.

Shared Hypermedia code

The server uses Hypermedia code from @seed-hypermedia/client, the SDK: resource-read.ts (resolveIdWithClient, which the CLI uses too), hm-resolver.ts, blocks-to-markdown.ts and markdown-to-blocks.ts, explore-query.ts, and the code that signs blobs and encodes DAG-CBOR. It imports the last two through @shm/shared/blobs and @shm/shared/cbor.

Test map

bun test, run in apps/, runs the whole suite of the server. The test files are beside the source in apps/src/.

    api-service.test.ts: the largest file: actions, ownership, sessions, delegation, obligations, plans.

    durable-session.test.ts: the durable session runtime: one conversation over several turns, a prompt prefix that stays the same byte for byte, a turn that continues from its checkpoint after the process dies, and a lost store built again from the log.

    verbs.test.ts: the five verbs (read, write, call, delegate, plan): address handling, touch-expand, promotion, and verbs that a user runs.

    tool-documents.test.ts: CIDs, built-in tools as tool documents, and the validation of authored tools.

    runs.test.ts, run-time.test.ts: claiming from the queue, leases, sweeps, and runs that wait and wake.

    workflow-host.test.ts, workflow-worker.test.ts: the script engine: lint, replay of the journal, fuel and limits, and the link to the worker thread.

    activity-triggers.test.ts, activity-conditions.test.ts, activity-monitor.test.ts, trigger-events.test.ts, activity-trigger-race.test.ts, schedule-triggers.test.ts: trigger matching, conditions with several parts, the watermark of the monitor, firing only once, and the race between a comment and the citation it creates.

    agent-memory.test.ts, session-attachments.test.ts, code-exec.test.ts, exec-pool.test.ts, exec-verify.test.ts, web-tools.test.ts, agent-tools-api.test.ts, mcp.test.ts, session-continuation.test.ts, write-link-validation.test.ts.

    auth.test.ts, sqlite.test.ts, main.test.ts, config.test.ts, json-schema.test.ts, poll-loop.test.ts, provider-oauth.test.ts, protocol-surface.test.ts, statements.test.ts, perf.test.ts, session-perf.test.ts.

    e2e-replay.test.ts runs e2e/run.ts, the replay gate. While the file e2e/recordings/STALE.md exists, the replay skips and passes. So a passing run does not prove that the gate ran. To bring the gate back, record new cassettes and delete that file.

Frontend: the agents tests of the shared UI are in frontend/packages/ui/src/__tests__/, the desktop app's are in frontend/apps/desktop/src/__tests__/, and the web app's are in frontend/apps/web/app/__tests__/. Put new tests for pages or hooks beside those.

Testing the app environment explains the suites and the gates in full.

See also

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

Unsubscribe anytime

People