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

packages/host/apiproxy/src/api/agent-presets.schema.ts

@@ -0,0 +1,88 @@
+/**
+ * agent-presets domain zod schemas (names derived from map keys:
+ * agentPresetListRequestSchema / agentPresetListValueSchema).
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+import type { AgentPresetEntry } from './agent-presets.ts'
+
+/** AgentPresetEntry row of agentPreset.list. */
+export const agentPresetEntrySchema = z.object({
+  id: z.string().min(1),
+  trust: z.union([z.literal('system'), z.literal('user')]),
+  isDefault: z.boolean(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  broken: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<AgentPresetEntry>>
+
+/** agentPreset.list request payload. */
+export const agentPresetListRequestSchema = z.object({
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.list'>>>
+
+/** agentPreset.list response value. */
+export const agentPresetListValueSchema = z.object({
+  presets: z.array(agentPresetEntrySchema),
+  authorable: z.boolean(),
+  hasDocument: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.list'>>>
+
+/** agentPreset.select request payload. */
+export const agentPresetSelectRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.select'>>>
+
+/** agentPreset.select response value. */
+export const agentPresetSelectValueSchema = z.object({
+  agentPreset: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.select'>>>
+
+/** agentPreset.read request payload. */
+export const agentPresetReadRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.read'>>>
+
+/** agentPreset.read response value. */
+export const agentPresetReadValueSchema = z.object({
+  agentPreset: z.string(),
+  trust: z.union([z.literal('system'), z.literal('user')]),
+  content: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.read'>>>
+
+/** agentPreset.copy request payload. */
+export const agentPresetCopyRequestSchema = z.object({
+  from: z.string().min(1),
+  agentPreset: z.string().min(1),
+  name: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.copy'>>>
+
+/** agentPreset.copy response value. */
+export const agentPresetCopyValueSchema = z.object({
+  agentPreset: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.copy'>>>
+
+/** agentPreset.openDocument request payload. */
+export const agentPresetOpenDocumentRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.openDocument'>>>
+
+/** agentPreset.openDocument response value. */
+export const agentPresetOpenDocumentValueSchema = z.union([
+  z.object({ opened: z.literal(true) }),
+  z.object({ opened: z.literal(false), path: z.string() }),
+]) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.openDocument'>>>
+
+/** agentPreset.remove request payload. */
+export const agentPresetRemoveRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.remove'>>>
+
+/** agentPreset.remove response value. */
+export const agentPresetRemoveValueSchema = z.object({
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.remove'>>>

packages/host/apiproxy/src/api/agent-presets.ts

@@ -0,0 +1,116 @@
+/**
+ * agent-presets domain contract: the roster a browser offers when starting a
+ * session, plus the authoring calls behind it.
+ *
+ * `list` is ordinary: it carries ids and trust, and every preset picker needs
+ * it. The authoring calls are privileged and loopback-pinned — a composition
+ * names the plugins a session runs, so reading one is reconnaissance, and
+ * although authoring is copy-only (no caller supplies composition text or a
+ * path), copying and deleting still rearrange what the deployment offers.
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** One preset the deployment can compose a session's agent from. */
+export interface AgentPresetEntry {
+  /** Stable identifier, also the display name until presets carry metadata. */
+  readonly id: string
+  /**
+   * Whether the preset ships with the deployment or was authored locally.
+   * A `user` preset is exactly as privileged as the plugins it names, so a
+   * surface offering one should say so rather than present it as vetted.
+   */
+  readonly trust: 'system' | 'user'
+  /** Whether a session that names no preset gets this one. */
+  readonly isDefault: boolean
+  /**
+   * Display name the preset published, absent when it published none. A
+   * surface falls back to {@link id}; it is never a second identity, and it
+   * never decides trust — a locally authored preset cannot name itself into
+   * the shipped set.
+   */
+  readonly name?: string
+  /** One sentence on what the preset is for, when it published one. */
+  readonly description?: string
+  /**
+   * Why this preset cannot compose a session, absent when it can. A broken
+   * preset stays listed — its directory still occupies the id, so a surface
+   * must be able to show and delete it — but offering it for selection would
+   * only defer this reason to a failed session start.
+   */
+  readonly broken?: string
+}
+
+/** agent-preset-domain unary methods (the map key agentPreset.* of RpcMethodMap). */
+export interface AgentPresetsApi {
+  /**
+   * Lists every preset the deployment currently supplies, in root-precedence
+   * order — the roots as configured, each root's own presets sorted by id,
+   * and the first root to supply an id wins. The order is not globally
+   * sorted: a user root's preset sits in that root's block, not among the
+   * shipped ids.
+   * An empty roster means the deployment composes no presets at all, and
+   * every session shares the host composition. `authorable` reports whether
+   * the deployment configures a root new presets can be written to, and
+   * `hasDocument` whether `openDocument` can hand a preset directory to a
+   * native opener — both deployment facts rather than per-preset ones, and
+   * neither exposes a Host path.
+   */
+  list(request: RpcRequest<{}>):
+  Promise<RpcResponse<{ presets: readonly AgentPresetEntry[]; authorable: boolean; hasDocument: boolean }>>
+
+  /**
+   * Recompose one session's agent from a different preset.
+   *
+   * Allowed only while the session is blank — no turn has run. Once a
+   * conversation starts, its history was produced under that preset's tools,
+   * and swapping them would leave logged tool calls the new composition cannot
+   * make; the attempt answers `agent-preset-locked`.
+   */
+  select(request: RpcRequest<{ sessionId: SessionId; agentPreset: string }>):
+  Promise<RpcResponse<{ agentPreset: string }>>
+
+  /**
+   * Read one preset's composition text, for the read-only viewer.
+   *
+   * Privileged: a composition names the plugins a session runs, so reading
+   * one is reconnaissance.
+   */
+  read(request: RpcRequest<{ agentPreset: string }>):
+  Promise<RpcResponse<{
+    agentPreset: string
+    trust: 'system' | 'user'
+    content: string
+    name?: string
+    description?: string
+  }>>
+
+  /**
+   * Create a locally authored preset by copying an existing one whole.
+   *
+   * The only authoring write. No composition text and no path crosses the
+   * wire: `from` and `agentPreset` are ids the Host resolves against its own
+   * roots, so a copy is exactly as loadable as its source and grants nothing
+   * the roster did not already carry. The copy keeps the source's description
+   * (the file is the author's to edit afterwards) but not its name — `name`
+   * here or the id fallback is what distinguishes the rows.
+   */
+  copy(request: RpcRequest<{ from: string; agentPreset: string; name?: string }>):
+  Promise<RpcResponse<{ agentPreset: string }>>
+
+  /**
+   * Hand one locally authored preset's DIRECTORY to the platform opener, for
+   * editing the files that are now the only composition editor. The request
+   * carries an id, never a path — the Host resolves it — so no browser
+   * payload can select an arbitrary filesystem target. Where the deployment
+   * has no native opener (`hasDocument: false` on `list`), the reply carries
+   * the resolved directory for the surface to show as text instead. Shipped
+   * presets are refused: their install is not the user's to manage.
+   */
+  openDocument(request: RpcRequest<{ agentPreset: string }>, signal: AbortSignal):
+  Promise<RpcResponse<{ opened: true } | { opened: false; path: string }>>
+
+  /** Delete a locally authored preset. Shipped presets are refused. */
+  remove(request: RpcRequest<{ agentPreset: string }>): Promise<RpcResponse<{}>>
+}

packages/host/apiproxy/src/api/approvals.schema.ts

@@ -10,7 +10,7 @@ import type { ApprovalResponsePayload } from './approvals.ts'
 import type { Wire } from './rpc.schema.ts'
 import { sessionIdSchema } from './sessions.schema.ts'
 
-/** ApprovalRequestId: one brand cast after shape validation (the only cast point in this domain). */
+/** ApprovalRequestId: one brand cast after schema validation (the only cast point in this domain). */
 export const approvalRequestIdSchema = z.string().min(1) as unknown as z.ZodType<ApprovalRequestId>
 
 /** Approval answer payload (the result.value slot of a client-response). */

packages/host/apiproxy/src/api/commands.schema.ts

@@ -33,7 +33,7 @@ export const commandExecuteRequestSchema = z.object({
   line: z.string(),
 }) satisfies z.ZodType<Wire<RequestPayload<'command.execute'>>>
 
-/** CommandId: one brand cast after shape validation (the only cast point in this domain). */
+/** CommandId: one brand cast after schema validation (the only cast point in this domain). */
 export const commandIdSchema = z.string().min(1) as unknown as z.ZodType<CommandId>
 
 /** command.execute response value: pure admission — outcomes ride the logged

packages/host/apiproxy/src/api/downloads.schema.ts

@@ -0,0 +1,26 @@
+/**
+ * downloads domain zod schemas. The GET download surface has no wire
+ * envelope: the request arrives as query parameters (all strings), so its
+ * request schema parses the raw query-parameter object into the method's
+ * exact request shape. SessionId brand cast point: sessionIdSchema, and only
+ * there (hosted in sessions.schema like every other cast).
+ */
+
+import { z } from 'zod'
+import type { DownloadsApi } from './downloads.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+
+/**
+ * session.export query params → the sessionLog request. `includeDescendants`
+ * accepts exactly `true`/`false`/absent; any other value is rejected (400) so
+ * a misspelled flag cannot silently under-export.
+ */
+export const sessionLogQuerySchema = z
+  .object({
+    sessionId: sessionIdSchema,
+    includeDescendants: z.union([z.literal('true'), z.literal('false')]).optional(),
+  })
+  .transform(query => ({
+    sessionId: query.sessionId,
+    ...(query.includeDescendants === 'true' ? { includeDescendants: true } : {}),
+  })) satisfies z.ZodType<Parameters<DownloadsApi['sessionLog']>[0]>

packages/host/apiproxy/src/api/downloads.ts

@@ -0,0 +1,25 @@
+/**
+ * downloads domain contract: host-only download surfaces — the GET-download
+ * channel family, the mirror of the SSE-stream `events` domain. No wire
+ * envelope: the carrier's GET routes answer these directly, and the browser
+ * `IApiClient` never exposes them.
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/** Host-only download surfaces (no wire envelope; absent from IApiClient). */
+export interface DownloadsApi {
+  /**
+   * Stream one session-log ZIP — the root artifact verbatim plus each subagent
+   * descendant's — as an attachment response. The carrier's GET route answers
+   * this directly; the browser never calls it.
+   * @param request - the root session id and whether to include descendants.
+   * @param signal - cancellation for the underlying reads.
+   * @returns the ZIP attachment response; missing services answer 500 and a
+   * missing root session 404 before any byte is produced.
+   */
+  sessionLog(
+    request: { sessionId: SessionId; includeDescendants?: boolean },
+    signal: AbortSignal,
+  ): Promise<Response>
+}

packages/host/apiproxy/src/api/events.schema.ts

@@ -13,9 +13,10 @@ import { approvalRequestIdSchema } from './approvals.schema.ts'
 import {
   contentBlockSchema, messageIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema,
 } from './sessions.schema.ts'
+import { taskViewSchema } from './tasks.schema.ts'
 import { workspaceIdSchema, workspaceViewSchema } from './workspace.schema.ts'
 
-/** Question shape validated strictly against core dsh-user-interaction. */
+/** Question fields validated strictly against core dsh-user-interaction. */
 export const askUserQuestionItemSchema = z.object({
   id: z.string(),
   question: z.string(),
@@ -58,6 +59,7 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
       message: messageSchema,
     })),
   }),
+  z.object({ type: z.literal('session/tasks'), sessionId: sessionIdSchema, tasks: z.array(taskViewSchema) }),
   // value stays wide: it already passed its unit's own schema on the host,
   // and deep-validating here would import every domain's schema into the carrier.
   z.object({ type: z.literal('session/projection'), sessionId: sessionIdSchema, key: z.string().min(1), value: z.unknown(), seq: z.number().int().nonnegative() }),
@@ -73,6 +75,7 @@ export const hostFrameSchema = z.discriminatedUnion('type', [
     parentSessionId: sessionIdSchema.optional(),
     origin: z.literal('subagent').optional(),
     cwd: z.string().optional(),
+    agentPreset: z.string().optional(),
   }),
   z.object({ type: z.literal('host/session-removed'), sessionId: sessionIdSchema }),
   z.object({ type: z.literal('host/session-status'), sessionId: sessionIdSchema, running: z.boolean() }),
@@ -81,6 +84,7 @@ export const hostFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('host/workspace-removed'), workspaceId: workspaceIdSchema }),
   z.object({ type: z.literal('host/archived-sessions-changed'), archivedSessionIds: z.array(sessionIdSchema) }),
   z.object({ type: z.literal('host/commands-changed') }),
+  z.object({ type: z.literal('host/session-preset-changed'), sessionId: sessionIdSchema, agentPreset: z.string() }),
   z.object({ type: z.literal('host/settings-changed'), ns: z.string() }),
   z.object({ type: z.literal('host/credentials-changed'), ref: z.string() }),
   z.object({ type: z.literal('host/models-changed') }),

packages/host/apiproxy/src/api/events.ts

@@ -14,6 +14,7 @@ import type { CallId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 import type { RpcError, RpcId, RpcRequest } from './rpc.ts'
+import type { TaskView } from './tasks.ts'
 import type { WorkspaceView } from './workspace.ts'
 
 // Client-side consumers take the render-intent vocabulary from the contract;
@@ -81,6 +82,20 @@ export type MuxFrame =
    * in QueueDock, while pending steering renders at the conversation tail.
    */
   | { type: 'session/queue'; sessionId: SessionId; items: QueuedInboxItem[] }
+  /**
+   * Complete set of background tasks this session can see, after every registry
+   * commit that changes it: registration, the stopping transition, settlement,
+   * and owner-disposal removal. The registry is process-local and holds no
+   * durable event, so — exactly like `session/queue` — the whole snapshot is
+   * what makes a start, a kill, a reconnect, and a second tab converge on one
+   * authoritative value.
+   *
+   * Sent as a subscription baseline only for a session that currently has
+   * tasks; an absent key means an empty set. A change that empties the set
+   * still sends `[]`, since that transition is the only one absence cannot
+   * express.
+   */
+  | { type: 'session/tasks'; sessionId: SessionId; tasks: TaskView[] }
   /**
    * One projection unit's finished value changed (session-projection RFC).
    * Live push state, never logged — replay recomputes on the host (the
@@ -116,6 +131,7 @@ export type HostFrame =
     parentSessionId?: SessionId
     origin?: 'subagent'
     cwd?: string
+    agentPreset?: string
   }
   | { type: 'host/session-removed'; sessionId: SessionId }
   | { type: 'host/session-status'; sessionId: SessionId; running: boolean }
@@ -129,6 +145,18 @@ export type HostFrame =
    * background rather than diffing.
    */
   | { type: 'host/commands-changed' }
+  /**
+   * One blank session was recomposed onto another agent preset (the logged
+   * `agent-preset/selected` commit point, read off the session stream). The
+   * registry-wide `host/commands-changed` cannot stand in for it: recomposing
+   * re-parents that agent's scope without registering anything, so a
+   * preset already mounted for another session produces no registry change
+   * at all. Clients refetch the catalogs this session's composition decides
+   * (`command.list`, `skill.list`) for this sessionId alone, and fold the
+   * preset id into their session row — the RPC echo reaches only the client
+   * that issued the switch, so the row is where every other one learns it.
+   */
+  | { type: 'host/session-preset-changed'; sessionId: SessionId; agentPreset: string }
   /**
    * One settings namespace's resolved value changed (`settings/updated`
    * passthrough) — an RPC write, an external `settings.yaml` edit, or a

packages/host/apiproxy/src/api/host.schema.ts

@@ -17,8 +17,6 @@ export const hostDescribeValueSchema = z.object({
   provider: z.string().optional(),
   model: z.string().optional(),
   attachedSessions: z.number().int().nonnegative(),
-  // Open string, not a literal union: unknown kinds must survive the wire so
-  // a merge-added capability can advertise (the client hides the affordance).
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>
 
 /** host.pickDirectory request payload (empty object literal). */

packages/host/apiproxy/src/api/index.ts

@@ -8,6 +8,7 @@ import type { SessionsApi } from './sessions.ts'
 import type { HostApi } from './host.ts'
 import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
+import type { AgentPresetsApi } from './agent-presets.ts'
 import type { SkillsApi } from './skills.ts'
 import type { SubagentsApi } from './subagents.ts'
 import type { EventsApi } from './events.ts'
@@ -15,9 +16,10 @@ import type { GoalsApi } from './goals.ts'
 import type { SettingsApi } from './settings.ts'
 import type { CredentialsApi } from './credentials.ts'
 import type { LlmApi } from './llm.ts'
+import type { DownloadsApi } from './downloads.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
 
-/** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
+/** Root interface of the unified API. New client-request domain = one new file pair + one field here + one map row. */
 export interface ApiProxy {
   sessions: SessionsApi
   subagents: SubagentsApi
@@ -25,11 +27,14 @@ export interface ApiProxy {
   workspace: WorkspaceApi
   commands: CommandsApi
   skills: SkillsApi
+  agentPresets: AgentPresetsApi
   events: EventsApi
   goals: GoalsApi
   settings: SettingsApi
   credentials: CredentialsApi
   llm: LlmApi
+  /** Host-only download surfaces (GET, no wire envelope); absent from IApiClient. */
+  downloads: DownloadsApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
   respond(message: ClientResponse): Promise<RpcReceipt>
 }
@@ -37,22 +42,25 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelSelection, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
-  SessionsApi, SessionSummary,
+  ModelReasoningEffort, ModelSelection, PromptContentPart, QueueAction, SessionModels,
+  SessionProjectionsBlock, SessionSearchItem, SessionsApi, SessionSummary,
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
 export type {
   SubagentAddress, SubagentCatalog, SubagentInterruptReceipt, SubagentListEntry,
   SubagentPromptReceipt, SubagentsApi,
 } from './subagents.ts'
+export type { TaskView } from './tasks.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'
+export type { AgentPresetsApi, AgentPresetEntry } from './agent-presets.ts'
 export type { EventsApi, MuxFrame, HostFrame, QueuedInboxItem, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
 export type { GoalsApi, GoalId, GoalRef } from './goals.ts'
 export type { SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView } from './settings.ts'
 export type { CredentialsApi, CredentialView } from './credentials.ts'
 export type { ConfigurableProviderView, DiscoveredModelView, LlmApi } from './llm.ts'
+export type { DownloadsApi } from './downloads.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
 
 export type { QuestionResponsePayload } from './questions.ts'

packages/host/apiproxy/src/api/rpc-map.ts

@@ -8,6 +8,7 @@ import type { SessionsApi } from './sessions.ts'
 import type { HostApi } from './host.ts'
 import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
+import type { AgentPresetsApi } from './agent-presets.ts'
 import type { SkillsApi } from './skills.ts'
 import type { GoalsApi } from './goals.ts'
 import type { SettingsApi } from './settings.ts'
@@ -31,6 +32,7 @@ export interface RpcMethodMap {
   'session.rename': SessionsApi['rename']
   'session.fork': SessionsApi['fork']
   'session.prompt': SessionsApi['prompt']
+  'session.attachment': SessionsApi['attachment']
   'session.updateQueue': SessionsApi['updateQueue']
   'session.cancel': SessionsApi['cancel']
   'subagent.list': SubagentsApi['list']
@@ -51,6 +53,12 @@ export interface RpcMethodMap {
   'command.list': CommandsApi['list']
   'command.execute': CommandsApi['execute']
   'skill.list': SkillsApi['list']
+  'agentPreset.list': AgentPresetsApi['list']
+  'agentPreset.select': AgentPresetsApi['select']
+  'agentPreset.read': AgentPresetsApi['read']
+  'agentPreset.copy': AgentPresetsApi['copy']
+  'agentPreset.openDocument': AgentPresetsApi['openDocument']
+  'agentPreset.remove': AgentPresetsApi['remove']
   'goal.create': GoalsApi['create']
   'goal.edit': GoalsApi['edit']
   'goal.pause': GoalsApi['pause']

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -23,8 +23,8 @@ export type Wire<T> = T extends readonly (infer E)[] ? Wire<E>[]
     : T
 
 /**
- * RpcId: one brand cast after shape validation (the only cast point in this
- * file). No min-length: the id is an opaque echo token, and rejecting shapes
+ * RpcId: one brand cast after schema validation (the only cast point in this
+ * file). No min-length: the id is an opaque echo token, and rejecting values
  * here would only turn a correlatable error report into a client-side parse
  * failure (the handler substitutes a sentinel when a request's id is unreadable).
  */
@@ -47,7 +47,13 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('directory-exists'), message: z.string(), details: z.object({ path: z.string() }) }),
   z.object({ code: z.literal('directory-create-failed'), message: z.string(), details: z.object({ path: z.string() }) }),
   z.object({ code: z.literal('directory-picker-unavailable'), message: z.string(), details: z.object({ capability: z.string() }) }),
+  z.object({ code: z.literal('agent-preset-read-only'), message: z.string(), details: z.object({ agentPreset: z.string(), reason: z.string() }) }),
+  z.object({ code: z.literal('agent-preset-locked'), message: z.string(), details: z.object({ sessionId: z.string(), agentPreset: z.string() }) }),
+  z.object({ code: z.literal('agent-preset-conflict'), message: z.string(), details: z.object({ sessionId: z.string(), requestedPreset: z.string(), existingPreset: z.string().optional() }) }),
+  z.object({ code: z.literal('agent-preset-not-found'), message: z.string(), details: z.object({ agentPreset: z.string(), available: z.array(z.string()) }) }),
+  z.object({ code: z.literal('agent-preset-invalid'), message: z.string(), details: z.object({ agentPreset: z.string(), reason: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
+  z.object({ code: z.literal('attachment-error'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('queue-item-not-found'), message: z.string(), details: z.object({ itemId: z.string() }) }),
   z.object({ code: z.literal('steer-unavailable'), message: z.string(), details: z.object({ itemId: z.string() }) }),
   z.object({ code: z.literal('command-error'), message: z.string(), details: z.object({}) }),

packages/host/apiproxy/src/api/rpc.ts

@@ -45,7 +45,13 @@ export interface RpcErrorDetailsMap {
   'directory-exists': { path: string }
   'directory-create-failed': { path: string }
   'directory-picker-unavailable': { capability: string }
+  'agent-preset-read-only': { agentPreset: string; reason: string }
+  'agent-preset-locked': { sessionId: SessionId; agentPreset: string }
+  'agent-preset-conflict': { sessionId: SessionId; requestedPreset: string; existingPreset?: string }
+  'agent-preset-not-found': { agentPreset: string; available: string[] }
+  'agent-preset-invalid': { agentPreset: string; reason: string }
   'agent-busy': { reason: string }
+  'attachment-error': { reason: string }
   'queue-item-not-found': { itemId: MessageId }
   'steer-unavailable': { itemId: MessageId }
   /** A known slash command reported a usage/state error; the message is the command's own text. */
@@ -111,7 +117,7 @@ export type RpcResult<T> = { ok: true; value: T } | { ok: false; error: RpcError
 
 /**
  * Fold a transport exception into the RpcResult error branch (unified error
- * surface; 'internal' as the catch-all code). Lives with RpcResult so every
+ * API; 'internal' as the catch-all code). Lives with RpcResult so every
  * carrier consumer folds the same way.
  * @param error - the thrown value from the carrier.
  * @returns the error branch of an RpcResult.

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -1,7 +1,7 @@
 /**
  * sessions domain zod schemas (names derived from map keys: sessionListRequestSchema /
  * sessionListValueSchema). SessionEvent passthrough = strict envelope (type/seq/time) + wide
- * data: the merge-extensible event surface keeps an unknown-type branch at the union level,
+ * data: the merge-extensible event API keeps an unknown-type branch at the union level,
  * with no field-level passthrough. SessionId brand cast point: sessionIdSchema, and only there.
  */
 
@@ -15,6 +15,7 @@ import type {
   ModelReasoningEffort, ModelSelection, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
+import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type { WorkspaceId } from './workspace.ts'
 import {
   SESSION_SEARCH_RESULT_LIMIT,
@@ -22,7 +23,7 @@ import {
   truncateUnicodeCodePoints,
 } from './session-search.ts'
 
-/** SessionId: one brand cast after shape validation (the only cast point in this domain). */
+/** SessionId: one brand cast after schema validation (the only cast point in this domain). */
 export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>
 
 /** MessageId: one brand cast after non-empty string validation. */
@@ -44,6 +45,7 @@ export const sessionEventSchema = z.object({
   data: z.unknown(),
   sourceEventSeqs: z.array(z.number()).optional(),
   surfaceOp: z.unknown().optional(),
+  ignorable: z.literal(true).optional(),
 }) as unknown as z.ZodType<SessionEvent>
 
 /** SessionSummary row of session.list (`projections` reuses the history block's shape and schema). */
@@ -55,6 +57,7 @@ export const sessionSummarySchema = z.object({
   parentSessionId: sessionIdSchema.optional(),
   origin: z.literal('subagent').optional(),
   cwd: z.string().optional(),
+  agentPreset: z.string().optional(),
   projections: z.lazy(() => sessionProjectionsBlockSchema).optional(),
 }) as unknown as z.ZodType<Wire<SessionSummary>>
 
@@ -100,6 +103,7 @@ export const sessionCreateRequestSchema = z.object({
   workspaceId: workspaceIdSchema.optional(),
   cwd: z.string().optional(),
   sessionId: sessionIdSchema.optional(),
+  agentPreset: z.string().optional(),
 }).refine(
   payload => payload.workspaceId === undefined || payload.cwd === undefined,
   { message: 'session.create accepts workspaceId or cwd, not both' },
@@ -108,6 +112,7 @@ export const sessionCreateRequestSchema = z.object({
 /** session.create response value. */
 export const sessionCreateValueSchema = z.object({
   sessionId: sessionIdSchema,
+  agentPreset: z.string().optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.create'>>>
 
 /** session.rename request payload (raw title; host-side normalization decides acceptance). */
@@ -246,11 +251,25 @@ export const sessionSelectModelValueSchema = z.object({
 /** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
 export const contentBlockSchema = z.looseObject({ type: z.string() })
 
+/** Raster image media types accepted by the version-one browser wire. */
+export const imageMediaTypeSchema = z.union([
+  z.literal('image/png'),
+  z.literal('image/jpeg'),
+  z.literal('image/webp'),
+  z.literal('image/gif'),
+])
+
+/** Prompt wire content is intentionally narrower than merge-extensible durable core content. */
+export const promptContentPartSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('text'), text: z.string() }),
+  z.object({ type: z.literal('image'), mediaType: imageMediaTypeSchema, data: z.string(), name: z.string().optional() }),
+])
+
 /** session.prompt request payload, including optional browser-local request provenance. */
 export const sessionPromptRequestSchema = z.object({
   sessionId: sessionIdSchema,
   mode: z.union([z.literal('queue'), z.literal('steer')]),
-  content: z.array(contentBlockSchema),
+  content: z.array(promptContentPartSchema),
   clientTimeZone: z.string().optional(),
 }) as unknown as z.ZodType<RequestPayload<'session.prompt'>>
 
@@ -263,6 +282,31 @@ export const sessionPromptValueSchema = z.object({
   }).optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.prompt'>>>
 
+/** Opaque attachment id after string-shape validation. */
+export const attachmentIdSchema = z.string().min(1) as unknown as z.ZodType<AttachmentIdType>
+
+/** Durable image reference returned from the authenticated session lookup. */
+export const imageAttachmentRefSchema = z.object({
+  attachmentId: attachmentIdSchema,
+  mediaType: imageMediaTypeSchema,
+  bytes: z.number().int().positive(),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  name: z.string().optional(),
+}) as unknown as z.ZodType<ImageAttachmentRef>
+
+/** session.attachment request payload. */
+export const sessionAttachmentRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  attachmentId: attachmentIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.attachment'>>>
+
+/** session.attachment response value. */
+export const sessionAttachmentValueSchema = z.object({
+  attachment: imageAttachmentRefSchema,
+  data: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.attachment'>>>
+
 /** session.updateQueue request payload. */
 export const sessionUpdateQueueRequestSchema = z.object({
   sessionId: sessionIdSchema,

packages/host/apiproxy/src/api/sessions.ts

@@ -5,6 +5,7 @@
  */
 
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+import type { AttachmentIdType, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 // The pure-type outlet: api/ is browser-importable, and the package root's
@@ -54,6 +55,11 @@ export interface SessionProjectionsBlock {
   values: Partial<SessionProjectionMap>
 }
 
+/** Browser-submitted prompt content; the host promotes image bytes to durable references. */
+export type PromptContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; mediaType: ImageMediaType; data: string; name?: string }
+
 /** Complete model selection for one session. */
 export interface ModelSelection {
   /** Registered provider route. */
@@ -166,6 +172,13 @@ export interface SessionSummary {
   origin?: 'subagent'
   /** Session working directory (header.cwd passthrough); absent when unrecorded. */
   cwd?: string
+  /**
+   * Agent preset this session's agent was composed from (header passthrough);
+   * absent when the deployment composes no presets. A surface offering a
+   * switch reads this to show what the session actually runs rather than what
+   * the deployment currently defaults to.
+   */
+  agentPreset?: string
   /**
    * Projection baseline for this row, with zero log loads: attached sessions
    * read the registry's live watermark cut; cold sessions read the persisted
@@ -209,9 +222,16 @@ export interface SessionsApi {
    * session, while a different cwd fails with `session-conflict`. Workspace
    * creation attaches the session after publication; an attach failure
    * returns `workspace-attach-failed` with the published session id.
+   *
+   * `agentPreset` names the composition the new session's agent is built
+   * from; omitted, the effective default applies — the user's stored choice
+   * where one exists, else the deployment's own. The resolved id is stored on
+   * the session header, so a later resume rebuilds the same agent. An unknown
+   * id fails with `agent-preset-not-found`, and a preset whose composition
+   * cannot be mounted fails with `agent-preset-invalid`.
    */
-  create(request: RpcRequest<{ workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId }>):
-  Promise<RpcResponse<{ sessionId: SessionId }>>
+  create(request: RpcRequest<{ workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId; agentPreset?: string }>):
+  Promise<RpcResponse<{ sessionId: SessionId; agentPreset?: string }>>
 
   /**
    * Reads a window of history events; page boundaries align to append-origin message
@@ -290,7 +310,8 @@ export interface SessionsApi {
   Promise<RpcResponse<{ sessionId: SessionId }>>
 
   /**
-   * Sends a message to an ordinary session Agent. Browser callers attach their current IANA zone;
+   * Sends text and temporary image bytes to an ordinary session Agent after durable host admission.
+   * Browser callers attach their current IANA zone;
    * the Host validates, canonicalizes, and records it on that exact user message. Omission remains
    * valid for non-browser callers. Session-backed subagents reject with `agent-busy` and use
    * `subagent.prompt`.
@@ -298,11 +319,15 @@ export interface SessionsApi {
   prompt(request: RpcRequest<{
     sessionId: SessionId
     mode: 'queue' | 'steer'
-    content: ContentBlock[]
+    content: PromptContentPart[]
     clientTimeZone?: string
   }>):
   Promise<RpcResponse<{ accepted: true; command?: { kind: 'success'; text?: string } }>>
 
+  /** Reads one durable image after proving that this session's log references its id. */
+  attachment(request: RpcRequest<{ sessionId: SessionId; attachmentId: AttachmentIdType }>):
+  Promise<RpcResponse<{ attachment: ImageAttachmentRef; data: string }>>
+
   /**
    * Edits, removes, or strictly steers one pending queued occurrence on an ordinary session.
    * Session-backed subagents reject with `agent-busy`.

packages/host/apiproxy/src/api/tasks.schema.ts

@@ -0,0 +1,33 @@
+/**
+ * tasks domain zod schemas: the branded task id and the wire view carried by
+ * `session/tasks` frames.
+ */
+
+import { z } from 'zod'
+import type { TaskId } from '@deepseek-ai/dsh-tasks/brand'
+import type { TaskView } from './tasks.ts'
+import type { Wire } from './rpc.schema.ts'
+
+/** TaskId: one brand cast after non-empty string validation. */
+export const taskIdSchema = z.string().min(1) as unknown as z.ZodType<TaskId>
+
+/**
+ * One wire task view. `kind` stays an open string because producer plugins
+ * extend the registry's kind map by declaration merging, so the closed set is
+ * not knowable at this boundary.
+ */
+export const taskViewSchema = z.object({
+  id: taskIdSchema,
+  kind: z.string().min(1),
+  label: z.string().min(1),
+  status: z.union([
+    z.literal('running'),
+    z.literal('stopping'),
+    z.literal('completed'),
+    z.literal('killed'),
+    z.literal('failed'),
+  ]),
+  detail: z.string().optional(),
+  startedAt: z.number().int().nonnegative(),
+  finishedAt: z.number().int().nonnegative().optional(),
+}) satisfies z.ZodType<Wire<TaskView>>

packages/host/apiproxy/src/api/tasks.ts

@@ -0,0 +1,36 @@
+/**
+ * Browser-safe background-task domain contract. The registry's live records
+ * never cross the wire; a view is the subset a human list needs, minted fresh
+ * per push.
+ */
+
+import type { TaskId } from '@deepseek-ai/dsh-tasks/brand'
+
+/**
+ * One background task as the client sees it.
+ *
+ * Three registry fields are deliberately absent. `ownerSession` is redundant
+ * beside the frame's own `sessionId`; `reported` is an internal notice-delivery
+ * bit with no user meaning; `outputLimitBytes` is producer-owned model
+ * presentation policy that never reaches a human surface.
+ */
+export interface TaskView {
+  /** Registry-issued `<kind>-N` identity, stable for the task's whole life. */
+  id: TaskId
+  /**
+   * Producer kind (`bash`, `pwsh`, `pty-send`, `subagent`, …). Kept as a bare
+   * string because producer plugins extend the kind map by declaration merging,
+   * so no client build can enumerate the closed set.
+   */
+  kind: string
+  /** Producer-supplied one-line label: the command, or the delegation description. */
+  label: string
+  /** Current lifecycle state. */
+  status: 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
+  /** Kind-specific status detail ('exit code: 3'), present once the producer supplied one. */
+  detail?: string
+  /** Epoch ms when the task was registered. */
+  startedAt: number
+  /** Epoch ms when the task settled; absent while live. */
+  finishedAt?: number
+}

packages/host/apiproxy/src/api/workspace.schema.ts

@@ -31,14 +31,10 @@ export const workspaceListValueSchema = z.object({
   archivedSessionIds: z.array(sessionIdSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'workspace.list'>>>
 
-/** workspace.create request payload: exactly one of path/name (the contract's create spellings). */
+/** workspace.create request payload: the existing directory to adopt. */
 export const workspaceCreateRequestSchema = z.object({
-  path: z.string().optional(),
-  name: z.string().optional(),
-}).refine(
-  payload => (payload.path === undefined) !== (payload.name === undefined),
-  { message: 'workspace.create requires exactly one of path / name' },
-) satisfies z.ZodType<Wire<RequestPayload<'workspace.create'>>>
+  path: z.string(),
+}) satisfies z.ZodType<Wire<RequestPayload<'workspace.create'>>>
 
 /** workspace.create response value. */
 export const workspaceCreateValueSchema = z.object({

packages/host/apiproxy/src/api/workspace.ts

@@ -46,19 +46,14 @@ export interface WorkspaceApi {
   list(request: RpcRequest<{}>): Promise<RpcResponse<{ items: WorkspaceView[]; archivedSessionIds: SessionId[] }>>
 
   /**
-   * Creates (or idempotently resolves) a workspace. Exactly one of `path` /
-   * `name` (schema-enforced): `path` registers an EXISTING directory (no
-   * mkdir — a missing or non-directory path fails with `workspace-invalid-path`);
-   * `name` is a single path segment the host mkdirs under its default project
-   * root before registering. Either spelling resolving to a directory already
-   * owned by a workspace returns that workspace (`created: false`) for the
-   * existing-folder spelling. Create-by-name rejects an existing title with
-   * `workspace-name-conflict`; path adoption allows distinct canonical paths
-   * whose basenames produce the same display title.
-   * A new name-created workspace uses `name` as both directory name and title;
-   * a path-created workspace uses the registry's basename title default.
+   * Creates (or idempotently resolves) a workspace over an EXISTING directory
+   * (no mkdir — a missing or non-directory path fails with
+   * `workspace-invalid-path`). A path resolving to a directory already owned
+   * by a workspace returns that workspace (`created: false`). Adoption allows
+   * distinct canonical paths whose basenames produce the same display title;
+   * the registry's basename title default names the new workspace.
    */
-  create(request: RpcRequest<{ path?: string; name?: string }>):
+  create(request: RpcRequest<{ path: string }>):
   Promise<RpcResponse<{ workspace: WorkspaceView; created: boolean }>>
 
   /**

packages/host/apiproxy/src/fetch/client.ts

@@ -19,6 +19,7 @@ import {
 } from '../api/host.schema.ts'
 import {
   sessionCancelValueSchema,
+  sessionAttachmentValueSchema,
   sessionCreateValueSchema,
   sessionForkValueSchema,
   sessionHistoryValueSchema,
@@ -40,6 +41,10 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
 import { skillListValueSchema } from '../api/skills.schema.ts'
+import {
+  agentPresetCopyValueSchema, agentPresetListValueSchema, agentPresetOpenDocumentValueSchema,
+  agentPresetReadValueSchema, agentPresetRemoveValueSchema, agentPresetSelectValueSchema,
+} from '../api/agent-presets.schema.ts'
 import {
   goalCreateValueSchema,
   goalEditValueSchema,
@@ -90,6 +95,7 @@ export interface IApiClient {
     rename(payload: RequestPayload<'session.rename'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.rename'>>>
     fork(payload: RequestPayload<'session.fork'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.fork'>>>
     prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
+    attachment(payload: RequestPayload<'session.attachment'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.attachment'>>>
     updateQueue(payload: RequestPayload<'session.updateQueue'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.updateQueue'>>>
     cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
   }
@@ -121,6 +127,14 @@ export interface IApiClient {
   skills: {
     list(payload: RequestPayload<'skill.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'skill.list'>>>
   }
+  agentPresets: {
+    list(payload: RequestPayload<'agentPreset.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.list'>>>
+    select(payload: RequestPayload<'agentPreset.select'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.select'>>>
+    read(payload: RequestPayload<'agentPreset.read'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.read'>>>
+    copy(payload: RequestPayload<'agentPreset.copy'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.copy'>>>
+    openDocument(payload: RequestPayload<'agentPreset.openDocument'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.openDocument'>>>
+    remove(payload: RequestPayload<'agentPreset.remove'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.remove'>>>
+  }
   events: {
     mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
     host(payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>
@@ -168,6 +182,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.rename': sessionRenameValueSchema,
   'session.fork': sessionForkValueSchema,
   'session.prompt': sessionPromptValueSchema,
+  'session.attachment': sessionAttachmentValueSchema,
   'session.updateQueue': sessionUpdateQueueValueSchema,
   'session.cancel': sessionCancelValueSchema,
   'subagent.list': subagentListValueSchema,
@@ -188,6 +203,12 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'command.list': commandListValueSchema,
   'command.execute': commandExecuteValueSchema,
   'skill.list': skillListValueSchema,
+  'agentPreset.list': agentPresetListValueSchema,
+  'agentPreset.select': agentPresetSelectValueSchema,
+  'agentPreset.read': agentPresetReadValueSchema,
+  'agentPreset.copy': agentPresetCopyValueSchema,
+  'agentPreset.openDocument': agentPresetOpenDocumentValueSchema,
+  'agentPreset.remove': agentPresetRemoveValueSchema,
   'goal.create': goalCreateValueSchema,
   'goal.edit': goalEditValueSchema,
   'goal.pause': goalPauseValueSchema,
@@ -390,7 +411,7 @@ export abstract class AbstractApiClient implements IApiClient {
     }
   }
 
-  // ---- IApiClient surface (arrow properties so destructured/passed references stay bound) ----
+  // ---- IApiClient API (arrow properties so destructured/passed references stay bound) ----
 
   readonly sessions: IApiClient['sessions'] = {
     list: (payload, signal) => this.callUnary('session.list', payload, signal),
@@ -402,6 +423,7 @@ export abstract class AbstractApiClient implements IApiClient {
     rename: (payload, signal) => this.callUnary('session.rename', payload, signal),
     fork: (payload, signal) => this.callUnary('session.fork', payload, signal),
     prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
+    attachment: (payload, signal) => this.callUnary('session.attachment', payload, signal),
     updateQueue: (payload, signal) => this.callUnary('session.updateQueue', payload, signal),
     cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
   }
@@ -447,6 +469,20 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('skill.list', payload, signal),
   }
 
+  // Annotated like every sibling, and load-bearing rather than cosmetic:
+  // inferring this member inlines `AgentPresetEntry` into the emitted
+  // declaration by the specifier TS picks — the host `index.ts` — which drags
+  // the whole gateway, and with it the host `Context` merges, into every
+  // Client program that imports this carrier.
+  readonly agentPresets: IApiClient['agentPresets'] = {
+    list: (payload, signal) => this.callUnary('agentPreset.list', payload, signal),
+    select: (payload, signal) => this.callUnary('agentPreset.select', payload, signal),
+    read: (payload, signal) => this.callUnary('agentPreset.read', payload, signal),
+    copy: (payload, signal) => this.callUnary('agentPreset.copy', payload, signal),
+    openDocument: (payload, signal) => this.callUnary('agentPreset.openDocument', payload, signal),
+    remove: (payload, signal) => this.callUnary('agentPreset.remove', payload, signal),
+  }
+
   readonly goals: IApiClient['goals'] = {
     create: (payload, signal) => this.callUnary('goal.create', payload, signal),
     edit: (payload, signal) => this.callUnary('goal.edit', payload, signal),

packages/host/apiproxy/src/fetch/handler.ts

@@ -9,6 +9,7 @@
 import { randomUUID } from 'node:crypto'
 import type { z } from 'zod'
 import type { ApiProxy, MuxFrame, HostFrame } from '../api/index.ts'
+import { sessionLogQuerySchema } from '../api/downloads.schema.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '../api/rpc-map.ts'
 import type { ClientRequest, RpcError, RpcRequest, RpcResponse, ServerRequest, ServerResponse } from '../api/rpc.ts'
 import { RpcId } from '../api/rpc.ts'
@@ -16,6 +17,7 @@ import type { Wire } from '../api/rpc.schema.ts'
 import { clientRequestSchema, clientResponseSchema } from '../api/rpc.schema.ts'
 import {
   sessionCancelRequestSchema,
+  sessionAttachmentRequestSchema,
   sessionCreateRequestSchema,
   sessionForkRequestSchema,
   sessionHistoryRequestSchema,
@@ -42,6 +44,10 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
 import { skillListRequestSchema } from '../api/skills.schema.ts'
+import {
+  agentPresetCopyRequestSchema, agentPresetListRequestSchema, agentPresetOpenDocumentRequestSchema,
+  agentPresetReadRequestSchema, agentPresetRemoveRequestSchema, agentPresetSelectRequestSchema,
+} from '../api/agent-presets.schema.ts'
 import {
   goalCreateRequestSchema,
   goalEditRequestSchema,
@@ -91,6 +97,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.rename': { schema: sessionRenameRequestSchema, invoke: (api, r) => api.sessions.rename(r) },
   'session.fork': { schema: sessionForkRequestSchema, invoke: (api, r) => api.sessions.fork(r) },
   'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
+  'session.attachment': { schema: sessionAttachmentRequestSchema, invoke: (api, r) => api.sessions.attachment(r) },
   'session.updateQueue': { schema: sessionUpdateQueueRequestSchema, invoke: (api, r) => api.sessions.updateQueue(r) },
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
   'subagent.list': { schema: subagentListRequestSchema, invoke: (api, r, signal) => api.subagents.list(r, signal) },
@@ -111,6 +118,12 @@ const UNARY_ROUTES: UnaryRoutes = {
   'command.list': { schema: commandListRequestSchema, invoke: (api, r) => api.commands.list(r) },
   'command.execute': { schema: commandExecuteRequestSchema, invoke: (api, r, signal) => api.commands.execute(r, signal) },
   'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
+  'agentPreset.list': { schema: agentPresetListRequestSchema, invoke: (api, r) => api.agentPresets.list(r) },
+  'agentPreset.select': { schema: agentPresetSelectRequestSchema, invoke: (api, r) => api.agentPresets.select(r) },
+  'agentPreset.read': { schema: agentPresetReadRequestSchema, invoke: (api, r) => api.agentPresets.read(r) },
+  'agentPreset.copy': { schema: agentPresetCopyRequestSchema, invoke: (api, r) => api.agentPresets.copy(r) },
+  'agentPreset.openDocument': { schema: agentPresetOpenDocumentRequestSchema, invoke: (api, r, signal) => api.agentPresets.openDocument(r, signal) },
+  'agentPreset.remove': { schema: agentPresetRemoveRequestSchema, invoke: (api, r) => api.agentPresets.remove(r) },
   'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
   'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },
   'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },
@@ -237,12 +250,23 @@ export function toFetchHandler(api: ApiProxy): { fetch: typeof fetch } {
       const url = new URL(req.url)
       const path = url.pathname
 
+      // No-envelope GET channel surface (SSE streams + host-only download):
+      // physical routes that answer directly, without a wire envelope.
       if (path === '/api/events.mux' && req.method === 'GET') {
         return sseResponse(api.events.mux({ rpcId: RpcId(randomUUID()), payload: {} }, req.signal))
       }
       if (path === '/api/events.host' && req.method === 'GET') {
         return sseResponse(api.events.host({ rpcId: RpcId(randomUUID()), payload: {} }, req.signal))
       }
+      if (path === '/api/session.export' && req.method === 'GET') {
+        // Query params are a different boundary from the POST envelope, but
+        // the request still casts its brands only through the domain schema.
+        const parsed = sessionLogQuerySchema.safeParse(Object.fromEntries(url.searchParams))
+        if (!parsed.success) {
+          return new Response('missing or invalid sessionId query parameter', { status: 400 })
+        }
+        return api.downloads.sessionLog(parsed.data, req.signal)
+      }
 
       if (req.method !== 'POST' || !path.startsWith('/api/')) {
         return new Response('not found', { status: 404 })

packages/host/apiproxy/src/index.ts

@@ -8,16 +8,19 @@
  * routes — physical carriers wrap `ctx.apiProxy` themselves.
  *
  * The gateway consumes `ctx.agentDefaultModel`, the transport-independent default
- * shared with direct front doors. Switching models persists through that
+ * shared with direct entry points. Switching models persists through that
  * service; sessions that have already logged a selection remain unchanged.
  */
 
-import { resolve } from 'node:path'
-import { Context, Service } from 'cordis'
-import z from 'schemastery'
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
 import type {} from '@deepseek-ai/dsh-agent-default-model'
 import type { ApiProxy } from './api/index.ts'
 import { createApiProxy } from './api-proxy.ts'
+import {
+  DEFAULT_SESSION_LOG_COMPRESSION_LEVEL,
+  type SessionLogCompressionLevel,
+} from './session-export.ts'
 
 export type * from './api/index.ts'
 export { RpcId } from './api/rpc.ts'
@@ -27,32 +30,46 @@ export type { IApiClient } from './fetch/client.ts'
 export { createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'
 
-declare module 'cordis' {
+declare module '@deepseek-ai/cordis' {
   interface Context {
     /** The host-side ApiProxy implementation (the transport-agnostic gateway face). */
     apiProxy: ApiProxy
   }
 }
 
-/** Gateway plugin config: the Host-only Workspace creation root. */
+/** Gateway plugin configuration. */
 export interface Config {
-  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
-  workspaceRoot?: string
+  /**
+   * Whether this deployment can hand paths to a native desktop opener —
+   * the `hasDocument` capability the agent-preset roster reports. Absent,
+   * the platform is asked (macOS/Windows/WSL yes; Linux only with a display
+   * server); set it explicitly where detection misleads, e.g. `false` in a
+   * container whose DISPLAY points nowhere a user can see.
+   */
+  nativeOpen?: boolean
+  /**
+   * DEFLATE level for every session-log ZIP entry: `0` stores without
+   * compression, `1` favors CPU/latency, and `9` favors archive size.
+   * @default 6
+   */
+  sessionExportCompressionLevel?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 }
 
 /**
  * The API gateway service: implements the ApiProxy contract over the composed
  * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
- * project directory and the fallback parent for name-created Workspaces.
+ * project directory.
  */
 export class ApiProxyService extends Service implements ApiProxy {
   static inject = [
-    'agentDefaultModel', 'agents', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
+    'agentDefaultModel', 'agents', 'attachments', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
     'tools', 'userInteraction', 'workspace',
   ]
 
   static Config: z<Config> = z.object({
-    workspaceRoot: z.string(),
+    nativeOpen: z.boolean(),
+    sessionExportCompressionLevel: z.number().step(1).min(0).max(9)
+      .default(DEFAULT_SESSION_LOG_COMPRESSION_LEVEL) as z<SessionLogCompressionLevel>,
   })
 
   readonly sessions: ApiProxy['sessions']
@@ -62,20 +79,24 @@ export class ApiProxyService extends Service implements ApiProxy {
   readonly commands: ApiProxy['commands']
   readonly goals: ApiProxy['goals']
   readonly skills: ApiProxy['skills']
+  readonly agentPresets: ApiProxy['agentPresets']
   readonly settings: ApiProxy['settings']
   readonly credentials: ApiProxy['credentials']
   readonly llm: ApiProxy['llm']
   readonly events: ApiProxy['events']
+  readonly downloads: ApiProxy['downloads']
   readonly respond: ApiProxy['respond']
 
   constructor(ctx: Context, config: Config) {
     super(ctx, 'apiProxy')
-    const cwd = process.cwd()
     const api = createApiProxy(ctx, {
       defaultModelSelection: () => ctx.agentDefaultModel.currentSelection(),
       saveDefaultModelSelection: selection => ctx.agentDefaultModel.saveSelection(selection),
-      cwd,
-      workspaceRoot: resolve(config.workspaceRoot ?? cwd),
+      cwd: process.cwd(),
+      ...config.nativeOpen === undefined ? {} : { canOpenPath: () => config.nativeOpen as boolean },
+      ...(config.sessionExportCompressionLevel === undefined
+        ? {}
+        : { sessionExportCompressionLevel: config.sessionExportCompressionLevel }),
     })
     this.sessions = api.sessions
     this.subagents = api.subagents
@@ -84,10 +105,12 @@ export class ApiProxyService extends Service implements ApiProxy {
     this.commands = api.commands
     this.goals = api.goals
     this.skills = api.skills
+    this.agentPresets = api.agentPresets
     this.settings = api.settings
     this.credentials = api.credentials
     this.llm = api.llm
     this.events = api.events
+    this.downloads = api.downloads
     // createApiProxy returns closures (no `this` capture), so the bind is
     // behavior-neutral.
     this.respond = api.respond.bind(api)

packages/host/apiproxy/src/invariant.ts

@@ -4,7 +4,7 @@
  */
 
 /* jscpd:ignore-start */
-import type { Context } from 'cordis'
+import type { Context } from '@deepseek-ai/cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-host-apiproxy'

packages/host/apiproxy/src/native-path-opener.ts

@@ -152,6 +152,25 @@ async function openNativePathWithIntent(
   throw new Error(`native path opener is unsupported on ${platform}`)
 }
 
+/**
+ * Whether {@link openNativePath} plausibly reaches a desktop on this host.
+ *
+ * macOS and Windows always carry a desktop opener; Linux does when it is WSL
+ * (the Windows desktop takes the path) or a display server is announced.
+ * A headless or containerised Linux host answers false, which is what lets a
+ * surface show a path as text instead of offering a button that would spawn
+ * `xdg-open` into nothing.
+ * @param internals - platform and environment seam for deterministic tests.
+ * @returns true when handing a path to the native opener can work at all.
+ */
+export function canOpenNativePath(internals: PathOpenerInternals = {}): boolean {
+  const platform = internals.platform ?? process.platform
+  if (platform === 'darwin' || platform === 'win32') return true
+  if (platform !== 'linux') return false
+  const env = internals.env ?? process.env
+  return isWsl(internals) || present(env.DISPLAY) || present(env.WAYLAND_DISPLAY)
+}
+
 /**
  * Open a filesystem path with the operating system's default application, or
  * with the default browser when the path names a document a browser renders.

packages/host/apiproxy/src/session-export.ts

@@ -0,0 +1,457 @@
+/**
+ * Host-side session-log download: streams one ZIP archive whose files are the
+ * sessions' stored artifact text verbatim plus every referenced media object.
+ * The root artifact sits under its original base name (`session.jsonl`); each
+ * subagent descendant under `subagents/<id>/<filename>`; each image referenced
+ * by any included log under `media/<attachmentId>.<ext>` (content-addressed,
+ * so one archive never duplicates a shared image). No manifest is written —
+ * every file is byte-identical to the backend's durable artifact or attachment
+ * store and self-describing through its own header line or media type. Before
+ * each live session's artifact read, the SessionStore flush barrier makes the
+ * current in-memory log durable; cold sessions need no barrier. Request abort
+ * and response-consumer cancellation share one producer signal and terminate
+ * the active compressor.
+ * Compression runs on the host with fflate's streaming Zip API, so the archive
+ * bytes are produced incrementally and the host never holds the whole archive
+ * in one buffer; production waits for consumer pull whenever the response queue
+ * reaches its byte high-water mark, so a slow consumer bounds accumulation to
+ * the fixed 64 KiB response queue plus one synchronous fflate push.
+ * @module
+ */
+
+import { Zip, ZipDeflate } from 'fflate'
+import type { Context } from '@deepseek-ai/cordis'
+import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import type { SessionLineageNode, SessionQueryService } from '@deepseek-ai/dsh-session-query'
+import type { SessionId, SessionStore } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence, SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
+
+/** Valid fflate DEFLATE levels accepted by session-log export. */
+export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+
+/** Balanced default used when a direct createApiProxy caller omits deployment config. */
+export const DEFAULT_SESSION_LOG_COMPRESSION_LEVEL: SessionLogCompressionLevel = 6
+
+/** The services a session-log export needs (the live-session store is optional). */
+export interface SessionLogExportDeps {
+  readonly sessionQuery: SessionQueryService | undefined
+  readonly sessionPersistence: SessionPersistence | undefined
+  readonly attachments: AttachmentStore | undefined
+  readonly sessions: SessionStore | undefined
+}
+
+/** The export services narrowed to the mounted ones streaming actually reads. */
+export interface SessionLogExportReady {
+  readonly sessionQuery: SessionQueryService
+  readonly sessionPersistence: SessionPersistence
+  readonly attachments: AttachmentStore
+  readonly sessions: SessionStore | undefined
+}
+
+/**
+ * Resolve the persistence, session-query, and attachment services a log export needs.
+ * @param ctx - the composed host context.
+ * @returns the export services (absent when the deployment does not mount them).
+ */
+export function sessionLogExportDeps(ctx: Context): SessionLogExportDeps {
+  return {
+    sessionQuery: ctx.get('sessionQuery'),
+    sessionPersistence: ctx.get('sessionPersistence'),
+    attachments: ctx.get('attachments'),
+    sessions: ctx.get('sessions'),
+  }
+}
+
+/**
+ * Flush one currently live session through the store's authoritative durability
+ * barrier immediately before its raw artifact is read. A cold or absent id has
+ * no in-memory work to flush.
+ * @param deps - export services, including the optional live-session store.
+ * @param id - the session whose artifact is about to be read.
+ * @param signal - optional cancellation observed around the flush barrier.
+ */
+export async function flushLiveSessionLog(
+  deps: Pick<SessionLogExportDeps, 'sessions'>,
+  id: SessionId,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted()
+  const sessions = deps.sessions
+  if (sessions === undefined) return
+  const session = sessions.get(id)
+  if (session === undefined) return
+  await sessions.flush(session)
+  signal?.throwIfAborted()
+}
+
+/** One exported file: a stored artifact text or one referenced media object. */
+export type SessionLogZipEntry =
+  | { readonly path: string; readonly content: string }
+  | { readonly path: string; readonly data: Uint8Array }
+
+/** Zip extension for each accepted raster media type. */
+const MEDIA_TYPE_EXTENSIONS: Record<ImageAttachmentRef['mediaType'], string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+}
+
+/**
+ * The zip path for one media object: content-addressed by the opaque
+ * attachment id so shared images land once and the id in the log maps back to
+ * the archive entry without a manifest.
+ * @param ref - the durable reference from a session log.
+ * @returns the archive path.
+ */
+function mediaEntryPath(ref: ImageAttachmentRef): string {
+  return `media/${String(ref.attachmentId)}.${MEDIA_TYPE_EXTENSIONS[ref.mediaType]}`
+}
+
+/**
+ * Collect every image reference inside one content array, descending into
+ * nested tool results the way the live attachment route does.
+ * @param content - an event content array (or nested tool-result content).
+ * @param refs - the dedupe map being filled (keyed by attachment id).
+ */
+function collectImageRefs(content: unknown, refs: Map<string, ImageAttachmentRef>): void {
+  if (!Array.isArray(content)) return
+  const pending: unknown[] = []
+  for (const item of content) pending.push(item)
+  while (pending.length > 0) {
+    const value = pending.pop()
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) continue
+    const block = value as { type?: unknown; attachment?: unknown; content?: unknown }
+    if (block.type === 'image' && typeof block.attachment === 'object' && block.attachment !== null) {
+      const ref = block.attachment as ImageAttachmentRef
+      refs.set(String(ref.attachmentId), ref)
+    }
+    if (Array.isArray(block.content)) {
+      for (const item of block.content) pending.push(item)
+    }
+  }
+}
+
+/**
+ * Collect every image reference one session event carries, across the same
+ * carriers the live attachment route scans (direct content, message content,
+ * inserted messages, and completed assistant chunk blocks).
+ * @param event - one parsed JSONL event object.
+ * @param refs - the dedupe map being filled (keyed by attachment id).
+ */
+function collectEventImageRefs(event: unknown, refs: Map<string, ImageAttachmentRef>): void {
+  const data = (event as { data?: unknown }).data
+  if (typeof data !== 'object' || data === null) return
+  const carrier = data as {
+    content?: unknown
+    message?: { content?: unknown }
+    inserted?: Array<{ content?: unknown }>
+    chunk?: { type?: unknown; block?: unknown }
+  }
+  collectImageRefs(carrier.content, refs)
+  if (carrier.message !== undefined) collectImageRefs(carrier.message.content, refs)
+  if (carrier.inserted !== undefined) {
+    for (const message of carrier.inserted) collectImageRefs(message.content, refs)
+  }
+  if (carrier.chunk?.type === 'block-end') collectImageRefs([carrier.chunk.block], refs)
+}
+
+/**
+ * Collect the distinct media references one stored artifact text names.
+ * Lines that fail to parse cannot reference media and are skipped (the
+ * artifact text itself is exported verbatim regardless).
+ * @param content - the stored artifact text.
+ * @returns the dedupe map keyed by attachment id.
+ */
+function imageRefsInArtifact(content: string): Map<string, ImageAttachmentRef> {
+  const refs = new Map<string, ImageAttachmentRef>()
+  for (const line of content.split('\n')) {
+    if (line === '') continue
+    let event: unknown
+    try {
+      event = JSON.parse(line)
+    } catch {
+      continue
+    }
+    collectEventImageRefs(event, refs)
+  }
+  return refs
+}
+
+/**
+ * One safe zip path segment from an untrusted session id. Session ids are
+ * host-controlled, but the brand allows any non-empty string, so `../`, dot
+ * segments, and separator characters are neutralized before they can shape
+ * archive entries. Distinct ids may collapse onto one segment (id collision
+ * is impossible for the host-minted UUIDs, so no uniqueness suffix is kept).
+ * @param id - the raw session id.
+ * @returns a filesystem-safe single path segment.
+ */
+function safeSessionIdSegment(id: string): string {
+  return id.replace(/[^A-Za-z0-9_-]/g, '_')
+}
+
+/**
+ * The export archive filename for one root session.
+ * @param sessionId - the root session id (sanitized to one safe path segment).
+ * @returns the attachment filename for the session's export archive.
+ */
+export function sessionLogZipFilename(sessionId: string): string {
+  return `dsh-session-${safeSessionIdSegment(sessionId)}.zip`
+}
+
+/**
+ * Yield the export entries in zip order: the preloaded root artifact first,
+ * then every subagent descendant in lineage order (each flushed when live,
+ * read from the persistence backend right before it is yielded, and dropped
+ * after the consumer moves on), then every distinct media object referenced by any of
+ * the included logs (read and verified from the attachment store, one archive
+ * entry per attachment id). The host holds at most one descendant's artifact
+ * text and one media object at a time beyond the root.
+ * @param deps - the mounted export services (the caller answered 500 before this runs).
+ * @param root - the already-read root artifact (read by the caller so the
+ * missing-session path can answer cleanly before streaming starts).
+ * @param sessionId - the root session id.
+ * @param includeDescendants - whether to include every subagent descendant.
+ * @param signal - optional cancellation forwarded to lineage, persistence, and attachment reads.
+ * @returns the export entries in zip order.
+ */
+export async function* sessionLogZipEntries(
+  deps: SessionLogExportReady,
+  root: SessionRawArtifact,
+  sessionId: SessionId,
+  includeDescendants: boolean,
+  signal?: AbortSignal,
+): AsyncGenerator<SessionLogZipEntry> {
+  const media = new Map<string, ImageAttachmentRef>()
+  const rememberMedia = (content: string): void => {
+    for (const [id, ref] of imageRefsInArtifact(content)) media.set(id, ref)
+  }
+  rememberMedia(root.content)
+  yield { path: root.filename, content: root.content }
+  if (includeDescendants) {
+    const seen = new Set<SessionId>([sessionId])
+    const collect = async function* (
+      nodes: readonly SessionLineageNode[],
+    ): AsyncGenerator<SessionLogZipEntry> {
+      for (const node of nodes) {
+        signal?.throwIfAborted()
+        const id = node.session.header.id
+        if (seen.has(id)) continue
+        seen.add(id)
+        await flushLiveSessionLog(deps, id, signal)
+        const raw = await deps.sessionPersistence.readRaw(id, signal)
+        signal?.throwIfAborted()
+        if (raw === undefined) {
+          throw new Error(`subagent "${id}" has no stored log artifact`)
+        }
+        rememberMedia(raw.content)
+        yield {
+          path: `subagents/${safeSessionIdSegment(id)}/${raw.filename}`,
+          content: raw.content,
+        }
+        yield* collect(node.descendants)
+      }
+    }
+    const lineage = await deps.sessionQuery.traceSession(sessionId, signal)
+    signal?.throwIfAborted()
+    yield* collect(lineage.descendants)
+  }
+  for (const ref of media.values()) {
+    signal?.throwIfAborted()
+    const stored = await deps.attachments.readImage(ref, signal)
+    signal?.throwIfAborted()
+    yield { path: mediaEntryPath(ref), data: stored.data }
+  }
+}
+
+/** How many code units of artifact text one zip push carries (bounded encode memory). */
+const PUSH_CHUNK_CODE_UNITS = 1 << 16
+
+/** How many bytes of media one zip push carries (bounded memory; images are already size-capped). */
+const PUSH_CHUNK_BYTES = 1 << 16
+
+/** Byte capacity retained by the response stream before ZIP production waits for pull. */
+const RESPONSE_HIGH_WATER_MARK_BYTES = 1 << 16
+
+/** One producer waiter released only when ReadableStream pull restores capacity. */
+class ResponseCapacityGate {
+  private releasePending: (() => void) | undefined
+
+  /**
+   * Wait until the response queue has positive byte capacity or cancellation wins.
+   * @param controller - response controller whose desired size owns capacity.
+   * @param signal - combined request/consumer cancellation.
+   */
+  async wait(
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    signal: AbortSignal,
+  ): Promise<void> {
+    signal.throwIfAborted()
+    if (controller.desiredSize === null || controller.desiredSize > 0) return
+    await new Promise<void>((resolve) => {
+      const release = (): void => {
+        this.releasePending = undefined
+        signal.removeEventListener('abort', release)
+        resolve()
+      }
+      this.releasePending = release
+      signal.addEventListener('abort', release, { once: true })
+    })
+    signal.throwIfAborted()
+  }
+
+  /** Release the current producer waiter after a consumer pull. */
+  pulled(): void {
+    this.releasePending?.()
+  }
+}
+
+/**
+ * Push one media object's bytes into a deflate stream in bounded chunks,
+ * waiting for consumer capacity between chunks like the artifact path does.
+ * @param deflate - the zip entry's deflate stream.
+ * @param data - the stored image bytes.
+ * @param controller - response queue controller.
+ * @param capacity - pull-driven response-capacity gate.
+ * @param signal - cancellation; throws when aborted.
+ */
+async function pushBinaryChunks(
+  deflate: ZipDeflate,
+  data: Uint8Array,
+  controller: ReadableStreamDefaultController<Uint8Array>,
+  capacity: ResponseCapacityGate,
+  signal: AbortSignal,
+): Promise<void> {
+  let offset = 0
+  do {
+    signal.throwIfAborted()
+    const end = Math.min(offset + PUSH_CHUNK_BYTES, data.byteLength)
+    const finalChunk = end >= data.byteLength
+    deflate.push(data.subarray(offset, end), finalChunk)
+    offset = end
+    await capacity.wait(controller, signal)
+  } while (offset < data.byteLength)
+}
+
+/**
+ * Push one artifact's text into a deflate stream in bounded chunks, never
+ * splitting a surrogate pair across a chunk boundary (a lone high surrogate
+ * re-encodes as U+FFFD and would silently corrupt the exported artifact).
+ * @param deflate - the zip entry's deflate stream.
+ * @param content - the artifact text verbatim.
+ * @param controller - response queue controller.
+ * @param capacity - pull-driven response-capacity gate.
+ * @param signal - cancellation; throws when aborted.
+ */
+async function pushArtifactChunks(
+  deflate: ZipDeflate,
+  content: string,
+  controller: ReadableStreamDefaultController<Uint8Array>,
+  capacity: ResponseCapacityGate,
+  signal: AbortSignal,
+): Promise<void> {
+  const encoder = new TextEncoder()
+  let offset = 0
+  let finalChunk: boolean
+  do {
+    signal.throwIfAborted()
+    let end = Math.min(offset + PUSH_CHUNK_CODE_UNITS, content.length)
+    if (end < content.length && end - offset > 1) {
+      // Back off one code unit when the boundary lands inside a surrogate
+      // pair: the pair then starts the next chunk whole.
+      const last = content.charCodeAt(end - 1)
+      if (last >= 0xd800 && last <= 0xdbff) end -= 1
+    }
+    finalChunk = end >= content.length
+    deflate.push(encoder.encode(content.slice(offset, end)), finalChunk)
+    offset = end
+    await capacity.wait(controller, signal)
+  } while (!finalChunk)
+}
+
+/**
+ * Stream one session-log ZIP as a WHATWG ReadableStream. The root artifact is
+ * read and validated by the caller before this is called (missing root or
+ * missing services answer cleanly before any byte is produced); each entry is
+ * then encoded and deflated in bounded chunks as it is produced, so the
+ * archive bytes arrive incrementally. A descendant that fails to read errors
+ * the stream (fail-loud, never silent under-export).
+ * @param deps - the mounted export services (the caller answered 500 before this runs).
+ * @param root - the already-read root artifact (first zip entry).
+ * @param sessionId - the root session id.
+ * @param includeDescendants - whether to include every subagent descendant.
+ * @param compressionLevel - validated fflate DEFLATE level for every ZIP entry.
+ * @param signal - request cancellation combined with response-consumer cancellation.
+ * @returns the zip byte stream.
+ */
+export function streamSessionLogZip(
+  deps: SessionLogExportReady,
+  root: SessionRawArtifact,
+  sessionId: SessionId,
+  includeDescendants: boolean,
+  compressionLevel: SessionLogCompressionLevel,
+  signal: AbortSignal,
+): ReadableStream<Uint8Array> {
+  const consumerAbort = new AbortController()
+  const producerSignal = AbortSignal.any([signal, consumerAbort.signal])
+  let zip: Zip | undefined
+  let zipTerminated = false
+  const capacity = new ResponseCapacityGate()
+  const terminateZip = (): void => {
+    if (zip === undefined || zipTerminated) return
+    zipTerminated = true
+    zip.terminate()
+  }
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      // fflate invokes the callback synchronously per compressed chunk, so a
+      // single push can enqueue ahead of a slow consumer; the capacity gate
+      // waits for pull between pushes once the byte queue is full, bounding
+      // accumulation to the queue high-water mark plus one synchronous push.
+      const archive = new Zip((error, data, final) => {
+        /* v8 ignore next 3 -- fflate reports only internal zip failures, unreachable for valid inputs */
+        if (error) {
+          controller.error(error)
+          return
+        }
+        /* v8 ignore next -- fflate may emit empty chunks; not controllable from tests */
+        if (data.byteLength > 0) controller.enqueue(data)
+        if (final) controller.close()
+      })
+      zip = archive
+      void (async () => {
+        try {
+          for await (const entry of sessionLogZipEntries(deps, root, sessionId, includeDescendants, producerSignal)) {
+            const deflate = new ZipDeflate(entry.path, { level: compressionLevel })
+            archive.add(deflate)
+            if ('content' in entry) {
+              await pushArtifactChunks(deflate, entry.content, controller, capacity, producerSignal)
+            } else {
+              await pushBinaryChunks(deflate, entry.data, controller, capacity, producerSignal)
+            }
+          }
+          archive.end()
+        } catch (error) {
+          // A mid-stream failure (missing descendant, cancellation, read
+          // error) must fail the download rather than ship a truncated archive.
+          /* v8 ignore next -- typed backends reject with Error, and DOMException is one in Node */
+          terminateZip()
+          controller.error(error instanceof Error ? error : new Error(String(error)))
+        }
+      })()
+    },
+    pull() {
+      capacity.pulled()
+    },
+    cancel(reason) {
+      consumerAbort.abort(
+        reason instanceof Error ? reason : new Error('session log export stream cancelled'),
+      )
+      terminateZip()
+    },
+  }, {
+    highWaterMark: RESPONSE_HIGH_WATER_MARK_BYTES,
+    size: chunk => chunk.byteLength,
+  })
+}