feat(web): project plan mode through host API

packages/host/apiproxy/README.md

@@ -10,6 +10,8 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc
 
 The mux stream projects the latest log-backed title as a validated `session/title` control frame after each attached-session subscription baseline and immediately after the corresponding live raw title event. This projection does not add titles to `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.
 
+Plan mode uses two unary methods instead of deriving current state from a history page: `session.planMode` returns the committed state plus any boundary-pending selection, and `session.setPlanMode` records a selection and returns the same authoritative shape. Both return `null` when the optional host service is absent; `null` is capability absence, while `{ active: false }` is a supported inactive session. Committed changes still arrive through the raw logged `plan/mode` session event.
+
 ## Carrier layer (`/client` + root)
 
 `AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.

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

@@ -19,7 +19,7 @@ export interface ApiProxy {
 }
 
 // ---- Domain interfaces and payload entities ----
-export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
+export type { HistoryEntry, PlanModeState, SessionsApi, SessionSummary } from './sessions.ts'
 export type { HostApi } from './host.ts'
 export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'

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

@@ -15,6 +15,8 @@ export interface RpcMethodMap {
   'session.history': SessionsApi['history']
   'session.prompt': SessionsApi['prompt']
   'session.cancel': SessionsApi['cancel']
+  'session.planMode': SessionsApi['planMode']
+  'session.setPlanMode': SessionsApi['setPlanMode']
   'host.describe': HostApi['describe']
 }
 

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

@@ -9,7 +9,7 @@ import { z } from 'zod'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
-import type { HistoryEntry, SessionSummary } from './sessions.ts'
+import type { HistoryEntry, PlanModeState, SessionSummary } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
 
 /** SessionId: one brand cast after shape validation (the only cast point in this domain). */
@@ -108,3 +108,28 @@ export const sessionCancelRequestSchema = z.object({
 export const sessionCancelValueSchema = z.object({
   accepted: z.literal(true),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.cancel'>>>
+
+/** Plan state shared by the read and selection responses. */
+export const planModeStateSchema = z.object({
+  active: z.boolean(),
+  pending: z.boolean().optional(),
+}) satisfies z.ZodType<Wire<PlanModeState>>
+
+/** session.planMode request payload. */
+export const sessionPlanModeRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.planMode'>>>
+
+/** session.planMode response value; null means the optional service is absent. */
+export const sessionPlanModeValueSchema =
+  planModeStateSchema.nullable() satisfies z.ZodType<Wire<ResponseValue<'session.planMode'>>>
+
+/** session.setPlanMode request payload. */
+export const sessionSetPlanModeRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  active: z.boolean(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.setPlanMode'>>>
+
+/** session.setPlanMode response value; null means the optional service is absent. */
+export const sessionSetPlanModeValueSchema =
+  planModeStateSchema.nullable() satisfies z.ZodType<Wire<ResponseValue<'session.setPlanMode'>>>

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

@@ -44,6 +44,16 @@ export interface SessionSummary {
   cwd?: string
 }
 
+/**
+ * Plan collaboration state exposed to clients. `active` is the logged state
+ * shaping the current request; `pending`, when present, is the user's
+ * next-boundary selection.
+ */
+export interface PlanModeState {
+  active: boolean
+  pending?: boolean
+}
+
 /** Session-domain unary methods (the map keys session.* of RpcMethodMap). */
 export interface SessionsApi {
   /** Lists persisted sessions (updatedAt descending). v1 returns everything; cursor is a reserved seat, unimplemented. */
@@ -70,4 +80,18 @@ export interface SessionsApi {
 
   /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */
   cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>
+
+  /**
+   * Reads plan collaboration state. `null` means the host did not compose the
+   * optional plan-mode service; it is distinct from inactive state.
+   */
+  planMode(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<PlanModeState | null>>
+
+  /**
+   * Selects plan collaboration state for the next model-request boundary.
+   * The returned state exposes the still-committed value and pending target;
+   * `null` means plan mode is unavailable on this host.
+   */
+  setPlanMode(request: RpcRequest<{ sessionId: SessionId; active: boolean }>):
+  Promise<RpcResponse<PlanModeState | null>>
 }

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

@@ -19,7 +19,9 @@ import {
   sessionCreateValueSchema,
   sessionHistoryValueSchema,
   sessionListValueSchema,
+  sessionPlanModeValueSchema,
   sessionPromptValueSchema,
+  sessionSetPlanModeValueSchema,
 } from '../api/sessions.schema.ts'
 
 /**
@@ -44,6 +46,8 @@ export interface IApiClient {
     history(payload: RequestPayload<'session.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.history'>>>
     prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
     cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
+    planMode(payload: RequestPayload<'session.planMode'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.planMode'>>>
+    setPlanMode(payload: RequestPayload<'session.setPlanMode'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.setPlanMode'>>>
   }
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
@@ -66,6 +70,8 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.history': sessionHistoryValueSchema,
   'session.prompt': sessionPromptValueSchema,
   'session.cancel': sessionCancelValueSchema,
+  'session.planMode': sessionPlanModeValueSchema,
+  'session.setPlanMode': sessionSetPlanModeValueSchema,
   'host.describe': hostDescribeValueSchema,
 }
 
@@ -247,6 +253,8 @@ export abstract class AbstractApiClient implements IApiClient {
     history: (payload, signal) => this.callUnary('session.history', payload, signal),
     prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
     cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
+    planMode: (payload, signal) => this.callUnary('session.planMode', payload, signal),
+    setPlanMode: (payload, signal) => this.callUnary('session.setPlanMode', payload, signal),
   }
 
   readonly host: IApiClient['host'] = {

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

@@ -19,7 +19,9 @@ import {
   sessionCreateRequestSchema,
   sessionHistoryRequestSchema,
   sessionListRequestSchema,
+  sessionPlanModeRequestSchema,
   sessionPromptRequestSchema,
+  sessionSetPlanModeRequestSchema,
 } from '../api/sessions.schema.ts'
 import { hostDescribeRequestSchema } from '../api/host.schema.ts'
 
@@ -43,6 +45,8 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.history': { schema: sessionHistoryRequestSchema, invoke: (api, r) => api.sessions.history(r) },
   'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
+  'session.planMode': { schema: sessionPlanModeRequestSchema, invoke: (api, r) => api.sessions.planMode(r) },
+  'session.setPlanMode': { schema: sessionSetPlanModeRequestSchema, invoke: (api, r) => api.sessions.setPlanMode(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
 }
 

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

@@ -31,6 +31,8 @@ function scriptedApi(overrides: {
       history: r => ok(r, { events: [], hasMore: false }),
       prompt: r => ok(r, { accepted: true as const }),
       cancel: r => ok(r, { accepted: true as const }),
+      planMode: r => ok(r, null),
+      setPlanMode: r => ok(r, null),
       ...overrides.sessions,
     },
     host: { describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }), ...overrides.host },

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

@@ -36,6 +36,12 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       async cancel(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
+      async planMode(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: null } }
+      },
+      async setPlanMode(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: null } }
+      },
     },
     host: {
       async describe(request) {
@@ -75,11 +81,13 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
   })
 
-  it('covers create/prompt/cancel/describe passthrough', async () => {
+  it('covers create/prompt/cancel/plan/describe passthrough', async () => {
     const c = client()
     expect((await c.sessions.create({})).result.ok).toBe(true)
     expect((await c.sessions.prompt({ sessionId: 's' as never, mode: 'queue', content: [{ type: 'text', text: 'x' }] })).result.ok).toBe(true)
     expect((await c.sessions.cancel({ sessionId: 's' as never })).result.ok).toBe(true)
+    expect((await c.sessions.planMode({ sessionId: 's' as never })).result).toEqual({ ok: true, value: null })
+    expect((await c.sessions.setPlanMode({ sessionId: 's' as never, active: true })).result).toEqual({ ok: true, value: null })
     expect((await c.host.describe({})).result.ok).toBe(true)
   })
 })

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

@@ -9,7 +9,8 @@ import {
   contentBlockSchema, sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
   sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
   sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionPromptRequestSchema,
-  sessionPromptValueSchema, sessionSummarySchema,
+  sessionPlanModeRequestSchema, sessionPlanModeValueSchema, sessionPromptValueSchema,
+  sessionSetPlanModeRequestSchema, sessionSetPlanModeValueSchema, sessionSummarySchema,
 } from '../src/api/sessions.schema.ts'
 import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
@@ -106,6 +107,13 @@ describe('sessions domain schemas', () => {
     expect(sessionPromptValueSchema.parse({ accepted: true }).accepted).toBe(true)
     expect(sessionCancelRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionCancelValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    expect(sessionPlanModeRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionPlanModeValueSchema.parse({ active: false, pending: true })).toEqual({ active: false, pending: true })
+    expect(sessionPlanModeValueSchema.parse(null)).toBeNull()
+    expect(sessionSetPlanModeRequestSchema.parse({ sessionId: 's1', active: true }).active).toBe(true)
+    expect(sessionSetPlanModeValueSchema.parse({ active: true })).toEqual({ active: true })
+    expect(() => sessionSetPlanModeRequestSchema.parse({ sessionId: 's1', active: 'yes' })).toThrow()
+    expect(() => sessionPlanModeValueSchema.parse({ active: 'yes' })).toThrow()
     expect(contentBlockSchema.parse({ type: 'text', text: 'x', extra: 1 })).toMatchObject({ extra: 1 })
   })
 })