@sanqianx/claude-ai-workbench 0.11.0

package/packages/server/README.md

@@ -0,0 +1,17 @@
+# @claude-ai-workbench/server
+
+版本化 REST/SSE Server SDK，同时提供 `claude-workbench-server` 命令。
+
+```js
+const { createWorkbenchServer } = require("@claude-ai-workbench/server");
+const app = createWorkbenchServer({ dataDir: "./workbench-data", serveHost: false });
+app.server.listen(5760, "127.0.0.1");
+```
+
+命令行启动：
+
+```bash
+claude-workbench-server
+```
+
+默认只应监听本机地址。若要跨机器部署，应在外层增加 HTTPS、身份认证和访问控制。

package/packages/server/bin/agent-terminal-server.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+// Standalone Agent Terminal entry point. Fresh data directory (~/.agent-terminal
+// by default, AGENT_TERMINAL_DATA_DIR overrides) so the terminal product starts
+// independently from any legacy workbench data.
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { createWorkbenchServer } = require('..');
+const { warmFolderPicker } = require('../lib/folder-picker');
+
+const port = Number(process.env.AGENT_TERMINAL_PORT || process.env.CLAUDE_WORKBENCH_PORT || 5760);
+const host = process.env.AGENT_TERMINAL_HOST || '127.0.0.1';
+const dataDir = process.env.AGENT_TERMINAL_DATA_DIR || path.join(os.homedir(), '.agent-terminal');
+fs.mkdirSync(dataDir, { recursive: true });
+// The agent-session runner resolves its own store through these env vars;
+// without them it falls back to the legacy ~/.claude-ai-workbench layout.
+process.env.CLAUDE_AI_WORKBENCH_DATA_DIR = dataDir;
+process.env.KB_DATA_DIR = dataDir;
+
+
+const app = createWorkbenchServer({ dataDir });
+app.server.listen(port, host, () => {
+  process.stdout.write(`Agent Terminal listening at http://${host}:${port}/agent-terminal/ (data: ${dataDir})\n`);
+  // Compile the folder-picker helper up front so the first "browse…" click
+  // pops the dialog in milliseconds instead of paying the powershell +
+  // Add-Type startup. Never blocks or crashes the server.
+  warmFolderPicker({ title: '选择项目文件夹' }).catch(() => {});
+});
+
+function shutdown() {
+  app.server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 3000).unref();
+}
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/packages/server/bin/claude-workbench-server.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { createWorkbenchServer } = require('..');
+const { warmFolderPicker } = require('../lib/folder-picker');
+
+function configuredWorkspaces() {
+  if (!process.env.CLAUDE_WORKBENCH_WORKSPACES) return {};
+  const parsed = JSON.parse(process.env.CLAUDE_WORKBENCH_WORKSPACES);
+  return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key, path.resolve(String(value))]));
+}
+
+const port = Number(process.env.CLAUDE_WORKBENCH_PORT || 5760);
+const host = process.env.CLAUDE_WORKBENCH_HOST || '127.0.0.1';
+const repositoryHosts = fs.existsSync(path.resolve(__dirname, '..', '..', '..', 'apps', 'ai-profile-settings-host'));
+const serveHost = process.env.CLAUDE_WORKBENCH_SERVE_HOST === '1'
+  || (process.env.CLAUDE_WORKBENCH_SERVE_HOST !== '0' && repositoryHosts);
+if (process.env.CLAUDE_AI_WORKBENCH_DATA_DIR) {
+  // Keep the runner's session store inside the same data dir as the server.
+  process.env.KB_DATA_DIR = process.env.CLAUDE_AI_WORKBENCH_DATA_DIR;
+}
+
+const app = createWorkbenchServer({
+  dataDir: process.env.CLAUDE_AI_WORKBENCH_DATA_DIR,
+  workspaces: configuredWorkspaces(),
+  serveHost,
+});
+
+app.server.listen(port, host, () => {
+  process.stdout.write(`Claude AI Workbench Server ${app.service.version} listening at http://${host}:${port}${app.apiPrefix}\n`);
+  if (serveHost) {
+    process.stdout.write(`Claude Code terminal: http://${host}:${port}/terminal/\n`);
+    process.stdout.write(`Minimal test host: http://${host}:${port}/test-host/\n`);
+    process.stdout.write(`AI Profile settings: http://${host}:${port}/profile-settings/\n`);
+  }
+  // Compile the folder-picker helper up front so the first "browse…" click
+  // pops the dialog in milliseconds instead of paying the powershell +
+  // Add-Type startup. Never blocks or crashes the server.
+  warmFolderPicker({ title: '选择项目文件夹' }).catch(() => {});
+});
+
+function shutdown() { app.server.close(() => process.exit(0)); }
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/packages/server/bin/claude-workbench.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+'use strict';
+
+// Standalone CLI for the published claude-ai-workbench package:
+//   claude-workbench                start the server in the foreground
+//   claude-workbench start [-d]     start in the foreground, detached with -d
+//   claude-workbench stop           stop the running instance
+//   claude-workbench status         report whether an instance is running
+//   claude-workbench -v             print the package version
+// Wired up via the package.json bin field, so a global `npm i -g
+// claude-ai-workbench` puts the `claude-workbench` command on PATH.
+
+const { execFileSync, spawn } = require('child_process');
+const fs = require('fs');
+const net = require('net');
+const os = require('os');
+const path = require('path');
+
+const pkg = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+// The standalone product is the Agent Terminal: current dark UI, its own
+// clean data directory — not the legacy workbench data at ~/.claude-ai-workbench.
+const serverScript = path.join(__dirname, 'agent-terminal-server.js');
+const DEFAULT_PORT = 5760;
+
+function dataDir() {
+  return path.resolve(process.env.AGENT_TERMINAL_DATA_DIR || path.join(os.homedir(), '.agent-terminal'));
+}
+function pidFile() {
+  return path.join(dataDir(), 'server.pid');
+}
+function port() {
+  return Number(process.env.AGENT_TERMINAL_PORT || process.env.CLAUDE_WORKBENCH_PORT || DEFAULT_PORT);
+}
+function listenUrl() {
+  const host = process.env.AGENT_TERMINAL_HOST || process.env.CLAUDE_WORKBENCH_HOST || '127.0.0.1';
+  return `http://${host}:${port()}/agent-terminal/`;
+}
+
+function writePid(pid) {
+  fs.mkdirSync(dataDir(), { recursive: true });
+  fs.writeFileSync(pidFile(), String(pid), 'utf8');
+}
+function readPid() {
+  try {
+    const pid = Number(fs.readFileSync(pidFile(), 'utf8').trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function clearPid() {
+  try { fs.unlinkSync(pidFile()); } catch { /* already gone */ }
+}
+
+function alive(pid) {
+  if (process.platform === 'win32') {
+    try {
+      const out = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], {
+        encoding: 'utf8', windowsHide: true, timeout: 10000,
+      });
+      return out.includes(`"${pid}"`);
+    } catch {
+      return false;
+    }
+  }
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function killPid(pid) {
+  if (process.platform === 'win32') {
+    execFileSync('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore', timeout: 15000 });
+    return;
+  }
+  process.kill(pid, 'SIGTERM');
+}
+
+// Fallback for instances started without this CLI (raw bin script, lost data
+// dir): whoever is LISTENING on the workbench port is the instance.
+function pidsListeningOnPort(portNum) {
+  let out = '';
+  try {
+    out = execFileSync('netstat', ['-ano'], {
+      encoding: 'utf8', windowsHide: true, timeout: 15000, maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch {
+    return [];
+  }
+  const pids = new Set();
+  for (const line of out.split(/\r?\n/)) {
+    if (!/LISTENING/i.test(line)) continue;
+    const columns = line.trim().split(/\s+/);
+    if (!String(columns[1] || '').endsWith(`:${portNum}`)) continue;
+    const pid = Number(columns[columns.length - 1]);
+    if (Number.isInteger(pid) && pid > 0) pids.add(pid);
+  }
+  return [...pids];
+}
+
+function stopTargets() {
+  const pid = readPid();
+  if (pid && alive(pid)) return [pid];
+  return pidsListeningOnPort(port());
+}
+
+// True when something already listens on the workbench port. Checked before
+// every start so a busy port surfaces as guidance instead of the server's
+// raw EADDRINUSE stack trace.
+function probePortInUse(portNum, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(true));
+    server.once('listening', () => server.close(() => resolve(false)));
+    server.listen(portNum, host);
+  });
+}
+
+async function cmdStart(argv) {
+  const daemon = argv.includes('-d') || argv.includes('--daemon');
+  const existing = readPid();
+  if (existing && alive(existing)) {
+    process.stdout.write(`claude-workbench is already running (pid ${existing}) at ${listenUrl()}\n`);
+    return 0;
+  }
+  const host = process.env.CLAUDE_WORKBENCH_HOST || '127.0.0.1';
+  if (await probePortInUse(port(), host)) {
+    const holders = pidsListeningOnPort(port());
+    process.stderr.write(
+      `port ${port()} is already in use${holders.length ? ` (pid ${holders.join(', ')})` : ''} — `
+      + `another instance may be running there.\n`
+      + `Try: claude-workbench stop, or pick another port via CLAUDE_WORKBENCH_PORT.\n`);
+    return 1;
+  }
+  if (daemon) {
+    const child = spawn(process.execPath, [serverScript], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.unref();
+    writePid(child.pid);
+    process.stdout.write(`claude-workbench ${pkg.version} started in the background (pid ${child.pid}) at ${listenUrl()}\n`);
+    return 0;
+  }
+  writePid(process.pid);
+  process.on('exit', clearPid);
+  process.stderr.write(`claude-workbench ${pkg.version} starting at ${listenUrl()} (Ctrl+C stops)\n`);
+  require(serverScript); // constructs and listens in-process; owns the lifetime
+  return null;
+}
+
+function cmdStop() {
+  const targets = stopTargets();
+  if (!targets.length) {
+    clearPid(); // stale pid file from a crashed instance
+    process.stdout.write(`claude-workbench is not running (port ${port()})\n`);
+    return 1;
+  }
+  let failed = false;
+  for (const pid of targets) {
+    try {
+      killPid(pid);
+      process.stdout.write(`stopped pid ${pid}\n`);
+    } catch (error) {
+      failed = true;
+      process.stderr.write(`failed to stop pid ${pid}: ${error.message}\n`);
+    }
+  }
+  clearPid();
+  return failed ? 1 : 0;
+}
+
+function cmdStatus() {
+  const pid = readPid();
+  if (pid && alive(pid)) {
+    process.stdout.write(`claude-workbench is running (pid ${pid}) at ${listenUrl()}\n`);
+    return 0;
+  }
+  const portPids = pidsListeningOnPort(port());
+  if (portPids.length) {
+    process.stdout.write(`claude-workbench is running without a pid file (pid ${portPids.join(', ')}) at ${listenUrl()}\n`);
+    return 0;
+  }
+  clearPid();
+  process.stdout.write(`claude-workbench is not running\n`);
+  return 1;
+}
+
+function cmdVersion() {
+  process.stdout.write(`${pkg.version}\n`);
+  return 0;
+}
+
+function help() {
+  return [
+    `claude-ai-workbench ${pkg.version} — local workbench server for Claude Code, Codex, OpenCode`,
+    '',
+    'usage: claude-workbench [command]',
+    '',
+    'commands:',
+    '  start [-d|--daemon]   start the server (foreground by default, background with -d)',
+    '  stop                  stop the running server',
+    '  status                show whether the server is running',
+    '  -v | --version        print the version',
+    '  -h | --help           show this help',
+    '',
+    'environment:',
+    `  AGENT_TERMINAL_PORT            port to listen on (default ${DEFAULT_PORT}; CLAUDE_WORKBENCH_PORT also honored)`,
+    '  AGENT_TERMINAL_HOST            bind address (default 127.0.0.1)',
+    '  AGENT_TERMINAL_DATA_DIR        data directory (default ~/.agent-terminal)',
+  ].join('\n');
+}
+
+async function main(argv) {
+  const command = argv[0];
+  if (command === undefined || command === 'start') return cmdStart(argv.slice(1));
+  if (command === 'stop') return cmdStop();
+  if (command === 'status') return cmdStatus();
+  if (command === 'version' || command === '-v' || command === '--version') return cmdVersion();
+  if (command === '-h' || command === '--help' || command === 'help') {
+    process.stdout.write(`${help()}\n`);
+    return 0;
+  }
+  process.stderr.write(`unknown command: ${command}\n\n${help()}\n`);
+  return 1;
+}
+
+main(process.argv.slice(2)).then((exitCode) => {
+  if (exitCode !== null && exitCode !== undefined) process.exitCode = exitCode;
+});

package/packages/server/index.d.ts

@@ -0,0 +1,145 @@
+import type { Server } from "node:http";
+import type { AgentId, AgentStatus, AiProfile, AiProfileInput, AttachmentInput, EffortLevel, PermissionMode, Project, ProjectInput, ProjectPatch, SessionSummary, SlashCommand, WorkbenchContext } from "@claude-ai-workbench/contracts";
+
+export interface WorkbenchRunner {
+  startChatSession(options: Record<string, unknown>): {sessionId: string};
+  listSessions(filter?: Record<string, unknown>): Record<string, unknown>[];
+  getState(sessionId: string): Record<string, unknown> | null;
+  getSession(sessionId: string): Record<string, unknown> | null;
+  getSessionTokenUsage(sessionId: string): Record<string, unknown>;
+  subscribe(sessionId: string, listener: (event: Record<string, unknown>) => void): () => void;
+  sendInput(sessionId: string, text: string, profile: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+  listSupportedCommands?(sessionId: string, profile: Record<string, unknown>): Promise<SlashCommand[]>;
+  resolvePermission(sessionId: string, requestId: string, decision: Record<string, unknown>): unknown;
+  abort(sessionId: string): void;
+  deleteSession(sessionId: string): unknown;
+  findClaudeExecutableForSdk(): unknown;
+}
+
+export interface WorkbenchServerOptions {
+  dataDir?: string;
+  workspaces?: Record<string, string>;
+  runner?: WorkbenchRunner;
+  profiles?: ProfileStore;
+  attachments?: AttachmentStore;
+  contexts?: ContextResolver;
+  service?: WorkbenchService;
+  projects?: ProjectStore;
+  sessionArchive?: SessionArchiveStore;
+  registry?: AgentRegistry;
+  drivers?: Partial<Record<AgentId, WorkbenchRunner>>;
+  agentDiscovery?: AgentDiscovery;
+  modelContextWindows?: { resolveContextWindow(model: string): number | null };
+  apiPrefix?: string;
+  corsOrigin?: string;
+  serveHost?: boolean;
+  staticRoot?: string;
+  profileSettingsRoot?: string;
+  terminalHostRoot?: string;
+  agentTerminalRoot?: string;
+  createMissingWorkspaces?: boolean;
+  version?: string;
+  maxSessions?: number;
+  maxConcurrentRuns?: number;
+}
+
+export interface WorkbenchServer {
+  server: Server;
+  service: WorkbenchService;
+  profiles: ProfileStore;
+  attachments: AttachmentStore;
+  contexts: ContextResolver;
+  projects: ProjectStore;
+  sessionArchive: SessionArchiveStore;
+  registry: AgentRegistry;
+  agentDiscovery: AgentDiscovery;
+  apiPrefix: string;
+  dataDir: string;
+}
+
+export declare class ProfileStore {
+  constructor(options: {dataDir: string; profileFile?: string; credentialFile?: string});
+  list(): AiProfile[];
+  get(id: string): AiProfile | null;
+  save(input: AiProfileInput, idOverride?: string): AiProfile;
+  delete(id: string): boolean;
+  setCredential(id: string, credential: string | {secret: string}): void;
+  runtimeProfile(id: string): Record<string, unknown>;
+  runtimeDraft(input: AiProfileInput, credential?: string | {secret: string}): Record<string, unknown>;
+}
+
+export declare class ContextResolver {
+  constructor(options?: {workspaces?: Record<string, string>; createMissing?: boolean});
+  register(ref: string, target: string): void;
+  unregister(ref: string): boolean;
+  resolve(context: WorkbenchContext): {context: WorkbenchContext; workspacePath: string};
+}
+
+export declare class ProjectStore {
+  constructor(options: {dataDir: string; projectFile?: string});
+  list(): Project[];
+  get(id: string): Project | null;
+  create(input: ProjectInput): Project;
+  rename(id: string, name: string): Project;
+  update(id: string, patch: ProjectPatch): Project;
+  remove(id: string): boolean;
+  toWorkspaceMap(): Record<string, string>;
+}
+
+export declare class SessionArchiveStore {
+  constructor(options: {dataDir: string; archiveFile?: string});
+  isArchived(sessionId: string): boolean;
+  archive(sessionId: string): {archivedAt: string};
+  restore(sessionId: string): boolean;
+  forget(sessionId: string): void;
+}
+
+export declare class AgentRegistry {
+  constructor(options?: {drivers?: Partial<Record<AgentId, WorkbenchRunner>>});
+  register(agentId: AgentId, driver: WorkbenchRunner): WorkbenchRunner;
+  driverFor(agentId: AgentId): WorkbenchRunner;
+  agentOf(sessionId: string): AgentId;
+  asRunner(): WorkbenchRunner;
+}
+
+export interface AgentDiscovery {
+  (): Record<AgentId, AgentStatus & {reason?: string}>;
+  invalidate?(): void;
+}
+
+export interface CliDriverOptions {
+  command?: string;
+  spawn?: typeof import("node:child_process").spawn;
+  ignoreUserConfig?: boolean;
+}
+
+export declare class AttachmentStore {
+  constructor(options: {root: string});
+  saveMany(sessionId: string, attachments: AttachmentInput[]): Record<string, unknown>[];
+  save(sessionId: string, attachment: AttachmentInput): Record<string, unknown>;
+  read(sessionId: string, attachmentId: string): {metadata: Record<string, unknown>; data: Buffer} | null;
+}
+
+export declare class WorkbenchService {
+  readonly version: string;
+  listProjects(): {projects: Project[]};
+  getProject(id: string): Project;
+  createProject(input: ProjectInput): Project;
+  renameProject(id: string, input: ProjectPatch): Project;
+  removeProject(id: string): boolean;
+  listSessions(contextId: string, options?: {includeArchived?: boolean}): SessionSummary[];
+  startSession(context: WorkbenchContext, aiProfileId?: string | null, options?: {agentId?: AgentId; model?: string | null; permissionMode?: PermissionMode; effort?: EffortLevel}): SessionSummary;
+  listCommands(sessionId: string): Promise<{commands: SlashCommand[]}>;
+  readAttachment(sessionId: string, attachmentId: string): {metadata: Record<string, unknown>; data: Buffer};
+  send(sessionId: string, text?: string, options?: Record<string, unknown>, attachments?: AttachmentInput[]): Promise<Record<string, unknown>>;
+  testProfile(profileId: string): Promise<Record<string, unknown>>;
+  testProfileDraft(input: {profile: AiProfileInput; credential?: string}): Promise<Record<string, unknown>>;
+  destroy(): void;
+}
+
+export declare function createWorkbenchServer(options?: WorkbenchServerOptions): WorkbenchServer;
+export declare function createAgentDiscovery(options?: {claudeProbe?: () => {available: boolean; version?: string | null}}): AgentDiscovery;
+export declare function createCodexDriver(options?: CliDriverOptions): WorkbenchRunner;
+export declare function createOpenCodeDriver(options?: CliDriverOptions): WorkbenchRunner;
+export declare function createZCodeDriver(): WorkbenchRunner;
+export declare function createHttpHandler(service: WorkbenchService, options?: Record<string, unknown>): (request: unknown, response: unknown) => Promise<boolean>;

package/packages/server/index.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { configureWorkbench } = loadLegacyRuntime('runtime-config');
+const { getDataDir } = loadLegacyRuntime('data-dir');
+const { DEFAULT_API_PREFIX } = require('../contracts');
+const { ProfileStore } = require('./lib/profile-store');
+const { CaptureSettingsStore } = require('./lib/capture-settings-store');
+const { UiPreferencesStore } = require('./lib/ui-preferences-store');
+const { ContextResolver } = require('./lib/context-resolver');
+const { WorkbenchService } = require('./lib/workbench-service');
+const { AttachmentStore } = require('./lib/attachment-store');
+const { ProjectStore } = require('./lib/project-store');
+const { SessionArchiveStore } = require('./lib/session-archive-store');
+const { AgentRegistry } = require('./lib/agent-registry');
+const { createAgentDiscovery, probeExecutableVersion } = require('./lib/agent-discovery');
+const { createSystemDoctor } = require('./lib/system-doctor');
+const { createModelDetection } = require('./lib/model-detection');
+const { createCodexDriver } = require('./lib/drivers/codex-driver');
+const { createOpenCodeDriver } = require('./lib/drivers/opencode-driver');
+const { createZCodeDriver, discoverZCodeCli, probeZCodeVersion } = require('./lib/drivers/zcode-driver');
+const { createHttpHandler } = require('./lib/http-handler');
+
+function createWorkbenchServer(options = {}) {
+  if (options.dataDir) configureWorkbench({ dataDir: options.dataDir });
+  const dataDir = path.resolve(options.dataDir || getDataDir());
+  const apiPrefix = options.apiPrefix || DEFAULT_API_PREFIX;
+  const testRoot = path.join(dataDir, 'test-workspaces');
+  const projects = options.projects || new ProjectStore({ dataDir });
+  const sessionArchive = options.sessionArchive || new SessionArchiveStore({ dataDir });
+  const workspaces = {
+    'test-workspace-a': path.join(testRoot, 'context-a'),
+    'test-workspace-b': path.join(testRoot, 'context-b'),
+    'test-workspace-c': path.join(testRoot, 'context-c'),
+    ...(options.workspaces || {}),
+    ...projects.toWorkspaceMap(),
+  };
+  const profiles = options.profiles || new ProfileStore({ dataDir });
+  const captureSettings = options.captureSettings || new CaptureSettingsStore({ dataDir });
+  const uiPreferences = options.uiPreferences || new UiPreferencesStore({ dataDir });
+  const attachments = options.attachments || new AttachmentStore({ root: path.join(dataDir, 'attachments') });
+  const contexts = options.contexts || new ContextResolver({ workspaces, createMissing: options.createMissingWorkspaces !== false });
+  const claudeDriver = options.runner || loadLegacyRuntime('claude-cli-runner');
+  // Bridge capture scope: terminal sessions are exempt from Development
+  // Conversation capture unless the 会话捕获 setting says otherwise. Applied to
+  // the driver at boot and re-applied on every settings save.
+  const applyBridgeCapture = enabled => {
+    if (claudeDriver && typeof claudeDriver.setBridgeCaptureConversation === 'function') {
+      claudeDriver.setBridgeCaptureConversation(enabled);
+    }
+  };
+  applyBridgeCapture(captureSettings.read().terminalConversations);
+  const registry = options.registry || new AgentRegistry({
+    drivers: {
+      'claude-code': claudeDriver,
+      ...(options.drivers || {
+        codex: createCodexDriver(),
+        opencode: createOpenCodeDriver(),
+        zcode: createZCodeDriver(),
+      }),
+    },
+  });
+  const runner = registry.asRunner();
+  const agentDiscovery = options.agentDiscovery || createAgentDiscovery({
+    claudeProbe: () => {
+      try {
+        const executable = claudeDriver.findClaudeExecutableForSdk();
+        // Handle both shapes: the legacy runner returns {cmd}, test doubles
+        // may return a plain string. No usable executable -> not available.
+        const cmd = typeof executable === 'string'
+          ? executable
+          : executable && executable.cmd;
+        if (!cmd) return { available: false, version: null };
+        // Honest probe: spawn the resolved executable with --version. Same
+        // contract as every other agent: no version, no availability claim.
+        const version = probeExecutableVersion(cmd);
+        return { available: version != null, version };
+      } catch { return { available: false, version: null }; }
+    },
+  });
+  const modelContextWindows = options.modelContextWindows || safeLoad('model-context-windows');
+  const modelDetection = options.modelDetection || createModelDetection({
+    contextLookup: modelContextWindows && modelContextWindows.lookupContextWindow,
+  });
+  const doctor = options.doctor || createSystemDoctor({
+    resolveClaudeExecutable: () => {
+      try { return claudeDriver.findClaudeExecutableForSdk(); } catch { return { cmd: null }; }
+    },
+    discoverZCodeCli,
+    probeZCodeVersion,
+  });
+  const service = options.service || new WorkbenchService({
+    runner, profiles, contexts, attachments, apiPrefix,
+    projects, sessionArchive, agentDiscovery, modelContextWindows, modelDetection,
+    archiveRetentionDays: options.archiveRetentionDays,
+    captureSettings, uiPreferences, onCaptureSettingsSaved: applyBridgeCapture,
+    testWorkspace: path.join(testRoot, 'profile-test'), auditFile: path.join(dataDir, 'audit.jsonl'),
+    version: options.version || require('./package.json').version,
+    maxSessions: options.maxSessions, maxConcurrentRuns: options.maxConcurrentRuns,
+  });
+  const handleApi = createHttpHandler(service, { apiPrefix, corsOrigin: options.corsOrigin, doctor });
+  const distributionRoot = resolveDistributionRoot();
+  const staticRoot = path.resolve(options.staticRoot || path.join(distributionRoot, 'apps', 'minimal-test-host'));
+  const profileSettingsRoot = path.resolve(options.profileSettingsRoot || path.join(distributionRoot, 'apps', 'ai-profile-settings-host'));
+  const agentTerminalRoot = path.resolve(options.agentTerminalRoot || path.join(distributionRoot, 'apps', 'agent-terminal'));
+  const packagesRoot = path.join(distributionRoot, 'packages');
+  const server = http.createServer(async (req, res) => {
+    if (await handleApi(req, res)) return;
+    if (options.serveHost !== false && servePackageAsset(req, res, packagesRoot)) return;
+    if (options.serveHost !== false && serveAppStatic(req, res, '/profile-settings/', profileSettingsRoot)) return;
+    if (options.serveHost !== false && serveAppStatic(req, res, '/agent-terminal/', agentTerminalRoot)) return;
+    if (options.serveHost !== false && serveStatic(req, res, staticRoot)) return;
+    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ ok: false, error: 'not found' }));
+  });
+  server.on('close', () => service.destroy());
+  return { server, service, profiles, contexts, attachments, projects, sessionArchive, registry, agentDiscovery, apiPrefix, dataDir };
+}
+
+function loadLegacyRuntime(name) {
+  const bundled = path.join(__dirname, 'legacy', 'src', 'backend', 'lib', name);
+  if (fs.existsSync(`${bundled}.js`)) return require(bundled);
+  return require(path.join(__dirname, '..', '..', 'src', 'backend', 'lib', name));
+}
+
+function safeLoad(name) {
+  try { return loadLegacyRuntime(name); } catch { return null; }
+}
+
+function resolveDistributionRoot() {
+  try { return path.dirname(require.resolve('claude-ai-workbench/package.json')); }
+  catch { return path.resolve(__dirname, '..', '..'); }
+}
+
+function servePackageAsset(req, res, packagesRoot) {
+  const url = new URL(req.url, 'http://127.0.0.1');
+  if (req.method !== 'GET' || !url.pathname.startsWith('/packages/')) return false;
+  const relative = decodeURIComponent(url.pathname.slice('/packages/'.length));
+  const file = path.resolve(packagesRoot, relative);
+  if (!file.startsWith(`${packagesRoot}${path.sep}`) || !fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
+  const type = path.extname(file) === '.css' ? 'text/css' : 'text/javascript';
+  res.writeHead(200, { 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-store' });
+  fs.createReadStream(file).pipe(res); return true;
+}
+
+function serveStatic(req, res, root) {
+  const url = new URL(req.url, 'http://127.0.0.1');
+  if (!['GET', 'HEAD'].includes(req.method)) return false;
+  let pathname = decodeURIComponent(url.pathname);
+  if (pathname === '/') { res.writeHead(302, { Location: '/agent-terminal/' }); res.end(); return true; }
+  if (!pathname.startsWith('/test-host/')) return false;
+  const relative = pathname.slice('/test-host/'.length) || 'index.html';
+  const file = path.resolve(root, relative);
+  if (file !== root && !file.startsWith(`${root}${path.sep}`)) return false;
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
+  const type = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml' }[path.extname(file)] || 'application/octet-stream';
+  res.writeHead(200, { 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-store' });
+  if (req.method === 'HEAD') res.end(); else fs.createReadStream(file).pipe(res);
+  return true;
+}
+
+function serveAppStatic(req, res, urlPrefix, root) {
+  const url = new URL(req.url, 'http://127.0.0.1');
+  if (!['GET', 'HEAD'].includes(req.method)) return false;
+  if (url.pathname === urlPrefix.slice(0, -1)) { res.writeHead(302, { Location: urlPrefix }); res.end(); return true; }
+  if (!url.pathname.startsWith(urlPrefix)) return false;
+  const relative = decodeURIComponent(url.pathname.slice(urlPrefix.length)) || 'index.html';
+  const file = path.resolve(root, relative);
+  if (file !== root && !file.startsWith(`${root}${path.sep}`)) return false;
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
+  const type = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml' }[path.extname(file)] || 'application/octet-stream';
+  res.writeHead(200, { 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-store' });
+  if (req.method === 'HEAD') res.end(); else fs.createReadStream(file).pipe(res);
+  return true;
+}
+
+module.exports = {
+  createWorkbenchServer, ProfileStore, CaptureSettingsStore, ContextResolver, AttachmentStore, WorkbenchService, createHttpHandler,
+  ProjectStore, SessionArchiveStore, AgentRegistry, createAgentDiscovery, UiPreferencesStore,
+  createCodexDriver, createOpenCodeDriver, createZCodeDriver,
+};