Merge remote-tracking branch 'origin/master' into feat/adr0016-type-build-check

2026-06-22 00:35:51 +08:00
parent fd55d20548 6b4dc48fbd
commit 74cdd9a2e5
365 changed files with 13601 additions and 7241 deletions
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -0,0 +1,70 @@
+# 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` — record an **already-constructed** agent. Disposed with the calling fiber.
+- `ctx.agents.get(id: AgentId): Agent | undefined`
+- `ctx.agents.list(): Agent[]`
+
+#### Factory seam (creation)
+
+Agent *creation* is provided by whichever plugin implements `AgentFactory` (phase 1: `dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package.
+
+- `ctx.agents.setFactory(factory: AgentFactory): () => void` — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
+- `ctx.agents.create(options: CreateAgentOptions): AgentHandle` — construct, start, AND register a new agent on a caller-supplied `sessionId` (with optional `meta.cwd`). Distinct from `register` (which only records). Throws if no factory is registered.
+- `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.
+
+`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear this agent down. `dispose()` stops the loop, `await`s its exit (quiescence — NOT just the `disposed` status flip), unregisters the agent, and removes its session from the store, in an order that captures the loop's final `session/flush` before the session is detached. `ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for the OWNER that created it. The ACP bridge is the production consumer (one handle per session, disposed on disconnect/teardown); config-created agents are owned by the loop fiber and never need a handle.
+
+### 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 (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md))
+- `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op.
+- `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.
+- `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.
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "@deepseek-ai/dsh-agent",
+  "description": "Agent interface, registry, and event vocabulary for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -0,0 +1,200 @@
+/**
+ * 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 { SessionId } from '@deepseek-ai/dsh-session'
+import type { Agent, AgentId, AgentOptions } from './types'
+
+export * from './types'
+
+declare module 'cordis' {
+  interface Context {
+    agents: AgentRegistry
+  }
+}
+
+/**
+ * Options for programmatically creating an agent through the registry factory
+ * ({@link AgentRegistry.create}). The caller supplies the live `sessionId`
+ * (e.g. an ACP-generated id) and optional session metadata (the validated
+ * `cwd`, fork lineage); the factory creates the session, the agent, and wires
+ * them together.
+ */
+export interface CreateAgentOptions {
+  /** The agent's id (the registry handle). */
+  agentId: AgentId
+  /** The live session's id (NOT derived from agentId). */
+  sessionId: SessionId
+  /**
+   * Session creation metadata: validated absolute `cwd` and `parentSession`
+   * fork lineage. Mirrors the `cwd`/`parentSession` fields of
+   * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
+   * `createdAt`, used when reconstructing a persisted session, is deliberately
+   * excluded — a factory caller never sets it).
+   */
+  meta?: { cwd?: string; parentSession?: SessionId }
+  /** Per-agent options (model, system prompt). */
+  agentOptions?: AgentOptions
+}
+
+/**
+ * Options for resuming an agent on a persisted session
+ * ({@link AgentRegistry.resume}).
+ */
+export interface ResumeAgentOptions {
+  /** The agent's id (the registry handle). */
+  agentId: AgentId
+  /** The persisted session id to load and resume on. */
+  resumeSessionId: SessionId
+  /** Per-agent options (model, system prompt). */
+  agentOptions?: AgentOptions
+}
+
+/**
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: only the holder
+ * can tear this agent down. `dispose()` unregisters the agent, stops its loop,
+ * awaits the loop's exit (quiescence — NOT just the `disposed` status flip), and
+ * removes the agent's session from the store, in an order that captures the
+ * loop's final `session/flush` before the session is detached.
+ *
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is only
+ * for the OWNER that created it. Config-created agents (the loop's own startup)
+ * are owned by the loop fiber and never need a handle.
+ */
+export interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
+
+/**
+ * The agent-creation factory the loop implementation provides to the registry
+ * via {@link AgentRegistry.setFactory}. Kept on the `dsh-agent` interface so
+ * consumers (e.g. the ACP bridge) program against `ctx.agents` without
+ * depending on the concrete `dsh-agent-loop` package.
+ */
+export interface AgentFactory {
+  /**
+   * Create, start, and register a new agent on a caller-supplied session id.
+   * Returns an {@link AgentHandle} — the owner disposes it to tear down exactly
+   * this agent (unregister + stop loop + await quiescence + remove session).
+   */
+  createAgent(options: CreateAgentOptions): AgentHandle
+  /**
+   * Load a persisted session and resume an agent on it. Async because it awaits
+   * `ctx.sessionPersistence.load`; must be called after that service exists
+   * (consumers inject `sessionPersistence`). Returns an {@link AgentHandle}.
+   */
+  resume(options: ResumeAgentOptions): Promise<AgentHandle>
+}
+
+/** Thrown when create/resume is called before an agent factory is registered. */
+const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plugin)'
+
+/**
+ * Agent registry (`ctx.agents`): tracks live agents so UI, hook, and
+ * orchestrator plugins can find them without depending on the concrete loop
+ * package. Agent *creation* is provided by whichever plugin implements the
+ * {@link AgentFactory} (phase 1: `@deepseek-ai/dsh-agent-loop`), registered via
+ * {@link setFactory}.
+ */
+export class AgentRegistry extends Service {
+  private store = new Map<AgentId, Agent>()
+  private factory: AgentFactory | undefined
+
+  constructor(ctx: Context) {
+    super(ctx, 'agents')
+  }
+
+  /**
+   * Register the agent-creation factory (the loop calls this on construction,
+   * effect-scoped). Throws if a factory is already registered. Returns the
+   * disposer; on dispose the factory slot is cleared.
+   */
+  setFactory(factory: AgentFactory): () => void {
+    const dispose = this.ctx.effect(() => {
+      if (this.factory !== undefined) throw new Error('an agent factory is already registered')
+      this.factory = factory
+      return () => { this.factory = undefined }
+    }, 'agents.setFactory()')
+    return () => void dispose()
+  }
+
+  /**
+   * Create, start, and register a new agent through the registered factory.
+   * Distinct from {@link register} (which records an already-constructed
+   * agent): this constructs the agent and its session. Throws if no factory is
+   * registered. Returns an {@link AgentHandle} — the owner disposes it to tear
+   * down exactly this agent.
+   */
+  create(options: CreateAgentOptions): AgentHandle {
+    if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
+    return this.factory.createAgent(options)
+  }
+
+  /**
+   * Load a persisted session and resume an agent on it through the registered
+   * factory. Rejects if no factory is registered; the factory rejects if
+   * session persistence is not configured. Returns an {@link AgentHandle}.
+   */
+  async resume(options: ResumeAgentOptions): Promise<AgentHandle> {
+    if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
+    return this.factory.resume(options)
+  }
+
+  /**
+   * 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 {
+    const dispose = this.ctx.effect(function* (this: AgentRegistry) {
+      if (this.store.has(agent.id)) {
+        throw new Error(`agent "${agent.id}" is already registered`)
+      }
+      this.store.set(agent.id, agent)
+      // Yield the rollback BEFORE emitting `agent/created`: a generator effect
+      // collects each yielded disposer before the next step runs, so a
+      // throwing `agent/created` listener rolls the entry back instead of
+      // leaking it (a leak would wedge the duplicate-id check until restart).
+      // The duplicate throw above fires before any mutation — it leaks nothing.
+      yield () => {
+        this.store.delete(agent.id)
+        // CONTAIN a throwing `agent/disposed` listener: this disposer runs as
+        // one link in the owning fiber/effect's disposal chain, and Cordis
+        // chains later disposers with `task.then(next)` — so an UNCAUGHT throw
+        // here rejects the chain and SKIPS every later disposer. When this
+        // registration shares a composite effect with a session (the agent
+        // factory's `AgentLoop.start`, where the session-detach disposer runs
+        // AFTER this one), a swallowed-less throw would strand the session in
+        // the store with `onAppend` attached — a leak AND a durability hole.
+        // The store entry is already removed above (the useful state), so
+        // logging the listener bug and continuing is correct (mirrors the
+        // guarded `agent/status` emit in dsh-agent-loop's ReactLoopAgent).
+        try {
+          this.ctx.emit('agent/disposed', agent)
+        } catch (error: unknown) {
+          this.ctx.logger.warn(`agent "${agent.id}": agent/disposed listener threw: ${String(error)}`)
+        }
+      }
+      this.ctx.emit('agent/created', agent)
+    }.bind(this), 'agents.register()')
+    // ctx.effect's disposer returns Promise<void>; our disposer API is
+    // synchronous fire-and-forget — discard the (always-resolved) promise.
+    return () => void dispose()
+  }
+
+  get(id: AgentId): Agent | undefined {
+    return this.store.get(id)
+  }
+
+  list(): Agent[] {
+    return [...this.store.values()]
+  }
+}
+
+export default AgentRegistry
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -0,0 +1,221 @@
+/**
+ * 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 { Branded } from '@deepseek-ai/dsh-brand'
+import type { ContentBlock, GenerateOptions, Message, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
+
+/** Identifies one live agent in the registry. */
+export type AgentId = Branded<'AgentId'>
+
+/** Brand a string as an {@link AgentId}. */
+export function AgentId(id: string): AgentId {
+  return id as AgentId
+}
+import type { Session, TurnEndReason } from '@deepseek-ai/dsh-session'
+
+/**
+ * Options an agent is created with.
+ * Merge-extensible: plugins declare extra fields via declaration merging.
+ */
+export interface AgentOptions {
+  /** Model name (must have a registered adapter at call time). */
+  model?: string
+  /** Per-agent system prompt appended after the assembled sections. */
+  systemPrompt?: string
+}
+
+export interface SendOptions {
+  source?: MessageSource
+}
+
+export type AgentStatus = 'idle' | 'running' | 'disposed'
+
+/**
+ * The agent handle — the surface every plugin (UI, hooks, orchestrators)
+ * programs against. The concrete implementation lives in
+ * `@deepseek-ai/dsh-agent-loop` (class `ReactLoopAgent`); nothing outside the loop
+ * package should depend on the implementation.
+ */
+export interface Agent {
+  readonly id: AgentId
+  readonly options: AgentOptions
+  readonly session: Session
+  readonly status: AgentStatus
+
+  /** Queue a user message. Starts a turn when idle; otherwise waits for the next turn. */
+  send(content: ContentBlock[], options?: SendOptions): void
+
+  /**
+   * Steer a running turn: content is injected between steps of the current
+   * turn. When idle, behaves like {@link send}.
+   */
+  steer(content: ContentBlock[], options?: SendOptions): void
+
+  /**
+   * Inject in-session context (file-change notices, skill content, cron
+   * notifications, …): appends a `context/message` session event the next model
+   * request sees at its chronological position, rendered as tagged synthetic
+   * context rather than a user prompt. Does not run the model.
+   *
+   * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn;
+   * an inject while idle wraps its `context/message` in a one-shot `injection`
+   * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for
+   * durability, so every event stays inside a turn and a persistence backend
+   * never loses a between-turn notice. The idle checkpoint is fire-and-forget
+   * (inject is synchronous): a failing flush is reported via `agent/error`
+   * (step `0`) and the logger, never thrown into the caller.
+   *
+   * Live-adapter review has validated the tagged-envelope rendering against
+   * current DeepSeek behavior; provider-specific mismatches belong in that
+   * adapter, not in the canonical session vocabulary.
+   */
+  inject(content: ContentBlock[], options?: SendOptions): void
+
+  /**
+   * Cancel ALL pending work for the agent. `cancel()`:
+   *
+   * - clears the queued FIFO (un-started prompts never run) and the steering
+   *   FIFO (steering for the cancelled turn is dropped, not re-enqueued);
+   * - aborts the in-flight step if one is running (the turn ends `aborted`);
+   * - drops a turn that is about to start (a `cancel()` landing in the
+   *   pre-step window — after a `send()` queued but before the loop flips to
+   *   `running`, or after `running` is emitted but before the first step) so
+   *   that queued prompt does not run and cannot be batched into the cancelled
+   *   turn.
+   *
+   * After `cancel()`, `whenIdle()` resolves on the post-cancel quiescent state.
+   * `cancel()` on an idle agent with nothing queued or running is a safe no-op
+   * — it does NOT arm anything that would drop a later legitimate prompt.
+   */
+  cancel(reason?: string): void
+
+  /**
+   * Resolve once the agent has reached quiescence after settling out of
+   * `running`, or immediately if it is already idle with no queued work. A
+   * non-owner's quiescence-observation hook: a consumer that does NOT own the
+   * agent's lifecycle awaits this to proceed only after queued/running work has
+   * fully stopped, rather than returning while the driver is still streaming or
+   * about to start a queued turn — without itself tearing the agent down. (A
+   * lifecycle OWNER does not need it: `AgentHandle.dispose()` already awaits the
+   * loop-exit promise directly as part of stopping and unregistering. So this is
+   * for a non-owning observer — e.g. a test awaiting a turn to settle, or a
+   * monitor — that wants the settle signal but must not dispose the agent.)
+   *
+   * "Quiescence", not merely "status changed": a disposed agent emits
+   * `agent/status('disposed')` from inside its disposer, BEFORE the driver loop
+   * has unwound — so `whenIdle()` resolving on `disposed` must wait for the loop
+   * to actually exit (the implementation chains the loop-exit promise), not just
+   * observe the status flip. A mid-step disposal that never reaches `idle` still
+   * unblocks the await this way.
+   */
+  whenIdle(): Promise<void>
+
+  // TODO(sub-agents): spawn/fork seams — semantics deliberately deferred.
+  // The intended shape: a creation option referencing a parent agent
+  // (fork = seed the child Session with the parent's event log; spawn =
+  // fresh Session), with the child returned as an Agent handle so steer()
+  // and event subscription work uniformly. See docs/architecture.md.
+}
+
+declare module 'cordis' {
+  interface Events {
+    // ---- lifecycle (emit) ----
+    /**
+     * An agent was registered in the {@link AgentRegistry} and is ready to
+     * receive messages.
+     * @mode emit
+     */
+    'agent/created'(agent: Agent): void
+    /**
+     * An agent was disposed and removed from the registry; its fiber and any
+     * in-flight turn have been torn down.
+     * @mode emit
+     */
+    'agent/disposed'(agent: Agent): void
+    /**
+     * Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive
+     * lifecycle off this transition, never off a status you just requested —
+     * `send()` does not flip status to `running` before it returns.
+     * @mode emit
+     */
+    'agent/status'(agent: Agent, status: AgentStatus): void
+    /**
+     * A message entered the agent's inbox (queued or steering). `source` is
+     * the resolved source (defaults applied), not the caller's raw options.
+     * @mode emit
+     */
+    'agent/queued'(agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
+
+    // ---- turn/step boundaries (emit) ----
+    /**
+     * A turn began. `turn` is the 1-based turn number within the session.
+     * @mode emit
+     */
+    'agent/turn-start'(agent: Agent, turn: number): void
+    /**
+     * A turn ended. `reason` distinguishes a clean stop from a truncated or
+     * aborted one (`completed` | `aborted` | `error` | `disposed` | `max-tokens`).
+     * @mode emit
+     */
+    'agent/turn-end'(agent: Agent, turn: number, reason: TurnEndReason): void
+    /**
+     * A step (one model call plus its tool dispatch) began. `step` is 1-based
+     * within the turn; a turn runs one or more steps.
+     * @mode emit
+     */
+    'agent/step-start'(agent: Agent, turn: number, step: number): void
+    /**
+     * A step ended.
+     * @mode emit
+     */
+    'agent/step-end'(agent: Agent, turn: number, step: number): void
+
+    // ---- interception seams (waterfall) ----
+    /**
+     * Waterfall: mutate the fully-assembled {@link GenerateOptions} before the
+     * model call (hooks, compaction, model switching, tool filtering, …). Call
+     * `next()` to delegate, or return without it to short-circuit.
+     * @mode waterfall
+     */
+    'agent/request'(agent: Agent, turn: number, step: number, options: GenerateOptions, next: () => Promise<GenerateOptions>): Promise<GenerateOptions>
+    /**
+     * Waterfall: post-process the assembled assistant {@link Message} before
+     * tool dispatch (validation, content rewriting, …).
+     * @mode waterfall
+     */
+    'agent/step-result'(agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
+    /**
+     * Waterfall: override the turn-continuation decision. The default
+     * (computed by the loop) is `hadToolCalls || steeringInjected`. Listeners
+     * can force-continue (/goal, /loop) or force-stop (budget guards).
+     * @mode waterfall
+     */
+    'agent/turn-continuation'(agent: Agent, turn: number, defaultDecision: boolean, next: () => Promise<boolean>): Promise<boolean>
+
+    // ---- streaming + tool notifications (emit) ----
+    /**
+     * A raw {@link StreamChunk} arrived from the model (token-level UI/log feed).
+     * @mode emit
+     */
+    'agent/stream-chunk'(agent: Agent, turn: number, step: number, chunk: StreamChunk): void
+    /**
+     * Steering content was injected into a running turn.
+     * @mode emit
+     */
+    'agent/steering'(agent: Agent, turn: number, content: ContentBlock[], source: MessageSource): void
+    /**
+     * A step or turn errored. The loop reports a failure here (plus the logger)
+     * even when the error has no in-turn position for a session `error` event.
+     * @mode emit
+     */
+    'agent/error'(agent: Agent, turn: number, step: number, error: Error): void
+  }
+}
--- a/packages/core/agent/tests/agent.spec.ts
+++ b/packages/core/agent/tests/agent.spec.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+
+function stubAgent(rawId: string): Agent {
+  const id = AgentId(rawId)
+  return {
+    id,
+    options: {},
+    session: new Session(SessionId(`${id}-session`)),
+    status: 'idle',
+    send() {},
+    steer() {},
+    inject() {},
+    cancel() {},
+    whenIdle() { return Promise.resolve() },
+  }
+}
+
+describe('AgentRegistry', () => {
+  it('registers agents and emits created/disposed events', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+
+    const created: string[] = []
+    const disposed: string[] = []
+    ctx.on('agent/created', agent => void created.push(agent.id))
+    ctx.on('agent/disposed', agent => void disposed.push(agent.id))
+
+    const agent = stubAgent('a1')
+    const dispose = ctx.agents.register(agent)
+    expect(created).toEqual(['a1'])
+    expect(ctx.agents.get(AgentId('a1'))).toBe(agent)
+    expect(ctx.agents.list()).toEqual([agent])
+
+    dispose()
+    expect(disposed).toEqual(['a1'])
+    expect(ctx.agents.get(AgentId('a1'))).toBeUndefined()
+  })
+
+  it('rejects duplicate ids and unregisters on fiber dispose (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    ctx.agents.register(stubAgent('main'))
+    expect(() => ctx.agents.register(stubAgent('main'))).toThrow('already registered')
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.agents.register(stubAgent('scoped'))
+    }, { inject: ['agents'] }))
+    expect(ctx.agents.list().map(a => a.id)).toEqual(['main', 'scoped'])
+
+    await fiber.dispose()
+    expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
+  })
+
+  it('rolls back the agent entry when an agent/created listener throws (P1-1)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+
+    let threw = false
+    ctx.on('agent/created', () => {
+      if (!threw) { threw = true; throw new Error('boom created listener') }
+    })
+
+    // The throwing emit must roll the entry back, not leak it.
+    expect(() => ctx.agents.register(stubAgent('main'))).toThrow('boom created listener')
+    expect(ctx.agents.get(AgentId('main'))).toBeUndefined() // rolled back, not leaked
+
+    // A subsequent listener-free register of the SAME id succeeds and is
+    // tracked exactly once (the duplicate-id check is not wedged).
+    const dispose = ctx.agents.register(stubAgent('main'))
+    expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
+    dispose()
+    expect(ctx.agents.get(AgentId('main'))).toBeUndefined()
+  })
+})
+
+describe('AgentRegistry factory seam', () => {
+  /** A stub AgentFactory that records calls and returns a stub agent. */
+  function stubFactory() {
+    const calls: { create: unknown[]; resume: unknown[] } = { create: [], resume: [] }
+    const factory: import('@deepseek-ai/dsh-agent').AgentFactory = {
+      createAgent(options) {
+        calls.create.push(options)
+        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+      },
+      resume(options) {
+        calls.resume.push(options)
+        return Promise.resolve({ agent: stubAgent(options.agentId), dispose: () => Promise.resolve() })
+      },
+    }
+    return { factory, calls }
+  }
+
+  it('create()/resume() throw when no factory is registered', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    expect(() => ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).toThrow(/no agent factory/)
+    await expect(ctx.agents.resume({ agentId: AgentId('a'), resumeSessionId: SessionId('s') })).rejects.toThrow(/no agent factory/)
+  })
+
+  it('setFactory registers a factory; create/resume delegate to it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const { factory, calls } = stubFactory()
+    ctx.agents.setFactory(factory)
+
+    const created = ctx.agents.create({ agentId: AgentId('c1'), sessionId: SessionId('sess-1'), meta: { cwd: '/w' } })
+    expect(created.agent.id).toBe('c1')
+    expect(calls.create).toEqual([{ agentId: AgentId('c1'), sessionId: SessionId('sess-1'), meta: { cwd: '/w' } }])
+
+    const resumed = await ctx.agents.resume({ agentId: AgentId('r1'), resumeSessionId: SessionId('old-sess') })
+    expect(resumed.agent.id).toBe('r1')
+    expect(calls.resume).toEqual([{ agentId: AgentId('r1'), resumeSessionId: SessionId('old-sess') }])
+  })
+
+  it('setFactory rejects a second factory', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    ctx.agents.setFactory(stubFactory().factory)
+    expect(() => ctx.agents.setFactory(stubFactory().factory)).toThrow(/already registered/)
+  })
+
+  it('disposing the setFactory fiber clears the factory (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    let dispose!: () => void
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      dispose = inner.agents.setFactory(stubFactory().factory)
+    }, { inject: ['agents'] }))
+    expect(() => ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).not.toThrow()
+    void dispose
+    await fiber.dispose()
+    // factory slot cleared → create throws again
+    expect(() => ctx.agents.create({ agentId: AgentId('a2'), sessionId: SessionId('s2') })).toThrow(/no agent factory/)
+  })
+})
--- a/packages/core/agent/tests/gen-cordis-catalog.spec.ts
+++ b/packages/core/agent/tests/gen-cordis-catalog.spec.ts
@@ -0,0 +1,83 @@
+/**
+ * Negative-path tests for the cordis catalog generator (`scripts/gen-cordis-catalog.ts`).
+ *
+ * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
+ * the freshness half is exercised by `pnpm run verify-cordis-catalog` in CI.
+ * What a freshness diff CANNOT prove is that the generator REJECTS malformed
+ * source the way it promises to — a missing `@mode` tag, or a tag that
+ * contradicts the signature shape. These tests drive `collectEvents()` against
+ * synthetic fixture packages to prove each guard fires (and that a well-formed
+ * event passes), mirroring the drift-guard negative tests for verify-type-equiv.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectEvents } from '../../../../scripts/gen-cordis-catalog.ts'
+
+/** Write a fixture package exposing one `interface Events` block and return the
+ * scan root to hand `collectEvents`. */
+function fixtureRoot(eventsBlock: string): string {
+  const root = mkdtempSync(join(tmpdir(), 'cordis-catalog-'))
+  const dir = join(root, 'packages', 'group', 'fix', 'src')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(
+    join(dir, 'index.ts'),
+    `declare module 'cordis' {\n  interface Events {\n${eventsBlock}\n  }\n}\n`,
+  )
+  return root
+}
+
+const roots: string[] = []
+const make = (block: string): string => {
+  const r = fixtureRoot(block)
+  roots.push(r)
+  return r
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+describe('gen-cordis-catalog collectEvents', () => {
+  it('extracts a well-formed event with its @mode and JSDoc', () => {
+    const events = collectEvents(make(
+      '    /**\n     * A thing happened.\n     * @mode emit\n     */\n    \'fix/happened\'(id: string): void',
+    ))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({ name: 'fix/happened', scope: 'fix', mode: 'emit', doc: 'A thing happened.' })
+  })
+
+  it('classifies a trailing-next signature as a waterfall', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Intercept it.\n     * @mode waterfall\n     */\n    \'fix/intercept\'(x: number, next: () => Promise<number>): Promise<number>',
+    ))
+    expect(events[0]?.mode).toBe('waterfall')
+  })
+
+  it('accepts a parallel (awaited, no next) event by trusting the tag', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Flush.\n     * @mode parallel\n     */\n    \'fix/flush\'(): Promise<void> | void',
+    ))
+    expect(events[0]?.mode).toBe('parallel')
+  })
+
+  it('hard-errors when an event is missing its @mode tag', () => {
+    expect(() => collectEvents(make(
+      '    /** No mode here. */\n    \'fix/untagged\'(id: string): void',
+    ))).toThrow(/missing an @mode tag/)
+  })
+
+  it('hard-errors when @mode contradicts a trailing-next (waterfall) shape', () => {
+    expect(() => collectEvents(make(
+      '    /**\n     * Mislabeled.\n     * @mode emit\n     */\n    \'fix/wrong\'(x: number, next: () => Promise<number>): Promise<number>',
+    ))).toThrow(/trailing 'next' parameter .* tagged '@mode emit'/)
+  })
+
+  it('hard-errors when @mode waterfall has no trailing next to delegate to', () => {
+    expect(() => collectEvents(make(
+      '    /**\n     * Not actually a waterfall.\n     * @mode waterfall\n     */\n    \'fix/nonext\'(id: string): void',
+    ))).toThrow(/tagged '@mode waterfall' but has no trailing 'next'/)
+  })
+})
--- a/packages/core/agent/tsconfig.json
+++ b/packages/core/agent/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    }
+  ]
+}