AGENTS.md

DeepSeek Harness is an all-plugin Cordis agent harness. Read docs/architecture.md before changing packages/; follow docs/AGENTS.md for documentation.

Pre-stable APIs and released Session data

Public APIs are pre-stable; update every consumer. Follow version/status and type acknowledgements. Adjacent migration may add a version-named successor but never move, overwrite, or delete committed generations; predecessors imply neither fallback nor downgrade support. SQLite uses monotonic SCHEMA_VERSION.

Acknowledge declared persistence-type changes.

Application launch. Only dsh profiles launch supported Node apps; package bins, demos, and public SDK argv escapes are forbidden (rule).

Repository layout

vendor/      Vendored Cordis (vendor/README.md)  
packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/  
  core/                 agent/session API  
  api/                  remote BFF  
  typert/               type graphs  
  llm/                  model providers  
  shell/                command execution  
  subprocess/           child-process management  
  ssh/                  SSH execution providers  
  terminal/             persistent terminals  
  ptc-runtime/          PTC execution  
  sandbox/              process confinement  
  deliverables/         turn deliverables  
  fs/                   filesystem access  
  lsp/                  language servers  
  skill/                skill loading  
  web/                  search/fetch tools  
  computer-use/         computer interaction  
  browser-use/          browser interaction  
  compaction/           context compaction  
  context/              request context  
  subagent/             delegated agents  
  jobs/                 background jobs  
  bundle/               profile bundles  
  workflow/             workflow execution  
  webhook/              webhook ingress  
  todo/                 todo_write tool  
  plan/                 logged planning  
  goal/                 session goals  
  schedule/             scheduled follow-ups  
  preset/               agent composition  
  guard/                loop/tool guards  
  extensions/           runtime self-modification  
  hooks/                Claude Code/Codex bridges  
  session/              durable sessions  
  session-query/        browsing/search/export  
  attachment/           binary attachments  
  spill/                output spill  
  storage/              non-session storage  
  workspace/            workspace entities  
  feedback/             human feedback  
  identity/             anonymous identity  
  settings/             user settings  
  credentials/          credentials/authorization  
  acp/                  automation-only ACP  
  interaction/          human interaction  
  boot/                 application boot  
  sdk/                  JSON-RPC SDK  
  host/                 GUI host  
  client/               GUI client  
  mcp/                  external tools  
  experimental/         pre-stable prototypes; public by default with explicit private exceptions  
  test-support/         test infrastructure  
  runtime-diagnostics/  runtime invariants  
  util/                 zero-dependency utilities  
python/      Python SDK/runtime (python/README.md)  
native/      @deepseek-ai/node-addon-system source (native/README.md)  
benchmarks/  performance gates  
.agents/     Agent workflows/notes  
docs/        Documentation (docs/AGENTS.md)  
scripts/     gates and generators  
website/     VitePress documentation projection  

Package groups: packages/README.md.

Commands

pnpm install            # pnpm workspaces, node ^22.19 || >=24  
pnpm run clean           # remove build outputs and safe residue from deleted packages  
pnpm run test           # unit tests  
pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src  
pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY  
pnpm run test:expected  # owner-local process expectations  
pnpm run test:snapshot  # keyless recorded-session replay through shipped profiles; filter: -t <name>  
pnpm run test:snapshot:record  # re-record expected outputs (needs key)  
pnpm run typecheck  
pnpm run lint  
pnpm run duplication    # cross-file TypeScript clone detection  
pnpm run build          # tsc emits lib/types, tsdown bundles runtime  
pnpm run hygiene        # publint + workspace/package/dependency checks + NodeNext consumer check  
pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal  
pnpm run doc-sync       # documentation gates (scripts/run-gates.ts)  
pnpm run test:docs      # quick documentation checks (no build; doc-quick aggregate)  
pnpm run website:build  # VitePress build (doubles as dead-link check)  
pnpm dsh --profile headless "task"  # run one task from source (needs DEEPSEEK_API_KEY)  
pnpm run demo:ptc -- "task"  # headless PTC mode run (needs key)  
pnpm run dev:web | dev:desktop  # build, then launch; Web also rebuilds client bundles on edits. start:web | start:desktop skip the build  
make web|dev-web|desktop|dev-desktop|build  # the same commands; ARGS='--no-open' forwards options  

Host sandbox failures

If a required gh, pnpm, build, test, or generator command fails because the sandbox blocks credentials, network, IPC, watching, or nested sandbox-exec, retry unchanged with the narrowest host escalation. Require sandbox evidence; never bypass test failures or the product sandbox.

Run relevant checks locally

Before pushing, follow dsh-pre-push-checks; report only commands run. After gh stack sync, validate immediately; do not merge before checks pass.

• Match evidence to the surface: focused behavior tests, model/user-output snapshots, doc-sync for docs, built smokes for published paths, and real-API e2e for providers.
• Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
• test:coverage, not test, is the CI coverage gate (why).
• Web browser automation and GIF recording: launch with pnpm dsh web --patch apps/web/tests/pin-browse-picker.overlay.yml to use the in-page directory picker; omit this override only when testing native picker behavior explicitly.

Secrets / .env

Windows packaging/signing: required reading.

Real-API tests/demos read DEEPSEEK_API_KEY, optional DEEPSEEK_BASE_URL, and root .env. cordis.yml allows !!js (never !js) under plugin config and entry disabled; other metadata stays literal, so conditional composition also uses overlays (primer). Never commit credentials. CI e2e skips without a key; testing.md owns key policy.

Conventions

• Packages use @deepseek-ai/dsh-<name>; vendor is rescoped and private: true. Harness packages declare @deepseek-ai/cordis in peerDependencies/devDependencies. Workspace dependency sections use DSH workspace:*, vendor/native workspace:~ (rules).
• ESM everywhere ("type": "module"). Use package names across packages and .ts in local relative imports. Config subprocesses run built lib/ under plain Node; source regressions use their declared launcher (testing policy). The dsh CLI source launch runs through tsx's ESM-only hook (node --import tsx/esm); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range (source-launch contract). Raw/Web cordis.yml bare plugins must appear in their resolver manifest's dependencies; verify-cordis-config enforces it.
• Registrations are effects: every contribution goes through ctx.effect() / ctx.on(); a registry's register() returns the disposer.
• Runtime invariants assert owned relationships. Publish ./invariant only when independent observations can diverge. Otherwise omit its source and wiring and record why in its README; empty installers and checks of service presence, plugin metadata, effects, or fixed examples are invalid (package invariant rules).
• Typed events use declaration merging and merge-extensible maps. Event JSDoc needs @mode and payload @param; scoped keys absent from payloads need @dshScopeScan unsupported. Public service methods document parameters and non-void returns. SessionEventMap members are required-on-read by default — builds that do not know a type refuse the log unless the event carries the envelope's ignorable: true; only structural format changes bump SESSION_FORMAT_VERSION (mechanism).
• Switch on discriminant tags. Closed unions end in assertNever; merge-extensible unions fall through a documented default.
• Waterfall listeners MUST call next() to delegate; returning without it short-circuits the chain (semantics).
• Model-visible ⟺ logged: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
• Plugins, not loop changes: new behavior goes on documented extension points; changing agent-loop requires updating docs/architecture.md.
• A capability seam comprises Service Definition / Service Provider / Consumer roles. It is complete, never one role; split only when roles evolve independently (glossary).
• Prefer maintained dependencies over hand-rolling when they genuinely delete owned code and tests (policy).
• Explicit > implicit at package boundaries: defaulting is an explicit resolve(request): Spec step in the owning implementation, never a hidden ?? default inside run() (the dsh-shell request/spec split is the template).
• No hardcoded tunables in plugins: deployment-varying choices are validated Config fields changeable from cordis.yml; a DEFAULT_* constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed.
• Misconfiguration fails loud at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
• Opaque cross-boundary ids are branded (Branded<B> from dsh-brand), never bare string.
• Trust TypeScript at typed same-process boundaries. Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
• No new assertions to unknown (as unknown or <unknown>). Preserve or reduce the exact legacy baseline; use typed values or validation for replacements (rule).
• Source plane vs artifact plane, never mixed. Static gates and tests resolve workspace imports through tsconfig paths to src and pass on a clean tree; gates consuming built lib/ declare that dependency (layout).
• Keep compiler faces explicit. A package with both Host and Client programs exposes face-specific leaf configs and a solution-only root; repo-wide programs seed a face config, never the root solution (layout).
• An empty catch names the error and why; keep its try to one statement.
• Keep comments local. Do not restate code, expand unrelated comments, or explain distant behavior without local need (rationale).
• Ban prove + nance (rule).
• Prefer symmetry for parallel values; unexplained asymmetry usually signals a missed extraction.
• Tests describe behavior, not correctness. Change obsolete behavior with its tests; explain why in the PR.
• Create Agent Notes only for durable decision rationale; mechanical/local edits are exempt, including local UI changes (scope). Archived notes are frozen: never edit or treat them as current authority (archive policy).
• Client UI copy is locale-owned. Route product text through typed dictionaries and t or localized primitive props; verify-client-ui-i18n rejects hardcoded copy (decision).
• Testing policy — docs/testing.md. Every non-trivial model- or product-user-visible change updates a keyless recorded-session snapshot; snapshot ownership reserves the top-level tree for session-driven cases and keeps other expected output owner-local. Fixtures replay on macOS/Linux; fix fixtures, not normalizers.
• Design each tool's UI presentation up front. Host presenters stay pure; Web cards derive from raw events and persisted result metadata (cookbook).
• Plan unit, e2e, and snapshot coverage for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
• Both SDKs project the loop. Agent-loop, session-lifecycle, and SessionEventMap changes update the TypeScript and Python SDK expected outputs in the same PR; pnpm run test covers neither (surfaces).
• Choose PR history deliberately. Split independent changes and fix the introducing PR before propagation. Standalone/stack branches may merge-forward or rebase. Rewrites use --force-with-lease, abort on remote movement, never raw --force; preserve an in-progress merge-forward checkpoint before taking a newer base (rationale).
• Labels: one PR kind/*, all material area/*, and native Issue Type (taxonomy).
• TODO markers: FIXME/TODO/XXX by urgency (semantics).
• Files end with exactly one trailing newline; git diff --cached --check (pre-commit) gates it.

Defensive patterns

Read docs/defensive-patterns.md before lifecycle, concurrency, subprocess, or teardown work.

Type safety and documentation

Everything compiles under strict: true with noImplicitAny; every remaining any explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include @param/@returns, as enforced by verify-export-jsdoc. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class.

Comments and docs state complete contracts and context, not reasoning transcripts. Use direct, concrete terms. Do not use metaphors. Before writing contract, boundary, or shape, ask whether a more exact term names the subject: write response fields, JSON validation, or ESM exports instead of response shape, validation boundary, or module shape. Keep contract for preconditions, postconditions, invariants, compatibility promises, and other obligations that callers, callees, implementers, providers, producers, or consumers rely on. Keep a literal process, wire, security, transaction, or lifecycle boundary. Do not narrate control flow or tests, preserve review history, or restate code. Keep behavior, failure, timing, ownership, and safe-use facts; link the rationale. Use dsh-prose-standard for decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case. Use narrow, justified exceptions instead of disabling a rule globally.

Docs accompany every code change: update affected README and JSDoc contracts together. Routine bilingual work follows docs/AGENTS.md; only explicit user invocation may run dsh-translate-docs. Current-state prose, one physical line per paragraph, one home per fact, and word budgets live there.

Editing these instructions

CLAUDE.md symlinks AGENTS.md at root and packages/; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a verify-doc-budgets ceiling when the required content genuinely needs more space.

Vendoring policy

vendor/ packages are pinned source copies (manifest with upstream SHAs in vendor/README.md). Update via the sync procedure there; re-apply or retire the logged local modifications; rerun pnpm run test && pnpm run build.