dsh-plugin-mobile-gateway 0.6.9 → 0.7.1

package/lib/index.mjs

@@ -6,7 +6,7 @@
 //     feed the browser UI consumes) to connected mobile clients as curated
 //     JSON text frames.
 //  2. Mobile -> agent: clients send a message through the same socket; the
-//     plugin admits it through the official host API (apiProxy.sessions.prompt)
+//     plugin admits it through the DSH Remote Gateway Host API.
 //     so it enters the target session exactly like a browser-submitted prompt.
 //
 // Wire protocol (JSON text frames):
@@ -57,6 +57,10 @@
 //                     { "type": "context-usage", "sessionId" }       -> tokenUsage + contextPressure projections
 //                     { "type": "session-stats", "sessionId" }       -> sessionStats + tokenUsage projections
 //                        (the input-box stats strip source)
+//                     { "type": "tasks", "sessionId" }               -> current todo-list projection
+//                     { "type": "goal", "sessionId" }                -> current goal projection
+//                     { "type": "goal-edit", "sessionId", "ref", "objective"?, "maxGoalRounds"? }
+//                     { "type": "goal-pause"|"goal-resume"|"goal-clear", "sessionId", "ref" }
 //                     { "type": "agent-presets" }                     -> preset roster (+ isDefault)
 //                     { "type": "defaults" }                          -> default agent preset + default permission
 //                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
@@ -64,7 +68,7 @@
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
 //                     { "type": "approval-response", "rpcId", "sessionId", "approvalId",
 //                       "outcome": "allowed-once"|"rejected" }
-//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "file-downloads"],
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "tasks", "goals", "file-downloads"],
 //                       "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
@@ -86,6 +90,12 @@
 //                     { "kind": "file-download-cancelled", "transferId" }
 //                     { "kind": "error", "code", "message", "requestType"?, "sessionId"? }
 //                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
+//                     { "kind": "tasks", "sessionId", "asOfSeq", "todos" }
+//                     { "kind": "goal", "sessionId", "asOfSeq", "goal" }
+//                     { "kind": "goal-edit"|"goal-pause"|"goal-resume", "sessionId", "ref" }
+//                     { "kind": "goal-clear", "sessionId", "cleared": true }
+//                     { "kind": "tasks-updated", "sessionId", "asOfSeq", "todos" }
+//                     { "kind": "goal-updated", "sessionId", "asOfSeq", "goal" }
 //                     { "kind": "question-requested", "rpcId", "sessionId", "questions", "replay"? }
 //                     { "kind": "question-response", "rpcId", "sessionId", "action", "accepted", "reason"? }
 //                     { "kind": "question-resolved", "rpcId", "sessionId", "outcome" }
@@ -104,6 +114,7 @@ import crypto from 'node:crypto'
 import Schema from '@deepseek-ai/schemastery'
 import { WebSocketServer } from 'ws'
 import devicesModule from './devices.js'
+import { createDshHostAdapter } from './dsh-host-adapter.mjs'
 import QRCode from 'qrcode'
 
 const { createRegistry } = devicesModule
@@ -397,25 +408,15 @@ function commandNameOf(line) {
   return (end === -1 ? trimmed.slice(1) : trimmed.slice(1, end)) || null
 }
 
-async function listHostCommands(typertGateway, sessionId) {
-  const listed = await typertGateway.invoke({
-    namespace: 'commands',
-    method: 'list',
-    args: { agentId: sessionId },
-    signal: new AbortController().signal,
-  })
+async function listHostCommands(host, sessionId) {
+  const listed = await host.commands.list(sessionId, new AbortController().signal)
   if (!Array.isArray(listed)) throw new Error('commands/list returned an invalid catalog')
   return listed
 }
 
-async function executeHostCommand(typertGateway, sessionId, line, images, requestType) {
+async function executeHostCommand(host, sessionId, line, images, requestType) {
   try {
-    const execution = await typertGateway.invoke({
-      namespace: 'commands',
-      method: 'execute',
-      args: { agentId: sessionId, line, images },
-      signal: new AbortController().signal,
-    })
+    const execution = await host.commands.execute(sessionId, line, images, new AbortController().signal)
     if (execution === undefined || execution === null) {
       return { kind: 'error', code: 'unknown-command', message: `unknown or malformed command: ${line}`, requestType, sessionId }
     }
@@ -435,7 +436,7 @@ async function executeHostCommand(typertGateway, sessionId, line, images, reques
   }
 }
 
-async function admitCommand(typertGateway, msg) {
+async function admitCommand(host, msg) {
   const sessionId = requireSessionId(msg)
   if (sessionId.error) return sessionId.error
   const line = typeof msg.line === 'string' ? msg.line.trim() : ''
@@ -446,7 +447,7 @@ async function admitCommand(typertGateway, msg) {
   const parsedImages = parseWireImages(msg.images, 'command-execute')
   if (parsedImages.error) return { ...parsedImages.error, sessionId: sessionId.value }
   try {
-    const listed = await listHostCommands(typertGateway, sessionId.value)
+    const listed = await listHostCommands(host, sessionId.value)
     const descriptor = listed.find((command) => command && command.name === name)
     if (!descriptor) {
       return { kind: 'error', code: 'unknown-command', message: `command not found: /${name}`, requestType: 'command-execute', sessionId: sessionId.value }
@@ -454,7 +455,7 @@ async function admitCommand(typertGateway, msg) {
     if (parsedImages.value.length > 0 && descriptor.input?.images !== true) {
       return { kind: 'error', code: 'bad-request', message: `/${name} does not accept image attachments`, requestType: 'command-execute', sessionId: sessionId.value }
     }
-    return executeHostCommand(typertGateway, sessionId.value, line, parsedImages.value, 'command-execute')
+    return executeHostCommand(host, sessionId.value, line, parsedImages.value, 'command-execute')
   } catch (error) {
     const code = error && error.code ? error.code : 'internal'
     const message = error && error.message ? error.message : String(error)
@@ -487,44 +488,30 @@ async function admitMessage(api, msg) {
         if (createPayload.workspaceId) log('mobile message: both workspaceId and cwd given, using workspaceId')
         else createPayload.cwd = msg.cwd.trim()
       }
-      const created = await api.sessions.create({ rpcId: crypto.randomUUID(), payload: createPayload })
-      if (!created.result.ok) {
-        return { kind: 'error', code: created.result.error.code, message: created.result.error.message }
-      }
-      sessionId = created.result.value.sessionId
+      const created = await api.sessions.create(createPayload)
+      sessionId = created.sessionId
       log(`mobile message created new session ${sessionId} (${JSON.stringify(createPayload)})`)
     }
 
     const resp = await api.sessions.prompt({
-      rpcId: crypto.randomUUID(),
-      payload: {
-        sessionId,
-        mode,
-        // Match the official WebUI ordering: images first, optional text last.
-        content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
-        ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
-      },
+      sessionId,
+      mode,
+      // Match the official WebUI ordering: images first, optional text last.
+      content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
+      ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
     })
-    if (resp.result.ok) {
-      log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
-      return {
-        kind: 'sent',
-        sessionId,
-        mode,
-        ...(resp.result.value.command ? { command: resp.result.value.command } : {}),
-      }
-    }
-    log(`mobile message rejected: ${resp.result.error.code}: ${resp.result.error.message}`)
+    log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
     return {
-      kind: 'error',
-      code: resp.result.error.code,
-      message: resp.result.error.message,
-      ...(sessionId ? { sessionId } : {}),
+      kind: 'sent',
+      sessionId,
+      mode,
+      ...(resp.command ? { command: resp.command } : {}),
     }
   } catch (error) {
+    const code = error && error.code ? error.code : 'internal'
     const message = error && error.message ? error.message : String(error)
     log(`mobile message failed: ${message}`)
-    return { kind: 'error', code: 'internal', message, ...(sessionId ? { sessionId } : {}) }
+    return { kind: 'error', code, message, ...(sessionId ? { sessionId } : {}) }
   }
 }
 
@@ -533,23 +520,17 @@ async function admitMessage(api, msg) {
 // the uniform `{ kind: 'error', code, message, requestType }` frame.
 async function proxyQuery(api, type, method, payload, signal) {
   try {
-    const req = { rpcId: crypto.randomUUID(), payload }
-    const resp = signal ? await method(req, signal) : await method(req)
-    if (resp.result.ok) {
-      log(`query ok: ${type}`)
-      return { kind: type, ...resp.result.value }
-    }
-    log(`query rejected: ${type} -> ${resp.result.error.code}: ${resp.result.error.message}`)
-    return {
-      kind: 'error',
-      code: resp.result.error.code,
-      message: resp.result.error.message,
-      requestType: type,
+    const value = signal ? await method(payload, signal) : await method(payload)
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error(`${type} returned an invalid response`)
     }
+    log(`query ok: ${type}`)
+    return { kind: type, ...value }
   } catch (error) {
+    const code = error && error.code ? error.code : 'internal'
     const message = error && error.message ? error.message : String(error)
-    log(`query failed: ${type} -> ${message}`)
-    return { kind: 'error', code: 'internal', message, requestType: type }
+    log(`query failed: ${type} -> ${code}: ${message}`)
+    return { kind: 'error', code, message, requestType: type }
   }
 }
 
@@ -958,6 +939,54 @@ function requireSessionId(msg) {
   return { value: sessionId }
 }
 
+// Goal mutations use DSH's compare-and-set reference. Returning a stale
+// revision is intentionally rejected by DSH instead of overwriting a newer
+// WebUI/mobile update.
+function requireGoalRef(msg, sessionId) {
+  const ref = msg.ref
+  const id = ref && typeof ref.id === 'string' && ref.id.trim() !== '' ? ref.id.trim() : null
+  const revision = ref && typeof ref.revision === 'number' && Number.isSafeInteger(ref.revision) && ref.revision > 0
+    ? ref.revision
+    : null
+  if (!id || revision === null) {
+    return {
+      error: {
+        kind: 'error',
+        code: 'bad-request',
+        message: `${typeof msg.type === 'string' ? msg.type : 'goal mutation'} requires ref.id and a positive integer ref.revision`,
+        requestType: typeof msg.type === 'string' ? msg.type : 'goal',
+        sessionId,
+      },
+    }
+  }
+  return { value: { id, revision } }
+}
+
+async function readSessionProjection(api, type, sessionId, key) {
+  const history = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), { sessionId })
+  if (history.kind !== 'history') return history
+  const values = (history.projections && history.projections.values) || {}
+  return {
+    kind: type,
+    sessionId,
+    asOfSeq: history.projections ? history.projections.asOfSeq : undefined,
+    [key]: Object.prototype.hasOwnProperty.call(values, key) ? values[key] : null,
+  }
+}
+
+async function mutateGoal(api, type, method, payload) {
+  if (!api.goals || typeof api.goals[method] !== 'function') {
+    return {
+      kind: 'error',
+      code: 'unsupported',
+      message: 'goal management is unavailable in this DSH host',
+      requestType: type,
+      sessionId: payload.sessionId,
+    }
+  }
+  return proxyQuery(api, type, api.goals[method].bind(api.goals), payload)
+}
+
 // ---------------------------------------------------------------------------
 // History frame sizing: raw session logs can be huge (trajectory, tool output,
 // context), so a single history response must never blow the client's
@@ -1132,7 +1161,7 @@ async function loadCommandOptions(api, command, sessionId) {
   }
 }
 
-async function selectCommandOption(api, typertGateway, command, sessionId, optionId) {
+async function selectCommandOption(api, host, command, sessionId, optionId) {
   const catalog = await loadCommandOptions(api, command, sessionId)
   if (catalog.kind !== 'command-options') return catalog
   const option = catalog.options.find((candidate) => candidate.id === optionId)
@@ -1148,12 +1177,12 @@ async function selectCommandOption(api, typertGateway, command, sessionId, optio
 
   if (command === 'permission') {
     try {
-      const execution = await typertGateway.invoke({
-        namespace: 'commands',
-        method: 'execute',
-        args: { agentId: sessionId, line: '/permission ' + optionId, images: [] },
-        signal: new AbortController().signal,
-      })
+      const execution = await host.commands.execute(
+        sessionId,
+        '/permission ' + optionId,
+        [],
+        new AbortController().signal,
+      )
       if (!execution || !execution.result) throw new Error('permission command returned an invalid result')
       if (execution.result.kind === 'error') {
         return { kind: 'error', code: 'command-error', message: execution.result.text, requestType: 'command-select', sessionId }
@@ -1198,7 +1227,7 @@ async function selectCommandOption(api, typertGateway, command, sessionId, optio
 }
 
 // Dispatch one mobile query frame; returns the wire frame to send back.
-async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
+async function handleQuery(api, host, agentDefaultModel, msg) {
   if (msg.type === 'workspaces') {
     return proxyQuery(api, 'workspaces', api.workspace.list.bind(api.workspace), {})
   }
@@ -1328,7 +1357,7 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     return proxyQuery(api, 'providers', api.llm.providers.bind(api.llm), {})
   }
   if (msg.type === 'command-execute') {
-    return admitCommand(typertGateway, msg)
+    return admitCommand(host, msg)
   }
   if (msg.type === 'commands') {
     const sessionId = requireSessionId(msg)
@@ -1340,7 +1369,7 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
       // the mobile wire. The Web UI also contributes /model client-side; expose
       // the equivalent action here so mobile clients can render the same menu.
       const [listed, skillFrame] = await Promise.all([
-        listHostCommands(typertGateway, sessionId.value),
+        listHostCommands(host, sessionId.value),
         api.skills && typeof api.skills.list === 'function'
           ? proxyQuery(api, 'skills', api.skills.list.bind(api.skills), { sessionId: sessionId.value })
           : Promise.resolve({ kind: 'error', code: 'unsupported', message: 'skill catalog is unavailable', requestType: 'skills' }),
@@ -1418,7 +1447,7 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     const command = typeof msg.command === 'string' && msg.command.trim() !== '' ? msg.command.trim() : null
     const optionId = typeof msg.optionId === 'string' && msg.optionId !== '' ? msg.optionId : null
     if (!command || !optionId) return { kind: 'error', code: 'bad-request', message: 'command-select requires command and optionId', requestType: 'command-select', sessionId: sessionId.value }
-    return selectCommandOption(api, typertGateway, command, sessionId.value, optionId)
+    return selectCommandOption(api, host, command, sessionId.value, optionId)
   }
   if (msg.type === 'select-model') {
     const sessionId = requireSessionId(msg)
@@ -1460,14 +1489,14 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     // command registry handler WITHOUT sending anything to the model, and the
     // api-remotes agent lookup resumes cold sessions just like prompt does.
     try {
-      const execution = await typertGateway.invoke({
-        namespace: 'commands',
-        method: 'execute',
-        // commands/execute 的当前 Typert descriptor 要求 images 字段始终存在；
-        // 权限斜杠命令没有附件，因此显式传空数组。
-        args: { agentId: sessionId.value, line: '/permission ' + name, images: [] },
-        signal: new AbortController().signal,
-      })
+      // commands/execute 的当前 Typert descriptor 要求 images 字段始终存在；
+      // 权限斜杠命令没有附件，因此显式传空数组。
+      const execution = await host.commands.execute(
+        sessionId.value,
+        '/permission ' + name,
+        [],
+        new AbortController().signal,
+      )
       if (execution === undefined || execution === null) {
         return { kind: 'error', code: 'unknown-command', message: 'command not found: /permission', requestType: 'permission', sessionId: sessionId.value }
       }
@@ -1515,6 +1544,39 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
       contextPressure: values.contextPressure || null,
     }
   }
+  if (msg.type === 'tasks') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    return readSessionProjection(api, 'tasks', sessionId.value, 'todos')
+  }
+  if (msg.type === 'goal') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    return readSessionProjection(api, 'goal', sessionId.value, 'goal')
+  }
+  if (msg.type === 'goal-edit') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const ref = requireGoalRef(msg, sessionId.value)
+    if (ref.error) return ref.error
+    const payload = { sessionId: sessionId.value, ref: ref.value }
+    if (typeof msg.objective === 'string' && msg.objective.trim() !== '') payload.objective = msg.objective.trim()
+    if (typeof msg.maxGoalRounds === 'number' && Number.isSafeInteger(msg.maxGoalRounds) && msg.maxGoalRounds > 0) {
+      payload.maxGoalRounds = msg.maxGoalRounds
+    }
+    if (payload.objective === undefined && payload.maxGoalRounds === undefined) {
+      return { kind: 'error', code: 'bad-request', message: 'goal-edit requires a non-empty objective or a positive maxGoalRounds', requestType: 'goal-edit', sessionId: sessionId.value }
+    }
+    return mutateGoal(api, 'goal-edit', 'edit', payload)
+  }
+  if (msg.type === 'goal-pause' || msg.type === 'goal-resume' || msg.type === 'goal-clear') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const ref = requireGoalRef(msg, sessionId.value)
+    if (ref.error) return ref.error
+    const method = msg.type === 'goal-pause' ? 'pause' : msg.type === 'goal-resume' ? 'resume' : 'clear'
+    return mutateGoal(api, msg.type, method, { sessionId: sessionId.value, ref: ref.value })
+  }
   if (msg.type === 'agent-presets') {
     return proxyQuery(api, 'agent-presets', api.agentPresets.list.bind(api.agentPresets), {})
   }
@@ -1772,16 +1834,16 @@ const plugin = {
   name: 'mobile-gateway',
   Config,
   // Hard dependencies: the gateway registers on the host web server and
-  // admits mobile messages through the host API gateway. Cordis must not
+  // admits mobile messages through the Host Remote Gateway. Cordis must not
   // activate this row before either service exists.
-  inject: ['webServer', 'apiProxy', 'typertGateway', 'agentDefaultModel'],
+  inject: ['webServer', 'typertGateway', 'agentDefaultModel'],
   // exported for local tests; Cordis ignores unknown plugin fields
   admitMessage,
   handleQuery,
   apply(ctx, config) {
     const webServer = ctx.webServer
-    const api = ctx.apiProxy
-    const typertGateway = ctx.typertGateway
+    const api = createDshHostAdapter(ctx.typertGateway)
+    const host = api
     const agentDefaultModel = ctx.agentDefaultModel
     const options = {
       path: DEFAULT_WS_PATH,
@@ -1838,7 +1900,7 @@ const plugin = {
         log(`file download expiry failed: ${error && error.message ? error.message : String(error)}`)
       })
     }, Math.min(options.fileDownloadIdleMs, 30_000))
-    const interactionMuxAbort = new AbortController()
+    const controlStreamAbort = new AbortController()
     let counter = 0
     let gatewayEnabled = options.gatewayEnabled === true
     let waitExpiresAt = null
@@ -1944,6 +2006,96 @@ const plugin = {
       return { questionCount, approvalCount }
     }
 
+    const hasInteractionClient = (sessionId) => [...clients].some((client) => (
+      client.readyState === 1
+      && (!client.filterSessionId || client.filterSessionId === sessionId)
+    ))
+
+    const completeQuestion = (pending, action, answer, cancellationCode = 'ASK_CANCELLED') => {
+      if (pendingQuestions.get(pending.rpcId) !== pending) return false
+      pendingQuestions.delete(pending.rpcId)
+      pending.cleanup()
+      if (action === 'answer') pending.resolve(answer)
+      else {
+        const error = new Error('question cancelled by mobile user')
+        error.name = 'UserQuestionError'
+        error.code = cancellationCode
+        pending.reject(error)
+      }
+      broadcastInteractionFrame({
+        kind: 'question-resolved',
+        rpcId: pending.rpcId,
+        sessionId: pending.sessionId,
+        outcome: action === 'answer' ? 'answered' : 'cancelled',
+      })
+      return true
+    }
+
+    const normalizeQuestionAnswers = (pending, answers) => {
+      if (answers.length !== pending.questions.length) return { error: 'answers must cover every question exactly once' }
+      const normalized = []
+      for (let index = 0; index < pending.questions.length; index += 1) {
+        const question = pending.questions[index]
+        const answer = answers[index]
+        if (!answer || typeof answer !== 'object' || answer.id !== question.id || !Array.isArray(answer.selected)) {
+          return { error: 'answers must preserve question order, ids, and selected arrays' }
+        }
+        if (answer.selected.some((label) => typeof label !== 'string')) return { error: 'selected values must be strings' }
+        if (new Set(answer.selected).size !== answer.selected.length) return { error: 'selected values must not repeat' }
+        const offered = new Set((question.options || []).map((option) => option.label))
+        if (answer.selected.some((label) => !offered.has(label))) return { error: 'selected values must match offered option labels' }
+        if (question.multiSelect !== true && answer.selected.length > 1) return { error: 'single-select questions accept at most one selection' }
+        let custom
+        if (answer.custom !== undefined) {
+          if (typeof answer.custom !== 'string' || !answer.custom.trim()) return { error: 'custom answers must be non-empty strings' }
+          custom = answer.custom.trim()
+        }
+        if (question.multiSelect !== true && custom !== undefined && answer.selected.length > 0) {
+          return { error: 'single-select custom answers cannot accompany a selection' }
+        }
+        normalized.push({ id: answer.id, selected: [...answer.selected], ...(custom === undefined ? {} : { custom }) })
+      }
+      return { value: { answers: normalized } }
+    }
+
+    const completeApproval = (pending, outcome) => {
+      if (pendingApprovals.get(pending.rpcId) !== pending) return false
+      pendingApprovals.delete(pending.rpcId)
+      pending.cleanup()
+      pending.resolve(outcome)
+      broadcastInteractionFrame({
+        kind: 'approval-resolved',
+        rpcId: pending.rpcId,
+        sessionId: pending.sessionId,
+        approvalId: pending.approvalId,
+        outcome,
+      })
+      return true
+    }
+
+    const fallbackQuestion = (pending) => {
+      if (pendingQuestions.get(pending.rpcId) !== pending) return
+      pendingQuestions.delete(pending.rpcId)
+      pending.cleanup()
+      Promise.resolve().then(pending.next).then(pending.resolve, pending.reject)
+    }
+
+    const fallbackApproval = (pending) => {
+      if (pendingApprovals.get(pending.rpcId) !== pending) return
+      pendingApprovals.delete(pending.rpcId)
+      pending.cleanup()
+      Promise.resolve().then(pending.next).then(pending.resolve, pending.reject)
+    }
+
+    const releaseUnclaimedInteractions = () => {
+      for (const pending of [...pendingQuestions.values()]) {
+        if (!hasInteractionClient(pending.sessionId)) fallbackQuestion(pending)
+      }
+      for (const pending of [...pendingApprovals.values()]) {
+        if (!hasInteractionClient(pending.sessionId)) fallbackApproval(pending)
+      }
+    }
+
     const respondToQuestion = async (msg, cancel = false) => {
       const rpcId = typeof msg.rpcId === 'string' && msg.rpcId.trim() ? msg.rpcId.trim() : null
       const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() ? msg.sessionId.trim() : null
@@ -1951,46 +2103,30 @@ const plugin = {
         return { kind: 'error', code: 'bad-request', message: `${msg.type} requires rpcId and sessionId`, requestType: msg.type }
       }
 
-      if (cancel) {
-        const pending = pendingQuestions.get(rpcId)
-        if (pending && pending.sessionId !== sessionId) {
-          return { kind: 'error', code: 'bad-request', message: 'sessionId does not match the pending question', requestType: msg.type, sessionId }
-        }
-      } else if (!Array.isArray(msg.answers)) {
+      const pending = pendingQuestions.get(rpcId)
+      if (!pending) {
+        return { kind: 'question-response', rpcId, sessionId, action: cancel ? 'cancel' : 'answer', accepted: false, reason: 'not-pending' }
+      }
+      if (pending.sessionId !== sessionId) {
+        return { kind: 'error', code: 'bad-request', message: 'sessionId does not match the pending question', requestType: msg.type, sessionId }
+      }
+      if (!cancel && !Array.isArray(msg.answers)) {
         return { kind: 'error', code: 'bad-request', message: 'question-answer requires an answers array', requestType: msg.type, sessionId }
       }
-
-      const result = cancel
-        ? { ok: false, error: { code: 'cancelled', message: 'question cancelled by mobile user', details: {} } }
-        : {
-            ok: true,
-            value: {
-              sessionId,
-              answer: {
-                answers: msg.answers.map((answer) => ({
-                  id: answer && answer.id,
-                  selected: answer && answer.selected,
-                  ...(answer && answer.custom !== undefined ? { custom: answer.custom } : {}),
-                })),
-              },
-            },
-          }
-
-      try {
-        const receipt = await api.respond({ type: 'client-response', rpcId, result })
-        log(`question response: rpcId=${rpcId} session=${sessionId} action=${cancel ? 'cancel' : 'answer'} accepted=${receipt.accepted}${receipt.accepted ? '' : ` reason=${receipt.reason}`}`)
-        return {
-          kind: 'question-response',
-          rpcId,
-          sessionId,
-          action: cancel ? 'cancel' : 'answer',
-          accepted: receipt.accepted,
-          ...(!receipt.accepted ? { reason: receipt.reason } : {}),
-        }
-      } catch (error) {
-        const message = error && error.message ? error.message : String(error)
-        log(`question response failed: rpcId=${rpcId} ${message}`)
-        return { kind: 'error', code: 'internal', message, requestType: msg.type, sessionId }
+      const normalized = cancel ? null : normalizeQuestionAnswers(pending, msg.answers)
+      if (normalized?.error) {
+        return { kind: 'error', code: 'bad-response', message: normalized.error, requestType: msg.type, sessionId }
+      }
+      const answer = normalized?.value
+      const accepted = completeQuestion(pending, cancel ? 'cancel' : 'answer', answer)
+      log(`question response: rpcId=${rpcId} session=${sessionId} action=${cancel ? 'cancel' : 'answer'} accepted=${accepted}`)
+      return {
+        kind: 'question-response',
+        rpcId,
+        sessionId,
+        action: cancel ? 'cancel' : 'answer',
+        accepted,
+        ...(!accepted ? { reason: 'not-pending' } : {}),
       }
     }
 
@@ -2007,30 +2143,22 @@ const plugin = {
       }
 
       const pending = pendingApprovals.get(rpcId)
-      if (pending && (pending.sessionId !== sessionId || pending.approvalId !== approvalId)) {
+      if (!pending) {
+        return { kind: 'approval-response', rpcId, sessionId, approvalId, outcome, accepted: false, reason: 'not-pending' }
+      }
+      if (pending.sessionId !== sessionId || pending.approvalId !== approvalId) {
         return { kind: 'error', code: 'bad-request', message: 'approval-response does not match the pending approval', requestType: msg.type, sessionId }
       }
-
-      try {
-        const receipt = await api.respond({
-          type: 'client-response',
-          rpcId,
-          result: { ok: true, value: { sessionId, approvalId, outcome } },
-        })
-        log(`approval response: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} outcome=${outcome} accepted=${receipt.accepted}${receipt.accepted ? '' : ` reason=${receipt.reason}`}`)
-        return {
-          kind: 'approval-response',
-          rpcId,
-          sessionId,
-          approvalId,
-          outcome,
-          accepted: receipt.accepted,
-          ...(!receipt.accepted ? { reason: receipt.reason } : {}),
-        }
-      } catch (error) {
-        const message = error && error.message ? error.message : String(error)
-        log(`approval response failed: rpcId=${rpcId} ${message}`)
-        return { kind: 'error', code: 'internal', message, requestType: msg.type, sessionId }
+      const accepted = completeApproval(pending, outcome)
+      log(`approval response: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} outcome=${outcome} accepted=${accepted}`)
+      return {
+        kind: 'approval-response',
+        rpcId,
+        sessionId,
+        approvalId,
+        outcome,
+        accepted,
+        ...(!accepted ? { reason: 'not-pending' } : {}),
       }
     }
 
@@ -2263,8 +2391,10 @@ const plugin = {
                        msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
                        msg.type === 'agent-presets' || msg.type === 'defaults' || msg.type === 'set-default' ||
                        msg.type === 'session-stats' || msg.type === 'default-model' ||
-                       msg.type === 'save-default-model' || msg.type === 'fork' || msg.type === 'providers') {
-              handleQuery(api, typertGateway, agentDefaultModel, msg).then((frame) => {
+                       msg.type === 'save-default-model' || msg.type === 'fork' || msg.type === 'providers' ||
+                       msg.type === 'tasks' || msg.type === 'goal' || msg.type === 'goal-edit' ||
+                       msg.type === 'goal-pause' || msg.type === 'goal-resume' || msg.type === 'goal-clear') {
+              handleQuery(api, host, agentDefaultModel, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
               })
             } else {
@@ -2275,6 +2405,7 @@ const plugin = {
           ws.on('close', () => {
             clients.delete(ws)
             if (ws.deviceId) registry.disconnected(ws.deviceId)
+            releaseUnclaimedInteractions()
             fileTransfers.closeClient(ws).catch((error) => {
               log(`file download cleanup failed: ${error && error.message ? error.message : String(error)}`)
             })
@@ -2292,7 +2423,7 @@ const plugin = {
           ws.send(JSON.stringify({
             kind: 'hello',
             protocol: 3,
-            capabilities: ['images', 'commands', ...(options.fileDownloadsEnabled ? ['file-downloads'] : [])],
+            capabilities: ['images', 'commands', 'tasks', 'goals', ...(options.fileDownloadsEnabled ? ['file-downloads'] : [])],
             port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,
@@ -2363,93 +2494,114 @@ const plugin = {
     })
     log('session/event listener attached')
 
-    const interactionMuxTask = api.events && typeof api.events.mux === 'function' && typeof api.respond === 'function'
-      ? (async () => {
-          try {
-            for await (const envelope of api.events.mux(
-              { rpcId: crypto.randomUUID(), payload: {} },
-              interactionMuxAbort.signal,
-            )) {
-              const payload = envelope && envelope.payload
-              if (!payload || typeof payload.type !== 'string') continue
-              log(`interaction observed: type=${payload.type} hasRpc=${envelope.rpcId !== undefined} hasSession=${payload.sessionId !== undefined} hasApprovalId=${payload.approvalId !== undefined} hasToolName=${payload.toolName !== undefined}`)
-              if (payload.type === 'question/requested') {
-                const rpcId = String(envelope.rpcId)
-                const pending = {
-                  rpcId,
-                  sessionId: String(payload.sessionId),
-                  questions: payload.questions,
-                }
-                pendingQuestions.set(rpcId, pending)
-                broadcastInteractionFrame(questionFrameFor(rpcId, pending))
-                log(`question requested: rpcId=${rpcId} session=${pending.sessionId} questions=${Array.isArray(pending.questions) ? pending.questions.length : 0}`)
-              } else if (payload.type === 'approval/requested') {
-                const rpcId = String(envelope.rpcId)
-                const pending = {
-                  rpcId,
-                  sessionId: String(payload.sessionId),
-                  approvalId: String(payload.approvalId),
-                  toolName: payload.toolName,
-                  ...(payload.callId !== undefined ? { callId: payload.callId } : {}),
-                  ...(payload.reason !== undefined ? { reason: payload.reason } : {}),
-                }
-                pendingApprovals.set(rpcId, pending)
-                broadcastInteractionFrame(approvalFrameFor(rpcId, pending))
-                log(`approval requested: rpcId=${rpcId} approvalId=${pending.approvalId} session=${pending.sessionId} tool=${pending.toolName}`)
-              } else if (payload.type === 'question/resolved') {
-                const questionRpcId = String(payload.questionRpcId)
-                pendingQuestions.delete(questionRpcId)
-                broadcastInteractionFrame({
-                  kind: 'question-resolved',
-                  rpcId: questionRpcId,
-                  sessionId: String(payload.sessionId),
-                  outcome: payload.outcome,
-                })
-                log(`question resolved: rpcId=${questionRpcId} session=${payload.sessionId} outcome=${payload.outcome}`)
-              } else if (payload.type === 'approval/resolved') {
-                const approvalId = String(payload.approvalId)
-                const sessionId = String(payload.sessionId)
-                const entry = [...pendingApprovals.entries()].find(([, pending]) => pending.approvalId === approvalId && pending.sessionId === sessionId)
-                if (!entry) {
-                  log(`approval resolved without pending request: approvalId=${approvalId} session=${sessionId} outcome=${payload.outcome}`)
-                  continue
-                }
-                const [rpcId, pending] = entry
-                pendingApprovals.delete(rpcId)
-                broadcastInteractionFrame({
-                  kind: 'approval-resolved',
-                  rpcId,
-                  sessionId,
-                  approvalId,
-                  outcome: payload.outcome,
-                })
-                log(`approval resolved: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} outcome=${payload.outcome}`)
-              } else {
-                log(`interaction ignored: type=${payload.type}`)
-              }
-            }
-          } catch (error) {
-            if (!interactionMuxAbort.signal.aborted) {
-              log(`interaction mux failed: ${error && error.message ? error.message : String(error)}`)
-            }
+    const disposeQuestions = ctx.on('user-questions/request', (request, next) => {
+      const sessionId = request?.agent?.id === undefined ? null : String(request.agent.id)
+      if (!sessionId || !Array.isArray(request.questions) || !hasInteractionClient(sessionId)) return next()
+      const rpcId = crypto.randomUUID()
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          const pending = pendingQuestions.get(rpcId)
+          if (pending) completeQuestion(pending, 'cancel', undefined, 'ASK_ABORTED')
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const pending = {
+          rpcId,
+          sessionId,
+          questions: request.questions,
+          next,
+          resolve,
+          reject,
+          cleanup: () => request.signal?.removeEventListener('abort', onAbort),
+        }
+        pendingQuestions.set(rpcId, pending)
+        broadcastInteractionFrame(questionFrameFor(rpcId, pending))
+        log(`question requested: rpcId=${rpcId} session=${sessionId} questions=${request.questions.length}`)
+      })
+    }, { prepend: true })
+
+    const disposeApprovals = ctx.on('approval/request', (request, next) => {
+      const sessionId = request?.agent?.id === undefined ? null : String(request.agent.id)
+      if (!sessionId || typeof request.toolName !== 'string' || !hasInteractionClient(sessionId)) return next()
+      const rpcId = crypto.randomUUID()
+      const approvalId = crypto.randomUUID()
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          const pending = pendingApprovals.get(rpcId)
+          if (pending) completeApproval(pending, 'cancelled')
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const pending = {
+          rpcId,
+          sessionId,
+          approvalId,
+          toolName: request.toolName,
+          ...(request.callId !== undefined ? { callId: request.callId } : {}),
+          ...(request.reason !== undefined ? { reason: request.reason } : {}),
+          next,
+          resolve,
+          reject,
+          cleanup: () => request.signal?.removeEventListener('abort', onAbort),
+        }
+        pendingApprovals.set(rpcId, pending)
+        broadcastInteractionFrame(approvalFrameFor(rpcId, pending))
+        log(`approval requested: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} tool=${request.toolName}`)
+      })
+    }, { prepend: true })
+
+    const projectionTask = (async () => {
+      while (!controlStreamAbort.signal.aborted) {
+        try {
+          const stream = await api.openControlStream(controlStreamAbort.signal)
+          for await (const frame of stream) {
+            if (frame?.type !== 'projection' || (frame.key !== 'todos' && frame.key !== 'goal')) continue
+            const sessionId = String(frame.sessionId)
+            const kind = frame.key === 'todos' ? 'tasks-updated' : 'goal-updated'
+            const valueKey = frame.key === 'todos' ? 'todos' : 'goal'
+            broadcastInteractionFrame({
+              kind,
+              sessionId,
+              asOfSeq: frame.seq,
+              [valueKey]: frame.value,
+            })
+            log(`projection forwarded: key=${frame.key} session=${sessionId} seq=${frame.seq}`)
           }
-        })()
-      : null
-    if (interactionMuxTask) log('api gateway interaction mux attached')
-    else log('api gateway interaction mux unavailable; human-in-the-loop disabled')
+          if (!controlStreamAbort.signal.aborted) log('session control stream ended; retrying')
+        } catch (error) {
+          if (!controlStreamAbort.signal.aborted) {
+            log(`session control stream failed; retrying: ${error && error.message ? error.message : String(error)}`)
+          }
+        }
+        if (controlStreamAbort.signal.aborted) break
+        await new Promise((resolve) => {
+          const onAbort = () => {
+            clearTimeout(timer)
+            resolve()
+          }
+          const timer = setTimeout(() => {
+            controlStreamAbort.signal.removeEventListener('abort', onAbort)
+            resolve()
+          }, 1_000)
+          controlStreamAbort.signal.addEventListener('abort', onAbort, { once: true })
+        })
+      }
+    })()
+    void projectionTask
+    log('Host waterfall interaction listeners and session control stream attached')
 
     ctx.effect(() => () => {
       if (waitTimer) clearTimeout(waitTimer)
       clearInterval(fileTransferExpiryTimer)
-      interactionMuxAbort.abort()
-      pendingQuestions.clear()
-      pendingApprovals.clear()
+      controlStreamAbort.abort()
+      for (const pending of [...pendingQuestions.values()]) fallbackQuestion(pending)
+      for (const pending of [...pendingApprovals.values()]) fallbackApproval(pending)
       fileTransfers.dispose().catch((error) => {
         log(`file download disposal failed: ${error && error.message ? error.message : String(error)}`)
       })
       disposeUpgrade()
       disposeMgmt()
       disposeEvents()
+      disposeQuestions()
+      disposeApprovals()
       if (lanServer) lanServer.close()
       for (const client of clients) client.terminate()
       clients.clear()