# Native seams for a static fullstack-expert Cordis plugin

Scope: a **static** plugin/package mounted by a profile or agent preset (not a dynamic runtime plugin). The installed artifacts are `@deepseek-ai/*` version `0.1.0-rc.6` and Cordis `4.0.1`; package manifests point at the official repository and package directories. Local citations below are authoritative for the installed runtime; GitHub links identify the corresponding upstream source.

## 1. Package shape and build/export conventions

- First-party packages are ESM packages with `type: "module"`, `main: "lib/index.js"`, and declarations in `lib/types/index.d.ts`. Public exports use conditional `types`/`default` targets; source is commonly exposed only as `./src/*` plus `./package.json`. Example: `@deepseek-ai/dsh-agent/package.json:13-30`; instructions package: `@deepseek-ai/dsh-agent-instructions/package.json:13-32`.
- Upstream package authoring rules are in `/tmp/deepseek-harness-official` at commit `47f943859bef60e4160492346772ded9b24f765a`, especially `packages/AGENTS.md:5-6,20-25`: service packages export a default service class, while function plugins export named `name`/`inject`/`Config`/`apply` (no default export); source/build wiring follows `src` → `lib/types` with tsconfig, workspace references, and aggregate requirements.
- The canonical bundle package adds a patch export and bundle manifest: `@deepseek-ai/dsh-base/package.json:13-39` exports `.`/`./invariant`/`./cordis.patch.yml`/`./src/*`/`./package.json`, publishes built `lib/*`, declarations, and the patch, and declares `dsh.bundle.patch: "./cordis.patch.yml"`. Ordinary tool packages are narrower: `@deepseek-ai/dsh-tool-bash/package.json:13-32` exports built root/invariant/source glob/package JSON.
- Published `files` lists built JS and declaration outputs, not the whole source tree (`dsh-agent/package.json:32-36`). Ordinary core packages may omit `scripts`; client/API packages commonly expose `bundle: tsdown` and `watch: tsdown --watch` (for example `@deepseek-ai/dsh-client-ui-sidebar/package.json:67-76` and `@deepseek-ai/dsh-api-gateway/package.json:71-74`). Do not assume every package has a `build` script; the launcher only states that production requires built artifacts and repository-root `pnpm run build` (`dsh/README.md:45-47`).
- A static plugin should ship its built `lib` artifacts and declarations and expose only deliberate public subpaths. The agent loop is intentionally stricter: its README says the root exports only the plugin/service/config contract and exposes no `./src/*` escape hatch (`@deepseek-ai/dsh-agent-loop/README.md:54-56`). Some packages additionally expose typed faces such as `./types` (agent/tools manifests) or `./presentation`; client-capable packages export `./client` and declare `dsh.client` metadata (`dsh-client-ui-sidebar/package.json:16-41`).
- Cordis composition rows name the package root and configuration; a package root exports the Cordis plugin contract (`name`, optional `inject`, `Config`, `apply`) rather than model-specific internals. This is explicit for filesystem and bash tools: `@deepseek-ai/dsh-tool-fs/README.md:60-62`, `@deepseek-ai/dsh-tool-bash/README.md:7-11`.
- Production uses built package/frontend artifacts; the launcher README requires `pnpm run build`, while `pnpm dsh ...` is the source-execution path (`@deepseek-ai/dsh/README.md:45-47`).

## 2. Agent prompt sections and scoped composition

- `SystemPrompt` (`ctx.systemPrompt`) is the native seam: register `PromptSection { name, order, text, complete? }` with `ctx.systemPrompt.section(...)`; register dynamic context, variables, and tool-schema providers through the corresponding methods. Registrations are scope-layered and disposed with the calling fiber (`@deepseek-ai/dsh-system-prompt/README.md:16-25`, `31-45`).
- Sections concatenate by ascending order; `-100` is harness identity, `0` deployment persona, and tool guidance normally occupies `100–199` (`dsh-system-prompt/README.md:33-36`). A fullstack persona should normally be an ordinary ordered section, not a `complete` section, because one effective complete section suppresses the rest and multiple complete sections reject assembly (`dsh-system-prompt/README.md:20,25,29`).
- Agent-local behavior belongs in `agent.ctx`: registrations shadow global sections/tools/variables and are unwound with that agent (`@deepseek-ai/dsh-agent/README.md:15,99-111`). For a static preset plugin, register against the preset standing scope; for per-agent specialization, use the agent setup context.
- `system-prompt/assemble` is the authoritative cooperative waterfall. A listener may replace the assembly, but must preserve active Code Mode/structured-output protocol (`dsh-system-prompt/README.md:27-29`). A fullstack plugin should prefer additive sections and avoid replacing the entire assembly.
- Concrete registrations: `dsh-tool-fs/lib/index.js:323-333` adds `tool:read` at order 100 before registering `read`; `dsh-tool-bash/lib/index.js:254-259` adds `tool:bash` at order 105 before registering `bash`. The app boot helper offers another global example: `addHarnessSourceSection` registers `harness:source` (`dsh-app-boot/README.md:23-24`). Agent-context integration can instead inject sourced user messages at `agent/pre-step` (`packages/context/agent-instructions/src/index.ts:322-347` in the official checkout).

## 3. Skills provider and runtime registration

- `@deepseek-ai/dsh-skill` owns `ctx.skills`. The official registry contract is `/tmp/deepseek-harness-official/packages/skill/skill/README.md:5-24,42-64`: external sources register synchronously through `ctx.skills.registerProvider(create)` with `{ signal, invalidate }`, provider names are unique within the calling scope layer, and consumers use `snapshot`, `list`, and `get`; `ctx.skills.register(runtimeSkill)` is the embedded-skill path and `skills/change` is the invalidation event. The installed rc.6 README describes the same API (`dsh-skill/README.md:5-19,48-56`).
- Embedded/static skills use `ctx.skills.register(skill)`, which supplies runtime provider/invocation defaults and returns a Cordis disposer. Runtime registrations are first-wins within their layer; project providers can override runtime skills by rank (`dsh-skill/README.md:58-64`).
- The registry does **not** register the model-facing `skill` tool or prompt catalog; `@deepseek-ai/dsh-tool-skill` is the consumer that does that (`dsh-skill/README.md:62-68`). Thus a fullstack plugin that publishes skills should depend on the registry, while tool exposure remains a separate composition row.
- The shipped filesystem provider discovers `<name>/SKILL.md` bundles or flat `<name>.md`, with kebab-case names and frontmatter fields such as `name`, `description`, `whenToUse`, and invocation flags (official `/tmp/deepseek-harness-official/packages/skill/skill-filesystem/README.md:5-11,29-51`; installed `dsh-skill-filesystem/README.md:41,55`). Its concrete provider requires `inject: ['skills']`, supports configured roots/watchers, and registers the provider in installed `lib/index.js:664-699` (export at `:880`); the standard preset mounts it with `tool-skill` (`@deepseek-ai/dsh/config/agent-presets/standard/agent.cordis.yml:76-87`).
- The model-facing loader remains separate: `dsh-tool-skill/lib/index.js:116-145` registers the `skill` tool and its catalog behavior, while its `agent/pre-step` listener is in the following implementation region. A provider alone does not expose a model tool.

## 4. Tool registration and model exposure

- `ToolRuntime` is `ctx.tools`. Register a trusted definition with `ctx.tools.register(...)`; definitions require a canonical output declaration and are disposed with the fiber. Agent-context registration is agent-local and shadows same-named global tools (`@deepseek-ai/dsh-tools/README.md:18-27`).
- Tool schemas enter prompt assembly automatically through ToolRuntime's SystemPrompt integration (`dsh-tools/README.md:29-31`). Tool guidance is separate: register a section explicitly, as `dsh-tool-bash` does with `tool:bash` order 105 (`dsh-tool-bash/README.md:9-11`).
- The execution seam is ordered: `tools/pre-execute` allow/deny/ask, monotonic `ctx.tools.guard`, `tools/execute` around-dispatch, `tools/post-execute`, definition `finalizeContent`, then observe-only `tools/result` (`dsh-tools/README.md:1-5,37-60`). Use these for policy/telemetry rather than wrapping the loop.
- A static plugin should use `defineTool` where practical for typed parameter/output schemas (`dsh-tools/README.md:63-97`). Tool bodies receive `exec.signal`; cancellation is cooperative and tool side effects are not rolled back (`dsh-tools/README.md:33-35,116-125`).

## 5. Agent and session events

- `@deepseek-ai/dsh-agent` owns the live `agent/*` coordination vocabulary, independent of the concrete loop. `ctx.agents` provides registry access, initiator propagation, and agent-scoped contexts (`dsh-agent/README.md:9-15,26-45`). Exact event signatures/payloads belong to generated official subsystem docs, not README paraphrases: use `/tmp/deepseek-harness-official/docs/subsystems/core.md#cordis-surface` for agent/tool/core contracts and `/tmp/deepseek-harness-official/docs/subsystems/session.md#cordis-surface` plus `persistence-catalog.md` for session payloads.
- Lifecycle notifications: `agent/created` runs after setup and registry publication; `agent/session-start` is the first supported non-vetoing startup injection point; `agent/disposed` means the exact agent left the registry (`dsh-agent/README.md:47-53`). Other useful hooks include `agent/pre-step`, `agent/request-error`, `agent/turn-stopping`, and inbox inserted/claimed/discarded notifications (`dsh-agent/README.md:53-61`).
- Turn/step boundaries and token chunks are **durable session events**, not mirrored agent notifications. `@deepseek-ai/dsh-session` owns the append-only `Session`, `ctx.sessions`, and `session/event`/`session/flush` durability seams (`dsh-session/README.md:5-17,31-43`). Persistence plugins subscribe to `session/event`, flush on `session/flush`, and mirror session lifecycle if needed (`dsh-session/README.md:89-93`).
- Plugins adding durable facts should declaration-merge `SessionEventMap`, append through `Session`, and await `ctx.sessions.flush(session)` when durability is required (`dsh-session/README.md:69-73`). Do not use live agent events as a substitute for reconstructable session facts.
- The concrete loop (`dsh-agent-loop`) is intentionally not the extension seam: new behavior belongs in plugins and event listeners; the loop injects `agents`, `sessions`, `llm`, `tools`, and `systemPrompt` (`dsh-agent-loop/README.md:5-15,28-34,74-83`).

## 6. Filesystem, shell, and services

- Filesystem capability is `ctx.fs` (`@deepseek-ai/dsh-fs`): resolve targets, canonical process paths/file URLs, containment, metadata, text/stream reads, bounded bytes, directory listing, atomic writes, and literal atomic edits. The provider contract is separate from policy and model-facing tools (`dsh-fs/README.md:5-16,18-37,43-47`).
- `@deepseek-ai/dsh-tool-fs` owns model-facing `read`, `read_image`, `write`, and `edit`; it calls `ctx.fs` directly and uses `fs/write-intent`, `fs/edit-intent`, and `fs/observed` events for policy (`dsh-tool-fs/README.md:1-17,43-58`). A fullstack plugin needing repository inspection should consume `ctx.fs`, not native `fs` globals. The installed implementation is a concrete reference: `dsh-tool-fs/lib/index.js:1182-1186` injects `tools`, `fs`, and `systemPrompt`, registers tools at `:333`, `:604`, `:749`, and `:952`, and conditionally injects `attachments` at `:1210-1212`; the installed rc.6 source does not include `fsObservationPolicy` in this inject list, so service keys must be checked against the installed version rather than copied from another revision.
- Process execution is `ctx.subprocess` (`@deepseek-ai/dsh-subprocess`): executable resolution, explicit-argv managed spawn, terminal spawn, bounded stdio, tree termination, scrubbed environment, and disposal cleanup (`dsh-subprocess/README.md:5-18`). Commands are not shell-interpreted unless the caller explicitly invokes `bash -c` (`dsh-subprocess/README.md:9-12`).
- Shell capability is `ctx.shell`; `@deepseek-ai/dsh-shell` defines the abstract executor (`run`, `start`, incremental output, `sandboxMode`, disposal) in `README.md:5-30`, while `@deepseek-ai/dsh-bash-local` implements it over `ctx.subprocess` (`dsh-bash-local/README.md:5-7`). **Installed rc.6 naming:** `dsh-tool-bash/lib/index.js:110-116` injects `['tools', 'shell', 'systemPrompt', 'shellEnv']`; do not normalize these to `bash`/`bashEnv` from a different revision. `dsh-tool-bash/lib/index.js:254-259` registers `tool:bash` (order 105) and the `bash` tool. For a plugin's trusted host work, inject/use the service seam; do not call undeclared globals.
- Hard dependencies should be declared with `inject`; optional services should be read with `ctx.get(...)` and handled when absent. This is also why filesystem tools keep policy optional and why tool-bash stays pending until its required services exist (`dsh-tool-bash/README.md:5-9`; `dsh-tool-fs/README.md:14-17`).

## 7. Static fullstack-expert preset shape

- The shipped standard preset is the closest reference composition: `@deepseek-ai/dsh/config/agent-presets/standard/agent.cordis.yml:20-33` owns persona, `:76-87` mounts skills/tool-skill, `:100-124` mounts plan-mode guidance, and later rows provide the model-facing tool set. A fullstack-expert preset should copy this composition into the user-owned preset root and change the persona/rows there, rather than edit the shipped install.
- The preset runtime is a standing mount, not a per-session duplicate: the agent view resolves `agent → preset → global`, and `mount()` belongs in factory `setup`; child agents use `composeFrom` so they inherit the parent's exact generation (`@deepseek-ai/dsh-agent-presets/README.md:5-8,29-51`). Package names resolve from the host composition while relative paths resolve from the preset directory (`:63-69`).
- Keep host-plane registries and capabilities (agents, sessions, filesystem/policy, shell/environment, model route) in the base/web host composition. A preset-owned service must be under a `cordis:group` with `isolate`; otherwise it publishes root/process-global and can collide across presets (`dsh-agent-presets/README.md:115-125`).

## 8. Profile bundles and `cordis.patch.yml`

- A profile is `$DSH_HOME/profiles/<name>` with `package.json` (dependencies plus `dsh.profile.bundles`) and a user `cordis.patch.yml`. Composition order is: bundle patches in manifest order, profile patch, home-level patch, then CLI overlays (`@deepseek-ai/dsh/README.md:30-41`). The official loader seam is `/tmp/deepseek-harness-official/packages/boot/app-boot/README.md:16-23,30-32,36-45`: `loadOptionalPatches`, `composeEntries`, bundle declaration/resolution, the ordered bundle list, later profile/home overlays, live `watchUserPatches`, and module-resolution rules.
- The shipped bundle package manifest is the exact shape: `@deepseek-ai/dsh-base/package.json:13-39` includes `dsh.bundle.patch: "./cordis.patch.yml"`. Bundle-only metadata is distinct from ordinary static plugins: only bundle packages need to export `./cordis.patch.yml` and declare `dsh.bundle.patch`; an ordinary plugin row can be inserted by an existing profile/bundle patch without carrying a patch file.
- A bundle package declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves listed bundles from the installation first, then profile `node_modules`, and `composeEntries` uses the same Include patch algorithm as boot (`@deepseek-ai/dsh-app-boot/README.md:36-38`).
- `cordis.patch.yml` is a top-level YAML array of Include patch options. The shipped headless/web patches show the concrete row grammar and flags (`@deepseek-ai/dsh-headless/cordis.patch.yml:7-35`; `@deepseek-ai/dsh-web-app/cordis.patch.yml:1-13,16-45,47-59,102-143`): `insert` rows carry `id`/`name`/`config`, rows may be `disabled`, and `!!js` expressions can derive values after services exist. An id-targeted patch replaces the matched row's **whole config** (restate fields you retain), rather than deep-merging. Empty/comments-only is invalid; `[]` disables a layer (`dsh-app-boot/README.md:16-19,43-45,60`).
- `watchUserPatches` keeps profile/home patches live and recomposes transactionally; a failed parse/read/candidate leaves the last good tree running and emits `hmr/config-update-failed` (`dsh-app-boot/README.md:19,45`).
- The shipped base patch is the canonical composition example: `@deepseek-ai/dsh-base/cordis.patch.yml:1-13` inserts its rows over an empty root; native service/tool rows occupy the later ranges `:15-43`, `:163-248`, and `:281-425`. The web patch documents the agent-plane split and ownership (`@deepseek-ai/dsh-web-app/cordis.patch.yml:276-330,367-425`): host retains registries/persistence/sandbox/model route, while per-agent tool/prompt rows move into presets. Its early rows also define the browser roster seam: `dsh.client` entries are scanned into `window.__DSH_BOOT__` (`dsh-web-app/cordis.patch.yml:1-12,45-50`).
- A web/client-capable plugin is a separate seam from adding a host row: it needs a host root export plus a built `./client` export and `dsh.client` metadata; client packages commonly declare client dependencies and bundle/watch scripts (`dsh-client-ui-sidebar/package.json:16-41,67-76`; API gateway `dsh-api-gateway/package.json:16-45,71-74`).
- For a static fullstack-expert plugin, the native integration is therefore: publish a package with built exports; add a bundle patch row (or insert the row in a profile patch); compose the prompt/tool/skill registrations in that plugin; and ensure required provider rows (`dsh-fs`, shell/subprocess, skills, tools, agent/session services) are present in a lower bundle layer. Do not edit shipped preset installs; a copied user preset is a whole snapshot, while `cordis.patch.yml` is the intended overlay mechanism (`dsh-agent-presets/README.md:53-67,145-153`).

## Primary source index

- Installed package artifacts: `/home/wk/.npm/_npx/1e7f6d9597241db0/node_modules/@deepseek-ai/`.
- Upstream repository: [github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).
- Package source locations are declared in each manifest's `repository.directory`; for example [`core/agent`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/core/agent), [`core/system-prompt`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/core/system-prompt), [`core/tools`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/core/tools), [`context/skill`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/context/skill), and [`boot/app-boot`](https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/boot/app-boot).