AGENTS.md

1# packages/AGENTS.md
2 
3Follow the root `AGENTS.md` first. This file only records module-level boundaries for `packages/`.
4 
5## Package responsibilities
6 
7- `packages/agui-adapter`: pure TypeScript adapter between persisted Open Design agent/GenUI/plugin-pipeline events and the AG-UI event protocol. Keep transport and filesystem concerns out; daemon producers and web/CopilotKit consumers share this conversion boundary.
8- `packages/contracts`: web/daemon app contract layer. Keep it pure TypeScript; it must not depend on Next.js, Express, Node filesystem/process APIs, browser APIs, SQLite, daemon internals, or the sidecar control-plane protocol.
9- `packages/components`: shared React UI primitives and primitive CSS. It may depend on React types/runtime only; keep product workflows and app-specific layout/styling in the apps.
10- `packages/diagnostics`: shared diagnostics export primitives for log collection, redaction, manifests, crash-report discovery, and zip packaging used by daemon and desktop.
11- `packages/download`: managed-download runtime. Owns resumable and checksum-verified transfers, concurrent-request deduplication, target locking, inspection/removal, copy-and-clear, and pruning; callers supply the download identity and storage base.
12- `packages/host`: web/desktop host bridge contract. It models renderer-facing host capabilities and helpers while keeping `window.__od__` access out of app UI code.
13- `packages/launcher-proto`: launcher protocol and path/state primitives. Owns channel/version/namespace validation, launcher directory derivation, runtime and cleanup descriptors, target selection, and after-quit argument parsing without owning launcher process orchestration.
14- `packages/metatool`: internal metadata helpers for repo-local tool build outputs. Keep reusable hash/check/write mechanics here; each concrete tool owns its own `meta.json`.
15- `packages/plugin-runtime`: pure TypeScript plugin manifest/marketplace parsers, source adapters, merge/ref resolution, validation, digesting, and pipeline-fallback selection. Daemon, web, and CI inject I/O rather than adding filesystem access here.
16- `packages/registry-protocol`: pure TypeScript plugin-registry backend protocol and schemas. Owns backend list/search/resolve/manifest/doctor plus optional publish/yank interfaces, not concrete network or storage integrations.
17- `packages/release`: pure release-domain primitives. Owns release channel names, version parsing/formatting, metadata field derivation, storage prefixes, release namespaces, and app identity data. It must not read/write files, call GitHub/R2, spawn build tools, or own workflow execution.
18- `packages/sidecar-proto`: Open Design sidecar business protocol. Owns app/mode/source constants, namespace validation, stamp descriptor/fields/flags, IPC message schema, status shapes, error semantics, and default product path constants.
19- `packages/sidecar`: generic sidecar runtime primitives. Includes bootstrap, IPC transport, path/runtime resolution, launch env, and JSON runtime file helpers; it must not hard-code Open Design app keys or IPC business messages.
20- `packages/platform`: generic OS process primitives. Includes stamp serialization, command parsing, process matching/search, and well-known user-toolchain bin discovery; it must consume the `sidecar-proto` descriptor and must not hard-code `--od-stamp-*` details. The toolchain helper is the single source of truth shared by the daemon runtime executable resolver (`apps/daemon/src/runtimes/executables.ts`) and the packaged sidecar PATH builder (`apps/packaged/src/sidecars.ts`) so neither layer can drift the search list.
21 
22## Removed directories
23 
24- `packages/shared` has been removed; do not restore it.
25- For new shared types, choose the boundary first: web/daemon app DTOs go in `contracts`; sidecar control-plane protocol goes in `sidecar-proto`; generic runtime code goes in `sidecar`; generic OS/process code goes in `platform`.
26 
27## Boundary checklist
28 
29- Package tests live in each package's `tests/` directory, sibling to `src/`; keep `src/` source-only and do not add new `*.test.ts` or `*.test.tsx` files under `src/`.
30- Keep cross-runtime DTO and plugin wire-shape validation schemas in `contracts` when callers need the same runtime parser, while keeping app-specific parsing, I/O, and enforcement in the owning app or package.
31- Do not let app packages depend directly on sidecar control-plane details.
32- Do not hard-code Open Design app/source/mode constants in `sidecar` or `platform`.
33- Keep stamp fields limited to five: `app`, `mode`, `namespace`, `ipc`, and `source`.
34 
35## Common package commands
36 
37```bash
38pnpm --filter @open-design/agui-adapter typecheck
39pnpm --filter @open-design/agui-adapter test
40pnpm --filter @open-design/contracts typecheck
41pnpm --filter @open-design/diagnostics typecheck
42pnpm --filter @open-design/diagnostics test
43pnpm --filter @open-design/download typecheck
44pnpm --filter @open-design/download test
45pnpm --filter @open-design/host typecheck
46pnpm --filter @open-design/host test
47pnpm --filter @open-design/launcher-proto typecheck
48pnpm --filter @open-design/launcher-proto test
49pnpm --filter @open-design/metatool typecheck
50pnpm --filter @open-design/metatool test
51pnpm --filter @open-design/plugin-runtime typecheck
52pnpm --filter @open-design/plugin-runtime test
53pnpm --filter @open-design/registry-protocol typecheck
54pnpm --filter @open-design/registry-protocol test
55pnpm --filter @open-design/release typecheck
56pnpm --filter @open-design/release test
57pnpm --filter @open-design/sidecar-proto typecheck
58pnpm --filter @open-design/sidecar-proto test
59pnpm --filter @open-design/sidecar typecheck
60pnpm --filter @open-design/sidecar test
61pnpm --filter @open-design/platform typecheck
62pnpm --filter @open-design/platform test
63```
64