@steerable/agent-shell 0.6.51 → 0.6.52

package/dist/tool-router.js

@@ -1,6 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
-import { buildProjectRootViolation, isPathWithinRoot, } from './local-executor.js';
+import { buildProjectRootViolation, expandFencePath, isPathWithinRoot, writableFenceRoots, writableFenceViolation, } from './local-executor.js';
 import { mcpExecutor } from './mcp-executor.js';
 import { rankTools, resolveMaxResults, TOOL_SEARCH_DEFAULT_MAX_RESULTS, } from './tool-search-rank.js';
 import { maybeAutoInstallWrittenSkill } from './local-backend/skill-install.js';
@@ -9,6 +9,8 @@ import { processViewImage } from './image-attachment.js';
 import { PRESENT_FILES_SCHEMA, PRESENT_FILES_TOOL_NAME, executePresentFiles, } from './present-files.js';
 import { isHostToolCapabilityEnabled } from './host-tools.js';
 import { getResolvedHostTools } from './host-tools-runtime.js';
+import { GoalStore, GOAL_ACTIONS } from './goal-store.js';
+import { searchGlob, searchGrep } from './workspace-search.js';
 /** 已注册 MCP 服务的动态工具名前缀：`mcp__<serverKey>__<toolName>`。 */
 export const MCP_DYNAMIC_TOOL_PREFIX = 'mcp__';
 /**
@@ -97,6 +99,16 @@ export class ToolRouter {
         this.taskService = services?.taskService ?? null;
         this.worktreeService = services?.worktreeService ?? null;
     }
+    /** 会话目标的持久化。缺省写到用户数据目录；测试注入临时文件。 */
+    goalStore = null;
+    setGoalStore(store) {
+        this.goalStore = store;
+    }
+    goals() {
+        if (!this.goalStore)
+            this.goalStore = GoalStore.default();
+        return this.goalStore;
+    }
     setWebTools(delegate, names = []) {
         this.webToolDelegate = delegate;
         this.webToolNames = new Set(names);
@@ -415,6 +427,7 @@ export class ToolRouter {
                     additionalProperties: false,
                 },
             },
+            ...this.listParityToolSchemas(),
             // ─── 4.6a/4.6b 跨 turn 后台任务 + git worktree 隔离 ─────────────
             // 服务未接线（CLI/test）时一个 schema 都不出——模型看不到不可用的工具。
             ...this.listTaskAndWorktreeSchemas(),
@@ -482,6 +495,105 @@ export class ToolRouter {
             },
         ];
     }
+    /**
+     * 内容搜索、PowerShell、会话目标。后台任务的 job_* 跟 task 服务一起出场。
+     */
+    listParityToolSchemas() {
+        return [
+            {
+                name: 'grep',
+                description: 'Search file contents under the project (or an optional subdirectory). '
+                    + 'pattern is a JavaScript regular expression. Optional glob limits which relative paths are scanned. '
+                    + 'Skips dependency and VCS directories. Returns {path, line, text} hits. Prefer this over shell rg/grep.',
+                mode: 'read',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pattern: { type: 'string', description: 'JavaScript regular expression matched per line.' },
+                        path: { type: 'string', description: 'Directory to search. Defaults to the project root.' },
+                        glob: { type: 'string', description: 'Optional fnmatch, e.g. "*.ts" or "src/**/*.py".' },
+                    },
+                    required: ['pattern'],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: 'glob',
+                description: 'List project files whose relative path matches a glob. A pattern without "/" matches any directory. '
+                    + 'Prefer this over shell find or ls.',
+                mode: 'read',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pattern: { type: 'string', description: 'Glob, e.g. "*.ts" or "src/**/*.py".' },
+                        path: { type: 'string', description: 'Directory to search. Defaults to the project root.' },
+                    },
+                    required: ['pattern'],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: 'pwsh',
+                description: 'Run a PowerShell command. On Windows this is powershell.exe; elsewhere it runs pwsh '
+                    + '(PowerShell 7) and fails clearly when that binary is not installed. '
+                    + 'Use local_exec_shell for the platform default shell.',
+                mode: 'destructive',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        command: { type: 'string' },
+                        cwd: { type: 'string' },
+                        timeout: {
+                            type: 'number',
+                            description: 'Timeout in milliseconds. A small number like 30 is treated as seconds.',
+                        },
+                    },
+                    required: ['command'],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: 'get_goal',
+                description: 'Read this chat\'s persisted goal, including the id and revision that update_goal requires. '
+                    + 'goal is null when none exists.',
+                mode: 'read',
+                inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            },
+            {
+                name: 'create_goal',
+                description: 'Create a persisted goal for this chat when the user\'s request is a long-running objective. '
+                    + 'Not for single-turn work. Fails if an unfinished goal already exists — update that one instead.',
+                mode: 'safe_write',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        objective: { type: 'string', description: 'What done looks like, as a result rather than an activity.' },
+                    },
+                    required: ['objective'],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: 'update_goal',
+                description: 'Change the current goal. Pass the id and revision from get_goal. '
+                    + 'action is edit (needs objective), pause, resume, complete, or blocked (needs reason). '
+                    + 'A stale revision is rejected; re-read and retry.',
+                mode: 'safe_write',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        revision: { type: 'integer' },
+                        action: { type: 'string', enum: [...GOAL_ACTIONS] },
+                        objective: { type: 'string', description: 'Required for action=edit.' },
+                        reason: { type: 'string', description: 'Required for action=blocked.' },
+                    },
+                    required: ['id', 'revision', 'action'],
+                    additionalProperties: false,
+                },
+            },
+        ];
+    }
     /**
      * 4.6a/4.6b 任务与 worktree 工具的 schema。task_run 立即返回
      * （任务在后台独立流里跨 turn 跑完）；worktree_* 操作绑定项目的
@@ -594,6 +706,46 @@ export class ToolRouter {
                     additionalProperties: false,
                 },
             },
+            {
+                name: 'job_list',
+                description: 'List this chat\'s background jobs (the same records task_run creates). '
+                    + 'Each row includes job_id (the taskId), status, and the task text.',
+                mode: 'read',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: 'job_output',
+                description: 'Read the final answer of a background job. job_id is the taskId from task_run or job_list. '
+                    + 'Fails with needsFollowup while the job is still running.',
+                mode: 'read',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        job_id: { type: 'string', description: 'taskId of the background job.' },
+                    },
+                    required: ['job_id'],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: 'job_kill',
+                description: 'Stop a running or blocked background job. A finished job cannot be killed. '
+                    + 'job_id is the taskId from task_run or job_list.',
+                mode: 'destructive',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        job_id: { type: 'string', description: 'taskId of the background job.' },
+                        reason: { type: 'string', description: 'Optional note stored on the job.' },
+                    },
+                    required: ['job_id'],
+                    additionalProperties: false,
+                },
+            },
             {
                 name: 'worktree_remove',
                 description: 'Remove a managed worktree and delete its branch — the DISCARD path, any unmerged changes are lost. '
@@ -738,7 +890,7 @@ export class ToolRouter {
                     command: String(args.command || ''),
                     cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
                     timeout: typeof args.timeout === 'number' ? args.timeout : undefined,
-                }, projectRoot);
+                }, projectRoot, context?.additionalWriteRoots ?? null);
             case 'local_read_file':
                 return await this.localExecutor.readLocalFile({
                     path: String(args.path || ''),
@@ -776,7 +928,7 @@ export class ToolRouter {
                     content: String(args.content || ''),
                     createDirs: Boolean(args.createDirs),
                     expectedVersion: typeof args.expectedVersion === 'string' ? args.expectedVersion : undefined,
-                }, projectRoot);
+                }, projectRoot, context?.additionalWriteRoots ?? null);
                 this.autoInstallSkillOnSuccess(written, args.path);
                 return written;
             }
@@ -793,7 +945,7 @@ export class ToolRouter {
                     path: String(args.path || ''),
                     edits,
                     expectedVersion: typeof args.expectedVersion === 'string' ? args.expectedVersion : undefined,
-                }, projectRoot);
+                }, projectRoot, context?.additionalWriteRoots ?? null);
                 this.autoInstallSkillOnSuccess(edited, args.path);
                 return edited;
             }
@@ -805,7 +957,7 @@ export class ToolRouter {
                 });
             case 'local_run_snippet': {
                 // 与 local_exec_shell 同款项目沙箱：cwd 默认项目根，显式越界拒绝。
-                const sandboxed = this.applyProjectCwdSandbox({ cwd: typeof args.cwd === 'string' ? args.cwd : undefined }, projectRoot);
+                const sandboxed = this.applyProjectCwdSandbox({ cwd: typeof args.cwd === 'string' ? args.cwd : undefined }, projectRoot, context?.additionalWriteRoots ?? null);
                 if ('error' in sandboxed)
                     return sandboxed.error;
                 return await this.localExecutor.runCode({
@@ -859,6 +1011,47 @@ export class ToolRouter {
                     await this.refreshPluginTools();
                 return result;
             }
+            case 'grep':
+            case 'glob': {
+                const requested = typeof args.path === 'string' ? args.path.trim() : '';
+                const start = requested
+                    ? this.resolveReadablePath(requested, projectRoot, context?.additionalReadRoots ?? null)
+                    : { path: projectRoot ? expandFencePath(projectRoot) : process.cwd() };
+                if ('error' in start) {
+                    return { success: false, error: start.error, needsFollowup: true };
+                }
+                if (call.name === 'grep') {
+                    return searchGrep({
+                        root: start.path,
+                        pattern: String(args.pattern || ''),
+                        glob: typeof args.glob === 'string' ? args.glob : undefined,
+                    });
+                }
+                return searchGlob({ root: start.path, pattern: String(args.pattern || '') });
+            }
+            case 'pwsh': {
+                const script = String(args.command || '');
+                if (!script.trim()) {
+                    return { success: false, error: 'command is required', needsFollowup: true };
+                }
+                const command = process.platform === 'win32'
+                    ? script
+                    : `pwsh -NoProfile -NonInteractive -Command ${JSON.stringify(script)}`;
+                return await this.executeShell({
+                    command,
+                    cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
+                    timeout: typeof args.timeout === 'number' ? args.timeout : undefined,
+                    shell: process.platform === 'win32' ? 'powershell' : undefined,
+                }, projectRoot, context?.additionalWriteRoots ?? null);
+            }
+            case 'get_goal':
+            case 'create_goal':
+            case 'update_goal':
+                return this.executeGoalTool(call.name, args, context);
+            case 'job_list':
+            case 'job_output':
+            case 'job_kill':
+                return this.executeJobTool(call.name, args, context);
             case 'task_run': {
                 const chatId = this.requireTaskContext(context);
                 const dependsOn = Array.isArray(args.dependsOn)
@@ -927,6 +1120,46 @@ export class ToolRouter {
      * 项目围栏按 chat 解析）。schema 出场 ⇒ 服务已接线，这里只缺 chatId 时
      * 抛错（reverse-tools 总是透传；缺了就是接线 bug，响亮失败）。
      */
+    async executeGoalTool(name, args, context) {
+        const chatId = context?.chatId;
+        if (!chatId) {
+            return { success: false, error: '目标工具需要 chatId 调用上下文', needsFollowup: true };
+        }
+        const store = this.goals();
+        if (name === 'get_goal')
+            return store.get(chatId);
+        if (name === 'create_goal')
+            return store.create(chatId, String(args.objective || ''));
+        return store.update({
+            chatId,
+            id: String(args.id || ''),
+            revision: typeof args.revision === 'number' ? args.revision : Number.NaN,
+            action: String(args.action || ''),
+            objective: typeof args.objective === 'string' ? args.objective : undefined,
+            reason: typeof args.reason === 'string' ? args.reason : undefined,
+        });
+    }
+    async executeJobTool(name, args, context) {
+        const chatId = this.requireTaskContext(context);
+        const jobId = String(args.job_id || '');
+        if (name === 'job_list') {
+            const listed = await this.taskService.status(chatId);
+            const tasks = Array.isArray(listed.tasks) ? listed.tasks : [];
+            return {
+                ...listed,
+                jobs: tasks.map((task) => {
+                    const row = task;
+                    return { ...row, job_id: row.taskId };
+                }),
+            };
+        }
+        if (!jobId)
+            return { success: false, error: 'job_id 不能为空', needsFollowup: true };
+        if (name === 'job_output')
+            return this.taskService.result(chatId, jobId);
+        const reason = typeof args.reason === 'string' && args.reason.trim() ? args.reason.trim() : undefined;
+        return this.taskService.kill(chatId, jobId, reason);
+    }
     requireTaskContext(context) {
         if (!this.taskService || !this.worktreeService) {
             throw new Error('任务/worktree 服务未接线（main.ts setTaskServices）');
@@ -955,41 +1188,44 @@ export class ToolRouter {
         }
     }
     /**
-     * 项目模式硬沙箱（cwd 维度）：projectRoot 非空时，cwd 默认收到项目根；
-     * 模型显式给的 cwd 越界则返回错误结果。相对 cwd 按项目根解析（而不是
-     * 进程 cwd），符合"在项目里干活"的直觉。
+     * 项目模式硬沙箱（cwd 维度）：有可写根时，cwd 默认收到项目家目录；
+     * 模型显式给的 cwd 必须落在家目录或额外可写根（源文件夹）内，含各自子目录。
+     * 相对 cwd 按家目录解析（而不是进程 cwd）。
      *
      * 注意边界：shell 命令文本里内嵌的绝对路径无法可靠解析，围栏只覆盖
-     * cwd 与文件读写工具——系统提示里已告知模型只在项目目录内操作。
+     * cwd 与文件读写工具。命令实际写盘还受 exec 沙箱的 writableRoots 约束，
+     * 那些根同样包含子目录。
      *
      * local_exec_shell 与 local_run_snippet 共用本 helper。
      */
-    applyProjectCwdSandbox(request, projectRoot) {
-        if (!projectRoot)
+    applyProjectCwdSandbox(request, projectRoot, additionalWriteRoots) {
+        const roots = writableFenceRoots(projectRoot, additionalWriteRoots);
+        if (roots.length === 0)
             return { request };
-        const root = path.resolve(projectRoot.startsWith('~') ? path.join(os.homedir(), projectRoot.slice(1)) : projectRoot);
+        const home = projectRoot ? expandFencePath(projectRoot) : roots[0];
         if (request.cwd) {
             const expanded = request.cwd.startsWith('~')
                 ? path.join(os.homedir(), request.cwd.slice(1))
                 : request.cwd;
             const resolvedCwd = path.isAbsolute(expanded)
                 ? path.resolve(expanded)
-                : path.resolve(root, expanded);
-            if (!isPathWithinRoot(resolvedCwd, root)) {
+                : path.resolve(home, expanded);
+            const violation = writableFenceViolation(resolvedCwd, roots);
+            if (violation) {
                 return {
                     error: {
                         success: false,
-                        error: buildProjectRootViolation(resolvedCwd, root),
+                        error: violation,
                         platform: process.platform,
                     },
                 };
             }
             return { request: { ...request, cwd: resolvedCwd } };
         }
-        return { request: { ...request, cwd: root } };
+        return { request: { ...request, cwd: home } };
     }
-    async executeShell(request, projectRoot) {
-        const sandboxed = this.applyProjectCwdSandbox(request, projectRoot);
+    async executeShell(request, projectRoot, additionalWriteRoots) {
+        const sandboxed = this.applyProjectCwdSandbox(request, projectRoot, additionalWriteRoots);
         if ('error' in sandboxed)
             return sandboxed.error;
         if (this.shellExecutor) {

package/dist/workspace-search.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 宿主侧 grep / glob。
+ *
+ * 调用方先把起点收进项目围栏。这里只在该目录内遍历，跳过符号链接，
+ * 并丢掉依赖目录和超大文件。命中数有上限。
+ */
+export interface SearchHit {
+    path: string;
+    line: number;
+    text: string;
+}
+export interface GrepResult {
+    success: boolean;
+    matches?: SearchHit[];
+    truncated?: boolean;
+    filesScanned?: number;
+    error?: string;
+    needsFollowup?: boolean;
+}
+export interface GlobResult {
+    success: boolean;
+    files?: string[];
+    truncated?: boolean;
+    error?: string;
+    needsFollowup?: boolean;
+}
+export declare function searchGrep(input: {
+    root: string;
+    pattern: string;
+    glob?: string;
+}): Promise<GrepResult>;
+export declare function searchGlob(input: {
+    root: string;
+    pattern: string;
+}): Promise<GlobResult>;

package/dist/workspace-search.js

@@ -0,0 +1,186 @@
+/**
+ * 宿主侧 grep / glob。
+ *
+ * 调用方先把起点收进项目围栏。这里只在该目录内遍历，跳过符号链接，
+ * 并丢掉依赖目录和超大文件。命中数有上限。
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'target',
+    '.steerable',
+    '__pycache__',
+    '.venv',
+    'venv',
+]);
+const MAX_FILES = 4_000;
+const MAX_MATCHES = 80;
+const MAX_FILE_BYTES = 1_000_000;
+const MAX_DEPTH = 20;
+function globToRegExp(pattern) {
+    const normalized = pattern.replaceAll('\\', '/');
+    const withPrefix = normalized.includes('/') ? normalized : `**/${normalized}`;
+    let out = '';
+    for (let i = 0; i < withPrefix.length; i += 1) {
+        const char = withPrefix[i];
+        if (char === '*' && withPrefix[i + 1] === '*') {
+            if (withPrefix[i + 2] === '/') {
+                out += '(?:.*/)?';
+                i += 2;
+            }
+            else {
+                out += '.*';
+                i += 1;
+            }
+            continue;
+        }
+        if (char === '*') {
+            out += '[^/]*';
+            continue;
+        }
+        if (char === '?') {
+            out += '[^/]';
+            continue;
+        }
+        if ('\\^$+?.()|{}[]'.includes(char))
+            out += `\\${char}`;
+        else
+            out += char;
+    }
+    return new RegExp(`^${out}$`);
+}
+async function walk(root, visit) {
+    let files = 0;
+    let truncated = false;
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length > 0) {
+        const next = queue.pop();
+        if (!next)
+            break;
+        let entries;
+        try {
+            entries = await readdir(next.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const absolute = path.join(next.dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || next.depth >= MAX_DEPTH)
+                    continue;
+                queue.push({ dir: absolute, depth: next.depth + 1 });
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            files += 1;
+            if (files > MAX_FILES) {
+                truncated = true;
+                return { truncated, files };
+            }
+            const relative = path.relative(root, absolute).split(path.sep).join('/');
+            const stop = await visit(absolute, relative);
+            if (stop === true) {
+                truncated = true;
+                return { truncated, files };
+            }
+        }
+    }
+    return { truncated, files };
+}
+export async function searchGrep(input) {
+    const pattern = input.pattern.trim();
+    if (!pattern)
+        return { success: false, error: 'pattern 不能为空', needsFollowup: true };
+    let matcher;
+    try {
+        matcher = new RegExp(pattern);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `无效的正则：${message}`, needsFollowup: true };
+    }
+    let fileFilter = null;
+    if (input.glob && input.glob.trim()) {
+        try {
+            fileFilter = globToRegExp(input.glob.trim());
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { success: false, error: `无效的 glob：${message}`, needsFollowup: true };
+        }
+    }
+    const matches = [];
+    const walked = await walk(input.root, async (absolute, relative) => {
+        if (fileFilter && !fileFilter.test(relative))
+            return;
+        let info;
+        try {
+            info = await stat(absolute);
+        }
+        catch {
+            return;
+        }
+        if (!info.isFile() || info.size > MAX_FILE_BYTES)
+            return;
+        let text;
+        try {
+            text = await readFile(absolute, 'utf8');
+        }
+        catch {
+            return;
+        }
+        if (text.includes('\0'))
+            return;
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i += 1) {
+            if (!matcher.test(lines[i]))
+                continue;
+            matches.push({ path: relative, line: i + 1, text: lines[i].slice(0, 400) });
+            if (matches.length >= MAX_MATCHES)
+                return true;
+        }
+        return undefined;
+    });
+    return {
+        success: true,
+        matches,
+        truncated: walked.truncated || matches.length >= MAX_MATCHES,
+        filesScanned: walked.files,
+    };
+}
+export async function searchGlob(input) {
+    const pattern = input.pattern.trim();
+    if (!pattern)
+        return { success: false, error: 'pattern 不能为空', needsFollowup: true };
+    let matcher;
+    try {
+        matcher = globToRegExp(pattern);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `无效的 glob：${message}`, needsFollowup: true };
+    }
+    const files = [];
+    const walked = await walk(input.root, async (_absolute, relative) => {
+        if (!matcher.test(relative))
+            return;
+        files.push(relative);
+        if (files.length >= MAX_MATCHES)
+            return true;
+        return undefined;
+    });
+    files.sort();
+    return {
+        success: true,
+        files,
+        truncated: walked.truncated || files.length >= MAX_MATCHES,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.51",
+  "version": "0.6.52",
   "description": "Steerable framework — product-neutral Node HostRuntime and headless HTTP server shared by Tauri desktop and browser deployments; scenario packs extend it through @steerable/pack-sdk.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -55,9 +55,9 @@
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
     "semver": "^7.8.0",
-    "@steerable/agent-harness": "0.6.51",
-    "@steerable/agent-protocol": "0.6.51",
-    "@steerable/pack-sdk": "0.6.51"
+    "@steerable/agent-harness": "0.6.52",
+    "@steerable/agent-protocol": "0.6.52",
+    "@steerable/pack-sdk": "0.6.52"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",