@steerable/agent-shell 0.6.15

package/dist/tool-router.d.ts

@@ -0,0 +1,228 @@
+import { LocalExecutor, type LocalExecRequest, type LocalExecResult } from './local-executor.js';
+import { LocalScriptRegistry } from './local-script-registry.js';
+import type { McpServerRegistry } from './mcp-server-registry.js';
+import type { ProjectRegistry } from './project-registry.js';
+import type { TaskService } from './local-backend/task-service.js';
+import type { WorktreeService } from './local-backend/worktree-service.js';
+import type { ToolContribution, ToolMode, ToolExposure } from './scenario/pack.js';
+export type { ToolMode, ToolExposure } from './scenario/pack.js';
+import { type AgentToolPolicy } from './local-backend/agent-capability.js';
+/** 已注册 MCP 服务的动态工具名前缀：`mcp__<serverKey>__<toolName>`。 */
+export declare const MCP_DYNAMIC_TOOL_PREFIX = "mcp__";
+/**
+ * 工具曝光分层（steerable-framework Wave 2 同构）：`direct` 进模型可见列表；
+ * `deferred` 可分发、可经 `tool_search` 发现，但不占每轮工具列表的 token；
+ * `hidden` 仅可分发。缺省 `direct`。
+ *
+ * ToolMode / ToolExposure 的单一真源在 scenario/pack.ts（pack-sdk），
+ * 本模块 re-export 兼容既有调用方。
+ */
+/** deferred 层的发现缝：一个 direct 层搜索工具，关键词命中即调。 */
+export declare const TOOL_SEARCH_TOOL_NAME = "tool_search";
+export interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * 单次工具执行的调用上下文（按 chat 解析，随每次 execute 传入）。
+ *
+ * `projectRoot` 是项目模式的硬沙箱根：非空时
+ *   - local_read_file / local_write_file 的路径必须落在根内（LocalExecutor 围栏）
+ *   - local_exec_shell 的 cwd 默认改为项目根；显式给的 cwd 越界则直接拒绝
+ * 无项目对话（null/缺省）行为与之前完全一致。
+ */
+export interface ToolExecContext {
+    projectRoot?: string | null;
+    /**
+     * 项目模式之外额外放行的只读根（会话附件目录等）。只放宽
+     * local_read_file 的读取范围，写入/编辑仍只受 projectRoot 围栏约束。
+     */
+    additionalReadRoots?: string[] | null;
+    /**
+     * 4.6a：调用发生的 chat。task_run / task_status / task_result 需要它把
+     * 任务绑定到来源对话（任务表按 chatId 归组）；reverse-tools 从
+     * toolContext.chatId 透传。缺省（CLI/直接 exec 场景）时任务工具拒绝服务。
+     */
+    chatId?: string;
+    /**
+     * 本轮智能体的工具准入策略（「智能体管理」页配置，router 按本轮生效的
+     * 智能体解析后随 toolContext 下发）。分发层按它复检：被拒的工具即使模型
+     * 从历史里捞到名字直接调用也会被拒绝——与 plan 模式同款的双层执行
+     * （广告层不出 + 分发层拒绝）。缺省 = 不限制。
+     */
+    toolPolicy?: AgentToolPolicy | null;
+}
+export interface ToolSchema {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    mode: ToolMode;
+    /** 曝光层；缺省 `direct`。MCP 动态工具默认 `deferred`。 */
+    exposure?: ToolExposure;
+}
+type ShellExecutor = (request: LocalExecRequest) => Promise<LocalExecResult>;
+/**
+ * web_search / web_fetch 的执行缝（W5-2）：唯一实现在 sidecar 的
+ * `web_tools.py`（SSRF 策略、字节上限、重定向上限都在那里），宿主只持
+ * schema 并经前向 `tool.invoke` 前转——与 local_* 工具"两处实现、契约
+ * 对齐"的模式相反，网络读取对刻意单实现，因此不进 tool-contract。
+ * main.ts 在 sidecar 启动后用 `tool.list` 握手填充可用集。
+ */
+export type WebToolDelegate = (name: 'web_search' | 'web_fetch', args: Record<string, unknown>) => Promise<unknown>;
+/** 前转 RPC 超时：sidecar 侧单次请求上限默认 30s（可配到 600s），这里给足余量。 */
+export declare const WEB_TOOL_RPC_TIMEOUT_MS = 130000;
+/**
+ * 插件生命周期 RPC 缝：sidecar 的 `plugin.*` 方法（list/enable/disable/reload）
+ * 由 PluginRegistry 背书。宿主只持 schema 并经此 delegate 直调——与 web 工具
+ * 不同，这些是普通 RPC 而非 tool.invoke（不经过模型工具分发层）。
+ */
+export type PluginRpcDelegate = (method: 'plugin.list' | 'plugin.enable' | 'plugin.disable' | 'plugin.reload', params?: Record<string, unknown>) => Promise<unknown>;
+/**
+ * 本机是否提供网络读取工具（`STEERABLE_WEB_TOOLS=0` 关闭）。
+ *
+ * 同一个开关同时管住两件事：`tool.list` 握手是否把 web 工具装进本路由，
+ * 以及 layer-1 Seatbelt profile 是否放行它们所需的出网（解析器 + 80/443）。
+ * 两者必须同源——只放宽不暴露是白开的口子，只暴露不放宽则每次抓取都死在
+ * 名字解析上，而模型会把它解释成用户断网。
+ */
+export declare function webToolsEnabled(): boolean;
+export declare class ToolRouter {
+    private readonly localExecutor;
+    private readonly localScriptRegistry;
+    private readonly shellExecutor?;
+    /** 可选：已注册的外部 MCP 服务（设置界面导入）。有缓存工具的服务会追加为一等工具。 */
+    readonly mcpRegistry?: McpServerRegistry | undefined;
+    /** 可选：项目注册表（项目模式）。路由层用它把 chat.projectId 解析成沙箱根目录。 */
+    readonly projectRegistry?: ProjectRegistry | undefined;
+    constructor(localExecutor: LocalExecutor, localScriptRegistry: LocalScriptRegistry, shellExecutor?: ShellExecutor | undefined, 
+    /** 可选：已注册的外部 MCP 服务（设置界面导入）。有缓存工具的服务会追加为一等工具。 */
+    mcpRegistry?: McpServerRegistry | undefined, 
+    /** 可选：项目注册表（项目模式）。路由层用它把 chat.projectId 解析成沙箱根目录。 */
+    projectRegistry?: ProjectRegistry | undefined);
+    /**
+     * 场景包贡献的工具（0.3a 开槽）。schema 进 listSchemas，分发在 execute
+     * 的 default 分支——内置工具优先，名字冲突在注册时响亮失败。
+     */
+    private readonly contributedTools;
+    /**
+     * 注册一组场景工具贡献。与既有工具（内置 / 任务 / web / MCP / 插件 /
+     * 已注册贡献）重名即抛错——一个包装不上却静默丢工具是能力暗损。
+     */
+    registerToolContributions(contributions: readonly ToolContribution[]): void;
+    /**
+     * sidecar 握手得到的网络读取工具可用集。web_search 只在 sidecar 配好
+     * 搜索后端（设置页免费 DuckDuckGo / Tavily 钥 / STEERABLE_WEB_SEARCH_API_KEY /
+     * TAVILY_API_KEY，或 STEERABLE_WEB_SEARCH_PROVIDER=host）时注册——
+     * 宿主不猜，避免出现"工具在列表里但一调就报未配置"。
+     */
+    private webToolDelegate;
+    private webToolNames;
+    /**
+     * OpenAI hosted search executed in this process with the chat credential.
+     * Set when the sidecar registered `web_search` via provider=host so the
+     * host must not forward the call back into the sidecar.
+     */
+    private hostedWebSearch;
+    /**
+     * 4.6a/4.6b：跨 turn 任务与 git worktree 服务。setter 注入（与
+     * setWebTools 同模式）——main.ts 里 ToolRouter 先于 TaskService 构造
+     * （TaskService 反向依赖 ToolRouter 的工具列表），构造后再接线。
+     * 未接线时任务/worktree 工具不出场（schema 都不出，模型看不到）。
+     */
+    private taskService;
+    private worktreeService;
+    setTaskServices(services: {
+        taskService: TaskService;
+        worktreeService: WorktreeService;
+    } | null): void;
+    setWebTools(delegate: WebToolDelegate | null, names?: readonly string[]): void;
+    setHostedWebSearch(handler: ((args: Record<string, unknown>) => Promise<unknown>) | null): void;
+    /**
+     * sidecar 握手后注入插件 RPC 缝。未注入（sidecar 缺席/握手失败）时
+     * plugin_* 工具一个 schema 都不出——模型看不到不可用的工具。
+     */
+    private pluginRpc;
+    setPluginRpc(delegate: PluginRpcDelegate | null): void;
+    listSchemas(): ToolSchema[];
+    /**
+     * 插件生命周期工具（框架 plugin.* RPC 的模型面）。全在 deferred 层：
+     * 插件管理是低频运维动作，不值每轮工具列表的 token——模型经
+     * tool_search 发现，命中即调。写操作（enable/disable/reload）标
+     * destructive，走宿主审批链。
+     */
+    private listPluginToolSchemas;
+    /**
+     * 4.6a/4.6b 任务与 worktree 工具的 schema。task_run 立即返回
+     * （任务在后台独立流里跨 turn 跑完）；worktree_* 操作绑定项目的
+     * git 仓库。description 用英文（面向模型），与 local_* 工具同款。
+     */
+    private listTaskAndWorktreeSchemas;
+    /**
+     * 网络读取对（W5-2）：schema 与 sidecar `web_tools.py` 保持一致；description
+     * 用英文（面向模型），与 local_* 工具同款。可用集由握手决定，未握手/未注册
+     * 时一个 schema 都不出——模型看不到不可用的工具。
+     */
+    private listWebToolSchemas;
+    /**
+     * 已注册 MCP 服务的动态工具。服务的工具列表来自注册表的内存缓存
+     * （启动后台刷新 + 设置界面"测试连接"刷新），没缓存或已禁用的服务不出场。
+     * 全部落在 deferred 层：MCP 目录是最大的无界第三方工具来源，不为每个
+     * schema 每轮付 token——模型经 `tool_search` 发现，命中即调。
+     */
+    private listRegisteredMcpToolSchemas;
+    /**
+     * 模型可见列表：仅 direct 层。`tool_search` 只有在存在 deferred 层时
+     * 才占一个列表槽——没有可发现的东西时它是每轮请求里的死重。
+     * 分发不按层设卡：被发现的 deferred 工具按名直调（execute 不查层）。
+     *
+     * @param policy 本轮智能体的工具准入策略；被拒的工具连 schema 都不出。
+     *   deferred 层同样按策略过滤，所以策略拒掉全部 deferred 工具时
+     *   `tool_search` 也一并退场（没有可发现的东西）。缺省 = 不限制。
+     */
+    listModelSchemas(policy?: AgentToolPolicy | null): ToolSchema[];
+    getSchemaByName(toolName: string): ToolSchema | null;
+    execute(call: ToolCall, context?: ToolExecContext): Promise<unknown>;
+    /**
+     * 任务/worktree 工具的调用上下文：必须有来源 chatId（任务表按 chat 归组、
+     * 项目围栏按 chat 解析）。schema 出场 ⇒ 服务已接线，这里只缺 chatId 时
+     * 抛错（reverse-tools 总是透传；缺了就是接线 bug，响亮失败）。
+     */
+    private requireTaskContext;
+    /**
+     * Agent 写出 `…/skills/<name>/SKILL.md` 且该目录还不在已知 skill root 上时，
+     * 拷进用户技能目录，Skill 设置 / `/` 菜单不必再手动导入。
+     */
+    private autoInstallSkillOnSuccess;
+    /**
+     * 项目模式硬沙箱（cwd 维度）：projectRoot 非空时，cwd 默认收到项目根；
+     * 模型显式给的 cwd 越界则返回错误结果。相对 cwd 按项目根解析（而不是
+     * 进程 cwd），符合"在项目里干活"的直觉。
+     *
+     * 注意边界：shell 命令文本里内嵌的绝对路径无法可靠解析，围栏只覆盖
+     * cwd 与文件读写工具——系统提示里已告知模型只在项目目录内操作。
+     *
+     * local_exec_shell 与 local_run_snippet 共用本 helper。
+     */
+    private applyProjectCwdSandbox;
+    private executeShell;
+    private resolveMcpConfig;
+    /**
+     * `tool_search` 处理器：BM25 排序 deferred 名录（name 分词计两次），返回
+     * 完整 schema，结果有界（默认 8，封顶 20）。算法、常量、默认上限与返回
+     * 文案都与 steerable-framework `tool_search.py` 对齐——同名工具在两侧给
+     * 出同样的名次；hidden 层不进搜索。
+     *
+     * 智能体工具策略在这里同样生效：否则每轮列表藏起来的工具会从这条发现缝
+     * 漏回去，「限制」只剩一半。
+     */
+    private executeToolSearch;
+    /**
+     * 前转网络读取调用到 sidecar（W5-2）。走到这里说明 schema 已出场，
+     * 即握手时 sidecar 注册了该工具；delegate 缺失/集合漂移是编程错误或
+     * sidecar 中途重启，按响亮失败处理（reverse-tools 会把抛错包成
+     * ToolResult）。
+     */
+    private executeWebTool;
+    /** 执行注册表里的 MCP 动态工具（`mcp__<serverKey>__<toolName>`）。 */
+    private executeRegisteredMcpTool;
+}