@steerable/agent-shell 0.6.15

package/dist/sidecar/boot.d.ts

@@ -0,0 +1,36 @@
+import { type ToolRouter } from '../tool-router.js';
+import type { createApprovalBridge } from './reverse-approval.js';
+import type { SidecarReverseHandler } from './types.js';
+export interface HostSidecarDeps {
+    toolRouter: ToolRouter;
+    /** W4-2 项目模式围栏：chatId → 项目根（无项目对话返回 null）。 */
+    resolveProjectRoot: (chatId: string) => string | null;
+    /**
+     * 项目模式之外额外放行的只读根（会话附件目录等）。文件写入仍只受
+     * projectRoot 围栏约束；这些根只放宽 local_read_file 的读取范围。
+     */
+    resolveAdditionalReadRoots?: (chatId: string) => string[];
+    /** W4-1 审批反向通道处理器（宿主审批弹窗的应答入口）。 */
+    approvalHandler: ReturnType<typeof createApprovalBridge>['handler'];
+    /**
+     * W8：sidecar ask_user 工具的 `ask_user.request` 反向调用处理器
+     * （renderer 问题卡片应答）。缺省时 ask_user 对宿主 fail-open 为空答。
+     */
+    askUserHandler?: SidecarReverseHandler;
+    /**
+     * P2b：sidecar 会话恢复时把记录里的 read-before-write 证据经
+     * `read_state.seed` 推给宿主（桌面 LocalExecutor 的 readFileState）。
+     * 缺省时宿主无读证据，自动 CAS 退化为仅依赖显式 expectedVersion。
+     */
+    readStateSeedHandler?: SidecarReverseHandler;
+    onLogLine?: (line: string) => void;
+}
+/**
+ * Default-on (2026-08-26): the sidecar hosts the CoreLoop, which is the
+ * default chat path. Explicit STEERABLE_USE_SIDECAR=0 opts out (in-process
+ * TS loop). Boot is registered synchronously so early RPC thin clients
+ * (skill-loader et al.) can await it via whenSidecarSupervisor().
+ */
+export declare function startHostSidecar(deps: HostSidecarDeps): Promise<void>;
+/** 宿主退出钩子：停 supervisor + egress proxy。幂等。 */
+export declare function shutdownHostSidecar(): Promise<void>;

package/dist/sidecar/boot.js

@@ -0,0 +1,343 @@
+/**
+ * sidecar 启动装配（W2/W4/W5 各反向通道 + egress 加固），Electron 主进程
+ * （main.ts）与 BS server（server/index.ts）共用一份，避免两条宿主路径
+ * 的启动行为漂移。
+ *
+ * 模块级持有 supervisor / egress proxy 引用，配对的 `shutdownHostSidecar`
+ * 由宿主的退出钩子调用（Electron before-quit / BS SIGTERM）。
+ */
+import path from 'node:path';
+import log from 'electron-log';
+import { SidecarSupervisor, resolveSidecarPython } from './supervisor.js';
+import { setSidecarSupervisor, setSidecarSupervisorPending, llmService } from '../llm/index.js';
+import { localStore } from '../storage/index.js';
+import { resolveSidecarStoragePath } from './storage-path.js';
+import { deriveEgressAllowListFromBaseUrl, probeExecSandboxCapability, } from './exec-sandbox.js';
+import { createToolInvokeHandler } from './reverse-tools.js';
+import { createProcessSpawnHandler } from './reverse-spawn.js';
+import { collectAmbientProxyEndpoints } from './proxy-detect.js';
+import { buildEgressProxyPlan, decideEgressProxy, deriveWebEgressHosts, pickFreePort, recordEgressPosture, startEgressProxy, } from './egress-proxy.js';
+import { WEB_TOOL_RPC_TIMEOUT_MS, webToolsEnabled } from '../tool-router.js';
+import { sidecarWebSearchEnv } from '../storage/web-search-settings.js';
+import { executeHostedWebSearch } from '../hosted-web-search.js';
+let egressProxyRef = null;
+let supervisorRef = null;
+async function deriveSidecarEgressAllowList() {
+    const envList = (process.env.STEERABLE_SIDECAR_SANDBOX_ALLOWED_HOSTS ?? '')
+        .split(',')
+        .map((h) => h.trim())
+        .filter(Boolean);
+    if (envList.length > 0)
+        return envList;
+    const derived = deriveEgressAllowListFromBaseUrl(llmService.getSettings().baseUrl);
+    // W4-8: the sidecar's httpx stack honors ambient proxies (env vars, and
+    // the macOS system proxy via getproxies). A configured proxy is an
+    // effective egress point — without it in the allow-list, the sandbox
+    // denies every LLM call for proxy users (found by dogfooding 2026-08-29:
+    // system proxy 127.0.0.1:7890 hijacked even 127.0.0.1:11434 because
+    // getproxies() does not surface the system bypass list).
+    const proxies = await collectAmbientProxyEndpoints();
+    const merged = [...new Set([...(derived ?? []), ...proxies])];
+    if (merged.length === 0) {
+        log.warn('[sidecar] cannot derive egress allow-list from provider baseUrl; outbound stays open');
+        return undefined;
+    }
+    if (proxies.length > 0) {
+        log.info(`[sidecar] egress allow-list includes ambient proxy: ${proxies.join(', ')}`);
+    }
+    return merged;
+}
+/**
+ * W1.3.3（3.1a 起默认开）：把 sidecar 出网收敛到本机
+ * steerable_egress_proxy。显式 `STEERABLE_EGRESS_PROXY=0` 退出。
+ *
+ * 两类自动回退到旧的 Seatbelt 端口级派生路径（加固永远不能弄断 LLM
+ * 通路）：
+ * - 检测到 ambient/系统代理：代理解析 CONNECT 后直连目标、无上游链，
+ *   系统代理劫持类网络开了反而断网（deriveSidecarEgressAllowList 会把
+ *   ambient 端点并进允许列表，见 W4-8）。
+ * - 启动失败 / 派生不出任何代理条目。
+ */
+async function startEgressProxyIfEnabled() {
+    try {
+        const ambient = process.env.STEERABLE_EGRESS_PROXY === '0' ? [] : await collectAmbientProxyEndpoints();
+        const decision = decideEgressProxy({ env: process.env, ambientProxies: ambient });
+        if (!decision.start) {
+            if (ambient.length > 0) {
+                log.warn(`[egress-proxy] ambient proxy detected (${ambient.join(', ')}); ` +
+                    'the per-host proxy dials targets directly and cannot chain upstream — ' +
+                    'staying on port-level enforcement');
+            }
+            recordEgressPosture(decision.posture);
+            return null;
+        }
+        const settings = llmService.getSettings();
+        const searchSettings = localStore.getWebSearchSettings();
+        const searchEnv = sidecarWebSearchEnv({
+            processEnv: process.env,
+            storedApiKey: searchSettings?.apiKey,
+            storedProvider: searchSettings?.provider,
+            llmBaseUrl: settings.baseUrl,
+        });
+        const plan = buildEgressProxyPlan({
+            pythonExecutable: resolveSidecarPython(),
+            port: await pickFreePort(),
+            providerBaseUrl: settings.baseUrl,
+            providerApiKey: settings.apiKey || undefined,
+            // 3.1b/3.1d：web 工具的允许域名与 sidecar 应用层同源，并入代理
+            // CONNECT 白名单——web_fetch/web_search 经 HTTPS_PROXY 走代理，
+            // 不再是 confined 下的互斥禁用。
+            webAllowedHosts: deriveWebEgressHosts({
+                webTools: webToolsEnabled(),
+                searchEnv,
+                env: process.env,
+            }),
+        });
+        if (!plan) {
+            log.warn('[egress-proxy] no https endpoint derivable from provider baseUrl; staying on port-level enforcement');
+            recordEgressPosture({
+                mode: 'port-only-fallback',
+                reason: '无法从 provider baseUrl 派生出 https 端点，按主机管控未启用',
+            });
+            return null;
+        }
+        egressProxyRef = await startEgressProxy(plan, (line) => log.info('[egress-proxy]', line));
+        log.info(`[egress-proxy] per-host egress active via ${plan.proxyEndpoint} (allow: ${plan.proxiedHosts.join(', ')}${plan.broker ? `; credential broker for ${plan.broker.host}` : ''})`);
+        recordEgressPosture({ mode: 'per-host-proxy', reason: null });
+        // 出网拓宽 ask 链路：控制端点端口 + token 注入 sidecar 环境。sidecar
+        // 进程在沙箱外；其沙箱子进程的环境经白名单过滤（run_code 的
+        // _child_environ），拿不到 token，无法自我拓宽。
+        const controlEnv = plan.control && egressProxyRef.controlPort
+            ? {
+                STEERABLE_EGRESS_CONTROL_PORT: String(egressProxyRef.controlPort),
+                [plan.control.tokenEnv]: plan.control.tokenValue,
+            }
+            : {};
+        return {
+            sandboxAllowedHosts: plan.sandboxAllowedHosts,
+            // 小写 https_proxy 是 httpx/getproxies 的惯例键；两个都写以兼容
+            // 只认大写的栈。broker 模式下 provider baseUrl 被改写成 http，
+            // 所以 HTTP_PROXY 也要指到代理（凭证注入在代理侧完成）。
+            // STEERABLE_EGRESS_CONFINED=1 标记"出网已收敛到代理"（W5-2）。只在
+            // 这条成功路径上设置——启动失败的回退分支不写，sidecar 不会误以为
+            // 自己被收敛。
+            env: plan.broker
+                ? {
+                    HTTPS_PROXY: plan.proxyUrl,
+                    https_proxy: plan.proxyUrl,
+                    HTTP_PROXY: plan.proxyUrl,
+                    http_proxy: plan.proxyUrl,
+                    STEERABLE_EGRESS_CONFINED: '1',
+                    ...controlEnv,
+                }
+                : {
+                    HTTPS_PROXY: plan.proxyUrl,
+                    https_proxy: plan.proxyUrl,
+                    STEERABLE_EGRESS_CONFINED: '1',
+                    ...controlEnv,
+                },
+        };
+    }
+    catch (err) {
+        log.warn('[egress-proxy] start failed; falling back to port-level enforcement', err);
+        egressProxyRef = null;
+        recordEgressPosture({
+            mode: 'port-only-fallback',
+            reason: `按主机代理启动失败（${err instanceof Error ? err.message : String(err)}），已退回端口级`,
+        });
+        return null;
+    }
+}
+/**
+ * Default-on (2026-08-26): the sidecar hosts the CoreLoop, which is the
+ * default chat path. Explicit STEERABLE_USE_SIDECAR=0 opts out (in-process
+ * TS loop). Boot is registered synchronously so early RPC thin clients
+ * (skill-loader et al.) can await it via whenSidecarSupervisor().
+ */
+export async function startHostSidecar(deps) {
+    if (process.env.STEERABLE_USE_SIDECAR === '0')
+        return;
+    // ready 后的完整接线：注册全局 handle + reverse channels + web 工具握手。
+    // 正常 boot 路径与「boot 失败后后台 restart 迟到就绪」路径共用。
+    const wireSupervisor = async (supervisor) => {
+        supervisorRef = supervisor;
+        setSidecarSupervisor(supervisor);
+        // A4 reverse channel: the sidecar-hosted CoreLoop asks this process to
+        // execute tools (shell / files / MCP live here, not in Python).
+        supervisor.onReverseRequest('tool.invoke', createToolInvokeHandler({
+            toolRouter: deps.toolRouter,
+            onBlocked: (info) => log.warn('[sidecar tool] blocked critical shell command', info),
+            // W4-2: project-mode fence on the CoreLoop path — the sidecar's
+            // tool.invoke carries context.chatId; resolve it to the project
+            // root so ToolRouter's cwd/path confinement applies.
+            resolveProjectRoot: deps.resolveProjectRoot,
+            resolveAdditionalReadRoots: deps.resolveAdditionalReadRoots,
+        }));
+        // W4-1: approval algebra reverse channel — the sidecar's
+        // ApprovalExecutor(HostApprover) asks here; the renderer modal answers
+        // via the host's decide endpoint (IPC in Electron, HTTP in BS).
+        supervisor.onReverseRequest('approval.request', deps.approvalHandler);
+        // W8: structured user questions — the sidecar-hosted ask_user tool asks
+        // here; the renderer question card answers via the host's answer
+        // endpoint (IPC in Electron, HTTP in BS).
+        if (deps.askUserHandler) {
+            supervisor.onReverseRequest('ask_user.request', deps.askUserHandler);
+        }
+        // P2b: on resume the sidecar rebuilds read-before-write evidence from
+        // the durable record and pushes it here so the host's readFileState
+        // survives process restarts (CC seed_read_state parity).
+        if (deps.readStateSeedHandler) {
+            supervisor.onReverseRequest('read_state.seed', deps.readStateSeedHandler);
+        }
+        // W4.1.1: confined-spawn reverse channel (Windows). The sidecar routes
+        // here only when no local rewriter backend exists; the handler confines
+        // via win-spawn-helper (restricted token + Job Object) and fails closed
+        // on other platforms or when the helper is missing.
+        supervisor.onReverseRequest('host.process.spawn', createProcessSpawnHandler());
+        // Layer-3 态势：问出这台机器的逐 exec 后端真能达到哪一档强制，
+        // `buildExecSandbox` 据此决定要不要 requireFull（见 exec-sandbox.ts）。
+        await probeExecSandboxCapability(supervisor);
+        // W5-2: web_search/web_fetch handshake. The single implementation lives
+        // in the sidecar (web_tools.py); the host router carries schemas only
+        // and forwards over `tool.invoke`. tool.list is the availability source
+        // of truth — web_search registers only when a search backend is
+        // configured, so an unconfigured deployment never advertises a broken
+        // tool. Handshake failure degrades to "web tools absent", not a boot
+        // failure.
+        try {
+            const advertised = webToolsEnabled() ? await supervisor.listToolNames() : [];
+            const webNames = advertised.filter((n) => n === 'web_fetch' || n === 'web_search');
+            deps.toolRouter.setWebTools((name, args) => supervisor.invokeTool(name, args, {
+                // Approval already happened in the sidecar's CoreLoop
+                // (ApprovalExecutor → approval.request reverse channel) before
+                // the call was delegated here.
+                consentGranted: true,
+                timeoutMs: WEB_TOOL_RPC_TIMEOUT_MS,
+            }), webNames);
+            const searchSettings = localStore.getWebSearchSettings();
+            const searchEnv = sidecarWebSearchEnv({
+                processEnv: process.env,
+                storedApiKey: searchSettings?.apiKey,
+                storedProvider: searchSettings?.provider,
+                llmBaseUrl: llmService.getSettings().baseUrl,
+            });
+            if (webNames.includes('web_search')
+                && searchEnv.STEERABLE_WEB_SEARCH_PROVIDER === 'host'
+                && !searchEnv.STEERABLE_WEB_SEARCH_API_KEY) {
+                deps.toolRouter.setHostedWebSearch(async (args) => {
+                    const query = typeof args.query === 'string' ? args.query : '';
+                    const max = typeof args.max_results === 'number' ? args.max_results : 8;
+                    return executeHostedWebSearch(query, max, llmService.getSettings());
+                });
+            }
+            else {
+                deps.toolRouter.setHostedWebSearch(null);
+            }
+            log.info(`[sidecar] web tools available: ${webNames.join(', ') || '(none)'}`);
+        }
+        catch (err) {
+            log.warn('[sidecar] web tool handshake failed; web tools unavailable this session', err);
+        }
+        // 插件生命周期：sidecar 的 plugin.* RPC 由 PluginRegistry 背书（__main__
+        // 缺省接线）。模型面是 tool-router 的 plugin_* 工具（deferred 层，经
+        // tool_search 发现）；这里注入直调缝。握手失败降级为工具缺席，不阻塞 boot。
+        try {
+            await supervisor.call('plugin.list');
+            deps.toolRouter.setPluginRpc((method, params) => supervisor.call(method, params));
+            log.info('[sidecar] plugin registry wired; plugin_* tools available');
+        }
+        catch (err) {
+            deps.toolRouter.setPluginRpc(null);
+            log.warn('[sidecar] plugin registry unavailable; plugin_* tools hidden this session', err);
+        }
+        log.info('[sidecar] ready', supervisor.getBootSnapshot());
+    };
+    const boot = (async () => {
+        try {
+            const egressProxy = await startEgressProxyIfEnabled();
+            // W2.6.1: durable sessions/traces/history in a zero-dependency
+            // sqlite database under ~/.steerable — the one root the Seatbelt
+            // profile already allows writes to; userData would be denied.
+            // Path is per-flavor / env-overridable — see resolveSidecarStoragePath.
+            const storagePath = resolveSidecarStoragePath();
+            const supervisor = await SidecarSupervisor.start({
+                args: [
+                    '--storage-path',
+                    storagePath,
+                ],
+                // 当 storage path 落在 ~/.steerable 之外（BS 模式 DEEPPATH_USER_DATA_DIR、
+                // 测试 tmpdir、显式 STEERABLE_SIDECAR_STORAGE_PATH）时，沙箱必须显式
+                // 授予该目录写权限，否则 sidecar 打不开 sessions.db/sessions.lock。
+                sandboxWritableRoots: [path.dirname(storagePath)],
+                // W4-3: sandbox default-on. This list is fixed at spawn (the sandbox
+                // profile cannot be edited afterwards), so a provider change reaches it
+                // only on restart — plain-http endpoints therefore still need one. The
+                // proxy's own CONNECT list does track the setting at runtime, via
+                // allowEgressForBaseUrl.
+                sandboxAllowedHosts: egressProxy?.sandboxAllowedHosts ?? (await deriveSidecarEgressAllowList()),
+                // egress-proxy 模式下不开 web-egress（*:80/443 会架空代理的按主机
+                // 名单）：web 工具改走代理（HTTPS_PROXY），代理白名单与 sidecar
+                // 应用层域名名单同源（3.1b/3.1d）。
+                sandboxWebEgress: webToolsEnabled() && !egressProxy,
+                // 3.1b：代理模式下 web_fetch 的 SSRF 预检仍在沙箱内做 DNS（抓取
+                // 本身走代理隧道），所以只放行解析器 socket——无 IP 可达性。
+                sandboxAllowResolver: webToolsEnabled() && Boolean(egressProxy),
+                env: {
+                    ...egressProxy?.env,
+                    ...sidecarWebSearchEnv({
+                        processEnv: process.env,
+                        storedApiKey: localStore.getWebSearchSettings()?.apiKey,
+                        storedProvider: localStore.getWebSearchSettings()?.provider,
+                        llmBaseUrl: llmService.getSettings().baseUrl,
+                    }),
+                    // P1: offer the sidecar's run_code (programmatic tool calls) to the
+                    // model. The sidecar registers + advertises it; the desktop's
+                    // tool-router forwards the call back over the reverse channel.
+                    STEERABLE_RUN_CODE: '1',
+                    // P3: conversational JS PTC (run_js/wait_js). The sidecar spawns a
+                    // long-lived Node worker; in the desktop that worker is the bundled
+                    // runtime — process.execPath is the Electron binary, which runs as
+                    // plain Node under ELECTRON_RUN_AS_NODE (and already *is* plain
+                    // Node in headless/BS mode, where the variable is ignored). The
+                    // sidecar's env scrub passes both through to the worker child.
+                    STEERABLE_PTC_JS: '1',
+                    STEERABLE_PTC_NODE: process.execPath,
+                    ELECTRON_RUN_AS_NODE: '1',
+                },
+                onLogLine: (line) => (deps.onLogLine ?? ((l) => log.info('[sidecar]', l)))(line),
+            });
+            await wireSupervisor(supervisor);
+            return supervisor;
+        }
+        catch (err) {
+            log.error('[sidecar] failed to start, falling back to in-process providers', err);
+            setSidecarSupervisor(null);
+            // boot 失败后 supervisor 的 exit→restart 循环仍在后台重试（另一个
+            // 宿主暂时持有 sessions.lock 这类瞬态冲突会自愈）。迟到就绪时补
+            // 接线，否则 sidecar 进程活着但 router 永远 503。
+            const late = err.supervisor;
+            if (late) {
+                late.once('ready', () => {
+                    log.info('[sidecar] late ready after initial boot failure');
+                    void wireSupervisor(late);
+                });
+            }
+            return null;
+        }
+    })();
+    setSidecarSupervisorPending(boot);
+    await boot;
+}
+/** 宿主退出钩子：停 supervisor + egress proxy。幂等。 */
+export async function shutdownHostSidecar() {
+    if (supervisorRef) {
+        const supervisor = supervisorRef;
+        supervisorRef = null;
+        setSidecarSupervisor(null);
+        await supervisor.shutdown();
+    }
+    if (egressProxyRef) {
+        egressProxyRef.stop();
+        egressProxyRef = null;
+    }
+}

package/dist/sidecar/egress-hint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * W-egress-hint: translate cryptic egress failures into user-facing hints.
+ *
+ * The sidecar's LLM clients (httpx, `trust_env=True`) honor ambient proxy
+ * configuration. When the sandbox or egress proxy denies a connection, the
+ * raw error is often a generic "All connection attempts failed" or a 403
+ * from the proxy — useless to the user. This module maps known failure
+ * patterns to actionable Chinese hints.
+ */
+/**
+ * Translate a raw egress/LLM error into a user-facing hint. Returns null
+ * when the error does not match a known egress failure pattern (caller
+ * should fall back to the raw message).
+ */
+export declare function egressFailureHint(raw: string): string | null;

package/dist/sidecar/egress-hint.js

@@ -0,0 +1,46 @@
+/**
+ * W-egress-hint: translate cryptic egress failures into user-facing hints.
+ *
+ * The sidecar's LLM clients (httpx, `trust_env=True`) honor ambient proxy
+ * configuration. When the sandbox or egress proxy denies a connection, the
+ * raw error is often a generic "All connection attempts failed" or a 403
+ * from the proxy — useless to the user. This module maps known failure
+ * patterns to actionable Chinese hints.
+ */
+/**
+ * Translate a raw egress/LLM error into a user-facing hint. Returns null
+ * when the error does not match a known egress failure pattern (caller
+ * should fall back to the raw message).
+ */
+export function egressFailureHint(raw) {
+    const text = raw.toLowerCase();
+    // httpx "All connection attempts failed" — the sandbox denied the
+    // connection (EPERM) or the proxy refused it. Most common cause: the
+    // provider endpoint is not in the allow-list.
+    if (text.includes('all connection attempts failed')) {
+        return '无法连接模型服务：沙箱或代理拒绝了连接。请检查 baseUrl 是否已加入允许列表，或尝试关闭系统代理后重试。';
+    }
+    // 403 from the egress proxy — the host is not in the per-host allow-list.
+    if (text.includes('403') && (text.includes('forbidden') || text.includes('denied'))) {
+        return '模型服务被代理拒绝（403）。请确认 baseUrl 已加入允许列表，或联系管理员放行该域名。';
+    }
+    // 502 Bad Gateway — the proxy itself failed to reach the upstream.
+    if (text.includes('502') && text.includes('bad gateway')) {
+        return '代理无法连接到模型服务（502）。请检查网络连接或代理配置，或尝试直连（关闭代理）后重试。';
+    }
+    // 504 Gateway Timeout — upstream timed out through the proxy.
+    if (text.includes('504') && text.includes('gateway timeout')) {
+        return '代理连接模型服务超时（504）。请检查网络连接或代理配置，或尝试直连（关闭代理）后重试。';
+    }
+    // ECONNREFUSED / ENOTFOUND / ETIMEDOUT — direct connection failures.
+    if (text.includes('econnrefused')) {
+        return '无法连接模型服务：连接被拒绝。请检查 baseUrl 是否正确，或确认服务已启动。';
+    }
+    if (text.includes('enotfound')) {
+        return '无法连接模型服务：域名解析失败。请检查 baseUrl 域名是否正确，或检查 DNS 配置。';
+    }
+    if (text.includes('etimedout')) {
+        return '无法连接模型服务：连接超时。请检查网络连接，或确认防火墙/代理未拦截该域名。';
+    }
+    return null;
+}

package/dist/sidecar/egress-proxy.d.ts

@@ -0,0 +1,183 @@
+/**
+ * W1.3.3：桌面宿主内嵌 `steerable_egress_proxy` 的启动器。
+ *
+ * 默认态势（3.1a，2026-09-08 起默认开）：sidecar 出网收敛到本机代理，
+ * Seatbelt 列表只放行代理端口，真正的主机名单由代理进程持有（代理跑在
+ * 沙箱外）。显式 `STEERABLE_EGRESS_PROXY=0` 退出，回退到 Seatbelt 允许
+ * 列表从 provider baseUrl 派生、主机名退化为端口级的旧态势（sbpl 限制，
+ * 见 docs/spec/safety.md）。
+ *
+ * 自动回退：检测到 ambient/系统代理（collectAmbientProxyEndpoints 非空）
+ * 时不启动——代理解析 CONNECT 后直连目标，没有上游代理链，系统代理劫持
+ * 类网络开了反而断网。回退路径就是旧的 Seatbelt 端口级派生（其允许列表
+ * 会并入 ambient proxy 端点，见 boot.ts 的 W4-8 注释）。
+ *
+ * v1 限制（与框架 egress-proxy 的 v1 范围一致）：
+ * - 只服务 CONNECT（HTTPS 隧道）。plain-http 端点（如本机 Ollama）不进
+ *   代理，直接留在 Seatbelt 列表里。
+ * - 代理直连目标主机，无上游代理链。
+ */
+export interface EgressProxyPlan {
+    command: string;
+    args: string[];
+    port: number;
+    /** `127.0.0.1:<port>` — 同时是 Seatbelt 列表里的代理条目。 */
+    proxyEndpoint: string;
+    /** 给 sidecar 子进程环境的 HTTPS_PROXY 值。 */
+    proxyUrl: string;
+    /** 代理开启后的 Seatbelt 允许列表：代理端口 + plain-http 直连端点。 */
+    sandboxAllowedHosts: string[];
+    /** 交给代理 --allow 的主机名单（https 端点）。 */
+    proxiedHosts: string[];
+    /**
+     * W2.2.2 凭证代理：存在时代理以注入模式运行，sidecar 的 provider
+     * baseUrl 改写为 http://<host> 且不再下发 apiKey——真实密钥只存在于
+     * 代理进程（经 env 传入，绝不出现在 argv / sidecar / 沙箱子进程）。
+     */
+    broker?: {
+        host: string;
+        secretEnv: string;
+        /** 完整 Authorization 头值（"Bearer sk-..."）；仅驻留主进程内存。 */
+        secretValue: string;
+    };
+    /**
+     * 出网拓宽控制面（ask 链路）：代理暴露 loopback-only `POST /allow`
+     * 端点（Bearer 认证），用户批准放行后 sidecar 把目标加进会话级白名单。
+     * token 经 env 传入代理与 sidecar（argv 在 ps 可见）；沙箱子进程环境
+     * 被白名单过滤，拿不到 token，无法自我拓宽。
+     */
+    control?: {
+        tokenEnv: string;
+        /** 仅驻留主进程内存；随 sidecar env 下发。 */
+        tokenValue: string;
+    };
+}
+/**
+ * `baseUrl` 对应的允许条目形态：裸主机（框架侧隐含 443/80）或 `host:port`。
+ *
+ * `proxied` 为 false 表示 plain-http 端点——它们不走代理，留在沙箱 profile
+ * 的直连列表里。解析不出主机名时返回 null。boot 时的名单派生与运行期的会话
+ * 放行共用这一处，两者的条目语义不会分叉。
+ */
+export declare function egressAllowEntry(baseUrl: string | undefined): {
+    entry: string;
+    host: string;
+    port: string;
+    proxied: boolean;
+} | null;
+/**
+ * 从 provider baseUrl 构建代理计划。https 端点进代理名单；http 端点留在
+ * 直连列表。派生不出任何代理条目（无 https 端点且无 web 域名）时返回
+ * null（调用方回退到旧的 Seatbelt 派生路径——空名单的代理没有意义，
+ * 框架侧也会 fail loud）。
+ */
+export declare function buildEgressProxyPlan(options: {
+    pythonExecutable: string;
+    port: number;
+    providerBaseUrl?: string;
+    /** 存在且 provider 为 https 时启用凭证代理模式（W2.2.2）。 */
+    providerApiKey?: string;
+    /**
+     * 3.1b/3.1d：并入代理 CONNECT 白名单的 web 出网主机（由
+     * deriveWebEgressHosts 推导，与 sidecar 应用层
+     * STEERABLE_WEB_ALLOWED_DOMAINS 同源）。注意框架代理是精确主机匹配
+     * ——应用层域名条目覆盖的子域不在其列，抓取子域会被代理 403（错误
+     * 信息已带提示）。
+     */
+    webAllowedHosts?: string[];
+}): EgressProxyPlan | null;
+/**
+ * 3.1b/3.1d：推导应并入代理 CONNECT 白名单的 web 出网主机。
+ *
+ * 数据源与 sidecar 应用层完全一致（同源）：`STEERABLE_WEB_ALLOWED_DOMAINS`
+ * 进程环境（sidecar 继承同一 env 做 domain_policy_error），规范化也与
+ * WebToolsConfig 相同（小写、去前导点）。web_search 在 sidecar 进程内
+ * 执行时（搜索 key 存在，或 provider=ddg），其固定 API 端点一并加入——否则
+ * CONNECT api.tavily.com:443 / html.duckduckgo.com:443 会被代理 403。
+ * provider=host 的托管搜索在 Electron 主进程执行，不占 sidecar 出网。
+ *
+ * 应用层空名单的语义是"任意公网"，代理白名单不能是开放的，所以空名单
+ * 不并入任何条目——此时 web_fetch 在 confined 下对名单外目标被代理
+ * 403，sidecar 侧错误信息已带指向本名单的提示。
+ */
+export declare function deriveWebEgressHosts(options: {
+    /** webToolsEnabled() 的结果。 */
+    webTools: boolean;
+    /** sidecarWebSearchEnv(...) 的结果（判断 sidecar 是否进程内执行搜索）。 */
+    searchEnv: Record<string, string>;
+    /** 读取 STEERABLE_WEB_* 的环境（通常 process.env）。 */
+    env: NodeJS.ProcessEnv;
+}): string[];
+export declare function getActiveEgressBroker(): {
+    host: string;
+    proxyUrl: string;
+} | null;
+/**
+ * 出网管控态势的持久披露（W-egress-posture）。boot 的每次决策都记录：
+ * per-host 代理生效 / 退回端口级（含原因）/ 用户显式关闭。设置页
+ * 「安全」区经 sandbox-posture 端点读取——退回不再是只有主进程日志
+ * 可见的静默事件。
+ */
+export interface EgressPosture {
+    mode: 'per-host-proxy' | 'port-only-fallback' | 'disabled';
+    /** 退回/关闭的原因（人可读，一行）。per-host-proxy 时为 null。 */
+    reason: string | null;
+}
+export declare function recordEgressPosture(posture: EgressPosture): void;
+/**
+ * 起不起按主机代理——在派生名单、起进程之前就能定的那部分判断。
+ *
+ * 两种不起：显式关闭，以及检测到 ambient/系统代理（本代理解析 CONNECT 后
+ * 直连目标，没有上游代理链，在系统代理劫持的网络里开了反而断网）。两者的
+ * `reason` 是设置页「安全」区直接渲染的文案，所以在这里定形并被测试锁住。
+ *
+ * 派生不出代理条目、或进程启动失败，要等到那两步才知道，仍由调用方处理。
+ */
+export declare function decideEgressProxy(options: {
+    env: NodeJS.ProcessEnv;
+    ambientProxies: string[];
+}): {
+    start: true;
+} | {
+    start: false;
+    posture: EgressPosture;
+};
+export declare function getEgressPosture(): EgressPosture | null;
+export declare function getActiveEgressProxyEndpoint(): string | null;
+/**
+ * 把 `baseUrl` 的主机加进运行中代理的会话白名单。
+ *
+ * LLM 端点不是一条策略判断：白名单本来就是从用户正在编辑的那一项设置派生
+ * 出来的，所以它必须跟着那项设置走，而不是停在 boot 时的取值上。否则用户
+ * 换网关后整个会话（连聊天）都被自己的代理 403，只有重启才好——测试按钮
+ * 更是必然被拒，因为它验的正是尚未保存的地址。
+ *
+ * 只有人能到达这里：调用点是设置页的 models.list 与保存路由，模型的工具面
+ * 没有这两者，`web_fetch` 的 SSRF 预检也拒绝回环地址。web 那半边的名单不受
+ * 影响，被注入的模型照样连不上名单外的主机。
+ *
+ * 放行是会话域的（代理进程退出即失效），条目形态与 `buildEgressProxyPlan`
+ * 的派生一致，两处语义不会分叉。
+ *
+ * @returns 已放行为 true；无可放行之处为 false——代理没在跑、URL 解析不了，
+ * 或端点是 plain-http（那类端点不进代理，由 spawn 时的沙箱 profile 钉死，
+ * 运行期改不了，仍需重启）。
+ */
+export declare function allowEgressForBaseUrl(baseUrl: string | undefined): Promise<boolean>;
+export interface EgressProxyHandle {
+    plan: EgressProxyPlan;
+    /** 控制端点实际端口（代理 stdout 的 EGRESS_CONTROL_PORT= 行读回）。 */
+    controlPort: number | null;
+    stop: () => void;
+}
+/**
+ * 启动代理并等它就绪后再放行 sidecar 启动——sidecar 的 LLM 路径要经过它，
+ * 代理未就绪就启动 sidecar 等于把首轮对话送进必失败的黑洞。
+ *
+ * 就绪判定用 TCP 连接探针而不是解析 stdout：框架 v1 的就绪日志走
+ * logging（默认不输出），把宿主耦合到日志文案上太脆。端口是我们选的，
+ * connect 成功 = 已在监听。
+ */
+export declare function startEgressProxy(plan: EgressProxyPlan, onLog: (line: string) => void, readyTimeoutMs?: number): Promise<EgressProxyHandle>;
+/** 让系统分配一个空闲回环端口（listen(0) 后立即释放，供代理绑定）。 */
+export declare function pickFreePort(): Promise<number>;