@ljwei-stak/dsh-model-route-bot 0.66.3 → 0.67.0

package/packages/bot-engines/src/claude-protocol.mjs

@@ -0,0 +1,177 @@
+// Pure Claude Code stream-json protocol helpers for the conversation-session adapter.
+//
+// Adapted from OpenMausBot server/drivers/claude.ts at pin
+// 1bc4749aa8307d7d6998bf86de4ef6478460dd93 (Apache-2.0); see licenses/NOTICE.md.
+// These functions are side-effect free so they can be tested without any child process.
+
+/** Turn text bounds mirror the target's CLI turn validation. */
+export function validTurnText(text) {
+  return typeof text === 'string' && text.trim() !== '' && !text.includes('\0') && Buffer.byteLength(text) <= 64_000
+}
+
+/** A stdin user message. The prompt rides stdin, never argv. */
+export function claudeUserMessage(text) {
+  return { type: 'user', message: { role: 'user', content: text } }
+}
+
+const firstText = content => {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content.filter(block => block?.type === 'text' && typeof block.text === 'string').map(block => block.text).join('')
+}
+
+/** What an error `result` says failed: its errors list, else its result text, else its kind. */
+export function claudeResultError(frame) {
+  const errors = Array.isArray(frame.errors) ? frame.errors.filter(value => typeof value === 'string' && value.trim() !== '') : []
+  if (errors.length) return errors.join('; ')
+  if (typeof frame.result === 'string' && frame.result.trim()) return frame.result
+  return `Claude ended the turn with an error (${String((frame.subtype !== 'success' && frame.subtype) || frame.terminal_reason || 'unknown')}).`
+}
+
+/** A turn's cost from total_cost_usd, which is the process's running total: the growth
+ * since `previous`, or the whole figure when the start is unknown or the total went down.
+ * Anything the CLI did not report as a finite number is not a cost: it stays null. */
+export function turnCostFromRunningTotal(total, previous) {
+  if (typeof total !== 'number' || !Number.isFinite(total)) return null
+  if (previous === null || total < previous) return total
+  return Number((total - previous).toFixed(10))
+}
+
+/** total_cost_usd and per-model modelUsage [input, cache read, cache write, output] from a
+ * `result`; both cover the whole session, including what --resume restored. */
+export function claudeCostSnapshot(total, modelUsage) {
+  if (typeof total !== 'number' || !Number.isFinite(total)) return null
+  const count = value => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
+  const models = {}
+  if (modelUsage && typeof modelUsage === 'object' && !Array.isArray(modelUsage)) {
+    for (const [model, raw] of Object.entries(modelUsage)) {
+      if (!raw || typeof raw !== 'object') continue
+      models[model] = [count(raw.inputTokens), count(raw.cacheReadInputTokens), count(raw.cacheCreationInputTokens), count(raw.outputTokens)]
+    }
+  }
+  return { total, models }
+}
+
+/** One native `result` frame. */
+export function nativeTurnResult(frame) {
+  const usage = frame.usage && typeof frame.usage === 'object' ? frame.usage : null
+  return {
+    ok: frame.is_error !== true,
+    stopReason: frame.is_error === true
+      ? frame.terminal_reason ?? (typeof frame.subtype === 'string' && frame.subtype !== 'success' ? frame.subtype : null) ?? frame.stop_reason ?? null
+      : frame.stop_reason ?? frame.terminal_reason ?? null,
+    cost: typeof frame.total_cost_usd === 'number' && Number.isFinite(frame.total_cost_usd) ? frame.total_cost_usd : null,
+    ...(usage ? { usage: resultUsage(usage) } : {}),
+  }
+}
+
+/** result.usage is per turn "in streaming-input sessions" even on a retained process;
+ * input components (fresh + cache read + cache write) are summed, cachedInput reported
+ * separately, and anything missing stays null instead of being invented. */
+export function resultUsage(usage) {
+  const nonNegative = value => (typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null)
+  const input = nonNegative(usage.input_tokens)
+  const cacheRead = nonNegative(usage.cache_read_input_tokens)
+  const cacheWrite = nonNegative(usage.cache_creation_input_tokens)
+  const output = nonNegative(usage.output_tokens)
+  if (input === null && cacheRead === null && cacheWrite === null && output === null) return null
+  const parts = [input, cacheRead, cacheWrite].filter(value => value !== null)
+  return {
+    input: parts.length ? parts.reduce((sum, value) => sum + value, 0) : null,
+    output,
+    ...(cacheRead !== null ? { cachedInput: cacheRead } : {}),
+  }
+}
+
+/** Merges native turns into one logical turn. Cost takes the latest figure: total_cost_usd
+ * is cumulative and the latest result is read rather than summed. */
+export function sumNativeTurnResults(earlier, latest) {
+  if (!earlier) return latest
+  const usage = earlier.usage && latest.usage
+    ? {
+        input: (earlier.usage.input ?? 0) + (latest.usage.input ?? 0),
+        output: (earlier.usage.output ?? 0) + (latest.usage.output ?? 0),
+        ...((earlier.usage.cachedInput !== undefined || latest.usage.cachedInput !== undefined)
+          ? { cachedInput: (earlier.usage.cachedInput ?? 0) + (latest.usage.cachedInput ?? 0) } : {}),
+      }
+    : latest.usage ?? earlier.usage
+  return {
+    ok: earlier.ok && latest.ok,
+    stopReason: latest.stopReason ?? earlier.stopReason,
+    cost: latest.cost ?? earlier.cost,
+    ...(usage ? { usage } : {}),
+  }
+}
+
+/**
+ * Classify one parsed stdout JSON line into a typed protocol event. Anything the engine
+ * does not act on is returned as { type: 'ignored', raw } rather than dropped silently.
+ */
+export function classifyClaudeFrame(frame) {
+  if (!frame || typeof frame !== 'object') return { type: 'ignored', reason: 'not-an-object' }
+  switch (frame.type) {
+    case 'system':
+      if (frame.subtype === 'init') {
+        return {
+          type: 'init',
+          sessionId: typeof frame.session_id === 'string' && frame.session_id ? frame.session_id : null,
+          model: typeof frame.model === 'string' && frame.model ? frame.model : null,
+          permissionMode: typeof frame.permissionMode === 'string' && frame.permissionMode ? frame.permissionMode : null,
+          tools: Array.isArray(frame.tools) ? frame.tools.filter(value => typeof value === 'string') : [],
+        }
+      }
+      if (frame.subtype === 'compact_boundary') return { type: 'compacted' }
+      return { type: 'ignored', reason: `system/${frame.subtype}` }
+    case 'stream_event': {
+      const event = frame.event ?? {}
+      const delta = event.delta ?? {}
+      if (frame.parent_tool_use_id) return { type: 'ignored', reason: 'subagent-narration' }
+      if (event.type === 'content_block_delta') {
+        if (delta.type === 'text_delta' && typeof delta.text === 'string' && delta.text) return { type: 'assistant-delta', delta: delta.text }
+        if (delta.type === 'thinking_delta' && typeof delta.thinking === 'string' && delta.thinking) return { type: 'reasoning-delta', delta: delta.thinking }
+      }
+      return { type: 'ignored', reason: `stream_event/${event.type ?? 'unknown'}` }
+    }
+    case 'assistant': {
+      const message = frame.message ?? {}
+      const text = firstText(message.content)
+      const out = { type: 'assistant', text }
+      if (Array.isArray(message.content)) {
+        const toolUses = message.content.filter(block => block?.type === 'tool_use')
+        if (toolUses.length) out.toolUses = toolUses.map(block => ({ id: typeof block.id === 'string' ? block.id : null, name: typeof block.name === 'string' ? block.name : null, input: block.input ?? null }))
+      }
+      if (message.usage && typeof message.usage === 'object') out.usage = message.usage
+      return out
+    }
+    case 'user': {
+      if (frame.isReplay === true) return { type: 'replay' }
+      const content = frame.message?.content
+      if (!Array.isArray(content)) return { type: 'ignored', reason: 'user/non-tool-result' }
+      const results = content.filter(block => block?.type === 'tool_result')
+      if (!results.length) return { type: 'ignored', reason: 'user/non-tool-result' }
+      return {
+        type: 'tool-result',
+        results: results.map(block => ({ toolUseId: typeof block.tool_use_id === 'string' ? block.tool_use_id : null, ok: block.is_error !== true })),
+      }
+    }
+    case 'result':
+      if (frame.origin?.kind === 'task-notification') return { type: 'ignored', reason: 'task-notification' }
+      return { type: 'result', isError: frame.is_error === true, native: nativeTurnResult(frame), errors: Array.isArray(frame.errors) ? frame.errors.filter(value => typeof value === 'string') : [] }
+    default:
+      return { type: 'ignored', reason: `type/${String(frame.type)}` }
+  }
+}
+
+/** Permission broker wire parsing (host side). A line must be {t:'ask', id, kind, tool, input}. */
+export function parseBrokerAsk(message) {
+  if (!message || typeof message !== 'object' || message.t !== 'ask') return null
+  const id = typeof message.id === 'string' && message.id ? message.id : null
+  if (!id) return null
+  const kind = message.kind === 'question' ? 'question' : 'permission'
+  return { id, kind, tool: typeof message.tool === 'string' && message.tool ? message.tool : 'tool', input: message.input && typeof message.input === 'object' && !Array.isArray(message.input) ? message.input : {} }
+}
+
+/** Serialize a broker answer line. */
+export function brokerAnswer(id, behavior, message, source, always = false) {
+  return { t: 'answer', id, behavior, message, source, ...(always ? { always: true } : {}) }
+}

package/packages/bot-engines/src/driver-catalog.mjs

@@ -0,0 +1,334 @@
+// Closed catalog of the 26 upstream OpenMausBot built-in Bot engine drivers.
+//
+// Upstream source: OpenMausBot at pin 1bc4749aa8307d7d6998bf86de4ef6478460dd93
+// (Apache-2.0), server/drivers/builtIn.ts BUILT_IN_DRIVERS. Every entry records the
+// upstream file it was verified against. This catalog is closed: exactly these 26 ids
+// exist, no unknown id resolves, and no arbitrary executable/endpoint/command can be
+// registered as a driver. The 13 CLIs in .dsh-plugin/shared/official-tool-registry.mjs
+// are one-shot official tools, a different and smaller set; they are NOT drivers and are
+// deliberately not conflated with this list.
+
+export const UPSTREAM_SOURCE = Object.freeze({
+  project: 'OpenMausBot',
+  pin: '1bc4749aa8307d7d6998bf86de4ef6478460dd93',
+  license: 'Apache-2.0',
+  driversRoot: 'server/drivers',
+  builtInList: 'server/drivers/builtIn.ts (BUILT_IN_DRIVERS)',
+})
+
+const unavailable = (reason, target) => ({ availability: 'unavailable', availabilityReason: reason, targetCapability: target })
+
+const api = (id, name, evidence, extra = {}) => ({
+  id, name, kind: 'api-provider', transport: 'https-openai-chat-completions',
+  multipleInstances: true,
+  evidence,
+  ...unavailable(
+    'API provider channel, not a conversation engine: stateless OpenAI chat-completions HTTP calls with no retained session process, no native tools and no permission broker. It belongs to the Host model-routing channel, not to packages/bot-engines.',
+    'api-provider-channel'),
+  ...extra,
+})
+
+const acpPending = (id, name, evidence, extra = {}) => ({
+  id, name, kind: 'conversation-engine',
+  evidence,
+  ...unavailable(
+    'CLI conversation engine whose upstream adapter runs it over ACP (Agent Client Protocol) stdio. Porting it requires the upstream acp/core.ts session/state machine first; it is deliberately not faked by spawning the CLI ad hoc.',
+    'pending-acp-core'),
+  ...extra,
+})
+
+export const BOT_ENGINE_DRIVERS = Object.freeze([
+  // ---- API providers (8) — createOpenAIChatRuntime, one request per call, no session ----
+  Object.freeze(api('grok', 'Grok (API)', Object.freeze({
+    file: 'server/drivers/grok.ts', anchor: 'L33-45',
+    modelSelection: 'Static catalog, default grok-4.7 (grok-4.7/grok-4/grok-4-fast/grok-3-mini)',
+    credentials: 'Per-instance apiKeyEnv, default XAI_API_KEY; default URL https://api.x.ai/v1',
+    session: 'None: one chat-completions request per model call',
+    permissions: 'None: no local tools, no permission flow',
+    usage: 'Usage reported by the xAI chat-completions response',
+  }))),
+  Object.freeze(api('groq', 'Groq (API)', Object.freeze({
+    file: 'server/drivers/groq.ts', anchor: 'L41-95',
+    modelSelection: 'Static default catalog refreshed from GET /models with the API key (8s timeout)',
+    credentials: 'GROQ_API_KEY (instance env, or process env when URL is the default)',
+    session: 'None: stateless chat-completions calls',
+    permissions: 'None',
+    usage: 'Provider-reported usage; includeUsageInCompleted; billing metered',
+  }))),
+  Object.freeze(api('mistral', 'Mistral (API)', Object.freeze({
+    file: 'server/drivers/mistral.ts', anchor: 'L48-60',
+    modelSelection: 'Static catalog with configured-model override',
+    credentials: 'MISTRAL_API_KEY (instance env first, then process env)',
+    session: 'None',
+    permissions: 'None',
+    usage: 'Provider-reported usage',
+  }))),
+  Object.freeze(api('cerebras', 'Cerebras (API)', Object.freeze({
+    file: 'server/drivers/cerebras.ts', anchor: 'L39-51',
+    modelSelection: 'Static catalog with configured-model override',
+    credentials: 'CEREBRAS_API_KEY (instance env first, then process env)',
+    session: 'None',
+    permissions: 'None',
+    usage: 'Provider-reported usage',
+  }))),
+  Object.freeze(api('greenference', 'Greenference (API)', Object.freeze({
+    file: 'server/drivers/greenference.ts', anchor: 'L57-71',
+    modelSelection: 'Static catalog with configured-model override',
+    credentials: 'GREENFERENCE_API_KEY (instance env; process env only on the default URL)',
+    session: 'None',
+    permissions: 'None',
+    usage: 'Provider-reported usage',
+  }))),
+  Object.freeze(api('meta', 'Meta Muse (API)', Object.freeze({
+    file: 'server/drivers/meta.ts', anchor: 'L54-68',
+    modelSelection: 'Static catalog with configured-model override',
+    credentials: 'META_API_KEY (instance env; process env only on the default URL)',
+    session: 'None',
+    permissions: 'None',
+    usage: 'Provider-reported usage',
+  }))),
+  Object.freeze(api('minimax', 'MiniMax (API)', Object.freeze({
+    file: 'server/drivers/minimax.ts', anchor: 'L11,L71-86',
+    modelSelection: 'Static catalog; URL from config or MINIMAX_BASE_URL',
+    credentials: 'MINIMAX_API_KEY (API key env); local mmx-cli profile via "mmx auth login --api-key" also supported upstream',
+    session: 'None',
+    permissions: 'None',
+    usage: 'Provider-reported usage',
+  }), { access: 'custom' })),
+  Object.freeze(api('openai-compat', 'Other (OpenAI-compatible)', Object.freeze({
+    file: 'server/drivers/openai-compat.ts', anchor: 'L43-184',
+    modelSelection: 'Caller-configured model id on any OpenAI-compatible endpoint (default OpenRouter)',
+    credentials: 'Configurable apiKeyEnv (OMB_OPENAI_API_KEY / OMB_OPENROUTER_API_KEY are first-class), else the endpoint key is added to the instance config',
+    session: 'None',
+    permissions: 'None',
+    usage: 'Provider-reported usage',
+  }), { access: 'api' })),
+
+  // ---- Conversation engines (18) ----
+  Object.freeze({
+    id: 'claude', name: 'Claude', kind: 'conversation-engine',
+    transport: 'cli-stream-json-stdio (retained process; -p --output-format stream-json --input-format stream-json --verbose --include-partial-messages)',
+    multipleInstances: true,
+    evidence: Object.freeze({
+      file: 'server/drivers/claude.ts', anchor: 'L758-771,L1006-1013',
+      modelSelection: '--model <slug> on argv; static catalog plus endpoint/org extras upstream',
+      credentials: 'Subscription OAuth under an isolated CLAUDE_CONFIG_DIR, or ANTHROPIC_API_KEY for managed/endpoint accounts; parent account env keys are stripped',
+      session: 'One retained CLI process per thread; init frame confirms session_id; later turns are new stdin user messages; relaunch uses --resume <session_id>; a steered continuation can chain several native result frames into one logical turn',
+      permissions: '--permission-mode default|acceptEdits|auto|bypassPermissions; permission/question asks arrive through an MCP permission-prompt tool backed by a local ask/answer broker socket; duplicate ask ids and post-close asks fail closed',
+      usage: 'result.usage is per-turn in streaming-input sessions; total_cost_usd is the process running total, so a turn cost is the growth since the previous result; missing values stay unknown',
+    }),
+    availability: 'implemented',
+    availabilityReason: null,
+    targetCapability: 'claude-engine',
+    implementation: 'src/claude-engine.mjs',
+  }),
+  Object.freeze({
+    id: 'codex', name: 'Codex', kind: 'conversation-engine',
+    transport: 'cli-app-server-ndjson (codex app-server JSON-RPC over stdio)',
+    multipleInstances: true,
+    evidence: Object.freeze({
+      file: 'server/drivers/codex.ts', anchor: 'L8-9,L579',
+      modelSelection: 'Model selected on thread/start and switchable per turn upstream',
+      credentials: 'ChatGPT plan login or OpenAI API key per instance',
+      session: 'Threads resume by codex thread id (thread/resume); completion is turn/completed; approvals arrive as server-to-client requests',
+      permissions: 'Upstream maps approval modes onto codex approval policy per thread',
+      usage: 'Token usage is reported as a running total for the app-server process',
+    }),
+    ...unavailable('Not yet ported as a Bot conversation engine. The target already runs codex as one-shot task execution (packages/cli-runtime/src/codex-session-core.mjs); lifting it into a retained multi-turn Bot engine is a separate port with its own tests.', 'pending-engine-port'),
+  }),
+  Object.freeze({
+    id: 'museCode', name: 'Muse Code', kind: 'conversation-engine',
+    transport: 'msdp-stdio (Muse Session Protocol over "muse serve" stdio)',
+    multipleInstances: true, access: 'subscription',
+    evidence: Object.freeze({
+      file: 'server/drivers/muse-code.ts', anchor: 'L250-262,L444-462',
+      modelSelection: 'model/list from the signed-in account; static fallback (muse-wonder-1.0, muse-spark-1.3/1.2); session/set_model',
+      credentials: '"muse login" under the instance HOME, or META_API_KEY for that instance',
+      session: 'session/start confirms sessionId; session/resume (sessionNotFound falls back to a fresh session); hosts are keyed by cwd/approval/MCP posture',
+      permissions: 'approval/requested with availableChoices (approved once / approvedForSession / denied); full-auto maps to allowAll',
+      usage: 'session/tokenUsage and turn/completed usage (inputTokens/outputTokens/cachedTokens); no dollar figure',
+    }),
+    ...unavailable('Requires the Muse Session Protocol host port (upstream drives it through @muse-code/sdk Connection over a supervised stdio transport). Not faked.', 'pending-engine-port'),
+  }),
+  Object.freeze({
+    id: 'pi', name: 'pi', kind: 'conversation-engine',
+    transport: 'cli-jsonrpc-stdio (pi --mode rpc --no-session)',
+    multipleInstances: true, access: 'custom',
+    evidence: Object.freeze({
+      file: 'server/drivers/pi.ts', anchor: 'L4-5,L57,L363-364',
+      modelSelection: 'BYOK: pi reads ~/.pi/agent/auth.json itself; the driver holds no key',
+      credentials: 'None held by the host; pi manages its own auth',
+      session: 'resumeCursor is pi sessionFile (switch_session); --no-session accepts a prompt without a session',
+      permissions: 'pi asks through its own RPC requests',
+      usage: 'Reported by pi per turn',
+    }),
+    ...unavailable('Not yet ported: the upstream driver drives pi over "pi --mode rpc --no-session" JSON-RPC stdio (BYOK auth under ~/.pi), which needs its own RPC adapter, session-file cursors and request broker before it can be a Bot engine. Not faked.', 'pending-engine-port'),
+  }),
+  Object.freeze({
+    id: 'antigravityAgent', name: 'Google Gemini (Antigravity)', kind: 'conversation-engine',
+    transport: 'acp-stdio via managed runtime (resolveAntigravityRuntime executable, isolated Google profile)',
+    multipleInstances: true,
+    evidence: Object.freeze({
+      file: 'server/drivers/antigravity.ts', anchor: 'L31-88',
+      modelSelection: 'Static gemini-3.8-flash with low/medium/high variants; AGY_ACP_DEFAULT_MODEL seeds new sessions',
+      credentials: 'Google account OAuth into an isolated profile (prepareAntigravityProfile)',
+      session: 'ACP resume method "resume"; session-scoped approval',
+      permissions: 'yolo / auto_edit / default session modes',
+      usage: 'ACP session reports',
+    }),
+    ...unavailable('Requires the ACP core port plus the managed Antigravity runtime resolver.', 'pending-acp-core'),
+  }),
+  Object.freeze(acpPending('grokAgent', 'Grok', Object.freeze({
+    file: 'server/drivers/acp/grok.ts', anchor: 'L368-395',
+    modelSelection: 'Static grok-4.7/4.6/4.5 plus local slugs from ~/.grok/config.toml; session/set_model (never on narrowed tool scope)',
+    credentials: 'grok.com subscription login at ~/.grok/auth.json via grok login --device-auth; XAI_API_KEY is deleted from the child env because a leaked key silently flips billing to pay-as-you-go',
+    session: 'One ACP session per conversation; -m must sit between "agent" and "stdio"',
+    permissions: '--permission-mode default|auto|acceptEdits|bypassPermissions before "agent"; verified native tool selection only on grok 1.0.41 agent profiles',
+    usage: 'ACP token usage reports',
+  }), { transport: 'acp-stdio (grok --permission-mode … agent [-m slug] [--reasoning-effort lvl] stdio)' })),
+  Object.freeze(acpPending('geminiAgent', 'Gemini', Object.freeze({
+    file: 'server/drivers/acp/gemini.ts', anchor: 'L1-5,L51-88',
+    modelSelection: 'gemini-2.5-pro / gemini-2.5-flash, -m on spawn',
+    credentials: 'GEMINI_API_KEY / GOOGLE_API_KEY, Vertex, or an enterprise Code Assist licence; consumer Google logins stopped working 2026-06-18 (route those accounts through antigravityAgent)',
+    session: 'ACP session lifecycle',
+    permissions: '--yolo (full) / --approval-mode auto_edit (edits) / ask otherwise',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (gemini --acp)', access: 'api' })),
+  Object.freeze(acpPending('kimiAgent', 'Kimi', Object.freeze({
+    file: 'server/drivers/acp/kimi.ts', anchor: 'L521-566',
+    modelSelection: 'CLI catalog aliases from ~/.kimi-code/config.toml (kimi provider list reports the same four); -m is global and precedes "acp"',
+    credentials: 'Kimi Code account login via device sign-in; MOONSHOT_API_KEY/KIMI_API_KEY are deleted so billing cannot flip to pay-as-you-go',
+    session: 'ACP session lifecycle',
+    permissions: 'ACP permission requests',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (kimi -m <model> acp)' })),
+  Object.freeze(acpPending('droidAgent', 'Droid', Object.freeze({
+    file: 'server/drivers/acp/droid.ts', anchor: 'L173-185',
+    modelSelection: 'Driver model catalog',
+    credentials: 'droid login or FACTORY_API_KEY',
+    session: 'ACP session lifecycle',
+    permissions: 'ACP permission requests',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (droid)' })),
+  Object.freeze(acpPending('cursorAgent', 'Cursor', Object.freeze({
+    file: 'server/drivers/acp/cursor.ts', anchor: 'L474-513',
+    modelSelection: 'Models fetched from the cursor-agent CLI; --model is a global flag before "acp"',
+    credentials: 'cursor_login OAuth, or CURSOR_API_KEY / CURSOR_AUTH_TOKEN (a key in env already authenticates and suppresses the login flow)',
+    session: 'ACP session lifecycle',
+    permissions: '--force (full auto) / --auto-review (auto) on argv',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (cursor-agent [--force|--auto-review] [--model id] acp)' })),
+  Object.freeze(acpPending('opencodeGo', 'OpenCode', Object.freeze({
+    file: 'server/drivers/acp/opencode-go.ts', anchor: 'L851-912',
+    modelSelection: 'Catalog loaded from the opencode CLI/config (OPENCODE_API_KEY plus provider envs); typed/injected models declared via env; free no-login Zen fallback is gated',
+    credentials: 'OPENCODE_API_KEY or per-provider keys, or opencode auth login storage',
+    session: 'ACP sessions; shared process across conversations (shareProcess); global project folder isolation for non-git folders',
+    permissions: 'OPENCODE_PERMISSION env allow-map under full auto; owned-directory grants otherwise',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (opencode acp)' })),
+  Object.freeze(acpPending('qwenAgent', 'Qwen', Object.freeze({
+    file: 'server/drivers/acp/qwen.ts', anchor: 'L208-240',
+    modelSelection: 'Provider routes from ~/.qwen (model_routes); ACP session/load switches and confirms the whole route; unconfigured or ambiguous models refuse',
+    credentials: 'Qwen Code account/config under QWEN_RUNTIME_DIR / QWEN_HOME / ~/.qwen',
+    session: 'ACP session lifecycle; restartOnMcpChange (live session/load ignores fresh MCP credentials)',
+    permissions: '--approval-mode default|auto-edit|auto, --yolo for full auto',
+    usage: 'ACP session reports; QWEN_DEBUG_LOG_FILE parsed for quiet-status evidence',
+  }), { transport: 'acp-stdio (qwen --acp)', access: 'custom' })),
+  Object.freeze(acpPending('hermesAgent', 'Hermes', Object.freeze({
+    file: 'server/drivers/acp/hermes.ts', anchor: 'L407-456',
+    modelSelection: 'resolveHermesModels from the hermes CLI config; session/set_model per turn; one concrete model bound per grant',
+    credentials: 'hermes setup login; OPENAI_API_KEY/OPENROUTER_API_KEY deleted (a leftover key auto-resolves to OpenRouter with no Authorization header)',
+    session: 'ACP session lifecycle; restartOnMcpChange',
+    permissions: 'ACP permission requests',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (hermes acp)', access: 'custom' })),
+  Object.freeze(acpPending('clineAgent', 'Cline', Object.freeze({
+    file: 'server/drivers/acp/cline.ts', anchor: 'L55-69',
+    modelSelection: 'Driver model catalog',
+    credentials: 'Cline CLI sign-in',
+    session: 'ACP session lifecycle',
+    permissions: '--auto-approve false: every action asks',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (cline --acp --auto-approve false)' })),
+  Object.freeze(acpPending('copilotAgent', 'GitHub Copilot', Object.freeze({
+    file: 'server/drivers/acp/copilot.ts', anchor: 'L186-199',
+    modelSelection: 'Driver model catalog',
+    credentials: 'GitHub Copilot subscription login',
+    session: 'ACP sessions; one-shot session-state kept out of the person\'s copilot --resume list',
+    permissions: 'ACP permission requests',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (copilot --acp --stdio)' })),
+  Object.freeze(acpPending('commandCodeAgent', 'Command Code', Object.freeze({
+    file: 'server/drivers/acp/command-code.ts', anchor: 'L82-95',
+    modelSelection: 'Driver model catalog',
+    credentials: 'Command Code CLI sign-in',
+    session: 'ACP session lifecycle',
+    permissions: 'ACP permission requests',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (command-code acp)' })),
+  Object.freeze({
+    id: 'customAcp', name: 'Custom (ACP)', kind: 'conversation-engine',
+    transport: 'acp-stdio (user-configured command)',
+    multipleInstances: true, access: 'custom',
+    evidence: Object.freeze({
+      file: 'server/drivers/acp/custom.ts', anchor: 'L14-26',
+      modelSelection: 'agent-default plus models advertised by the configured agent',
+      credentials: 'Whatever the configured ACP command uses',
+      session: 'ACP session lifecycle',
+      permissions: 'ACP permission requests',
+      usage: 'ACP session reports',
+    }),
+    ...unavailable('Pending ACP core and trusted owner registration: custom engines remain in migration scope. Registration must commit a Host-approved executable pin, grant scope and permission broker; arbitrary executable/command fields in model or turn requests remain rejected.', 'pending-acp-core'),
+  }),
+  Object.freeze(acpPending('deepseekAgent', 'DeepSeek Harness', Object.freeze({
+    file: 'server/drivers/acp/deepseek.ts', anchor: 'L286-305',
+    modelSelection: 'Driver model catalog',
+    credentials: 'DeepSeek account login in the dsh CLI',
+    session: 'ACP session lifecycle',
+    permissions: 'ACP permission requests',
+    usage: 'ACP session reports',
+  }), { transport: 'acp-stdio (dsh --profile acp)' })),
+].map(Object.freeze))
+
+const byId = new Map(BOT_ENGINE_DRIVERS.map(driver => [driver.id, driver]))
+if (byId.size !== BOT_ENGINE_DRIVERS.length) throw new Error('DUPLICATE_BOT_ENGINE_DRIVER_ID')
+
+/** The closed id set, exactly the 26 upstream built-in drivers. */
+export const BOT_ENGINE_DRIVER_IDS = Object.freeze([...byId.keys()])
+
+export function getBotEngineDriver(id) {
+  if (typeof id !== 'string') return undefined
+  return byId.get(id)
+}
+
+export function listBotEngineDrivers() {
+  return BOT_ENGINE_DRIVERS.map(driver => Object.freeze({ ...driver, evidence: driver.evidence }))
+}
+
+/**
+ * Resolve a driver request into an engine factory. Only 'claude' is implemented; every
+ * other id returns an explicit unavailable verdict with its reason. Unknown ids throw.
+ * The input is never allowed to carry an executable, endpoint, command or credential:
+ * those are Host-owned and attempting to supply them is an error, not a configuration.
+ */
+export async function resolveBotEngine(request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) throw new TypeError('INVALID_ENGINE_REQUEST')
+  assertNoAdHocDriverInput(request)
+  const { driver: id } = request
+  const entry = byId.get(id)
+  if (!entry) throw new Error(`UNKNOWN_BOT_ENGINE_DRIVER: ${JSON.stringify(String(id))} (closed catalog of ${BOT_ENGINE_DRIVERS.length} upstream drivers)`)
+  if (entry.availability !== 'implemented') {
+    return { status: 'unavailable', driver: entry.id, name: entry.name, reason: entry.availabilityReason, targetCapability: entry.targetCapability }
+  }
+  const { createClaudeEngine } = await import('./claude-engine.mjs')
+  return { status: 'ready', driver: entry.id, name: entry.name, createEngine: createClaudeEngine, implementation: entry.implementation }
+}
+
+/** Ad-hoc engine inputs are refused outright: authority comes from committed Host state only. */
+export function assertNoAdHocDriverInput(request) {
+  const forbidden = ['executable', 'path', 'command', 'cmd', 'endpoint', 'url', 'baseUrl', 'args', 'argv', 'env', 'environment', 'credentials', 'apiKey', 'token', 'autoApprove', 'alwaysAllow', 'bypassPermissions']
+  for (const key of Object.keys(request)) {
+    if (forbidden.includes(key)) throw new TypeError(`HOST_OWNED_ENGINE_INPUT: ${key} may not appear in a driver request`)
+  }
+  return true
+}

package/packages/bot-engines/src/host-loop-request.mjs

@@ -0,0 +1,95 @@
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+const TEXT_FIELDS = new Set(['provider', 'model', 'messages', 'system', 'signal', 'sessionId'])
+const CONTROL_FIELDS = new Set(['maxTokens', 'reasoningEffort', 'temperature', 'stop', 'purpose'])
+const META_FIELDS = new Set(['tools', 'toolHistory'])
+const HOST_FACT_SOURCES = new Set(['runtime-context', 'ds-bot-time-context'])
+
+/** Project only a true, canonical Host loop request into the text-only native
+ * route. Nonempty tools and controls remain unsupported; no authority is
+ * accepted from a caller and the original request stays untouched for accounting.
+ */
+export function projectHostLoopTextRequest(request, { session, isLoopRequest, allowRouteContext = false } = {}) {
+  if (!session || session.id !== request?.sessionId || typeof isLoopRequest !== 'function'
+    || !isLoopRequest(request) || !Object.isFrozen(request) || !Object.isFrozen(request.messages)) fail('CLAUDE_HOST_LOOP_REQUEST_REQUIRED')
+  if (Object.keys(request).some(key => !TEXT_FIELDS.has(key) && !CONTROL_FIELDS.has(key) && !META_FIELDS.has(key))) fail('CLAUDE_ROUTE_UNKNOWN_REQUEST_FIELD')
+  if ([...CONTROL_FIELDS].some(key => request[key] !== undefined)) fail('CLAUDE_ROUTE_CAPABILITY_REFUSED')
+  if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.length)) fail('CLAUDE_ROUTE_CAPABILITY_REFUSED')
+  const canonical = session.deriveMessages()
+  if (!Array.isArray(request.messages) || canonical.length !== request.messages.length
+    || canonical.some((message, index) => message !== request.messages[index])) fail('CLAUDE_HOST_HISTORY_MISMATCH')
+  const history = session.toolHistory()
+  if (!history || !Array.isArray(history.tools) || !Array.isArray(history.updates)
+    || request.toolHistory !== undefined && request.toolHistory !== history) fail('CLAUDE_HOST_TOOL_HISTORY_UNSUPPORTED')
+  const foreign = allowRouteContext ? lastCompletedForeignReply(canonical, session, request) : null
+  if ((history.tools.length || history.updates.length) && !foreign) fail('CLAUDE_HOST_TOOL_HISTORY_UNSUPPORTED')
+  const declarationIds = new Set(history.updates.map(update => update.messageId))
+  const messages = []
+  for (const message of request.messages) {
+    if (foreign && message.role === 'developer' && message.source?.kind === 'tool-registry' && declarationIds.has(message.id)
+      && Array.isArray(message.content) && message.content.every(block => ['tool-addition', 'tool-removal'].includes(block.type))) continue
+    if (message.role === 'user' && (HOST_FACT_SOURCES.has(message.source?.kind)
+      || allowRouteContext && message.source?.kind === 'model-selection' && message.source.form === 'notice')) {
+      const previous = messages.at(-1)
+      if (previous?.role !== 'user' || HOST_FACT_SOURCES.has(previous.source?.kind)) fail('CLAUDE_HOST_RUNTIME_CONTEXT_UNSUPPORTED')
+      const text = plainText(message.content)
+      const input = plainText(previous.content)
+      messages[messages.length - 1] = { ...previous, content: [{ type: 'text', text: `${input}\n\n[Host runtime context]\n${text}` }] }
+    } else messages.push(message)
+  }
+  return { ...Object.fromEntries([...TEXT_FIELDS].filter(key => request[key] !== undefined).map(key => [key, request[key]])), messages }
+}
+
+function lastCompletedForeignReply(messages, session, route) {
+  const reply = messages.findLast(message => message.role === 'assistant' && message.source?.kind === 'model'
+    && (message.source.provider !== route.provider || message.source.model !== route.model))
+  if (!reply) return null
+  const event = session.log?.findLast(item => item.type === 'assistant/message' && item.data.message?.id === reply.id)
+  if (!event || !session.log.some(item => item.type === 'turn/end' && item.data.turn === event.data.turn && item.data.reason?.kind === 'completed')) {
+    fail('CLAUDE_HOST_ROUTE_CONTEXT_UNCONFIRMED')
+  }
+  return reply
+}
+
+/** A verified text prefix can initialize a new process as reference context. */
+export function hostLoopRouteContext(projected, { session, redact = text => text } = {}) {
+  const messages = projected.messages[0]?.role === 'system' ? projected.messages.slice(1) : projected.messages
+  const boundary = lastCompletedForeignReply(messages, session, projected)
+  if (!boundary) return null
+  const prefixLength = messages.indexOf(boundary) + 1
+  const completed = new Set(session.log.filter(event => event.type === 'turn/end' && event.data.reason?.kind === 'completed').map(event => event.data.turn))
+  const confirmed = new Map()
+  let turn = null
+  for (const event of session.log) {
+    if (event.type === 'turn/start') turn = event.data.turn
+    else if (event.type === 'turn/end') turn = null
+    else if (event.type === 'user/message' && completed.has(turn)) confirmed.set(event.data.id, event.type)
+    else if (event.type === 'assistant/message' && completed.has(event.data.turn) && !event.data.interrupted) confirmed.set(event.data.message?.id, event.type)
+  }
+  const history = messages.slice(0, prefixLength).map(message => {
+    if (!message.id || !['user', 'assistant'].includes(message.role) || confirmed.get(message.id) !== `${message.role}/message`) {
+      fail('CLAUDE_HOST_ROUTE_CONTEXT_UNSUPPORTED')
+    }
+    return { role: message.role, text: redact(plainText(message.content)) }
+  })
+  const text = JSON.stringify(history).replaceAll('<', '\\u003c')
+  const context = `\n\n<host_conversation_history>\nCompleted Host conversation, provided as reference. Continue with the new user input.\n${text}\n</host_conversation_history>`
+  if (Buffer.byteLength(`${hostSessionPersona(session, '')}${context}`) > 32_000) fail('CLAUDE_HOST_ROUTE_CONTEXT_LIMIT')
+  return { prefixLength, context }
+}
+
+function plainText(content) {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content) || content.some(part => part.type !== 'text' || typeof part.text !== 'string')) fail('CLAUDE_HOST_RUNTIME_CONTEXT_UNSUPPORTED')
+  return content.map(part => part.text).join('')
+}
+
+/** The persona is the Host's own current Session projection, never a request's
+ * proposed system field. It is still compared by the native adapter before use.
+ */
+export function hostSessionPersona(session, fallback = null) {
+  const head = session?.deriveMessages?.()[0]
+  if (head?.role !== 'system') return fallback
+  if (typeof head.content === 'string') return head.content
+  if (!Array.isArray(head.content) || head.content.some(part => part.type !== 'text' || typeof part.text !== 'string')) fail('CLAUDE_PERSONA_UNSUPPORTED')
+  return head.content.map(part => part.text).join('')
+}