Merge remote-tracking branch 'upstream/master' into feat/web-workspace-file-links

# Conflicts:
#	apps/web/tsconfig.json
#	packages/client/connection/README.i18n.yaml
#	packages/client/connection/README.zh.md
#	packages/client/ui-conversation/README.i18n.yaml
#	packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
#	packages/client/ui-conversation/src/client/chat/ChatView.tsx
#	packages/client/ui-conversation/src/client/chat/ToolRow.module.css
#	packages/client/ui-conversation/src/client/chat/chat-flow.ts
#	packages/client/ui-conversation/tests/chat-view.spec.tsx
#	packages/host/apiproxy/src/native-path-opener.ts
#	tsconfig.host.json

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

@@ -1,8 +1,8 @@
 /**
  * commands domain contract: the web catalog/dispatch face of the host command
- * registry (`ctx.commands`). Both methods address one session's agent via
- * `sessionId` — every served session has an Agent (Session+Agent are born
- * together), so there is no agent-less surface on this wire.
+ * registry (`ctx.commands`). Both methods address an ordinary session's Agent
+ * via `sessionId`, resuming it when cold. Session-backed subagents reject with
+ * `agent-busy` and retain their dedicated continuation owner.
  */
 
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
@@ -27,7 +27,8 @@ export interface CommandDescriptor {
 export interface CommandsApi {
   /**
    * Lists the addressed agent's effective command catalog (name-sorted,
-   * globals plus its scoped shadows).
+   * globals plus its scoped shadows). Session-backed subagents reject with
+   * `agent-busy`.
    */
   list(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ commands: readonly CommandDescriptor[] }>>
 
@@ -42,6 +43,7 @@ export interface CommandsApi {
    * pairing id, letting the issuing client correlate this acknowledgment
    * with that flow node. The signal rides beside the request, never on the
    * wire: the fetch carrier's request signal cancels the running handler.
+   * Session-backed subagents reject with `agent-busy` before dispatch.
    */
   execute(request: RpcRequest<{ sessionId: SessionId; line: string }>, signal: AbortSignal):
   Promise<RpcResponse<{ matched: boolean; commandId?: CommandId }>>

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

@@ -11,7 +11,7 @@ import type { Wire } from './rpc.schema.ts'
 import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
 import { approvalRequestIdSchema } from './approvals.schema.ts'
 import {
-  contentBlockSchema, inboxItemIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema,
+  contentBlockSchema, messageIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema,
 } from './sessions.schema.ts'
 import { workspaceIdSchema, workspaceViewSchema } from './workspace.schema.ts'
 
@@ -53,7 +53,8 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
     type: z.literal('session/queue'),
     sessionId: sessionIdSchema,
     items: z.array(z.object({
-      id: inboxItemIdSchema,
+      id: messageIdSchema,
+      placement: z.union([z.literal('queued'), z.literal('steering'), z.literal('context')]),
       message: messageSchema,
     })),
   }),
@@ -65,7 +66,14 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
 
 /** HostFrame union (payload slot of a host-stream ServerRequest). */
 export const hostFrameSchema = z.discriminatedUnion('type', [
-  z.object({ type: z.literal('host/session-added'), sessionId: sessionIdSchema, blank: z.boolean(), parentSessionId: sessionIdSchema.optional(), cwd: z.string().optional() }),
+  z.object({
+    type: z.literal('host/session-added'),
+    sessionId: sessionIdSchema,
+    blank: z.boolean(),
+    parentSessionId: sessionIdSchema.optional(),
+    origin: z.literal('subagent').optional(),
+    cwd: 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() }),
   z.object({ type: z.literal('host/agent-error'), sessionId: sessionIdSchema, message: z.string() }),

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

@@ -1,5 +1,5 @@
 /**
- * events domain contract: signatures and frame unions for the two SSE
+ * events domain contract: signatures and frame unions for the two logical
  * streams. Four-quadrant: streams yield the narrow form `RpcRequest<Frame>` (server-request
  * view) — rpcId must be exposed to the business layer, because responses to answerable frames
  * (approval/question requested) echo it; for pure pushes it identifies that one push.
@@ -9,7 +9,7 @@
 import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
 import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
 import type { Message } from '@deepseek-ai/dsh-llm/types'
-import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 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'
@@ -32,15 +32,17 @@ export type ToolEventView =
   | { for: 'call'; view: ToolCallView }
   | { for: 'result'; view: ToolResultView }
 
-/** One pending queued occurrence in an authoritative queue snapshot. */
+/** One pending inbox occurrence in the authoritative `session/queue` snapshot. */
 export interface QueuedInboxItem {
-  /** Agent-owned occurrence identity used by queue mutations. */
-  id: InboxItemId
+  /** Message identity used by inbox mutations. */
+  id: MessageId
+  /** Agent-resolved FIFO placement; queued and steering items render on different surfaces, context items stay invisible until claimed. */
+  placement: 'queued' | 'steering' | 'context'
   /** Complete pending message; it is not durable until the Agent claims it. */
   message: Message
 }
 
-/** Streaming face of the contract: the two SSE stream openers (mux + host). */
+/** Streaming face of the contract: the two logical stream openers (mux + host). */
 export interface EventsApi {
   /**
    * All-session aggregated mux stream. On open, emits a subscribed control frame for every
@@ -71,11 +73,12 @@ export type MuxFrame =
   | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }
   | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' }
   /**
-   * Complete transient queue state after every enqueue, mutation, claim, or
+   * Complete transient inbox state after every enqueue, mutation, claim, or
    * discard. Pending work is not model-visible and therefore has no durable
    * session event; the whole snapshot makes edit, deletion, cancel, and
-   * reconnect converge through one authoritative signal. Pending steering is
-   * outside this Web queue projection.
+   * reconnect converge through one authoritative signal. `session/queue`
+   * covers both resolved placements: queued items render
+   * in QueueDock, while pending steering renders at the conversation tail.
    */
   | { type: 'session/queue'; sessionId: SessionId; items: QueuedInboxItem[] }
   /**
@@ -90,9 +93,9 @@ export type MuxFrame =
   | { type: 'stream/error'; error: RpcError }
 
 /**
- * Host stream frames. session-added carries the lineage anchor, the project
- * cwd, and the blank bit (the list-summary fields a client cannot wait for a
- * refresh to learn); the frame fires at session/created, so blank is
+ * Host stream frames. session-added carries the lineage anchor, product
+ * origin, project cwd, and blank bit (the list-summary fields a client cannot
+ * wait for a refresh to learn); the frame fires at session/created, so blank is
  * constantly true — clients flip it on the session's first
  * `host/session-status(running:true)` (a blank session never runs), and a
  * reconnecting client takes `session.list`'s summary.blank as authoritative.
@@ -106,7 +109,14 @@ export type MuxFrame =
  * workspace-changed — `workspace.list` re-baselines it on reconnect).
  */
 export type HostFrame =
-  | { type: 'host/session-added'; sessionId: SessionId; blank: boolean; parentSessionId?: SessionId; cwd?: string }
+  | {
+    type: 'host/session-added'
+    sessionId: SessionId
+    blank: boolean
+    parentSessionId?: SessionId
+    origin?: 'subagent'
+    cwd?: string
+  }
   | { type: 'host/session-removed'; sessionId: SessionId }
   | { type: 'host/session-status'; sessionId: SessionId; running: boolean }
   | { type: 'host/agent-error'; sessionId: SessionId; message: string }

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

@@ -22,7 +22,11 @@ export interface GoalRef {
   readonly revision: number
 }
 
-/** Goal-domain unary methods (every mutation resolves the session's agent and applies one CAS-guarded verb). */
+/**
+ * Goal-domain unary methods. Every mutation resolves an ordinary session's
+ * Agent and applies one CAS-guarded verb; session-backed subagents reject with
+ * `agent-busy`.
+ */
 export interface GoalsApi {
   /** Create and arm a goal. */
   create(request: RpcRequest<{ sessionId: SessionId; objective: string; maxGoalRounds?: number }>):

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

@@ -1,7 +1,7 @@
 /**
  * apiproxy contract-layer barrel. api/ has zero Node dependencies and is
- * importable from the browser; the TS interfaces are the authoritative contract, HTTP/SSE are
- * merely physical channels (four-quadrant message model).
+ * importable from the browser; the TS interfaces are the authoritative contract, while HTTP,
+ * WebSocket, and in-process SSE are merely physical channels (four-quadrant message model).
  */
 
 import type { SessionsApi } from './sessions.ts'
@@ -9,6 +9,7 @@ import type { HostApi } from './host.ts'
 import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
 import type { SkillsApi } from './skills.ts'
+import type { SubagentsApi } from './subagents.ts'
 import type { EventsApi } from './events.ts'
 import type { GoalsApi } from './goals.ts'
 import type { SettingsApi } from './settings.ts'
@@ -19,6 +20,7 @@ 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. */
 export interface ApiProxy {
   sessions: SessionsApi
+  subagents: SubagentsApi
   host: HostApi
   workspace: WorkspaceApi
   commands: CommandsApi
@@ -39,6 +41,9 @@ export type {
   SessionsApi, SessionSummary,
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
+export type {
+  SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, SubagentsApi,
+} from './subagents.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'
@@ -46,7 +51,7 @@ export type { EventsApi, MuxFrame, HostFrame, QueuedInboxItem, ToolCallView, Too
 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, LlmApi } from './llm.ts'
+export type { ConfigurableProviderView, DiscoveredModelView, LlmApi } from './llm.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
 
 export type { QuestionResponsePayload } from './questions.ts'
@@ -67,7 +72,6 @@ export type {
 // ---- Errors and ids ----
 export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
-export type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
 
 // ---- Fixed session-search product bounds ----
 export {

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

@@ -6,7 +6,7 @@
 import { z } from 'zod'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
-import type { ConfigurableProviderView } from './llm.ts'
+import type { ConfigurableProviderView, DiscoveredModelView } from './llm.ts'
 import { modelCatalogFailureSchema, modelProviderGroupSchema } from './sessions.schema.ts'
 
 /** ConfigurableProviderView row of llm.providers. */
@@ -34,3 +34,30 @@ export const llmModelsValueSchema = z.object({
   groups: z.array(modelProviderGroupSchema),
   failures: z.array(modelCatalogFailureSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'llm.models'>>>
+
+/** DiscoveredModelView row of llm.discoverModels. */
+export const discoveredModelViewSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1).optional(),
+  contextWindow: z.number().int().positive().optional(),
+  maxTokens: z.number().int().positive().optional(),
+}) satisfies z.ZodType<Wire<DiscoveredModelView>>
+
+/** llm.discoverModels request payload. */
+export const llmDiscoverModelsRequestSchema = z.object({
+  settingsNs: z.string().min(1),
+  provider: z.string().min(1).optional(),
+  baseURL: z.string().min(1).optional(),
+  api: z.string().min(1).optional(),
+  // Write-only at the host: used for this one interrogation, never stored and
+  // never returned. It does ride the client's outgoing envelope like every
+  // other secret-bearing payload (`credentials.set`, `settings.update`), which
+  // `subscribeEnvelopes()` observers can see — redacting that tap is a
+  // configuration-plane-wide change, not this method's to make alone.
+  apiKey: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'llm.discoverModels'>>>
+
+/** llm.discoverModels response value. */
+export const llmDiscoverModelsValueSchema = z.object({
+  models: z.array(discoveredModelViewSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'llm.discoverModels'>>>

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

@@ -3,8 +3,8 @@
  * surfaces. `llm.providers` merges the configurable-provider directory
  * (which providers CAN be configured, and where their settings live) with the
  * live route registry; `llm.models` is the session-independent model catalog
- * (`session.models` minus the per-session current/unlisted logic). Both
- * invalidate on the `host/models-changed` frame.
+ * (the same groups as `session.models`, without the per-session current
+ * target). Both invalidate on the `host/models-changed` frame.
  */
 
 import type { RpcRequest, RpcResponse } from './rpc.ts'
@@ -40,4 +40,43 @@ export interface LlmApi {
    * failures ride `failures` without failing the sound groups.
    */
   models(request: RpcRequest<{}>): Promise<RpcResponse<{ groups: ModelProviderGroup[]; failures: ModelCatalogFailure[] }>>
+
+  /**
+   * Interrogate a provider endpoint the configuration surface is still
+   * drafting, and return the models it advertises for the user to adopt.
+   *
+   * The payload is the draft, not a stored route: `settingsNs` selects the
+   * adapter family that answers, and the rest comes from the form. `provider`
+   * names the route being edited when there is one — an adapter that already
+   * describes that route answers from its own registry, with better metadata
+   * and no network call, and needs no endpoint. A route it does not describe is
+   * asked over the wire, which is what `baseURL`, `api`, and `apiKey` are for.
+   *
+   * Nothing is written — the reply is candidates, and only a later
+   * `settings.mutate` decides what a route serves. `apiKey` is accepted here
+   * but never stored or returned; a provider whose key is already stored omits
+   * it and the endpoint answers unauthenticated or refuses.
+   */
+  discoverModels(
+    request: RpcRequest<{
+      settingsNs: string
+      provider?: string
+      baseURL?: string
+      api?: string
+      apiKey?: string
+    }>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<{ models: DiscoveredModelView[] }>>
+}
+
+/** Wire view of one model an interrogated endpoint advertises. */
+export interface DiscoveredModelView {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
 }

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

@@ -13,6 +13,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 { SubagentsApi } from './subagents.ts'
 import type { RpcResponse } from './rpc.ts'
 
 /**
@@ -32,6 +33,9 @@ export interface RpcMethodMap {
   'session.prompt': SessionsApi['prompt']
   'session.updateQueue': SessionsApi['updateQueue']
   'session.cancel': SessionsApi['cancel']
+  'subagent.list': SubagentsApi['list']
+  'subagent.history': SubagentsApi['history']
+  'subagent.prompt': SubagentsApi['prompt']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
   'host.listDirectory': HostApi['listDirectory']
@@ -53,6 +57,7 @@ export interface RpcMethodMap {
   'goal.complete': GoalsApi['complete']
   'goal.clear': GoalsApi['clear']
   'settings.describe': SettingsApi['describe']
+  'settings.openDocument': SettingsApi['openDocument']
   'settings.update': SettingsApi['update']
   'settings.replace': SettingsApi['replace']
   'settings.mutate': SettingsApi['mutate']
@@ -61,6 +66,7 @@ export interface RpcMethodMap {
   'credentials.unset': CredentialsApi['unset']
   'llm.providers': LlmApi['providers']
   'llm.models': LlmApi['models']
+  'llm.discoverModels': LlmApi['discoverModels']
 }
 
 /** Business request payload of method K (reaches through the RpcRequest narrow form to payload). */

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

@@ -48,14 +48,26 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('directory-picker-unavailable'), message: z.string(), details: z.object({ capability: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), 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({}) }),
   z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('settings-rejected'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-not-exposed'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-conflict'), message: z.string(), details: z.object({ ns: z.string(), expected: z.number(), actual: z.number() }) }),
   z.object({ code: z.literal('credential-rejected'), message: z.string(), details: z.object({ ref: z.string() }) }),
+  z.object({ code: z.literal('model-discovery-failed'), message: z.string(), details: z.object({ settingsNs: z.string(), baseURL: z.string().optional() }) }),
   z.object({ code: z.literal('title-invalid'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('fork-unavailable'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-parent-unavailable'), message: z.string(), details: z.object({ parentSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-not-found'), message: z.string(), details: z.object({ parentSessionId: z.string(), childSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-catalog-diagnostic'), message: z.string(), details: z.object({
+    parentSessionId: z.string(),
+    childSessionId: z.string(),
+    reason: z.union([z.literal('corrupt'), z.literal('unsupported'), z.literal('unavailable')]),
+  }) }),
+  z.object({ code: z.literal('subagent-not-resumable'), message: z.string(), details: z.object({ childSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-unauthorized'), message: z.string(), details: z.object({ childSessionId: z.string() }) }),
+  z.object({ code: z.literal('subagent-delivery-unavailable'), message: z.string(), details: z.object({ childSessionId: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>
 

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

@@ -1,15 +1,15 @@
 /**
- * Four-quadrant RPC message model. Channels and messages are
- * decoupled: HTTP is the client→server physical channel, SSE the server→client one; logical
- * messages are channel-independent, and the wire full form is a four-member discriminated union.
+ * Four-quadrant RPC message model. Channels and messages are decoupled: HTTP,
+ * WebSocket, and in-process SSE are physical carriers, while logical messages
+ * are channel-independent and form a four-member discriminated union.
  * api/ contract layer: zero Node dependencies, importable from the browser.
  */
 
 import type { z as zCore } from 'zod'
 type ZodIssue = zCore.core.$ZodIssue
 import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
 
 /**
  * Message correlation id: the initiator mints it on a request; a response
@@ -45,7 +45,8 @@ export interface RpcErrorDetailsMap {
   'directory-create-failed': { path: string }
   'directory-picker-unavailable': { capability: string }
   'agent-busy': { reason: string }
-  'queue-item-not-found': { itemId: InboxItemId }
+  '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. */
   'command-error': {}
   /** A leading-/ prompt named no registered command; the message names the token. */
@@ -69,8 +70,27 @@ export interface RpcErrorDetailsMap {
   'settings-conflict': { ns: string; expected: number; actual: number }
   /** A credential write was refused (read-only shadowing layer or storage failure); the message is the seam's own text. */
   'credential-rejected': { ref: string }
+  /**
+   * Interrogating a draft provider endpoint did not produce a model listing:
+   * no adapter family serves the namespace, the protocol has no listing this
+   * build can read, or the endpoint was unreachable, refused the credential,
+   * or answered with something else. The message is the adapter's own text —
+   * it is what the form shows before falling back to hand-entry — and the
+   * details name the endpoint asked, never the credential offered.
+   */
+  'model-discovery-failed': { settingsNs: string; baseURL?: string }
   'title-invalid': { sessionId: SessionId }
   'fork-unavailable': { sessionId: SessionId }
+  'subagent-parent-unavailable': { parentSessionId: SessionId }
+  'subagent-not-found': { parentSessionId: SessionId; childSessionId: SessionId }
+  'subagent-catalog-diagnostic': {
+    parentSessionId: SessionId
+    childSessionId: SessionId
+    reason: 'corrupt' | 'unsupported' | 'unavailable'
+  }
+  'subagent-not-resumable': { childSessionId: SessionId }
+  'subagent-unauthorized': { childSessionId: SessionId }
+  'subagent-delivery-unavailable': { childSessionId: SessionId }
   'internal': {}
 }
 
@@ -136,7 +156,7 @@ export interface ServerResponse {
 }
 
 /**
- * Message initiated by the server (wire carrier: SSE frame). Answerable interactions
+ * Message initiated by the server (wire carrier: downstream stream frame). Answerable interactions
  * (approval/question requested — stable rpcId, reused on replay) and pure pushes
  * (session/event etc. — rpcId identifies that one push) share this shape; whether a
  * response is expected is determined statically by method (a strict dichotomy, no third kind).

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

@@ -7,7 +7,7 @@
 
 import { z } from 'zod'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
-import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
@@ -25,8 +25,8 @@ import {
 /** SessionId: one brand cast after shape validation (the only cast point in this domain). */
 export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>
 
-/** InboxItemId: one brand cast after non-empty string validation. */
-export const inboxItemIdSchema = z.string().min(1) as unknown as z.ZodType<InboxItemId>
+/** MessageId: one brand cast after non-empty string validation. */
+export const messageIdSchema = z.string().min(1) as unknown as z.ZodType<MessageId>
 
 /**
  * WorkspaceId: the workspace domain's one brand cast. Hosted here rather
@@ -53,6 +53,7 @@ export const sessionSummarySchema = z.object({
   running: z.boolean(),
   blank: z.boolean(),
   parentSessionId: sessionIdSchema.optional(),
+  origin: z.literal('subagent').optional(),
   cwd: z.string().optional(),
   projections: z.lazy(() => sessionProjectionsBlockSchema).optional(),
 }) as unknown as z.ZodType<Wire<SessionSummary>>
@@ -164,7 +165,6 @@ export const modelCatalogModelSchema = z.object({
   id: z.string().min(1),
   name: z.string().min(1),
   description: z.string().optional(),
-  unlisted: z.literal(true).optional(),
   reasoning: modelReasoningSchema.optional(),
 }) satisfies z.ZodType<Wire<ModelCatalogModel>>
 
@@ -194,10 +194,10 @@ export const toolEventViewSchema = z.discriminatedUnion('for', [
 ]) as unknown as z.ZodType<ToolEventView>
 
 /** One session.history item: the session event plus its optional host-computed tool view. */
-export const historyEntrySchema = z.object({
+export const historyEntrySchema: z.ZodType<Wire<HistoryEntry>> = z.object({
   event: sessionEventSchema,
   view: toolEventViewSchema.optional(),
-}) satisfies z.ZodType<Wire<HistoryEntry>>
+}) as unknown as z.ZodType<Wire<HistoryEntry>>
 
 /**
  * Projection baseline passthrough: `values` stays a wide record — each value
@@ -211,11 +211,11 @@ export const sessionProjectionsBlockSchema = z.object({
 }) as unknown as z.ZodType<SessionProjectionsBlock>
 
 /** session.history response value (projections rides the tail page only). */
-export const sessionHistoryValueSchema = z.object({
+export const sessionHistoryValueSchema: z.ZodType<Wire<ResponseValue<'session.history'>>> = z.object({
   events: z.array(historyEntrySchema),
   hasMore: z.boolean(),
   projections: sessionProjectionsBlockSchema.optional(),
-}) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
+})
 
 /** session.models request payload. */
 export const sessionModelsRequestSchema = z.object({
@@ -264,10 +264,11 @@ export const sessionPromptValueSchema = z.object({
 /** session.updateQueue request payload. */
 export const sessionUpdateQueueRequestSchema = z.object({
   sessionId: sessionIdSchema,
-  itemId: inboxItemIdSchema,
+  itemId: messageIdSchema,
   action: z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('edit'), content: z.array(contentBlockSchema) }),
     z.object({ kind: z.literal('remove') }),
+    z.object({ kind: z.literal('steer') }),
   ]),
 }) as unknown as z.ZodType<RequestPayload<'session.updateQueue'>>
 

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

@@ -4,8 +4,8 @@
  * else references RequestPayload<'session.*'> / ResponseValue<'session.*'>.
  */
 
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 // The pure-type outlet: api/ is browser-importable, and the package root's
 // cordis Context merge (via dsh-agent) must not enter client aggregates.
@@ -89,8 +89,6 @@ export interface ModelCatalogModel {
   name: string
   /** Optional provider-supplied description. */
   description?: string
-  /** The current model was inserted because the advisory catalog omitted it. */
-  unlisted?: true
   /** Exact-route reasoning metadata when the adapter exposes it. */
   reasoning?: ModelReasoning
 }
@@ -129,6 +127,7 @@ export interface SessionModels {
 export type QueueAction =
   | { kind: 'edit'; content: ContentBlock[] }
   | { kind: 'remove' }
+  | { kind: 'steer' }
 
 /** Session list entry (v1 builds no index: list does readdir+stat). */
 export interface SessionSummary {
@@ -153,6 +152,8 @@ export interface SessionSummary {
   blank: boolean
   /** fork/spawn lineage (session.header.parentSession passthrough); absent for root sessions. */
   parentSessionId?: SessionId
+  /** Coarse durable origin used by navigation surfaces; never proves resumability. */
+  origin?: 'subagent'
   /** Session working directory (header.cwd passthrough); absent when unrecorded. */
   cwd?: string
   /**
@@ -217,17 +218,22 @@ export interface SessionsApi {
    * the client needs a fresh baseline already pulls the tail page, and
    * loadOlder (the only beforeSeq path) is the only path that never needs one.
    * A deployment without the registry serves histories without the block.
+   * Reading history uses an attached Session or persistence inspection and
+   * never resumes or publishes an Agent.
    */
   history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
   Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; projections?: SessionProjectionsBlock }>>
 
-  /** Reads a fresh advisory model directory for this session. Provider lookups run independently. */
+  /**
+   * Reads a fresh advisory model directory for an ordinary session. Provider
+   * lookups run independently; subagents reject with `agent-busy`.
+   */
   models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>
 
   /**
    * Selects the complete target for this session. Exact model metadata
    * validates an optional reasoning effort, while catalog membership remains
-   * advisory.
+   * advisory. Session-backed subagents reject with `agent-busy`.
    */
   selectModel(request: RpcRequest<{
     sessionId: SessionId
@@ -243,6 +249,7 @@ export interface SessionsApi {
    * normalized accepted title and the title event's seq return so the caller
    * can settle its projection cell without waiting for the push frame. A
    * title that normalizes to empty fails with `title-invalid`.
+   * Session-backed subagents reject with `agent-busy`.
    */
   rename(request: RpcRequest<{ sessionId: SessionId; title: string }>):
   Promise<RpcResponse<{ title: string; seq: number }>>
@@ -263,23 +270,31 @@ export interface SessionsApi {
    * falls back to the source's last completed turn. An in-log anchor whose
    * turn is still open fails with `fork-unavailable` instead of clipping to
    * an earlier turn. The child inherits the source cwd, latest logged model
-   * target, workspace attachment, and `parentSessionId` lineage; the seed
-   * prefix carries the source title.
+   * target and `parentSessionId` lineage; the seed prefix carries the source
+   * title. Reading the source uses attached state or persistence inspection
+   * without acquiring an Agent. Workspace attachment follows the source
+   * directly, or the nearest workspace-owning ancestor when the source is a
+   * subagent.
    */
   fork(request: RpcRequest<{ sessionId: SessionId; atSeq?: number }>):
   Promise<RpcResponse<{ sessionId: SessionId }>>
 
-  /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
+  /** Sends a message to an ordinary session Agent. Session-backed subagents reject with `agent-busy` and use `subagent.prompt`. */
   prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
   Promise<RpcResponse<{ accepted: true; command?: { kind: 'success'; text?: string } }>>
 
   /**
-   * Edits or removes one pending queued occurrence.
+   * Edits, removes, or strictly steers one pending queued occurrence on an ordinary session.
+   * Session-backed subagents reject with `agent-busy`.
    */
-  updateQueue(request: RpcRequest<{ sessionId: SessionId; itemId: InboxItemId; action: QueueAction }>):
+  updateQueue(request: RpcRequest<{ sessionId: SessionId; itemId: MessageId; action: QueueAction }>):
   Promise<RpcResponse<{ accepted: true }>>
 
-  /** Stops the active turn, preserving pending inbox work that resumes in FIFO order after cancellation settles. */
+  /**
+   * Stops an ordinary session's active turn, preserving pending inbox work
+   * that resumes in FIFO order after cancellation settles. Session-backed
+   * subagents reject with `agent-busy`.
+   */
   cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>
 
 }

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

@@ -32,9 +32,18 @@ export const settingsDescribeRequestSchema = z.object({}) satisfies z.ZodType<Wi
 /** settings.describe response value. */
 export const settingsDescribeValueSchema = z.object({
   writable: z.boolean(),
+  hasDocument: z.boolean(),
   namespaces: z.array(settingsNamespaceViewSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'settings.describe'>>>
 
+/** settings.openDocument request payload. */
+export const settingsOpenDocumentRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'settings.openDocument'>>>
+
+/** settings.openDocument response value. */
+export const settingsOpenDocumentValueSchema = z.object({
+  opened: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'settings.openDocument'>>>
+
 /** settings.update request payload. */
 export const settingsUpdateRequestSchema = z.object({
   ns: z.string().min(1),

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

@@ -53,10 +53,26 @@ export type SettingsPathOpView =
 export interface SettingsApi {
   /**
    * Describe every registered namespace: redacted layered values plus the
-   * serialized schema a client renders its form from. `writable: false`
-   * (read-only provider) tells the client to disable every write control.
+   * serialized schema a client renders its form from. `hasDocument` reports
+   * whether a file-backed provider owns a local document without exposing its
+   * Host path. This method is loopback-only; `writable: false` (read-only
+   * provider) tells the client to disable every write control.
    */
-  describe(request: RpcRequest<{}>): Promise<RpcResponse<{ writable: boolean; namespaces: SettingsNamespaceView[] }>>
+  describe(request: RpcRequest<{}>): Promise<RpcResponse<{
+    writable: boolean
+    hasDocument: boolean
+    namespaces: SettingsNamespaceView[]
+  }>>
+
+  /**
+   * Materialize the configured local document when absent and ask the Host to
+   * hand it to the platform text-document opener. macOS forces a text editor;
+   * Linux and Windows use the desktop file association. The request carries
+   * no path, so the browser cannot choose an arbitrary Host filesystem target.
+   */
+  openDocument(
+    request: RpcRequest<{}>, signal: AbortSignal,
+  ): Promise<RpcResponse<{ opened: true }>>
 
   /**
    * Merge a patch into one namespace's user layer (validate → persist →

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

@@ -0,0 +1,77 @@
+/** Zod schemas for the browser-safe subagent domain. */
+
+import { z } from 'zod'
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import {
+  contentBlockSchema, historyEntrySchema, sessionIdSchema, sessionProjectionsBlockSchema,
+} from './sessions.schema.ts'
+import type { SubagentListEntry } from './subagents.ts'
+
+/** Healthy and diagnostic durable catalog rows. */
+export const subagentListEntrySchema = z.union([
+  z.object({
+    kind: z.literal('child'),
+    id: sessionIdSchema,
+    mode: z.literal('one-shot'),
+    activity: z.union([z.literal('running'), z.literal('inactive')]),
+    hasChildren: z.boolean(),
+    label: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('child'),
+    id: sessionIdSchema,
+    mode: z.literal('continuable'),
+    activity: z.union([z.literal('running'), z.literal('inactive')]),
+    hasChildren: z.boolean(),
+    label: z.string(),
+  }),
+  z.object({
+    kind: z.literal('diagnostic'),
+    id: sessionIdSchema,
+    reason: z.union([z.literal('corrupt'), z.literal('unsupported'), z.literal('unavailable')]),
+  }),
+]) satisfies z.ZodType<Wire<SubagentListEntry>>
+
+/** subagent.list request payload. */
+export const subagentListRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.list'>>>
+
+/** subagent.list response value. */
+export const subagentListValueSchema = z.object({
+  entries: z.array(subagentListEntrySchema),
+  parentAvailable: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.list'>>>
+
+/** subagent.history request payload. */
+export const subagentHistoryRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  mode: z.union([z.literal('one-shot'), z.literal('continuable')]),
+  beforeSeq: z.number().int().nonnegative().optional(),
+  maxMessages: z.number().int().positive().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.history'>>>
+
+/** subagent.history response value. */
+export const subagentHistoryValueSchema = z.object({
+  events: z.array(historyEntrySchema),
+  hasMore: z.boolean(),
+  projections: sessionProjectionsBlockSchema.optional(),
+}) as unknown as z.ZodType<Wire<ResponseValue<'subagent.history'>>>
+
+/** subagent.prompt request payload. */
+export const subagentPromptRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  mode: z.literal('continuable'),
+  content: z.array(contentBlockSchema),
+}) as unknown as z.ZodType<RequestPayload<'subagent.prompt'>>
+
+const messageIdSchema = z.string() as unknown as z.ZodType<MessageId>
+
+/** subagent.prompt response value. */
+export const subagentPromptValueSchema = z.object({
+  messageId: messageIdSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.prompt'>>>

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

@@ -0,0 +1,96 @@
+/**
+ * Browser-safe subagent domain contract. Persisted transcript reads never
+ * activate an Agent, while continuable prompts route through the exact live
+ * direct parent into the child's Agent inbox.
+ */
+
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+import type { HistoryEntry, SessionProjectionsBlock } from './sessions.ts'
+
+/** Complete durable direct-child catalog row. */
+export type SubagentListEntry =
+  | {
+    kind: 'child'
+    id: SessionId
+    /** Whether the child Agent driver is running at the Host sampling boundary. */
+    activity: 'running' | 'inactive'
+    /** Whether a direct descendant has durable `origin: 'subagent'`. */
+    hasChildren: boolean
+  } & (
+    | {
+      mode: 'one-shot'
+      label?: string
+    }
+    | {
+      mode: 'continuable'
+      label: string
+    }
+  )
+  | {
+    kind: 'diagnostic'
+    id: SessionId
+    reason: 'corrupt' | 'unsupported' | 'unavailable'
+  }
+
+/** Inbox identity returned once the continuation accepts one human message. */
+export interface SubagentPromptReceipt {
+  messageId: MessageId
+}
+
+/** Durable parent/child address that selects subagent transport in the client. */
+export type SubagentAddress =
+  & {
+    parentSessionId: SessionId
+    childSessionId: SessionId
+  }
+  & (
+    | { mode: 'one-shot' }
+    | { mode: 'continuable' }
+  )
+
+/** Complete direct-child catalog plus the delivery-time parent availability hint. */
+export interface SubagentCatalog {
+  entries: SubagentListEntry[]
+  parentAvailable: boolean
+}
+
+/** Subagent-domain unary methods. */
+export interface SubagentsApi {
+  /**
+   * Lists direct session-backed children without loading either side. Parent
+   * availability is a hint; continuable prompt performs the authoritative
+   * check.
+   */
+  list(
+    request: RpcRequest<{ parentSessionId: SessionId }>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<SubagentCatalog>>
+
+  /**
+   * Reads one healthy catalog child's persisted raw log with ordinary
+   * message-aligned pagination and render intents, without Agent activation.
+   */
+  history(
+    request: RpcRequest<SubagentAddress & { beforeSeq?: number; maxMessages?: number }>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<{
+    events: HistoryEntry[]
+    hasMore: boolean
+    projections?: SessionProjectionsBlock
+  }>>
+
+  /**
+   * Delivers human content to a continuable child through the exact live
+   * parent's continuation owner. Success identifies the message accepted by
+   * the child's FIFO inbox; later execution is independent of this request.
+   */
+  prompt(
+    request: RpcRequest<
+      Extract<SubagentAddress, { mode: 'continuable' }> & { content: ContentBlock[] }
+    >,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<SubagentPromptReceipt>>
+}