Merge worktree/schedule-conversational-after into worktree/schedule-explicit-at

packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts

@@ -0,0 +1,727 @@
+/**
+ * A session's agent preset is fixed at creation. The gateway records the
+ * resolved id on the header and refuses to adopt the identity under a different
+ * one, because the session's history was produced under that preset's tools:
+ * rebuilding it differently would replay tool calls the new agent cannot make.
+ */
+
+import { mkdtempSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import AgentRegistry, { type AgentFactory } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import { RpcId, type RpcRequest } from '../src/api/rpc.ts'
+import type { HostFrame } from '../src/api/events.ts'
+import {
+  InvalidPresetIdError, PresetExistsError, resolveSessionPreset, UnknownPresetError,
+} from '@deepseek-ai/dsh-agent-presets'
+import { GoalId } from '@deepseek-ai/dsh-goal'
+import { createApiProxy } from '../src/api-proxy.ts'
+import { describe, expect, it } from 'vitest'
+
+let nextRpc = 0
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`preset-${String(nextRpc++)}`), payload }
+}
+
+/** Minimal live agent; the gateway only needs identity and its session. */
+function stubAgent(session: Session): Agent {
+  return { id: session.id, session, status: 'idle' } as unknown as Agent
+}
+
+/**
+ * A roster whose `mount` is a no-op: this spec is about the gateway's identity
+ * rules, and the composition itself is covered by the real-composition test in
+ * `apps/cli`. Ids listed in `userIds` present as locally authored; the rest
+ * ship with the deployment.
+ */
+function roster(ids: readonly string[], userIds: readonly string[] = []): unknown {
+  const trustOf = (id: string): 'system' | 'user' => (userIds.includes(id) ? 'user' : 'system')
+  const presetOf = (id: string): object =>
+    ({ id, trust: trustOf(id), path: `/presets/${id}/agent.cordis.yml` })
+  return {
+    defaultId: ids[0],
+    list: () => Promise.resolve(ids.map(presetOf)),
+    resolve: (id?: string) => {
+      const wanted = id ?? ids[0] ?? ''
+      if (!ids.includes(wanted)) return Promise.reject(new UnknownPresetError(wanted, ids))
+      return Promise.resolve(presetOf(wanted))
+    },
+    mount: (_ctx: Context, id?: string) => Promise.resolve(presetOf(id ?? ids[0] ?? '')),
+    // What a real mount leaves behind: a service instance only the agent that
+    // mounted it can be used to address. The doubles are per agent so a test
+    // can tell "this session's" from "some session's".
+    serviceFor: (agent: { id: unknown }, name: string) => {
+      const perAgent = services.get(String(agent.id))
+      return perAgent?.[name]
+    },
+    authorable: true,
+    read: (id: string) => Promise.resolve(`# ${id}\n- id: x\n  name: y\n`),
+    copy: (from: string, id: string) => {
+      if (!ids.includes(from)) return Promise.reject(new UnknownPresetError(from, ids))
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) return Promise.reject(new InvalidPresetIdError(id))
+      if (ids.includes(id)) return Promise.reject(new PresetExistsError(id))
+      return Promise.resolve()
+    },
+    remove: (id: string) => {
+      if (!ids.includes(id)) return Promise.reject(new UnknownPresetError(id, ids))
+      return Promise.resolve()
+    },
+    recompose: (_ctx: Context, id: string) => {
+      if (!ids.includes(id)) return Promise.reject(new UnknownPresetError(id, ids))
+      return Promise.resolve({ id, trust: 'system', path: `/presets/${id}.yml` })
+    },
+    // The standing scope key a cold transcript read resolves presenters in.
+    standingKeyFor: (id?: string) => {
+      const wanted = id ?? ids[0] ?? ''
+      standingKeyRequests.push(wanted)
+      if (!ids.includes(wanted) || failingStandingKeys.has(wanted)) {
+        return Promise.reject(new UnknownPresetError(wanted, ids))
+      }
+      let key = standingKeys.get(wanted)
+      if (key === undefined) {
+        key = { agentPreset: wanted }
+        standingKeys.set(wanted, key)
+      }
+      return Promise.resolve(key)
+    },
+  }
+}
+
+/** Standing keys the roster double minted, and the ids readers asked for. */
+const standingKeys = new Map<string, object>()
+const standingKeyRequests: string[] = []
+/** Preset ids whose standing mount the double reports as unusable. */
+const failingStandingKeys = new Set<string>()
+
+/** Per-agent service instances a mounted preset would own, keyed by session id. */
+const services = new Map<string, Record<string, unknown>>()
+
+async function harness(
+  presets?: readonly string[],
+  persistence?: unknown,
+  options: { userIds?: readonly string[]; defaults?: Record<string, unknown> } = {},
+) {
+  const cwd = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-preset-')))
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  ctx.provide('sessionPersistence', (persistence ?? { list: () => Promise.resolve([]) }) as never)
+  if (presets !== undefined) ctx.provide('agentPresets', roster(presets, options.userIds) as never)
+
+  const factory: AgentFactory = {
+    async createAgent(_ownerCtx, options) {
+      const session = ctx.sessions.create(
+        options.sessionId,
+        options.meta === undefined ? {} : { meta: options.meta },
+      )
+      const agent = stubAgent(session)
+      // Setup runs before publication against a context that carries the
+      // agent, and the agent reaches back through `agent.ctx` — the pair the
+      // gateway's own `installTarget` relies on.
+      const agentCtx = ctx.extend({ agent })
+      ;(agent as { ctx?: Context }).ctx = agentCtx
+      await options.setup?.(agentCtx)
+      const unregister = ctx.agents.register(agent)
+      return { agent, dispose: () => { unregister(); return Promise.resolve() } }
+    },
+    async resume() {
+      throw new Error('test harness has no persisted sessions')
+    },
+  }
+  ctx.agents.setFactory(factory)
+  const api = createApiProxy(ctx, {
+    defaultModelSelection: () => ({ provider: 'test', model: 'test-model' }),
+    cwd,
+    ...options.defaults,
+  })
+  return { api, ctx, cwd }
+}
+
+describe('session.create with an agent preset', () => {
+  it('records the resolved preset on the session header', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+
+    const created = await api.sessions.create(request({ sessionId: SessionId('s1'), agentPreset: 'minimal' }))
+
+    expect(created.result.ok).toBe(true)
+    expect(ctx.sessions.get(SessionId('s1'))?.header.agentPreset).toBe('minimal')
+  })
+
+  it('records the default when the caller names none', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+
+    await api.sessions.create(request({ sessionId: SessionId('s2') }))
+
+    expect(ctx.sessions.get(SessionId('s2'))?.header.agentPreset).toBe('standard')
+  })
+
+  it('rejects an unknown preset and names the ones that exist', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.sessions.create(request({ sessionId: SessionId('s3'), agentPreset: 'nope' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+
+  it('refuses to adopt a live session under a different preset', async () => {
+    const { api } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('s4'), agentPreset: 'minimal' }))
+
+    const response = await api.sessions.create(request({ sessionId: SessionId('s4'), agentPreset: 'standard' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-conflict')
+    expect(response.result.error.details).toEqual({
+      sessionId: 's4',
+      requestedPreset: 'standard',
+      existingPreset: 'minimal',
+    })
+  })
+
+  it('adopts a live session under the preset it SWITCHED to', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('s4b'), agentPreset: 'standard' }))
+    // Exactly what `agentPreset.select` leaves behind on a blank session: the
+    // header keeps the creation fact, the log states what the agent runs.
+    ctx.sessions.get(SessionId('s4b'))?.append('agent-preset/selected', { agentPreset: 'minimal' })
+
+    const adopted = await api.sessions.create(request({ sessionId: SessionId('s4b'), agentPreset: 'minimal' }))
+    const stale = await api.sessions.create(request({ sessionId: SessionId('s4b'), agentPreset: 'standard' }))
+
+    // Comparing against the header would invert both answers: the preset the
+    // session actually runs would be refused, and the one it left would pass.
+    expect(adopted.result.ok).toBe(true)
+    // The echo has to name the same preset the adoption just accepted, or the
+    // client labels the session with one it has already left — and disagrees
+    // with the row `session.list` serves for it.
+    if (!adopted.result.ok) throw new Error('unreachable')
+    expect(adopted.result.value).toMatchObject({ agentPreset: 'minimal' })
+    expect(stale.result.ok).toBe(false)
+    if (stale.result.ok) throw new Error('unreachable')
+    expect(stale.result.error.details).toMatchObject({ existingPreset: 'minimal' })
+  })
+
+  it('adopts a live session unchanged when the caller names no preset', async () => {
+    const { api } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('s5'), agentPreset: 'minimal' }))
+
+    // Reconnecting and retrying a create must stay ordinary operations.
+    const response = await api.sessions.create(request({ sessionId: SessionId('s5') }))
+
+    expect(response.result.ok).toBe(true)
+  })
+
+  it('leaves the header preset-less when no roster is composed', async () => {
+    const { api, ctx } = await harness()
+
+    await api.sessions.create(request({ sessionId: SessionId('s6') }))
+
+    expect(ctx.sessions.get(SessionId('s6'))?.header.agentPreset).toBeUndefined()
+  })
+
+  it('says why a preset-less session cannot be adopted under one', async () => {
+    // Two callers reach this: a deployment that composes no roster, and a
+    // session created before one existed. Both record no preset, so naming
+    // any is a conflict rather than an adoption — the history was produced
+    // under a composition this roster cannot name. The message has to say
+    // that, because "already runs agent preset undefined" reads as a bug.
+    const { api } = await harness()
+    await api.sessions.create(request({ sessionId: SessionId('s7') }))
+
+    const response = await api.sessions.create(request({ sessionId: SessionId('s7'), agentPreset: 'standard' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-conflict')
+    expect(response.result.error.message).toContain('records no agent preset')
+    expect(response.result.error.details).toEqual({
+      sessionId: 's7',
+      requestedPreset: 'standard',
+      existingPreset: undefined,
+    })
+  })
+})
+
+/**
+ * A capability a preset mounts is reachable from nowhere the host normally
+ * looks: an `isolate` realm is what makes it per session. The gateway serves
+ * requests that are ABOUT a session from OUTSIDE it, so it addresses the
+ * instance through the agent instead of reading a root-realm singleton.
+ */
+describe('a capability the session\'s preset mounts', () => {
+  it('serves the goal RPC from the session\'s own goal service', async () => {
+    const { api } = await harness(['standard'])
+    await api.sessions.create(request({ sessionId: SessionId('g1'), agentPreset: 'standard' }))
+    const ref = { id: GoalId('goal-1'), revision: 1 }
+    const paused: unknown[] = []
+    services.set('g1', {
+      goals: { pause: (agent: { id: unknown }, r: unknown) => { paused.push([String(agent.id), r]); return ref } },
+    })
+
+    const response = await api.goals.pause(request({ sessionId: SessionId('g1'), ref }))
+
+    expect(response.result).toMatchObject({ ok: true, value: { ref } })
+    // Reached the instance this session mounted, and was handed its own agent.
+    expect(paused).toEqual([['g1', ref]])
+    services.delete('g1')
+  })
+
+  it('serves the skill catalog from the session\'s own registry', async () => {
+    const { api } = await harness(['standard'])
+    await api.sessions.create(request({ sessionId: SessionId('k1'), agentPreset: 'standard' }))
+    services.set('k1', {
+      skills: {
+        list: () => Promise.resolve([{
+          name: 'preset-owned',
+          description: 'ships inside the preset directory',
+          invocation: { modelInvocable: true, userInvocable: true },
+        }]),
+      },
+    })
+
+    const response = await api.skills.list(request({ sessionId: SessionId('k1') }))
+
+    // A preset ships its own skill directory, so the catalog IS the
+    // session's; reading a host singleton would answer for the wrong one.
+    expect(response.result).toMatchObject({ ok: true, value: { skills: [{ name: 'preset-owned' }] } })
+    services.delete('k1')
+  })
+
+  it('says so when no composition mounts the capability at all', async () => {
+    const { api } = await harness(['standard'])
+    await api.sessions.create(request({ sessionId: SessionId('n1'), agentPreset: 'standard' }))
+
+    const response = await api.skills.list(request({ sessionId: SessionId('n1') }))
+
+    // Absent means absent — not "this session has none", which is what a
+    // root-realm read used to report for every presetd session.
+    expect(response.result.ok).toBe(false)
+    const failure = response.result as { ok: false; error: { message: string } }
+    expect(failure.error.message).toContain('neither this session')
+  })
+})
+
+describe('agentPreset.list', () => {
+  it('marks the default and carries each preset\'s trust', async () => {
+    const { api } = await harness(['standard', 'minimal'])
+
+    const response = await api.agentPresets.list(request({}))
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.presets).toEqual([
+      { id: 'standard', trust: 'system', isDefault: true },
+      { id: 'minimal', trust: 'system', isDefault: false },
+    ])
+    expect(response.result.value.authorable).toBe(true)
+  })
+
+  it('answers with an empty roster when the deployment composes no presets', async () => {
+    const { api } = await harness()
+
+    const response = await api.agentPresets.list(request({}))
+
+    // Composing no presets is a valid deployment, not an error: every session
+    // then shares the host composition and the browser offers no choice.
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.presets).toEqual([])
+    // Nothing to write to either, so a surface offering "new preset" knows to
+    // stay hidden rather than offering a button whose save always fails.
+    expect(response.result.value.authorable).toBe(false)
+  })
+})
+
+describe('agentPreset.select', () => {
+  it('recomposes a blank session', async () => {
+    const { api } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('sel-1'), agentPreset: 'standard' }))
+
+    const response = await api.agentPresets.select(
+      request({ sessionId: SessionId('sel-1'), agentPreset: 'minimal' }))
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.agentPreset).toBe('minimal')
+  })
+
+  it('records the switch in the log, and the list reads it back', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('sel-log'), agentPreset: 'standard' }))
+
+    await api.agentPresets.select(
+      request({ sessionId: SessionId('sel-log'), agentPreset: 'minimal' }))
+
+    // The header is written once at creation, so the switch lives in the log —
+    // this is what a restart replays and what every projection resolves from.
+    // Asserting only the RPC's echo would miss a switch that never persisted.
+    const session = ctx.sessions.get(SessionId('sel-log'))
+    if (session === undefined) throw new Error('unreachable')
+    expect(session.header.agentPreset).toBe('standard')
+    expect(resolveSessionPreset(session)).toBe('minimal')
+    const listed = await api.sessions.list(request({}))
+    if (!listed.result.ok) throw new Error('unreachable')
+    expect(listed.result.value.items.find(item => item.sessionId === 'sel-log')?.agentPreset)
+      .toBe('minimal')
+  })
+
+  it('frames the committed switch so clients can drop that session\'s catalogs', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('sel-frame'), agentPreset: 'standard' }))
+    // The host-stream opener reads the committed-workspace baseline; this
+    // spec owns preset identity, so the stub suffices (api-proxy-commands
+    // precedent).
+    ctx.provide('workspace', { list: () => [] } as never)
+    const abort = new AbortController()
+    const frames: HostFrame[] = []
+    const stream = api.events.host(request({}), abort.signal)
+    const consume = (async () => {
+      for await (const frame of stream) {
+        if (frame.payload.type === 'host/session-preset-changed') frames.push(frame.payload)
+      }
+    })()
+
+    await api.agentPresets.select(
+      request({ sessionId: SessionId('sel-frame'), agentPreset: 'minimal' }))
+    // The queue push rides the synchronous append, so one turn of the loop is
+    // enough to deliver it; closing the stream bounds the read either way.
+    await new Promise(resolve => setTimeout(resolve, 0))
+    abort.abort()
+    await consume
+
+    // Recomposing registers nothing, so this frame — not the registry-wide
+    // commands one — is what tells a client its cached catalogs are stale.
+    expect(frames).toEqual([
+      { type: 'host/session-preset-changed', sessionId: 'sel-frame', agentPreset: 'minimal' },
+    ])
+  })
+
+  it('serializes two concurrent selects on one session', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('sel-race'), agentPreset: 'standard' }))
+
+    // Both pass the blank check; unserialized, the second unmount finds no
+    // record because the first already removed it, and two compositions end up
+    // in one agent layer. The client's busy flag is not enforcement.
+    const [first, second] = await Promise.all([
+      api.agentPresets.select(request({ sessionId: SessionId('sel-race'), agentPreset: 'minimal' })),
+      api.agentPresets.select(request({ sessionId: SessionId('sel-race'), agentPreset: 'standard' })),
+    ])
+
+    expect(first.result.ok).toBe(true)
+    expect(second.result.ok).toBe(true)
+    const session = ctx.sessions.get(SessionId('sel-race'))
+    if (session === undefined) throw new Error('unreachable')
+    // One winner, and the log agrees with it: the last committed switch.
+    expect(resolveSessionPreset(session)).toBe('standard')
+  })
+
+  it('refuses once the conversation has started', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('sel-2'), agentPreset: 'standard' }))
+    // One turn is enough: the history from here on was produced under
+    // `standard`'s tools, and a swap would strand those tool calls.
+    ctx.sessions.get(SessionId('sel-2'))?.append('turn/start', { turn: 0 })
+
+    const response = await api.agentPresets.select(
+      request({ sessionId: SessionId('sel-2'), agentPreset: 'minimal' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-locked')
+  })
+
+  it('reports an unknown preset without disturbing the session', async () => {
+    const { api } = await harness(['standard'])
+    await api.sessions.create(request({ sessionId: SessionId('sel-3') }))
+
+    const response = await api.agentPresets.select(
+      request({ sessionId: SessionId('sel-3'), agentPreset: 'nope' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+
+  it('reports a deployment that composes no presets', async () => {
+    const { api } = await harness()
+    await api.sessions.create(request({ sessionId: SessionId('sel-4') }))
+
+    const response = await api.agentPresets.select(
+      request({ sessionId: SessionId('sel-4'), agentPreset: 'anything' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+})
+
+describe('authoring over the wire', () => {
+  it('reads a composition with its trust', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.read(request({ agentPreset: 'standard' }))
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    // The shipped set is readable: it is the known-good composition a copy
+    // starts from, and trust is what tells a surface to say so.
+    expect(response.result.value.trust).toBe('system')
+    expect(response.result.value.content).toContain('- id: x')
+  })
+
+  it('copies a preset under a new id', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.copy(
+      request({ from: 'standard', agentPreset: 'mine', name: '我的模式' }))
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.agentPreset).toBe('mine')
+  })
+
+  it('rejects a copy target that could escape the preset root', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.copy(request({ from: 'standard', agentPreset: '../escape' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-invalid')
+  })
+
+  it('rejects a copy target the roster already supplies', async () => {
+    const { api } = await harness(['standard', 'minimal'])
+
+    const response = await api.agentPresets.copy(request({ from: 'standard', agentPreset: 'minimal' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-invalid')
+    expect(response.result.error.message).toMatch(/already exists/)
+  })
+
+  it('rejects a copy whose source is unknown', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.copy(request({ from: 'never-existed', agentPreset: 'mine' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+
+  it('reports a deployment that composes no presets', async () => {
+    const { api } = await harness()
+
+    const response = await api.agentPresets.read(request({ agentPreset: 'anything' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+
+  it('reports an unknown id on delete rather than succeeding silently', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.remove(request({ agentPreset: 'never-existed' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+})
+
+describe('opening a preset directory', () => {
+  it('hands the resolved directory to the native opener', async () => {
+    const opened: string[] = []
+    const { api } = await harness(['standard', 'my-preset'], undefined, {
+      userIds: ['my-preset'],
+      defaults: { openPath: (path: string) => { opened.push(path); return Promise.resolve() } },
+    })
+
+    const response = await api.agentPresets.openDocument(
+      request({ agentPreset: 'my-preset' }), new AbortController().signal)
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value).toEqual({ opened: true })
+    // The id selected the directory; the browser supplied no path.
+    expect(opened).toEqual(['/presets/my-preset'])
+  })
+
+  it('answers the path as text where the deployment has no opener', async () => {
+    const { api } = await harness(['standard', 'my-preset'], undefined, {
+      userIds: ['my-preset'],
+      defaults: { canOpenPath: () => false },
+    })
+
+    const response = await api.agentPresets.openDocument(
+      request({ agentPreset: 'my-preset' }), new AbortController().signal)
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value).toEqual({ opened: false, path: '/presets/my-preset' })
+  })
+
+  it('refuses a preset that ships with the deployment', async () => {
+    const opened: string[] = []
+    const { api } = await harness(['standard'], undefined, {
+      defaults: { openPath: (path: string) => { opened.push(path); return Promise.resolve() } },
+    })
+
+    const response = await api.agentPresets.openDocument(
+      request({ agentPreset: 'standard' }), new AbortController().signal)
+
+    // Pointing an editor into the install invites edits an upgrade will
+    // silently overwrite; the refusal mirrors copy/remove.
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-read-only')
+    expect(opened).toEqual([])
+  })
+
+  it('reports the roster capability on list', async () => {
+    const openable = await harness(['standard'], undefined, {
+      defaults: { canOpenPath: () => true },
+    })
+    const headless = await harness(['standard'], undefined, {
+      defaults: { canOpenPath: () => false },
+    })
+
+    const yes = await openable.api.agentPresets.list(request({}))
+    const no = await headless.api.agentPresets.list(request({}))
+
+    expect(yes.result.ok && yes.result.value.hasDocument).toBe(true)
+    expect(no.result.ok && no.result.value.hasDocument).toBe(false)
+  })
+
+  it('counts an injected opener as openable', async () => {
+    const { api } = await harness(['standard'], undefined, {
+      defaults: { openPath: () => Promise.resolve() },
+    })
+
+    const response = await api.agentPresets.list(request({}))
+
+    expect(response.result.ok && response.result.value.hasDocument).toBe(true)
+  })
+})
+
+describe('skills over the layered host registry', () => {
+  it('passes the live agent as the view scope to the host registry', async () => {
+    const { api, ctx } = await harness(['standard'])
+    const seen: unknown[] = []
+    ctx.provide('skills', {
+      list: (options: { scope?: unknown }) => {
+        seen.push(options.scope)
+        return Promise.resolve([])
+      },
+    } as never)
+    await api.sessions.create(request({ sessionId: SessionId('h1'), agentPreset: 'standard' }))
+
+    const response = await api.skills.list(request({ sessionId: SessionId('h1') }))
+
+    expect(response.result).toMatchObject({ ok: true, value: { skills: [] } })
+    expect(seen).toEqual([ctx.agents.get(SessionId('h1'))])
+  })
+
+  it('resolves a cold session to its recorded preset standing key', async () => {
+    const { api, ctx } = await harness(['standard', 'minimal'])
+    const seen: unknown[] = []
+    ctx.provide('skills', {
+      list: (options: { scope?: unknown }) => {
+        seen.push(options.scope)
+        return Promise.resolve([])
+      },
+    } as never)
+    ctx.sessions.create(SessionId('h2'), { meta: { cwd: '/workspace/cold', agentPreset: 'minimal' } })
+
+    const response = await api.skills.list(request({ sessionId: SessionId('h2') }))
+
+    expect(response.result).toMatchObject({ ok: true, value: { skills: [] } })
+    expect(seen).toEqual([standingKeys.get('minimal')])
+  })
+
+  it('serves the global view when the roster no longer supplies the recorded preset', async () => {
+    const { api, ctx } = await harness(['standard'])
+    const seen: unknown[] = []
+    ctx.provide('skills', {
+      list: (options: { scope?: unknown }) => {
+        seen.push(options.scope)
+        return Promise.resolve([])
+      },
+    } as never)
+    ctx.sessions.create(SessionId('h3'), { meta: { cwd: '/workspace/cold', agentPreset: 'gone' } })
+
+    const response = await api.skills.list(request({ sessionId: SessionId('h3') }))
+
+    expect(response.result).toMatchObject({ ok: true, value: { skills: [] } })
+    expect(seen).toEqual([undefined])
+  })
+})
+
+describe('session.history presenter scope', () => {
+  it('asks the roster for the RECORDED preset\'s standing key on a cold read', async () => {
+    const { api } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('p1'), agentPreset: 'minimal' }))
+    // Cold: creation registered a live agent in this harness, so simulate the
+    // cold path by asking for a session only persistence knows... the harness
+    // has no persistence, so read the live one and assert no roster query.
+    standingKeyRequests.length = 0
+    const live = await api.sessions.history(request({ sessionId: SessionId('p1') }))
+    expect(live.result.ok).toBe(true)
+    // A live agent IS the presenter scope; the roster is not consulted.
+    expect(standingKeyRequests).toEqual([])
+  })
+
+  it('resolves a switched session from the LOG, not its creation header', async () => {
+    // The header is a creation fact; a switch while blank is a logged event,
+    // and every turn after it ran under the newer composition. Reading the
+    // header would render that history through the older preset's layer,
+    // where the tools it is made of have no presenter at all.
+    const meta = { id: SessionId('p4'), createdAt: 1, cwd: '/tmp/p4', agentPreset: 'standard' }
+    const { api } = await harness(['standard', 'minimal'], {
+      list: () => Promise.resolve([meta]),
+      inspect: () => Promise.resolve({
+        meta,
+        events: [{ type: 'agent-preset/selected', seq: 1, time: 0, data: { agentPreset: 'minimal' } }],
+      }),
+    })
+
+    standingKeyRequests.length = 0
+    const response = await api.sessions.history(request({ sessionId: SessionId('p4') }))
+
+    expect(response.result.ok).toBe(true)
+    expect(standingKeyRequests).toEqual(['minimal'])
+  })
+
+  it('serves a COLD transcript whose standing mount is no longer usable', async () => {
+    // A genuinely cold session: persistence knows it, no live agent exists.
+    const meta = { id: SessionId('p3'), createdAt: 1, cwd: '/tmp/p3', agentPreset: 'standard' }
+    const { api } = await harness(['standard'], {
+      list: () => Promise.resolve([meta]),
+      inspect: () => Promise.resolve({ meta, events: [] }),
+    })
+    // The preset broke after the session ran: the roster rejects the mount.
+    failingStandingKeys.add('standard')
+    try {
+      standingKeyRequests.length = 0
+      const response = await api.sessions.history(request({ sessionId: SessionId('p3') }))
+      // Degraded, never failed: the roster WAS asked, and the transcript
+      // still serves — with the generic cards a viewless entry renders.
+      expect(standingKeyRequests).toEqual(['standard'])
+      expect(response.result.ok).toBe(true)
+    } finally {
+      failingStandingKeys.delete('standard')
+    }
+  })
+})

packages/host/apiproxy/tests/api-proxy-approval.spec.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
@@ -27,7 +27,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(ApprovalService)
-  const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
   return { ctx, api }
 }
 
@@ -217,7 +217,7 @@ describe('approval pending registry', () => {
     await ctx.plugin(ApprovalService)
     let api!: ApiProxy
     const fiber = ctx.plugin(Object.assign((fiberCtx: Context) => {
-      api = createApiProxy(fiberCtx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+      api = createApiProxy(fiberCtx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     }, { inject: ['sessions', 'agents', 'userInteraction', 'approval'] }))
     await fiber.await()
     const abort = new AbortController()

packages/host/apiproxy/tests/api-proxy-blank.spec.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
@@ -35,7 +35,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy; attach: (sessio
   await ctx.plugin(AgentRegistry)
   return {
     ctx,
-    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' }),
     attach: (session) => {
       ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     },

packages/host/apiproxy/tests/api-proxy-cold.spec.ts

@@ -8,7 +8,7 @@ import { mkdtempSync, writeFileSync, utimesSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
@@ -64,7 +64,7 @@ describe('sessions.list cold merge', () => {
         return undefined
       },
     })
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const response = await api.sessions.list(request({}))
     expect(response.result.ok).toBe(true)
@@ -92,7 +92,7 @@ describe('attached updatedAt excludes end-seed', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(UserInteractionService)
     await ctx.plugin(AgentRegistry)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     // Old work, resumed just now: the log tail would report the pickup.
     const worked = 1_000_000
@@ -150,7 +150,7 @@ describe('cold history recovery view', () => {
       inspect: (id: SessionId, signal?: AbortSignal) => coordinator.inspect(id, signal),
       locate: () => undefined,
     } as never)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId, beforeSeq: 2, maxMessages: 10 }))
     if (!history.result.ok) throw new Error('history failed')
@@ -206,7 +206,7 @@ describe('Remote Agent and Session lookup policy', () => {
     })
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -250,7 +250,7 @@ describe('Remote Agent and Session lookup policy', () => {
     const resume = vi.spyOn(ctx.agents, 'resume')
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -312,7 +312,7 @@ describe('subagent ownership fence', () => {
       locate: () => undefined,
     } as never)
     const resume = vi.spyOn(ctx.agents, 'resume')
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId }))
     expect(history.result.ok).toBe(true)
@@ -371,7 +371,7 @@ describe('subagent ownership fence', () => {
     // answering `agent-busy`.
     const resume = vi.spyOn(ctx.agents, 'resume')
       .mockRejectedValue(new Error('registry unavailable in this bench'))
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const prompt = await api.sessions.prompt(request({
       sessionId,
@@ -412,7 +412,7 @@ describe('subagent ownership fence', () => {
     })
     const startingChild = { id: startingSession.id, session: startingSession, status: 'idle', ctx } as Agent
     ctx.agents.enter(startingChild, parent)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const stopped = await api.sessions.cancel(request({ sessionId: originChild.id }))
     expect(stopped.result.ok).toBe(false)
@@ -458,7 +458,7 @@ describe('subagent ownership fence', () => {
     const followup = vi.fn()
     const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
     ctx.agents.register(agent)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const response = await api.sessions.prompt(request({
       sessionId: agent.id,
@@ -481,7 +481,6 @@ describe('subagent ownership fence', () => {
     const api = createApiProxy(ctx, {
       defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
       cwd: '/tmp',
-      workspaceRoot: '/tmp',
     })
 
     const alias = 'US/Pacific'
@@ -551,7 +550,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const listed = await api.sessions.list(request({}))
     expect(listed.result.ok).toBe(true)
@@ -576,7 +575,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
       list: () => Promise.resolve([]),
       inspect,
     } as never)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const response = await api.sessions.history(request({ sessionId: sid('session-missing') }))
     expect(response.result.ok).toBe(false)
@@ -602,7 +601,7 @@ describe('sessions.prompt synchronous rejection', () => {
       followup: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
       steer: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
     } as unknown as Agent)
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     for (const mode of ['queue', 'steer'] as const) {
       const response = await api.sessions.prompt(request({
@@ -646,7 +645,7 @@ describe('sessions.prompt synchronous rejection', () => {
       ctx.agents.register(child)
       throw new Error('session id already published')
     })
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
     const models = await api.sessions.models(request({ sessionId }))
     expect(models.result.ok).toBe(false)

packages/host/apiproxy/tests/api-proxy-commands.spec.ts

@@ -10,7 +10,7 @@ import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm'
  */
 
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
@@ -25,7 +25,7 @@ import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
 import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' }
 
 function request<P>(payload: P): RpcRequest<P> {
   return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }

packages/host/apiproxy/tests/api-proxy-config.spec.ts

@@ -6,8 +6,8 @@
  */
 
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
-import z from 'schemastery'
+import { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -25,7 +25,7 @@ import { RpcId } from '../src/api/rpc.ts'
 import { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-default-model'
 import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' }
 
 let nextRpc = 1
 function request<P>(payload: P): RpcRequest<P> {
@@ -309,8 +309,8 @@ describe('settings domain', () => {
     // The settings seam is general: any plugin may register a namespace for
     // its own configuration. The Web configuration plane remains opt-in, so a
     // future internal plugin cannot become remotely configurable just by
-    // registering; permission and the product onboarding namespace are the
-    // non-model namespaces intentionally admitted by this surface.
+    // registering; locale, permission, conversation, theme, and the product
+    // onboarding namespace are intentionally admitted by this surface.
     const ctx = await harness()
     ctx.settings.register(NS, AdapterConfig)
     ctx.settings.register(settingsNamespace('some-other-plugin'), z.object({ secretPath: z.string() }))
@@ -319,15 +319,41 @@ describe('settings domain', () => {
     }), {
       base: { defaultPreset: 'read-only' },
     })
+    ctx.settings.register(settingsNamespace('ui-theme'), z.object({
+      preference: z.union(['light', 'dark', 'system']).default('system'),
+    }))
+    ctx.settings.register(settingsNamespace('locale'), z.object({
+      preference: z.union(['zh', 'en']).required(false),
+    }))
+    ctx.settings.register(settingsNamespace('ui-conversation'), z.object({
+      busyEnter: z.union(['queue', 'steer']).default('queue'),
+    }))
     const api = createApiProxy(ctx, DEFAULTS)
 
     const value = expectOk(await api.settings.describe(request({})))
-    expect(value.namespaces.map(view => view.ns)).toEqual(['llm-deepseek', 'permission'])
+    expect(value.namespaces.map(view => view.ns)).toEqual([
+      'llm-deepseek', 'permission', 'ui-theme', 'locale', 'ui-conversation',
+    ])
     const permission = expectOk(await api.settings.mutate(request({
       ns: 'permission',
       ops: [{ op: 'set', path: ['defaultPreset'], value: 'workspace-write' }],
     })))
     expect(permission.value).toEqual({ defaultPreset: 'workspace-write' })
+    const theme = expectOk(await api.settings.mutate(request({
+      ns: 'ui-theme',
+      ops: [{ op: 'set', path: ['preference'], value: 'dark' }],
+    })))
+    expect(theme.value).toEqual({ preference: 'dark' })
+    const locale = expectOk(await api.settings.mutate(request({
+      ns: 'locale',
+      ops: [{ op: 'set', path: ['preference'], value: 'en' }],
+    })))
+    expect(locale.value).toEqual({ preference: 'en' })
+    const conversation = expectOk(await api.settings.mutate(request({
+      ns: 'ui-conversation',
+      ops: [{ op: 'set', path: ['busyEnter'], value: 'steer' }],
+    })))
+    expect(conversation.value).toEqual({ busyEnter: 'steer' })
 
     for (const response of [
       await api.settings.update(request({ ns: 'some-other-plugin', patch: { secretPath: '/etc/shadow' } })),
@@ -341,19 +367,44 @@ describe('settings domain', () => {
     expect(ctx.settings.describe().find(d => String(d.ns) === 'some-other-plugin')?.value).toEqual({})
   })
 
-  it('serves the product onboarding namespace without invalidating the model catalog', async () => {
+  it('serves product preference namespaces without invalidating the model catalog', async () => {
     const ctx = await harness()
     ctx.settings.register(settingsNamespace('ui-onboarding'), z.object({ welcomeNoticeVersion: z.string() }))
+    ctx.settings.register(settingsNamespace('ui-theme'), z.object({
+      preference: z.union(['light', 'dark', 'system']).default('system'),
+    }))
     const api = createApiProxy(ctx, DEFAULTS)
     expect(expectOk(await api.settings.describe(request({}))).namespaces.map(view => view.ns))
-      .toEqual(['ui-onboarding'])
-    const frames = await collectHost(api, ['host/settings-changed'], 1, async () => {
+      .toEqual(['ui-onboarding', 'ui-theme'])
+    const frames = await collectHost(api, ['host/settings-changed'], 2, async () => {
       expectOk(await api.settings.mutate(request({
         ns: 'ui-onboarding',
         ops: [{ op: 'set', path: ['welcomeNoticeVersion'], value: 'v1' }],
       })))
+      expectOk(await api.settings.mutate(request({
+        ns: 'ui-theme',
+        ops: [{ op: 'set', path: ['preference'], value: 'dark' }],
+      })))
     })
-    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'ui-onboarding' }])
+    expect(frames).toEqual([
+      { type: 'host/settings-changed', ns: 'ui-onboarding' },
+      { type: 'host/settings-changed', ns: 'ui-theme' },
+    ])
+  })
+
+  it('serves the agent-preset namespace, so a browser preset picker can persist its choice', async () => {
+    const ctx = await harness()
+    ctx.settings.register(settingsNamespace('agent-presets'), z.object({ default: z.string() }))
+    const api = createApiProxy(ctx, DEFAULTS)
+
+    expectOk(await api.settings.update(request({ ns: 'agent-presets', patch: { default: 'minimal' } })))
+
+    // Both browser surfaces that offer the choice — the General row and the
+    // management section — write the default through `settings.update`, so a
+    // namespace outside this boundary makes the picker move and then silently
+    // forget, which is worse than refusing the control.
+    expect(ctx.settings.describe().find(view => String(view.ns) === 'agent-presets')?.value)
+      .toEqual({ default: 'minimal' })
   })
 
   it('refuses even a model-provider namespace once its directory entry is gone', async () => {

packages/host/apiproxy/tests/api-proxy-fork.spec.ts

@@ -1,7 +1,7 @@
 /** Session-fork boundaries, lineage, and inherited model routing. */
 
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
@@ -84,7 +84,6 @@ function liveAgent(
 const api = (ctx: Context) => createApiProxy(ctx, {
   defaultModelSelection: () => ({ provider: 'default-provider', model: 'default-model' }),
   cwd: '/tmp',
-  workspaceRoot: '/tmp',
 })
 
 describe('sessions.fork', () => {

packages/host/apiproxy/tests/api-proxy-models.spec.ts

@@ -5,14 +5,15 @@
  * boundary for a running selection change.
  */
 
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import LlmService, { LlmAdapter, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type {
   GenerateOptions, LlmCallConfig, LlmModelInfo, LlmModelReasoningInfo, LlmProviderInfo,
   LlmResolvedModelInfo, StreamChunk,
+  UserMessage,
 } from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
 import type { SessionId } from '@deepseek-ai/dsh-session'
@@ -108,7 +109,8 @@ async function harness(logged?: {
     session,
     status: 'running',
     ctx,
-  } as Agent
+    inbox: { nextTurn: [], nextStep: [] },
+  } as unknown as Agent
   ctx.agents.register(agent)
   return { ctx, agent, sessionId: session.id }
 }
@@ -118,14 +120,161 @@ function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false
   return response.result.value
 }
 
+function registerTextOnly(ctx: Context): void {
+  ctx.llm.registerAdapter(['text-only'], new class extends CatalogAdapter {
+    override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+      return Promise.resolve({ provider, id: model, name: model, inputModalities: ['text'] })
+    }
+  }('Text Only', []))
+}
+
 describe('Web session model selection', () => {
+  it('validates an ordered image batch before persisting any member', async () => {
+    const { ctx, agent, sessionId } = await harness()
+    const validateImage = vi.fn((_input: { data: Uint8Array }) => Promise.resolve())
+    const saveImage = vi.fn((input: { data: Uint8Array; mediaType: 'image/png'; name?: string }) => Promise.resolve({
+      attachmentId: `att-${String(input.data[0])}`,
+      mediaType: input.mediaType,
+      bytes: input.data.byteLength,
+      width: 1,
+      height: 1,
+      ...input.name === undefined ? {} : { name: input.name },
+    }))
+    ctx.provide('attachments', {
+      imageLimits: {
+        maxImageBytes: 4,
+        maxImagesPerMessage: 2,
+        maxMessageImageBytes: 4,
+        maxImagePixels: 4,
+        mediaTypes: ['image/png'],
+      },
+      validateImage,
+      saveImage,
+    } as never)
+    const followup = vi.fn()
+    Object.assign(agent, { followup })
+    const api = createApiProxy(ctx, {
+      defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      cwd: '/tmp',
+    })
+
+    const result = await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: [
+        { type: 'image' as const, mediaType: 'image/png' as const, data: 'AQ==', name: 'first.png' },
+        { type: 'text' as const, text: 'compare' },
+        { type: 'image' as const, mediaType: 'image/png' as const, data: 'Ag==' },
+      ],
+    }))
+    expect(result.result.ok).toBe(true)
+    expect(validateImage.mock.calls.map(([input]) => [...input.data])).toEqual([[1], [2]])
+    expect(saveImage.mock.calls.map(([input]) => [...input.data])).toEqual([[1], [2]])
+    expect((followup.mock.calls[0]?.[0] as UserMessage).content).toEqual([
+      {
+        type: 'image',
+        attachment: {
+          attachmentId: 'att-1', mediaType: 'image/png', bytes: 1, width: 1, height: 1, name: 'first.png',
+        },
+      },
+      { type: 'text', text: 'compare' },
+      { type: 'image', attachment: { attachmentId: 'att-2', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } },
+    ])
+
+    const denied = await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: Array.from({ length: 3 }, () => ({
+        type: 'image' as const, mediaType: 'image/png' as const, data: 'AQ==',
+      })),
+    }))
+    expect(denied.result).toMatchObject({
+      ok: false,
+      error: { code: 'attachment-error', details: { reason: 'TOO_MANY_IMAGES' } },
+    })
+    expect(saveImage).toHaveBeenCalledTimes(2)
+    await ctx.fiber.dispose()
+  })
+
+  it('refuses a text-only selection while durable or pending image content remains visible', async () => {
+    const { ctx, agent, sessionId } = await harness()
+    registerTextOnly(ctx)
+    const api = createApiProxy(ctx, {
+      defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      cwd: '/tmp',
+    })
+    const image = {
+      type: 'image' as const,
+      attachment: { attachmentId: 'att-history', mediaType: 'image/png' as const, bytes: 1, width: 1, height: 1 },
+    }
+    agent.session.append('user/message', {
+      id: 'image-message', role: 'user', source: { kind: 'user' }, content: [image],
+    } as never, { surfaceOp: 'append' })
+    expect((await api.sessions.selectModel(request({
+      sessionId, provider: 'text-only', model: 'plain',
+    }))).result).toMatchObject({ ok: false, error: { code: 'model-unavailable' } })
+
+    agent.session.append('user/message', {
+      id: 'summary', role: 'user', source: { kind: 'plugin', plugin: 'compact' },
+      content: [{ type: 'text', text: 'image summarized' }],
+    } as never, {
+      surfaceOp: { op: 'replace', start: 0, end: agent.session.events.length - 1 },
+      sourceEventSeqs: agent.session.events.map(event => event.seq),
+    })
+    ;(agent.inbox.nextTurn as UserMessage[]).push({
+      id: 'pending-image', role: 'user', source: { kind: 'user' }, content: [image],
+    } as never)
+    expect((await api.sessions.selectModel(request({
+      sessionId, provider: 'text-only', model: 'plain',
+    }))).result.ok).toBe(false)
+    ;(agent.inbox.nextTurn as UserMessage[]).length = 0
+    expect(expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'text-only', model: 'plain',
+    }))).selected).toEqual({ provider: 'text-only', model: 'plain' })
+    await ctx.fiber.dispose()
+  })
+
+  it('authorizes attachment bytes only when the session event stream references the id', async () => {
+    const { ctx, agent, sessionId } = await harness()
+    const ref = {
+      attachmentId: 'att-authorized', mediaType: 'image/png' as const, bytes: 2, width: 1, height: 1,
+    }
+    const readImage = vi.fn(() => Promise.resolve({ ref, data: Uint8Array.of(1, 2) }))
+    ctx.provide('attachments', { readImage } as never)
+    const api = createApiProxy(ctx, {
+      defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      cwd: '/tmp',
+    })
+    agent.session.append('agent/inbox/spliced', {
+      target: 'next-turn',
+      start: 0,
+      inserted: [{
+        id: 'queued-image', role: 'user', source: { kind: 'user' },
+        content: [{ type: 'image', attachment: ref }],
+      }],
+    } as never)
+
+    const allowed = await api.sessions.attachment(request({
+      sessionId, attachmentId: 'att-authorized' as never,
+    }))
+    expect(allowed.result).toMatchObject({ ok: true, value: { attachment: ref, data: 'AQI=' } })
+    const denied = await api.sessions.attachment(request({
+      sessionId, attachmentId: 'att-other' as never,
+    }))
+    expect(denied.result).toMatchObject({
+      ok: false,
+      error: { code: 'attachment-error', details: { reason: 'ATTACHMENT_NOT_REFERENCED' } },
+    })
+    expect(readImage).toHaveBeenCalledOnce()
+    await ctx.fiber.dispose()
+  })
   it('groups successful providers and leaves an unlisted current selection out of the catalog', async () => {
     const { ctx, sessionId } = await harness({
       provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: ReasoningEffortId('max'),
     })
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp' })
 
     const catalog = expectValue(await api.sessions.models(request({ sessionId })))
     expect(catalog.current).toEqual({
@@ -160,7 +309,7 @@ describe('Web session model selection', () => {
 
   it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
     const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp' })
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
 
@@ -232,7 +381,6 @@ describe('Web session model selection', () => {
     const api = createApiProxy(ctx, {
       defaultModelSelection: () => stored,
       cwd: '/tmp',
-      workspaceRoot: '/tmp',
     })
 
     expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
@@ -257,7 +405,6 @@ describe('Web session model selection', () => {
     const api = createApiProxy(ctx, {
       defaultModelSelection: () => stored,
       cwd: '/tmp',
-      workspaceRoot: '/tmp',
     })
 
     stored = { provider: 'duplicate', model: 'same' }
@@ -277,7 +424,6 @@ describe('Web session model selection', () => {
         return reject ? Promise.reject(new Error('read-only document')) : Promise.resolve()
       },
       cwd: '/tmp',
-      workspaceRoot: '/tmp',
     })
 
     expectValue(await api.sessions.selectModel(request({
@@ -308,7 +454,6 @@ describe('Web session model selection', () => {
     const api = createApiProxy(ctx, {
       defaultModelSelection: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
       cwd: '/tmp',
-      workspaceRoot: '/tmp',
     })
 
     // The client disabling its input is an affordance; this method stays
@@ -341,7 +486,6 @@ describe('Web session model selection', () => {
       // names the route the user last picked, and nothing serves it.
       defaultModelSelection: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
       cwd: '/tmp',
-      workspaceRoot: '/tmp',
     })
 
     const catalog = expectValue(await api.sessions.models(request({ sessionId })))

packages/host/apiproxy/tests/api-proxy-projections.spec.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import { z } from 'zod'
 import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -68,7 +68,7 @@ function seedMessages(session: Session, count: number): void {
   }
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
 describe('session.history projections block', () => {
   it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {

packages/host/apiproxy/tests/api-proxy-question.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -14,7 +14,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   return {
     ctx,
-    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' }),
   }
 }
 

packages/host/apiproxy/tests/api-proxy-rename.spec.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
@@ -68,7 +68,7 @@ function liveAgent(ctx: Context, id: string, turns: number): Session {
   return session
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
 
 describe('sessions.rename', () => {
   it('accepts through the composed title service: normalized user-source event, echoed seq', async () => {

packages/host/apiproxy/tests/api-proxy-search.spec.ts

@@ -5,7 +5,7 @@
  */
 
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import { stat } from 'node:fs/promises'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
@@ -27,7 +27,7 @@ vi.mock('node:fs/promises', async (importOriginal) => {
 })
 
 const sid = (value: string): SessionId => value as SessionId
-const defaults = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const defaults = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' }
 
 function request(query: string): RpcRequest<{ query: string }> {
   return { rpcId: RpcId(`search-${query}`), payload: { query } }

packages/host/apiproxy/tests/api-proxy-subagents.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import { SubagentError } from '@deepseek-ai/dsh-subagent'
 import { RpcId } from '../src/api/rpc.ts'
@@ -98,7 +98,7 @@ function bench(options: {
   ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
-    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp',
   })
   return { api, getAgent, listChildren, inspect, snapshot, restore, followup, interrupt, parent }
 }

packages/host/apiproxy/tests/api-proxy-tasks.spec.ts

@@ -0,0 +1,263 @@
+/**
+ * Background-task carrier paths of the host ApiProxy: the subscription
+ * baseline is sent only for a session that has tasks, every registry change
+ * pushes that owner's whole set, an unowned change fans out to every
+ * subscribed session, the projection drops the three internal snapshot
+ * fields, a composition without `ctx.tasks` emits nothing, and listing never
+ * resumes a cold session.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
+import type { TaskOutcome } from '@deepseek-ai/dsh-tasks'
+import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+type TaskFrame = Extract<MuxFrame, { type: 'session/tasks' }>
+
+/**
+ * A producer whose settlement the test drives. `cancel` deliberately does not
+ * settle, so a kill is observable as the distinct `stopping` step before the
+ * test supplies the terminal outcome and its detail.
+ */
+function producer(label = 'sleep 60') {
+  let settle!: (outcome: TaskOutcome) => void
+  // A stream producer, so the carrier CAN consume the cursor if it ever calls
+  // `read()`; `reads` is what proves it never does.
+  const reads = { count: 0 }
+  const spec = {
+    kind: 'bash' as const,
+    label,
+    run: () => ({
+      cancel: () => {},
+      done: new Promise<TaskOutcome>((resolve) => { settle = resolve }),
+      readOutput: () => { reads.count += 1; return 'stolen output' },
+    }),
+  }
+  return { spec, reads, settle: (outcome: TaskOutcome) => { settle(outcome) } }
+}
+
+async function harness(withRegistry: boolean): Promise<{ ctx: Context; session: Session; agent: Agent }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  if (withRegistry) {
+    await ctx.plugin(LocalTaskService)
+    ctx.tasks.attachController('api-proxy-test')
+  }
+  const session = ctx.sessions.create()
+  const agent = {
+    id: session.id,
+    session,
+    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle',
+    ctx,
+  } as Agent
+  ctx.agents.register(agent)
+  return { ctx, session, agent }
+}
+
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
+
+/** Drain the mux until `count` session/tasks frames arrived, then abort. */
+async function collect(
+  iterable: AsyncIterable<RpcRequest<MuxFrame>>,
+  count: number,
+  abort: AbortController,
+): Promise<TaskFrame[]> {
+  const frames: MuxFrame[] = []
+  for await (const envelope of iterable) {
+    frames.push(envelope.payload)
+    if (frames.filter(frame => frame.type === 'session/tasks').length >= count) abort.abort()
+  }
+  return frames.filter((frame): frame is TaskFrame => frame.type === 'session/tasks')
+}
+
+describe('session/tasks subscription baseline', () => {
+  it('is omitted for a session with no tasks — absence is the empty set', async () => {
+    const { ctx, session } = await harness(true)
+    const abort = new AbortController()
+    const stream = api(ctx).events.mux({ rpcId: RpcId('t-tasks-empty'), payload: {} }, abort.signal)
+    const frames: MuxFrame[] = []
+    const drained = (async () => {
+      for await (const envelope of stream) {
+        frames.push(envelope.payload)
+        if (frames.some(frame => frame.type === 'session/subscribed')) abort.abort()
+      }
+    })()
+    await drained
+    expect(frames.some(frame => frame.type === 'session/tasks')).toBe(false)
+    expect(frames.some(frame => frame.type === 'session/subscribed')).toBe(true)
+    void session
+  })
+
+  it('carries the live set for a session that already has tasks when the stream opens', async () => {
+    const { ctx, session, agent } = await harness(true)
+    ctx.tasks.start({ ...producer('pnpm run build').spec, owner: agent })
+    const abort = new AbortController()
+    const stream = api(ctx).events.mux({ rpcId: RpcId('t-tasks-baseline'), payload: {} }, abort.signal)
+    const [baseline] = await collect(stream, 1, abort)
+    expect(baseline?.sessionId).toBe(session.id)
+    expect(baseline?.tasks).toHaveLength(1)
+    const [task] = baseline?.tasks ?? []
+    expect(task?.startedAt).toBeTypeOf('number')
+    expect({ ...task, startedAt: 0 }).toEqual({
+      id: 'bash-1',
+      kind: 'bash',
+      label: 'pnpm run build',
+      status: 'running',
+      startedAt: 0,
+    })
+  })
+})
+
+describe('session/tasks change pushes', () => {
+  it('pushes the owner\'s whole set on registration, stopping, and settlement', async () => {
+    const { ctx, session, agent } = await harness(true)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-changes'), payload: {} }, abort.signal)
+    const collected = collect(stream, 3, abort)
+
+    const p = producer()
+    const id = ctx.tasks.start({ ...p.spec, owner: agent })
+    ctx.tasks.kill(id, agent, 'test')
+    p.settle({ status: 'killed', detail: 'signal: SIGTERM' })
+
+    const frames = await collected
+    expect(frames.map(frame => frame.sessionId)).toEqual([session.id, session.id, session.id])
+    expect(frames.map(frame => frame.tasks[0]?.status)).toEqual(['running', 'stopping', 'killed'])
+    // Terminal detail rides the same whole-set push; no separate signal.
+    expect(frames[2]?.tasks[0]?.detail).toBe('signal: SIGTERM')
+    expect(frames[2]?.tasks[0]?.finishedAt).toBeTypeOf('number')
+  })
+
+  it('drops ownerSession, reported, and outputLimitBytes from the wire view', async () => {
+    const { ctx, agent } = await harness(true)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-fields'), payload: {} }, abort.signal)
+    const collected = collect(stream, 1, abort)
+    ctx.tasks.start({ ...producer().spec, owner: agent, outputLimitBytes: 1_024 })
+
+    const [frame] = await collected
+    const fields: readonly string[] = Object.keys(frame?.tasks[0] ?? {})
+    expect([...fields].sort()).toEqual(['id', 'kind', 'label', 'startedAt', 'status'])
+  })
+
+  it('fans an unowned change out to every subscribed session', async () => {
+    const { ctx } = await harness(true)
+    const second = ctx.sessions.create()
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-unowned'), payload: {} }, abort.signal)
+    const collected = collect(stream, 2, abort)
+
+    ctx.tasks.start(producer('open to every caller').spec)
+
+    const frames = await collected
+    expect(new Set(frames.map(frame => frame.sessionId)).size).toBe(2)
+    expect(frames.some(frame => frame.sessionId === second.id)).toBe(true)
+    for (const frame of frames) expect(frame.tasks[0]?.label).toBe('open to every caller')
+  })
+
+  it('serves a cold session the unowned set without resuming it', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-tasks')
+    let loaded = false
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+      load: () => { loaded = true; throw new Error('task listing must not load a cold log') },
+    } as never)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-cold'), payload: {} }, abort.signal)
+    const collected = collect(stream, 1, abort)
+
+    ctx.tasks.start(producer().spec)
+    await collected
+    expect(loaded).toBe(false)
+    expect(ctx.agents.get(coldId)).toBeUndefined()
+  })
+})
+
+describe('session/tasks without the registry', () => {
+  it('emits no frames at all, so the client renders no entry point', async () => {
+    const { ctx, session } = await harness(false)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-absent'), payload: {} }, abort.signal)
+    const frames: MuxFrame[] = []
+    const drained = (async () => {
+      for await (const envelope of stream) {
+        frames.push(envelope.payload)
+        if (frames.filter(frame => frame.type === 'session/event').length >= 1) abort.abort()
+      }
+    })()
+    session.append('turn/start', { turn: 1 })
+    await drained
+    expect(frames.some(frame => frame.type === 'session/tasks')).toBe(false)
+  })
+})
+
+describe('session/tasks never consumes model output', () => {
+  it('drives the whole lifecycle without calling the single consuming cursor', async () => {
+    // `ctx.tasks.read()` consumes the one output cursor, so a carrier read
+    // silently takes bytes the model's `task_output` will never see. The
+    // failure is invisible at the call site, which is why this asserts the
+    // count rather than trusting review.
+    const { ctx, agent } = await harness(true)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-no-read'), payload: {} }, abort.signal)
+    const collected = collect(stream, 3, abort)
+
+    const p = producer()
+    const id = ctx.tasks.start({ ...p.spec, owner: agent })
+    ctx.tasks.kill(id, agent, 'test')
+    p.settle({ status: 'killed', detail: 'signal: SIGTERM' })
+    await collected
+
+    expect(p.reads.count).toBe(0)
+  })
+
+  it('reads nothing while minting the subscription baseline either', async () => {
+    const { ctx, agent } = await harness(true)
+    const p = producer()
+    ctx.tasks.start({ ...p.spec, owner: agent })
+
+    const abort = new AbortController()
+    const stream = api(ctx).events.mux({ rpcId: RpcId('t-tasks-no-read-baseline'), payload: {} }, abort.signal)
+    const [baseline] = await collect(stream, 1, abort)
+
+    expect(baseline?.tasks).toHaveLength(1)
+    expect(p.reads.count).toBe(0)
+  })
+})
+
+describe('session/tasks baseline for a session born after the stream opened', () => {
+  it('carries the already-visible unowned set to the new session', async () => {
+    const { ctx } = await harness(true)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-tasks-late-session'), payload: {} }, abort.signal)
+
+    // One unowned task exists before the new session is created; the subscribe
+    // frame clears the client mirror, so the baseline has to follow it.
+    ctx.tasks.start(producer('visible to every caller').spec)
+    const created = ctx.sessions.create()
+
+    const frames = await collect(stream, 2, abort)
+    const forNew = frames.filter(frame => frame.sessionId === created.id)
+    expect(forNew.at(-1)?.tasks[0]?.label).toBe('visible to every caller')
+  })
+})

packages/host/apiproxy/tests/api-proxy-view.spec.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
@@ -105,7 +105,7 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 describe('mux live view computation', () => {
   it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
     const collected = collect(stream, 9, abort)
@@ -170,7 +170,7 @@ describe('mux live view computation', () => {
 
   it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     const session = ctx.sessions.create()
     // history resolves the agent first; a live structural stub is enough (only
     // .session is read on this path).
@@ -238,7 +238,7 @@ describe('mux live view computation', () => {
 
   it('counts only append-origin messages toward maxMessages and keeps each compaction summary with its replacement', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     const session = ctx.sessions.create()
     ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     session.append('turn/start', { turn: 1 })
@@ -287,7 +287,7 @@ describe('mux live view computation', () => {
 
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
 
@@ -308,7 +308,7 @@ describe('mux live view computation', () => {
 
   it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
     const collected = collect(stream, 4, abort)

packages/host/apiproxy/tests/api-proxy-workspace.spec.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, realpathSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentFactory } from '@deepseek-ai/dsh-agent'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
@@ -59,7 +59,7 @@ function stubAgent(session: Session): Agent {
 
 /** Compose the API over real Session, Agent, Storage, Domain, and Workspace services. */
 async function harness(
-  workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
+  root = realpathSync.native(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
   picker: DirectoryPickerCapability = { kind: 'native', pick: async () => null },
   extras: { openPath?: (path: string, signal: AbortSignal) => Promise<void> } = {},
 ) {
@@ -101,11 +101,17 @@ async function harness(
   ctx.provide('directoryPicker', { capability: () => picker } as never)
   const api = createApiProxy(ctx, {
     defaultModelSelection: () => ({ provider: 'test', model: 'test-model' }),
-    cwd: workspaceRoot,
-    workspaceRoot,
+    cwd: root,
     ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
   })
-  return { api, ctx, storageDomain, workspaceRoot }
+  return { api, ctx, storageDomain, root }
+}
+
+/** Stage one directory under the harness root for path adoption. */
+function stageDir(root: string, name: string): string {
+  const path = join(root, name)
+  mkdirSync(path)
+  return path
 }
 
 describe('host.pickDirectory', () => {
@@ -243,31 +249,25 @@ describe('host.openPath', () => {
 })
 
 describe('workspace.create', () => {
-  it('serializes concurrent names and rejects the duplicate', async () => {
-    const { api, workspaceRoot } = await harness()
+  it('serializes concurrent creates of one path into a single registration', async () => {
+    const { api, root } = await harness()
+    const target = stageDir(root, 'alpha')
     const responses = await Promise.all([
-      api.workspace.create(request({ name: 'alpha' })),
-      api.workspace.create(request({ name: 'alpha' })),
+      api.workspace.create(request({ path: target })),
+      api.workspace.create(request({ path: target })),
     ])
-    const created = responses.find(response => response.result.ok)
-    const duplicate = responses.find(response => !response.result.ok)
+    const values = responses.map(response => expectOk(response))
+    const created = values.find(value => value.created)
+    const resolved = values.find(value => !value.created)
 
-    expect(created).toBeDefined()
-    expect(expectOk(created!)).toMatchObject({
-      created: true,
-      workspace: { path: join(workspaceRoot, 'alpha'), title: 'alpha' },
-    })
-    expect(duplicate?.result).toMatchObject({
-      ok: false,
-      error: { code: 'workspace-name-conflict', details: { name: 'alpha' } },
-    })
-    expect(existsSync(join(workspaceRoot, 'alpha'))).toBe(true)
+    expect(created).toMatchObject({ workspace: { path: target, title: 'alpha' } })
+    expect(resolved?.workspace.workspaceId).toBe(created?.workspace.workspaceId)
+    expect(expectOk(await api.workspace.list(request({}))).items).toHaveLength(1)
   })
 
-  it('adopts only existing directories and rejects unsafe names', async () => {
-    const { api, workspaceRoot } = await harness()
-    const existing = join(workspaceRoot, 'existing')
-    mkdirSync(existing)
+  it('adopts only existing directories', async () => {
+    const { api, root } = await harness()
+    const existing = stageDir(root, 'existing')
     const first = expectOk(await api.workspace.create(request({ path: existing })))
     const repeated = expectOk(await api.workspace.create(request({ path: existing })))
     expect(first).toMatchObject({ created: true, workspace: { path: existing, title: 'existing' } })
@@ -280,21 +280,16 @@ describe('workspace.create', () => {
     const reopened = expectOk(await api.workspace.create(request({ path: existing })))
     expect(reopened.workspace.title).toBe('renamed-existing')
 
-    const missing = join(workspaceRoot, 'missing')
+    const missing = join(root, 'missing')
     const missingResult = await api.workspace.create(request({ path: missing }))
     expect(missingResult.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
     expect(existsSync(missing)).toBe(false)
-
-    for (const name of ['', '.', '..', 'a/b', 'a\\b']) {
-      const invalid = await api.workspace.create(request({ name }))
-      expect(invalid.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
-    }
   })
 
   it('adopts different paths that derive the same Workspace title', async () => {
-    const { api, workspaceRoot } = await harness()
-    const first = join(workspaceRoot, 'one', 'project')
-    const second = join(workspaceRoot, 'two', 'project')
+    const { api, root } = await harness()
+    const first = join(root, 'one', 'project')
+    const second = join(root, 'two', 'project')
     mkdirSync(first, { recursive: true })
     mkdirSync(second, { recursive: true })
     const firstResult = expectOk(await api.workspace.create(request({ path: first })))
@@ -315,8 +310,8 @@ describe('workspace.create', () => {
 
 describe('session creation and Workspace membership', () => {
   it('attaches a preallocated idempotent session while cwd-only sessions stay ungrouped', async () => {
-    const { api, ctx } = await harness()
-    const workspace = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const { api, ctx, root } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ path: stageDir(root, 'project') }))).workspace
     const sessionId = SessionId('session-workspace-preallocated')
 
     expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
@@ -342,8 +337,8 @@ describe('session creation and Workspace membership', () => {
   })
 
   it('retains a published session when attachment fails and repairs it on retry', async () => {
-    const { api, ctx } = await harness()
-    const created = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const { api, ctx, root } = await harness()
+    const created = expectOk(await api.workspace.create(request({ path: stageDir(root, 'project') }))).workspace
     const workspace = ctx.workspace.list()[0]
     if (workspace === undefined) throw new Error('workspace missing from registry')
     vi.spyOn(workspace, 'attachSession').mockRejectedValueOnce(new Error('simulated write failure'))
@@ -393,7 +388,7 @@ describe('Host Workspace increments', () => {
   })
 
   it('streams committed Workspace and Session increments after empty baselines', async () => {
-    const { api } = await harness()
+    const { api, root } = await harness()
     expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
     expect(expectOk(await api.sessions.list(request({}))).items).toEqual([])
 
@@ -401,7 +396,7 @@ describe('Host Workspace increments', () => {
     const stream: AsyncIterator<RpcRequest<HostFrame>> =
       api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
     const workspaceIncrement = nextHostFrame(stream)
-    const workspace = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const workspace = expectOk(await api.workspace.create(request({ path: stageDir(root, 'project') }))).workspace
     expect(await workspaceIncrement).toMatchObject({
       payload: { type: 'host/workspace-changed', workspace: { workspaceId: workspace.workspaceId } },
     })
@@ -429,7 +424,7 @@ describe('Host Workspace increments', () => {
   })
 
   it('does not publish a Workspace whose registry-order commit fails', async () => {
-    const { api, storageDomain } = await harness()
+    const { api, storageDomain, root } = await harness()
     const domain = storageDomain.get('workspace')
     if (domain === undefined) throw new Error('workspace domain is not open')
     vi.spyOn(domain.global, 'set').mockRejectedValueOnce(new Error('simulated registry order failure'))
@@ -438,7 +433,7 @@ describe('Host Workspace increments', () => {
       api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
     const next = stream.next()
 
-    const failed = await api.workspace.create(request({ name: 'ghost' }))
+    const failed = await api.workspace.create(request({ path: stageDir(root, 'ghost') }))
     expect(failed.result.ok).toBe(false)
     expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
     abort.abort()
@@ -446,8 +441,8 @@ describe('Host Workspace increments', () => {
   })
 
   it('deletes the registration, keeps its session and folder, and streams one removal', async () => {
-    const { api, ctx } = await harness()
-    const workspace = expectOk(await api.workspace.create(request({ name: 'delete-me' }))).workspace
+    const { api, ctx, root } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ path: stageDir(root, 'delete-me') }))).workspace
     const sessionId = SessionId('session-kept-after-workspace-delete')
     expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
 
@@ -479,8 +474,8 @@ describe('Host Workspace increments', () => {
   })
 
   it('archives a session into the global set, keeps its accounting, and streams the set once', async () => {
-    const { api } = await harness()
-    const workspace = expectOk(await api.workspace.create(request({ name: 'archive-home' }))).workspace
+    const { api, root } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ path: stageDir(root, 'archive-home') }))).workspace
     const sessionId = SessionId('session-to-archive')
     expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
     expect(expectOk(await api.workspace.list(request({}))).archivedSessionIds).toEqual([])

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -23,6 +23,7 @@ function scriptedApi(overrides: {
   host?: Partial<ApiProxy['host']>
   commands?: Partial<ApiProxy['commands']>
   skills?: Partial<ApiProxy['skills']>
+  agentPresets?: Partial<ApiProxy['agentPresets']>
   events?: Partial<ApiProxy['events']>
   goals?: Partial<ApiProxy['goals']>
   settings?: Partial<ApiProxy['settings']>
@@ -55,6 +56,10 @@ function scriptedApi(overrides: {
       rename: r => ok(r, { title: 'renamed', seq: 0 }),
       fork: r => ok(r, { sessionId: sid('s-fork') }),
       prompt: r => ok(r, { accepted: true as const }),
+      attachment: r => ok(r, {
+        attachment: { attachmentId: 'a' as never, mediaType: 'image/png', bytes: 1, width: 1, height: 1 },
+        data: 'AA==',
+      }),
       updateQueue: r => ok(r, { accepted: true as const }),
       cancel: r => ok(r, { accepted: true as const }),
       ...overrides.sessions,
@@ -88,6 +93,15 @@ function scriptedApi(overrides: {
       ...overrides.commands,
     },
     skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
+    agentPresets: {
+      list: r => ok(r, { presets: [], authorable: false, hasDocument: false }),
+      select: r => ok(r, { agentPreset: r.payload.agentPreset }),
+      read: r => ok(r, { agentPreset: r.payload.agentPreset, trust: 'user' as const, content: '' }),
+      copy: r => ok(r, { agentPreset: r.payload.agentPreset }),
+      openDocument: r => ok(r, { opened: true as const }),
+      remove: r => ok(r, {}),
+      ...overrides.agentPresets,
+    },
     goals: {
       create: err,
       edit: err,
@@ -119,6 +133,7 @@ function scriptedApi(overrides: {
     },
     events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
     respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
+    downloads: { sessionLog: async () => new Response('stub', { status: 404 }) },
   }
 }
 
@@ -222,6 +237,18 @@ describe('unary round trip', () => {
     expect(appended.result.ok).toBe(true)
   })
 
+  it('routes the agent-preset roster and switch through the wire', async () => {
+    const c = client(scriptedApi())
+
+    const listed = await c.agentPresets.list({})
+    expect(listed.result).toEqual({ ok: true, value: { presets: [], authorable: false, hasDocument: false } })
+
+    // The switch carries the session it is about: the host refuses one whose
+    // conversation has started, and it can only know which by id.
+    const selected = await c.agentPresets.select({ sessionId: sid('s1'), agentPreset: 'standard' })
+    expect(selected.result).toEqual({ ok: true, value: { agentPreset: 'standard' } })
+  })
+
   it('passes business errors through as 200 + err result, not a throw', async () => {
     const api = scriptedApi({
       sessions: {
@@ -406,8 +433,8 @@ describe('workspace domain round trip', () => {
     expect(archivedResponse.result).toEqual({ ok: true, value: { archivedSessionIds: ['s-arch'] } })
   })
 
-  it('rejects a create payload violating the exactly-one refine at the handler', async () => {
-    const response = await client(scriptedApi()).workspace.create({})
+  it('rejects a pathless create payload at the handler schema', async () => {
+    const response = await client(scriptedApi()).workspace.create({} as never)
     expect(response.result.ok).toBe(false)
     if (!response.result.ok) expect(response.result.error.code).toBe('bad-request')
   })

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -97,6 +97,12 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       async prompt(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
+      async attachment(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { attachment: { attachmentId: 'a' as never, mediaType: 'image/png' as const, bytes: 1, width: 1, height: 1 }, data: 'AA==' } },
+        }
+      },
       async updateQueue(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
@@ -197,6 +203,32 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
         return { rpcId: request.rpcId, result: { ok: true, value: { matched: false } } }
       },
     },
+    agentPresets: {
+      list(request: RpcRequest<{}>) {
+        return Promise.resolve({
+          rpcId: request.rpcId,
+          result: { ok: true as const, value: { presets: [], authorable: false, hasDocument: false } },
+        })
+      },
+      select(request: RpcRequest<{ agentPreset: string }>) {
+        const value = { agentPreset: request.payload.agentPreset }
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
+      },
+      read(request: RpcRequest<{ agentPreset: string }>) {
+        const value = { agentPreset: request.payload.agentPreset, trust: 'user' as const, content: '' }
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
+      },
+      copy(request: RpcRequest<{ from: string; agentPreset: string }>) {
+        const value = { agentPreset: request.payload.agentPreset }
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
+      },
+      openDocument(request: RpcRequest<{ agentPreset: string }>) {
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value: { opened: true as const } } })
+      },
+      remove(request: RpcRequest<{ agentPreset: string }>) {
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value: {} } })
+      },
+    },
     skills: {
       async list(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits', modelInvocable: true }] } } }
@@ -268,6 +300,11 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
     async respond(message: ClientResponse): Promise<RpcReceipt> {
       return message.rpcId === 'known' ? { accepted: true } : { accepted: false, reason: 'not-pending' }
     },
+    downloads: {
+      async sessionLog() {
+        return new Response('stub', { status: 404 })
+      },
+    },
   }
 }
 
@@ -331,6 +368,7 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     const renamed = await c.sessions.rename({ sessionId: 's' as never, title: 'named' })
     expect(renamed.result).toMatchObject({ ok: true, value: { title: 'named', seq: 0 } })
     expect((await c.sessions.prompt({ sessionId: 's' as never, mode: 'queue', content: [{ type: 'text', text: 'x' }] })).result.ok).toBe(true)
+    expect((await c.sessions.attachment({ sessionId: 's' as never, attachmentId: 'a' as never })).result.ok).toBe(true)
     expect((await c.sessions.updateQueue({
       sessionId: 's' as never,
       itemId: 'item-1' as never,
@@ -340,6 +378,28 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect((await c.host.describe({})).result.ok).toBe(true)
   })
 
+  it('round-trips every agent-preset method, authoring included', async () => {
+    const c = client()
+
+    // The whole domain crosses the carrier: the roster a picker reads, the
+    // per-session switch, and the authoring calls the settings page makes.
+    // Each has its own request schema, so a registration missing from either
+    // half fails here rather than in the browser.
+    expect((await c.agentPresets.list({})).result).toEqual({
+      ok: true, value: { presets: [], authorable: false, hasDocument: false },
+    })
+    expect((await c.agentPresets.select({ sessionId: 's' as never, agentPreset: 'minimal' })).result)
+      .toEqual({ ok: true, value: { agentPreset: 'minimal' } })
+    expect((await c.agentPresets.read({ agentPreset: 'mine' })).result).toEqual({
+      ok: true, value: { agentPreset: 'mine', trust: 'user', content: '' },
+    })
+    expect((await c.agentPresets.copy({ from: 'standard', agentPreset: 'mine' })).result)
+      .toEqual({ ok: true, value: { agentPreset: 'mine' } })
+    expect((await c.agentPresets.openDocument({ agentPreset: 'mine' })).result)
+      .toEqual({ ok: true, value: { opened: true } })
+    expect((await c.agentPresets.remove({ agentPreset: 'mine' })).result).toEqual({ ok: true, value: {} })
+  })
+
   it('round-trips the native picker without the default unary timeout', async () => {
     const api = fakeApi()
     api.host.pickDirectory = async (request) => {

packages/host/apiproxy/tests/native-path-opener.spec.ts

@@ -16,7 +16,7 @@ vi.mock('node:child_process', () => ({ execFile: execFileMock }))
 
 import { release as osRelease } from 'node:os'
 import { describe, expect, it, vi } from 'vitest'
-import { openNativePath, openNativeTextFile, type PathOpenerRunner } from '../src/native-path-opener.ts'
+import { canOpenNativePath, openNativePath, openNativeTextFile, type PathOpenerRunner } from '../src/native-path-opener.ts'
 
 const signal = () => new AbortController().signal
 
@@ -287,3 +287,35 @@ describe('browser-renderable documents', () => {
     ])
   })
 })
+
+describe('canOpenNativePath', () => {
+  it('always answers yes where the desktop is part of the platform', () => {
+    expect(canOpenNativePath({ platform: 'darwin', env: {} })).toBe(true)
+    expect(canOpenNativePath({ platform: 'win32', env: {} })).toBe(true)
+  })
+
+  it('requires a display server or WSL interop on linux', () => {
+    const linux = { platform: 'linux' as const, osRelease: '6.8.0-generic' }
+    // Headless is the case the capability exists for: `xdg-open` would spawn
+    // into nothing, so a surface should show the path as text instead.
+    expect(canOpenNativePath({ ...linux, env: {} })).toBe(false)
+    expect(canOpenNativePath({ ...linux, env: { DISPLAY: ':0' } })).toBe(true)
+    expect(canOpenNativePath({ ...linux, env: { WAYLAND_DISPLAY: 'wayland-0' } })).toBe(true)
+    expect(canOpenNativePath({
+      platform: 'linux', osRelease: '5.15.153.1-microsoft-standard-WSL2', env: {},
+    })).toBe(true)
+  })
+
+  it('answers no on a platform the opener does not support', () => {
+    expect(canOpenNativePath({ platform: 'freebsd', env: {} })).toBe(false)
+  })
+
+  it('samples the ambient environment when no override is supplied', () => {
+    const env = process.env
+    const marked = (value: string | undefined): boolean => value !== undefined && value !== ''
+    const expected = marked(env.WSL_DISTRO_NAME) || marked(env.WSL_INTEROP)
+      || marked(env.DISPLAY) || marked(env.WAYLAND_DISPLAY)
+
+    expect(canOpenNativePath({ platform: 'linux', osRelease: '6.8.0-generic' })).toBe(expected)
+  })
+})

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -32,6 +32,9 @@ import {
   commandListRequestSchema, commandListValueSchema,
 } from '../src/api/commands.schema.ts'
 import { skillEntrySchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.schema.ts'
+import {
+  agentPresetEntrySchema, agentPresetListValueSchema, agentPresetOpenDocumentValueSchema,
+} from '../src/api/agent-presets.schema.ts'
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
@@ -356,11 +359,11 @@ describe('workspace domain schemas', () => {
     expect(() => workspaceArchiveSessionValueSchema.parse({ archivedSessionIds: 's1' })).toThrow()
   })
 
-  it('create requires exactly one of path/name (both refine arms)', () => {
+  it('create requires a path', () => {
     expect(workspaceCreateRequestSchema.parse({ path: '/p' }).path).toBe('/p')
-    expect(workspaceCreateRequestSchema.parse({ name: 'n' }).name).toBe('n')
-    expect(() => workspaceCreateRequestSchema.parse({})).toThrow(/exactly one/)
-    expect(() => workspaceCreateRequestSchema.parse({ path: '/p', name: 'n' })).toThrow(/exactly one/)
+    expect(() => workspaceCreateRequestSchema.parse({})).toThrow()
+    // The retired create-by-name spelling stays a clean schema rejection.
+    expect(() => workspaceCreateRequestSchema.parse({ name: 'n' })).toThrow()
     expect(workspaceCreateValueSchema.parse({ workspace: view, created: false }).created).toBe(false)
   })
 
@@ -462,6 +465,11 @@ describe('events frame schemas', () => {
         },
       ] },
       { type: 'session/projection', sessionId: 's', key: 'todos', value: [{ content: 'x', status: 'pending' }], seq: 7 },
+      { type: 'session/tasks', sessionId: 's', tasks: [] },
+      { type: 'session/tasks', sessionId: 's', tasks: [
+        { id: 'bash-1', kind: 'bash', label: 'pnpm run build', status: 'running', startedAt: 5 },
+        { id: 'pty-send-2', kind: 'pty-send', label: 'send keys', status: 'failed', detail: 'exit code: 3', startedAt: 5, finishedAt: 9 },
+      ] },
       { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
     ]
     for (const frame of frames) expect(muxFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
@@ -470,6 +478,14 @@ describe('events frame schemas', () => {
       { type: 'session/projection', sessionId: 's', key: '', value: null, seq: 0 },
       { type: 'session/projection', sessionId: 's', key: 'todos', value: null, seq: -1 },
       { type: 'session/projection', sessionId: 's', key: 'todos', value: null, seq: 0.5 },
+      // A producer kind stays an open string, but the closed status set and
+      // the identity/label bounds are the carrier's own wire contract.
+      { type: 'session/tasks', sessionId: 's', tasks: [{ id: '', kind: 'bash', label: 'l', status: 'running', startedAt: 0 }] },
+      { type: 'session/tasks', sessionId: 's', tasks: [{ id: 'bash-1', kind: '', label: 'l', status: 'running', startedAt: 0 }] },
+      { type: 'session/tasks', sessionId: 's', tasks: [{ id: 'bash-1', kind: 'bash', label: '', status: 'running', startedAt: 0 }] },
+      { type: 'session/tasks', sessionId: 's', tasks: [{ id: 'bash-1', kind: 'bash', label: 'l', status: 'pending', startedAt: 0 }] },
+      { type: 'session/tasks', sessionId: 's', tasks: [{ id: 'bash-1', kind: 'bash', label: 'l', status: 'running', startedAt: -1 }] },
+      { type: 'session/tasks', sessionId: 's', tasks: [{ id: 'bash-1', kind: 'bash', label: 'l', status: 'completed', startedAt: 0, finishedAt: 0.5 }] },
     ]) expect(() => muxFrameSchema.parse(invalid)).toThrow()
     expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
   })
@@ -519,6 +535,7 @@ describe('events frame schemas', () => {
       } },
       { type: 'host/workspace-removed', workspaceId: 'w' },
       { type: 'host/commands-changed' },
+      { type: 'host/session-preset-changed', sessionId: 's', agentPreset: 'minimal' },
       { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
     ]
     for (const frame of frames) expect(hostFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
@@ -537,3 +554,27 @@ describe('respond payload schemas', () => {
     expect(payload.sessionId).toBe('s')
   })
 })
+
+describe('agent-preset schemas', () => {
+  it('accepts a roster row and rejects an unknown trust', () => {
+    expect(agentPresetEntrySchema.parse({ id: 'standard', trust: 'system', isDefault: true }))
+      .toEqual({ id: 'standard', trust: 'system', isDefault: true })
+    expect(() => agentPresetEntrySchema.parse({ id: 'x', trust: 'root', isDefault: false })).toThrow()
+    expect(() => agentPresetEntrySchema.parse({ id: '', trust: 'user', isDefault: false })).toThrow()
+  })
+
+  it('accepts an empty roster', () => {
+    // A deployment composing no presets still reports its authoring and
+    // native-open capabilities, so a surface knows what to offer.
+    expect(agentPresetListValueSchema.parse({ presets: [], authorable: false, hasDocument: false }))
+      .toEqual({ presets: [], authorable: false, hasDocument: false })
+  })
+
+  it('answers the open-document union by its discriminant', () => {
+    expect(agentPresetOpenDocumentValueSchema.parse({ opened: true })).toEqual({ opened: true })
+    expect(agentPresetOpenDocumentValueSchema.parse({ opened: false, path: '/presets/mine' }))
+      .toEqual({ opened: false, path: '/presets/mine' })
+    // A closed reply must carry the path the surface shows instead.
+    expect(() => agentPresetOpenDocumentValueSchema.parse({ opened: false })).toThrow()
+  })
+})

packages/host/apiproxy/tests/session-export.spec.ts

@@ -0,0 +1,684 @@
+/**
+ * session.export host path: the GET download endpoint streams a ZIP whose
+ * files are the stored artifacts verbatim (root + optional descendants), and
+ * the degenerate compositions fail loudly (missing services → 500, missing
+ * root → 404, missing descendant → errored stream).
+ */
+
+import { randomBytes } from 'node:crypto'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { unzipSync, strFromU8 } from 'fflate'
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionLineageNode } from '@deepseek-ai/dsh-session-query'
+import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
+import ApiProxyService, { createApiProxy, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+
+const sid = (id: string): SessionId => id as SessionId
+
+function header(id: string, parentSession?: SessionId): SessionHeader {
+  return {
+    version: 0,
+    id: sid(id),
+    createdAt: 1000,
+    cwd: '/proj',
+    ...parentSession === undefined ? {} : { parentSession },
+    delegationDepth: parentSession === undefined ? 0 : 1,
+  }
+}
+
+function artifact(id: string, parentSession?: SessionId, content?: string): SessionRawArtifact {
+  return {
+    meta: header(id, parentSession),
+    filename: 'session.jsonl',
+    content: content ?? `{"type":"session","version":0,"id":"${id}","createdAt":1000}\n{"type":"turn/start","seq":0,"time":2000,"data":{"turn":1}}\n`,
+  }
+}
+
+function node(id: string, ...descendants: SessionLineageNode[]): SessionLineageNode {
+  return { session: { header: header(id, sid('session-root')), live: false, persisted: true }, descendants }
+}
+
+/** One durable image object served by the fake attachment store. */
+function storedImage(id: string, mediaType: ImageAttachmentRef['mediaType'] = 'image/png') {
+  return {
+    ref: { attachmentId: sid(id), mediaType, bytes: 4, width: 2, height: 2 } as unknown as ImageAttachmentRef,
+    data: new Uint8Array([1, 2, 3, 4]),
+  }
+}
+
+/** A user/message event line carrying one image reference. */
+function imageEventLine(id: string, mediaType: ImageAttachmentRef['mediaType'] = 'image/png'): string {
+  return `{"type":"user/message","seq":1,"time":1000,"data":{"content":[{"type":"image","attachment":{"attachmentId":"${id}","mediaType":"${mediaType}","bytes":4,"width":2,"height":2}}]}}`
+}
+
+async function buildApi(
+  artifacts: Record<string, SessionRawArtifact>,
+  descendants: SessionLineageNode[] = [],
+  services: {
+    query?: boolean
+    persistence?: boolean | 'throw' | 'unsupported'
+    attachments?: boolean | ((ref: ImageAttachmentRef, signal?: AbortSignal) => Promise<ReturnType<typeof storedImage>>)
+    sessions?: {
+      get(id: SessionId): { readonly id: SessionId } | undefined
+      flush(session: { readonly id: SessionId }): Promise<boolean>
+    }
+    readRaw?: (id: SessionId, signal?: AbortSignal) => Promise<SessionRawArtifact | undefined>
+    traceSession?: (id: SessionId, signal?: AbortSignal) => Promise<{
+      target: { header: SessionHeader; live: boolean; persisted: boolean }
+      ancestors: readonly SessionLineageNode[]
+      complete: boolean
+      root: { header: SessionHeader; live: boolean; persisted: boolean }
+      descendants: readonly SessionLineageNode[]
+    }>
+    compressionLevel?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+  } = {},
+) {
+  const ctx = new Context()
+  await ctx.plugin(UserInteractionService)
+  const query = services.query ?? true
+  const persistence = services.persistence ?? true
+  if (query) {
+    ctx.provide('sessionQuery', {
+      traceSession: services.traceSession ?? (async () => ({
+        target: { header: header('session-root'), live: false, persisted: true },
+        ancestors: [],
+        complete: true,
+        root: { header: header('session-root'), live: false, persisted: true },
+        descendants,
+      })),
+    } as never)
+  }
+  if (persistence) {
+    ctx.provide('sessionPersistence', {
+      supportsRawArtifacts: persistence !== 'unsupported',
+      readRaw: services.readRaw ?? (async (id: SessionId) => {
+        if (persistence === 'throw') throw new Error('/host/private/session.jsonl')
+        return artifacts[id]
+      }),
+    } as never)
+  }
+  if (services.attachments !== false) {
+    const readImage = typeof services.attachments === 'function'
+      ? services.attachments
+      : async (ref: ImageAttachmentRef) => storedImage(String(ref.attachmentId), ref.mediaType)
+    ctx.provide('attachments', {
+      imageLimits: {} as never,
+      validateImage: async () => {},
+      saveImage: async () => { throw new Error('export never saves images') },
+      readImage,
+    } as never)
+  }
+  if (services.sessions !== undefined) ctx.provide('sessions', services.sessions as never)
+  return createApiProxy(ctx, {
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
+    cwd: '/tmp',
+    ...services.compressionLevel === undefined
+      ? {}
+      : { sessionExportCompressionLevel: services.compressionLevel },
+  })
+}
+
+async function responseBytes(response: Response): Promise<Uint8Array> {
+  return new Uint8Array(await response.arrayBuffer())
+}
+
+describe('session export compression config', () => {
+  it('defaults to level 6 and rejects values outside the integer 0-9 range', () => {
+    expect(ApiProxyService.Config({})).toEqual({ sessionExportCompressionLevel: 6 })
+    expect(ApiProxyService.Config({ sessionExportCompressionLevel: 0 }))
+      .toEqual({ sessionExportCompressionLevel: 0 })
+    expect(ApiProxyService.Config({ sessionExportCompressionLevel: 9 }))
+      .toEqual({ sessionExportCompressionLevel: 9 })
+    for (const value of [-1, 10, 1.5]) {
+      expect(() => ApiProxyService.Config({ sessionExportCompressionLevel: value } as never)).toThrow()
+    }
+  })
+})
+
+describe('session.export download endpoint', () => {
+  it('streams a ZIP with the root artifact verbatim under its original filename', async () => {
+    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toBe('application/zip')
+    expect(response.headers.get('content-disposition')).toContain('dsh-session-session-root.zip')
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files)).toEqual(['session.jsonl'])
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(artifact('session-root').content)
+  })
+
+  it('uses the resolved compression level for ZIP entries', async () => {
+    const root = artifact('session-root', undefined, 'compressible\n'.repeat(32 * 1024))
+    const storedApi = await buildApi({ 'session-root': root }, [], { compressionLevel: 0 })
+    const compressedApi = await buildApi({ 'session-root': root }, [], { compressionLevel: 9 })
+    const stored = await storedApi.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: false },
+      new AbortController().signal,
+    )
+    const compressed = await compressedApi.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: false },
+      new AbortController().signal,
+    )
+    const storedBytes = await responseBytes(stored)
+    const compressedBytes = await responseBytes(compressed)
+    expect(compressedBytes.byteLength).toBeLessThan(storedBytes.byteLength)
+    expect(strFromU8(unzipSync(compressedBytes)['session.jsonl'] as Uint8Array)).toBe(root.content)
+  })
+
+  it('includes descendant artifacts under subagents/<id>/ when requested', async () => {
+    const api = await buildApi({
+      'session-root': artifact('session-root'),
+      'child-a': artifact('child-a', sid('session-root')),
+      'grandchild-a': artifact('grandchild-a', sid('child-a')),
+    }, [
+      node('child-a', node('grandchild-a')),
+    ])
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
+    )
+    expect(response.status).toBe(200)
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files).sort()).toEqual([
+      'session.jsonl',
+      'subagents/child-a/session.jsonl',
+      'subagents/grandchild-a/session.jsonl',
+    ])
+    expect(strFromU8(files['subagents/child-a/session.jsonl'] as Uint8Array))
+      .toBe(artifact('child-a').content)
+  })
+
+  it('flushes each live root and descendant immediately before reading its artifact', async () => {
+    const stored: Record<string, SessionRawArtifact> = {
+      'session-root': artifact('session-root', undefined, 'stale root'),
+      'child-a': artifact('child-a', sid('session-root'), 'stale child'),
+    }
+    const durable: Record<string, SessionRawArtifact> = {
+      'session-root': artifact('session-root', undefined, 'durable root'),
+      'child-a': artifact('child-a', sid('session-root'), 'durable child'),
+    }
+    const flushed: SessionId[] = []
+    const api = await buildApi(stored, [node('child-a')], {
+      sessions: {
+        get: id => durable[id] === undefined ? undefined : { id },
+        flush: async (session) => {
+          const artifactAfterFlush = durable[session.id]
+          if (artifactAfterFlush === undefined) throw new Error('unexpected session')
+          flushed.push(session.id)
+          stored[session.id] = artifactAfterFlush
+          return true
+        },
+      },
+    })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(flushed).toEqual([sid('session-root'), sid('child-a')])
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe('durable root')
+    expect(strFromU8(files['subagents/child-a/session.jsonl'] as Uint8Array)).toBe('durable child')
+  })
+
+  it('reads a cold artifact without asking the live-session store to flush', async () => {
+    const flush = vi.fn(async () => true)
+    const root = artifact('session-root')
+    const api = await buildApi({ 'session-root': root }, [], {
+      sessions: {
+        get: () => undefined,
+        flush,
+      },
+    })
+    const response = await api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: false },
+      new AbortController().signal,
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(flush).not.toHaveBeenCalled()
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(root.content)
+  })
+
+  it('answers 404 for a missing root session', async () => {
+    const api = await buildApi({})
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(404)
+  })
+
+  it('answers 501 when the persistence backend has no per-session raw artifacts', async () => {
+    const api = await buildApi({}, [], { persistence: 'unsupported' })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(501)
+    expect(await response.text()).toContain('does not expose per-session raw artifacts')
+  })
+
+  it('answers 400 when the sessionId query parameter is absent', async () => {
+    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?includeDescendants=true'),
+    )
+    expect(response.status).toBe(400)
+  })
+
+  it('answers 400 for an includeDescendants value other than true or false', async () => {
+    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=1'),
+    )
+    expect(response.status).toBe(400)
+  })
+
+  it('answers 500 when the deployment mounts no persistence or session-query service', async () => {
+    const api = await buildApi({}, [], { query: false, persistence: false })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(500)
+    expect(await response.text()).toContain('session-query')
+  })
+
+  it('fails the whole export when a descendant has no stored artifact', async () => {
+    const api = await buildApi({
+      'session-root': artifact('session-root'),
+    }, [node('child-missing')])
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
+    )
+    expect(response.status).toBe(200)
+    // The stream errors before completing, so the body read rejects rather
+    // than returning a truncated-but-valid archive.
+    await expect(response.arrayBuffer()).rejects.toThrow()
+  })
+
+  it('keeps an astral character whole when its surrogate pair straddles a push boundary', async () => {
+    // The push loop slices by 2^16 code units and must back off one unit when
+    // the boundary lands inside a surrogate pair; otherwise the pair re-encodes
+    // as U+FFFD and the exported artifact is silently corrupted.
+    const root = { ...artifact('session-root'), content: `${'a'.repeat((1 << 16) - 1)}😀tail` }
+    const api = await buildApi({ 'session-root': root })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(root.content)
+  })
+
+  it('splits a long artifact on a plain code-unit boundary without backoff', async () => {
+    // A boundary that lands on a BMP character needs no surrogate backoff; the
+    // round trip must still be byte-identical across the multi-chunk push.
+    const root = { ...artifact('session-root'), content: 'z'.repeat((1 << 16) + 4096) }
+    const api = await buildApi({ 'session-root': root })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe(root.content)
+  })
+
+  it('waits for response pull capacity before reading the next archive entry', async () => {
+    const root = artifact('session-root', undefined, [
+      imageEventLine('after-root'),
+      randomBytes(512 * 1024).toString('base64'),
+    ].join('\n'))
+    let imageReads = 0
+    const api = await buildApi({ 'session-root': root }, [], {
+      attachments: async (ref) => {
+        imageReads += 1
+        return storedImage(String(ref.attachmentId), ref.mediaType)
+      },
+    })
+    vi.useFakeTimers()
+    let response: Response | undefined
+    try {
+      response = await toFetchHandler(api).fetch(
+        new Request('http://host/api/session.export?sessionId=session-root'),
+      )
+      // Exhausting timer turns must not advance a producer whose byte queue is
+      // full; only a consumer pull can release it.
+      await vi.runAllTimersAsync()
+      expect(imageReads).toBe(0)
+    } finally {
+      vi.useRealTimers()
+    }
+    if (response === undefined) throw new Error('missing export response')
+    const files = unzipSync(await responseBytes(response))
+    expect(imageReads).toBe(1)
+    expect(files['media/after-root.png']).toEqual(storedImage('after-root').data)
+  })
+
+  it('exports an empty artifact as an empty zip entry', async () => {
+    const root = { ...artifact('session-root'), content: '' }
+    const api = await buildApi({ 'session-root': root })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files)).toEqual(['session.jsonl'])
+    expect(strFromU8(files['session.jsonl'] as Uint8Array)).toBe('')
+  })
+
+  it('exports a shared lineage node once (seen-set dedup)', async () => {
+    const api = await buildApi({
+      'session-root': artifact('session-root'),
+      'child-a': artifact('child-a', sid('session-root')),
+      'child-b': artifact('child-b', sid('session-root')),
+      shared: artifact('shared', sid('child-a')),
+    }, [
+      node('child-a', node('shared')),
+      node('child-b', node('shared')),
+    ])
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files).sort()).toEqual([
+      'session.jsonl',
+      'subagents/child-a/session.jsonl',
+      'subagents/child-b/session.jsonl',
+      'subagents/shared/session.jsonl',
+    ])
+  })
+
+  it('answers 500 without leaking the backend error when the root artifact read fails', async () => {
+    const api = await buildApi({}, [], { query: true, persistence: 'throw' })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(500)
+    const body = await response.text()
+    expect(body).toBe('session log export failed to prepare the stored artifact')
+    expect(body).not.toContain('/host/private/')
+  })
+
+  it('answers the private-error-safe 500 when the live root flush fails', async () => {
+    const api = await buildApi({ 'session-root': artifact('session-root') }, [], {
+      sessions: {
+        get: id => ({ id }),
+        flush: async () => { throw new Error('/host/private/flush-state') },
+      },
+    })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(500)
+    const body = await response.text()
+    expect(body).toBe('session log export failed to prepare the stored artifact')
+    expect(body).not.toContain('/host/private/')
+  })
+
+  it('forwards one request signal through root, lineage, and descendant reads', async () => {
+    const reads: Array<{ id: SessionId; signal: AbortSignal | undefined }> = []
+    const traces: AbortSignal[] = []
+    const api = await buildApi({}, [node('child-a')], {
+      readRaw: async (id, signal) => {
+        reads.push({ id, signal })
+        return id === sid('session-root')
+          ? artifact('session-root')
+          : artifact('child-a', sid('session-root'))
+      },
+      traceSession: async (_id, signal) => {
+        if (signal !== undefined) traces.push(signal)
+        return {
+          target: { header: header('session-root'), live: false, persisted: true },
+          ancestors: [],
+          complete: true,
+          root: { header: header('session-root'), live: false, persisted: true },
+          descendants: [node('child-a')],
+        }
+      },
+    })
+    const controller = new AbortController()
+    const response = await api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: true },
+      controller.signal,
+    )
+    await response.arrayBuffer()
+    const producerSignal = traces[0]
+    if (producerSignal === undefined) throw new Error('missing lineage signal')
+    expect(reads[0]).toEqual({ id: sid('session-root'), signal: controller.signal })
+    expect(reads[1]).toEqual({ id: sid('child-a'), signal: producerSignal })
+    const cancellation = new Error('request cancelled after response')
+    controller.abort(cancellation)
+    expect(producerSignal.aborted).toBe(true)
+    expect(producerSignal.reason).toBe(cancellation)
+  })
+
+  it('preserves request cancellation instead of translating it to HTTP 500', async () => {
+    const api = await buildApi({ 'session-root': artifact('session-root') })
+    const controller = new AbortController()
+    const cancellation = new Error('request cancelled')
+    controller.abort(cancellation)
+    await expect(api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: false },
+      controller.signal,
+    )).rejects.toBe(cancellation)
+  })
+
+  it('aborts descendant work and terminates ZIP production when its reader cancels', async () => {
+    let reportDescendantStarted!: (signal: AbortSignal) => void
+    const descendantStarted = new Promise<AbortSignal>((resolve) => {
+      reportDescendantStarted = resolve
+    })
+    const api = await buildApi({}, [node('child-a')], {
+      readRaw: async (id, signal) => {
+        if (id === sid('session-root')) return artifact('session-root')
+        if (signal === undefined) throw new Error('missing descendant signal')
+        reportDescendantStarted(signal)
+        return new Promise((_, reject) => {
+          signal.addEventListener('abort', () => {
+            reject(signal.reason as Error)
+          }, { once: true })
+        })
+      },
+    })
+    const response = await api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: true },
+      new AbortController().signal,
+    )
+    const reader = response.body?.getReader()
+    if (reader === undefined) throw new Error('missing response body')
+    const descendantSignal = await descendantStarted
+    const cancellation = new Error('download consumer left')
+    await reader.cancel(cancellation)
+    expect(descendantSignal.aborted).toBe(true)
+    expect(descendantSignal.reason).toBe(cancellation)
+  })
+
+  it('aborts attachment reads when its reader cancels', async () => {
+    let reportAttachmentStarted!: (signal: AbortSignal) => void
+    const attachmentStarted = new Promise<AbortSignal>((resolve) => {
+      reportAttachmentStarted = resolve
+    })
+    const root = artifact('session-root', undefined, [
+      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
+      imageEventLine('slow-img'),
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': root }, [], {
+      attachments: async (_ref, signal) => {
+        if (signal === undefined) throw new Error('missing attachment signal')
+        reportAttachmentStarted(signal)
+        return new Promise((_, reject) => {
+          signal.addEventListener('abort', () => {
+            reject(signal.reason as Error)
+          }, { once: true })
+        })
+      },
+    })
+    const response = await api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: false },
+      new AbortController().signal,
+    )
+    const reader = response.body?.getReader()
+    if (reader === undefined) throw new Error('missing response body')
+    const attachmentSignal = await attachmentStarted
+    const cancellation = new Error('download consumer left during attachment read')
+    await reader.cancel(cancellation)
+    expect(attachmentSignal.aborted).toBe(true)
+    expect(attachmentSignal.reason).toBe(cancellation)
+  })
+
+  it('uses a stable Error reason when its reader cancels without one', async () => {
+    let reportDescendantStarted!: (signal: AbortSignal) => void
+    const descendantStarted = new Promise<AbortSignal>((resolve) => {
+      reportDescendantStarted = resolve
+    })
+    const api = await buildApi({}, [node('child-a')], {
+      readRaw: async (id, signal) => {
+        if (id === sid('session-root')) return artifact('session-root')
+        if (signal === undefined) throw new Error('missing descendant signal')
+        reportDescendantStarted(signal)
+        return new Promise((_, reject) => {
+          signal.addEventListener('abort', () => {
+            reject(signal.reason as Error)
+          }, { once: true })
+        })
+      },
+    })
+    const response = await api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: true },
+      new AbortController().signal,
+    )
+    const reader = response.body?.getReader()
+    if (reader === undefined) throw new Error('missing response body')
+    const descendantSignal = await descendantStarted
+    await reader.cancel()
+    expect(descendantSignal.reason).toEqual(new Error('session log export stream cancelled'))
+  })
+
+  it('normalizes a non-Error descendant failure before erroring the stream', async () => {
+    const api = await buildApi({}, [node('child-a')], {
+      readRaw: async (id) => {
+        if (id === sid('session-root')) return artifact('session-root')
+        throw 'descendant read failed'
+      },
+    })
+    const response = await api.downloads.sessionLog(
+      { sessionId: sid('session-root'), includeDescendants: true },
+      new AbortController().signal,
+    )
+    await expect(response.arrayBuffer()).rejects.toEqual(new Error('descendant read failed'))
+  })
+
+  it('includes media objects referenced by the root log under media/<id>.<ext>', async () => {
+    const root = artifact('session-root', undefined, [
+      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
+      imageEventLine('img-1'),
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': root })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(200)
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files).sort()).toEqual(['media/img-1.png', 'session.jsonl'])
+    expect(files['media/img-1.png']).toEqual(storedImage('img-1').data)
+  })
+
+  it('collects media referenced from nested tool results', async () => {
+    const nested = '{"type":"assistant/message","seq":2,"time":2000,"data":{"content":[{"type":"tool-result","content":[{"type":"image","attachment":{"attachmentId":"nested-1","mediaType":"image/webp","bytes":4,"width":2,"height":2}}]}]}}'
+    const root = artifact('session-root', undefined, [
+      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
+      nested,
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': root })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files).sort()).toEqual(['media/nested-1.webp', 'session.jsonl'])
+  })
+
+  it('scans the wrapped, inserted, and chunk carriers plus non-object content items', async () => {
+    const block = (id: string, mediaType: string) =>
+      `{"type":"image","attachment":{"attachmentId":"${id}","mediaType":"${mediaType}","bytes":4,"width":2,"height":2}}`
+    const wrapped = `{"type":"assistant/message","seq":2,"time":2000,"data":{"message":{"role":"assistant","content":["noise",${block('wrapped-1', 'image/jpeg')}]}}}`
+    const inserted = `{"type":"context/inserted","seq":3,"time":3000,"data":{"inserted":[{"content":[${block('inserted-1', 'image/gif')}]}]}}`
+    const chunk = `{"type":"assistant/chunk","seq":4,"time":4000,"data":{"chunk":{"type":"block-end","block":${block('chunk-1', 'image/png')}}}}`
+    const root = artifact('session-root', undefined, [
+      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
+      wrapped,
+      inserted,
+      chunk,
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': root })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(Object.keys(files).sort()).toEqual([
+      'media/chunk-1.png',
+      'media/inserted-1.gif',
+      'media/wrapped-1.jpg',
+      'session.jsonl',
+    ])
+  })
+
+  it('deduplicates one media object referenced by several included logs', async () => {
+    const line = imageEventLine('shared-img')
+    const root = artifact('session-root', undefined, [
+      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
+      line,
+    ].join('\n') + '\n')
+    const child = artifact('child-a', sid('session-root'), [
+      '{"type":"session","version":0,"id":"child-a","createdAt":1000}',
+      line,
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': root, 'child-a': child }, [node('child-a')])
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
+    )
+    const files = unzipSync(await responseBytes(response))
+    expect(files['media/shared-img.png']).toEqual(storedImage('shared-img').data)
+    expect(Object.keys(files).filter(name => name.startsWith('media/'))).toEqual(['media/shared-img.png'])
+  })
+
+  it('includes descendant media only when descendants are requested', async () => {
+    const child = artifact('child-a', sid('session-root'), [
+      '{"type":"session","version":0,"id":"child-a","createdAt":1000}',
+      imageEventLine('child-img'),
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': artifact('session-root'), 'child-a': child }, [node('child-a')])
+    const without = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(Object.keys(unzipSync(await responseBytes(without)))).toEqual(['session.jsonl'])
+    const withDescendants = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root&includeDescendants=true'),
+    )
+    expect(Object.keys(unzipSync(await responseBytes(withDescendants))).sort()).toEqual([
+      'media/child-img.png',
+      'session.jsonl',
+      'subagents/child-a/session.jsonl',
+    ])
+  })
+
+  it('fails the whole export when a referenced image cannot be read', async () => {
+    const root = artifact('session-root', undefined, [
+      '{"type":"session","version":0,"id":"session-root","createdAt":1000}',
+      imageEventLine('gone-img'),
+    ].join('\n') + '\n')
+    const api = await buildApi({ 'session-root': root }, [], {
+      attachments: async () => { throw new Error('attachment bytes missing') },
+    })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(200)
+    await expect(response.arrayBuffer()).rejects.toThrow('attachment bytes missing')
+  })
+
+  it('answers 500 when the deployment mounts no attachments service', async () => {
+    const api = await buildApi({ 'session-root': artifact('session-root') }, [], { attachments: false })
+    const response = await toFetchHandler(api).fetch(
+      new Request('http://host/api/session.export?sessionId=session-root'),
+    )
+    expect(response.status).toBe(500)
+    expect(await response.text()).toContain('attachments')
+  })
+})