diff --git a/AGENTS.md b/AGENTS.md index 416958e4..7f5ab11c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,9 +17,11 @@ and the enforce most code conventions; run them before saying the tree passes. These are the ones no check catches: -- Build on Interchange's agent loop, retries, waits, timeouts, mail, approvals - and failure handling rather than reimplementing them, and read the area's - Interchange doc first. +- Build on Interchange for anything it owns (agents, workflows, tools, + compaction, mail, approvals, credentials, isolation) rather than + reimplementing it, and raise what falls between Interchange, Corbits packages + and Builder before building it + ([who owns what](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what)). - The interface talks to the hub through `@corbits-builder/client`. - A change to `vendor/interchange` is its own `(vendor)` commit that also updates `vendor/interchange.manifest.json`. diff --git a/apps/hub/README.md b/apps/hub/README.md index 541dc5a3..f3bace84 100644 --- a/apps/hub/README.md +++ b/apps/hub/README.md @@ -34,12 +34,12 @@ from `.env.hub.example`; [setup][setup] covers both. `bun run dev` migrates the database and starts the hub with the interface, and `bun run start` runs the hub alone. `bun run lint`, `bun run format:check`, `bun run typecheck` and `bun run test` check it. The -[Interchange docs map][interchange-docs] lists the Interchange doc for each -area; read it before building on one. +[ownership notes][interchange-docs] say what Interchange, Corbits packages +and the hub each own. [workflows]: https://github.com/corbitsdev/corbits-builder/tree/main/workflows [schemas]: https://github.com/corbitsdev/corbits-builder/tree/main/packages/schemas [client]: https://github.com/corbitsdev/corbits-builder/tree/main/packages/client [web]: https://github.com/corbitsdev/corbits-builder/tree/main/apps/web [setup]: https://github.com/corbitsdev/corbits-builder/blob/main/CONTRIBUTING.md#setup -[interchange-docs]: https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#interchange-docs-map +[interchange-docs]: https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what diff --git a/docs/DEV.md b/docs/DEV.md index ad399fc0..44c7bc5f 100644 --- a/docs/DEV.md +++ b/docs/DEV.md @@ -32,8 +32,8 @@ The roles: Each role runs on the tier its profile assigns ([apps/hub/src/config/models.ts](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/config/models.ts)), so any connected provider can run any role. The project's conventions are in -[AGENTS.md](https://github.com/corbitsdev/corbits-builder/blob/main/AGENTS.md), and the Interchange doc for each area in -[IMPLEMENTATION.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#interchange-docs-map). +[AGENTS.md](https://github.com/corbitsdev/corbits-builder/blob/main/AGENTS.md), and what Interchange, Corbits packages and Builder each own in +[IMPLEMENTATION.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what). ## Model profile choice diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md index 6cb077d1..fe5c84d7 100644 --- a/docs/IMPLEMENTATION.md +++ b/docs/IMPLEMENTATION.md @@ -66,8 +66,8 @@ Skills are packed into the bundle at build time with a Bun macro. ### Hub tools -The tools agents call are tool packages that reach the hub's API with the -run's own credential: +The tools agents call live in the hub and reach the hub's API with the run's +own credential: - documents: `read_artifact`, `write_artifact` ([apps/hub/src/artifacts/tools.ts](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/artifacts/tools.ts)); @@ -83,6 +83,10 @@ run's own credential: installs, app status, browser) ([apps/hub/src/builds/](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/builds)). +Builder's tool packages (`tools-*`) follow Interchange's tool-package +convention (`vendor/interchange/packages/agent/CONVENTIONS.md`), and keep each +tool's logic a plain function so a workflow action can call it directly. + The coder's browser tools are Playwright's MCP server inside its sandbox, limited to loopback; its web search is Exa's MCP server ([apps/hub/src/config/mcp.ts](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/config/mcp.ts)). @@ -173,27 +177,29 @@ updates [vendor/interchange.manifest.json](https://github.com/corbitsdev/corbits-builder/blob/main/vendor/interchange.manifest.json). `bun run vendor:verify` fails on any unrecorded change. -## Interchange docs map - -Read the doc for an area before changing code in it. All are under -[vendor/interchange/docs/](https://github.com/corbitsdev/corbits-builder/blob/main/vendor/interchange/docs). - -| Area | Doc | -| ---------------------------------------------------- | ------------------------------------------------------ | -| Concepts: definitions, principals, offerings | `ARCHITECTURE.md`, `IMPLEMENTATION.md` | -| Definitions, triggers, gates, child workflows, loops | `WORKFLOW_AUTHORING.md` | -| Warm agents, step lifecycle, mail drain, cancel | `unified-execution-host-design.md` | -| Sidecar, workflow child, harness | `HARNESS_DESIGN.md` | -| Inference turns, tool execution, doom loop | `INFERENCE.md` | -| Mail transport and admission | `MESSAGE.md`, `INBOUND_MAIL_POLICY.md` | -| Approvals, grants, credentials, definition hashes | `AUTH.md`, `CREDENTIALS.md` | -| Git repositories and tokens | `GIT_ACCESS.md` | -| Lifetimes, cancellation, drain, placement | `workflow-lifecycle-policy.md`, `SIDECAR_PLACEMENT.md` | -| Routes | `ROUTES.md` (`API.md` is generated; never edit it) | -| Publishing the `@intx/*` packages | `PUBLISHING.md` | - -A vendor design marked as not yet built is not a capability; confirm the code -exists in `vendor/interchange` before relying on it. +## Who owns what + +Builder sits on two sets of packages it does not own. Use theirs before +writing anything of its kind. + +- **Interchange** (`@intx/*`) owns running agents: workflows, triggers and + gates, the agent loop, tools and tool packages, directors and compaction, + inference providers, mail, approvals, grants and credentials, sidecars and + isolation, lifetimes and cancellation. Its docs are under + [vendor/interchange/docs/](https://github.com/corbitsdev/corbits-builder/blob/main/vendor/interchange/docs), + and each package documents itself in `vendor/interchange/packages//`. + A vendor design marked as not yet built is not a capability; confirm the + code exists before relying on it. +- **Corbits packages** (`@corbits/*`) are shared across Corbits products: + document storage (`artifacts`), the interface kit (`react-ui`), provider + adapters and logins, MCP and agent tokens. +- **Builder** owns the product on top: projects and their documents, the + hub's own routes and tenant state, the role workflows, prompts and skills, + its tool packages, product configuration and the interface. + +When a change needs something that none of them clearly owns, or that one of +the first two almost covers, raise it before building: it may belong upstream, +as a deliberate vendor change, or in a Corbits package. `@intx/*` packages come from npm where a published version serves. A package is vendored only when Builder patches it or needs Interchange's main past the