@steerable/agent-shell 0.6.74 → 0.7.1

package/dist/fence-path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `~` 展开后收成真实路径。
+ * 绝对路径按自身解析。相对路径在给了 `baseDir` 时按该目录解析
+ * （项目家目录或对话工作区），否则按进程当前目录解析。
+ * 围栏比较前路径与根都要过这一步，这样 `/tmp` 与 `/private/tmp` 是同一目录。
+ */
+export declare function resolveFencePath(inputPath: string, baseDir?: string | null): string;
+/** `~` 展开后 resolve，再解析符号链接。相对路径按进程当前目录解析。 */
+export declare function expandFencePath(inputPath: string): string;
+/**
+ * `target` 是否就是 `root`，或落在它里面。两边都先解析符号链接，
+ * 所以 `/tmp` 与 `/private/tmp` 是同一目录，指向外面的链接不算在里面。
+ */
+export declare function canonicalPathInside(root: string, target: string): boolean;
+/** 把已 resolve 的绝对路径收成真实路径。解析失败时保留原路径。 */
+export declare function canonicalFencePath(resolved: string): string;

package/dist/fence-path.js

@@ -0,0 +1,54 @@
+import { realpathSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * `~` 展开后收成真实路径。
+ * 绝对路径按自身解析。相对路径在给了 `baseDir` 时按该目录解析
+ * （项目家目录或对话工作区），否则按进程当前目录解析。
+ * 围栏比较前路径与根都要过这一步，这样 `/tmp` 与 `/private/tmp` 是同一目录。
+ */
+export function resolveFencePath(inputPath, baseDir) {
+    const expanded = inputPath.startsWith('~')
+        ? path.join(os.homedir(), inputPath.slice(1))
+        : inputPath;
+    if (path.isAbsolute(expanded) || !baseDir?.trim()) {
+        return canonicalFencePath(path.resolve(expanded));
+    }
+    const base = canonicalFencePath(path.resolve(baseDir));
+    return canonicalFencePath(path.resolve(base, expanded));
+}
+/** `~` 展开后 resolve，再解析符号链接。相对路径按进程当前目录解析。 */
+export function expandFencePath(inputPath) {
+    return resolveFencePath(inputPath);
+}
+/**
+ * `target` 是否就是 `root`，或落在它里面。两边都先解析符号链接，
+ * 所以 `/tmp` 与 `/private/tmp` 是同一目录，指向外面的链接不算在里面。
+ */
+export function canonicalPathInside(root, target) {
+    const relative = path.relative(canonicalFencePath(path.resolve(root)), canonicalFencePath(path.resolve(target)));
+    return relative === '' || (relative !== '..' &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+/** 把已 resolve 的绝对路径收成真实路径。解析失败时保留原路径。 */
+export function canonicalFencePath(resolved) {
+    const missing = [];
+    let current = resolved;
+    for (;;) {
+        try {
+            const real = realpathSync(current);
+            return missing.reduceRight((dir, name) => path.join(dir, name), real);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                return resolved;
+            const parent = path.dirname(current);
+            if (parent === current)
+                return resolved;
+            missing.push(path.basename(current));
+            current = parent;
+        }
+    }
+}

package/dist/host/runtime.d.ts

@@ -1,16 +1,3 @@
-/**
- * HostRuntime —— CS（Electron 主进程）与 BS（headless HTTP server）共享的
- * 服务装配与生命周期。
- *
- * 历史上 main.ts 与 server/index.ts 各自装配同一份服务（LocalExecutor /
- * ToolRouter / TaskService / sidecar …），两处逐行重复；BS 曾漏接
- * TaskService 导致模型退化成 local_exec_shell + nohup 的"假后台"。本模块
- * 把装配收敛为一处，两个入口只保留各自的广播机制（IPC webContents.send
- * vs SSE 总线）与生命周期（Electron app 事件 vs SIGINT/SIGTERM）。
- *
- * 这也是阶段 3 上提框架后 `@steerable/agent-shell` 的核心装配件：场景包
- * （ScenarioPack）的服务/工具贡献在 0.3 逐槽接入本模块。
- */
 import { LocalExecutor, type LocalExecRequest, type LocalExecResult } from '../local-executor.js';
 import { LocalScriptRegistry } from '../local-script-registry.js';
 import { TerminalManager } from '../terminal-manager.js';

package/dist/host/runtime.js

@@ -11,6 +11,7 @@
  * 这也是阶段 3 上提框架后 `@steerable/agent-shell` 的核心装配件：场景包
  * （ScenarioPack）的服务/工具贡献在 0.3 逐槽接入本模块。
  */
+import { homedir } from 'node:os';
 import { LocalExecutor, setDefaultExecTimeoutMs, } from '../local-executor.js';
 import { LocalScriptRegistry } from '../local-script-registry.js';
 import { TerminalManager } from '../terminal-manager.js';
@@ -27,6 +28,7 @@ import { LOCAL_SCOPE, closeStorage, getPackDbAccess, getScopedStore, initializeS
 import { subscribeChatActivity } from '../storage/chat-activity.js';
 import { getUserDataDir } from '../runtime.js';
 import { acquireInstanceLease, bindStorageInstance, } from '../storage/process-locks.js';
+import { approvalCwdFence, hostApprovalCategoryLabel } from '../sidecar/approval-label.js';
 import { createApprovalBridge } from '../sidecar/reverse-approval.js';
 import { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
 import { startHostSidecar, shutdownHostSidecar } from '../sidecar/boot.js';
@@ -214,6 +216,30 @@ export async function createHostRuntime(options) {
         broadcast,
         hasWindow,
         onLog: (line) => onLog(line),
+        categoryLabel: (toolName, category) => {
+            const declaredLabel = toolRouter.getSchemaByName(toolName)?.approval?.label;
+            return hostApprovalCategoryLabel({
+                category,
+                toolName,
+                ...(declaredLabel ? { declaredLabel } : {}),
+            });
+        },
+        outsideWorkspace: async ({ toolName, arguments: args, chatId }) => {
+            if (!chatId || !localBackendRouter)
+                return false;
+            const project = await localBackendRouter.resolveChatProject(chatId);
+            const workspaceRoot = project
+                ? null
+                : await localBackendRouter.resolveChatWorkspaceRoot(chatId);
+            return approvalCwdFence({
+                toolName,
+                cwd: args.cwd,
+                projectRoot: project?.folderPath ?? null,
+                workspaceRoot,
+                sourceFolders: project?.sourceFolders ?? [],
+                home: homedir(),
+            });
+        },
     });
     const askUserBridge = createAskUserBridge({
         broadcast,

package/dist/host-tools.d.ts

@@ -47,6 +47,7 @@ export declare function resolveHostTools(config?: HostToolsConfig | null): Resol
 export declare function resolveApprovalMode(value: unknown): ApprovalMode;
 /**
  * 产品 `approval: "off"` 或 STEERABLE_APPROVAL=0 时本轮不挂 host 审批。
+ * 环境变量关掉审批层后，破坏性工具由工具路由拒绝。命令行放行用 `--approve allow-all`。
  * 环境变量是调试逃生口；产品字段是装配真源。
  */
 export declare function isApprovalEnabled(input?: {

package/dist/host-tools.js

@@ -139,6 +139,7 @@ export function resolveApprovalMode(value) {
 }
 /**
  * 产品 `approval: "off"` 或 STEERABLE_APPROVAL=0 时本轮不挂 host 审批。
+ * 环境变量关掉审批层后，破坏性工具由工具路由拒绝。命令行放行用 `--approve allow-all`。
  * 环境变量是调试逃生口；产品字段是装配真源。
  */
 export function isApprovalEnabled(input = {}) {

package/dist/i18n.d.ts

@@ -20,4 +20,6 @@ export declare function configureI18n(options: {
 export declare function getLocale(): string;
 export declare function setLocale(locale: string): boolean;
 export declare function t(message: string, params?: Record<string, string | number>): string;
+/** Translate `message` for one request without changing the process locale. */
+export declare function tFor(locale: string, message: string, params?: Record<string, string | number>): string;
 export declare function resetI18nForTests(): void;

package/dist/i18n.js

@@ -74,7 +74,12 @@ export function setLocale(locale) {
     return true;
 }
 export function t(message, params) {
-    const table = current === SOURCE_LOCALE ? undefined : catalogs[current];
+    return tFor(current, message, params);
+}
+/** Translate `message` for one request without changing the process locale. */
+export function tFor(locale, message, params) {
+    const normalized = normalizeLocale(locale) ?? SOURCE_LOCALE;
+    const table = normalized === SOURCE_LOCALE ? undefined : catalogs[normalized];
     const template = table?.[message] ?? message;
     return formatMessage(template, params);
 }

package/dist/json-store.d.ts

@@ -2,6 +2,7 @@ export interface JsonStore<T extends Record<string, unknown>> {
     get<Key extends keyof T>(key: Key): T[Key];
     get<Key extends keyof T>(key: Key, defaultValue: Required<T>[Key]): Required<T>[Key];
     set<Key extends keyof T>(key: Key, value?: T[Key]): void;
+    mutate<Key extends keyof T>(key: Key, update: (current: T[Key]) => T[Key]): T[Key];
 }
 export declare function createJsonStore<T extends Record<string, unknown>>(options: {
     name: string;

package/dist/json-store.js

@@ -7,21 +7,23 @@
  * 解析会塌成 namespace——所以这里声明用到的最小接口并做一次强转，不依赖
  * 它的声明文件。
  */
+import fs from 'node:fs';
+import path from 'node:path';
 import ConfImport from 'conf';
 import { getUserDataDir } from './runtime.js';
 import { fileLockPath } from './storage/process-locks.js';
 import { acquireWriteLease } from './storage/write-lease.js';
 const Conf = ConfImport;
 export function createJsonStore(options) {
+    const cwd = getUserDataDir();
     const store = new Conf({
-        cwd: getUserDataDir(),
-        name: options.name,
-        defaults: options.defaults,
+        cwd,
+        configName: options.name,
+        defaults: defaultsFromLegacy(cwd, options.name, options.defaults),
     });
     const lockPath = fileLockPath(getUserDataDir(), options.name);
     return {
         get: store.get.bind(store),
-        // set is wrapped below so two processes cannot clobber a read-modify-write.
         set(key, value) {
             const lease = acquireWriteLease(lockPath, 5_000);
             try {
@@ -31,5 +33,49 @@ export function createJsonStore(options) {
                 lease.release();
             }
         },
+        mutate(key, update) {
+            const lease = acquireWriteLease(lockPath, 5_000);
+            try {
+                const next = update(store.get(key));
+                store.set(key, next);
+                return next;
+            }
+            finally {
+                lease.release();
+            }
+        },
     };
 }
+/**
+ * Older builds passed `name` to conf, which only reads `configName` and
+ * therefore stored every registry in `config.json`. Copy this registry's
+ * keys once, and leave the old file in place.
+ */
+function defaultsFromLegacy(cwd, name, defaults) {
+    if (defaults === undefined)
+        return undefined;
+    const target = path.join(cwd, `${name}.json`);
+    const legacy = path.join(cwd, 'config.json');
+    if (fs.existsSync(target) || !fs.existsSync(legacy))
+        return defaults;
+    const record = readRecord(legacy);
+    if (!record)
+        return defaults;
+    const seeded = { ...defaults };
+    for (const key of Object.keys(defaults)) {
+        if (key in record)
+            seeded[key] = record[key];
+    }
+    return seeded;
+}
+function readRecord(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/local-backend/coreloop-stream.d.ts

@@ -31,6 +31,13 @@ export interface CoreLoopToolAction {
         backend?: string;
         enforcement: string;
     };
+    /** Session-allow reuse lifted onto the stream chunk. */
+    approval?: {
+        kind?: string;
+        category?: string;
+        cached?: boolean;
+        waitMs?: number;
+    };
 }
 export interface CoreLoopTurnOutcome {
     status: string;
@@ -71,6 +78,27 @@ export interface SkillTurnContext {
     /** 智能体的「加载全部技能」:catalog 无视条件全量列出。 */
     ignoreConditions: boolean;
 }
+/** 一轮发给 sidecar 的工具。`mode` 与 `approvalCategory` 是可选线协议字段。 */
+export interface TurnToolWire {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    mode?: string;
+    approvalCategory?: string;
+}
+/**
+ * 把宿主工具 schema 收成线协议上的一项。未声明审批类别时不带 `approvalCategory`，
+ * sidecar 按工具名做类别。
+ */
+export declare function toTurnTool(schema: {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    mode?: string;
+    approval?: {
+        category?: string;
+    } | null;
+}): TurnToolWire;
 export interface StreamCoreLoopTurnOptions {
     supervisor: SidecarSupervisor;
     chatId: string;
@@ -86,11 +114,7 @@ export interface StreamCoreLoopTurnOptions {
      */
     resume?: boolean;
     messages: LlmMessage[];
-    tools: Array<{
-        name: string;
-        description: string;
-        inputSchema: unknown;
-    }>;
+    tools: TurnToolWire[];
     provider: string;
     model: string;
     baseUrl?: string;

package/dist/local-backend/coreloop-stream.js

@@ -11,6 +11,123 @@
  * sidecar failed to start, the router fails loud with a 503 — there is no
  * in-process fallback loop or sidecar opt-out.
  */
+/** Markers an older engine left inside the tool-result preview JSON. */
+function markersFromToolPreview(preview) {
+    if (!preview || preview[0] !== '{')
+        return {};
+    const record = previewData(preview);
+    if (!record)
+        return {};
+    const sandbox = record._sandbox;
+    const approval = record._approval;
+    return {
+        ...(sandbox && typeof sandbox === 'object' && !Array.isArray(sandbox)
+            && typeof sandbox.enforcement === 'string'
+            ? { sandbox: sandbox }
+            : {}),
+        ...(approval && typeof approval === 'object' && !Array.isArray(approval)
+            ? { approval: approval }
+            : {}),
+    };
+}
+function previewData(preview) {
+    try {
+        const parsed = JSON.parse(preview);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        const data = parsed.data;
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            return undefined;
+        return data;
+    }
+    catch {
+        // The published loop cuts the preview at 300 characters and appends an
+        // ellipsis. The marker objects are placed first so they are still intact.
+        return {
+            _sandbox: objectAfterKey(preview, '_sandbox'),
+            _approval: objectAfterKey(preview, '_approval'),
+        };
+    }
+}
+function objectAfterKey(text, key) {
+    const needle = `"${key}"`;
+    let from = 0;
+    while (from < text.length) {
+        const found = text.indexOf(needle, from);
+        if (found < 0)
+            return undefined;
+        const colon = text.indexOf(':', found + needle.length);
+        if (colon < 0)
+            return undefined;
+        let index = colon + 1;
+        while (text[index] === ' ' || text[index] === '\n' || text[index] === '\t')
+            index += 1;
+        if (text[index] !== '{') {
+            from = found + needle.length;
+            continue;
+        }
+        const end = matchingBrace(text, index);
+        if (end < 0)
+            return undefined;
+        try {
+            const value = JSON.parse(text.slice(index, end + 1));
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                return value;
+            }
+        }
+        catch {
+            // The cut landed inside this object. A later copy of the key will not
+            // be more complete.
+            return undefined;
+        }
+        from = found + needle.length;
+    }
+    return undefined;
+}
+function matchingBrace(text, open) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let index = open; index < text.length; index += 1) {
+        const char = text[index] ?? '';
+        if (inString) {
+            if (escape)
+                escape = false;
+            else if (char === '\\')
+                escape = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === '{')
+            depth += 1;
+        else if (char === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+/**
+ * 把宿主工具 schema 收成线协议上的一项。未声明审批类别时不带 `approvalCategory`，
+ * sidecar 按工具名做类别。
+ */
+export function toTurnTool(schema) {
+    const tool = {
+        name: schema.name,
+        description: schema.description,
+        inputSchema: schema.inputSchema,
+    };
+    if (schema.mode)
+        tool.mode = schema.mode;
+    const category = schema.approval?.category;
+    if (category)
+        tool.approvalCategory = category;
+    return tool;
+}
 /**
  * Active CoreLoop turns by chatId — lets the main process route a mid-turn
  * steer (user typed while the turn runs) to the right sidecar stream without
@@ -145,6 +262,8 @@ export async function streamCoreLoopTurn(options) {
                 description: t.description,
                 parameters: t.inputSchema ?? { type: 'object', properties: {} },
             },
+            ...(t.mode ? { mode: t.mode } : {}),
+            ...(t.approvalCategory ? { approvalCategory: t.approvalCategory } : {}),
         })),
     };
     // Track in-flight tool calls so results can be paired with their arguments
@@ -208,6 +327,7 @@ export async function streamCoreLoopTurn(options) {
                 if (chunk.toolResult) {
                     const started = pendingCalls.get(chunk.toolResult.id);
                     pendingCalls.delete(chunk.toolResult.id);
+                    const lifted = markersFromToolPreview(chunk.toolResult.resultPreview);
                     options.onToolAction?.({
                         id: chunk.toolResult.id,
                         tool: chunk.toolResult.name,
@@ -216,7 +336,8 @@ export async function streamCoreLoopTurn(options) {
                         result: chunk.toolResult.resultPreview,
                         error: chunk.toolResult.error,
                         durationMs: chunk.toolResult.durationMs,
-                        sandbox: chunk.toolResult.sandbox,
+                        sandbox: chunk.toolResult.sandbox ?? lifted.sandbox,
+                        approval: chunk.toolResult.approval ?? lifted.approval,
                     });
                 }
                 if (chunk.notice) {

package/dist/local-backend/fork-copy.d.ts

@@ -0,0 +1,9 @@
+/** 无项目会话工作区复制上限。产品配置 `forkWorkspaceMaxBytes` 可以改。 */
+export declare const DEFAULT_FORK_WORKSPACE_MAX_BYTES: number;
+/** 目录里普通文件的字节数。不跟随符号链接。目录不存在时为 0。 */
+export declare function directorySizeBytes(root: string): number;
+/** 复制目录。源不存在时什么也不做。目标已存在则失败，避免盖住别的会话。 */
+export declare function copyForkDirectory(src: string, dst: string): Promise<void>;
+export declare function removeForkDirectory(dir: string): Promise<void>;
+/** 把旧会话的附件目录和工作区前缀换成新会话的。只换完整路径前缀。 */
+export declare function forkPathRewriter(oldChatId: string, newChatId: string): (text: string) => string;

package/dist/local-backend/fork-copy.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { chatAttachmentsDirPath } from '../attachments.js';
+import { canonicalFencePath } from '../fence-path.js';
+import { replacePathPrefix } from './history-edit.js';
+import { chatWorkspacePath } from '../project-home.js';
+/** 无项目会话工作区复制上限。产品配置 `forkWorkspaceMaxBytes` 可以改。 */
+export const DEFAULT_FORK_WORKSPACE_MAX_BYTES = 500 * 1024 * 1024;
+/** 目录里普通文件的字节数。不跟随符号链接。目录不存在时为 0。 */
+export function directorySizeBytes(root) {
+    if (!fs.existsSync(root))
+        return 0;
+    let total = 0;
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            break;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            try {
+                total += fs.statSync(full).size;
+            }
+            catch {
+                // 统计期间文件消失则跳过。
+            }
+        }
+    }
+    return total;
+}
+/** 复制目录。源不存在时什么也不做。目标已存在则失败，避免盖住别的会话。 */
+export async function copyForkDirectory(src, dst) {
+    if (!fs.existsSync(src))
+        return;
+    await fs.promises.cp(src, dst, {
+        recursive: true,
+        errorOnExist: true,
+        verbatimSymlinks: true,
+    });
+}
+export async function removeForkDirectory(dir) {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+}
+/** 登记路径和它的真实路径都要换，`/tmp` 与 `/private/tmp` 指向同一目录。 */
+function forkPrefixPairs(from, to) {
+    const pairs = [[from, to]];
+    const realFrom = canonicalFencePath(path.resolve(from));
+    const realTo = canonicalFencePath(path.resolve(to));
+    if (realFrom !== from)
+        pairs.push([realFrom, realTo]);
+    return pairs;
+}
+/** 把旧会话的附件目录和工作区前缀换成新会话的。只换完整路径前缀。 */
+export function forkPathRewriter(oldChatId, newChatId) {
+    const pairs = [
+        ...forkPrefixPairs(chatAttachmentsDirPath(oldChatId), chatAttachmentsDirPath(newChatId)),
+        ...forkPrefixPairs(chatWorkspacePath(oldChatId), chatWorkspacePath(newChatId)),
+    ].sort((left, right) => right[0].length - left[0].length);
+    return (text) => pairs.reduce((current, [from, to]) => replacePathPrefix(current, from, to), text);
+}

package/dist/local-backend/history-edit.d.ts

@@ -23,5 +23,15 @@ export declare function rewindFrom(messages: readonly StoredTurn[]): {
     deleteFromId: string;
     removed: number;
 } | null;
-/** Newest-first history copied in time order. */
-export declare function forkHistory(messages: readonly StoredTurn[]): HistoryWrite[];
+/**
+ * Replace `from` only when it is a complete path prefix: the next character
+ * is a separator or the end of the string, and the previous character does
+ * not continue a path. Letters and digits count in any script, so a Han
+ * character glues the same way an ASCII letter does. A longer name that
+ * merely starts with the same characters is left alone.
+ * On Windows the match ignores letter case and treats `/` and `\` as the
+ * same separator.
+ */
+export declare function replacePathPrefix(text: string, from: string, to: string, platform?: NodeJS.Platform): string;
+/** Newest-first history copied in time order. `rewrite` updates copied paths. */
+export declare function forkHistory(messages: readonly StoredTurn[], rewrite?: (text: string) => string): HistoryWrite[];