Development guide
The setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI organization. Design rationale and implementation details belong to the linked Agent Notes and scripts.
Setup tutorial
Prerequisites
- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the Node engine floor Agent Note.
- Corepack-enabled pnpm. The repo pins
pnpm@11.7.0inpackage.json; runcorepack enableifpnpm --versiondoes not resolve through Corepack. - Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.
- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.
First-time setup
Install dependencies from the repo root:
pnpm install
The install also configures worktree-local Lefthook hooks and the dsh-translation-pairing Git merge driver through scripts/install-lefthook.mjs. The worktree-local hooks Agent Note owns the hook-path safety contract; the automatic pairing merges Agent Note owns the merge driver.
If either integration is missing because dependencies were restored from cache or postinstall was skipped, install them manually:
node scripts/install-lefthook.mjs
If the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.
Run typecheck once after a fresh clone:
pnpm run typecheck
Setup is complete when pnpm run typecheck exits successfully.
Contributor reference
TypeScript project layout
The repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in tsconfig.host.json and Client packages in tsconfig.client.json.
| File | Role | Forms a program? |
|---|---|---|
tsconfig.json |
Solution root: extends base, files: [], and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited paths, it is also the resolution config for tsx running examples/ and scripts/. |
No |
tsconfig.host.json |
Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of api/remotes. |
Yes |
tsconfig.client.json |
Client aggregate: packages/client/* packages and their tests, apps/web, and the exceptional Client project of api/remotes. |
Yes |
tsconfig.base.json |
Shared compilerOptions and the source paths map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no include, so its paths apply to every importer. |
No |
tsconfig.base.client.json |
Browser compiler settings (jsx, DOM libs, types: []) extended by the Client aggregate and every packages/client/* package. |
No |
Host and Client stay two aggregate programs because both sides declaration-merge the cordis Context interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a ts.Program — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:
tsconfig.base.jsonnever gainsincludeorfiles: they would leak into every extending package project and narrow the facade's match-all scope.- A script that builds a repo-wide
ts.Programseedstsconfig.host.jsonortsconfig.client.jsonexplicitly — never the root solution, because flattening both aggregates into one program collides theContextmerges. - A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.
api/remotes is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host Typert graph, while its Client entry imports /remote declarations that Host tsdown must generate first. The package-root tsconfig.json is therefore only a solution, and the two aggregates and direct consumers reference tsconfig.host.json or tsconfig.client.json respectively. The workspace constraints gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf; it discovers split packages from the presence of both leaf configs, so a new split joins the gate automatically. Do not copy this structure to other packages; the api-remotes README explains the Host/Client split and build order.
The root build follows the generated dependency order:
tsc -b tsconfig.host.json
tsdown --env.DSH_BUILD_FACE host
tsc -b tsconfig.client.json
tsdown --env.DSH_BUILD_FACE client
pnpm run build:web
Both tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through DSH_BUILD_FACE: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; api-remotes uses hostPhase: true to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to lib/types by the preceding tsc phase.
Typert runs only during Host tsdown, seeded by tsconfig.host.json. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start Typert. Consequently, pnpm run typecheck runs the complete Host lib phase before Client tsc, while pnpm run build continues through Client tsdown and the Web build. The API Remotes generated-contract build note records this ordering decision.
Static analysis and tests resolve workspace imports through the base paths map to src and must pass on a clean tree; gates that consume built lib/ output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public typecheck, lint, and doc-typecheck commands generate them first, while internal *:contracts-ready scripts assume that an invoking public command or scheduler gate already depends on the Typert contract-generation pass or the complete build. See the solution-root note for the two-aggregate setup, the ts-build-config note for tsc-first emit ownership, and the Typert Remote note for the gate-preparation contract.
Business services declare callable methods on the Host with @Remote or @RemoteScope; the Host build generates Host-for-Client types and runtime contributions, and the Client's api-remotes composition loads those contributions under ctx.remote and scoped agentCtx.remote namespaces. See API Gateway for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
If a relevant local check consumes built package output, build once first:
pnpm run build
pnpm run hygiene includes publint, which validates package entrypoints against the built lib/*.js files, and verify-node-next-types, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until pnpm run build runs; ordinary commits and pushes do not require that build unless their selected checks consume it.
Environment variables
The real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored .env at the repo root:
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_BASE_URL=https://... # optional
DEEPSEEK_BASE_URL is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when DEEPSEEK_API_KEY is not set.
Git integrations
The pairing merge driver derives a conflicted .i18n.yaml record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run pnpm run resolve-translation-pairing-conflicts, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the bilingual documentation contract for the exact files and states the driver accepts.
The installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run pnpm run resolve-translation-pairing-conflicts, or run git merge --abort. If pre-merge-commit rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run git commit, or abort. The automatic pairing merges Agent Note owns the exact index and MERGE_HEAD states.
lefthook is configured in lefthook.yml as a fast local checkpoint:
pre-commitverifies staged pairing records against the staged owner blobs, validates staged files with the project-free.oxlintrc.staged.jsonprofile and applies Oxlint fixes with one bounded retry, regeneratesTHIRD_PARTY_NOTICES.mdwhen a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.pre-merge-commitperforms the same index-backed pairing check before Git creates an automatic merge commit.pre-pushrunspnpm run typecheck, which completes the Host lib phase, including generated Typert contracts, before the Client TypeScript check.
The vendor manifest guard checks that changes under vendor/*/src are staged with the matching vendor/README.md manifest update. See vendor/README.md before editing vendored code.
Apart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the checks relevant to the changed behavior once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.
Contributors can opt into the comprehensive local gate set with pnpm run check:all. The command is independent of the Git hooks and is not an agent instruction.
CI gates
The keyless CI workflow groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs pnpm run test:e2e with its configured worker bound. See scripts/run-gates.ts and the workflow files for the current gate and job inventory.
Daily commands
The root contributor instructions summarize common commands, while package.json and scripts/run-gates.ts own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use pnpm run doc-sync; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require pnpm run build first.
Demos
Run the repository build separately before using these source-checkout demos:
pnpm run build
The one-shot Headless coding agent needs DEEPSEEK_API_KEY in the environment or repo-root .env:
pnpm dsh --profile headless "summarize this workspace"
The self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (web by default, or acp):
pnpm run demo:cordis
The ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs DEEPSEEK_API_KEY:
pnpm run demo:acp
TODO markers
Use one of three comment tags to flag known issues in the code, ordered by urgency:
FIXME— an issue that should block a new release. A release should not ship with an openFIXMEunless reviewers explicitly agree the change can be merged anyway.TODO— an issue that should be fixed soon, once we have the resources.XXX— an issue that we may fix someday; lowest priority, no commitment.
Pick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.
Documenting types verbatim (ts type-equiv)
The subsystems pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact type definition and source contract. To keep a paste from drifting when source changes, fence it as ```ts type-equiv (instead of ```ts) and register it in scripts/type-equiv.manifest.json with the source file and symbol it mirrors:
{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
pnpm run verify-type-equiv (part of doc-sync) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ```ts public-api and set "projection": "public-api"; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact type definition. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired .zh.md block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. doc-typecheck applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.