@steerable/agent-shell 0.6.15

package/dist/local-backend/worktree-service.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 4.6b Worktree（git worktree 隔离）。
+ *
+ * 在绑定项目的仓库里管理隔离工作区：`<项目根>/.steerable/worktrees/<name>`
+ * + 分支 `steerable/<name>`。任务（task_run worktree:true）在隔离区里跑，
+ * 主检出不被触碰；完成后由用户选择「合并到主仓」（worktree 内提交 +
+ * 主仓 merge）或「丢弃」（remove + 删分支）。
+ *
+ * 位置选择的取舍：worktree 放在项目根**之内**（而不是 sibling 目录），
+ * 这样既有的项目围栏（writableRoots = 项目根、applyProjectCwdSandbox）
+ * 天然覆盖它，无需为主检出之外的目录开洞；`.steerable/` 写进
+ * `.git/info/exclude`（仓库本地、不动用户的 .gitignore），主检出的
+ * `git status` 保持干净。
+ *
+ * 本模块只依赖注入的 git 执行器与项目根解析器——不 import electron，
+ * 保持纯 Node 可测（与 project-registry.ts 同一模式）。
+ */
+export interface WorktreeInfo {
+    /** worktree 目录名（也是分支名的 slug 部分）。 */
+    name: string;
+    path: string;
+    branch: string;
+}
+export interface WorktreeProject {
+    name: string;
+    folderPath: string;
+}
+/** git 执行缝：默认 execFile；测试可注入假实现。 */
+export type GitRunner = (args: string[], cwd: string) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/** worktree 名 → 目录/分支可用的 slug（小写字母数字中划线，防爆目录注入）。 */
+export declare function slugifyWorktreeName(raw: string): string;
+export declare class WorktreeService {
+    private readonly deps;
+    constructor(deps: {
+        resolveProject: (chatId: string) => WorktreeProject | null;
+        runGit?: GitRunner;
+    });
+    private git;
+    /** 项目根下的托管 worktree 根目录。 */
+    private managedRoot;
+    private requireProject;
+    /** 校验目标确是 git 仓库（worktree 子命令只在仓库里才有意义）。 */
+    private requireGitRepo;
+    /**
+     * 把 `.steerable/` 写进 `.git/info/exclude`（仓库本地排除，不动用户的
+     * .gitignore），让托管 worktree 目录不出现在主检出的 git status 里。
+     * 幂等。
+     */
+    private ensureGitInfoExclude;
+    /**
+     * 创建隔离 worktree：分支 `steerable/<name>` 从当前 HEAD 切出。
+     * 同名已存在时直接复用（幂等——模型重试不该炸掉已建好的工作区）。
+     */
+    createWorktree(chatId: string, rawName?: string): Promise<WorktreeInfo>;
+    /** 列出本项目的托管 worktree（只认 .steerable/worktrees 下的）。 */
+    listWorktrees(chatId: string): Promise<WorktreeInfo[]>;
+    /**
+     * 移除 worktree。`deleteBranch` 同时删掉 `steerable/<name>` 分支
+     * （丢弃语义）；保留分支用于合并后的清理（合并后分支引用留着无害，
+     * 但默认删掉保持分支列表干净——已合并的分支删除是安全的）。
+     */
+    removeWorktree(chatId: string, name: string, options?: {
+        deleteBranch?: boolean;
+    }): Promise<{
+        removed: string;
+        branchDeleted: string | null;
+    }>;
+    /**
+     * 把 worktree 里的改动合并回主仓当前分支：
+     *   1. worktree 内 `git add -A` + 提交（任务 agent 只改文件，不提交）；
+     *   2. 主仓 `git merge --no-ff <branch>`；
+     *   3. 移除 worktree 并删除已合并分支。
+     * 冲突时 `merge --abort` 把主检出还原到干净状态（主检出是用户的工作区，
+     * 不能留半合并的冲突现场），worktree 与分支保留，错误如实上抛——用户
+     * 可稍后重试或手工处理。
+     */
+    mergeWorktree(chatId: string, name: string, commitMessage: string): Promise<{
+        merged: string;
+        commit: string | null;
+    }>;
+}

package/dist/local-backend/worktree-service.js

@@ -0,0 +1,243 @@
+/**
+ * 4.6b Worktree（git worktree 隔离）。
+ *
+ * 在绑定项目的仓库里管理隔离工作区：`<项目根>/.steerable/worktrees/<name>`
+ * + 分支 `steerable/<name>`。任务（task_run worktree:true）在隔离区里跑，
+ * 主检出不被触碰；完成后由用户选择「合并到主仓」（worktree 内提交 +
+ * 主仓 merge）或「丢弃」（remove + 删分支）。
+ *
+ * 位置选择的取舍：worktree 放在项目根**之内**（而不是 sibling 目录），
+ * 这样既有的项目围栏（writableRoots = 项目根、applyProjectCwdSandbox）
+ * 天然覆盖它，无需为主检出之外的目录开洞；`.steerable/` 写进
+ * `.git/info/exclude`（仓库本地、不动用户的 .gitignore），主检出的
+ * `git status` 保持干净。
+ *
+ * 本模块只依赖注入的 git 执行器与项目根解析器——不 import electron，
+ * 保持纯 Node 可测（与 project-registry.ts 同一模式）。
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+const defaultGitRunner = (args, cwd) => new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error) {
+            reject(new Error(`git ${args.join(' ')} 失败: ${stderr.trim() || error.message}`));
+            return;
+        }
+        resolve({ stdout, stderr });
+    });
+});
+/** worktree 名 → 目录/分支可用的 slug（小写字母数字中划线，防爆目录注入）。 */
+export function slugifyWorktreeName(raw) {
+    const slug = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9一-鿿]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40);
+    return slug || 'wt';
+}
+export class WorktreeService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    git(cwd, args) {
+        return (this.deps.runGit ?? defaultGitRunner)(args, cwd);
+    }
+    /** 项目根下的托管 worktree 根目录。 */
+    managedRoot(projectRoot) {
+        return path.join(projectRoot, '.steerable', 'worktrees');
+    }
+    requireProject(chatId) {
+        const project = this.deps.resolveProject(chatId);
+        if (!project) {
+            throw new Error('worktree 需要对话绑定项目（git 仓库）——请先把本对话关联到一个项目。');
+        }
+        return project;
+    }
+    /** 校验目标确是 git 仓库（worktree 子命令只在仓库里才有意义）。 */
+    async requireGitRepo(projectRoot) {
+        try {
+            await this.git(projectRoot, ['rev-parse', '--git-dir']);
+        }
+        catch {
+            throw new Error(`项目目录不是 git 仓库：${projectRoot}`);
+        }
+    }
+    /**
+     * 把 `.steerable/` 写进 `.git/info/exclude`（仓库本地排除，不动用户的
+     * .gitignore），让托管 worktree 目录不出现在主检出的 git status 里。
+     * 幂等。
+     */
+    async ensureGitInfoExclude(projectRoot) {
+        const { stdout } = await this.git(projectRoot, [
+            'rev-parse',
+            '--git-path',
+            'info/exclude',
+        ]);
+        const excludePath = path.join(projectRoot, stdout.trim());
+        const existing = existsSync(excludePath)
+            ? await readFile(excludePath, 'utf8')
+            : '';
+        if (existing.split('\n').some((line) => line.trim() === '.steerable/')) {
+            return;
+        }
+        await mkdir(path.dirname(excludePath), { recursive: true });
+        await appendFile(excludePath, '.steerable/\n', 'utf8');
+    }
+    /**
+     * 创建隔离 worktree：分支 `steerable/<name>` 从当前 HEAD 切出。
+     * 同名已存在时直接复用（幂等——模型重试不该炸掉已建好的工作区）。
+     */
+    async createWorktree(chatId, rawName) {
+        const project = this.requireProject(chatId);
+        await this.requireGitRepo(project.folderPath);
+        const name = slugifyWorktreeName(rawName ?? '');
+        const suffix = name === 'wt' ? `-${Date.now().toString(36)}` : '';
+        const finalName = `${name}${suffix}`;
+        const branch = `steerable/${finalName}`;
+        const worktreePath = path.join(this.managedRoot(project.folderPath), finalName);
+        const existing = await this.listWorktrees(chatId);
+        const found = existing.find((w) => w.name === finalName);
+        if (found)
+            return found;
+        await this.ensureGitInfoExclude(project.folderPath);
+        await mkdir(this.managedRoot(project.folderPath), { recursive: true });
+        await this.git(project.folderPath, [
+            'worktree',
+            'add',
+            worktreePath,
+            '-b',
+            branch,
+        ]);
+        // 返回 realpath（与 listWorktrees 一致）——任务表存它、沙箱围栏用它，
+        // 字符串前缀比较不能落在未解析的符号链接形式上（macOS /var 软链）。
+        return { name: finalName, path: realpathSync(worktreePath), branch };
+    }
+    /** 列出本项目的托管 worktree（只认 .steerable/worktrees 下的）。 */
+    async listWorktrees(chatId) {
+        const project = this.requireProject(chatId);
+        await this.requireGitRepo(project.folderPath);
+        const { stdout } = await this.git(project.folderPath, [
+            'worktree',
+            'list',
+            '--porcelain',
+        ]);
+        // git 报的是 realpath（macOS 上 /var → /private/var），而项目根可能
+        // 是未解析的符号链接路径——项目根（必然存在）过 realpath 再拼托管后缀，
+        // 否则前缀匹配在 macOS 上永远落空（managedRoot 本身可能还没建，
+        // 不能直接 realpath）。
+        const root = path.join(realpathSync(project.folderPath), '.steerable', 'worktrees');
+        const out = [];
+        let currentPath = null;
+        let currentBranch = '';
+        const flush = () => {
+            if (!currentPath)
+                return;
+            const normalized = realpathSync(currentPath);
+            if (normalized.startsWith(root + path.sep) &&
+                currentBranch.startsWith('refs/heads/steerable/')) {
+                out.push({
+                    name: path.basename(normalized),
+                    path: normalized,
+                    branch: currentBranch.slice('refs/heads/'.length),
+                });
+            }
+            currentPath = null;
+            currentBranch = '';
+        };
+        for (const line of stdout.split('\n')) {
+            if (line.startsWith('worktree ')) {
+                flush();
+                currentPath = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                currentBranch = line.slice('branch '.length);
+            }
+            else if (line === '') {
+                flush();
+            }
+        }
+        flush();
+        return out;
+    }
+    /**
+     * 移除 worktree。`deleteBranch` 同时删掉 `steerable/<name>` 分支
+     * （丢弃语义）；保留分支用于合并后的清理（合并后分支引用留着无害，
+     * 但默认删掉保持分支列表干净——已合并的分支删除是安全的）。
+     */
+    async removeWorktree(chatId, name, options = {}) {
+        const project = this.requireProject(chatId);
+        const worktrees = await this.listWorktrees(chatId);
+        const target = worktrees.find((w) => w.name === name || w.path === name);
+        if (!target) {
+            throw new Error(`未找到托管 worktree：${name}`);
+        }
+        // --force：worktree 里可能躺着任务留下的未提交改动，移除语义就是不要了。
+        await this.git(project.folderPath, [
+            'worktree',
+            'remove',
+            '--force',
+            target.path,
+        ]);
+        let branchDeleted = null;
+        if (options.deleteBranch ?? true) {
+            try {
+                await this.git(project.folderPath, ['branch', '-D', target.branch]);
+                branchDeleted = target.branch;
+            }
+            catch {
+                // 分支可能已被删/从未创建成功——移除 worktree 本身已成功，不因此翻车。
+            }
+        }
+        return { removed: target.path, branchDeleted };
+    }
+    /**
+     * 把 worktree 里的改动合并回主仓当前分支：
+     *   1. worktree 内 `git add -A` + 提交（任务 agent 只改文件，不提交）；
+     *   2. 主仓 `git merge --no-ff <branch>`；
+     *   3. 移除 worktree 并删除已合并分支。
+     * 冲突时 `merge --abort` 把主检出还原到干净状态（主检出是用户的工作区，
+     * 不能留半合并的冲突现场），worktree 与分支保留，错误如实上抛——用户
+     * 可稍后重试或手工处理。
+     */
+    async mergeWorktree(chatId, name, commitMessage) {
+        const project = this.requireProject(chatId);
+        const worktrees = await this.listWorktrees(chatId);
+        const target = worktrees.find((w) => w.name === name || w.path === name);
+        if (!target) {
+            throw new Error(`未找到托管 worktree：${name}`);
+        }
+        let commit = null;
+        const { stdout: status } = await this.git(target.path, [
+            'status',
+            '--porcelain',
+        ]);
+        if (status.trim()) {
+            await this.git(target.path, ['add', '-A']);
+            await this.git(target.path, ['commit', '-m', commitMessage]);
+            const { stdout: sha } = await this.git(target.path, [
+                'rev-parse',
+                'HEAD',
+            ]);
+            commit = sha.trim();
+        }
+        try {
+            await this.git(project.folderPath, [
+                'merge',
+                '--no-ff',
+                '-m',
+                `Merge ${target.branch}`,
+                target.branch,
+            ]);
+        }
+        catch (err) {
+            // 主检出是用户的工作区——冲突时还原干净，绝不留 MERGE_HEAD/冲突标记。
+            await this.git(project.folderPath, ['merge', '--abort']).catch(() => { });
+            throw err;
+        }
+        await this.removeWorktree(chatId, target.name, { deleteBranch: true });
+        return { merged: target.branch, commit };
+    }
+}

package/dist/local-edit.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 结构化文件编辑（W6-1）的桌面侧薄客户端。
+ *
+ * 定位/替换/统一 diff 算法已下沉到框架，单一真源是 Python 的
+ * `steerable_sidecar/file_edit.py`（headless 与 ACP 工作区工具共用同一实现），
+ * 通过 sidecar 的 `workspace.apply_edits` RPC 调用。本模块只做线协议转换与
+ * 错误映射；文件读写、版本令牌、原子落盘、同文件串行队列仍在 local-executor。
+ */
+export interface EditOp {
+    /** 定位锚点（要被替换掉的原文）。 */
+    oldText: string;
+    /** 替换后的新文。 */
+    newText: string;
+}
+export type MatchLevel = 'exact' | 'trim' | 'unicode';
+/** 一次命中在原文中的位置与跨度（供工具卡/测试断言用）。 */
+export interface EditMatch {
+    level: MatchLevel;
+    startLine: number;
+    oldLineCount: number;
+}
+export interface ApplyEditsResult {
+    /** 应用全部编辑后的新文件内容。 */
+    content: string;
+    /** 统一 diff（unified diff，3 行上下文），供工具卡渲染。 */
+    diff: string;
+    matches: EditMatch[];
+}
+export declare class EditError extends Error {
+    readonly code: 'empty_old' | 'not_found' | 'ambiguous' | 'overlap' | 'no_edits';
+    constructor(message: string, code: 'empty_old' | 'not_found' | 'ambiguous' | 'overlap' | 'no_edits');
+}
+/** 把 sidecar 的 `workspace.apply_edits` 响应映射为桌面结果形状。 */
+export declare function buildApplyEditsResult(result: {
+    content: string;
+    diff: string;
+    matches: Array<{
+        level: MatchLevel;
+        startLine: number;
+        oldLineCount: number;
+    }>;
+}): ApplyEditsResult;
+/**
+ * 在 sidecar（Python 真源）里对 `content` 应用 `edits`。只在回合内可达——
+ * 编辑工具经 reverse `tool.invoke` 触发，此刻 sidecar 必在运行；sidecar 不可用
+ * 时抛出 EditError 之外的错误，由 local-executor 的兜底分支转成失败结果。
+ */
+export declare function applyEdits(content: string, edits: EditOp[], filePath?: string): Promise<ApplyEditsResult>;

package/dist/local-edit.js

@@ -0,0 +1,44 @@
+/**
+ * 结构化文件编辑（W6-1）的桌面侧薄客户端。
+ *
+ * 定位/替换/统一 diff 算法已下沉到框架，单一真源是 Python 的
+ * `steerable_sidecar/file_edit.py`（headless 与 ACP 工作区工具共用同一实现），
+ * 通过 sidecar 的 `workspace.apply_edits` RPC 调用。本模块只做线协议转换与
+ * 错误映射；文件读写、版本令牌、原子落盘、同文件串行队列仍在 local-executor。
+ */
+import { getSidecarSupervisor } from './sidecar/handle.js';
+import { SidecarMethodError } from './sidecar/errors.js';
+export class EditError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'EditError';
+    }
+}
+/** 把 sidecar 的 `workspace.apply_edits` 响应映射为桌面结果形状。 */
+export function buildApplyEditsResult(result) {
+    return { content: result.content, diff: result.diff, matches: result.matches };
+}
+/**
+ * 在 sidecar（Python 真源）里对 `content` 应用 `edits`。只在回合内可达——
+ * 编辑工具经 reverse `tool.invoke` 触发，此刻 sidecar 必在运行；sidecar 不可用
+ * 时抛出 EditError 之外的错误，由 local-executor 的兜底分支转成失败结果。
+ */
+export async function applyEdits(content, edits, filePath = 'file') {
+    const supervisor = getSidecarSupervisor();
+    if (!supervisor) {
+        throw new Error('sidecar 不可用——结构化编辑算法在框架侧，需 sidecar 运行。');
+    }
+    try {
+        const result = await supervisor.applyEdits({ content, edits, filePath });
+        return buildApplyEditsResult(result);
+    }
+    catch (error) {
+        if (error instanceof SidecarMethodError && error.kind === 'edit_failed') {
+            const code = error.data?.code;
+            throw new EditError(error.message, code ?? 'not_found');
+        }
+        throw error;
+    }
+}

package/dist/local-executor.d.ts

@@ -0,0 +1,255 @@
+import { type ApplyEditsResult, type EditOp } from './local-edit.js';
+export declare function getWineCommand(): string | null;
+export declare function rewriteExeCommandIfNeeded(command: string): string;
+export type ShellType = 'zsh' | 'bash' | 'wsl' | 'powershell' | 'cmd';
+export interface LocalExecRequest {
+    command: string;
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+    shell?: ShellType;
+}
+export interface LocalExecResult {
+    success: boolean;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    error?: string;
+    truncated?: boolean;
+    shell?: ShellType;
+    platform?: string;
+    /** 命令因超时被终止（不代表命令本身出错——长任务 / GUI 程序常见）。 */
+    timedOut?: boolean;
+    /**
+     * GUI/长交互命令超时后进程未被终止，仍在后台运行。此时 success=true：
+     * "程序已启动并在运行" 对启动类命令就是成功，不能让 LLM 当失败重试。
+     */
+    stillRunning?: boolean;
+}
+export interface LocalFileReadRequest {
+    path: string;
+    encoding?: BufferEncoding;
+    maxSize?: number;
+}
+export interface LocalFileReadResult {
+    success: boolean;
+    content?: string;
+    /** 内容版本令牌（SHA-256）。读后写场景把它回传给 edit/write 做冲突检测。 */
+    version?: string;
+    error?: string;
+}
+export interface LocalFileWriteRequest {
+    path: string;
+    content: string;
+    encoding?: BufferEncoding;
+    createDirs?: boolean;
+    /** 可选：期望的当前版本令牌（read 返回的 version）。不匹配则拒绝写入。 */
+    expectedVersion?: string;
+}
+export interface LocalFileWriteResult {
+    success: boolean;
+    /** 写入后的新版本令牌。 */
+    version?: string;
+    error?: string;
+}
+/** local_edit_file 的单条编辑。 */
+export interface LocalFileEditOp extends EditOp {
+}
+export interface LocalFileEditRequest {
+    path: string;
+    edits: LocalFileEditOp[];
+    encoding?: BufferEncoding;
+    /** 可选：期望的当前版本令牌（read 返回的 version）。不匹配则拒绝（冲突）。 */
+    expectedVersion?: string;
+}
+export interface LocalFileEditResult {
+    success: boolean;
+    /** 编辑后的新版本令牌。 */
+    version?: string;
+    /** 统一 diff 预览（供工具卡渲染）。 */
+    diff?: string;
+    /** 每条编辑的命中信息（定位级别 / 起始行）。 */
+    matches?: Array<{
+        level: string;
+        startLine: number;
+        oldLineCount: number;
+    }>;
+    /** 命中的编辑条数。 */
+    applied?: number;
+    error?: string;
+}
+export interface LocalOpenRequest {
+    target: string;
+}
+export interface LocalOpenResult {
+    success: boolean;
+    error?: string;
+}
+export type RunCodeLanguage = 'python' | 'node';
+export interface LocalRunCodeRequest {
+    language: string;
+    code: string;
+    cwd?: string;
+    timeout?: number;
+    /** 运行前要 pip 安装的依赖（如 ["pandas", "openpyxl"]）。 */
+    pipPackages?: string[];
+    /** 运行前要 npm 安装到 scratch 目录的依赖（如 ["xlsx"]）。 */
+    npmPackages?: string[];
+}
+export interface LocalRunCodeResult extends LocalExecResult {
+    language?: RunCodeLanguage;
+    /** 实际使用的解释器命令/路径（venv 兜底时是 venv 里的 python）。 */
+    interpreter?: string;
+    /** 代码片段落盘位置（保留不删，便于排查/复用）。 */
+    scriptPath?: string;
+    /** 本次调用实际安装成功的依赖。 */
+    installedPackages?: string[];
+}
+/** 内容版本令牌：UTF-8 内容的 SHA-256。用于 read-before-write 冲突检测。 */
+/**
+ * read-before-write 冲突令牌：内容的 SHA-256（UTF-8）十六进制。与框架
+ * `steerable_sidecar.file_edit.content_version` 是同一算法（WS4 契约
+ * `versionAlgorithm: sha256-utf8-hex`），两侧由共享测试向量防漂移。
+ * 导出供 `tests/tool-contract.test.ts` 断言算法一致性。
+ */
+export declare function hashContent(content: string): string;
+/**
+ * GUI 命令（见 isGuiLaunchCommand）没显式给 timeout 时的等待时长：只等一小段
+ * 时间捕获"立即启动失败"类错误；到点后按"已启动、仍在运行"成功返回，不杀进程。
+ */
+export declare const GUI_LAUNCH_WAIT_MS = 15000;
+export declare function setDefaultExecTimeoutMs(ms: number | null | undefined): void;
+export declare function getDefaultExecTimeoutMs(): number;
+/** 用户配置的默认超时；未配置返回 null（调用方可用各自的内置默认）。 */
+export declare function getConfiguredExecTimeoutMs(): number | null;
+/**
+ * 判断命令是否在启动 GUI/交互式程序。场景应用启动图形图件的命令行约定
+ * 带有 "gui" 字样（如 `xxx.exe gui replay ...`、`--gui`、`start_gui.bat`），
+ * 以非字母数字为边界匹配独立的 "gui" token，避免误伤 guide/guid 之类的词。
+ *
+ * 这类命令的语义是"把程序拉起来给用户操作"，等不到退出码是常态——超时后
+ * 不应杀进程、更不应判失败重跑（那会把 Qt 图件重复启动多次）。
+ */
+export declare function isGuiLaunchCommand(command: string): boolean;
+/**
+ * 项目模式的路径围栏：判断 resolvedPath 是否落在 root 之内（含 root 本身）。
+ * 两个入参都应先经过 resolve（`~` 展开 + path.resolve）——本函数只做纯
+ * 字符串/相对路径判断，不碰 fs，方便 ToolRouter 与 LocalExecutor 共用。
+ */
+export declare function isPathWithinRoot(resolvedPath: string, resolvedRoot: string): boolean;
+/** 越界错误消息（给模型看，引导它把操作收回项目目录内）。 */
+export declare function buildProjectRootViolation(resolvedPath: string, resolvedRoot: string): string;
+export interface CommandSafetyConfigPayload {
+    disabledPatternIds: string[];
+    customPatterns: Array<{
+        id: string;
+        label: string;
+        pattern: string;
+        category: string;
+        enabled: boolean;
+    }>;
+}
+/** 结构化编辑算法（默认走 sidecar 的 Python 真源；测试可注入 stub）。 */
+type ApplyEditsFn = (content: string, edits: EditOp[], filePath?: string) => Promise<ApplyEditsResult>;
+export declare class LocalExecutor {
+    private readonly maxOutputBytes;
+    private readonly defaultShell;
+    private readonly applyEditsFn;
+    private wslAvailable;
+    private shellCacheInitialized;
+    private dangerousPatterns;
+    /** 同文件读-改-写的串行队列（key = resolvedPath）。 */
+    private readonly fileQueues;
+    /**
+     * P2b read-before-write 证据：resolvedPath → 读取时的内容版本
+     * （CC `seed_read_state` 对齐）。read 成功时记录；write/edit 缺省
+     * expectedVersion 时用它做自动 CAS；写成功后回写新版本。会话恢复时
+     * 由 sidecar 的 `read_state.seed` 反向调用重灌（seedReadState）。
+     */
+    private readonly readFileState;
+    constructor(maxOutputBytes?: number, applyEditsFn?: ApplyEditsFn);
+    updateSafetyConfig(config: CommandSafetyConfigPayload): void;
+    /**
+     * P2b：会话恢复时重灌 read-before-write 证据。sidecar 扫描持久记录里的
+     * 文件工具结果，把 path → version 经 `read_state.seed` 推到这里——进程
+     * 重启后自动 CAS 仍然成立（CC `seed_read_state` 语义）。键是 sidecar 侧
+     * 已解析的绝对路径，原样存储；resolvePath 对绝对路径是恒等，查询能命中。
+     * 返回实际收录的条目数（畸形条目跳过）。
+     */
+    seedReadState(state: Record<string, unknown>): number;
+    init(): Promise<void>;
+    getPlatformInfo(): {
+        platform: string;
+        shell: ShellType;
+        wslAvailable: boolean;
+        osVersion: string;
+        osArch: string;
+    };
+    executeShell(request: LocalExecRequest): Promise<LocalExecResult>;
+    readLocalFile(request: LocalFileReadRequest, projectRoot?: string | null, additionalReadRoots?: string[] | null): Promise<LocalFileReadResult>;
+    writeLocalFile(request: LocalFileWriteRequest, projectRoot?: string | null): Promise<LocalFileWriteResult>;
+    /**
+     * local_edit_file 的实现（W6-1）：结构化批量编辑。先按 expectedVersion 做
+     * read-before-write 冲突检测，再在原文上做三级模糊定位 + 逆序替换，最后
+     * 原子落盘。返回新版本令牌与统一 diff。
+     */
+    editLocalFile(request: LocalFileEditRequest, projectRoot?: string | null): Promise<LocalFileEditResult>;
+    /**
+     * read-before-write 冲突检测：当前内容版本与调用方期望不一致时返回错误
+     * 消息（引导重新读取），一致返回 null。文件不存在且期望存在也算冲突，
+     * 除非 `missingOk`（隐式期望来自读证据：读后被删的文件再写是新建，
+     * 没有可覆盖的他人改动）。
+     */
+    private checkVersion;
+    /** 原子写：先写同目录临时文件再 rename（同卷 rename 原子），失败清理临时文件。 */
+    private atomicWrite;
+    /**
+     * 同文件操作串行队列：把同一 resolvedPath 的读-改-写串成链，避免并发
+     * 写互相覆盖。不同文件互不影响。
+     */
+    private serializeFileOp;
+    /**
+     * local_run_snippet 的实现：把代码片段写到 scratch 目录（os.tmpdir()/
+     * agent-shell-code），用本机解释器跑起来；可选先装 pip/npm 依赖。
+     *
+     * 设计要点：
+     * - 解释器探测结果缓存（python3 → python → py；node）；缺失时返回可操作错误。
+     * - pip 优先 `--user`；被 PEP 668（externally-managed，Homebrew Python 常见）
+     *   拒绝时在 scratch 目录建一次性 venv，之后所有 python 运行都用 venv 解释器。
+     * - npm 依赖装进 scratchDir，node 脚本也落盘在 scratchDir——node 的
+     *   node_modules 解析会沿脚本所在目录向上找到依赖，无需 NODE_PATH。
+     * - cwd 的项目沙箱在 ToolRouter 层完成，这里只负责跑。
+     */
+    runCode(request: LocalRunCodeRequest): Promise<LocalRunCodeResult>;
+    private getCodeScratchDir;
+    /** 解释器探测缓存：undefined=未探测，null=探测过但没有。 */
+    private pythonCommand;
+    private nodeCommand;
+    /** PEP 668 兜底 venv 的解释器路径；一旦建立，后续 python 运行都用它。 */
+    private pythonVenvPath;
+    private resolveInterpreter;
+    private probeCommand;
+    /**
+     * pip 安装：`--user` 优先；遇到 PEP 668（externally-managed-environment，
+     * Homebrew/系统 Python 的默认限制）就在 scratch 目录建 venv 兜底，
+     * 并把 venv 解释器缓存下来供后续运行使用。
+     *
+     * 返回的 `python` 字段是后续运行脚本应使用的解释器（可能已被 venv 替换）。
+     */
+    private installPythonPackages;
+    openLocalTarget(request: LocalOpenRequest): Promise<LocalOpenResult>;
+    /**
+     * Public wrapper so other execution paths (e.g. the visible-terminal path
+     * in main.ts) can run the same dangerous-command check that headless
+     * `executeShell` applies, instead of silently bypassing it.
+     */
+    detectDangerousCommand(command: string): string | null;
+    private detectDangerousCommandInternal;
+    private getDefaultPatterns;
+    private resolvePath;
+    private resolveCwd;
+    private resolveShell;
+    private computeDefaultShell;
+    private detectWslAvailable;
+}
+export {};