@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/packages/server/index.js

@@ -1,230 +1,230 @@
-'use strict';
-
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
-const { loadLegacyRuntime } = require('./lib/runtime-loader');
-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, probeExecutableAsync, resolveClaudeAsync, resolveZCodeAsync } = require('./lib/agent-discovery');
-const { createDiagnostics } = require('./lib/diagnostics');
-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 } = require('./lib/drivers/zcode-driver');
-const { createDelegationStore } = require('./lib/delegation-store');
-const { createDelegationPhaseStore } = require('./lib/delegation-phase-store');
-const { createHttpHandler } = require('./lib/http-handler');
-
-function createWorkbenchServer(options = {}) {
-  if (options.dataDir) configureWorkbench({ dataDir: options.dataDir });
-  const dataDir = path.resolve(options.dataDir || getDataDir());
-  const storeIdentity = loadLegacyRuntime('store-scope').ensureStoreScope(dataDir);
-  const apiPrefix = options.apiPrefix || DEFAULT_API_PREFIX;
-  const testRoot = path.join(dataDir, 'test-workspaces');
-  const projects = options.projects || new ProjectStore({ dataDir });
-  require('./lib/cli-session-recovery').recoverOwnedCliSessions({ dataDir, projects });
-  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 bridgeUrl = options.bridgeUrl || process.env.KB_EVENT_BRIDGE_URL;
-  const runtimeToken = options.runtimeToken || process.env.KB_WORKBENCH_RUNTIME_TOKEN;
-  const conversationCapture = options.conversationCapture || (bridgeUrl && runtimeToken ? new (require('./lib/conversation-capture').ConversationCapture)({ file: path.join(dataDir, 'capture-outbox.v1.json'), bridgeUrl, token: runtimeToken }) : null);
-  const captureSettings = options.captureSettings || new CaptureSettingsStore({ dataDir, defaultConversations: !!conversationCapture });
-  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');
-  const knowledgeContextProvided = Boolean(options.knowledge || options.engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL);
-  claudeDriver.setKnowledgeContextProvided?.(knowledgeContextProvided);
-  // 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') {
-      // Native capture records the original input, not the augmented SDK
-      // prompt. Suppress inherited CLI hooks to avoid duplicate capture.
-      claudeDriver.setBridgeCaptureConversation(conversationCapture ? false : enabled);
-    }
-  };
-  applyBridgeCapture(captureSettings.read().terminalConversations);
-  const registry = options.registry || new AgentRegistry({
-    drivers: {
-      'claude-code': claudeDriver,
-      ...(options.drivers || {
-        codex: createCodexDriver({ knowledgeContextProvided, conversationCaptureProvided: Boolean(conversationCapture), persistence: { dir: path.join(dataDir, 'cli-sessions') } }),
-        opencode: createOpenCodeDriver({ persistence: { dir: path.join(dataDir, 'cli-sessions') } }),
-        zcode: createZCodeDriver({ knowledgeContextProvided, conversationCaptureProvided: Boolean(conversationCapture), persistence: { dir: path.join(dataDir, 'cli-sessions') } }),
-      }),
-    },
-  });
-  const runner = registry.asRunner();
-  const diagnostics = options.logger || createDiagnostics({ dataDir, secrets: () => [...Object.values(profiles._credentials().credentials), process.env.ANTHROPIC_API_KEY, process.env.ANTHROPIC_AUTH_TOKEN] });
-  const agentDiscovery = options.agentDiscovery || createAgentDiscovery({
-    claudeProbe: async ({ signal } = {}) => {
-      try {
-        const executable = await resolveClaudeAsync(claudeDriver, { signal });
-        // 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) {
-          const reason = executable?.reason || '未发现可用的 Claude Code 启动文件。';
-          diagnostics.error('agent.discovery.failed', 'Claude Code 不可用。', { phase: 'discovery', error: { code: 'CLAUDE_EXECUTABLE_NOT_FOUND', message: reason }, context: { agent: 'claude-code', rejectedPaths: executable?.rejected || [] } });
-          return { available: false, version: null, reason };
-        }
-        // Honest probe: spawn the resolved executable with --version. Same
-        // contract as every other agent: no version, no availability claim.
-        const probe = await probeExecutableAsync(cmd, { signal });
-        if (!probe.available) diagnostics.error('agent.discovery.failed', 'Claude Code 版本探测失败。', { phase: 'version-probe', error: { code: probe.code, message: probe.reason }, context: { agent: 'claude-code', executable: cmd, exitCode: probe.exitCode } });
-        else if (executable.rejected?.length) diagnostics.warn('agent.discovery.recovered', '已跳过失效的 Claude Code 启动路径，使用有效安装。', { phase: 'discovery', context: { executable: cmd, rejectedPaths: executable.rejected } });
-        return probe;
-      } catch { return { available: false, version: null }; }
-    },
-  });
-  const modelContextWindows = options.modelContextWindows || safeLoad('model-context-windows');
-  const modelDetection = options.modelDetection || createModelDetection({
-    contextLookup: modelContextWindows && modelContextWindows.lookupContextWindow,
-  });
-  const collectDoctor = options.doctor || createSystemDoctor({
-    resolveClaudeExecutable: async () => {
-      try { return await resolveClaudeAsync(claudeDriver); } catch { return { cmd: null }; }
-    },
-    discoverZCodeCli: () => resolveZCodeAsync(),
-  });
-  const doctor = async () => {
-    const report = await collectDoctor();
-    const claude = report.agents?.['claude-code'];
-    if (claude && !claude.versionProbe?.ok) diagnostics.error('agent.doctor.failed', 'Claude Code 环境诊断失败。', { phase: 'doctor', error: { code: 'CLAUDE_PROBE_FAILED', message: claude.versionProbe?.error || claude.resolutionReason }, context: { agent: 'claude-code', executable: claude.resolvedExecutable, rejectedPaths: claude.rejectedPaths, exitCode: claude.versionProbe?.exitCode } });
-    return report;
-  };
-  const service = options.service || new WorkbenchService({
-    knowledge: options.knowledge || new (require('./lib/knowledge-context').KnowledgeContext)({ engineUrl: options.engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL, contextFile: path.join(dataDir, 'knowledge-contexts.v1.json') }),
-    runner, profiles, contexts, attachments, apiPrefix, diagnostics,
-    resolveRuntimeExecutable: () => resolveClaudeAsync(claudeDriver),
-    projects, sessionArchive, agentDiscovery, modelContextWindows, modelDetection,
-    archiveRetentionDays: options.archiveRetentionDays,
-    captureSettings, uiPreferences, onCaptureSettingsSaved: applyBridgeCapture,
-    conversationCapture,
-    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,
-    storeIdentity,
-    delegations: buildDelegationStores(dataDir, storeIdentity, options),
-  });
-  const handleApi = createHttpHandler(service, { apiPrefix, corsOrigin: options.corsOrigin, doctor, runtimeToken: options.runtimeToken || process.env.KB_WORKBENCH_RUNTIME_TOKEN });
-  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', () => { agentDiscovery.close?.(); Promise.resolve(service.destroy()).catch(error => diagnostics.error('agent.shutdown.failed', '客户端运行环境关闭失败。', { phase: 'shutdown', error: { code: error.code || 'SHUTDOWN_FAILED', message: error.message } })); });
-  return { server, service, profiles, contexts, attachments, projects, sessionArchive, registry, agentDiscovery, apiPrefix, dataDir };
-}
-
-function safeLoad(name) {
-  try { return loadLegacyRuntime(name); } catch { return null; }
-}
-
-// Delegation stores bind to the SAME durable store identity as native-task
-// scopes; without one the delegation APIs answer explicit unavailability.
-function buildDelegationStores(dataDir, storeIdentity, options) {
-  if (options.delegations) return options.delegations;
-  if (!storeIdentity || storeIdentity.available !== true || !storeIdentity.storeScope) return null;
-  const root = path.join(dataDir, 'delegations');
-  return {
-    ledger: createDelegationStore({ root, storeScope: storeIdentity.storeScope }),
-    phases: createDelegationPhaseStore({ root, storeScope: storeIdentity.storeScope }),
-  };
-}
-
-function resolveDistributionRoot() {
-  // A source checkout must win over whatever unrelated 'claude-ai-workbench'
-  // package require.resolve happens to find on this machine (an old copy in
-  // the user's home node_modules once shadowed this tree and served a stale
-  // agent-terminal). Only trust require.resolve when this file is not running
-  // from a checkout of the monorepo itself.
-  const sourceRoot = path.resolve(__dirname, '..', '..');
-  try {
-    const manifest = JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8'));
-    if (manifest && manifest.name === '@sanqianx/claude-ai-workbench') return sourceRoot;
-  } catch { /* not a source layout: fall through */ }
-  try { return path.dirname(require.resolve('claude-ai-workbench/package.json')); }
-  catch { return sourceRoot; }
-}
-
-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,
-  createDelegationStore, createDelegationPhaseStore,
-};
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { loadLegacyRuntime } = require('./lib/runtime-loader');
+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, probeExecutableAsync, resolveClaudeAsync, resolveZCodeAsync } = require('./lib/agent-discovery');
+const { createDiagnostics } = require('./lib/diagnostics');
+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 } = require('./lib/drivers/zcode-driver');
+const { createDelegationStore } = require('./lib/delegation-store');
+const { createDelegationPhaseStore } = require('./lib/delegation-phase-store');
+const { createHttpHandler } = require('./lib/http-handler');
+
+function createWorkbenchServer(options = {}) {
+  if (options.dataDir) configureWorkbench({ dataDir: options.dataDir });
+  const dataDir = path.resolve(options.dataDir || getDataDir());
+  const storeIdentity = loadLegacyRuntime('store-scope').ensureStoreScope(dataDir);
+  const apiPrefix = options.apiPrefix || DEFAULT_API_PREFIX;
+  const testRoot = path.join(dataDir, 'test-workspaces');
+  const projects = options.projects || new ProjectStore({ dataDir });
+  require('./lib/cli-session-recovery').recoverOwnedCliSessions({ dataDir, projects });
+  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 bridgeUrl = options.bridgeUrl || process.env.KB_EVENT_BRIDGE_URL;
+  const runtimeToken = options.runtimeToken || process.env.KB_WORKBENCH_RUNTIME_TOKEN;
+  const conversationCapture = options.conversationCapture || (bridgeUrl && runtimeToken ? new (require('./lib/conversation-capture').ConversationCapture)({ file: path.join(dataDir, 'capture-outbox.v1.json'), bridgeUrl, token: runtimeToken }) : null);
+  const captureSettings = options.captureSettings || new CaptureSettingsStore({ dataDir, defaultConversations: !!conversationCapture });
+  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');
+  const knowledgeContextProvided = Boolean(options.knowledge || options.engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL);
+  claudeDriver.setKnowledgeContextProvided?.(knowledgeContextProvided);
+  // 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') {
+      // Native capture records the original input, not the augmented SDK
+      // prompt. Suppress inherited CLI hooks to avoid duplicate capture.
+      claudeDriver.setBridgeCaptureConversation(conversationCapture ? false : enabled);
+    }
+  };
+  applyBridgeCapture(captureSettings.read().terminalConversations);
+  const registry = options.registry || new AgentRegistry({
+    drivers: {
+      'claude-code': claudeDriver,
+      ...(options.drivers || {
+        codex: createCodexDriver({ knowledgeContextProvided, conversationCaptureProvided: Boolean(conversationCapture), persistence: { dir: path.join(dataDir, 'cli-sessions') } }),
+        opencode: createOpenCodeDriver({ persistence: { dir: path.join(dataDir, 'cli-sessions') } }),
+        zcode: createZCodeDriver({ knowledgeContextProvided, conversationCaptureProvided: Boolean(conversationCapture), persistence: { dir: path.join(dataDir, 'cli-sessions') } }),
+      }),
+    },
+  });
+  const runner = registry.asRunner();
+  const diagnostics = options.logger || createDiagnostics({ dataDir, secrets: () => [...Object.values(profiles._credentials().credentials), process.env.ANTHROPIC_API_KEY, process.env.ANTHROPIC_AUTH_TOKEN] });
+  const agentDiscovery = options.agentDiscovery || createAgentDiscovery({
+    claudeProbe: async ({ signal } = {}) => {
+      try {
+        const executable = await resolveClaudeAsync(claudeDriver, { signal });
+        // 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) {
+          const reason = executable?.reason || '未发现可用的 Claude Code 启动文件。';
+          diagnostics.error('agent.discovery.failed', 'Claude Code 不可用。', { phase: 'discovery', error: { code: 'CLAUDE_EXECUTABLE_NOT_FOUND', message: reason }, context: { agent: 'claude-code', rejectedPaths: executable?.rejected || [] } });
+          return { available: false, version: null, reason };
+        }
+        // Honest probe: spawn the resolved executable with --version. Same
+        // contract as every other agent: no version, no availability claim.
+        const probe = await probeExecutableAsync(cmd, { signal });
+        if (!probe.available) diagnostics.error('agent.discovery.failed', 'Claude Code 版本探测失败。', { phase: 'version-probe', error: { code: probe.code, message: probe.reason }, context: { agent: 'claude-code', executable: cmd, exitCode: probe.exitCode } });
+        else if (executable.rejected?.length) diagnostics.warn('agent.discovery.recovered', '已跳过失效的 Claude Code 启动路径，使用有效安装。', { phase: 'discovery', context: { executable: cmd, rejectedPaths: executable.rejected } });
+        return probe;
+      } catch { return { available: false, version: null }; }
+    },
+  });
+  const modelContextWindows = options.modelContextWindows || safeLoad('model-context-windows');
+  const modelDetection = options.modelDetection || createModelDetection({
+    contextLookup: modelContextWindows && modelContextWindows.lookupContextWindow,
+  });
+  const collectDoctor = options.doctor || createSystemDoctor({
+    resolveClaudeExecutable: async () => {
+      try { return await resolveClaudeAsync(claudeDriver); } catch { return { cmd: null }; }
+    },
+    discoverZCodeCli: () => resolveZCodeAsync(),
+  });
+  const doctor = async () => {
+    const report = await collectDoctor();
+    const claude = report.agents?.['claude-code'];
+    if (claude && !claude.versionProbe?.ok) diagnostics.error('agent.doctor.failed', 'Claude Code 环境诊断失败。', { phase: 'doctor', error: { code: 'CLAUDE_PROBE_FAILED', message: claude.versionProbe?.error || claude.resolutionReason }, context: { agent: 'claude-code', executable: claude.resolvedExecutable, rejectedPaths: claude.rejectedPaths, exitCode: claude.versionProbe?.exitCode } });
+    return report;
+  };
+  const service = options.service || new WorkbenchService({
+    knowledge: options.knowledge || new (require('./lib/knowledge-context').KnowledgeContext)({ engineUrl: options.engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL, contextFile: path.join(dataDir, 'knowledge-contexts.v1.json') }),
+    runner, profiles, contexts, attachments, apiPrefix, diagnostics,
+    resolveRuntimeExecutable: () => resolveClaudeAsync(claudeDriver),
+    projects, sessionArchive, agentDiscovery, modelContextWindows, modelDetection,
+    archiveRetentionDays: options.archiveRetentionDays,
+    captureSettings, uiPreferences, onCaptureSettingsSaved: applyBridgeCapture,
+    conversationCapture,
+    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,
+    storeIdentity,
+    delegations: buildDelegationStores(dataDir, storeIdentity, options),
+  });
+  const handleApi = createHttpHandler(service, { apiPrefix, corsOrigin: options.corsOrigin, doctor, runtimeToken: options.runtimeToken || process.env.KB_WORKBENCH_RUNTIME_TOKEN });
+  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', () => { agentDiscovery.close?.(); Promise.resolve(service.destroy()).catch(error => diagnostics.error('agent.shutdown.failed', '客户端运行环境关闭失败。', { phase: 'shutdown', error: { code: error.code || 'SHUTDOWN_FAILED', message: error.message } })); });
+  return { server, service, profiles, contexts, attachments, projects, sessionArchive, registry, agentDiscovery, apiPrefix, dataDir };
+}
+
+function safeLoad(name) {
+  try { return loadLegacyRuntime(name); } catch { return null; }
+}
+
+// Delegation stores bind to the SAME durable store identity as native-task
+// scopes; without one the delegation APIs answer explicit unavailability.
+function buildDelegationStores(dataDir, storeIdentity, options) {
+  if (options.delegations) return options.delegations;
+  if (!storeIdentity || storeIdentity.available !== true || !storeIdentity.storeScope) return null;
+  const root = path.join(dataDir, 'delegations');
+  return {
+    ledger: createDelegationStore({ root, storeScope: storeIdentity.storeScope }),
+    phases: createDelegationPhaseStore({ root, storeScope: storeIdentity.storeScope }),
+  };
+}
+
+function resolveDistributionRoot() {
+  // A source checkout must win over whatever unrelated 'claude-ai-workbench'
+  // package require.resolve happens to find on this machine (an old copy in
+  // the user's home node_modules once shadowed this tree and served a stale
+  // agent-terminal). Only trust require.resolve when this file is not running
+  // from a checkout of the monorepo itself.
+  const sourceRoot = path.resolve(__dirname, '..', '..');
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8'));
+    if (manifest && manifest.name === '@sanqianx/claude-ai-workbench') return sourceRoot;
+  } catch { /* not a source layout: fall through */ }
+  try { return path.dirname(require.resolve('claude-ai-workbench/package.json')); }
+  catch { return sourceRoot; }
+}
+
+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,
+  createDelegationStore, createDelegationPhaseStore,
+};