@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/packages/server/lib/drivers/zcode-driver.js

@@ -1,1250 +1,1250 @@
-'use strict';
-
-const fs = require('fs');
-const { writeJson } = require('../json-file');
-const os = require('os');
-const path = require('path');
-const crypto = require('crypto');
-const { spawnSync } = require('child_process');
-const { createAppServerBridge } = require('../bridges/app-server-bridge');
-const {
-  appendTextAttachments, normalizeAttachments, resolveOpenAIBaseUrl, resolveOpenAIModel,
-} = require('../../../contracts');
-const { stampEvent, resequenceRestoredEvents } = require('../event-stream');
-
-// ZCode driver — speaks the "ZCode Protocol" app-server bundled with the
-// ZCode desktop install (`resources/glm/zcode.cjs`, `app-server --stdio`).
-// Protocol verified live against zcode CLI 0.16.5 / desktop 3.11.2:
-//
-//   - Line-delimited JSON-RPC over stdio WITHOUT the `jsonrpc` envelope field
-//     (the same dialect as `codex app-server`, so the shared app-server bridge
-//     drives it as-is). Server-initiated request ids are strings ("server-N").
-//   - No initialize handshake. The first request is usually `session/create`:
-//       { workspace: { workspacePath, workspaceKey }, mode, runtimeModel? }
-//     and it BLOCKS on a server-initiated `session/requestRuntimePreferences`
-//     request that must be answered before the create response arrives.
-//   - Sessions, not threads: `session/create` -> `session/resume` ->
-//     `session/subscribe` { deliveryKind: 'desktop-continuous' } ->
-//     `session/send` { content } -> `session/stop` to abort. Turn lifecycle
-//     and token deltas ride `session/event` notifications (types: turn.started,
-//     model.streaming, tool.updated, permission.requested/resolved,
-//     turn.completed, session.updated, session.titleUpdated, ...).
-//   - Approvals are server-initiated `interaction/requestPermission` requests
-//     whose params carry an `options[]` array; the response must echo one of
-//     `options[].response` (allow_once / allow_project / deny).
-//   - Models come from `runtimeModel` on create/resume/send (provider kind
-//     anthropic | openai | openai-compatible, inline api keys supported).
-//     Without one the app-server requires ~/.zcode/cli/config.json to define a
-//     provider; agent-owned turns bridge the desktop's ~/.zcode/v2/config.json
-//     providers instead (see desktopRuntimeModelFor).
-//
-// The driver deliberately has NO CLI one-shot fallback: the bundled CLI's
-// headless `--prompt` mode has no verified JSON event stream, so an unusable
-// app-server surfaces honest errors instead of a fake fallback transport.
-
-const ACTIVE_STATES = new Set(['running', 'thinking', 'tool-running']);
-// Workbench permission modes -> ZCode session modes
-// (default/plan/acceptEdits/bypassPermissions -> build/plan/edit/yolo).
-const MODE_FOR_PERMISSION = {
-  default: 'build',
-  plan: 'plan',
-  acceptEdits: 'edit',
-  bypassPermissions: 'yolo',
-};
-
-const RUNTIME_PREFERENCES = Object.freeze({
-  nativeSearchEnhancementsEnabled: false,
-  memoryEnabled: false,
-  askUserQuestionAutoResolutionEnabled: false,
-  modelContextBudgetStrategy: 'preflight-v1',
-});
-
-const APP_SERVER_PERSIST_SCHEMA = 'zcode-appserver-session/v1';
-const MAX_PERSISTED_EVENTS = 5000;
-
-// ---------------------------------------------------------------------------
-// CLI discovery
-// ---------------------------------------------------------------------------
-
-function defaultRegQuery(key) {
-  try {
-    const result = spawnSync('reg', ['query', key], { windowsHide: true, encoding: 'utf8', timeout: 5000 });
-    if (result.error || result.status !== 0) return null;
-    return String(result.stdout || '');
-  } catch {
-    return null;
-  }
-}
-
-function safeExists(target) {
-  try { return fs.existsSync(target); } catch { return false; }
-}
-
-function safeReaddir(dir) {
-  try { return fs.readdirSync(dir); } catch { return []; }
-}
-
-function providerRuntimeEnvironment(cliPath, { env = process.env, homedir = os.homedir(), existsSync = safeExists } = {}) {
-  const output = {};
-  if (!env.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE?.trim()) {
-    // Desktop bundles keep config beside glm, not inside it. Recent native
-    // CLIs otherwise resolve a development-tree fallback outside the install.
-    const dir = path.dirname(path.resolve(cliPath));
-    const bundled = [path.join(dir, 'provider/zcode-builtin.json'), path.resolve(dir, '../config/provider/zcode-builtin.json')].find(existsSync);
-    if (!bundled) return output;
-    output.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE = bundled;
-  }
-  if (!env.ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim()) output.ZCODE_PERSONAL_PROVIDER_CONFIG_FILE = path.join(env.ZCODE_DATA_BASE_DIR?.trim() || homedir, '.zcode/v2/provider_config.json');
-  return output;
-}
-
-// Discovery chain for the bundled zcode CLI:
-//   1. ZCODE_CLI_PATH env override (the .cjs itself or the install root);
-//   2. common Windows install roots (%LOCALAPPDATA%\Programs, Program Files,
-//      Program Files (x86) on every configured drive) scanning for
-//      <root>/*[Zz][Cc]ode*/resources/glm/zcode.cjs;
-//   3. registry App Paths (HKCU/HKLM ZCode.exe) via `reg query`;
-//   4. ~/.zcode neighbors (last resort).
-// Purely filesystem-based (no subprocess) so driver construction stays cheap;
-// everything is injectable for tests (env/existsSync/readdirSync/regQuery).
-function discoverZCodeCli(options = {}) {
-  const env = options.env || process.env;
-  const exists = options.existsSync || safeExists;
-  const readdir = options.readdirSync || safeReaddir;
-  const regQuery = options.regQuery || defaultRegQuery;
-  const home = options.homedir || os.homedir();
-
-  const candidates = [];
-  const envPath = String(env.ZCODE_CLI_PATH || '').trim();
-  if (envPath) {
-    candidates.push(envPath, path.join(envPath, 'resources', 'glm', 'zcode.cjs'));
-  }
-  const rootExprs = [
-    env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, 'Programs'),
-    env.ProgramFiles,
-    env['ProgramFiles(x86)'],
-    'C:\\Program Files',
-    'C:\\Program Files (x86)',
-    'D:\\Program Files',
-    'D:\\Program Files (x86)',
-  ].filter(Boolean);
-  for (const root of rootExprs) {
-    candidates.push(path.join(root, 'ZCode', 'resources', 'glm', 'zcode.cjs'));
-    for (const name of readdir(root)) {
-      if (/^zcode/i.test(name) || /zcode$/i.test(name)) {
-        candidates.push(path.join(root, name, 'resources', 'glm', 'zcode.cjs'));
-      }
-    }
-  }
-  // macOS desktop layout (cheap extra candidate, harmless elsewhere).
-  candidates.push('/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs');
-  // Registry App Paths: the desktop registers ZCode.exe there on install.
-  for (const hive of ['HKCU', 'HKLM']) {
-    const output = regQuery(`${hive}\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\ZCode.exe`);
-    const match = output && output.match(/REG_SZ\s+(\S*ZCode\.exe)/i);
-    if (match) candidates.push(path.join(path.dirname(match[1]), 'resources', 'glm', 'zcode.cjs'));
-  }
-  candidates.push(
-    path.join(home, '.zcode', 'cli', 'zcode.cjs'),
-    path.join(home, '.zcode', 'zcode.cjs'),
-  );
-
-  const seen = new Set();
-  for (const candidate of candidates) {
-    if (!candidate || seen.has(candidate)) continue;
-    seen.add(candidate);
-    if (exists(candidate)) return { path: candidate, source: 'discovered' };
-  }
-  return null;
-}
-
-// Version probe for /agents: spawns `node <zcode.cjs> --version`. Skipped under
-// the node:test runner so unit/integration suites never spawn a real 12MB CLI
-// bundle; production gets a real version string (cached by agent-discovery).
-function probeZCodeVersion(cliPath) {
-  if (process.env.NODE_TEST_CONTEXT) return null;
-  try {
-    const result = spawnSync(process.execPath, [cliPath, '--version'], {
-      timeout: 10000, windowsHide: true, encoding: 'utf8',
-    });
-    if (result.error || result.status !== 0) return null;
-    const match = String(result.stdout || result.stderr || '').match(/(\d+\.\d+[\w.-]*)/);
-    return match ? match[1] : null;
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Driver factory
-// ---------------------------------------------------------------------------
-
-function createZCodeDriver(options = {}) {
-  const injected = Boolean(options.appServerSpawn);
-  // Under the node:test runner an un-injected driver must stay a deterministic
-  // 501 placeholder (agent-drivers.test.js): discovery on a dev machine with
-  // ZCode installed would otherwise spawn real app-server children in tests.
-  const testContext = Boolean(process.env.NODE_TEST_CONTEXT);
-  let cli = null;
-  if (injected) {
-    cli = { path: options.cliPath || '<injected app-server>', source: 'injected' };
-  } else if (!testContext) {
-    cli = options.cli || discoverZCodeCli({ env: options.env });
-  }
-  if (!cli) {
-    const reason = testContext
-      ? 'ZCode app-server transport is not scripted in this test context; inject an appServerSpawn double to drive it'
-      : 'ZCode desktop was not found on this machine. Install the ZCode desktop app (it bundles the zcode CLI used by the app-server transport), or set ZCODE_CLI_PATH to the installed resources/glm/zcode.cjs';
-    return createUnavailableZCodeDriver(reason);
-  }
-  return createAppServerZCodeDriver(options, cli);
-}
-
-// Honest 501 shell (the pre-driver behavior, kept for missing installs and
-// unscripted test contexts).
-function createUnavailableZCodeDriver(reason) {
-  return {
-    agentId: 'zcode',
-    unavailableReason: reason,
-    startChatSession() {
-      throw Object.assign(new Error(this.unavailableReason), { status: 501 });
-    },
-    listSessions() { return []; },
-    getState() { return null; },
-    getSession() { return null; },
-    getSessionTokenUsage() { return { used: 0, hasUsage: false }; },
-    subscribe() { throw Object.assign(new Error('session not found'), { status: 404 }); },
-    async sendInput() { throw Object.assign(new Error(this.unavailableReason), { status: 501 }); },
-    resolvePermission() { throw Object.assign(new Error(this.unavailableReason), { status: 501 }); },
-    abort() {},
-    deleteSession() { return false; },
-    async listSupportedCommands() { return []; },
-    findClaudeExecutableForSdk() { return null; },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// app-server transport
-// ---------------------------------------------------------------------------
-
-function createAppServerZCodeDriver(options, cli) {
-  const log = typeof options.log === 'function' ? options.log : () => {};
-  const sessions = new Map();
-  const zcodeSessions = new Map(); // zcode sessionId (sess_...) -> driver sessionId
-  const persist = resolvePersistence(options);
-  let diskIndex = null;
-  let nextId = 1;
-  let nextPermissionId = 1;
-  let bridge = null;
-  let protocolMode = null;
-  let profileRuntime = null;
-  let profileRuntimeSignature = null;
-  let bridgeSetup = Promise.resolve();
-  let destroyed = false;
-  let desktopProviderCache; // lazily-read ~/.zcode/v2 providers (agent-owned auth)
-
-  function summary(session) {
-    return {
-      sessionId: session.sessionId,
-      projectSlug: session.projectSlug,
-      state: session.state,
-      model: session.model,
-      selectedModel: session.selectedModel,
-      aiProfileId: session.aiProfileId,
-      permissionMode: session.permissionMode,
-      turns: session.turns,
-      startedAt: session.startedAt,
-      // Live activity marker: turn end refreshes it (see turns += 1 site).
-      updatedAt: session.updatedAt || session.startedAt,
-      endedAt: session.endedAt,
-      pendingPermission: session.pendingPermission,
-    };
-  }
-
-  function emit(session, event) {
-    stampEvent(session, event);
-    session.outputBuffer.push(event);
-    if (session.outputBuffer.length > MAX_PERSISTED_EVENTS) session.outputBuffer.shift();
-    for (const listener of session.listeners) {
-      try { listener(event); } catch { /* listener errors never break the turn */ }
-    }
-  }
-
-  function setState(session, state) {
-    session.state = state;
-    emit(session, { type: 'claude/state', state, turn: session.turns });
-  }
-
-  // ---- persistence (records share ~/.agent-terminal/cli-sessions with the
-  // other CLI drivers but carry their own schema; only this driver claims
-  // them). The zcode session id (sess_...) is stored as threadId so a restart
-  // resumes the server-side conversation instead of starting a new one. ----
-
-  function recordFile(sessionId) {
-    return path.join(persist.dir, `${safeFileStem(sessionId)}.json`);
-  }
-
-  function readRecord(file) {
-    try {
-      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
-      if (parsed && parsed.schema === APP_SERVER_PERSIST_SCHEMA && parsed.agentId === 'zcode'
-        && parsed.transport === 'app-server' && typeof parsed.sessionId === 'string' && parsed.sessionId) return parsed;
-    } catch { /* corrupt or foreign records are skipped, never fatal */ }
-    return null;
-  }
-
-  function syncDiskIndex() {
-    if (!persist.enabled) return null;
-    if (!diskIndex) diskIndex = new Map();
-    else diskIndex.clear();
-    let names = [];
-    try { names = fs.readdirSync(persist.dir).filter(name => name.endsWith('.json')); } catch { return diskIndex; }
-    for (const name of names) {
-      const file = path.join(persist.dir, name);
-      const record = readRecord(file);
-      if (record) diskIndex.set(record.sessionId, { file, summary: persistedSummary(record) });
-    }
-    return diskIndex;
-  }
-
-  function persistedSummary(record) {
-    return {
-      sessionId: record.sessionId,
-      projectSlug: record.projectSlug,
-      state: 'idle', // a restart killed any live turn
-      model: record.model || null,
-      selectedModel: record.selectedModel || null,
-      aiProfileId: record.aiProfileId || null,
-      permissionMode: record.permissionMode || 'default',
-      turns: Number(record.turns) || 0,
-      startedAt: record.startedAt || '',
-      updatedAt: record.updatedAt || record.startedAt || '',
-      endedAt: record.endedAt || null,
-      pendingPermission: null,
-    };
-  }
-
-  function persistSession(session) {
-    if (!persist.enabled) return;
-    try {
-      const file = recordFile(session.sessionId);
-      writeJson(file, {
-        schema: APP_SERVER_PERSIST_SCHEMA,
-        agentId: 'zcode',
-        transport: 'app-server',
-        sessionId: session.sessionId,
-        projectSlug: session.projectSlug,
-        projectPath: session.projectPath,
-        state: session.state,
-        model: session.model,
-        selectedModel: session.selectedModel,
-        aiProfileId: session.aiProfileId,
-        permissionMode: session.permissionMode,
-        title: session.title || null,
-        turns: session.turns,
-        startedAt: session.startedAt,
-        endedAt: session.endedAt,
-        // The ZCode Protocol session id: session/resume needs it after a restart.
-        threadId: session.zcodeSessionId || null,
-        lastResult: session.lastResult || '',
-        usage: { ...session.usage },
-        peakTurnTokens: session.peakTurnTokens || 0,
-      eventSequence: Number(session.eventSequence) || 0,
-        // Old numeric cursors predate this session's numbering era; the
-        // boundary must survive restarts, not just the first restore.
-        legacySequenceReset: session.legacySequenceReset === true,
-        events: session.outputBuffer.slice(-MAX_PERSISTED_EVENTS),
-        updatedAt: new Date().toISOString(),
-      });
-      if (diskIndex) diskIndex.set(session.sessionId, { file: recordFile(session.sessionId), summary: summary(session) });
-    } catch {
-      // Read-only home or full disk degrades to memory-only behavior.
-      persist.enabled = false;
-      diskIndex = null;
-    }
-  }
-
-  function removeRecord(sessionId) {
-    if (diskIndex) diskIndex.delete(sessionId);
-    if (!persist.enabled) return;
-    try {
-      const file = recordFile(sessionId);
-      if (fs.existsSync(file) && readRecord(file)) fs.rmSync(file, { force: true });
-    } catch { /* already gone */ }
-  }
-
-  function restoreSession(id) {
-    if (!persist.enabled) return null;
-    const index = syncDiskIndex();
-    const entry = index && index.get(id);
-    if (!entry) return null;
-    const record = readRecord(entry.file);
-    if (!record || record.sessionId !== id) { index.delete(id); return null; }
-    // Legacy records (written before stable event identity) carry unstamped
-    // events: renumber the retained tail explicitly and continue from there.
-    const restored = resequenceRestoredEvents(
-      Array.isArray(record.events) ? record.events.slice(-MAX_PERSISTED_EVENTS) : [],
-      record.eventSequence,
-    );
-    const session = {
-      sessionId: record.sessionId,
-      projectSlug: record.projectSlug,
-      projectPath: record.projectPath,
-      state: 'idle',
-      model: record.model || null,
-      selectedModel: record.selectedModel || null,
-      aiProfileId: record.aiProfileId || null,
-      permissionMode: record.permissionMode || 'default',
-      effort: null,
-      title: record.title || null,
-      turns: Number(record.turns) || 0,
-      startedAt: record.startedAt || new Date().toISOString(),
-      updatedAt: record.updatedAt || record.startedAt || new Date().toISOString(),
-      endedAt: record.endedAt || null,
-      pendingPermission: null,
-      pendingApproval: null,
-      outputBuffer: restored.events,
-      eventSequence: restored.eventSequence,
-      legacySequenceReset: restored.legacyRenumbered === true || record.legacySequenceReset === true,
-      listeners: new Set(),
-      zcodeSessionId: record.threadId || null,
-      currentTurn: null,
-      lastResult: record.lastResult || '',
-      lastDiag: '',
-      usage: {
-        inputTokens: Number(record.usage && record.usage.inputTokens) || 0,
-        outputTokens: Number(record.usage && record.usage.outputTokens) || 0,
-        cachedTokens: Number(record.usage && record.usage.cachedTokens) || 0,
-      },
-      peakTurnTokens: Number(record.peakTurnTokens) || 0,
-      turnTokenUsage: null,
-      turnPromise: Promise.resolve(),
-    };
-    sessions.set(id, session);
-    return session;
-  }
-
-  const runner = {
-    agentId: 'zcode',
-
-    startChatSession({ slug, projectPath, aiProfile, permissionMode, effort, title }) {
-      if (!slug) throw new Error('slug required');
-      if (!projectPath) throw new Error('projectPath required');
-      const sessionId = nextDriverSessionId();
-      const session = {
-        sessionId,
-        projectSlug: slug,
-        projectPath,
-        state: 'idle',
-        model: modelForProfile(aiProfile),
-        selectedModel: aiProfile && (aiProfile.mainModel || aiProfile.models && aiProfile.models.default) || '',
-        aiProfileId: aiProfile && aiProfile.id,
-        permissionMode: permissionMode || 'default',
-        effort: effort || null,
-        title: title || null,
-        turns: 0,
-        startedAt: new Date().toISOString(),
-        endedAt: null,
-        pendingPermission: null,
-        pendingApproval: null,
-        outputBuffer: [],
-        eventSequence: 0,
-        listeners: new Set(),
-        zcodeSessionId: null,
-        currentTurn: null,
-        lastResult: '',
-        lastDiag: '',
-        usage: { inputTokens: 0, outputTokens: 0, cachedTokens: 0 },
-        peakTurnTokens: 0,
-        turnTokenUsage: null,
-        turnPromise: Promise.resolve(),
-      };
-      sessions.set(sessionId, session);
-      emit(session, {
-        type: 'claude/session-ready',
-        model: session.model,
-        aiProfileId: session.aiProfileId,
-        permissionMode: session.permissionMode,
-        message: 'zcode session is ready. Send a message to start the first turn.',
-      });
-      // Write the record immediately so a session with no turns yet still
-      // shows up in the sidebar after a restart.
-      persistSession(session);
-      return { sessionId };
-    },
-
-    listSessions(filter = {}) {
-      const byId = new Map();
-      const index = syncDiskIndex();
-      if (index) {
-        for (const entry of index.values()) {
-          if (filter.projectSlug && entry.summary.projectSlug !== filter.projectSlug) continue;
-          byId.set(entry.summary.sessionId, entry.summary);
-        }
-      }
-      for (const session of sessions.values()) {
-        if (filter.projectSlug && session.projectSlug !== filter.projectSlug) continue;
-        byId.set(session.sessionId, summary(session));
-      }
-      return [...byId.values()];
-    },
-
-    getState(id) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) return null;
-      return {
-        ...summary(session),
-        listenerCount: session.listeners.size,
-        bufferedEvents: session.outputBuffer.length,
-      };
-    },
-
-    getSession(id) { return sessions.get(id) || restoreSession(id); },
-
-    getSessionTokenUsage(id) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) return { used: 0, hasUsage: false };
-      const { inputTokens, outputTokens } = session.usage;
-      const used = session.peakTurnTokens || 0;
-      return {
-        used,
-        inputTokens,
-        outputTokens,
-        hasUsage: Boolean(used || inputTokens || outputTokens),
-      };
-    },
-
-    subscribe(id, listener) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
-      for (const event of session.outputBuffer) listener(event);
-      session.listeners.add(listener);
-      return () => session.listeners.delete(listener);
-    },
-
-    async sendInput(id, text, profile, sendOptions = {}) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
-      if (ACTIVE_STATES.has(session.state)) {
-        throw Object.assign(new Error('session already has an active turn'), { status: 409 });
-      }
-      const value = String(text || '').trim();
-      const attachments = normalizeAttachments(sendOptions.attachments || []);
-      if (!value && !attachments.length) throw Object.assign(new Error('text or attachments are required'), { status: 400 });
-      if (profile) {
-        session.model = modelForProfile(profile);
-        session.selectedModel = profile.mainModel || profile.models && profile.models.default || '';
-      }
-      if (sendOptions.permissionMode) session.permissionMode = sendOptions.permissionMode;
-      session.lastPromptText = value;
-
-      let runtimeModel = null;
-      try {
-        // Invalid injected profiles (no base URL) throw here and surface as a
-        // turn error, mirroring the codex driver's bridgeSpecFor contract.
-        runtimeModel = runtimeModelFor(profile);
-        session.preparing = true;
-        session.runtimeSignature = profile?.apiKey ? runtimeModel.revision : 'agent-owned';
-        await ensureBridge(profile, session);
-        await ensureZcodeSession(session, runtimeModel);
-      } catch (error) {
-        emit(session, { type: 'claude/error', message: `zcode app-server unavailable: ${error.message}`.slice(0, 500) });
-        setState(session, 'idle');
-        return { started: false };
-      } finally { session.preparing = false; }
-
-      emit(session, {
-        type: 'claude/user-prompt',
-        text: value,
-        attachments: (sendOptions.displayAttachments || []).map(({ id: attachmentId, name, mediaType, size, width, height, url }) => ({ id: attachmentId, name, mediaType, size, width, height, url })),
-      });
-      setState(session, 'running');
-      // Until the first session/event lands the UI would show dead air
-      // (reasoning models think for tens of seconds first) — announce it.
-      setState(session, 'thinking');
-      try {
-        // Image attachments have no verified ZCode Protocol wire shape yet
-        // (session/send attachments are an opaque record); text attachments
-        // ride the prompt text, images are refused with an honest notice.
-        const images = attachments.filter(item => item.mediaType.startsWith('image/'));
-        if (images.length) {
-          emitDiag(session, { type: 'claude/stderr', text: 'the zcode app-server driver does not support image attachments yet' });
-        }
-        session.currentTurn = {
-          turnId: null,
-          announcedText: new Set(),
-          streamedText: new Set(),
-          announcedThinking: new Set(),
-          streamedThinking: new Set(),
-          sawEvent: false,
-        };
-        session.turnPromise = new Promise(resolve => { session.currentTurn.resolve = resolve; });
-        await bridge.request('session/send', {
-          sessionId: session.zcodeSessionId,
-          content: appendTextAttachments(value, attachments) + (sendOptions.knowledgeContext || ''),
-          ...(protocolMode === 'selection' ? (session.nativeModel ? { modelSelection: session.nativeModel } : {}) : runtimeModel ? { runtimeModel } : {}),
-        }, { timeoutMs: 30000 });
-        return { started: true };
-      } catch (error) {
-        finishTurn(session, { resultType: 'error', response: '' }, `zcode turn failed to start: ${error.message}`);
-        return { started: false };
-      }
-    },
-
-    resolvePermission(id, requestId, decision) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session || !session.pendingApproval || session.pendingApproval.requestId !== requestId) {
-        throw Object.assign(new Error('permission request not found or already resolved'), { status: 409 });
-      }
-      const allow = decision && decision.allow === true;
-      const approval = session.pendingApproval;
-      session.pendingApproval = null;
-      session.pendingPermission = null;
-      const response = allow ? approval.allowResponse : approval.denyResponse;
-      emit(session, {
-        type: 'claude/permission-resolved',
-        requestId,
-        allow,
-        decision: response && response.decision,
-        resolvedAt: new Date().toISOString(),
-      });
-      setState(session, 'running');
-      approval.resolve(response);
-      return { ok: true, started: true, decision: response && response.decision };
-    },
-
-    updateSelection(id, profile, selectedModel) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
-      if (ACTIVE_STATES.has(session.state)) {
-        throw Object.assign(new Error('session already has an active turn'), { status: 409 });
-      }
-      const fromAiProfileId = session.aiProfileId || null;
-      const fromModel = session.selectedModel || session.model || null;
-      session.aiProfileId = profile && profile.id || null;
-      session.selectedModel = selectedModel || (profile && (profile.mainModel || profile.models && profile.models.default)) || null;
-      session.model = modelForProfile(profile);
-      emit(session, {
-        type: 'claude/selection-changed',
-        fromAiProfileId,
-        toAiProfileId: session.aiProfileId,
-        fromModel,
-        toModel: session.selectedModel,
-      });
-      persistSession(session);
-      return summary(session);
-    },
-
-    abort(id, reason) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) return;
-      session.abortedByUser = true;
-      denyPendingApproval(session, 'aborted');
-      const currentTurn = session.currentTurn;
-      if (currentTurn && bridge && bridge.state === 'ready' && session.zcodeSessionId) {
-        // Ask the app-server to interrupt the live turn; a failure falls back
-        // to the local turn teardown below (the bridge recycles lazily).
-        bridge.request('session/stop', { sessionId: session.zcodeSessionId }, { timeoutMs: 5000 })
-          .catch(() => recycleBridge('session/stop failed'));
-      }
-      if (!['idle', 'ended'].includes(session.state)) {
-        session.state = 'aborted';
-        emit(session, { type: 'claude/aborted', reason: reason || 'user-abort' });
-        finishTurn(session, { resultType: 'cancelled', response: '' });
-      }
-      persistSession(session);
-    },
-
-    deleteSession(id) {
-      const session = sessions.get(id) || restoreSession(id);
-      if (!session) {
-        const index = syncDiskIndex();
-        if (index && index.has(id)) { removeRecord(id); return true; }
-        return false;
-      }
-      if (ACTIVE_STATES.has(session.state)) runner.abort(id);
-      denyPendingApproval(session, 'deleted');
-      if (session.zcodeSessionId) zcodeSessions.delete(session.zcodeSessionId);
-      const deleted = sessions.delete(id);
-      removeRecord(id);
-      return deleted;
-    },
-
-    async listSupportedCommands() { return []; },
-
-    findClaudeExecutableForSdk() { return null; },
-
-    async destroy() {
-      destroyed = true;
-      for (const session of sessions.values()) if (ACTIVE_STATES.has(session.state)) runner.abort(session.sessionId);
-      await bridge?.close(); bridge = null;
-      await bridgeSetup.catch(() => {});
-      await bridge?.close(); bridge = null;
-      await profileRuntime?.close(); profileRuntime = null;
-    },
-
-    // Test seams.
-    get transportMode() { return 'app-server'; },
-    get bridgeState() { return bridge ? bridge.state : 'uncreated'; },
-    get cliPath() { return cli.path; },
-  };
-
-  // -- bridge lifecycle ----------------------------------------------------
-
-  function ensureBridge(profile, session) {
-    const preparing = bridgeSetup.then(() => prepareBridge(profile, session));
-    bridgeSetup = preparing.catch(() => {});
-    return preparing;
-  }
-
-  async function prepareBridge(profile, session) {
-    if (destroyed) throw new Error('ZCode 工作台正在关闭。');
-    if (protocolMode === 'selection' && profileRuntimeSignature !== session.runtimeSignature) {
-      if ([...sessions.values()].some(other => other !== session && (other.preparing || ACTIVE_STATES.has(other.state)) && other.runtimeSignature !== session.runtimeSignature)) throw new Error('另一个 ZCode 任务正在使用不同的模型配置，请等待任务结束。');
-      if (profileRuntimeSignature !== null || profile?.apiKey) { await bridge?.close(); bridge = null; }
-      await profileRuntime?.close(); profileRuntime = null;
-      if (profile?.apiKey) profileRuntime = await require('./zcode-profile-runtime').createZCodeProfileRuntime(injectedRuntimeModel(profile));
-      profileRuntimeSignature = session.runtimeSignature;
-    }
-    if (destroyed) throw new Error('ZCode 工作台正在关闭。');
-    if (bridge && bridge.state === 'closed') { bridge = null; }
-    if (bridge && bridge.state === 'crashed') { recycleBridge('bridge exhausted its restart budget'); }
-    if (!bridge) {
-      bridge = createAppServerBridge({
-        // The bundled CLI is a node bundle: spawn it through the running node
-        // runtime with the app-server stdio subcommand.
-        command: options.nodePath || process.execPath,
-        args: [cli.path, 'app-server', '--stdio'],
-        env: { ...providerRuntimeEnvironment(cli.path, { env: options.env || process.env }), ...(profileRuntime ? { ZCODE_PERSONAL_PROVIDER_CONFIG_FILE: profileRuntime.file } : {}), ...(options.knowledgeContextProvided ? { KB_KNOWLEDGE_CONTEXT: '0' } : {}), ...(options.conversationCaptureProvided ? { AI_CODING_EVENT_BRIDGE_CAPTURE: '0' } : {}) },
-        spawn: options.appServerSpawn,
-        onEvent: handleNotification,
-        onServerRequest: handleServerRequest,
-        onUnexpectedExit: handleBridgeCrash,
-        idleTimeoutMs: options.idleTimeoutMs !== undefined ? options.idleTimeoutMs : 10 * 60 * 1000,
-        requestTimeoutMs: options.requestTimeoutMs !== undefined ? options.requestTimeoutMs : 120000,
-        restartBackoffMs: options.restartBackoffMs,
-        log,
-      });
-    }
-    await bridge.start();
-    if (protocolMode === null) {
-      try { const capabilities = await bridge.request('runtime/capabilities', {}, { timeoutMs: 10000 }); protocolMode = capabilities?.independentPlanState === true ? 'selection' : 'runtime-model'; }
-      catch (error) { if (error.rpcCode !== -32601) throw error; protocolMode = 'runtime-model'; }
-      if (protocolMode === 'selection') return prepareBridge(profile, session);
-    }
-  }
-
-  function recycleBridge(reason) {
-    log(`recycling zcode app-server bridge: ${reason}`);
-    if (bridge) bridge.close().catch(() => {});
-    bridge = null;
-    failoverSessions(`zcode app-server exited: ${reason}`);
-  }
-
-  // The app-server died mid-flight: turn.completed will never arrive, so
-  // every live turn is finished with an error here (the bridge restarts
-  // itself and the next turn retries with a fresh session/resume).
-  function handleBridgeCrash(error) {
-    failoverSessions(`zcode app-server exited unexpectedly: ${error && error.message || 'crashed'}`);
-  }
-
-  function failoverSessions(reason) {
-    for (const session of sessions.values()) {
-      denyPendingApproval(session, reason);
-      if (!session.currentTurn) continue;
-      finishTurn(session, { resultType: 'error', response: '' }, String(reason).slice(0, 500));
-    }
-  }
-
-  // -- zcode session lifecycle ----------------------------------------------
-
-  async function ensureZcodeSession(session, runtimeModel) {
-    if (session.zcodeSessionId) {
-      try {
-        const resumed = await bridge.request('session/resume', {
-          sessionId: session.zcodeSessionId,
-          ...(protocolMode !== 'selection' && runtimeModel ? { runtimeModel } : {}),
-        }, { timeoutMs: 30000 });
-        if (protocolMode === 'selection') { session.nativeModel = resumed.settings?.model?.current || session.nativeModel || null; await selectNativeModel(session); }
-        zcodeSessions.set(session.zcodeSessionId, session.sessionId);
-        await subscribeZcodeSession(session);
-        return;
-      } catch (error) {
-        // The app-server child restarted or rolled the session away; fall
-        // through to a fresh one (the client-side history stays).
-        zcodeSessions.delete(session.zcodeSessionId);
-        session.zcodeSessionId = null;
-        log(`zcode session resume failed, creating a new one: ${error.message}`);
-      }
-    }
-    const result = await bridge.request('session/create', {
-      workspace: { workspacePath: session.projectPath, workspaceKey: session.projectPath },
-      mode: MODE_FOR_PERMISSION[session.permissionMode] || 'build',
-      ...(protocolMode === 'selection' ? { titleGenerationEnabled: false } : runtimeModel ? { runtimeModel } : {}),
-    }, { timeoutMs: 60000 });
-    const zcodeId = result && result.session && (result.session.sessionId || result.session.id);
-    if (!zcodeId) throw new Error('zcode app-server did not return a session');
-    session.zcodeSessionId = zcodeId;
-    if (protocolMode === 'selection') { session.nativeModel = result.settings?.model?.current || null; await selectNativeModel(session); }
-    zcodeSessions.set(zcodeId, session.sessionId);
-    if (result.session && result.session.title && !session.title) session.title = result.session.title;
-    await subscribeZcodeSession(session);
-    persistSession(session);
-  }
-
-  async function selectNativeModel(session) {
-    if (profileRuntime) session.nativeModel = profileRuntime.selection;
-    else if (session.selectedModel) {
-      const slash = session.selectedModel.indexOf('/');
-      if (slash > 0) session.nativeModel = { providerId: session.selectedModel.slice(0, slash), modelId: session.selectedModel.slice(slash + 1), options: { reasoningLevel: 'enabled' } };
-      else if (session.nativeModel) session.nativeModel = { ...session.nativeModel, modelId: session.selectedModel };
-    }
-    await bridge.request('session/setMode', { sessionId: session.zcodeSessionId, mode: MODE_FOR_PERMISSION[session.permissionMode] || 'build' }, { timeoutMs: 10000 });
-  }
-
-  async function subscribeZcodeSession(session) {
-    await bridge.request('session/subscribe', {
-      sessionId: session.zcodeSessionId,
-      deliveryKind: 'desktop-continuous',
-    }, { timeoutMs: 30000 });
-  }
-
-  // -- notifications ---------------------------------------------------------
-
-  function handleNotification({ method, params }) {
-    if (!params) return;
-    const session = routeZcodeSession(params.sessionId);
-    if (!session) return; // notifications for unknown sessions are ignored
-    if (method === 'session/event') return onSessionEvent(session, params);
-    if (method === 'state.updated') {
-      // status patches (running/idle) only mark liveness here; turn completion
-      // is authoritative on the session/event stream.
-      markActivity(session);
-      return;
-    }
-    // computer-use/operation-event, v4/telemetry/event, process/*, ... are noise.
-  }
-
-  function routeZcodeSession(zcodeSessionId) {
-    if (!zcodeSessionId) return null;
-    const driverId = zcodeSessions.get(zcodeSessionId);
-    return driverId ? sessions.get(driverId) : null;
-  }
-
-  function markActivity(session) {
-    const turn = session.currentTurn;
-    if (!turn) return;
-    if (!turn.sawEvent) {
-      turn.sawEvent = true;
-      if (session.state === 'thinking') setState(session, 'running');
-    }
-  }
-
-  function onSessionEvent(session, params) {
-    markActivity(session);
-    const turn = session.currentTurn;
-    if (!turn) return; // events outside a driver-tracked turn (e.g. background) are ignored
-    const { type, payload } = params;
-    if (params.turnId && !turn.turnId) turn.turnId = params.turnId;
-    if (turn.turnId && params.turnId && params.turnId !== turn.turnId) return; // stale turn
-
-    switch (type) {
-      case 'turn.started': return; // announced locally at send time
-      case 'model.streaming': return onModelStreaming(session, payload || {});
-      case 'tool.updated': return onToolUpdated(session, payload || {});
-      case 'turn.completed': return finishTurn(session, payload || {});
-      case 'turn.failed': return finishTurn(session, { resultType: 'error', response: '' }, payload?.error?.message || payload?.error?.code || 'ZCode 任务失败');
-      case 'session.titleUpdated': {
-        if (payload && payload.title) session.title = String(payload.title).slice(0, 200);
-        return;
-      }
-      case 'permission.requested':
-      case 'permission.resolved':
-        return; // approvals are driven by the interaction/requestPermission RPC
-      default: return; // session.updated, checkpoint.*, streamRecovery.*, ...
-    }
-  }
-
-  function onModelStreaming(session, payload) {
-    const turn = session.currentTurn;
-    if (!turn) return;
-    const { kind } = payload;
-    const messageId = payload.assistantMessageId || `text-${session.turns}`;
-    if (kind === 'text_start') {
-      turn.announcedText.add(messageId);
-      emit(session, { type: 'claude/text-start', id: messageId });
-    } else if (kind === 'text_delta') {
-      if (!turn.announcedText.has(messageId)) {
-        turn.announcedText.add(messageId);
-        emit(session, { type: 'claude/text-start', id: messageId });
-      }
-      turn.streamedText.add(messageId);
-      emit(session, { type: 'claude/text-delta', id: messageId, text: String(payload.delta || '') });
-    } else if (kind === 'reasoning_start') {
-      turn.announcedThinking.add(messageId);
-      emit(session, { type: 'claude/thinking-start', id: messageId });
-    } else if (kind === 'reasoning_delta') {
-      if (!turn.announcedThinking.has(messageId)) {
-        turn.announcedThinking.add(messageId);
-        emit(session, { type: 'claude/thinking-start', id: messageId });
-      }
-      turn.streamedThinking.add(messageId);
-      emit(session, { type: 'claude/thinking-delta', id: messageId, text: String(payload.delta || '') });
-    } else if (kind === 'tool_call') {
-      setState(session, 'tool-running');
-      emit(session, {
-        type: 'claude/tool-use',
-        id: payload.toolCallId || `tool-${session.turns}-${session.outputBuffer.length}`,
-        name: payload.toolName || 'Tool',
-        input: payload.input && typeof payload.input === 'object' ? payload.input : { input: payload.input },
-      });
-    } else if (kind === 'tool_error') {
-      emit(session, {
-        type: 'claude/tool-result',
-        id: payload.toolCallId || `tool-${session.turns}-${session.outputBuffer.length}`,
-        output: String(payload.delta || payload.error || 'tool failed').slice(0, 4000),
-        isError: true,
-      });
-    }
-    // text_end / reasoning_end / tool_input_* deltas need no normalized event;
-    // the tool_use input arrives complete on the tool_call kind.
-  }
-
-  function onToolUpdated(session, payload) {
-    if (!payload.result || !payload.toolCallId) return; // scheduling metadata only
-    setState(session, 'running');
-    emit(session, {
-      type: 'claude/tool-result',
-      id: payload.toolCallId,
-      output: toolResultText(payload.result).slice(0, 4000),
-      isError: payload.result.success === false,
-    });
-  }
-
-  function finishTurn(session, payload, forcedError) {
-    const current = session.currentTurn;
-    if (!current) return;
-    session.currentTurn = null;
-    denyPendingApproval(session, 'turn completed'); // the server cancels unanswered approvals
-    session.turns += 1;
-    session.updatedAt = new Date().toISOString();
-    const usage = payload.usage || {};
-    const input = Number(usage.inputTokens || 0);
-    const output = Number(usage.outputTokens || 0);
-    const cached = Number(usage.cacheReadTokens || 0);
-    if (input || output || cached) {
-      session.usage.inputTokens += input;
-      session.usage.outputTokens += output;
-      session.usage.cachedTokens += cached;
-      session.peakTurnTokens = Math.max(session.peakTurnTokens || 0, input + output + cached);
-      emit(session, { type: 'claude/usage', usage: { input_tokens: input, output_tokens: output } });
-    }
-    const resultType = String(payload.resultType || 'success');
-    const response = String(payload.response != null ? payload.response : session.lastResult || '');
-    if (response) session.lastResult = response;
-    const failed = resultType === 'error' || resultType === 'failed' || Boolean(forcedError);
-    if (failed) {
-      emitDiag(session, { type: 'claude/error', message: String(forcedError || `zcode turn ${resultType}`).slice(0, 500) });
-    }
-    if (resultType === 'cancelled' && !session.abortedByUser) {
-      emit(session, { type: 'claude/aborted' });
-    }
-    emit(session, {
-      type: 'claude/result',
-      result: failed ? '' : response,
-      model: session.model,
-      isError: failed,
-    });
-    session.abortedByUser = false;
-    if (!session.endedAt) session.state = 'idle';
-    emit(session, { type: 'claude/state', state: 'idle', turn: session.turns });
-    persistSession(session);
-    if (current.resolve) current.resolve();
-  }
-
-  function emitDiag(session, event) {
-    const text = event.text != null ? event.text : event.message;
-    if (text === session.lastDiag) return;
-    session.lastDiag = String(text == null ? '' : text);
-    emit(session, event);
-  }
-
-  // -- server-initiated requests (preferences + approvals) ------------------
-
-  async function handleServerRequest(method, params) {
-    if (method === 'session/requestRuntimePreferences') {
-      // Defaults verified live: native search off, memory off, question
-      // auto-resolution off; answering unblocks session/create and session/send.
-      return RUNTIME_PREFERENCES;
-    }
-    if (method === 'interaction/requestPermission') {
-      const session = routeZcodeSession(params && params.sessionId);
-      if (!session) throw Object.assign(new Error('zcode approval for an unknown session'), { status: 404 });
-      return await waitForApproval(session, method, params || {});
-    }
-    // Official MCP plugin auth (image_search & friends) and user-input
-    // interactions have no terminal surface yet: rejecting them is verified
-    // harmless (the session continues; affected tools report a failure).
-    throw Object.assign(new Error(`zcode app-server request ${method} is not supported`), { status: 501 });
-  }
-
-  function waitForApproval(session, method, params) {
-    const choices = Array.isArray(params.options) ? params.options.filter(Boolean) : [];
-    const allowChoice = choices.find(choice => choice.kind === 'allow_once' || choice.kind === 'allow_always');
-    const denyChoice = choices.find(choice => choice.kind === 'deny');
-    const described = describeApproval(params);
-    return new Promise(resolve => {
-      const requestId = params.requestId || `zcode-perm-${nextPermissionId++}`;
-      session.pendingApproval = {
-        requestId,
-        allowResponse: allowChoice && allowChoice.response || { decision: 'allow', reason: 'Approved by the terminal user' },
-        denyResponse: denyChoice && denyChoice.response || { decision: 'deny', reason: 'Denied' },
-        resolve,
-      };
-      session.pendingPermission = {
-        requestId,
-        status: 'pending',
-        createdAt: new Date().toISOString(),
-        summary: described.summary,
-      };
-      setState(session, 'tool-running');
-      emit(session, { type: 'claude/permission-request', requestId, ...described, status: 'pending', createdAt: session.pendingPermission.createdAt });
-    });
-  }
-
-  function describeApproval(params) {
-    const input = params.input && typeof params.input === 'object' ? params.input : {};
-    const commandText = String(input.command || input.path || input.file || '');
-    const toolName = String(params.toolName || (/file|edit|patch/i.test(commandText) ? 'Edit' : 'Bash'));
-    const title = toolName === 'Edit' ? 'ZCode wants to modify files' : 'ZCode wants to run a command';
-    return {
-      toolName,
-      title,
-      description: commandText.slice(0, 200) || String(params.reason || 'tool approval').slice(0, 200),
-      promptPreview: JSON.stringify({ toolName, command: commandText, riskLevel: params.riskLevel || '' }).slice(0, 500),
-      summary: {
-        toolName,
-        title,
-        description: commandText.slice(0, 200) || String(params.reason || '').slice(0, 200),
-        promptPreview: commandText.slice(0, 500),
-      },
-    };
-  }
-
-  function denyPendingApproval(session, reason) {
-    if (!session.pendingApproval) return;
-    const approval = session.pendingApproval;
-    session.pendingApproval = null;
-    session.pendingPermission = null;
-    emit(session, {
-      type: 'claude/permission-resolved',
-      requestId: approval.requestId,
-      allow: false,
-      decision: approval.denyResponse && approval.denyResponse.decision,
-      message: reason,
-      resolvedAt: new Date().toISOString(),
-    });
-    approval.resolve(approval.denyResponse);
-  }
-
-  // -- model runtime ----------------------------------------------------------
-
-  // Profile-injected providers become inline runtimeModel configs; agent-owned
-  // auth bridges the desktop's own provider store so a logged-in ZCode desktop
-  // works with zero terminal-side configuration. Returns null when the
-  // app-server should use its own ~/.zcode/cli/config.json. The desktop store
-  // is never read under the test runner without an explicit zcodeHome, so
-  // injected-double tests stay machine-independent.
-  function runtimeModelFor(profile) {
-    if (profile && profile.apiKey) return injectedRuntimeModel(profile);
-    if (desktopProviderCache === undefined) {
-      desktopProviderCache = options.zcodeHome || !process.env.NODE_TEST_CONTEXT
-        ? readDesktopRuntimeModel(cli, options)
-        : null;
-    }
-    return desktopProviderCache;
-  }
-
-  // Driver session ids must never collide with persisted records from a
-  // previous process: a collision would shadow a restartable session behind
-  // an empty one.
-  function nextDriverSessionId() {
-    const taken = new Set(sessions.keys());
-    const index = syncDiskIndex();
-    if (index) for (const id of index.keys()) taken.add(id);
-    let id = `zcode-${nextId++}`;
-    while (taken.has(id)) id = `zcode-${nextId++}`;
-    return id;
-  }
-
-  return runner;
-}
-
-// ---------------------------------------------------------------------------
-// module helpers
-// ---------------------------------------------------------------------------
-
-function modelForProfile(profile) {
-  if (!profile) return null;
-  const model = resolveOpenAIModel(profile);
-  return model ? String(model) : null;
-}
-
-function runtimeModelRevision(spec) {
-  return `wb-${crypto.createHash('sha1').update(JSON.stringify(spec)).digest('hex').slice(0, 16)}`;
-}
-
-// Workbench profile -> ZCode runtimeModel. Anthropic-compatible base URLs
-// (the profile default) map to the anthropic provider kind; everything else
-// falls back to the resolved OpenAI-compatible endpoint.
-function injectedRuntimeModel(profile) {
-  const anthropicBase = String(profile.baseUrl || '').trim();
-  const openaiBase = resolveOpenAIBaseUrl(profile);
-  const useAnthropic = Boolean(anthropicBase) && profile.protocol !== 'openai-compatible';
-  if (!useAnthropic && !openaiBase) {
-    throw new Error('the selected provider needs a base URL for ZCode');
-  }
-  const modelId = resolveOpenAIModel(profile) || 'default';
-  const providerId = 'agent-terminal';
-  const spec = {
-    providerId, modelId,
-    kind: useAnthropic ? 'anthropic' : 'openai-compatible',
-    baseURL: useAnthropic ? anthropicBase : openaiBase,
-    apiKey: profile.apiKey,
-  };
-  return {
-    revision: runtimeModelRevision(spec),
-    generatedAt: Date.now(),
-    model: { providerId, modelId },
-    provider: {
-      providerId,
-      kind: spec.kind,
-      label: 'Agent Terminal',
-      source: 'ephemeral',
-      baseURL: spec.baseURL,
-      apiKey: { source: 'inline', value: spec.apiKey },
-      models: [{
-        modelId,
-        ...(Number(profile.contextWindow) > 0 ? { contextWindow: profile.contextWindow } : {}),
-        supportsTools: true,
-      }],
-    },
-  };
-}
-
-// Agent-owned auth: mirror what the ZCode desktop itself does — its provider
-// selection lives in ~/.zcode/v2/config.json (keyed like "builtin:bigmodel"),
-// and model catalogs ship beside the CLI in resources/model-providers. Any
-// read/parse failure degrades to null (the app-server then applies its own
-// config or reports an actionable model_config_missing error).
-function readDesktopRuntimeModel(cli, options) {
-  try {
-    const home = options.zcodeHome || path.join(os.homedir(), '.zcode');
-    const configPath = path.join(home, 'v2', 'config.json');
-    if (!fs.existsSync(configPath)) return null;
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    const providers = config && config.provider && typeof config.provider === 'object' ? config.provider : {};
-    let chosen = null;
-    let chosenScore = -1;
-    for (const [key, value] of Object.entries(providers)) {
-      if (!value || typeof value !== 'object') continue;
-      if (value.enabled === false || value.enabled === 'false') continue;
-      const options2 = value.options && typeof value.options === 'object' ? value.options : {};
-      if (!options2.apiKey || !options2.baseURL) continue;
-      const providerId = String(key).split(':').pop() || key;
-      let score = 1;
-      if (/coding-plan/i.test(providerId)) score += 2;
-      if (/bigmodel|zai|glm/i.test(providerId)) score += 1;
-      if (score > chosenScore) { chosenScore = score; chosen = { providerId, value, options: options2 }; }
-    }
-    if (!chosen) return null;
-    const modelId = desktopDefaultModel(cli, chosen.providerId, chosen.value);
-    if (!modelId) return null;
-    const spec = { providerId: chosen.providerId, modelId, baseURL: chosen.options.baseURL };
-    return {
-      revision: runtimeModelRevision(spec),
-      generatedAt: Date.now(),
-      model: { providerId: chosen.providerId, modelId },
-      provider: {
-        providerId: chosen.providerId,
-        kind: chosen.value.kind === 'openai' || chosen.value.kind === 'openai-compatible' ? chosen.value.kind : 'anthropic',
-        label: String(chosen.value.name || chosen.providerId).slice(0, 100),
-        source: 'ephemeral',
-        baseURL: chosen.options.baseURL,
-        apiKey: { source: 'inline', value: String(chosen.options.apiKey) },
-        models: [{ modelId }],
-      },
-    };
-  } catch {
-    return null;
-  }
-}
-
-// Model catalog lookup: resources/model-providers/*.json next to the CLI
-// bundle; falls back to the provider's own models list, then 'glm-4.7'.
-function desktopDefaultModel(cli, providerId, providerValue) {
-  try {
-    if (Array.isArray(providerValue.models) && providerValue.models.length) {
-      const first = providerValue.models[0];
-      return String(first.modelId || first.id || first).slice(0, 128);
-    }
-    const catalogDir = path.resolve(cli.path, '..', '..', 'model-providers');
-    for (const name of fs.readdirSync(catalogDir).filter(item => item.endsWith('.json')).sort().reverse()) {
-      const catalog = JSON.parse(fs.readFileSync(path.join(catalogDir, name), 'utf8'));
-      const entry = Array.isArray(catalog && catalog.providers)
-        && catalog.providers.find(item => item && (item.id === providerId || item.id === `builtin:${providerId}`));
-      const models = entry && Array.isArray(entry.models) ? entry.models : [];
-      const model = models.find(item => item && item.default) || models[0];
-      if (model && (model.id || model.modelId)) return String(model.id || model.modelId).slice(0, 128);
-    }
-  } catch { /* catalog is best-effort */ }
-  return 'glm-4.7';
-}
-
-// Tool results arrive as { success, content, display } where content may be a
-// string or an array of parts; normalize to displayable text.
-function toolResultText(result) {
-  if (result == null) return '';
-  if (typeof result.display === 'string' && result.display) return result.display;
-  const content = result.content;
-  if (typeof content === 'string') return content;
-  if (Array.isArray(content)) {
-    return content.map(part => {
-      if (typeof part === 'string') return part;
-      if (part && typeof part.text === 'string') return part.text;
-      return '';
-    }).filter(Boolean).join('\n');
-  }
-  if (result.success === false && result.error) return String(result.error);
-  return '';
-}
-
-function safeFileStem(value) {
-  return String(value).replace(/[^A-Za-z0-9._-]/g, '_');
-}
-
-// Mirrors the CLI runners' resolution: explicit config always wins; otherwise
-// persistence is suppressed under the node:test runner so test runs never
-// touch the real session store. An injected app-server spawn doubles the
-// app-server child only and does NOT suppress persistence.
-function resolvePersistence(options) {
-  const configured = options.persistence && typeof options.persistence === 'object' ? options.persistence : {};
-  const explicitlyConfigured = options.persistence != null;
-  const ephemeralTestContext = Boolean(process.env.NODE_TEST_CONTEXT);
-  const enabled = options.persistence !== null
-    && configured.enabled !== false
-    && (explicitlyConfigured || !ephemeralTestContext);
-  const dir = path.resolve(configured.dir || path.join(os.homedir(), '.agent-terminal', 'cli-sessions'));
-  return { enabled, dir };
-}
-
-module.exports = {
-  createZCodeDriver,
-  discoverZCodeCli,
-  probeZCodeVersion,
-  providerRuntimeEnvironment,
-  runtimeModelForProfile: injectedRuntimeModel,
-  toolResultText,
-  MODE_FOR_PERMISSION,
-  APP_SERVER_PERSIST_SCHEMA,
-};
+'use strict';
+
+const fs = require('fs');
+const { writeJson } = require('../json-file');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const { createAppServerBridge } = require('../bridges/app-server-bridge');
+const {
+  appendTextAttachments, normalizeAttachments, resolveOpenAIBaseUrl, resolveOpenAIModel,
+} = require('../../../contracts');
+const { stampEvent, resequenceRestoredEvents } = require('../event-stream');
+
+// ZCode driver — speaks the "ZCode Protocol" app-server bundled with the
+// ZCode desktop install (`resources/glm/zcode.cjs`, `app-server --stdio`).
+// Protocol verified live against zcode CLI 0.16.5 / desktop 3.11.2:
+//
+//   - Line-delimited JSON-RPC over stdio WITHOUT the `jsonrpc` envelope field
+//     (the same dialect as `codex app-server`, so the shared app-server bridge
+//     drives it as-is). Server-initiated request ids are strings ("server-N").
+//   - No initialize handshake. The first request is usually `session/create`:
+//       { workspace: { workspacePath, workspaceKey }, mode, runtimeModel? }
+//     and it BLOCKS on a server-initiated `session/requestRuntimePreferences`
+//     request that must be answered before the create response arrives.
+//   - Sessions, not threads: `session/create` -> `session/resume` ->
+//     `session/subscribe` { deliveryKind: 'desktop-continuous' } ->
+//     `session/send` { content } -> `session/stop` to abort. Turn lifecycle
+//     and token deltas ride `session/event` notifications (types: turn.started,
+//     model.streaming, tool.updated, permission.requested/resolved,
+//     turn.completed, session.updated, session.titleUpdated, ...).
+//   - Approvals are server-initiated `interaction/requestPermission` requests
+//     whose params carry an `options[]` array; the response must echo one of
+//     `options[].response` (allow_once / allow_project / deny).
+//   - Models come from `runtimeModel` on create/resume/send (provider kind
+//     anthropic | openai | openai-compatible, inline api keys supported).
+//     Without one the app-server requires ~/.zcode/cli/config.json to define a
+//     provider; agent-owned turns bridge the desktop's ~/.zcode/v2/config.json
+//     providers instead (see desktopRuntimeModelFor).
+//
+// The driver deliberately has NO CLI one-shot fallback: the bundled CLI's
+// headless `--prompt` mode has no verified JSON event stream, so an unusable
+// app-server surfaces honest errors instead of a fake fallback transport.
+
+const ACTIVE_STATES = new Set(['running', 'thinking', 'tool-running']);
+// Workbench permission modes -> ZCode session modes
+// (default/plan/acceptEdits/bypassPermissions -> build/plan/edit/yolo).
+const MODE_FOR_PERMISSION = {
+  default: 'build',
+  plan: 'plan',
+  acceptEdits: 'edit',
+  bypassPermissions: 'yolo',
+};
+
+const RUNTIME_PREFERENCES = Object.freeze({
+  nativeSearchEnhancementsEnabled: false,
+  memoryEnabled: false,
+  askUserQuestionAutoResolutionEnabled: false,
+  modelContextBudgetStrategy: 'preflight-v1',
+});
+
+const APP_SERVER_PERSIST_SCHEMA = 'zcode-appserver-session/v1';
+const MAX_PERSISTED_EVENTS = 5000;
+
+// ---------------------------------------------------------------------------
+// CLI discovery
+// ---------------------------------------------------------------------------
+
+function defaultRegQuery(key) {
+  try {
+    const result = spawnSync('reg', ['query', key], { windowsHide: true, encoding: 'utf8', timeout: 5000 });
+    if (result.error || result.status !== 0) return null;
+    return String(result.stdout || '');
+  } catch {
+    return null;
+  }
+}
+
+function safeExists(target) {
+  try { return fs.existsSync(target); } catch { return false; }
+}
+
+function safeReaddir(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; }
+}
+
+function providerRuntimeEnvironment(cliPath, { env = process.env, homedir = os.homedir(), existsSync = safeExists } = {}) {
+  const output = {};
+  if (!env.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE?.trim()) {
+    // Desktop bundles keep config beside glm, not inside it. Recent native
+    // CLIs otherwise resolve a development-tree fallback outside the install.
+    const dir = path.dirname(path.resolve(cliPath));
+    const bundled = [path.join(dir, 'provider/zcode-builtin.json'), path.resolve(dir, '../config/provider/zcode-builtin.json')].find(existsSync);
+    if (!bundled) return output;
+    output.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE = bundled;
+  }
+  if (!env.ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim()) output.ZCODE_PERSONAL_PROVIDER_CONFIG_FILE = path.join(env.ZCODE_DATA_BASE_DIR?.trim() || homedir, '.zcode/v2/provider_config.json');
+  return output;
+}
+
+// Discovery chain for the bundled zcode CLI:
+//   1. ZCODE_CLI_PATH env override (the .cjs itself or the install root);
+//   2. common Windows install roots (%LOCALAPPDATA%\Programs, Program Files,
+//      Program Files (x86) on every configured drive) scanning for
+//      <root>/*[Zz][Cc]ode*/resources/glm/zcode.cjs;
+//   3. registry App Paths (HKCU/HKLM ZCode.exe) via `reg query`;
+//   4. ~/.zcode neighbors (last resort).
+// Purely filesystem-based (no subprocess) so driver construction stays cheap;
+// everything is injectable for tests (env/existsSync/readdirSync/regQuery).
+function discoverZCodeCli(options = {}) {
+  const env = options.env || process.env;
+  const exists = options.existsSync || safeExists;
+  const readdir = options.readdirSync || safeReaddir;
+  const regQuery = options.regQuery || defaultRegQuery;
+  const home = options.homedir || os.homedir();
+
+  const candidates = [];
+  const envPath = String(env.ZCODE_CLI_PATH || '').trim();
+  if (envPath) {
+    candidates.push(envPath, path.join(envPath, 'resources', 'glm', 'zcode.cjs'));
+  }
+  const rootExprs = [
+    env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, 'Programs'),
+    env.ProgramFiles,
+    env['ProgramFiles(x86)'],
+    'C:\\Program Files',
+    'C:\\Program Files (x86)',
+    'D:\\Program Files',
+    'D:\\Program Files (x86)',
+  ].filter(Boolean);
+  for (const root of rootExprs) {
+    candidates.push(path.join(root, 'ZCode', 'resources', 'glm', 'zcode.cjs'));
+    for (const name of readdir(root)) {
+      if (/^zcode/i.test(name) || /zcode$/i.test(name)) {
+        candidates.push(path.join(root, name, 'resources', 'glm', 'zcode.cjs'));
+      }
+    }
+  }
+  // macOS desktop layout (cheap extra candidate, harmless elsewhere).
+  candidates.push('/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs');
+  // Registry App Paths: the desktop registers ZCode.exe there on install.
+  for (const hive of ['HKCU', 'HKLM']) {
+    const output = regQuery(`${hive}\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\ZCode.exe`);
+    const match = output && output.match(/REG_SZ\s+(\S*ZCode\.exe)/i);
+    if (match) candidates.push(path.join(path.dirname(match[1]), 'resources', 'glm', 'zcode.cjs'));
+  }
+  candidates.push(
+    path.join(home, '.zcode', 'cli', 'zcode.cjs'),
+    path.join(home, '.zcode', 'zcode.cjs'),
+  );
+
+  const seen = new Set();
+  for (const candidate of candidates) {
+    if (!candidate || seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (exists(candidate)) return { path: candidate, source: 'discovered' };
+  }
+  return null;
+}
+
+// Version probe for /agents: spawns `node <zcode.cjs> --version`. Skipped under
+// the node:test runner so unit/integration suites never spawn a real 12MB CLI
+// bundle; production gets a real version string (cached by agent-discovery).
+function probeZCodeVersion(cliPath) {
+  if (process.env.NODE_TEST_CONTEXT) return null;
+  try {
+    const result = spawnSync(process.execPath, [cliPath, '--version'], {
+      timeout: 10000, windowsHide: true, encoding: 'utf8',
+    });
+    if (result.error || result.status !== 0) return null;
+    const match = String(result.stdout || result.stderr || '').match(/(\d+\.\d+[\w.-]*)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Driver factory
+// ---------------------------------------------------------------------------
+
+function createZCodeDriver(options = {}) {
+  const injected = Boolean(options.appServerSpawn);
+  // Under the node:test runner an un-injected driver must stay a deterministic
+  // 501 placeholder (agent-drivers.test.js): discovery on a dev machine with
+  // ZCode installed would otherwise spawn real app-server children in tests.
+  const testContext = Boolean(process.env.NODE_TEST_CONTEXT);
+  let cli = null;
+  if (injected) {
+    cli = { path: options.cliPath || '<injected app-server>', source: 'injected' };
+  } else if (!testContext) {
+    cli = options.cli || discoverZCodeCli({ env: options.env });
+  }
+  if (!cli) {
+    const reason = testContext
+      ? 'ZCode app-server transport is not scripted in this test context; inject an appServerSpawn double to drive it'
+      : 'ZCode desktop was not found on this machine. Install the ZCode desktop app (it bundles the zcode CLI used by the app-server transport), or set ZCODE_CLI_PATH to the installed resources/glm/zcode.cjs';
+    return createUnavailableZCodeDriver(reason);
+  }
+  return createAppServerZCodeDriver(options, cli);
+}
+
+// Honest 501 shell (the pre-driver behavior, kept for missing installs and
+// unscripted test contexts).
+function createUnavailableZCodeDriver(reason) {
+  return {
+    agentId: 'zcode',
+    unavailableReason: reason,
+    startChatSession() {
+      throw Object.assign(new Error(this.unavailableReason), { status: 501 });
+    },
+    listSessions() { return []; },
+    getState() { return null; },
+    getSession() { return null; },
+    getSessionTokenUsage() { return { used: 0, hasUsage: false }; },
+    subscribe() { throw Object.assign(new Error('session not found'), { status: 404 }); },
+    async sendInput() { throw Object.assign(new Error(this.unavailableReason), { status: 501 }); },
+    resolvePermission() { throw Object.assign(new Error(this.unavailableReason), { status: 501 }); },
+    abort() {},
+    deleteSession() { return false; },
+    async listSupportedCommands() { return []; },
+    findClaudeExecutableForSdk() { return null; },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// app-server transport
+// ---------------------------------------------------------------------------
+
+function createAppServerZCodeDriver(options, cli) {
+  const log = typeof options.log === 'function' ? options.log : () => {};
+  const sessions = new Map();
+  const zcodeSessions = new Map(); // zcode sessionId (sess_...) -> driver sessionId
+  const persist = resolvePersistence(options);
+  let diskIndex = null;
+  let nextId = 1;
+  let nextPermissionId = 1;
+  let bridge = null;
+  let protocolMode = null;
+  let profileRuntime = null;
+  let profileRuntimeSignature = null;
+  let bridgeSetup = Promise.resolve();
+  let destroyed = false;
+  let desktopProviderCache; // lazily-read ~/.zcode/v2 providers (agent-owned auth)
+
+  function summary(session) {
+    return {
+      sessionId: session.sessionId,
+      projectSlug: session.projectSlug,
+      state: session.state,
+      model: session.model,
+      selectedModel: session.selectedModel,
+      aiProfileId: session.aiProfileId,
+      permissionMode: session.permissionMode,
+      turns: session.turns,
+      startedAt: session.startedAt,
+      // Live activity marker: turn end refreshes it (see turns += 1 site).
+      updatedAt: session.updatedAt || session.startedAt,
+      endedAt: session.endedAt,
+      pendingPermission: session.pendingPermission,
+    };
+  }
+
+  function emit(session, event) {
+    stampEvent(session, event);
+    session.outputBuffer.push(event);
+    if (session.outputBuffer.length > MAX_PERSISTED_EVENTS) session.outputBuffer.shift();
+    for (const listener of session.listeners) {
+      try { listener(event); } catch { /* listener errors never break the turn */ }
+    }
+  }
+
+  function setState(session, state) {
+    session.state = state;
+    emit(session, { type: 'claude/state', state, turn: session.turns });
+  }
+
+  // ---- persistence (records share ~/.agent-terminal/cli-sessions with the
+  // other CLI drivers but carry their own schema; only this driver claims
+  // them). The zcode session id (sess_...) is stored as threadId so a restart
+  // resumes the server-side conversation instead of starting a new one. ----
+
+  function recordFile(sessionId) {
+    return path.join(persist.dir, `${safeFileStem(sessionId)}.json`);
+  }
+
+  function readRecord(file) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (parsed && parsed.schema === APP_SERVER_PERSIST_SCHEMA && parsed.agentId === 'zcode'
+        && parsed.transport === 'app-server' && typeof parsed.sessionId === 'string' && parsed.sessionId) return parsed;
+    } catch { /* corrupt or foreign records are skipped, never fatal */ }
+    return null;
+  }
+
+  function syncDiskIndex() {
+    if (!persist.enabled) return null;
+    if (!diskIndex) diskIndex = new Map();
+    else diskIndex.clear();
+    let names = [];
+    try { names = fs.readdirSync(persist.dir).filter(name => name.endsWith('.json')); } catch { return diskIndex; }
+    for (const name of names) {
+      const file = path.join(persist.dir, name);
+      const record = readRecord(file);
+      if (record) diskIndex.set(record.sessionId, { file, summary: persistedSummary(record) });
+    }
+    return diskIndex;
+  }
+
+  function persistedSummary(record) {
+    return {
+      sessionId: record.sessionId,
+      projectSlug: record.projectSlug,
+      state: 'idle', // a restart killed any live turn
+      model: record.model || null,
+      selectedModel: record.selectedModel || null,
+      aiProfileId: record.aiProfileId || null,
+      permissionMode: record.permissionMode || 'default',
+      turns: Number(record.turns) || 0,
+      startedAt: record.startedAt || '',
+      updatedAt: record.updatedAt || record.startedAt || '',
+      endedAt: record.endedAt || null,
+      pendingPermission: null,
+    };
+  }
+
+  function persistSession(session) {
+    if (!persist.enabled) return;
+    try {
+      const file = recordFile(session.sessionId);
+      writeJson(file, {
+        schema: APP_SERVER_PERSIST_SCHEMA,
+        agentId: 'zcode',
+        transport: 'app-server',
+        sessionId: session.sessionId,
+        projectSlug: session.projectSlug,
+        projectPath: session.projectPath,
+        state: session.state,
+        model: session.model,
+        selectedModel: session.selectedModel,
+        aiProfileId: session.aiProfileId,
+        permissionMode: session.permissionMode,
+        title: session.title || null,
+        turns: session.turns,
+        startedAt: session.startedAt,
+        endedAt: session.endedAt,
+        // The ZCode Protocol session id: session/resume needs it after a restart.
+        threadId: session.zcodeSessionId || null,
+        lastResult: session.lastResult || '',
+        usage: { ...session.usage },
+        peakTurnTokens: session.peakTurnTokens || 0,
+      eventSequence: Number(session.eventSequence) || 0,
+        // Old numeric cursors predate this session's numbering era; the
+        // boundary must survive restarts, not just the first restore.
+        legacySequenceReset: session.legacySequenceReset === true,
+        events: session.outputBuffer.slice(-MAX_PERSISTED_EVENTS),
+        updatedAt: new Date().toISOString(),
+      });
+      if (diskIndex) diskIndex.set(session.sessionId, { file: recordFile(session.sessionId), summary: summary(session) });
+    } catch {
+      // Read-only home or full disk degrades to memory-only behavior.
+      persist.enabled = false;
+      diskIndex = null;
+    }
+  }
+
+  function removeRecord(sessionId) {
+    if (diskIndex) diskIndex.delete(sessionId);
+    if (!persist.enabled) return;
+    try {
+      const file = recordFile(sessionId);
+      if (fs.existsSync(file) && readRecord(file)) fs.rmSync(file, { force: true });
+    } catch { /* already gone */ }
+  }
+
+  function restoreSession(id) {
+    if (!persist.enabled) return null;
+    const index = syncDiskIndex();
+    const entry = index && index.get(id);
+    if (!entry) return null;
+    const record = readRecord(entry.file);
+    if (!record || record.sessionId !== id) { index.delete(id); return null; }
+    // Legacy records (written before stable event identity) carry unstamped
+    // events: renumber the retained tail explicitly and continue from there.
+    const restored = resequenceRestoredEvents(
+      Array.isArray(record.events) ? record.events.slice(-MAX_PERSISTED_EVENTS) : [],
+      record.eventSequence,
+    );
+    const session = {
+      sessionId: record.sessionId,
+      projectSlug: record.projectSlug,
+      projectPath: record.projectPath,
+      state: 'idle',
+      model: record.model || null,
+      selectedModel: record.selectedModel || null,
+      aiProfileId: record.aiProfileId || null,
+      permissionMode: record.permissionMode || 'default',
+      effort: null,
+      title: record.title || null,
+      turns: Number(record.turns) || 0,
+      startedAt: record.startedAt || new Date().toISOString(),
+      updatedAt: record.updatedAt || record.startedAt || new Date().toISOString(),
+      endedAt: record.endedAt || null,
+      pendingPermission: null,
+      pendingApproval: null,
+      outputBuffer: restored.events,
+      eventSequence: restored.eventSequence,
+      legacySequenceReset: restored.legacyRenumbered === true || record.legacySequenceReset === true,
+      listeners: new Set(),
+      zcodeSessionId: record.threadId || null,
+      currentTurn: null,
+      lastResult: record.lastResult || '',
+      lastDiag: '',
+      usage: {
+        inputTokens: Number(record.usage && record.usage.inputTokens) || 0,
+        outputTokens: Number(record.usage && record.usage.outputTokens) || 0,
+        cachedTokens: Number(record.usage && record.usage.cachedTokens) || 0,
+      },
+      peakTurnTokens: Number(record.peakTurnTokens) || 0,
+      turnTokenUsage: null,
+      turnPromise: Promise.resolve(),
+    };
+    sessions.set(id, session);
+    return session;
+  }
+
+  const runner = {
+    agentId: 'zcode',
+
+    startChatSession({ slug, projectPath, aiProfile, permissionMode, effort, title }) {
+      if (!slug) throw new Error('slug required');
+      if (!projectPath) throw new Error('projectPath required');
+      const sessionId = nextDriverSessionId();
+      const session = {
+        sessionId,
+        projectSlug: slug,
+        projectPath,
+        state: 'idle',
+        model: modelForProfile(aiProfile),
+        selectedModel: aiProfile && (aiProfile.mainModel || aiProfile.models && aiProfile.models.default) || '',
+        aiProfileId: aiProfile && aiProfile.id,
+        permissionMode: permissionMode || 'default',
+        effort: effort || null,
+        title: title || null,
+        turns: 0,
+        startedAt: new Date().toISOString(),
+        endedAt: null,
+        pendingPermission: null,
+        pendingApproval: null,
+        outputBuffer: [],
+        eventSequence: 0,
+        listeners: new Set(),
+        zcodeSessionId: null,
+        currentTurn: null,
+        lastResult: '',
+        lastDiag: '',
+        usage: { inputTokens: 0, outputTokens: 0, cachedTokens: 0 },
+        peakTurnTokens: 0,
+        turnTokenUsage: null,
+        turnPromise: Promise.resolve(),
+      };
+      sessions.set(sessionId, session);
+      emit(session, {
+        type: 'claude/session-ready',
+        model: session.model,
+        aiProfileId: session.aiProfileId,
+        permissionMode: session.permissionMode,
+        message: 'zcode session is ready. Send a message to start the first turn.',
+      });
+      // Write the record immediately so a session with no turns yet still
+      // shows up in the sidebar after a restart.
+      persistSession(session);
+      return { sessionId };
+    },
+
+    listSessions(filter = {}) {
+      const byId = new Map();
+      const index = syncDiskIndex();
+      if (index) {
+        for (const entry of index.values()) {
+          if (filter.projectSlug && entry.summary.projectSlug !== filter.projectSlug) continue;
+          byId.set(entry.summary.sessionId, entry.summary);
+        }
+      }
+      for (const session of sessions.values()) {
+        if (filter.projectSlug && session.projectSlug !== filter.projectSlug) continue;
+        byId.set(session.sessionId, summary(session));
+      }
+      return [...byId.values()];
+    },
+
+    getState(id) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) return null;
+      return {
+        ...summary(session),
+        listenerCount: session.listeners.size,
+        bufferedEvents: session.outputBuffer.length,
+      };
+    },
+
+    getSession(id) { return sessions.get(id) || restoreSession(id); },
+
+    getSessionTokenUsage(id) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) return { used: 0, hasUsage: false };
+      const { inputTokens, outputTokens } = session.usage;
+      const used = session.peakTurnTokens || 0;
+      return {
+        used,
+        inputTokens,
+        outputTokens,
+        hasUsage: Boolean(used || inputTokens || outputTokens),
+      };
+    },
+
+    subscribe(id, listener) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
+      for (const event of session.outputBuffer) listener(event);
+      session.listeners.add(listener);
+      return () => session.listeners.delete(listener);
+    },
+
+    async sendInput(id, text, profile, sendOptions = {}) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
+      if (ACTIVE_STATES.has(session.state)) {
+        throw Object.assign(new Error('session already has an active turn'), { status: 409 });
+      }
+      const value = String(text || '').trim();
+      const attachments = normalizeAttachments(sendOptions.attachments || []);
+      if (!value && !attachments.length) throw Object.assign(new Error('text or attachments are required'), { status: 400 });
+      if (profile) {
+        session.model = modelForProfile(profile);
+        session.selectedModel = profile.mainModel || profile.models && profile.models.default || '';
+      }
+      if (sendOptions.permissionMode) session.permissionMode = sendOptions.permissionMode;
+      session.lastPromptText = value;
+
+      let runtimeModel = null;
+      try {
+        // Invalid injected profiles (no base URL) throw here and surface as a
+        // turn error, mirroring the codex driver's bridgeSpecFor contract.
+        runtimeModel = runtimeModelFor(profile);
+        session.preparing = true;
+        session.runtimeSignature = profile?.apiKey ? runtimeModel.revision : 'agent-owned';
+        await ensureBridge(profile, session);
+        await ensureZcodeSession(session, runtimeModel);
+      } catch (error) {
+        emit(session, { type: 'claude/error', message: `zcode app-server unavailable: ${error.message}`.slice(0, 500) });
+        setState(session, 'idle');
+        return { started: false };
+      } finally { session.preparing = false; }
+
+      emit(session, {
+        type: 'claude/user-prompt',
+        text: value,
+        attachments: (sendOptions.displayAttachments || []).map(({ id: attachmentId, name, mediaType, size, width, height, url }) => ({ id: attachmentId, name, mediaType, size, width, height, url })),
+      });
+      setState(session, 'running');
+      // Until the first session/event lands the UI would show dead air
+      // (reasoning models think for tens of seconds first) — announce it.
+      setState(session, 'thinking');
+      try {
+        // Image attachments have no verified ZCode Protocol wire shape yet
+        // (session/send attachments are an opaque record); text attachments
+        // ride the prompt text, images are refused with an honest notice.
+        const images = attachments.filter(item => item.mediaType.startsWith('image/'));
+        if (images.length) {
+          emitDiag(session, { type: 'claude/stderr', text: 'the zcode app-server driver does not support image attachments yet' });
+        }
+        session.currentTurn = {
+          turnId: null,
+          announcedText: new Set(),
+          streamedText: new Set(),
+          announcedThinking: new Set(),
+          streamedThinking: new Set(),
+          sawEvent: false,
+        };
+        session.turnPromise = new Promise(resolve => { session.currentTurn.resolve = resolve; });
+        await bridge.request('session/send', {
+          sessionId: session.zcodeSessionId,
+          content: appendTextAttachments(value, attachments) + (sendOptions.parentContext || '') + (sendOptions.knowledgeContext || ''),
+          ...(protocolMode === 'selection' ? (session.nativeModel ? { modelSelection: session.nativeModel } : {}) : runtimeModel ? { runtimeModel } : {}),
+        }, { timeoutMs: 30000 });
+        return { started: true };
+      } catch (error) {
+        finishTurn(session, { resultType: 'error', response: '' }, `zcode turn failed to start: ${error.message}`);
+        return { started: false };
+      }
+    },
+
+    resolvePermission(id, requestId, decision) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session || !session.pendingApproval || session.pendingApproval.requestId !== requestId) {
+        throw Object.assign(new Error('permission request not found or already resolved'), { status: 409 });
+      }
+      const allow = decision && decision.allow === true;
+      const approval = session.pendingApproval;
+      session.pendingApproval = null;
+      session.pendingPermission = null;
+      const response = allow ? approval.allowResponse : approval.denyResponse;
+      emit(session, {
+        type: 'claude/permission-resolved',
+        requestId,
+        allow,
+        decision: response && response.decision,
+        resolvedAt: new Date().toISOString(),
+      });
+      setState(session, 'running');
+      approval.resolve(response);
+      return { ok: true, started: true, decision: response && response.decision };
+    },
+
+    updateSelection(id, profile, selectedModel) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
+      if (ACTIVE_STATES.has(session.state)) {
+        throw Object.assign(new Error('session already has an active turn'), { status: 409 });
+      }
+      const fromAiProfileId = session.aiProfileId || null;
+      const fromModel = session.selectedModel || session.model || null;
+      session.aiProfileId = profile && profile.id || null;
+      session.selectedModel = selectedModel || (profile && (profile.mainModel || profile.models && profile.models.default)) || null;
+      session.model = modelForProfile(profile);
+      emit(session, {
+        type: 'claude/selection-changed',
+        fromAiProfileId,
+        toAiProfileId: session.aiProfileId,
+        fromModel,
+        toModel: session.selectedModel,
+      });
+      persistSession(session);
+      return summary(session);
+    },
+
+    abort(id, reason) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) return;
+      session.abortedByUser = true;
+      denyPendingApproval(session, 'aborted');
+      const currentTurn = session.currentTurn;
+      if (currentTurn && bridge && bridge.state === 'ready' && session.zcodeSessionId) {
+        // Ask the app-server to interrupt the live turn; a failure falls back
+        // to the local turn teardown below (the bridge recycles lazily).
+        bridge.request('session/stop', { sessionId: session.zcodeSessionId }, { timeoutMs: 5000 })
+          .catch(() => recycleBridge('session/stop failed'));
+      }
+      if (!['idle', 'ended'].includes(session.state)) {
+        session.state = 'aborted';
+        emit(session, { type: 'claude/aborted', reason: reason || 'user-abort' });
+        finishTurn(session, { resultType: 'cancelled', response: '' });
+      }
+      persistSession(session);
+    },
+
+    deleteSession(id) {
+      const session = sessions.get(id) || restoreSession(id);
+      if (!session) {
+        const index = syncDiskIndex();
+        if (index && index.has(id)) { removeRecord(id); return true; }
+        return false;
+      }
+      if (ACTIVE_STATES.has(session.state)) runner.abort(id);
+      denyPendingApproval(session, 'deleted');
+      if (session.zcodeSessionId) zcodeSessions.delete(session.zcodeSessionId);
+      const deleted = sessions.delete(id);
+      removeRecord(id);
+      return deleted;
+    },
+
+    async listSupportedCommands() { return []; },
+
+    findClaudeExecutableForSdk() { return null; },
+
+    async destroy() {
+      destroyed = true;
+      for (const session of sessions.values()) if (ACTIVE_STATES.has(session.state)) runner.abort(session.sessionId);
+      await bridge?.close(); bridge = null;
+      await bridgeSetup.catch(() => {});
+      await bridge?.close(); bridge = null;
+      await profileRuntime?.close(); profileRuntime = null;
+    },
+
+    // Test seams.
+    get transportMode() { return 'app-server'; },
+    get bridgeState() { return bridge ? bridge.state : 'uncreated'; },
+    get cliPath() { return cli.path; },
+  };
+
+  // -- bridge lifecycle ----------------------------------------------------
+
+  function ensureBridge(profile, session) {
+    const preparing = bridgeSetup.then(() => prepareBridge(profile, session));
+    bridgeSetup = preparing.catch(() => {});
+    return preparing;
+  }
+
+  async function prepareBridge(profile, session) {
+    if (destroyed) throw new Error('ZCode 工作台正在关闭。');
+    if (protocolMode === 'selection' && profileRuntimeSignature !== session.runtimeSignature) {
+      if ([...sessions.values()].some(other => other !== session && (other.preparing || ACTIVE_STATES.has(other.state)) && other.runtimeSignature !== session.runtimeSignature)) throw new Error('另一个 ZCode 任务正在使用不同的模型配置，请等待任务结束。');
+      if (profileRuntimeSignature !== null || profile?.apiKey) { await bridge?.close(); bridge = null; }
+      await profileRuntime?.close(); profileRuntime = null;
+      if (profile?.apiKey) profileRuntime = await require('./zcode-profile-runtime').createZCodeProfileRuntime(injectedRuntimeModel(profile));
+      profileRuntimeSignature = session.runtimeSignature;
+    }
+    if (destroyed) throw new Error('ZCode 工作台正在关闭。');
+    if (bridge && bridge.state === 'closed') { bridge = null; }
+    if (bridge && bridge.state === 'crashed') { recycleBridge('bridge exhausted its restart budget'); }
+    if (!bridge) {
+      bridge = createAppServerBridge({
+        // The bundled CLI is a node bundle: spawn it through the running node
+        // runtime with the app-server stdio subcommand.
+        command: options.nodePath || process.execPath,
+        args: [cli.path, 'app-server', '--stdio'],
+        env: { ...providerRuntimeEnvironment(cli.path, { env: options.env || process.env }), ...(profileRuntime ? { ZCODE_PERSONAL_PROVIDER_CONFIG_FILE: profileRuntime.file } : {}), ...(options.knowledgeContextProvided ? { KB_KNOWLEDGE_CONTEXT: '0' } : {}), ...(options.conversationCaptureProvided ? { AI_CODING_EVENT_BRIDGE_CAPTURE: '0' } : {}) },
+        spawn: options.appServerSpawn,
+        onEvent: handleNotification,
+        onServerRequest: handleServerRequest,
+        onUnexpectedExit: handleBridgeCrash,
+        idleTimeoutMs: options.idleTimeoutMs !== undefined ? options.idleTimeoutMs : 10 * 60 * 1000,
+        requestTimeoutMs: options.requestTimeoutMs !== undefined ? options.requestTimeoutMs : 120000,
+        restartBackoffMs: options.restartBackoffMs,
+        log,
+      });
+    }
+    await bridge.start();
+    if (protocolMode === null) {
+      try { const capabilities = await bridge.request('runtime/capabilities', {}, { timeoutMs: 10000 }); protocolMode = capabilities?.independentPlanState === true ? 'selection' : 'runtime-model'; }
+      catch (error) { if (error.rpcCode !== -32601) throw error; protocolMode = 'runtime-model'; }
+      if (protocolMode === 'selection') return prepareBridge(profile, session);
+    }
+  }
+
+  function recycleBridge(reason) {
+    log(`recycling zcode app-server bridge: ${reason}`);
+    if (bridge) bridge.close().catch(() => {});
+    bridge = null;
+    failoverSessions(`zcode app-server exited: ${reason}`);
+  }
+
+  // The app-server died mid-flight: turn.completed will never arrive, so
+  // every live turn is finished with an error here (the bridge restarts
+  // itself and the next turn retries with a fresh session/resume).
+  function handleBridgeCrash(error) {
+    failoverSessions(`zcode app-server exited unexpectedly: ${error && error.message || 'crashed'}`);
+  }
+
+  function failoverSessions(reason) {
+    for (const session of sessions.values()) {
+      denyPendingApproval(session, reason);
+      if (!session.currentTurn) continue;
+      finishTurn(session, { resultType: 'error', response: '' }, String(reason).slice(0, 500));
+    }
+  }
+
+  // -- zcode session lifecycle ----------------------------------------------
+
+  async function ensureZcodeSession(session, runtimeModel) {
+    if (session.zcodeSessionId) {
+      try {
+        const resumed = await bridge.request('session/resume', {
+          sessionId: session.zcodeSessionId,
+          ...(protocolMode !== 'selection' && runtimeModel ? { runtimeModel } : {}),
+        }, { timeoutMs: 30000 });
+        if (protocolMode === 'selection') { session.nativeModel = resumed.settings?.model?.current || session.nativeModel || null; await selectNativeModel(session); }
+        zcodeSessions.set(session.zcodeSessionId, session.sessionId);
+        await subscribeZcodeSession(session);
+        return;
+      } catch (error) {
+        // The app-server child restarted or rolled the session away; fall
+        // through to a fresh one (the client-side history stays).
+        zcodeSessions.delete(session.zcodeSessionId);
+        session.zcodeSessionId = null;
+        log(`zcode session resume failed, creating a new one: ${error.message}`);
+      }
+    }
+    const result = await bridge.request('session/create', {
+      workspace: { workspacePath: session.projectPath, workspaceKey: session.projectPath },
+      mode: MODE_FOR_PERMISSION[session.permissionMode] || 'build',
+      ...(protocolMode === 'selection' ? { titleGenerationEnabled: false } : runtimeModel ? { runtimeModel } : {}),
+    }, { timeoutMs: 60000 });
+    const zcodeId = result && result.session && (result.session.sessionId || result.session.id);
+    if (!zcodeId) throw new Error('zcode app-server did not return a session');
+    session.zcodeSessionId = zcodeId;
+    if (protocolMode === 'selection') { session.nativeModel = result.settings?.model?.current || null; await selectNativeModel(session); }
+    zcodeSessions.set(zcodeId, session.sessionId);
+    if (result.session && result.session.title && !session.title) session.title = result.session.title;
+    await subscribeZcodeSession(session);
+    persistSession(session);
+  }
+
+  async function selectNativeModel(session) {
+    if (profileRuntime) session.nativeModel = profileRuntime.selection;
+    else if (session.selectedModel) {
+      const slash = session.selectedModel.indexOf('/');
+      if (slash > 0) session.nativeModel = { providerId: session.selectedModel.slice(0, slash), modelId: session.selectedModel.slice(slash + 1), options: { reasoningLevel: 'enabled' } };
+      else if (session.nativeModel) session.nativeModel = { ...session.nativeModel, modelId: session.selectedModel };
+    }
+    await bridge.request('session/setMode', { sessionId: session.zcodeSessionId, mode: MODE_FOR_PERMISSION[session.permissionMode] || 'build' }, { timeoutMs: 10000 });
+  }
+
+  async function subscribeZcodeSession(session) {
+    await bridge.request('session/subscribe', {
+      sessionId: session.zcodeSessionId,
+      deliveryKind: 'desktop-continuous',
+    }, { timeoutMs: 30000 });
+  }
+
+  // -- notifications ---------------------------------------------------------
+
+  function handleNotification({ method, params }) {
+    if (!params) return;
+    const session = routeZcodeSession(params.sessionId);
+    if (!session) return; // notifications for unknown sessions are ignored
+    if (method === 'session/event') return onSessionEvent(session, params);
+    if (method === 'state.updated') {
+      // status patches (running/idle) only mark liveness here; turn completion
+      // is authoritative on the session/event stream.
+      markActivity(session);
+      return;
+    }
+    // computer-use/operation-event, v4/telemetry/event, process/*, ... are noise.
+  }
+
+  function routeZcodeSession(zcodeSessionId) {
+    if (!zcodeSessionId) return null;
+    const driverId = zcodeSessions.get(zcodeSessionId);
+    return driverId ? sessions.get(driverId) : null;
+  }
+
+  function markActivity(session) {
+    const turn = session.currentTurn;
+    if (!turn) return;
+    if (!turn.sawEvent) {
+      turn.sawEvent = true;
+      if (session.state === 'thinking') setState(session, 'running');
+    }
+  }
+
+  function onSessionEvent(session, params) {
+    markActivity(session);
+    const turn = session.currentTurn;
+    if (!turn) return; // events outside a driver-tracked turn (e.g. background) are ignored
+    const { type, payload } = params;
+    if (params.turnId && !turn.turnId) turn.turnId = params.turnId;
+    if (turn.turnId && params.turnId && params.turnId !== turn.turnId) return; // stale turn
+
+    switch (type) {
+      case 'turn.started': return; // announced locally at send time
+      case 'model.streaming': return onModelStreaming(session, payload || {});
+      case 'tool.updated': return onToolUpdated(session, payload || {});
+      case 'turn.completed': return finishTurn(session, payload || {});
+      case 'turn.failed': return finishTurn(session, { resultType: 'error', response: '' }, payload?.error?.message || payload?.error?.code || 'ZCode 任务失败');
+      case 'session.titleUpdated': {
+        if (payload && payload.title) session.title = String(payload.title).slice(0, 200);
+        return;
+      }
+      case 'permission.requested':
+      case 'permission.resolved':
+        return; // approvals are driven by the interaction/requestPermission RPC
+      default: return; // session.updated, checkpoint.*, streamRecovery.*, ...
+    }
+  }
+
+  function onModelStreaming(session, payload) {
+    const turn = session.currentTurn;
+    if (!turn) return;
+    const { kind } = payload;
+    const messageId = payload.assistantMessageId || `text-${session.turns}`;
+    if (kind === 'text_start') {
+      turn.announcedText.add(messageId);
+      emit(session, { type: 'claude/text-start', id: messageId });
+    } else if (kind === 'text_delta') {
+      if (!turn.announcedText.has(messageId)) {
+        turn.announcedText.add(messageId);
+        emit(session, { type: 'claude/text-start', id: messageId });
+      }
+      turn.streamedText.add(messageId);
+      emit(session, { type: 'claude/text-delta', id: messageId, text: String(payload.delta || '') });
+    } else if (kind === 'reasoning_start') {
+      turn.announcedThinking.add(messageId);
+      emit(session, { type: 'claude/thinking-start', id: messageId });
+    } else if (kind === 'reasoning_delta') {
+      if (!turn.announcedThinking.has(messageId)) {
+        turn.announcedThinking.add(messageId);
+        emit(session, { type: 'claude/thinking-start', id: messageId });
+      }
+      turn.streamedThinking.add(messageId);
+      emit(session, { type: 'claude/thinking-delta', id: messageId, text: String(payload.delta || '') });
+    } else if (kind === 'tool_call') {
+      setState(session, 'tool-running');
+      emit(session, {
+        type: 'claude/tool-use',
+        id: payload.toolCallId || `tool-${session.turns}-${session.outputBuffer.length}`,
+        name: payload.toolName || 'Tool',
+        input: payload.input && typeof payload.input === 'object' ? payload.input : { input: payload.input },
+      });
+    } else if (kind === 'tool_error') {
+      emit(session, {
+        type: 'claude/tool-result',
+        id: payload.toolCallId || `tool-${session.turns}-${session.outputBuffer.length}`,
+        output: String(payload.delta || payload.error || 'tool failed').slice(0, 4000),
+        isError: true,
+      });
+    }
+    // text_end / reasoning_end / tool_input_* deltas need no normalized event;
+    // the tool_use input arrives complete on the tool_call kind.
+  }
+
+  function onToolUpdated(session, payload) {
+    if (!payload.result || !payload.toolCallId) return; // scheduling metadata only
+    setState(session, 'running');
+    emit(session, {
+      type: 'claude/tool-result',
+      id: payload.toolCallId,
+      output: toolResultText(payload.result).slice(0, 4000),
+      isError: payload.result.success === false,
+    });
+  }
+
+  function finishTurn(session, payload, forcedError) {
+    const current = session.currentTurn;
+    if (!current) return;
+    session.currentTurn = null;
+    denyPendingApproval(session, 'turn completed'); // the server cancels unanswered approvals
+    session.turns += 1;
+    session.updatedAt = new Date().toISOString();
+    const usage = payload.usage || {};
+    const input = Number(usage.inputTokens || 0);
+    const output = Number(usage.outputTokens || 0);
+    const cached = Number(usage.cacheReadTokens || 0);
+    if (input || output || cached) {
+      session.usage.inputTokens += input;
+      session.usage.outputTokens += output;
+      session.usage.cachedTokens += cached;
+      session.peakTurnTokens = Math.max(session.peakTurnTokens || 0, input + output + cached);
+      emit(session, { type: 'claude/usage', usage: { input_tokens: input, output_tokens: output } });
+    }
+    const resultType = String(payload.resultType || 'success');
+    const response = String(payload.response != null ? payload.response : session.lastResult || '');
+    if (response) session.lastResult = response;
+    const failed = resultType === 'error' || resultType === 'failed' || Boolean(forcedError);
+    if (failed) {
+      emitDiag(session, { type: 'claude/error', message: String(forcedError || `zcode turn ${resultType}`).slice(0, 500) });
+    }
+    if (resultType === 'cancelled' && !session.abortedByUser) {
+      emit(session, { type: 'claude/aborted' });
+    }
+    emit(session, {
+      type: 'claude/result',
+      result: failed ? '' : response,
+      model: session.model,
+      isError: failed,
+    });
+    session.abortedByUser = false;
+    if (!session.endedAt) session.state = 'idle';
+    emit(session, { type: 'claude/state', state: 'idle', turn: session.turns });
+    persistSession(session);
+    if (current.resolve) current.resolve();
+  }
+
+  function emitDiag(session, event) {
+    const text = event.text != null ? event.text : event.message;
+    if (text === session.lastDiag) return;
+    session.lastDiag = String(text == null ? '' : text);
+    emit(session, event);
+  }
+
+  // -- server-initiated requests (preferences + approvals) ------------------
+
+  async function handleServerRequest(method, params) {
+    if (method === 'session/requestRuntimePreferences') {
+      // Defaults verified live: native search off, memory off, question
+      // auto-resolution off; answering unblocks session/create and session/send.
+      return RUNTIME_PREFERENCES;
+    }
+    if (method === 'interaction/requestPermission') {
+      const session = routeZcodeSession(params && params.sessionId);
+      if (!session) throw Object.assign(new Error('zcode approval for an unknown session'), { status: 404 });
+      return await waitForApproval(session, method, params || {});
+    }
+    // Official MCP plugin auth (image_search & friends) and user-input
+    // interactions have no terminal surface yet: rejecting them is verified
+    // harmless (the session continues; affected tools report a failure).
+    throw Object.assign(new Error(`zcode app-server request ${method} is not supported`), { status: 501 });
+  }
+
+  function waitForApproval(session, method, params) {
+    const choices = Array.isArray(params.options) ? params.options.filter(Boolean) : [];
+    const allowChoice = choices.find(choice => choice.kind === 'allow_once' || choice.kind === 'allow_always');
+    const denyChoice = choices.find(choice => choice.kind === 'deny');
+    const described = describeApproval(params);
+    return new Promise(resolve => {
+      const requestId = params.requestId || `zcode-perm-${nextPermissionId++}`;
+      session.pendingApproval = {
+        requestId,
+        allowResponse: allowChoice && allowChoice.response || { decision: 'allow', reason: 'Approved by the terminal user' },
+        denyResponse: denyChoice && denyChoice.response || { decision: 'deny', reason: 'Denied' },
+        resolve,
+      };
+      session.pendingPermission = {
+        requestId,
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+        summary: described.summary,
+      };
+      setState(session, 'tool-running');
+      emit(session, { type: 'claude/permission-request', requestId, ...described, status: 'pending', createdAt: session.pendingPermission.createdAt });
+    });
+  }
+
+  function describeApproval(params) {
+    const input = params.input && typeof params.input === 'object' ? params.input : {};
+    const commandText = String(input.command || input.path || input.file || '');
+    const toolName = String(params.toolName || (/file|edit|patch/i.test(commandText) ? 'Edit' : 'Bash'));
+    const title = toolName === 'Edit' ? 'ZCode wants to modify files' : 'ZCode wants to run a command';
+    return {
+      toolName,
+      title,
+      description: commandText.slice(0, 200) || String(params.reason || 'tool approval').slice(0, 200),
+      promptPreview: JSON.stringify({ toolName, command: commandText, riskLevel: params.riskLevel || '' }).slice(0, 500),
+      summary: {
+        toolName,
+        title,
+        description: commandText.slice(0, 200) || String(params.reason || '').slice(0, 200),
+        promptPreview: commandText.slice(0, 500),
+      },
+    };
+  }
+
+  function denyPendingApproval(session, reason) {
+    if (!session.pendingApproval) return;
+    const approval = session.pendingApproval;
+    session.pendingApproval = null;
+    session.pendingPermission = null;
+    emit(session, {
+      type: 'claude/permission-resolved',
+      requestId: approval.requestId,
+      allow: false,
+      decision: approval.denyResponse && approval.denyResponse.decision,
+      message: reason,
+      resolvedAt: new Date().toISOString(),
+    });
+    approval.resolve(approval.denyResponse);
+  }
+
+  // -- model runtime ----------------------------------------------------------
+
+  // Profile-injected providers become inline runtimeModel configs; agent-owned
+  // auth bridges the desktop's own provider store so a logged-in ZCode desktop
+  // works with zero terminal-side configuration. Returns null when the
+  // app-server should use its own ~/.zcode/cli/config.json. The desktop store
+  // is never read under the test runner without an explicit zcodeHome, so
+  // injected-double tests stay machine-independent.
+  function runtimeModelFor(profile) {
+    if (profile && profile.apiKey) return injectedRuntimeModel(profile);
+    if (desktopProviderCache === undefined) {
+      desktopProviderCache = options.zcodeHome || !process.env.NODE_TEST_CONTEXT
+        ? readDesktopRuntimeModel(cli, options)
+        : null;
+    }
+    return desktopProviderCache;
+  }
+
+  // Driver session ids must never collide with persisted records from a
+  // previous process: a collision would shadow a restartable session behind
+  // an empty one.
+  function nextDriverSessionId() {
+    const taken = new Set(sessions.keys());
+    const index = syncDiskIndex();
+    if (index) for (const id of index.keys()) taken.add(id);
+    let id = `zcode-${nextId++}`;
+    while (taken.has(id)) id = `zcode-${nextId++}`;
+    return id;
+  }
+
+  return runner;
+}
+
+// ---------------------------------------------------------------------------
+// module helpers
+// ---------------------------------------------------------------------------
+
+function modelForProfile(profile) {
+  if (!profile) return null;
+  const model = resolveOpenAIModel(profile);
+  return model ? String(model) : null;
+}
+
+function runtimeModelRevision(spec) {
+  return `wb-${crypto.createHash('sha1').update(JSON.stringify(spec)).digest('hex').slice(0, 16)}`;
+}
+
+// Workbench profile -> ZCode runtimeModel. Anthropic-compatible base URLs
+// (the profile default) map to the anthropic provider kind; everything else
+// falls back to the resolved OpenAI-compatible endpoint.
+function injectedRuntimeModel(profile) {
+  const anthropicBase = String(profile.baseUrl || '').trim();
+  const openaiBase = resolveOpenAIBaseUrl(profile);
+  const useAnthropic = Boolean(anthropicBase) && profile.protocol !== 'openai-compatible';
+  if (!useAnthropic && !openaiBase) {
+    throw new Error('the selected provider needs a base URL for ZCode');
+  }
+  const modelId = resolveOpenAIModel(profile) || 'default';
+  const providerId = 'agent-terminal';
+  const spec = {
+    providerId, modelId,
+    kind: useAnthropic ? 'anthropic' : 'openai-compatible',
+    baseURL: useAnthropic ? anthropicBase : openaiBase,
+    apiKey: profile.apiKey,
+  };
+  return {
+    revision: runtimeModelRevision(spec),
+    generatedAt: Date.now(),
+    model: { providerId, modelId },
+    provider: {
+      providerId,
+      kind: spec.kind,
+      label: 'Agent Terminal',
+      source: 'ephemeral',
+      baseURL: spec.baseURL,
+      apiKey: { source: 'inline', value: spec.apiKey },
+      models: [{
+        modelId,
+        ...(Number(profile.contextWindow) > 0 ? { contextWindow: profile.contextWindow } : {}),
+        supportsTools: true,
+      }],
+    },
+  };
+}
+
+// Agent-owned auth: mirror what the ZCode desktop itself does — its provider
+// selection lives in ~/.zcode/v2/config.json (keyed like "builtin:bigmodel"),
+// and model catalogs ship beside the CLI in resources/model-providers. Any
+// read/parse failure degrades to null (the app-server then applies its own
+// config or reports an actionable model_config_missing error).
+function readDesktopRuntimeModel(cli, options) {
+  try {
+    const home = options.zcodeHome || path.join(os.homedir(), '.zcode');
+    const configPath = path.join(home, 'v2', 'config.json');
+    if (!fs.existsSync(configPath)) return null;
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const providers = config && config.provider && typeof config.provider === 'object' ? config.provider : {};
+    let chosen = null;
+    let chosenScore = -1;
+    for (const [key, value] of Object.entries(providers)) {
+      if (!value || typeof value !== 'object') continue;
+      if (value.enabled === false || value.enabled === 'false') continue;
+      const options2 = value.options && typeof value.options === 'object' ? value.options : {};
+      if (!options2.apiKey || !options2.baseURL) continue;
+      const providerId = String(key).split(':').pop() || key;
+      let score = 1;
+      if (/coding-plan/i.test(providerId)) score += 2;
+      if (/bigmodel|zai|glm/i.test(providerId)) score += 1;
+      if (score > chosenScore) { chosenScore = score; chosen = { providerId, value, options: options2 }; }
+    }
+    if (!chosen) return null;
+    const modelId = desktopDefaultModel(cli, chosen.providerId, chosen.value);
+    if (!modelId) return null;
+    const spec = { providerId: chosen.providerId, modelId, baseURL: chosen.options.baseURL };
+    return {
+      revision: runtimeModelRevision(spec),
+      generatedAt: Date.now(),
+      model: { providerId: chosen.providerId, modelId },
+      provider: {
+        providerId: chosen.providerId,
+        kind: chosen.value.kind === 'openai' || chosen.value.kind === 'openai-compatible' ? chosen.value.kind : 'anthropic',
+        label: String(chosen.value.name || chosen.providerId).slice(0, 100),
+        source: 'ephemeral',
+        baseURL: chosen.options.baseURL,
+        apiKey: { source: 'inline', value: String(chosen.options.apiKey) },
+        models: [{ modelId }],
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+// Model catalog lookup: resources/model-providers/*.json next to the CLI
+// bundle; falls back to the provider's own models list, then 'glm-4.7'.
+function desktopDefaultModel(cli, providerId, providerValue) {
+  try {
+    if (Array.isArray(providerValue.models) && providerValue.models.length) {
+      const first = providerValue.models[0];
+      return String(first.modelId || first.id || first).slice(0, 128);
+    }
+    const catalogDir = path.resolve(cli.path, '..', '..', 'model-providers');
+    for (const name of fs.readdirSync(catalogDir).filter(item => item.endsWith('.json')).sort().reverse()) {
+      const catalog = JSON.parse(fs.readFileSync(path.join(catalogDir, name), 'utf8'));
+      const entry = Array.isArray(catalog && catalog.providers)
+        && catalog.providers.find(item => item && (item.id === providerId || item.id === `builtin:${providerId}`));
+      const models = entry && Array.isArray(entry.models) ? entry.models : [];
+      const model = models.find(item => item && item.default) || models[0];
+      if (model && (model.id || model.modelId)) return String(model.id || model.modelId).slice(0, 128);
+    }
+  } catch { /* catalog is best-effort */ }
+  return 'glm-4.7';
+}
+
+// Tool results arrive as { success, content, display } where content may be a
+// string or an array of parts; normalize to displayable text.
+function toolResultText(result) {
+  if (result == null) return '';
+  if (typeof result.display === 'string' && result.display) return result.display;
+  const content = result.content;
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map(part => {
+      if (typeof part === 'string') return part;
+      if (part && typeof part.text === 'string') return part.text;
+      return '';
+    }).filter(Boolean).join('\n');
+  }
+  if (result.success === false && result.error) return String(result.error);
+  return '';
+}
+
+function safeFileStem(value) {
+  return String(value).replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+// Mirrors the CLI runners' resolution: explicit config always wins; otherwise
+// persistence is suppressed under the node:test runner so test runs never
+// touch the real session store. An injected app-server spawn doubles the
+// app-server child only and does NOT suppress persistence.
+function resolvePersistence(options) {
+  const configured = options.persistence && typeof options.persistence === 'object' ? options.persistence : {};
+  const explicitlyConfigured = options.persistence != null;
+  const ephemeralTestContext = Boolean(process.env.NODE_TEST_CONTEXT);
+  const enabled = options.persistence !== null
+    && configured.enabled !== false
+    && (explicitlyConfigured || !ephemeralTestContext);
+  const dir = path.resolve(configured.dir || path.join(os.homedir(), '.agent-terminal', 'cli-sessions'));
+  return { enabled, dir };
+}
+
+module.exports = {
+  createZCodeDriver,
+  discoverZCodeCli,
+  probeZCodeVersion,
+  providerRuntimeEnvironment,
+  runtimeModelForProfile: injectedRuntimeModel,
+  toolResultText,
+  MODE_FOR_PERMISSION,
+  APP_SERVER_PERSIST_SCHEMA,
+};