Merge remote-tracking branch 'origin/master' into worktree-dynamic-workflows

Beyond the mechanical conflicts (provider capability lines vs master's new
inheritsParentContext field; generated catalogs regenerated rather than
hand-merged; knip/lockfile), three master-side reworks required semantic
adaptation of this branch:

- The persona rework removed AgentOptions.systemPrompt, which was the
  structured-output instruction's channel. The instruction now rides the
  SAME final-request enforcement listener that injects the schema'd tool:
  appended per request to final.system (per-request wire state, not agent
  prompt state). Tests assert the wire request (adapter.requests) instead
  of child.options; the bare-direct-dispatch test pins the no-system arm.
- Tool guidance moved out of deployment prompts into per-tool prompt
  sections; the examples' workflow paragraph became a tool:<toolName>
  section contributed by dsh-tool-workflow (explicit-ask-only policy),
  and both example personas resolve to master's minimal identity+behavior
  form. tool-workflow gains inject: systemPrompt (+ peer dep, tsconfig
  ref); the export-shape guard updated.
- The uniform-RFC-format gate: the dynamic-workflows RFC restructured to
  the implemented/ skeleton (bare Status line; Proposal -> Decision;
  What-was-rejected -> Alternatives considered; new Consequences), and
  the overall-run-timeout deferral is now recorded in the RFC's Deferred
  list. The doc-graphs atlas classification gains the workflows seam
  (workflow-vm implementation, tool-workflow consumer).

Master's harness-identity section made "empty assembled prompt" states
unreachable through the loop, so the instruction-append is a plain
undefined-ternary and the structured tests assert append-not-replace.
All snapshot goldens (including workflow-run) replay unchanged. Full
local CI-equivalent gate sequence green on the merged tree.

examples/acp-agent/README.md

@@ -1,6 +1,6 @@
 # acp-agent example
 
-The DeepSeek Harness agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio — drive it from Zed or any other ACP client.
+The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio — drive it from Zed or any other ACP client.
 
 ```sh
 pnpm run demo:acp          # needs DEEPSEEK_API_KEY (repo-root .env or env)

examples/acp-agent/composition.md

@@ -0,0 +1,73 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# ACP Agent App Composition
+
+The ACP demo exposes the same agent spine over JSON-RPC stdio, with no stdout logger and no pre-created agent; clients create sessions through the ACP bridge.
+
+```mermaid
+flowchart LR
+  cfg["examples/acp-agent<br/>cordis.yml"]
+  plugin_acp_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_acp_llm_deepseek
+  plugin_acp_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_acp_bash
+  plugin_acp_acp_agent["acp-agent<br/>@deepseek-ai/dsh-acp-agent"]
+  cfg --> plugin_acp_acp_agent
+  plugin_acp_acp_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_acp_acp_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_acp_acp_agent --> frontdoor_acp["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_acp_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
+  cfg --> plugin_acp_subagent
+  plugin_acp_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
+  cfg --> plugin_acp_subagent_spawn
+  plugin_acp_subagent_fork["subagent-fork<br/>@deepseek-ai/dsh-subagent-fork"]
+  cfg --> plugin_acp_subagent_fork
+  plugin_acp_tool_subagent["tool-subagent<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_acp_tool_subagent
+  plugin_acp_tool_subagent_fork["tool-subagent-fork<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_acp_tool_subagent_fork
+  plugin_acp_workflow_vm["workflow-vm<br/>@deepseek-ai/dsh-workflow-vm"]
+  cfg --> plugin_acp_workflow_vm
+  plugin_acp_tool_workflow["tool-workflow<br/>@deepseek-ai/dsh-tool-workflow"]
+  cfg --> plugin_acp_tool_workflow
+  plugin_acp_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
+  cfg --> plugin_acp_tool_todo
+  plugin_acp_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
+  cfg --> plugin_acp_fs_local
+  plugin_acp_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
+  cfg --> plugin_acp_fs_policy
+  plugin_acp_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
+  cfg --> plugin_acp_tool_fs
+  plugin_acp_hooks_claude["hooks-claude<br/>@deepseek-ai/dsh-hooks-claude"]
+  cfg --> plugin_acp_hooks_claude
+  plugin_acp_hooks_codex["hooks-codex<br/>@deepseek-ai/dsh-hooks-codex"]
+  cfg --> plugin_acp_hooks_codex
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `bash` | `@deepseek-ai/dsh-bash-local` |
+| `acp-agent` | `@deepseek-ai/dsh-acp-agent` |
+| `subagent` | `@deepseek-ai/dsh-subagent` |
+| `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
+| `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
+| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
+| `workflow-vm` | `@deepseek-ai/dsh-workflow-vm` |
+| `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` |
+| `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `fs-local` | `@deepseek-ai/dsh-fs-local` |
+| `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
+| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+| `hooks-claude` | `@deepseek-ai/dsh-hooks-claude` |
+| `hooks-codex` | `@deepseek-ai/dsh-hooks-codex` |
+
+Source config: [`examples/acp-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.

examples/acp-agent/cordis.yml

@@ -23,9 +23,8 @@
       - deepseek-v4-flash
       - deepseek-v4-pro
 
-# Local bash executor for agent-core's tool-bash schema.
-# FIXME(config-comments): keep this executor note from implying bash is the
-# whole tool set; filesystem, subagent, and todo_write are loaded below.
+# Local bash executor for agent-core's tool-bash schema (one of several tool
+# stacks in this tree: filesystem, subagent, and todo_write load below).
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
@@ -39,34 +38,17 @@
   config:
     model: deepseek-v4-flash
     persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
-    systemPrompt: |
-      You are a coding assistant driven over the Agent Client Protocol.
+    # The persona: identity + behavior only, nothing about transports or
+    # tooling — tool guidance lives with each tool plugin (descriptions +
+    # prompt sections). {{model}} and {{cwd}} are prompt variables the agent
+    # loop resolves per session (every ACP session carries the client's cwd,
+    # so the persona can state the workspace).
+    persona: |
+      You are a coding assistant powered by the {{model}} model. Your working
+      directory is {{cwd}}.
 
-      Your tools are read/write/edit for file operations, bash (plus
-      bash_output/bash_kill for background tasks), and subagent. Use read to
-      inspect UTF-8 text files, write to create or replace files, and edit for
-      targeted literal replacements. Use bash for shell commands, tests,
-      searches, and operations that are not ordinary file reads or edits. Each
-      bash call runs in a fresh shell — pass workdir instead of cd. Check the
-      [exit code: N] marker; verify your work. Keep answers brief and factual.
-
-      Use the subagent tool to delegate a focused, self-contained subtask to
-      a fresh child agent (it works in its own context and returns only its
-      final result) — give it a complete, standalone instruction. Use
-      subagent_fork instead when the subtask needs THIS conversation's
-      context: the child inherits the log so far.
-
-      Use the workflow tool ONLY when the user explicitly asks for a
-      workflow or for large multi-agent orchestration: you write a
-      JavaScript script (its description documents the exact format) that
-      fans work out across many subagents with phases and structured
-      results. For one or two delegations, prefer plain subagent calls.
-
-      For multi-step work, use the todo_write tool to track a task list:
-      send the WHOLE list each call (it replaces the previous one), keep at
-      most one task in_progress (exactly one while work remains), and mark a
-      task completed as soon as it is done. Skip it for trivial single-step
-      tasks.
+      Verify your work by running the code or tests. Keep answers brief and
+      factual.
 
 # The subagent seam + both in-process backends + two model-facing tools, as leaf
 # entries after the app (which provides ctx.agents/ctx.tools). spawn (a fresh