Merge origin/master (goal line #527) into web-permission-sandbox-merge-master

Shared-surface conflicts resolve as unions: the fixture serves all four
projection keys (title/todos/permissions/goal) with both the /permission
and /goal command mirrors (the goal-fixture placeholder retires with
master), apps/cli carries both lines' dependency additions, and the README
Model Experience allowlist keeps both entries. The connection specs assert
the four-key baseline and the shifted approval/question replay indices;
the module graph regenerates over the merged dependency set.

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

@@ -24,7 +24,7 @@ import {
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
-  ApiProxy, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup, ModelReasoning,
+  ApiProxy, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup, ModelReasoning,
   MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSummary, ToolEventView,
   WorkspaceId, WorkspaceView,
 } from './api/index.ts'
@@ -32,6 +32,9 @@ import type {
 import type {} from '@deepseek-ai/dsh-session-projection'
 // Type-only: resolves `ctx.get('sessionProjectionCache')` (the cold listing column).
 import type {} from '@deepseek-ai/dsh-session-projection-cache'
+// GoalError narrows domain rejections to their stable codes at the wire boundary.
+import { GoalError } from '@deepseek-ai/dsh-goal'
+import type { GoalRef as CoreGoalRef } from '@deepseek-ai/dsh-goal'
 // Type-only edges: resolve `ctx.get('commands')`, the `commands/change` event, and `ctx.get('skills')`.
 import type {} from '@deepseek-ai/dsh-commands'
 import type {} from '@deepseek-ai/dsh-skill'
@@ -773,6 +776,38 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     return operation
   }
 
+  /** Resolve the goal service; absent = the deployment did not compose @deepseek-ai/dsh-goal. */
+  function goalService(): NonNullable<ReturnType<typeof ctx.get<'goals'>>> | { error: RpcError } {
+    const goals = ctx.get('goals')
+    if (goals === undefined) {
+      return { error: { code: 'internal', message: 'goal service is absent: this deployment does not mount @deepseek-ai/dsh-goal in its composition (cordis.yml or explicit assembly)', details: {} } }
+    }
+    return goals
+  }
+
+  /** Map one goal-domain rejection to the wire error (stable GoalError codes ride in details). */
+  function goalError(request: RpcRequest<unknown>, error: unknown): RpcResponse<never> {
+    const details = error instanceof GoalError ? { goalCode: error.code } : {}
+    return err(request, { code: 'internal', message: String(error), details })
+  }
+
+  /** Resolve a session's agent, apply one goal mutation, and acknowledge with the new CAS ref. */
+  async function mutateGoal(
+    request: RpcRequest<{ sessionId: SessionId }>,
+    mutation: (goals: NonNullable<ReturnType<typeof ctx.get<'goals'>>>, agent: Agent) => CoreGoalRef,
+  ): Promise<RpcResponse<{ ref: GoalRef }>> {
+    const goals = goalService()
+    if ('error' in goals) return err(request, goals.error)
+    const found = await agentFor(request.payload.sessionId)
+    if ('error' in found) return err(request, found.error)
+    try {
+      const ref = mutation(goals, found.agent)
+      return ok(request, { ref: { id: ref.id, revision: ref.revision } })
+    } catch (error: unknown) {
+      return goalError(request, error)
+    }
+  }
+
   return {
     sessions: {
       // Attached sessions summarize from memory; persisted-but-unattached (cold)
@@ -1230,6 +1265,54 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       },
     },
 
+    goals: {
+      // Mutations only — the read side is the 'goal' session projection.
+      // Every verb resolves the session's agent (agentFor: implicit cold
+      // resume, the command.* precedent) and acknowledges with the new CAS
+      // ref; the committed goal/change event carries the whole value to every
+      // client through the projection frames.
+      async create(request) {
+        const { objective, maxGoalRounds } = request.payload
+        return mutateGoal(request, (goals, agent) => goals.create(agent, {
+          objective,
+          ...(maxGoalRounds !== undefined ? { maxGoalRounds } : {}),
+        }))
+      },
+
+      async edit(request) {
+        const { ref, objective, maxGoalRounds } = request.payload
+        return mutateGoal(request, (goals, agent) => goals.edit(agent, ref, {
+          ...(objective !== undefined ? { objective } : {}),
+          ...(maxGoalRounds !== undefined ? { maxGoalRounds } : {}),
+        }))
+      },
+
+      async pause(request) {
+        return mutateGoal(request, (goals, agent) => goals.pause(agent, request.payload.ref))
+      },
+
+      async resume(request) {
+        return mutateGoal(request, (goals, agent) => goals.resume(agent, request.payload.ref))
+      },
+
+      async complete(request) {
+        return mutateGoal(request, (goals, agent) => goals.complete(agent, request.payload.ref))
+      },
+
+      async clear(request) {
+        const goals = goalService()
+        if ('error' in goals) return err(request, goals.error)
+        const found = await agentFor(request.payload.sessionId)
+        if ('error' in found) return err(request, found.error)
+        try {
+          goals.clear(found.agent, request.payload.ref)
+          return ok(request, { cleared: true as const })
+        } catch (error: unknown) {
+          return goalError(request, error)
+        }
+      },
+    },
+
     skills: {
       // Skill lookup never touches the Agent registry: the session address
       // resolves to a canonical cwd from the host-resident session header, so

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

@@ -0,0 +1,79 @@
+/**
+ * goals domain zod schemas. Mutation-only shapes: every value schema is a
+ * `{ ref }` acknowledgement (clear: `{ cleared }`) — the current goal state
+ * travels exclusively on the 'goal' session projection.
+ */
+
+import { z } from 'zod'
+import type { Wire } from './rpc.schema.ts'
+import type { GoalRef, RequestPayload, ResponseValue } from './index.ts'
+
+/** GoalRef schema. */
+export const goalRefSchema = z.object({
+  id: z.string(),
+  revision: z.number().int().positive(),
+}) as unknown as z.ZodType<Wire<GoalRef>>
+
+/** Shared `{ ref }` acknowledgement value of every non-clear mutation. */
+const goalRefValueSchema = z.object({ ref: goalRefSchema })
+
+/** goal.create request payload. */
+export const goalCreateRequestSchema = z.object({
+  sessionId: z.string(),
+  objective: z.string().min(1),
+  maxGoalRounds: z.number().int().positive().optional(),
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.create'>>>
+
+/** goal.create response value. */
+export const goalCreateValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.create'>>>
+
+/** goal.edit request payload. */
+export const goalEditRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+  objective: z.string().min(1).optional(),
+  maxGoalRounds: z.number().int().positive().optional(),
+}).refine(value => value.objective !== undefined || value.maxGoalRounds !== undefined, {
+  message: 'goal.edit requires objective or maxGoalRounds',
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.edit'>>>
+
+/** goal.edit response value. */
+export const goalEditValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.edit'>>>
+
+/** goal.pause request payload. */
+export const goalPauseRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.pause'>>>
+
+/** goal.pause response value. */
+export const goalPauseValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.pause'>>>
+
+/** goal.resume request payload. */
+export const goalResumeRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.resume'>>>
+
+/** goal.resume response value. */
+export const goalResumeValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.resume'>>>
+
+/** goal.complete request payload. */
+export const goalCompleteRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.complete'>>>
+
+/** goal.complete response value. */
+export const goalCompleteValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.complete'>>>
+
+/** goal.clear request payload. */
+export const goalClearRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.clear'>>>
+
+/** goal.clear response value. */
+export const goalClearValueSchema = z.object({
+  cleared: z.literal(true),
+}) as unknown as z.ZodType<Wire<ResponseValue<'goal.clear'>>>

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

@@ -0,0 +1,50 @@
+/**
+ * goals domain contract. Method signatures are the source of truth:
+ * unary methods take the RpcRequest<P> narrow form and the impl echoes rpcId.
+ *
+ * Mutations only: the read side is the 'goal' session projection (history
+ * tail-page projections block + session/projection frames), so there is no
+ * goal.get and no wire goal view — responses acknowledge with the new CAS
+ * ref and never feed client state (the committed goal/change event reaches
+ * every client through the mux stream carrying the same whole value).
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** Identifies one goal across its durable revisions. */
+export type GoalId = Branded<'GoalId'>
+
+/** Compare-and-set identity for one exact goal revision. */
+export interface GoalRef {
+  readonly id: GoalId
+  readonly revision: number
+}
+
+/** Goal-domain unary methods (every mutation resolves the session's agent and applies one CAS-guarded verb). */
+export interface GoalsApi {
+  /** Create and arm a goal. */
+  create(request: RpcRequest<{ sessionId: SessionId; objective: string; maxGoalRounds?: number }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Edit objective and/or round cap without changing phase. */
+  edit(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef; objective?: string; maxGoalRounds?: number }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Pause an active goal and disarm automatic continuation. */
+  pause(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Resume and arm a stopped goal. */
+  resume(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Mark a current non-complete goal complete and disarm it. */
+  complete(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Clear the current goal while retaining a durable tombstone and history. */
+  clear(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ cleared: true }>>
+}

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

@@ -10,6 +10,7 @@ import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
 import type { SkillsApi } from './skills.ts'
 import type { EventsApi } from './events.ts'
+import type { GoalsApi } from './goals.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. */
@@ -20,6 +21,7 @@ export interface ApiProxy {
   commands: CommandsApi
   skills: SkillsApi
   events: EventsApi
+  goals: GoalsApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
   respond(message: ClientResponse): Promise<RpcReceipt>
 }
@@ -34,6 +36,7 @@ export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'
 export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
+export type { GoalsApi, GoalId, GoalRef } from './goals.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
 export type { QuestionResponsePayload } from './questions.ts'
 

packages/host/apiproxy/src/api/rpc-map.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 { GoalsApi } from './goals.ts'
 import type { RpcResponse } from './rpc.ts'
 
 /**
@@ -35,6 +36,12 @@ export interface RpcMethodMap {
   'command.list': CommandsApi['list']
   'command.execute': CommandsApi['execute']
   'skill.list': SkillsApi['list']
+  'goal.create': GoalsApi['create']
+  'goal.edit': GoalsApi['edit']
+  'goal.pause': GoalsApi['pause']
+  'goal.resume': GoalsApi['resume']
+  'goal.complete': GoalsApi['complete']
+  'goal.clear': GoalsApi['clear']
 }
 
 /** Business request payload of method K (reaches through the RpcRequest narrow form to payload). */

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

@@ -43,6 +43,8 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('workspace-name-conflict'), message: z.string(), details: z.object({ name: z.string() }) }),
   z.object({ code: z.literal('workspace-move-invalid'), message: z.string(), details: z.object({ workspaceId: z.string(), sessionId: z.string(), beforeSessionId: z.string().optional() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: 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('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>
 

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

@@ -40,6 +40,10 @@ export interface RpcErrorDetailsMap {
   'workspace-name-conflict': { name: string }
   'workspace-move-invalid': { workspaceId: string; sessionId: SessionId; beforeSessionId?: SessionId }
   'agent-busy': { reason: string }
+  /** 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. */
+  'unknown-command': {}
   'internal': {}
 }
 

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

@@ -193,9 +193,13 @@ export const sessionPromptRequestSchema = z.object({
   content: z.array(contentBlockSchema),
 }) as unknown as z.ZodType<RequestPayload<'session.prompt'>>
 
-/** session.prompt response value. */
+/** session.prompt response value (the command slot appears only when the prompt dispatched a slash command). */
 export const sessionPromptValueSchema = z.object({
   accepted: z.literal(true),
+  command: z.object({
+    kind: z.literal('success'),
+    text: z.string().optional(),
+  }).optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.prompt'>>>
 
 /** session.cancel request payload. */

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

@@ -206,9 +206,16 @@ export interface SessionsApi {
   }>):
   Promise<RpcResponse<{ selected: ModelTarget }>>
 
-  /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
+  /**
+   * Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer.
+   * A prompt whose content is exactly one text block starting with '/' is a slash command: the host
+   * executes it through the command registry (mode-agnostic) and it is never sent to the model. A
+   * successful command returns ok with the command slot (its success text, when the command produced
+   * one — carried for future rendering; the state change is the feedback). A usage/state error is an
+   * RPC error with code command-error; an unrecognized name is an RPC error with code unknown-command.
+   */
   prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
-  Promise<RpcResponse<{ accepted: true }>>
+  Promise<RpcResponse<{ accepted: true; command?: { kind: 'success'; text?: string } }>>
 
   /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */
   cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>

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

@@ -34,6 +34,14 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
 import { skillListValueSchema } from '../api/skills.schema.ts'
+import {
+  goalCreateValueSchema,
+  goalEditValueSchema,
+  goalPauseValueSchema,
+  goalResumeValueSchema,
+  goalCompleteValueSchema,
+  goalClearValueSchema,
+} from '../api/goals.schema.ts'
 
 /**
  * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
@@ -83,6 +91,14 @@ export interface IApiClient {
     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>>
   }
+  goals: {
+    create(payload: RequestPayload<'goal.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.create'>>>
+    edit(payload: RequestPayload<'goal.edit'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.edit'>>>
+    pause(payload: RequestPayload<'goal.pause'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.pause'>>>
+    resume(payload: RequestPayload<'goal.resume'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.resume'>>>
+    complete(payload: RequestPayload<'goal.complete'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.complete'>>>
+    clear(payload: RequestPayload<'goal.clear'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.clear'>>>
+  }
   /** client-response passthrough (rpcId is a backfill of the server-request's id — never minted here). */
   respond(message: ClientResponse, signal?: AbortSignal): Promise<RpcReceipt>
 }
@@ -110,6 +126,12 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'command.list': commandListValueSchema,
   'command.execute': commandExecuteValueSchema,
   'skill.list': skillListValueSchema,
+  'goal.create': goalCreateValueSchema,
+  'goal.edit': goalEditValueSchema,
+  'goal.pause': goalPauseValueSchema,
+  'goal.resume': goalResumeValueSchema,
+  'goal.complete': goalCompleteValueSchema,
+  'goal.clear': goalClearValueSchema,
 }
 
 /** Default unary timeout (rpc-compare 2026-07-19: a hung host must not leave callers pending forever). */
@@ -329,6 +351,15 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('skill.list', payload, signal),
   }
 
+  readonly goals: IApiClient['goals'] = {
+    create: (payload, signal) => this.callUnary('goal.create', payload, signal),
+    edit: (payload, signal) => this.callUnary('goal.edit', payload, signal),
+    pause: (payload, signal) => this.callUnary('goal.pause', payload, signal),
+    resume: (payload, signal) => this.callUnary('goal.resume', payload, signal),
+    complete: (payload, signal) => this.callUnary('goal.complete', payload, signal),
+    clear: (payload, signal) => this.callUnary('goal.clear', payload, signal),
+  }
+
   readonly events: IApiClient['events'] = {
     mux: (payload, signal, onOpen) => this.openMux(payload, signal, onOpen),
     host: (payload, signal, onOpen) => this.openHost(payload, signal, onOpen),

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

@@ -35,6 +35,14 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
 import { skillListRequestSchema } from '../api/skills.schema.ts'
+import {
+  goalCreateRequestSchema,
+  goalEditRequestSchema,
+  goalPauseRequestSchema,
+  goalResumeRequestSchema,
+  goalCompleteRequestSchema,
+  goalClearRequestSchema,
+} from '../api/goals.schema.ts'
 
 /**
  * Unary dispatch table, keyed by (and compiler-locked to) RpcMethodMap: a map row without a
@@ -71,6 +79,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) },
+  '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) },
+  'goal.resume': { schema: goalResumeRequestSchema, invoke: (api, r) => api.goals.resume(r) },
+  'goal.complete': { schema: goalCompleteRequestSchema, invoke: (api, r) => api.goals.complete(r) },
+  'goal.clear': { schema: goalClearRequestSchema, invoke: (api, r) => api.goals.clear(r) },
 }
 
 /** Route lookup that narrows an arbitrary path segment to a map key (single cast point for the string→key refinement). */

packages/host/apiproxy/src/index.ts

@@ -57,6 +57,7 @@ export class ApiProxyService extends Service implements ApiProxy {
   readonly workspace: ApiProxy['workspace']
   readonly host: ApiProxy['host']
   readonly commands: ApiProxy['commands']
+  readonly goals: ApiProxy['goals']
   readonly skills: ApiProxy['skills']
   readonly events: ApiProxy['events']
   readonly respond: ApiProxy['respond']
@@ -74,6 +75,7 @@ export class ApiProxyService extends Service implements ApiProxy {
     this.workspace = api.workspace
     this.host = api.host
     this.commands = api.commands
+    this.goals = api.goals
     this.skills = api.skills
     this.events = api.events
     // createApiProxy returns closures (no `this` capture); bind only satisfies