feat(apiproxy): host session-log download surface

Streams one ZIP of the root session artifact plus each subagent descendant
verbatim (the persistence readRaw bytes) from GET /api/session.export as a
host-only download — no wire envelope, absent from IApiClient. The downloads
domain owns the query schema, the fetch handler answers the GET alongside the
SSE routes, and compression runs on the host with fflate's streaming Zip API.

THIRD_PARTY_NOTICES.md

@@ -59,6 +59,7 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
 | [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
+| [`fflate`](https://github.com/101arrowz/fflate) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
 | [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT |

packages/host/apiproxy/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 64f6ae7bcd92735f821c8f8d2b3b93203dbac17e
-README.zh.md: 680fcee730674a21b5c2407247ce46b1a01cf6f3
+README.md: 452e157ed93ca4ace07a8c958bad04b15d598b31
+README.zh.md: f0509276ef690874e788a3a1e312d35ec37034f0

packages/host/apiproxy/README.md

@@ -28,6 +28,8 @@ Question responses are validated against their pending request before the first
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
+Session-log export is a host-only download surface, not an RPC: `GET /api/session.export?sessionId=…&includeDescendants=true` streams a ZIP whose files are each session's stored artifact text verbatim (the persistence backend's `readRaw` — exact durable bytes decoded from the physical encoding, never a reconstruction from parsed events), root under its original base name plus each subagent descendant under `subagents/<id>/`. Compression runs on the host with fflate's streaming Zip API, so the response is chunked as it is produced and the host never materializes the whole archive. It requires both the persistence and session-query services: a deployment without either answers 500, a missing root session 404, and a descendant without a stored artifact fails the stream (fail-loud, never silent under-export). The carrier mounts the endpoint; `ApiProxy.downloads.sessionLog` implements it.
+
 Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key. Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
 
 `session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged `ModelSelection`, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) records why the anchor maps to that `turn/end`.

packages/host/apiproxy/README.zh.md

@@ -28,6 +28,8 @@ Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
+会话日志导出是宿主侧的下载面，不是 RPC：`GET /api/session.export?sessionId=…&includeDescendants=true` 流式返回一个 ZIP，其中每个文件都是会话存储工件的逐字原文（持久化后端的 `readRaw`——按物理编码解码的确切持久化字节，绝非从解析后事件重建），根会话放在其原始基础文件名下，每个子代理后代放在 `subagents/<id>/` 下。压缩在宿主侧用 fflate 的流式 Zip API 完成，响应边生成边分块写出，宿主从不把整个归档放进内存。它要求同时挂载持久化与 session-query 服务：任一缺失应答 500，根会话缺失应答 404，后代缺少存储工件则整个流失败（fail-loud，绝不静默少导出）。端点由传输层挂载，`ApiProxy.downloads.sessionLog` 实现它。
+
 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
 
 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的 `ModelSelection` 及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)记录了为何锚点要映射到该 `turn/end`。

packages/host/apiproxy/package.json

@@ -62,6 +62,7 @@
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
+    "fflate": "^0.8.2",
     "schemastery": "^3.18.0",
     "zod": "^4.4.3"
   },

packages/host/apiproxy/src/api-proxy.ts

@@ -41,6 +41,12 @@ import type {
   QueuedInboxItem, SessionSummary, SettingsNamespaceView, SubagentAddress, ToolEventView,
   WorkspaceId, WorkspaceView,
 } from './api/index.ts'
+import {
+  sessionLogExportDeps,
+  sessionLogZipFilename,
+  streamSessionLogZip,
+} from './session-export.ts'
+import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
 import {
   SESSION_SEARCH_RESULT_LIMIT,
   SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS,
@@ -3348,6 +3354,39 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       },
     },
 
+    downloads: {
+      async sessionLog(request, signal) {
+        // Clean error path first: missing services answer 500 and a missing
+        // root artifact 404 before any zip byte is produced. The root content
+        // read here is reused as the first zip entry, so nothing is read twice.
+        const deps = sessionLogExportDeps(ctx)
+        if (deps.sessionQuery === undefined || deps.sessionPersistence === undefined) {
+          return new Response(
+            'session log export is unavailable: missing session-query or session-persistence service',
+            { status: 500 },
+          )
+        }
+        let root: SessionRawArtifact | undefined
+        try {
+          root = await deps.sessionPersistence.readRaw(request.sessionId)
+        } catch (error: unknown) {
+          return new Response(String(error), { status: 500 })
+        }
+        if (root === undefined) {
+          return new Response('session not found', { status: 404 })
+        }
+        return new Response(
+          streamSessionLogZip(deps, root, request.sessionId, request.includeDescendants === true, signal),
+          {
+            headers: {
+              'content-type': 'application/zip',
+              'content-disposition': `attachment; filename="${sessionLogZipFilename(request.sessionId)}"`,
+            },
+          },
+        )
+      },
+    },
+
     respond(message: ClientResponse): Promise<RpcReceipt> {
       // Route by the echoed rpcId (the wire correlation): approvals first,
       // then questions — the two registries share one id space of UUIDs.

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

@@ -0,0 +1,22 @@
+/**
+ * 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. */
+export const sessionLogQuerySchema = z
+  .object({
+    sessionId: sessionIdSchema,
+    includeDescendants: z.string().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/index.ts

@@ -16,6 +16,7 @@ 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. */
@@ -32,6 +33,8 @@ export interface ApiProxy {
   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>
 }
@@ -39,9 +42,8 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelSelection, PromptContentPart, 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 {
@@ -57,6 +59,7 @@ 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/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'
@@ -249,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

@@ -72,6 +72,7 @@ export class ApiProxyService extends Service implements ApiProxy {
   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) {
@@ -94,6 +95,7 @@ export class ApiProxyService extends Service implements ApiProxy {
     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/session-export.ts

@@ -0,0 +1,176 @@
+/**
+ * Host-side session-log download: streams one ZIP archive whose files are the
+ * sessions' stored artifact text verbatim. The root artifact sits under its
+ * original base name (`session.jsonl`); each subagent descendant under
+ * `subagents/<id>/<filename>`. No manifest is written — every file is
+ * byte-identical to the backend's durable artifact and self-describing
+ * through its own header line. Compression happens on the host with fflate's
+ * streaming Zip API, so the response is chunked as it is produced and the
+ * host never materializes the whole archive.
+ * @module
+ */
+
+import { Zip, ZipDeflate } from 'fflate'
+import type { Context } from 'cordis'
+import type { SessionLineageNode, SessionQueryService } from '@deepseek-ai/dsh-session-query'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence, SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence'
+
+/** The services a session-log export needs (absent → the export is unavailable). */
+export interface SessionLogExportDeps {
+  readonly sessionQuery: SessionQueryService | undefined
+  readonly sessionPersistence: SessionPersistence | undefined
+}
+
+/**
+ * Resolve the persistence and session-query 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'),
+  }
+}
+/** One exported artifact: the stored text plus the zip path it lands at. */
+export interface SessionLogZipEntry {
+  /** Zip entry path (root filename verbatim; descendants under `subagents/<id>/`). */
+  readonly path: string
+  /** The stored artifact text verbatim. */
+  readonly content: string
+}
+
+/**
+ * One safe zip path segment from an untrusted session id. Session ids are
+ * host-controlled, but the brand allows any non-empty string, so `../` and
+ * separator characters are neutralized before they can shape archive entries.
+ * @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 read from the
+ * persistence backend right before it is yielded and dropped after the
+ * consumer moves on (the host holds at most one descendant's artifact text at
+ * a time beyond the root).
+ * @param deps - the export services.
+ * @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 for read work.
+ * @returns the export entries in zip order.
+ */
+export async function* sessionLogZipEntries(
+  deps: SessionLogExportDeps,
+  root: SessionRawArtifact,
+  sessionId: SessionId,
+  includeDescendants: boolean,
+  signal?: AbortSignal,
+): AsyncGenerator<SessionLogZipEntry> {
+  yield { path: root.filename, content: root.content }
+  if (!includeDescendants) return
+  const sessionQuery = deps.sessionQuery
+  const sessionPersistence = deps.sessionPersistence
+  if (sessionQuery === undefined || sessionPersistence === undefined) {
+    // The caller validated services before the stream started; this arm is
+    // unreachable today and guards a future caller that skips the check.
+    throw new Error('session log export is unavailable: missing session-query or session-persistence service')
+  }
+  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)
+      const raw = await sessionPersistence.readRaw(id)
+      if (raw === undefined) {
+        throw new Error(`subagent "${id}" has no stored log artifact`)
+      }
+      yield {
+        path: `subagents/${safeSessionIdSegment(id)}/${raw.filename}`,
+        content: raw.content,
+      }
+      yield* collect(node.descendants)
+    }
+  }
+  const lineage = await sessionQuery.traceSession(sessionId)
+  yield* collect(lineage.descendants)
+}
+
+/** How many code points of artifact text one zip push carries (bounded encode memory). */
+const PUSH_CHUNK_CODE_POINTS = 1 << 16
+
+/**
+ * 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 export services.
+ * @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 signal - optional cancellation for read work.
+ * @returns the zip byte stream.
+ */
+export function streamSessionLogZip(
+  deps: SessionLogExportDeps,
+  root: SessionRawArtifact,
+  sessionId: SessionId,
+  includeDescendants: boolean,
+  signal?: AbortSignal,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      // fflate invokes the callback synchronously per compressed chunk;
+      // enqueued bytes stay bounded by the compressed archive size (the body
+      // consumer drains them over the wire as the stream is pulled).
+      const zip = new Zip((error, data, final) => {
+        if (error) {
+          controller.error(error)
+          return
+        }
+        if (data.byteLength > 0) controller.enqueue(data)
+        if (final) controller.close()
+      })
+      void (async () => {
+        try {
+          for await (const entry of sessionLogZipEntries(deps, root, sessionId, includeDescendants, signal)) {
+            const deflate = new ZipDeflate(entry.path, { level: 6 })
+            zip.add(deflate)
+            const content = entry.content
+            for (let offset = 0; offset < content.length; offset += PUSH_CHUNK_CODE_POINTS) {
+              signal?.throwIfAborted()
+              const finalChunk = offset + PUSH_CHUNK_CODE_POINTS >= content.length
+              deflate.push(encoder.encode(content.slice(offset, offset + PUSH_CHUNK_CODE_POINTS)), finalChunk)
+            }
+          }
+          zip.end()
+        } catch (error) {
+          // A mid-stream failure (missing descendant, cancellation, read
+          // error) must fail the download rather than ship a truncated archive.
+          controller.error(error instanceof Error ? error : new Error(String(error)))
+        }
+      })()
+    },
+  })
+}

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

@@ -133,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 }) },
   }
 }
 

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

@@ -300,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 })
+      },
+    },
   }
 }
 

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

@@ -0,0 +1,149 @@
+/**
+ * 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 { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { unzipSync, strFromU8 } from 'fflate'
+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 { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { createApiProxy } 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): SessionRawArtifact {
+  return {
+    meta: header(id, parentSession),
+    filename: 'session.jsonl',
+    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 }
+}
+
+async function buildApi(
+  artifacts: Record<string, SessionRawArtifact>,
+  descendants: SessionLineageNode[] = [],
+  services: { query?: boolean; persistence?: boolean } = { query: true, persistence: true },
+) {
+  const ctx = new Context()
+  await ctx.plugin(UserInteractionService)
+  if (services.query) {
+    ctx.provide('sessionQuery', {
+      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 (services.persistence) {
+    ctx.provide('sessionPersistence', {
+      readRaw: async (id: SessionId) => artifacts[id],
+    } as never)
+  }
+  return createApiProxy(ctx, {
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
+    cwd: '/tmp',
+  })
+}
+
+async function responseBytes(response: Response): Promise<Uint8Array> {
+  return new Uint8Array(await response.arrayBuffer())
+}
+
+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('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('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 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 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()
+  })
+})

pnpm-lock.yaml

@@ -2727,6 +2727,9 @@ importers:
         specifier: ^9.0.0
         version: 9.0.0
     devDependencies:
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
@@ -4292,6 +4295,9 @@ importers:
       '@deepseek-ai/dsh-workspace':
         specifier: workspace:^
         version: link:../../workspace/workspace
+      fflate:
+        specifier: ^0.8.2
+        version: 0.8.3
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
@@ -11521,6 +11527,9 @@ packages:
     resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
     engines: {node: ^12.20 || >= 14.13}
 
+  fflate@0.8.3:
+    resolution: {integrity: sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==}
+
   figures@6.1.0:
     resolution: {integrity: sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg==}
     engines: {node: '>=18'}
@@ -16818,6 +16827,8 @@ snapshots:
       node-domexception: 1.0.0
       web-streams-polyfill: 3.3.3
 
+  fflate@0.8.3: {}
+
   figures@6.1.0:
     dependencies:
       is-unicode-supported: 2.1.0