AGENTS.md

1# apps/daemon/AGENTS.md
2 
3Follow the root `AGENTS.md` and `apps/AGENTS.md` first. This file records daemon-specific code organization and editing rules.
4 
5## Role
6 
7`apps/daemon` is the local Express + SQLite daemon and owns:
8 
9- `/api/*` HTTP routes and SSE streams.
10- The `od` CLI entrypoint in `src/cli.ts`.
11- Project persistence, generated files, artifacts, media, skills, design systems, plugins, MCP, connector credentials, automation state, agent spawning, and static serving.
12- The daemon sidecar entry under `sidecar/`.
13 
14The daemon is not a shared library for the web app. Do not import daemon private `src/` modules from `apps/web`; shared web/daemon contracts belong in `packages/contracts`.
15 
16## Source Layout
17 
18- `src/server.ts` is the composition root: create process-wide services, build dependency objects, install middleware, and register route modules. Keep request/domain logic out of `server.ts` unless the route is genuinely bootstrap-wide.
19- `src/cli.ts` is the CLI composition root: parse top-level commands, dispatch subcommands, and format process output. Keep substantial command implementation in domain modules or focused `*-cli.ts` helpers.
20- `src/server-context.ts`, `src/route-context-contract.ts`, `src/route-registration-guard.ts`, and small root constants/startup helpers may stay at the top level because they describe daemon-wide wiring.
21- `src/routes/` contains domain route registrars that were split out of `server.ts`. New daemon domain endpoints should normally land here.
22- Legacy route files still at `src/*-routes.ts` may remain until touched. When making meaningful changes in one, prefer moving it to `src/routes/<domain>.ts` if the move is small and mechanically safe.
23- `src/http/` owns shared HTTP helpers, error/result adapters, origin checks, and route mounting utilities.
24- `src/services/` owns reusable daemon services that are not tied to Express request/response objects.
25- `src/runtimes/` owns agent runtime definitions, spawning, parser integration, executable discovery, and runtime environment shaping. Agent argument definitions belong in `src/runtimes/defs/`.
26- `src/prompts/` owns daemon-side prompt construction. Keep mirrored BYOK/API wording in `packages/contracts/src/prompts/` when the same text is exposed outside the daemon.
27- `src/plugins/`, `src/connectors/`, `src/registry/`, `src/research/`, `src/media-adapters/`, `src/live-artifacts/`, `src/storage/`, and `src/critique/` own their named domains. Prefer adding code inside the existing domain folder before creating a new top-level folder.
28- Team resource storage is Vela-owned. Daemon adapters under `src/collab/vela-cli-*` must invoke Vela through `src/integrations/vela-command.ts`, which shares the login/agent binary resolver and environment. Do not add Resource Hub tokens, direct HTTP clients, or a second content-addressed drive implementation to Open Design. `od resource` is only a thin Vela CLI compatibility entry point.
29- `tests/` contains daemon tests. Keep test paths roughly parallel to `src/` when useful.
30 
31Do not edit generated `dist/` output.
32 
33## Top-Level `src/` Hygiene
34 
35Do not keep adding unrelated files directly under `src/`. The top level is currently crowded, so use these rules for new code and for touched legacy files:
36 
37- New domain code belongs in a domain folder, not in `src/<feature>.ts`, unless it is a daemon-wide primitive.
38- New route code belongs in `src/routes/` or an existing route subfolder such as `src/routes/plugins/`.
39- New runtime or stream-parser code belongs in `src/runtimes/`, with runtime definitions in `src/runtimes/defs/`.
40- New provider/integration client code belongs in the existing domain folder when one exists, or under `src/integrations/<provider>.ts` for provider-specific glue.
41- New persistence/storage abstractions belong in `src/storage/` unless they are tightly coupled to the legacy SQLite facade in `src/db.ts`.
42- New prompt construction belongs in `src/prompts/`.
43- New plugin, connector, registry, research, media adapter, live-artifact, critique, metrics, logging, QA, or GenUI code belongs in the matching existing folder.
44- New general-purpose helpers should be avoided. If a helper has a real owner, put it with that owner. If it is daemon-wide infrastructure, use a focused folder such as `src/http/`, `src/services/`, `src/storage/`, or `src/runtimes/` instead of creating another top-level utility file.
45 
46When touching a legacy top-level file:
47 
48- Prefer a small, safe move into an existing domain folder when imports are straightforward and the change is already about that domain.
49- Do not mix a broad mechanical move with behavior changes unless the move is required to make the behavior change understandable.
50- If a file is split, keep the public function names stable at call sites where possible and move tests with the behavior they cover.
51- Use temporary root-level compatibility exports only when they materially reduce churn; remove them in the same PR if the diff stays small.
52 
53Suggested ownership for common legacy top-level families:
54 
55- `project-routes.ts`, `import-export-routes.ts`, `mcp-routes.ts` -> `src/routes/`. (Route modules already split out, such as `routes/chat.ts`, `routes/terminal.ts`, and `routes/social-share.ts`, are done; do not list them here.)
56- `copilot-stream.ts`, `acp.ts`, `agents.ts`, `run-*`, `agent-*`, `*-diagnostics.ts` -> usually `src/runtimes/` or a future `src/runs/` folder, depending on ownership. (`claude-stream.ts`, `qoder-stream.ts`, `json-event-stream.ts`, and `runs.ts` already live under `src/runtimes/`.)
57- `design-systems-cli-help.ts`, `tools-design-systems-cli.ts`, `claude-design-import.ts` when used only there -> `src/design-systems/`. (Core design-system modules, design tokens, `swift-colors.ts`, and `frontmatter.ts` are already under `src/design-systems/`.)
58- `inline-assets.ts`, `lint-artifact.ts`, `pdf-export.ts`, `document-preview.ts`, `static-spa.ts` -> `src/artifacts/` or the existing artifact owner. (The `artifact-*` family already moved under `src/artifacts/`.)
59- `memory*.ts`, `orbit*.ts`, `automation-*.ts`, `routines.ts`, `prompt-*`, `handoff-*`, `finalize-design.ts` -> keep with their domain; introduce folders when touching multiple related files.
60 
61The `media-*` family has already moved into `src/media/`; no media modules remain at the top level.
62 
63These are migration targets, not permission to do a large cleanup PR. Move only what helps the current change or removes active ambiguity.
64 
65## Route Structure
66 
67Route modules should follow this shape:
68 
69```ts
70import type { Express } from 'express';
71import type { RouteDeps } from '../server-context.js';
72 
73export interface RegisterExampleRoutesDeps extends RouteDeps<'http' | 'paths'> {
74  example: ExampleService;
75}
76 
77export function registerExampleRoutes(app: Express, ctx: RegisterExampleRoutesDeps): void {
78  // app.get/post/patch/delete(...)
79}
80```
81 
82Guidelines:
83 
84- Keep one exported registrar per domain, except where the existing file already has a small family of closely related registrars.
85- Declare a narrow `Register*RoutesDeps` type. Pick only the `ServerContext` keys the route uses, and add explicit service interfaces for domain-specific dependencies.
86- Add the registrar dependency type to `src/route-context-contract.ts` when it should be covered by the server context assertion.
87- Register the route from the matching semantic section in `src/server.ts`.
88- Use existing route helpers from `src/http/` when they fit. Do not invent another error envelope if a contract already exists.
89- Keep parsing/validation near the route boundary and push reusable behavior into named helpers or services.
90- Do not add new route handlers directly to `server.ts` unless they are bootstrap-wide process metadata such as health/version.
91 
92## Dependency Boundaries
93 
94- `src/server-context.ts` is the route dependency map. If a route needs a new cross-route dependency, add it there deliberately and keep its type narrow.
95- Prefer explicit domain service interfaces in route files over `any` or `unknown`.
96- Use types from the implementation module or `packages/contracts` instead of restating response shapes by hand.
97- Keep `packages/contracts` pure. Do not move daemon-only Node, SQLite, Express, filesystem, or process types into contracts.
98- Daemon data paths must follow the root **Daemon data directory contract**. Route all daemon-owned data through `RUNTIME_DATA_DIR` or constants derived from it.
99 
100## CLI and Surface Parity
101 
102User-facing capabilities must be reachable through both:
103 
104- Web/API routes in the daemon.
105- `od` CLI subcommands in `src/cli.ts`.
106 
107When adding a user-facing capability, close the loop in one change: contract type, daemon route, web surface if applicable, and CLI command with `--json` plus `--prompt-file <path|->` for long prompts where relevant.
108 
109## Runtime and Agent Changes
110 
111- Parser changes belong beside the matching runtime stream helper and should include focused parser tests.
112- Runtime definition changes belong in `src/runtimes/defs/`.
113- For agent-stream/parser changes, replay a mock CLI trace from `mocks/` when practical instead of burning provider budget.
114- Preserve Claude stream-json bookkeeping in `src/runtimes/claude-stream.ts` and `src/server.ts`; do not close stdin on `tool_use` stop reasons.
115 
116## Tests
117 
118- Tests belong under `apps/daemon/tests/`, not under `src/`.
119- Use the cheapest layer that can observe the behavior: pure helper test, route-level Vitest with `startServer`, then broader integration only when necessary.
120- For bug fixes, prefer a red spec that fails before the fix.
121- If a test depends on native modules such as `better-sqlite3`, make sure local dependencies were built for the active Node version before blaming the code.
122 
123## Commands
124 
125Common daemon checks:
126 
127```bash
128pnpm --filter @open-design/daemon typecheck
129pnpm --filter @open-design/daemon test
130pnpm --filter @open-design/daemon build
131```
132 
133Focused tests from `apps/daemon`:
134 
135```bash
136pnpm exec vitest run -c vitest.config.ts tests/&lt;file&gt;.test.ts
137```
138 
139For local runtime validation, start through the repo control plane, not daemon package lifecycle aliases:
140 
141```bash
142pnpm tools-dev run web --daemon-port &lt;port&gt; --web-port &lt;port&gt;
143```
144 
145## Review Checklist
146 
147Before handing off daemon changes, check:
148 
149- Route logic is in a route module, not newly embedded in `server.ts`.
150- New route deps are explicit and covered by `route-context-contract.ts` where appropriate.
151- Shared DTOs or error shapes live in `packages/contracts` when the web or CLI consumes them.
152- CLI parity is handled or explicitly not applicable.
153- Daemon data paths derive from the resolved daemon data root.
154- Tests are under `tests/` and relevant checks were run.
155