Tianyi Cui
7f024a1a9d
Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
dsh-agent
Agent interface, registry, and agent/* event vocabulary. Every plugin (UI,
hooks, orchestrators) programs against the Agent handle defined here — it has
zero loop dependency, so the loop is swappable.
Service: AgentRegistry (ctx key: agents)
Tracks live agents so UI, hook, and orchestrator plugins can find them without importing the concrete loop package.
Public API
ctx.agents.register(agent: Agent): () => voidRegister a live agent. Disposed with the calling fiber.ctx.agents.get(id: string): Agent | undefinedctx.agents.list(): Agent[]
Events
The full agent/* event taxonomy is declared via declaration merging in
dsh-agent (not dsh-agent-loop), so plugins depend only on this package.
Lifecycle (emit)
agent/created,agent/disposed— registration/deregistrationagent/status— idle / running / disposed transitionagent/queued— message entered inbox (source-resolved, steering flag)
Turn/step boundaries (emit)
agent/turn-start,agent/turn-end(carriesTurnEndReason)agent/step-start,agent/step-end
Interception seams (waterfall)
agent/request— mutateGenerateOptionsbefore the model call (hooks, compaction, model switching, tool filtering)agent/step-result— post-process the assembled assistant message before tool dispatch (validates what the log records)agent/turn-continuation— override the continue/stop decision (force-continue /loop, force-stop budget guard)
Streaming + tool (emit)
agent/stream-chunk— raw chunk from the model (token-level UI/log feed)agent/steering— steering content injected mid-turnagent/error— step/turn error
Agent interface (types.ts)
The handle every plugin programs against:
agent.send(content, options?)— queue a message; starts a turn when idleagent.steer(content, options?)— steer a running turn (inject between steps); behaves likesendwhen idleagent.inject(content, options?)— inject in-session context without triggering a turn (context/message event); next request sees itagent.abort(reason?)— abort the in-flight stepagent.session,agent.status,agent.options,agent.id
Extension points
- Agent creation:
AgentLoop.create()is the concrete implementation (indsh-agent-loop). Replace the loop by implementingAgentand registering viactx.agents.register(). - Event listeners: all
agent/*events are declared here — no dependency on the loop package needed.
What is NOT here (TODO)
- Sub-agent spawn/fork — seam on
AgentLoop.create(), semantics deferred.