Cloud-DSH

Imported from YihengCai/Cloud-DSH (AGENTS.md). Install upstream with npx skills add YihengCai/Cloud-DSH. Copyright stays with the author.

AGENTS.md

DeepSeek Harness is a plugin harness on vendored Cordis: everything is a plugin. Follow package architecture, documentation rules, and cloud-runtime rules.

Personal learning fork scope

This fork is for local learning and portfolio demonstration. M0-M3 are delivered and no milestone is active. Hosted automation, publication, public deployment, tenancy, and Kubernetes are out of scope. Keep local checks that explain or verify the runtime.

There are no external consumers or compatibility releases. Change foundations directly and update every reference. Backends reject old formats. SQLite uses monotonic SCHEMA_VERSION; dsh-session keeps SESSION_FORMAT_VERSION at 0 without compatibility guarantees.

Repository layout

vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
  core/        product API spine: session, system-prompt, tools, agent, agent-loop
  api/         Remote BFF + Typert RPC gateway
  typert/      type graph generator, loader, and runtime registry
  llm/         LLM capability: Service Definition/Consumer + DeepSeek providers
  e2b/         E2B POC: sandbox + FS/subprocess adapters
  shell/        bash seam: definitions, local/pwsh providers, Consumers
  subprocess/  subprocess capability + local process-tree provider
  terminal/         persistent sessions
  fs/          filesystem capability + policy
  lsp/         language-server capability
  skill/       skill provider registry + local impl + catalog/loader tool
  web/         web capability: Service Definition + search/fetch providers + tool Consumer
  compaction/     compaction capability + basic provider
  context/     request-context plugins
  subagent/    subagent seam: definitions, providers, delegation Consumers
  bundle/      installable dsh --profile patch-layer bundles
  workflow/    workflow capability + worker-thread provider + tool Consumer
  action/      durable actions + PostgreSQL provider
  todo/        todo_write tool
  plan/        plan mode as logged state
  preset/      per-session agent composition from preset cordis.yml files
  guard/       loop-hygiene + tool-timeout plugins
  self-modification/  the agent inspects/mounts its own plugins
  hooks/       Claude Code/Codex hook bridges + wire-protocol library
  session/     durable session data: persistence, projection, titles, telemetry
  identity/    anonymous identity
  settings/    user-settings capability + file provider
  credentials/ credential/authorization capabilities + env/.env provider
  acp/         automation-only Agent Client Protocol server
  interaction/ approval/interaction capabilities, permission, commands, ask-user
  boot/        shared app-bin glue
  sdk/         JSON-RPC protocol, server, and TypeScript client
  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
  experimental/ private prototypes excluded from local pack/install checks
  support/     dev/test infrastructure
  util/        zero-dependency utilities
python/      Python SDK and bundled runtime (see python/README.md)
native/      @deepseek-ai/node-addon-landlock-run source of record (see native/README.md)
examples/    Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md)
.agents/     Agent workflows and Agent Notes (`notes/`)
docs/        architecture, generated catalogs, postmortems, cookbook (see docs/AGENTS.md)
scripts/     repo gates and generators
website/     VitePress projection of selected bilingual docs/ sources

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           # vitest unit tests
pnpm run test:coverage  # per-file 100% on packages/*/*/src
pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
pnpm run test:snapshot  # keyless ACP/headless replay vs expected outputs; 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        # knip + publint + workspace constraints + NodeNext consumer check
pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine)
pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
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:cordis    # the agent modifies its own runtime (needs key)
pnpm run demo:acp       # ACP automation server (needs DEEPSEEK_API_KEY)

Host sandbox failures

When required commands fail because the agent sandbox blocks credentials, network, IPC, file watching, or nested sandbox-exec, retry unchanged with the narrowest host escalation. Require sandbox evidence; never bypass genuine failures or the product sandbox under test.

Run relevant checks locally

Run the smallest local checks that cover the change and report only commands actually run.

• Match evidence to the surface: focused tests for behavior, snapshots for model or user output, doc-sync for docs, build/hygiene and built smokes for packaged paths, and real-API e2e for provider behavior.
• Never default to the full suite or repeat a passing check for a commit. Run the full local matrix only by explicit request or for an irreducibly repository-wide change.
• Use test:coverage when the change needs the repository's per-file coverage guarantee; ordinary test does not enforce it (why).

Secrets / .env

Real-API tests and 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. Real-API e2e self-skips without a key; testing.md owns key policy.

Conventions

• Explain before editing. Before making any change, tell the user the current state of the relevant code and why the change is needed.
• Every npm package is @deepseek-ai/dsh-<name>; vendored packages are rescoped (mapping) and private: true. @deepseek-ai/cordis is a peerDependency (+ dev) of every harness package.
• 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. Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct (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. A SessionEventMap member is required-on-read by default — builds that do not know its 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.
• 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. Each package uses one aggregate except api/remotes; repo-wide programs seed a face config, never the root solution (layout).
• An empty catch names what it swallows and why nothing else can reach it; keep the try to one statement.
• Do not comment on facts obvious from code.
• 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 change record.
• Non-trivial changes MUST include an Agent Note in the same change; only mechanical/local edits are exempt (scope). Archived notes are frozen: never edit or treat them as current authority (archive policy).
• Testing policy — docs/testing.md. Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same change; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
• A tool's UI render intent is part of its design, decided up front (generic/terminal/diff, locations); presentation methods are pure functions of args (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 change; pnpm run test covers neither (surfaces).
• Keep Git history reviewable. Automatically commit each small, coherent slice when relevant checks pass; include its tests and documentation, exclude unrelated or failing work, and never push without a request.
• 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

Root CLAUDE.md references AGENTS.md with @AGENTS.md; packages/CLAUDE.md and examples/CLAUDE.md symlink their local AGENTS.md. Edit the real instruction files. 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.