Files
deepseek-harness/docs/event-producer-consumer.md
Turtle f290a8b851 refactor(cli)!: one shared base config with per-surface overlays
`dsh` shipped two config trees that were 43 rows the same: apps/cli/cordis.yml
composed web as 74 flat rows, while the TUI booted examples/tui-agent/cordis.yml
whose single `@deepseek-ai/dsh-tui-demo` row mounted twelve plugins behind a
twenty-key pass-through Config. Neither file was what its location claimed —
apps/cli hardcoded the "example" as the product default and the "demo" bundle
was the application — and every capability change had to be made twice.

- apps/cli/base.cordis.yml holds the 43 shared rows; tui.cordis.yml and
  web.cordis.yml are patch lists stating only what differs per surface
- overlays apply as SIBLING patch lists at one include level, because include
  patches never cross an include boundary. Precedence: base < surface <
  (--config | personal ~/.dsh/config.yaml) < launcher flag/profile patches
- `--config` now applies an overlay INSTEAD OF the personal one, so a demo or
  test tree never inherits the user's route; new `--config-replace` boots a file
  as the entire tree (the old `--config` behaviour). Both survive /resume
- vendor/include: index each `insert`ed row as it is added so a later patch can
  configure or disable it. Upstream built the id index once before the patch
  loop, leaving every surface-only row — the whole TUI front door — silently
  unpatchable from user config. Logged as local modification 8
- session identity moves to dsh-agent-loop's CONFIGURED_AGENT_IDENTITIES_KEY;
  dsh-tui's MAIN_SESSION_ID_KEY is deleted (only the bundle read it)
- delete examples/tui-agent, examples/cordis-agent, packages/examples/tui-demo;
  TUI tests → apps/cli/tests, cordis e2e → packages/cordis/tool-cordis/tests,
  examples/code-mode survives as an overlay leaf
- `dsh web` gains --config, threaded into AppCLIEntry as an extra overlay

Three latent defects surfaced and are fixed here: the TUI captured the optional
sessionQuery service once at construction and could permanently disable /resume
when it won the mount race; the session-store root silently reverted to a
project-local ./.sessions; --config-replace was dropped by the resume handoff.

Verified by booting each tree through the real Loader (TUI 55 entries, web 75,
zero unsettled) rather than reading YAML. All eight terminal snapshots replay
byte-identically; 14/14 PTY smoke, 112/112 snapshots, 25/25 doc-sync, hygiene
and lint clean.
2026-07-29 21:15:42 +08:00

17 KiB

Event Producer And Consumer Matrix

This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass ctx.emit, such as subagent lifecycle containment.

Event Mode Declared in Dispatchers Listeners
agent-loop/config-start-failed emit packages/core/agent-loop/src/index.ts:157 agent-loop (events.dispatch) tui
agent/cancel-requested emit packages/core/agent/src/types.ts:286 agent-loop (emitAgentEvent) goal-session
agent/created emit packages/core/agent/src/types.ts:218 agent (events.dispatch) goal-session, tui
agent/disposed emit packages/core/agent/src/types.ts:227 agent (events.dispatch) agent-loop, goal-session, tui
agent/error emit packages/core/agent/src/types.ts:400 agent-loop (emitAgentEvent) apiproxy, goal-session, session-telemetry, tui
agent/inbox/dequeue emit packages/core/agent/src/types.ts:259 agent-loop (emitAgentEvent) agent, apiproxy, tui
agent/inbox/discard emit packages/core/agent/src/types.ts:276 agent-loop (emitAgentEvent) agent, apiproxy, tui
agent/inbox/enqueue emit packages/core/agent/src/types.ts:247 agent-loop (emitAgentEvent) agent, apiproxy, goal-session
agent/prompt-submit waterfall packages/core/agent/src/types.ts:313 agent-loop (waterfall) goal-session, hooks-claude, hooks-codex, repeat-tool-guard, tui
agent/request waterfall packages/core/agent/src/types.ts:339 agent-loop (waterfall) agent
agent/request-error waterfall packages/core/agent/src/types.ts:358 agent-loop (waterfall) compact-basic, llm-retry
agent/session-start emit packages/core/agent/src/types.ts:299 agent-loop (emitAgentEvent) goal, goal-session, hooks-claude, hooks-codex, workspace-context
agent/settled emit packages/core/agent/src/types.ts:387 agent-loop (emitAgentEvent) compact-basic
agent/status emit packages/core/agent/src/types.ts:236 agent-loop (emitAgentEvent) agent, apiproxy, goal-session, tui
agent/step serial packages/core/agent/src/types.ts:326 agent-loop (serial) compact-basic, plan-mode, session-checkpoint-policy, time-context, tool-skill, user-approval, workspace-context
agent/turn-stopping serial packages/core/agent/src/types.ts:373 agent-loop (serial) hooks-claude, hooks-codex
approval/request waterfall packages/ui/user-approval/src/index.ts:30 user-approval (waterfall) acp, apiproxy
commands/change emit packages/ui/commands/src/index.ts:154 commands (events.dispatch) apiproxy, tui
domain/changed emit packages/storage/storage-domain/src/events.ts:46 storage-domain (emit) apiproxy, storage-domain, workspace
fs/edit-intent waterfall packages/fs/fs/src/index.ts:62 tool-fs (waterfall) fs-policy
fs/observed emit packages/fs/fs/src/index.ts:71 tool-fs (emit) fs-policy
fs/write-intent waterfall packages/fs/fs/src/index.ts:54 tool-fs (waterfall) fs-policy
goal/changed emit packages/goal/goal/src/domain.ts:135 goal (emit) goal-session
llm/stream waterfall packages/llm/llm/src/index.ts:58 llm (waterfall) agent-loop, llm, llm-replay, session-checkpoint-policy, session-title
session/created emit packages/core/session/src/index.ts:71 session (events.dispatch) apiproxy, compact, goal, hook-protocol, jsonrpc, llm-retry, plan-mode, session, session-persistence, session-telemetry, tools, user-approval
session/disposed emit packages/core/session/src/index.ts:81 session (events.dispatch) agent-loop, apiproxy, session-persistence, session-projection-cache, session-telemetry, session-title
session/event emit packages/core/session/src/index.ts:93 session (events.dispatch) acp, apiproxy, cli-demo, compact, compact-basic, goal, goal-session, hook-protocol, jsonrpc, session, session-persistence, session-projection, session-projection-cache, session-telemetry, session-title, token-meter, tools, tui, user-approval, workspace-context
session/flush parallel packages/core/session/src/index.ts:103 session (events.dispatch) session-persistence, session-telemetry
slash/input-begin-command bail packages/client/ui-slash/src/types.ts:230 - ui-conversation
slash/input-consume-token bail packages/client/ui-slash/src/types.ts:244 - ui-conversation
slash/input-insert-reference bail packages/client/ui-slash/src/types.ts:237 - ui-conversation
slash/input-insert-text bail packages/client/ui-slash/src/types.ts:252 - ui-conversation
subagent/end emit packages/subagent/subagent/src/index.ts:140 subagent (events.dispatch) hooks-claude, jsonrpc, subagent
subagent/provider-added emit packages/subagent/subagent/src/index.ts:114 subagent (emit) subagent, tool-subagent
subagent/provider-removed emit packages/subagent/subagent/src/index.ts:120 subagent (events.dispatch) subagent, tool-subagent
subagent/start emit packages/subagent/subagent/src/index.ts:131 subagent (events.dispatch) hooks-claude, subagent
system-prompt/assemble waterfall packages/core/system-prompt/src/index.ts:29 system-prompt (waterfall) agent, system-prompt
system-prompt/change emit packages/core/system-prompt/src/index.ts:35 system-prompt (emit) -
telemetry/record waterfall packages/telemetry/session-telemetry/src/index.ts:41 session-telemetry (waterfall) -
tools/change emit packages/core/tools/src/index.ts:156 tools (emit) -
tools/code-dispatch-log waterfall packages/core/tools/src/index.ts:138 tools (waterfall) spill-policy
tools/execute waterfall packages/core/tools/src/index.ts:113 tools (waterfall) session-checkpoint-policy, timeout-policy
tools/post-execute waterfall packages/core/tools/src/index.ts:125 tools (waterfall) hooks-claude, hooks-codex, repeat-tool-guard, spill-policy, tool-fs-search, workspace-context
tools/pre-execute waterfall packages/core/tools/src/index.ts:102 tools (waterfall) hooks-claude, hooks-codex, tool-tasks
tools/result emit packages/core/tools/src/index.ts:146 tools (events.dispatch) subagent-inprocess, workspace-context
workflow/agent-end emit packages/workflow/workflow/src/index.ts:81 workflow (events.dispatch) workflow
workflow/agent-start emit packages/workflow/workflow/src/index.ts:70 workflow (events.dispatch) workflow
workflow/end emit packages/workflow/workflow/src/index.ts:91 workflow (events.dispatch) workflow
workflow/log emit packages/workflow/workflow/src/index.ts:60 workflow (events.dispatch) -
workflow/phase emit packages/workflow/workflow/src/index.ts:53 workflow (events.dispatch) -
workflow/start emit packages/workflow/workflow/src/index.ts:45 workflow (events.dispatch) workflow

Non-harness or undeclared event strings seen in package source

Event string Dispatchers Listeners
commands/changed runtime (emit) ui-command
connection/reset runtime (emit) ui-command
internal/dispatch - commands, compact, fs, goal, goal-session, hook-protocol, llm-retry, permission, plan-mode, pty-local, runtime, sandbox-policy, scope, session, subagent, time-context, tool-todo, tools, user-approval, workflow
internal/plugin - hmr, modules, webserver
internal/status - agent
locale/change locale (emit) locale, ui-models, ui-settings-general
slots/changed runtime (emit) -
theme/change ui-theme (emit) ui-layout, ui-theme

Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.