feat(agent): create/resume factory seam

Add the agent-creation factory seam on ctx.agents (AgentRegistry):
setFactory/create/resume plus the AgentFactory interface and
CreateAgentOptions/ResumeAgentOptions. AgentLoop implements AgentFactory
and registers itself via ctx.agents.setFactory(this), so plugins
create/resume agents through the interface without depending on the
concrete loop package.

- create({ agentId, sessionId, meta?, agentOptions? }) — programmatic
  create on a caller-supplied session id (e.g. an ACP-generated id).
- resume({ agentId, resumeSessionId, agentOptions? }) — load a persisted
  session via ctx.sessionPersistence (RFC 009) and resume an agent on it;
  the live session id is the resumed id, turn numbering and derived
  history continue from the loaded log. sessionPersistence is NOT
  hard-injected (non-persistent demos still work); resume rejects with a
  typed error when it is absent. assertAgentIdFree runs before any
  session is created (and again after the load await) so a duplicate id
  never leaves an orphaned live session.

Adds the runtime dsh-session-persistence dependency to agent-loop.

packages/agent/README.md

@@ -8,10 +8,18 @@ Tracks live agents so UI, hook, and orchestrator plugins can find them without i
 
 ### Public API
 
-- `ctx.agents.register(agent: Agent): () => void` Register a live agent. Disposed with the calling fiber.
+- `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
 - `ctx.agents.get(id: string): 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): Agent` — 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<Agent>` — load a persisted session (RFC 009) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.
+
 ### 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.
@@ -45,7 +53,7 @@ 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); next request sees it. While running it joins the open turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed (ADR 0017)
+- `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`
 

packages/agent/src/index.ts

@@ -6,7 +6,8 @@
  */
 
 import { Context, Service } from 'cordis'
-import type { Agent } from './types.ts'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
 
@@ -16,19 +17,110 @@ declare module 'cordis' {
   }
 }
 
+/**
+ * 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: string
+  /** The live session's id (NOT derived from agentId). */
+  sessionId: string
+  /**
+   * 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: string
+  /** The persisted session id to load and resume on. */
+  resumeSessionId: string
+  /** Per-agent options (model, system prompt). */
+  agentOptions?: AgentOptions
+}
+
+/**
+ * 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. */
+  createAgent(options: CreateAgentOptions): Agent
+  /**
+   * 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`).
+   */
+  resume(options: ResumeAgentOptions): Promise<Agent>
+}
+
 /**
  * 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* belongs to whichever plugin implements the Agent
- * interface (phase 1: `@deepseek-ai/dsh-agent-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<string, 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.
+   */
+  create(options: CreateAgentOptions): Agent {
+    if (this.factory === undefined) throw new Error('no agent factory registered (load an agent-loop plugin)')
+    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.
+   */
+  async resume(options: ResumeAgentOptions): Promise<Agent> {
+    if (this.factory === undefined) throw new Error('no agent factory registered (load an agent-loop plugin)')
+    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`

packages/agent/tests/agent.spec.ts

@@ -74,3 +74,58 @@ describe('AgentRegistry', () => {
     expect(ctx.agents.get('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 stubAgent(options.agentId) },
+      resume(options) { calls.resume.push(options); return Promise.resolve(stubAgent(options.agentId)) },
+    }
+    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: 'a', sessionId: 's' })).toThrow(/no agent factory/)
+    await expect(ctx.agents.resume({ agentId: 'a', resumeSessionId: '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: 'c1', sessionId: 'sess-1', meta: { cwd: '/w' } })
+    expect(created.id).toBe('c1')
+    expect(calls.create).toEqual([{ agentId: 'c1', sessionId: 'sess-1', meta: { cwd: '/w' } }])
+
+    const resumed = await ctx.agents.resume({ agentId: 'r1', resumeSessionId: 'old-sess' })
+    expect(resumed.id).toBe('r1')
+    expect(calls.resume).toEqual([{ agentId: 'r1', resumeSessionId: '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: 'a', sessionId: 's' })).not.toThrow()
+    void dispose
+    await fiber.dispose()
+    // factory slot cleared → create throws again
+    expect(() => ctx.agents.create({ agentId: 'a2', sessionId: 's2' })).toThrow(/no agent factory/)
+  })
+})