Document the codebase thoroughly and tighten type safety

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.

packages/agent/README.md

@@ -0,0 +1,72 @@
+# 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): () => void`
+  Register a live agent. Disposed with the calling fiber.
+- `ctx.agents.get(id: string): Agent | undefined`
+- `ctx.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/deregistration
+- `agent/status` — idle / running / disposed transition
+- `agent/queued` — message entered inbox (source-resolved, steering flag)
+
+#### Turn/step boundaries (emit)
+
+- `agent/turn-start`, `agent/turn-end` (carries `TurnEndReason`)
+- `agent/step-start`, `agent/step-end`
+
+#### Interception seams (waterfall)
+
+- `agent/request` — mutate `GenerateOptions` before 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-turn
+- `agent/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 idle
+- `agent.steer(content, options?)` — steer a running turn (inject between steps);
+  behaves like `send` when idle
+- `agent.inject(content, options?)` — inject in-session context without triggering
+  a turn (context/message event); next request sees it
+- `agent.abort(reason?)` — abort the in-flight step
+- `agent.session`, `agent.status`, `agent.options`, `agent.id`
+
+### Extension points
+
+- Agent creation: `AgentLoop.create()` is the concrete implementation (in
+  `dsh-agent-loop`). Replace the loop by implementing `Agent` and registering
+  via `ctx.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.

packages/agent/src/index.ts

@@ -1,3 +1,10 @@
+/**
+ * Agent registry service. Tracks live agents so plugins can find them without
+ * depending on the concrete loop package. Agent creation belongs to the loop.
+ *
+ * @module @deepseek-ai/dsh-agent
+ */
+
 import { Context, Service } from 'cordis'
 import type { Agent } from './types.ts'
 
@@ -22,7 +29,11 @@ export class AgentRegistry extends Service {
     super(ctx, 'agents')
   }
 
-  /** Register a live agent. Disposed with the calling fiber. */
+  /**
+   * Register a live agent. Throws if an agent with the same id is already
+   * registered. Emits `agent/created` on registration and `agent/disposed`
+   * when the calling fiber is disposed. Returns the disposer.
+   */
   register(agent: Agent): () => void {
     return this.ctx.effect(() => {
       if (this.store.has(agent.id)) {

packages/agent/src/types.ts

@@ -1,3 +1,14 @@
+/**
+ * Agent interface and event taxonomy. Every plugin programs against the
+ * `Agent` handle defined here; the concrete implementation lives in
+ * `@deepseek-ai/dsh-agent-loop`.
+ *
+ * Merge-extensible: `AgentOptions` supports declaration merging for
+ * plugin-specific creation options.
+ *
+ * @module @deepseek-ai/dsh-agent/types
+ */
+
 import type { ContentBlock, GenerateOptions, Message, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { Session, TurnEndReason } from '@deepseek-ai/dsh-session'