@steerable/agent-shell 0.6.15

package/dist/sidecar/egress-proxy.js

@@ -0,0 +1,419 @@
+/**
+ * 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 列表里。
+ * - 代理直连目标主机，无上游代理链。
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { connect, createServer } from 'node:net';
+import { defaultSearchBaseUrl } from '../storage/web-search-settings.js';
+/**
+ * `baseUrl` 对应的允许条目形态：裸主机（框架侧隐含 443/80）或 `host:port`。
+ *
+ * `proxied` 为 false 表示 plain-http 端点——它们不走代理，留在沙箱 profile
+ * 的直连列表里。解析不出主机名时返回 null。boot 时的名单派生与运行期的会话
+ * 放行共用这一处，两者的条目语义不会分叉。
+ */
+export function egressAllowEntry(baseUrl) {
+    if (!baseUrl)
+        return null;
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return null;
+    }
+    if (!url.hostname)
+        return null;
+    return {
+        entry: url.port ? `${url.hostname}:${url.port}` : url.hostname,
+        host: url.hostname,
+        port: url.port,
+        proxied: url.protocol === 'https:',
+    };
+}
+/**
+ * 从 provider baseUrl 构建代理计划。https 端点进代理名单；http 端点留在
+ * 直连列表。派生不出任何代理条目（无 https 端点且无 web 域名）时返回
+ * null（调用方回退到旧的 Seatbelt 派生路径——空名单的代理没有意义，
+ * 框架侧也会 fail loud）。
+ */
+export function buildEgressProxyPlan(options) {
+    const { pythonExecutable, port, providerBaseUrl, providerApiKey } = options;
+    const proxiedHosts = [];
+    const directHosts = [];
+    let brokerHost = null;
+    // unparseable baseUrl → no derivation, same as the legacy path
+    const provider = egressAllowEntry(providerBaseUrl);
+    if (provider) {
+        if (provider.proxied) {
+            proxiedHosts.push(provider.entry);
+            // 凭证注入按裸主机匹配（转发目标是 443）；显式端口端点不进
+            // broker——注入规则与 CONNECT 名单语义保持各自单一。
+            if (!provider.port && providerApiKey)
+                brokerHost = provider.host;
+        }
+        else {
+            directHosts.push(provider.entry);
+        }
+    }
+    for (const host of options.webAllowedHosts ?? []) {
+        if (!proxiedHosts.includes(host))
+            proxiedHosts.push(host);
+    }
+    if (proxiedHosts.length === 0)
+        return null;
+    const proxyEndpoint = `127.0.0.1:${port}`;
+    const broker = brokerHost
+        ? {
+            host: brokerHost,
+            secretEnv: 'STEERABLE_EGRESS_SECRET',
+            secretValue: `Bearer ${providerApiKey}`,
+        }
+        : undefined;
+    const control = {
+        tokenEnv: 'STEERABLE_EGRESS_CONTROL_TOKEN',
+        tokenValue: randomBytes(24).toString('base64url'),
+    };
+    return {
+        command: pythonExecutable,
+        args: [
+            '-m',
+            'steerable_egress_proxy',
+            '--bind',
+            proxyEndpoint,
+            ...proxiedHosts.flatMap((host) => ['--allow', host]),
+            // 控制端口 0 = ephemeral；实际端口由代理 stdout 的
+            // EGRESS_CONTROL_PORT= 行读回（startEgressProxy 解析）。
+            '--control-port',
+            '0',
+            '--control-token-env',
+            control.tokenEnv,
+            ...(broker
+                ? [
+                    '--inject-host',
+                    broker.host,
+                    '--inject-secret-env',
+                    broker.secretEnv,
+                ]
+                : []),
+        ],
+        port,
+        proxyEndpoint,
+        proxyUrl: `http://${proxyEndpoint}`,
+        sandboxAllowedHosts: [proxyEndpoint, ...directHosts],
+        proxiedHosts,
+        broker,
+        control,
+    };
+}
+/**
+ * 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 function deriveWebEgressHosts(options) {
+    if (!options.webTools)
+        return [];
+    const { env, searchEnv } = options;
+    const hosts = [];
+    for (const entry of (env.STEERABLE_WEB_ALLOWED_DOMAINS ?? '').split(',')) {
+        const domain = entry.trim().toLowerCase().replace(/^\.+/, '');
+        if (domain)
+            hosts.push(domain);
+    }
+    if (searchEnv.STEERABLE_WEB_SEARCH_API_KEY || searchEnv.STEERABLE_WEB_SEARCH_PROVIDER === 'ddg') {
+        // 与 WebToolsConfig.resolve 的 search_base_url 推导保持一致：显式
+        // STEERABLE_WEB_SEARCH_BASE_URL 优先，否则按 provider 取默认端点。
+        // ddg 无钥也在 sidecar 进程内执行，必须放行 html.duckduckgo.com。
+        const explicit = (env.STEERABLE_WEB_SEARCH_BASE_URL ?? '').trim();
+        const provider = (searchEnv.STEERABLE_WEB_SEARCH_PROVIDER
+            || env.STEERABLE_WEB_SEARCH_PROVIDER
+            || '').trim();
+        const base = explicit || defaultSearchBaseUrl(provider);
+        try {
+            const url = new URL(base);
+            // 显式端口保留（裸主机只放行 443/80，带端口的端点要精确条目）。
+            const entry = url.port ? `${url.hostname}:${url.port}` : url.hostname;
+            if (entry)
+                hosts.push(entry);
+        }
+        catch {
+            /* 畸形 base url：sidecar 侧 resolve 同样失败，web_search 不会注册 */
+        }
+    }
+    // 框架代理对畸形 --allow 条目 fail loud（拒启 → 整体回退端口级）。在
+    // 这里过滤保住 LLM 通路的按主机管控；被丢的条目本就无法匹配真实主机，
+    // 应用层名单语义不变。形态与框架 parse_allow_entry 的字母表一致
+    // （host 或 host:port；域名已在上面小写化）。
+    return hosts.filter((host) => /^[a-z0-9._-]+(:[0-9]{1,5})?$/.test(host));
+}
+/**
+ * 当前活跃的凭证代理（broker 模式开启时非空）。router 据此改写
+ * chat.stream 的 baseUrl/apiKey。模块级状态：代理由 main.ts 拥有，
+ * 流参数构造在 router.ts，二者经此 getter 会面。
+ */
+let activeBroker = null;
+export function getActiveEgressBroker() {
+    return activeBroker;
+}
+let egressPosture = null;
+export function recordEgressPosture(posture) {
+    egressPosture = posture;
+}
+/**
+ * 起不起按主机代理——在派生名单、起进程之前就能定的那部分判断。
+ *
+ * 两种不起：显式关闭，以及检测到 ambient/系统代理（本代理解析 CONNECT 后
+ * 直连目标，没有上游代理链，在系统代理劫持的网络里开了反而断网）。两者的
+ * `reason` 是设置页「安全」区直接渲染的文案，所以在这里定形并被测试锁住。
+ *
+ * 派生不出代理条目、或进程启动失败，要等到那两步才知道，仍由调用方处理。
+ */
+export function decideEgressProxy(options) {
+    if (options.env.STEERABLE_EGRESS_PROXY === '0') {
+        return {
+            start: false,
+            posture: { mode: 'disabled', reason: '已通过 STEERABLE_EGRESS_PROXY=0 关闭' },
+        };
+    }
+    if (options.ambientProxies.length > 0) {
+        return {
+            start: false,
+            posture: {
+                mode: 'port-only-fallback',
+                reason: `检测到系统/环境代理（${options.ambientProxies.join(', ')}），按主机管控已退回端口级`,
+            },
+        };
+    }
+    return { start: true };
+}
+export function getEgressPosture() {
+    return egressPosture;
+}
+/**
+ * 当前活跃代理的 `127.0.0.1:<port>` 端点（无论是否 broker 模式）。P3.2
+ * shell-via-proxy：chat 的 execSandbox 在代理活跃时把 allowedHosts 收敛到
+ * 这个 localhost 端点，Seatbelt 据此判 enforcement="full"，requireFull
+ * 才能缺省开。代理未运行时为 null（回退到 baseUrl 派生的 partial 路径）。
+ */
+let activeProxyEndpoint = null;
+export function getActiveEgressProxyEndpoint() {
+    return activeProxyEndpoint;
+}
+/**
+ * 活跃代理的控制端点（loopback-only `POST /allow` + Bearer）。token 只驻留
+ * 主进程内存，与下发给 sidecar 的是同一个值。
+ */
+let activeControl = null;
+/**
+ * 把 `baseUrl` 的主机加进运行中代理的会话白名单。
+ *
+ * LLM 端点不是一条策略判断：白名单本来就是从用户正在编辑的那一项设置派生
+ * 出来的，所以它必须跟着那项设置走，而不是停在 boot 时的取值上。否则用户
+ * 换网关后整个会话（连聊天）都被自己的代理 403，只有重启才好——测试按钮
+ * 更是必然被拒，因为它验的正是尚未保存的地址。
+ *
+ * 只有人能到达这里：调用点是设置页的 models.list 与保存路由，模型的工具面
+ * 没有这两者，`web_fetch` 的 SSRF 预检也拒绝回环地址。web 那半边的名单不受
+ * 影响，被注入的模型照样连不上名单外的主机。
+ *
+ * 放行是会话域的（代理进程退出即失效），条目形态与 `buildEgressProxyPlan`
+ * 的派生一致，两处语义不会分叉。
+ *
+ * @returns 已放行为 true；无可放行之处为 false——代理没在跑、URL 解析不了，
+ * 或端点是 plain-http（那类端点不进代理，由 spawn 时的沙箱 profile 钉死，
+ * 运行期改不了，仍需重启）。
+ */
+export async function allowEgressForBaseUrl(baseUrl) {
+    const control = activeControl;
+    if (!control)
+        return false;
+    const target = egressAllowEntry(baseUrl);
+    if (!target || !target.proxied)
+        return false;
+    const entry = target.entry;
+    try {
+        const response = await fetch(`http://127.0.0.1:${control.port}/allow`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${control.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ host: entry }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!response.ok) {
+            control.log(`control endpoint refused ${entry}: ${response.status}`);
+            return false;
+        }
+        control.log(`session allow added for ${entry}`);
+        return true;
+    }
+    catch (err) {
+        control.log(`control endpoint unreachable for ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+/**
+ * 启动代理并等它就绪后再放行 sidecar 启动——sidecar 的 LLM 路径要经过它，
+ * 代理未就绪就启动 sidecar 等于把首轮对话送进必失败的黑洞。
+ *
+ * 就绪判定用 TCP 连接探针而不是解析 stdout：框架 v1 的就绪日志走
+ * logging（默认不输出），把宿主耦合到日志文案上太脆。端口是我们选的，
+ * connect 成功 = 已在监听。
+ */
+export async function startEgressProxy(plan, onLog, readyTimeoutMs = 10_000) {
+    const child = spawn(plan.command, plan.args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // 凭证与控制 token 经 env 传入代理进程——argv 在 ps 里可见，env 不入
+        // 命令行。
+        env: plan.broker
+            ? {
+                ...process.env,
+                [plan.broker.secretEnv]: plan.broker.secretValue,
+                ...(plan.control ? { [plan.control.tokenEnv]: plan.control.tokenValue } : {}),
+            }
+            : plan.control
+                ? { ...process.env, [plan.control.tokenEnv]: plan.control.tokenValue }
+                : process.env,
+    });
+    // 控制端口是 ephemeral 的：代理由 stdout 报回实际端口。就绪条件在
+    // TCP 探针之外加上这一行（控制面开启时），否则 sidecar 拿到的
+    // STEERABLE_EGRESS_CONTROL_PORT 可能是尚未监听的端口。
+    let controlPort = null;
+    let resolveControlLine = () => { };
+    const controlLineSeen = new Promise((resolve) => {
+        resolveControlLine = resolve;
+    });
+    child.stdout.on('data', (chunk) => {
+        for (const line of chunk.toString().split('\n')) {
+            if (!line.trim())
+                continue;
+            const match = /^EGRESS_CONTROL_PORT=(\d+)$/.exec(line.trim());
+            if (match) {
+                controlPort = Number(match[1]);
+                resolveControlLine();
+            }
+            onLog(line);
+        }
+    });
+    child.stderr.on('data', (chunk) => {
+        for (const line of chunk.toString().split('\n'))
+            if (line.trim())
+                onLog(line);
+    });
+    const ready = new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            fail(new Error(`egress proxy did not listen on ${plan.proxyEndpoint} within ${readyTimeoutMs}ms`));
+        }, readyTimeoutMs);
+        const succeed = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        };
+        child.on('exit', (code) => fail(new Error(`egress proxy exited before ready (code ${code})`)));
+        const probe = () => {
+            if (settled)
+                return;
+            const socket = connect(plan.port, '127.0.0.1');
+            socket.once('connect', () => {
+                socket.destroy();
+                succeed();
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                setTimeout(probe, 100);
+            });
+        };
+        probe();
+    });
+    try {
+        await ready;
+        if (plan.control) {
+            await Promise.race([
+                controlLineSeen,
+                new Promise((_, reject) => setTimeout(() => reject(new Error('egress proxy did not report its control port')), readyTimeoutMs)),
+            ]);
+        }
+    }
+    catch (err) {
+        child.kill('SIGTERM');
+        throw err;
+    }
+    activeBroker = plan.broker
+        ? { host: plan.broker.host, proxyUrl: plan.proxyUrl }
+        : null;
+    activeProxyEndpoint = plan.proxyEndpoint;
+    activeControl =
+        plan.control && controlPort
+            ? { port: controlPort, token: plan.control.tokenValue, log: onLog }
+            : null;
+    let stopping = false;
+    child.on('exit', (code, signal) => {
+        activeBroker = null;
+        activeProxyEndpoint = null;
+        activeControl = null;
+        if (!stopping) {
+            onLog(`egress proxy exited unexpectedly (code ${code}, signal ${signal})`);
+        }
+    });
+    return {
+        plan,
+        controlPort,
+        stop: () => {
+            stopping = true;
+            activeBroker = null;
+            activeProxyEndpoint = null;
+            activeControl = null;
+            if (!child.killed)
+                child.kill('SIGTERM');
+        },
+    };
+}
+/** 让系统分配一个空闲回环端口（listen(0) 后立即释放，供代理绑定）。 */
+export async function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close(() => (port > 0 ? resolve(port) : reject(new Error('no free port'))));
+        });
+    });
+}

package/dist/sidecar/errors.d.ts

@@ -0,0 +1,22 @@
+import type { SidecarSandboxPosture } from './types.js';
+/** Failed to spawn or hand-shake the sidecar. */
+export declare class SidecarBootError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** A JSON-RPC method call returned an error frame. */
+export declare class SidecarMethodError extends Error {
+    readonly code: number;
+    readonly kind: string | undefined;
+    readonly data: unknown;
+    constructor(message: string, code: number, kind: string | undefined, data: unknown);
+}
+/** Sidecar exited or stopped responding before a request completed. */
+export declare class SidecarShutdownError extends Error {
+    constructor(message: string);
+}
+/** Layer-1 confinement was requested and no backend could wrap the process. */
+export declare class SidecarSandboxUnavailableError extends SidecarBootError {
+    readonly posture: SidecarSandboxPosture;
+    constructor(message: string, posture: SidecarSandboxPosture, cause?: unknown);
+}

package/dist/sidecar/errors.js

@@ -0,0 +1,38 @@
+/** Failed to spawn or hand-shake the sidecar. */
+export class SidecarBootError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'SidecarBootError';
+    }
+}
+/** A JSON-RPC method call returned an error frame. */
+export class SidecarMethodError extends Error {
+    code;
+    kind;
+    data;
+    constructor(message, code, kind, data) {
+        super(message);
+        this.code = code;
+        this.kind = kind;
+        this.data = data;
+        this.name = 'SidecarMethodError';
+    }
+}
+/** Sidecar exited or stopped responding before a request completed. */
+export class SidecarShutdownError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SidecarShutdownError';
+    }
+}
+/** Layer-1 confinement was requested and no backend could wrap the process. */
+export class SidecarSandboxUnavailableError extends SidecarBootError {
+    posture;
+    constructor(message, posture, cause) {
+        super(message, cause);
+        this.posture = posture;
+        this.name = 'SidecarSandboxUnavailableError';
+    }
+}

package/dist/sidecar/exec-sandbox.d.ts

@@ -0,0 +1,48 @@
+import type { SidecarSupervisor } from './supervisor.js';
+import type { SidecarChatStreamRequest } from './types.js';
+export type ExecSandboxEnforcement = 'full' | 'partial' | 'none';
+/** 会话级命令沙箱档：工作区围栏 vs 关闭逐条命令沙箱。 */
+export type ExecPolicy = 'workspace' | 'full';
+export declare function parseExecPolicy(value: unknown): ExecPolicy;
+export interface ExecSandboxCapability {
+    backend: string;
+    enforcement: ExecSandboxEnforcement;
+}
+/**
+ * 一个回合发出的 layer-3 参数。字段全必填——请求类型把它们都设成可选是为了
+ * 让宿主省略整段，而桌面永远发全套，`worldState` 的权限披露也直接读这里。
+ */
+export type ExecSandboxParams = Required<Omit<NonNullable<SidecarChatStreamRequest['execSandbox']>, 'allowedHosts'>> & {
+    allowedHosts: string[] | undefined;
+};
+/**
+ * W4-2/W4-3：从 provider baseUrl 派生出egress 允许列表条目——代理未启用时
+ * agent 唯一合法的出网对端。baseUrl 缺失/不可解析时返回 undefined（沙箱保持
+ * 出网开放；加固永远不能弄断 LLM 通路）。与 layer-1 同样的 sbpl 限制：远端
+ * 条目退化为端口级强制。
+ */
+export declare function deriveEgressAllowListFromBaseUrl(baseUrl: string | undefined): string[] | undefined;
+export declare function getExecSandboxCapability(): ExecSandboxCapability | null;
+/**
+ * 用回合真实会发的 egress 参数问 sidecar：这台机器的后端到底能达到哪一档
+ * 强制。boot 时问一次即可——后端选择只随平台与 egress 变化，两者在一次进程
+ * 生命周期内都是定的。
+ *
+ * 探测失败按「未知能力」处理（保持 null），`buildExecSandbox` 于是不要求
+ * full。宁可少收紧一档，也不能因为一次 RPC 抖动把整个 shell 面判死。
+ */
+export declare function probeExecSandboxCapability(supervisor: SidecarSupervisor): Promise<void>;
+/**
+ * 一个回合的 `execSandbox` 参数。
+ *
+ * `requireFull` 只在探测确认这台机器真能达到 full 时才开。它会在执行前拒掉
+ * 所有达不到 full 的调用，而带 egress 时只有 Seatbelt 能报 full（它按主机
+ * 钉死）——bwrap 与 Landlock 没有按主机管控、Windows 没有改写后端。从平台
+ * 猜测推导过一次，结果是代理一开、Linux 上每一次 shell 调用都被拒。
+ *
+ * `requireBackend` 在沙箱开启时始终开：请求了收容就不能因为没有后端而裸跑。
+ * `policy: 'full'` 关闭这一层（enabled/requireBackend 都为 false）。
+ */
+export declare function buildExecSandbox(writableRoots: string[], options?: {
+    policy?: ExecPolicy;
+}): ExecSandboxParams;

package/dist/sidecar/exec-sandbox.js

@@ -0,0 +1,94 @@
+/**
+ * Layer-3（逐 exec 沙箱）的桌面态势：`execSandbox` 请求参数的唯一构造点。
+ *
+ * 聊天回合（router.ts）与任务回合（task-service.ts）发的是同一份态势，只有
+ * 可写根不同。两边各建一份的时候，`requireFull` 在其中一边改错就只在另一边
+ * 暴露——所以这里收成一个 `buildExecSandbox`。
+ */
+import log from 'electron-log';
+import { llmService } from '../llm/index.js';
+import { getActiveEgressProxyEndpoint } from './egress-proxy.js';
+export function parseExecPolicy(value) {
+    return value === 'full' ? 'full' : 'workspace';
+}
+/**
+ * W4-2/W4-3：从 provider baseUrl 派生出egress 允许列表条目——代理未启用时
+ * agent 唯一合法的出网对端。baseUrl 缺失/不可解析时返回 undefined（沙箱保持
+ * 出网开放；加固永远不能弄断 LLM 通路）。与 layer-1 同样的 sbpl 限制：远端
+ * 条目退化为端口级强制。
+ */
+export function deriveEgressAllowListFromBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return undefined;
+    try {
+        const url = new URL(baseUrl);
+        const host = url.hostname;
+        if (!host)
+            return undefined;
+        return [url.port ? `${host}:${url.port}` : host];
+    }
+    catch {
+        return undefined;
+    }
+}
+let capability = null;
+export function getExecSandboxCapability() {
+    return capability;
+}
+/**
+ * 用回合真实会发的 egress 参数问 sidecar：这台机器的后端到底能达到哪一档
+ * 强制。boot 时问一次即可——后端选择只随平台与 egress 变化，两者在一次进程
+ * 生命周期内都是定的。
+ *
+ * 探测失败按「未知能力」处理（保持 null），`buildExecSandbox` 于是不要求
+ * full。宁可少收紧一档，也不能因为一次 RPC 抖动把整个 shell 面判死。
+ */
+export async function probeExecSandboxCapability(supervisor) {
+    const endpoint = getActiveEgressProxyEndpoint();
+    try {
+        capability = await supervisor.call('sandbox.describe', {
+            network: true,
+            allowedHosts: endpoint
+                ? [endpoint]
+                : deriveEgressAllowListFromBaseUrl(llmService.getSettings().baseUrl),
+        });
+        log.info(`[sidecar] exec sandbox: ${capability.backend} → ${capability.enforcement}`);
+    }
+    catch (err) {
+        capability = null;
+        log.warn('[sidecar] exec sandbox probe failed; not requiring full enforcement', err);
+    }
+}
+/**
+ * 一个回合的 `execSandbox` 参数。
+ *
+ * `requireFull` 只在探测确认这台机器真能达到 full 时才开。它会在执行前拒掉
+ * 所有达不到 full 的调用，而带 egress 时只有 Seatbelt 能报 full（它按主机
+ * 钉死）——bwrap 与 Landlock 没有按主机管控、Windows 没有改写后端。从平台
+ * 猜测推导过一次，结果是代理一开、Linux 上每一次 shell 调用都被拒。
+ *
+ * `requireBackend` 在沙箱开启时始终开：请求了收容就不能因为没有后端而裸跑。
+ * `policy: 'full'` 关闭这一层（enabled/requireBackend 都为 false）。
+ */
+export function buildExecSandbox(writableRoots, options) {
+    const policy = options?.policy ?? 'workspace';
+    const enabled = policy !== 'full' && process.env.STEERABLE_EXEC_SANDBOX !== '0';
+    const endpoint = getActiveEgressProxyEndpoint();
+    return {
+        enabled,
+        writableRoots: enabled ? writableRoots : [],
+        network: true,
+        // P3.2 shell-via-proxy：代理活跃时把 shell 出网收敛到本机代理端点
+        // （HTTP(S) 走代理的 CONNECT 名单；SSH 这类非 HTTP 出网由内核 fail-closed
+        // 拒掉）。代理未启用时退回 baseUrl 派生的远端条目。
+        allowedHosts: endpoint
+            ? [endpoint]
+            : deriveEgressAllowListFromBaseUrl(llmService.getSettings().baseUrl),
+        requireFull: enabled && capability?.enforcement === 'full',
+        requireBackend: enabled,
+        // W4.1.1：Windows 没有命令改写器——把 shell 调用路由到宿主的受限
+        // spawn（win-spawn-helper：受限令牌 + Job Object），而不是以
+        // enforcement:"none" 裸跑。其他平台无害：解析到本地后端就不会走这条。
+        hostSpawn: enabled && process.platform === 'win32',
+    };
+}

package/dist/sidecar/handle.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Optional sidecar handle. `main.ts` calls `setSidecarSupervisor()` after the
+ * sidecar has booted. The sidecar path is default-on (2026-08-26): the
+ * CoreLoop chat path and the LLM provider both route through it. Set
+ * `STEERABLE_USE_SIDECAR=0` to fall back to the in-process providers — also
+ * the automatic behavior when the sidecar failed to start.
+ *
+ * Kept in a dependency-light module (type-only import of the supervisor) so
+ * RPC thin clients (`local-edit`, `skill-loader`) can read the handle without
+ * pulling the LLM-service → storage → Electron graph into pure-Node test
+ * contexts.
+ */
+import type { SidecarSupervisor } from './index.js';
+export declare function setSidecarSupervisor(supervisor: SidecarSupervisor | null): void;
+/**
+ * Register the in-flight boot promise so early callers (e.g. the renderer's
+ * skills request racing sidecar boot) can await readiness instead of
+ * observing a bare `null` and degrading. `main.ts` registers this
+ * synchronously inside `maybeStartSidecar()`, before the first await.
+ */
+export declare function setSidecarSupervisorPending(pending: Promise<SidecarSupervisor | null> | null): void;
+/** The supervised sidecar handle, when the sidecar path is active. */
+export declare function getSidecarSupervisor(): SidecarSupervisor | null;
+export declare function isSidecarEnabled(): boolean;
+/**
+ * Await the sidecar handle through boot: returns the live handle immediately
+ * when already up, otherwise waits on the registered boot promise. Returns
+ * null when the sidecar is disabled, no boot is in flight, boot failed, or
+ * the wait exceeds `timeoutMs` (bounded so a hung python env degrades the
+ * caller to its no-sidecar fallback instead of hanging the request).
+ */
+export declare function whenSidecarSupervisor(timeoutMs?: number): Promise<SidecarSupervisor | null>;