@x-otto/tools 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,1329 @@
+import { z } from "zod";
+import { ChildProcess, SpawnOptionsWithoutStdio } from "node:child_process";
+import { CallAgent, CancelBackground, GetBackgroundOutput, GetTask, ListTasks, TaskDispatch, UpdateTask, WriteTodos } from "@x-otto/orchestration-contracts";
+import * as _$_x_otto_interchange0 from "@x-otto/interchange";
+import { AgentTool, GrillAnswer, GrillQuestion, ProcessTracker } from "@x-otto/interchange";
+import { SandboxConfig, ToolPreset } from "@x-otto/setting";
+
+//#region src/hitl/grill-me.d.ts
+type SessionGrill = (sessionId: string, question: Omit<GrillQuestion, 'id'>) => Promise<GrillAnswer>;
+declare const GrillMeArgsSchema: z.ZodObject<{
+  header: z.ZodString;
+  question: z.ZodString;
+  background: z.ZodString;
+  recommendation: z.ZodString;
+  options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    label: z.ZodString;
+    rationale: z.ZodString;
+    recommended: z.ZodOptional<z.ZodBoolean>;
+    preview: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  allowFreeform: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+  multiSelect: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+  evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type GrillMeArgs = z.infer<typeof GrillMeArgsSchema>;
+declare function createGrillMe(_projectRoot: string, grill?: SessionGrill): AgentTool<GrillMeArgs>;
+//#endregion
+//#region src/binary/binary-executor.d.ts
+interface BinaryToolExecutionOptions extends SpawnOptionsWithoutStdio {
+  /**
+   * stdout 累计字节上限（M6-06，防无界缓冲/OOM）。超过即停止收集 + 终止子进程，
+   * 结果标记 `truncated`。缺省不限（向后兼容）。
+   */
+  maxBuffer?: number;
+}
+interface BinaryToolExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  /** stdout 触达 maxBuffer 被截断（M6-06）。 */
+  truncated?: boolean;
+}
+interface BinaryTool {
+  name: string;
+  version: string;
+  execute(args: string[], options?: BinaryToolExecutionOptions): Promise<BinaryToolExecutionResult>;
+}
+//#endregion
+//#region src/binary/binary-executor-registry.d.ts
+declare class BinaryToolExecutorRegistry {
+  private binaries;
+  has(tool: string): boolean;
+  get(tool: string): BinaryTool | undefined;
+  register(tool: BinaryTool): void;
+  unregister(tool: string): void;
+  ensureAll(): Promise<void>;
+  ensure(tool: string): Promise<BinaryTool>;
+  dispose(): void;
+}
+declare const createBinaryToolExecutorRegistry: (projectRoot: string, processTracker?: ProcessTracker) => BinaryToolExecutorRegistry;
+//#endregion
+//#region src/orchestration/delegate-job.d.ts
+/** 起一个隔离作业的回调（app 注入：→ agentJobs.start({origin:'main'})）。同步返回作业 id。 */
+type StartJob = (input: {
+  prompt: string;
+  title: string;
+  sessionId: string;
+}) => {
+  jobId: string;
+};
+//#endregion
+//#region src/memory/memory-archive.d.ts
+/**
+ * memory-archive.ts — RFC-340 M2：会话归档召回工具。
+ *
+ * 背景：压缩（compaction）把旧历史折叠成摘要后，原始消息仍完整保留在会话树里
+ * （RFC-159 红线保证 `session_entries` 永不删行），`MemoryManager` 也早已实现了
+ * 按 compaction 边界重建归档全文的能力（`readArchiveFromEntries`）——但这套能力
+ * **从未暴露给模型**（终局复审 R3 实证：零工具、零生产调用方）。
+ *
+ * 后果是 RFC-340 M1 的低保真标注只完成了半环：标注告诉模型"有 N% 历史没进摘要"，
+ * 模型却没有任何手段找回，标注沦为焦虑提示而非可行动信息。本文件补上下半环。
+ */
+/** 归档条目的工具层视图——不依赖 `@x-otto/memory` 的 `ArchiveEntry`（保持 tools 包分层纯净）。 */
+interface ArchiveEntryView {
+  path: string;
+  timestamp: number;
+  messageCount: number;
+  summary: string;
+}
+type ReadArchive = (archivePath: string) => Promise<string>;
+type ListArchives = (sessionId: string) => Promise<ArchiveEntryView[]>;
+//#endregion
+//#region src/scheduling/create.d.ts
+declare const CronCreateArgs: z.ZodObject<{
+  cron: z.ZodString;
+  prompt: z.ZodString;
+  recurring: z.ZodBoolean;
+  name: z.ZodOptional<z.ZodString>;
+  maxDurationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type CronCreateArgs = z.infer<typeof CronCreateArgs>;
+interface CronCreateResult {
+  taskId: string;
+  nextFireAt: number;
+  name: string;
+}
+type ScheduleCreateCallback = (input: CronCreateArgs) => CronCreateResult;
+//#endregion
+//#region src/scheduling/list.d.ts
+interface CronTask {
+  id: string;
+  name: string;
+  cronExpression: string;
+  enabled: boolean;
+  recurring: boolean;
+  nextFireAt: number;
+  lastFiredAt?: number;
+}
+type ScheduleListCallback = () => CronTask[];
+//#endregion
+//#region src/scheduling/delete.d.ts
+type ScheduleDeleteCallback = (taskId: string) => boolean;
+//#endregion
+//#region src/scheduling/run.d.ts
+type ScheduleRunCallback = (taskId: string) => void;
+//#endregion
+//#region src/scheduling/cancel.d.ts
+interface ScheduleCancelResult {
+  ok: boolean;
+  reason?: string;
+}
+type ScheduleCancelCallback = (taskId: string) => ScheduleCancelResult;
+//#endregion
+//#region src/orchestration/capability-gap.d.ts
+/**
+ * capability_gap —— RFC-287 M4：自迭代回路的**认知入口**。
+ *
+ * 让模型在"我做不到这件事"时，能主动查生态里有没有现成能力、没有则拿到造一个的蓝图，
+ * 而不是简单地回一句"我不支持"。这是 otto 作为开放 Agent 容器的关键一环：能力面不再
+ * 只能由人类预先装好，模型可以参与发现与补齐。
+ *
+ * ## 无副作用契约（R1 零豁免的结构性保证，不是保守取舍）
+ *
+ * 本工具**只返回文本引导，绝不执行安装**。理由是安全而非谨慎：
+ * - 工具无任何写盘/装载副作用 → 结构上不存在"模型自己把插件装上了"的路径；
+ * - 用户执行 `otto extension install` 时走的是既有 `runPluginInstall` —— 高危能力确认
+ *   弹窗 → `trustPlugin`/`grantPluginCapabilities`，与人类第三方插件**完全同一条路径**；
+ * - **不新增任何 scope/来源标记**来区分"模型生成的插件"。RFC-229 §10 的事故（借
+ *   `builtin` scope 绕过信任门）已经证明：任何为自动化开的旁路，最终都会变成提权通道。
+ *
+ * 因此"模型能造插件"与"模型能给自己装插件"是两件事——本里程碑只做前者。
+ */
+declare const CapabilityGapArgsSchema: z.ZodObject<{
+  need: z.ZodString;
+  searchTerms: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type CapabilityGapArgs = z.infer<typeof CapabilityGapArgsSchema>;
+/** registry 命中项（宿主侧检索后回传的最小投影）。 */
+interface CapabilityGapHit {
+  id: string;
+  description: string;
+  /** 能力预披露（registry 声明值，非执法源——真实执法在安装时的 manifest 信任门）。 */
+  capabilities?: string[];
+  sourceName: string;
+  /** registry 缓存已过期（结果可能不是最新）。 */
+  stale?: boolean;
+}
+/**
+ * 宿主注入的生态检索能力。返回 `undefined` 表示 registry 不可达（网络/配置问题）——
+ * 与"检索到 0 条"是不同语义，前者要如实告知模型"没查成"而非"生态里没有"。
+ */
+type SearchEcosystem = (searchTerms: string[]) => Promise<{
+  hits: CapabilityGapHit[];
+  warnings: string[];
+} | undefined>;
+/**
+ * 会话级去重键：searchTerms 归一化（小写 + 去重 + 排序 + 连接）。
+ *
+ * 用 searchTerms 而非 `need` 做键——`need` 是自由文本，同一缺口每轮措辞都可能不同，
+ * 用它去重等于不去重；searchTerms 是模型给出的检索意图，重复上报时高度稳定。
+ */
+declare function capabilityGapDedupKey(searchTerms: string[]): string;
+declare function createCapabilityGap(searchEcosystem?: SearchEcosystem): AgentTool<CapabilityGapArgs>;
+//#endregion
+//#region src/shell/execution-backend.d.ts
+interface ExecutionBackendOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  /** 毫秒。超时后后端应自行终止命令并在结果里标 `timedOut: true`。 */
+  timeout: number;
+  /** 触发时后端应尽快终止命令（不保证立即，语义与本地 SIGTERM→SIGKILL 分级一致）。 */
+  signal?: AbortSignal;
+}
+interface ExecutionResult {
+  /** stdout+stderr 按到达顺序交错合并的全量字节流（与现有 `SpawnExecuteResult.chunks` 语义一致）。 */
+  chunks: Buffer;
+  stdout: Buffer;
+  stderr: Buffer;
+  exitCode: number;
+  timedOut: boolean;
+}
+type ExecutionProgressCallback = (chunk: Buffer, source: StreamSource) => void;
+interface ExecutionBackend {
+  /** 后端标识名（日志/调试/配置文件选择用）。 */
+  readonly name: string;
+  /**
+   * 执行一条命令，返回聚合后的 stdout/stderr/exitCode。
+   * 超时应 reject（与现有 `process.spawn()` 行为一致：`Process timed out after ${timeout}ms`）；
+   * 非超时失败（如 spawn 本身失败）应 reject 底层错误；正常退出（含非零 exitCode）应 resolve。
+   */
+  execute(command: string, args: string[], options: ExecutionBackendOptions, onProgress?: ExecutionProgressCallback): Promise<ExecutionResult>;
+}
+/**
+ * 晚绑定 provider（M16a `SandboxProvider` 同款范式，见 `bash.ts` 对 `sandbox` 的解析方式）。
+ * 无参数——是否用某个执行后端通常是会话/全局级配置，不存在"按命令名选后端"的真实场景
+ * （对比 `SandboxProvider` 接受 `{command}` 上下文用于命令级 bypass 决策，见 RFC-297 D1a
+ * 自查补充说明）。未来若出现命令级选择后端的真实需求，再按需给 provider 加参数。
+ */
+type ExecutionBackendProvider = () => ExecutionBackend;
+//#endregion
+//#region src/shell/process.d.ts
+type StreamSource = 'stdout' | 'stderr';
+type ProgressCallback = (chunk: Buffer, source: StreamSource) => void;
+interface SpawnExecuteOptions {
+  timeout: number;
+  cwd?: string;
+  signal?: AbortSignal;
+  env?: Record<string, string>;
+  onProgress?: ProgressCallback;
+  /** OS 级沙箱策略。未注入时直接 spawn（保持兼容行为）。 */
+  sandbox?: SandboxStrategy;
+  /**
+   * 项目根目录（沙箱可写域锚点）。
+   * 与 cwd 是不同概念：cwd 是命令工作目录（bash targetDir，可为项目子目录），
+   * projectRoot 是沙箱允许写入的根。未传时回退 cwd（兼容直接调 spawn 的用法）。
+   */
+  projectRoot?: string;
+  /**
+   * RFC-297：可插拔命令执行后端。未提供时回退 `LocalExecutionBackend`（即本函数迁移前的
+   * 原生 `node:child_process.spawn` 行为，零回归）。可传实例或晚绑定 provider。
+   */
+  backend?: ExecutionBackend | ExecutionBackendProvider;
+}
+//#endregion
+//#region src/shell/sandbox/types.d.ts
+/**
+ * OS 级沙箱策略接口（M16a）。
+ *
+ * 在 spawn() 层注入，包装 child_process.spawn 的参数以在隔离环境中执行命令。
+ * 与 coding/session/sandbox.ts 的 SandboxRunner（L2 重执行隔离）是不同关注点：
+ * 本接口用于**首次执行即隔离**，非重放沙箱。
+ */
+interface SandboxStrategy {
+  /** 策略标识名（用于日志/调试/配置文件选择）。 */
+  readonly name: string;
+  /**
+   * 包装 spawn 参数，返回经沙箱包装后的 command / args / options。
+   * spawn() 使用返回的参数执行，对上游调用方完全透明。
+   */
+  wrap(input: SandboxWrapInput): SandboxWrapResult;
+  /**
+   * 释放沙箱持有的临时资源（临时文件等）。
+   * 应在不再需要该策略实例时调用。
+   */
+  dispose(): Promise<void>;
+}
+interface SandboxWrapInput {
+  /** 要执行的命令（如 'sh'） */
+  command: string;
+  /** 命令参数（如 ['-c', 'echo hello']） */
+  args: string[];
+  /** spawn 选项（cwd / timeout / signal / env / onProgress） */
+  options: SpawnExecuteOptions;
+  /** 项目根目录（用于路径约束；沙箱通常将可写范围限定在此目录内） */
+  projectRoot: string;
+}
+interface SandboxWrapResult {
+  /** 经沙箱包装后的命令 */
+  command: string;
+  /** 经沙箱包装后的参数 */
+  args: string[];
+  /** 经沙箱包装后的选项（可修改 cwd / env 等） */
+  options: SpawnExecuteOptions;
+}
+/**
+ * 沙箱策略晚绑定提供者（M16a settings 接线）。
+ *
+ * createBash 在工具创建期注入，但策略本身可在运行期变化
+ * （settings.sandbox 在 app.start() 才 load，且支持热更新）。
+ * 每次命令执行时调用，返回当前生效策略；undefined = 无沙箱。
+ * M4 1b-2：可选 ctx 让提供者按当前操作裁决——被批准 bypass 的命令返回 undefined（该次不套沙箱）。
+ */
+type SandboxProvider = (ctx?: {
+  command?: string;
+}) => SandboxStrategy | undefined;
+//#endregion
+//#region src/shell/background-types.d.ts
+/**
+ * 后台进程注册表的结构化 port。
+ *
+ * tools 与 runtime 互不依赖（都依赖 agent），故此处定义工具侧所需的最小接口，
+ * runtime 的 `ProcessRegistry`（含 `globalProcessRegistry` 单例）结构化满足它，
+ * 由组合根（coding）注入。避免 tools→runtime 循环依赖。
+ */
+type BackgroundProcessStatus = 'running' | 'killing' | 'exited' | 'killed';
+/** RFC-223：委托后台进程的服务协议分类——从运行时输出识别，best-effort。 */
+type ServiceProtocol = 'http' | 'ws' | 'tcp';
+/** RFC-223：从后台进程运行时输出识别到的服务信息（url 优先，退化到纯端口）。 */
+interface DetectedService {
+  url?: string;
+  port?: number;
+  protocol: ServiceProtocol;
+}
+interface BackgroundProcessInfo {
+  id: string;
+  sessionId: string;
+  pid: number;
+  command: string;
+  status: BackgroundProcessStatus;
+  exitCode?: number;
+  logPath?: string;
+  port?: number;
+  url?: string;
+  startedAt: number;
+  /** RFC-223：运行时输出识别到的服务信息（比 port/url 更精确时覆盖，见 D2 去重规则）。 */
+  detectedService?: DetectedService;
+}
+interface BackgroundProcessRegisterInput {
+  id: string;
+  sessionId: string;
+  /** 子进程句柄：注册表据此监听自然退出 + 推导 pgid。 */
+  child: ChildProcess;
+  command: string;
+  cwd: string;
+  logPath?: string;
+  port?: number;
+  url?: string;
+}
+interface BackgroundProcessPort {
+  register(input: BackgroundProcessRegisterInput): BackgroundProcessInfo;
+  get(id: string): BackgroundProcessInfo | undefined;
+  getForSession(sessionId: string, id: string): BackgroundProcessInfo | undefined;
+  listForSession(sessionId: string): BackgroundProcessInfo[];
+  /** 优雅停止：SIGTERM→grace→SIGKILL。 */
+  kill(id: string): Promise<void>;
+  /**
+   * RFC-223：运行时输出识别到新的服务信息时调用（D2 去重规则由实现方——`ProcessRegistry`
+   * ——内部处理："最近一条更优先"：新 URL 覆盖旧 URL/无 URL；新 port-only 不覆盖已有 URL）。
+   * 进程已不在册（已退出/被驱逐）时静默忽略，不抛错。
+   */
+  updateDetectedService(id: string, service: DetectedService): void;
+}
+//#endregion
+//#region src/orchestration/capture-file-state.d.ts
+declare const CaptureFileStateArgsSchema: z.ZodObject<{
+  plan_status: z.ZodOptional<z.ZodString>;
+  recent_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  findings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type CaptureFileStateArgs = z.infer<typeof CaptureFileStateArgsSchema>;
+type CaptureFileState = (args: {
+  planStatus?: string;
+  recentFiles?: string[];
+  findings?: string[];
+}) => Promise<{
+  success: boolean;
+  summary: string;
+  timestamp: number;
+}>;
+declare function createCaptureFileState(captureFileState?: CaptureFileState): AgentTool<CaptureFileStateArgs>;
+//#endregion
+//#region src/orchestration/learn.d.ts
+declare const LearnArgsSchema: z.ZodObject<{
+  tags: z.ZodArray<z.ZodString>;
+  trigger: z.ZodString;
+  insight: z.ZodString;
+  scope: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+    workspace: "workspace";
+    local: "local";
+  }>>>;
+}, z.core.$strip>;
+type LearnArgs = z.infer<typeof LearnArgsSchema>;
+type LearnCallback = (args: {
+  tags: string[];
+  trigger: string;
+  insight: string;
+  sessionId: string;
+  scope?: 'workspace' | 'local';
+}) => Promise<{
+  success: boolean;
+  lessonId?: string; /** RFC-036 R4:命中近似既有经验、复用而非新增(去重)。 */
+  deduped?: boolean;
+  error?: string;
+}>;
+declare function createLearn(sessionId: string, learn?: LearnCallback): AgentTool<LearnArgs>;
+//#endregion
+//#region src/orchestration/list-models.d.ts
+interface ModelCatalogEntry {
+  id: string;
+  provider: string;
+  /** 能力优势标签（planning/knowledge/coding/reasoning/vision/speed/long-context）。 */
+  strengths: string[];
+  /** 是否经实时拉取确认「当前账号可用」（会话配置内）。 */
+  available: boolean;
+  /**
+   * 是否通过 usability gate(已认证 + 非 429 风险)——subagent 选型应只从 usable!==false 中选。
+   * 缺省(undefined)视为可用(host 未提供 gate 信息时向后兼容)。
+   */
+  usable?: boolean;
+  /** usable===false 时的原因(unauthenticated / oauth-429-risk),供 LLM 理解为何不可选。 */
+  unusableReason?: string;
+}
+/** host 注入：按 sessionId 返回该会话的模型目录（含会话级可用集合 + 可用性）。可同步或异步。 */
+type ModelCatalogQuery = (sessionId?: string) => ModelCatalogEntry[] | Promise<ModelCatalogEntry[]>;
+//#endregion
+//#region src/session/session-manager.d.ts
+declare const SessionManagerArgsSchema: z.ZodObject<{
+  action: z.ZodEnum<{
+    list: "list";
+    create: "create";
+    remove: "remove";
+    compact: "compact";
+  }>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SessionManagerArgs = z.infer<typeof SessionManagerArgsSchema>;
+interface SessionManagerTool {
+  list: () => Promise<Array<{
+    id: string;
+    title: string;
+    messageCount: number;
+  }>>;
+  create: (title?: string) => Promise<{
+    id: string;
+  }>;
+  remove: (id: string) => Promise<boolean>;
+  compact: (id: string) => Promise<boolean>;
+}
+interface SessionManagerToolOptions {
+  sessionManager?: SessionManagerTool;
+}
+declare function createSessionManagerTool(options: SessionManagerToolOptions): AgentTool<SessionManagerArgs>;
+//#endregion
+//#region src/skill/skill.d.ts
+type LoadSkill = (path: string) => Promise<{
+  success: boolean;
+  name?: string;
+  error?: string;
+}>;
+type ExecuteSkill = (name: string) => Promise<{
+  success: boolean;
+  content?: string;
+  error?: string;
+}>;
+//#endregion
+//#region src/memory/memory-record.d.ts
+type RecordMemory = (entry: {
+  name: string;
+  description: string;
+  content: string;
+  scope?: 'workspace' | 'local' | 'project-shared';
+}) => Promise<void>;
+//#endregion
+//#region src/memory/memory-read.d.ts
+type ReadMemory = (name: string) => Promise<string | null>;
+//#endregion
+//#region src/orchestration/delegation-runners.d.ts
+/**
+ * 委派 runner 回调契约（M90-02）：宿主注入给 `task_delegate` 的 fork/team 执行体。
+ * 原分别定义在 fork-call.ts / team-run.ts；那两个独立工具已被 task_delegate 的
+ * mode=fork/team 吸收（§10 C5），类型抽到此中性处供工具面与 register-builtin 共用。
+ */
+/** mode=fork：在全新隔离会话里跑 prompt-only 子任务（不继承父上下文，§10 C15）。 */
+type ForkRunner = (prompt: string, depth?: number, signal?: AbortSignal) => Promise<{
+  ok: boolean;
+  value?: string;
+  error?: string;
+}>;
+/** mode=team：跑声明式多 agent team（topology 由 swarm 决，.otto/teams/*.md）。 */
+type RunTeam = (team: string, input: string, signal?: AbortSignal, depth?: number) => Promise<{
+  success: boolean;
+  output?: string;
+  pattern?: string;
+  error?: string;
+}>;
+//#endregion
+//#region src/register-builtin.d.ts
+interface OrchestrationCapability {
+  dispatchTask: TaskDispatch;
+  getTask?: GetTask;
+  listTasks?: ListTasks;
+  updateTask?: UpdateTask;
+  getBackgroundOutput?: GetBackgroundOutput;
+  cancelBackground?: CancelBackground;
+  writeTodos?: WriteTodos;
+  /** 起一个隔离可变作业（origin:'main'）。缺省 → delegate_job 回 missingCapability。 */
+  startJob?: StartJob;
+}
+interface AgentsCapability {
+  callAgent: CallAgent;
+}
+interface ForkCapability {
+  fork: ForkRunner;
+}
+interface SkillsCapability {
+  loadSkill: LoadSkill;
+  executeSkill: ExecuteSkill;
+}
+interface MemoryCapability {
+  recordMemory: RecordMemory;
+  readMemory: ReadMemory;
+  /**
+   * RFC-340 M2：会话归档召回（压缩折叠掉的历史全文）。
+   *
+   * **可选**——归档重建依赖 `MemoryManager` 的 `loadSessionEntries` 注入，V 形态/
+   * 无持久化会话拿不到。缺省时归档工具整组**不注册**（`tool-nodes` 的 `when` 门），
+   * 模型看不到它，而不是注册一个恒失败的工具（对齐 `capabilityGap` 既有纪律）。
+   */
+  archive?: {
+    read: ReadArchive;
+    list: ListArchives;
+  };
+}
+interface TeamCapability {
+  runTeam: RunTeam;
+}
+interface SessionCapability {
+  manager: SessionManagerTool;
+}
+interface FeaturesCapability {
+  captureFileState?: CaptureFileState;
+  learn?: LearnCallback;
+  sessionId?: string;
+  /** LSP 工具 opt-in（语言服务器需本机安装；缺省不注册）。 */
+  enableLsp?: boolean;
+  /**
+   * bash OS 级沙箱策略（缺省 = 无沙箱，保持兼容）。
+   * provider 形态支持晚绑定：settings.sandbox 在 app.start() 才 load 且可热更新。
+   */
+  sandbox?: SandboxStrategy | SandboxProvider;
+  /** HITL grill 能力（按 sessionId 路由到会话闸）。缺省 → grill_me 兜底 fail-soft。 */
+  grill?: SessionGrill;
+  /** 列出当前会话可用模型 + 能力优势（供 list_models 工具 → subagent 选型）。 */
+  listModels?: ModelCatalogQuery;
+  /**
+   * 后台进程注册表 port。注入 → bash 支持 run_in_background +
+   * 注册 bash_output/kill_shell；缺省 → run_in_background 优雅降级为前台。
+   */
+  processRegistry?: BackgroundProcessPort;
+}
+interface RegisterBuiltinOptions {
+  orchestration: OrchestrationCapability;
+  agents: AgentsCapability;
+  fork?: ForkCapability;
+  skills?: SkillsCapability;
+  memory?: MemoryCapability;
+  team?: TeamCapability;
+  session?: SessionCapability;
+  features?: FeaturesCapability;
+  /** task_delegate 描述所需的 declared agent profile 列表 */
+  agentProfiles?: Array<{
+    name: string;
+    description: string;
+    preferredModelTier?: string;
+  }>;
+  /** Schedule callbacks (schedule_create/list/delete/run/cancel tools). */
+  schedule?: {
+    readonly create: ScheduleCreateCallback;
+    readonly list: ScheduleListCallback;
+    readonly delete: ScheduleDeleteCallback;
+    readonly run: ScheduleRunCallback;
+    readonly cancel: ScheduleCancelCallback;
+  };
+  /** RFC-287 M4：自迭代回路的生态检索能力（缺省 → capability_gap 工具不注册）。 */
+  capabilityGap?: {
+    readonly search: SearchEcosystem;
+  };
+  /** RFC-095：进程追踪器（组合根注入，替代 globalProcessRuntime）。 */
+  processTracker?: _$_x_otto_interchange0.ProcessTracker;
+}
+declare function registerBuiltinTools(registry: ToolRegistry, projectRoot: string, options: RegisterBuiltinOptions): void;
+//#endregion
+//#region src/types.d.ts
+interface ToolMetadata {
+  preset: ToolPreset;
+  category?: string;
+  builtin: boolean;
+  snippet?: string;
+  guideline?: string;
+  /**
+   * 注册来源标签（RFC-105 D4/R2）：插件工具打 `pluginId`，供 `unregisterBySource` 批量清理。
+   * 内置工具/MCP 工具不设置（MCP 走既有 `mcp__` 前缀 unregister 约定，不用此字段）。
+   */
+  source?: string;
+}
+interface RegisteredTool<Args = unknown> extends AgentTool<Args> {
+  metadata: ToolMetadata;
+}
+interface ToolRegistrationOptions {
+  preset?: ToolPreset;
+  category?: string;
+  builtin?: boolean;
+  snippet?: string;
+  guideline?: string;
+  /** description 函数求值所需的 projectRoot，注册时传。 */
+  projectRoot?: string;
+  /** 注册来源（RFC-105 D4）：插件装载器传 `pluginId`。 */
+  source?: string;
+}
+//#endregion
+//#region src/tool-registry.d.ts
+declare class ToolRegistry {
+  private readonly tools;
+  private binaryToolExecutors;
+  private readonly disposers;
+  /**
+   * RFC-303 D4：工具面变更通知（register/unregister/unregisterBySource 后调用）。
+   * 由宿主（App）注入，桥接为 monitor 事件 `tool.registered`/`tool.unregistered`。
+   * 可选——不注入则工具增减不对外广播（不影响注册/注销本身）。
+   */
+  onMutation?: (delta: {
+    added?: string[];
+    removed?: string[];
+    source?: string;
+  }) => void;
+  get size(): number;
+  setBinaryToolExecutors(registry: BinaryToolExecutorRegistry): void;
+  getBinaryToolExecutors(): BinaryToolExecutorRegistry;
+  /** 注册随 registry dispose（app stop）一并释放的清理函数（如 browser session）。best-effort。 */
+  registerDisposer(disposer: () => void | Promise<void>): void;
+  register(tool: unknown, options?: ToolRegistrationOptions): void;
+  register(tools: unknown[], options?: ToolRegistrationOptions): void;
+  unregister(name: string): boolean;
+  unregister(name: string[]): boolean;
+  /**
+   * 注销某来源注册的全部工具（RFC-105 D4/R2：插件卸载/reload 批量清理）。
+   * 只清理 `metadata.source === source` 的条目——不影响内置工具（source 未设置）或
+   * 其他来源。返回注销数量。
+   */
+  unregisterBySource(source: string): number;
+  get(name: string): RegisteredTool | undefined;
+  has(name: string): boolean;
+  getAll(): RegisteredTool[];
+  getAvailable(preset?: ToolPreset): RegisteredTool[];
+  /** M33-02：按 preset 投影并三分流——direct 进模型列表 / deferred 进 tool_search / hidden 仅 dispatch。 */
+  project(preset?: ToolPreset): {
+    direct: RegisteredTool[];
+    deferred: RegisteredTool[];
+  };
+  /**
+   * Tool Reference 段的默认总预算（tokens）。同 `@x-otto/memory` 的预算门同一治理动机——
+   * MCP/插件工具经 `register()` 的 `guideline`/`snippet` 选项可贡献任意长度文本，
+   * 且无 per-tool 上限；已安装插件数量增长时这段会无界累积（同 skill catalog 此前的
+   * 问题）。本仓 full preset 实测 ~1.7k tokens，取 3 倍留余量，同时挡住"装了一堆长
+   * guideline 插件"的极端场景。
+   */
+  private static readonly TOOL_GUIDANCE_BUDGET_TOKENS;
+  private static estimatedTokens;
+  /**
+   * RFC-303 D6：exposure 泄漏修复——此前用 `getAvailable(preset)` 遍历全集，deferred
+   * （MCP 工具默认态）与 hidden 工具的完整 description 会被渐进披露契约以外的方式
+   * 泄漏进 system prompt（M33 的核心设计是"deferred 工具只能经 tool_search 按需发现"，
+   * 但指引段一直在无条件展开它们的正文）。改用 `project(preset)` 统一投影：direct 集合
+   * 走原有分组渲染，deferred 集合只输出一行聚合提示（不展开 description，省 token 且不
+   * 破坏渐进披露），hidden 集合完全不出现（tool_search 也搜不到，仅供内部派发）。
+   */
+  buildToolGuidance(preset?: ToolPreset): string;
+  clear(): void;
+  dispose(): void;
+}
+declare const createToolRegistry: (workspaceDir: string, options: RegisterBuiltinOptions) => ToolRegistry;
+//#endregion
+//#region src/tool-nodes.d.ts
+/**
+ * 工具装配上下文。**least-privilege**——只暴露工具装配真需的能力子集，
+ * 不再挂整包 `RegisterBuiltinOptions`（宿主编排全套）。每个能力按需注入命名字段，工具工厂无法
+ * 越权触达无关宿主编排细节（规则 10：能力层不泄漏宿主知识）。
+ */
+interface ToolNodeContext {
+  readonly projectRoot: string;
+  readonly registry: ToolRegistry;
+  readonly orchestration: OrchestrationCapability;
+  readonly agents: AgentsCapability;
+  readonly features: FeaturesCapability;
+  /** 统一降级：skills 缺组时已解析的占位实现（文案单源在 register-builtin）。 */
+  readonly loadSkill: LoadSkill;
+  readonly executeSkill: ExecuteSkill;
+  /** 委派 fork runner（task_delegate fork mode）。缺省 → 该路径优雅降级。 */
+  readonly fork?: ForkCapability;
+  /** 多代理 team runner（task_delegate team mode）。 */
+  readonly team?: TeamCapability;
+  /** 跨会话 memory 读写（memory_record/memory_read）。 */
+  readonly memory?: MemoryCapability;
+  /** 会话管理工具（session_manager）。缺省 → 整组跳过。 */
+  readonly session?: SessionCapability;
+  /** task_delegate 描述所需的 declared agent profile 列表。 */
+  readonly agentProfiles?: Array<{
+    name: string;
+    description: string;
+    preferredModelTier?: string;
+  }>;
+  /**
+   * RFC-287 M4：自迭代回路的生态检索能力。缺省 → `capability_gap` 工具不注册
+   * （`when` 门），模型看不到该工具。
+   */
+  readonly capabilityGap?: {
+    readonly search: SearchEcosystem;
+  };
+  readonly schedule?: {
+    readonly create: ScheduleCreateCallback;
+    readonly list: ScheduleListCallback;
+    readonly delete: ScheduleDeleteCallback;
+    readonly run: ScheduleRunCallback;
+    readonly cancel: ScheduleCancelCallback;
+  };
+  /** RFC-095：进程追踪器（组合根注入）。 */
+  readonly processTracker?: ProcessTracker;
+}
+interface ToolNode {
+  /**
+   * 本节点产出的 canonical 工具名（**必填**）。register-builtin 无条件断言
+   * `create` 实产名集合 === names——漏声明或 create 漂移在注册时 fail-fast，不再静默绕过。
+   */
+  readonly names: readonly string[];
+  readonly preset: ToolPreset;
+  readonly category: string;
+  /** 行为指南（注入 system prompt；同 category 同串在 buildToolGuidance 渲染时去重）。 */
+  readonly guidance?: string;
+  /** opt-in / 能力闸：缺省恒注册；返回 false → 整组跳过。 */
+  readonly when?: (ctx: ToolNodeContext) => boolean;
+  /** 工具构造（单一来源）；返回该节点产出的一组工具。 */
+  readonly create: (ctx: ToolNodeContext) => AgentTool[];
+}
+declare const TOOL_NODES: readonly ToolNode[];
+//#endregion
+//#region src/fs/read.d.ts
+declare const ReadArgsSchema: z.ZodObject<{
+  path: z.ZodString;
+  limit: z.ZodOptional<z.ZodNumber>;
+  offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ReadArgs = z.infer<typeof ReadArgsSchema>;
+declare function createRead(projectRoot: string): AgentTool<ReadArgs>;
+//#endregion
+//#region src/fs/write.d.ts
+declare const WriteArgsSchema: z.ZodObject<{
+  path: z.ZodString;
+  content: z.ZodString;
+  createDirectories: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type WriteArgs = z.infer<typeof WriteArgsSchema>;
+declare function createWrite(projectRoot: string): AgentTool<WriteArgs>;
+//#endregion
+//#region src/fs/edit.d.ts
+declare const EditArgsSchema: z.ZodObject<{
+  path: z.ZodString;
+  oldContent: z.ZodString;
+  newContent: z.ZodString;
+}, z.core.$strip>;
+type EditArgs = z.infer<typeof EditArgsSchema>;
+declare function createEdit(projectRoot: string): AgentTool<EditArgs>;
+//#endregion
+//#region src/orchestration/write-todos.d.ts
+declare const WriteTodosArgsSchema: z.ZodObject<{
+  title: z.ZodOptional<z.ZodString>;
+  action: z.ZodEnum<{
+    set: "set";
+    update: "update";
+  }>;
+  todos: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+      pending: "pending";
+      failed: "failed";
+      in_progress: "in_progress";
+      done: "done";
+      skipped: "skipped";
+    }>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type WriteTodosArgs = z.infer<typeof WriteTodosArgsSchema>;
+declare function createWriteTodos(writeTodos?: WriteTodos): AgentTool<WriteTodosArgs>;
+//#endregion
+//#region src/orchestration/agent-call-description.d.ts
+/**
+ * agent-call-description.ts —— declared agent profiles 的描述段构建器（RFC-302 共享模块）。
+ *
+ * RFC-302（委派单一入口）：原 `buildAgentCallDescription` 把「探询句 + agents 段」揉在
+ * 一个函数里，只服务 agent_call。合并后 agents 段由 task_delegate / agent_call 共用，
+ * 探询句由各调用方自己的静态主体提供——本函数只产「agents 段」：空 profiles → ''，
+ * 非空 → 'Available agents:' 列表 + fuzzy match 提示（不带探询句，调用方拼接）。
+ * M3 结案时 agent_call 工厂删除，本共享模块保留。
+ */
+interface AgentSummary {
+  name: string;
+  description: string;
+  slot?: string;
+  readOnly?: boolean;
+}
+/**
+ * 生成 declared agents 描述段（含 Available agents 列表 + fuzzy match 提示）。
+ * 空 profiles → ''（调用方描述回退为自己的静态主体）。拼接约定：`静态主体 + (段 ? '\n' + 段 : '')`，
+ * 与旧 buildAgentCallDescription 非空分支输出字节一致（探询句\nAvailable agents:…）。
+ */
+declare function buildDelegationAgentListDescription(profiles: AgentSummary[]): string;
+//#endregion
+//#region src/orchestration/task-inspect.d.ts
+declare const TaskInspectArgsSchema: z.ZodObject<{
+  action: z.ZodEnum<{
+    output: "output";
+    get: "get";
+    list: "list";
+  }>;
+  taskId: z.ZodOptional<z.ZodString>;
+  statusFilter: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+    all: "all";
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+  }>>>;
+}, z.core.$strip>;
+type TaskInspectArgs = z.infer<typeof TaskInspectArgsSchema>;
+interface TaskInspectOptions {
+  get?: GetTask;
+  list?: ListTasks;
+  output?: GetBackgroundOutput;
+}
+declare function createTaskInspect(_projectRoot: string, options: TaskInspectOptions): AgentTool<TaskInspectArgs>;
+//#endregion
+//#region src/orchestration/task-control.d.ts
+declare const TaskControlArgsSchema: z.ZodObject<{
+  action: z.ZodEnum<{
+    cancel: "cancel";
+    retry: "retry";
+  }>;
+  taskId: z.ZodString;
+}, z.core.$strip>;
+type TaskControlArgs = z.infer<typeof TaskControlArgsSchema>;
+interface TaskControlOptions {
+  update?: UpdateTask;
+  cancelBackground?: CancelBackground;
+}
+declare function createTaskControl(_projectRoot: string, options: TaskControlOptions): AgentTool<TaskControlArgs>;
+//#endregion
+//#region src/orchestration/tool-search.d.ts
+declare const ToolSearchArgsSchema: z.ZodObject<{
+  query: z.ZodString;
+}, z.core.$strip>;
+type ToolSearchArgs = z.infer<typeof ToolSearchArgsSchema>;
+declare function createToolSearch(/** 返回当前 deferred 工具池（由 registry.project() 提供）。 */
+
+getDeferredTools: () => RegisteredTool[]): AgentTool<ToolSearchArgs>;
+//#endregion
+//#region src/orchestration/constants.d.ts
+/**
+ * 直接派生子代理的工具名（**子代理生成器 denylist**）——`allowSubagents=false` 时由
+ * session-config-resolver 据此剔除，防锁定 agent 递归起子代理。
+ *
+ * RFC-074 D9：这是 orchestration `category` 的**有意子集**（category 还含 write_todos/list_models/
+ * task_inspect 等管理类，非生成器，不应被剔），故不从 category 派生。新增"会起子代理"的工具时
+ * 必须在此登记；`tool-nodes.test` 的漂移守卫断言本集合 ⊆ 真实工具名（堵 team_run/fork_call 类幻影）。
+ */
+declare const ORCHESTRATION_TOOL_NAMES: Set<string>;
+//#endregion
+//#region src/web/fetch.d.ts
+declare const WebFetchArgsSchema: z.ZodObject<{
+  url: z.ZodString;
+  format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+    text: "text";
+    markdown: "markdown";
+    raw: "raw";
+  }>>>;
+  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  maxLength: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type WebFetchArgs = z.infer<typeof WebFetchArgsSchema>;
+declare function createWebFetch(_projectRoot: string): AgentTool<WebFetchArgs>;
+//#endregion
+//#region src/web/search.d.ts
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface WebSearchProvider {
+  readonly id: string;
+  /** 结构化/官方 API=true；HTML 抓取(易随页面改版失效)=false → 输出标注不可靠。 */
+  readonly reliable: boolean;
+  search(query: string, limit: number, signal?: AbortSignal): Promise<SearchResult[]>;
+}
+declare const WebSearchArgsSchema: z.ZodObject<{
+  query: z.ZodString;
+  limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+type WebSearchArgs = z.infer<typeof WebSearchArgsSchema>;
+interface WebSearchOptions {
+  /** 直接注入 provider（测试/自定义后端）。优先于 env 推断。 */
+  provider?: WebSearchProvider;
+  /** Brave API key（覆盖 env）。 */
+  apiKey?: string;
+  fetchImpl?: FetchLike;
+}
+declare function createWebSearch(_projectRoot: string, options?: WebSearchOptions): AgentTool<WebSearchArgs>;
+//#endregion
+//#region src/lsp/types.d.ts
+interface LSPServerConfig {
+  id: string;
+  command: string[];
+  extensions: string[];
+  disabled?: boolean;
+  env?: Record<string, string>;
+  initialization?: Record<string, unknown>;
+}
+interface Position {
+  line: number;
+  character: number;
+}
+interface Range {
+  start: Position;
+  end: Position;
+}
+interface Location {
+  uri: string;
+  range: Range;
+}
+interface LocationLink {
+  targetUri: string;
+  targetRange: Range;
+  targetSelectionRange: Range;
+  originSelectionRange?: Range;
+}
+interface SymbolInfo {
+  name: string;
+  kind: number;
+  location: Location;
+  containerName?: string;
+}
+interface DocumentSymbol {
+  name: string;
+  kind: number;
+  range: Range;
+  selectionRange: Range;
+  children?: DocumentSymbol[];
+}
+interface Diagnostic {
+  range: Range;
+  severity?: number;
+  code?: string | number;
+  source?: string;
+  message: string;
+}
+interface TextDocumentIdentifier {
+  uri: string;
+}
+interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier {
+  version: number | null;
+}
+interface TextEdit {
+  range: Range;
+  newText: string;
+}
+interface TextDocumentEdit {
+  textDocument: VersionedTextDocumentIdentifier;
+  edits: TextEdit[];
+}
+interface CreateFile {
+  kind: 'create';
+  uri: string;
+  options?: {
+    overwrite?: boolean;
+    ignoreIfExists?: boolean;
+  };
+}
+interface RenameFile {
+  kind: 'rename';
+  oldUri: string;
+  newUri: string;
+  options?: {
+    overwrite?: boolean;
+    ignoreIfExists?: boolean;
+  };
+}
+interface DeleteFile {
+  kind: 'delete';
+  uri: string;
+  options?: {
+    recursive?: boolean;
+    ignoreIfNotExists?: boolean;
+  };
+}
+interface WorkspaceEdit {
+  changes?: {
+    [uri: string]: TextEdit[];
+  };
+  documentChanges?: (TextDocumentEdit | CreateFile | RenameFile | DeleteFile)[];
+}
+interface PrepareRenameResult {
+  range: Range;
+  placeholder?: string;
+}
+interface ServerLookupInfo {
+  id: string;
+  command: string[];
+  extensions: string[];
+}
+type ServerLookupResult = {
+  status: 'found';
+  server: ResolvedServer;
+} | {
+  status: 'not_configured';
+  extension: string;
+  availableServers: string[];
+} | {
+  status: 'not_installed';
+  server: ServerLookupInfo;
+  installHint: string;
+};
+interface ResolvedServer {
+  id: string;
+  command: string[];
+  extensions: string[];
+  priority: number;
+  env?: Record<string, string>;
+  initialization?: Record<string, unknown>;
+  /**
+   * workspace/configuration 应答按 section 注入的配置（M6-09，去硬编码）。
+   * 例：`{ json: { validate: { enable: true } } }`。未提供则 json 段回退默认、其余空对象。
+   */
+  settings?: Record<string, unknown>;
+}
+//#endregion
+//#region src/lsp/lsp-server-manager.d.ts
+declare class LSPServerManager {
+  private static instance;
+  private clients;
+  private cleanupInterval;
+  private readonly IDLE_TIMEOUT;
+  private readonly INIT_TIMEOUT;
+  /** RFC-095：进程追踪器（组合根注入）。 */
+  private processTracker?;
+  private constructor();
+  static getInstance(): LSPServerManager;
+  /** RFC-095：设置进程追踪器（组合根装配时调用）。 */
+  setProcessTracker(tracker: ProcessTracker): void;
+  private getKey;
+  private startCleanupTimer;
+  private cleanupIdleClients;
+  getClient(root: string, server: ResolvedServer): Promise<LSPClient>;
+  warmupClient(root: string, server: ResolvedServer): void;
+  releaseClient(root: string, serverId: string): void;
+  isServerInitializing(root: string, serverId: string): boolean;
+  stopAll(): Promise<void>;
+}
+declare const lspManager: LSPServerManager;
+//#endregion
+//#region src/lsp/lsp-client.d.ts
+declare class LSPClient {
+  private readonly root;
+  private readonly server;
+  private readonly processTracker?;
+  private process;
+  private nextId;
+  private pending;
+  private buffer;
+  private contentLength;
+  private processExited;
+  private stderrBuffer;
+  private diagnosticsStore;
+  private readonly diagnosticsWaiter;
+  private openedFiles;
+  private documentVersions;
+  private lastSyncedText;
+  private readonly REQUEST_TIMEOUT;
+  constructor(root: string, server: ResolvedServer, processTracker?: ProcessTracker | undefined);
+  start(): Promise<void>;
+  initialize(): Promise<void>;
+  private rejectAllPending;
+  stop(): Promise<void>;
+  isAlive(): boolean;
+  private processBuffer;
+  private onMessage;
+  private sendRequest;
+  private sendNotification;
+  private respond;
+  openFile(filePath: string): Promise<void>;
+  definition(filePath: string, line: number, character: number): Promise<unknown>;
+  references(filePath: string, line: number, character: number, includeDeclaration?: boolean): Promise<unknown>;
+  documentSymbols(filePath: string): Promise<unknown>;
+  workspaceSymbols(query: string): Promise<unknown>;
+  diagnostics(filePath: string): Promise<{
+    items: Diagnostic[];
+  }>;
+  prepareRename(filePath: string, line: number, character: number): Promise<unknown>;
+  rename(filePath: string, line: number, character: number, newName: string): Promise<unknown>;
+}
+//#endregion
+//#region src/lsp/lsp-wrapper.d.ts
+declare function findWorkspaceRoot(filePath: string): string;
+declare function withLspClient<T>(filePath: string, fn: (client: LSPClient) => Promise<T>): Promise<T>;
+//#endregion
+//#region src/lsp/definition.d.ts
+declare const DefinitionArgsSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  line: z.ZodNumber;
+  character: z.ZodNumber;
+}, z.core.$strip>;
+type DefinitionArgs = z.infer<typeof DefinitionArgsSchema>;
+declare function createLspDefinition(_projectRoot: string): AgentTool<DefinitionArgs>;
+//#endregion
+//#region src/lsp/references.d.ts
+declare const ReferencesArgsSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  line: z.ZodNumber;
+  character: z.ZodNumber;
+  includeDeclaration: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ReferencesArgs = z.infer<typeof ReferencesArgsSchema>;
+declare function createLspReferences(_projectRoot: string): AgentTool<ReferencesArgs>;
+//#endregion
+//#region src/lsp/symbols.d.ts
+declare const SymbolsArgsSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  scope: z.ZodDefault<z.ZodEnum<{
+    workspace: "workspace";
+    document: "document";
+  }>>;
+  query: z.ZodOptional<z.ZodString>;
+  limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SymbolsArgs = z.infer<typeof SymbolsArgsSchema>;
+declare function createLspSymbols(_projectRoot: string): AgentTool<SymbolsArgs>;
+//#endregion
+//#region src/lsp/diagnostics.d.ts
+declare const DiagnosticsArgsSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  severity: z.ZodOptional<z.ZodEnum<{
+    error: "error";
+    all: "all";
+    warning: "warning";
+    information: "information";
+    hint: "hint";
+  }>>;
+}, z.core.$strip>;
+type DiagnosticsArgs = z.infer<typeof DiagnosticsArgsSchema>;
+declare function createLspDiagnostics(_projectRoot: string): AgentTool<DiagnosticsArgs>;
+//#endregion
+//#region src/lsp/rename.d.ts
+declare const PrepareRenameArgsSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  line: z.ZodNumber;
+  character: z.ZodNumber;
+}, z.core.$strip>;
+type PrepareRenameArgs = z.infer<typeof PrepareRenameArgsSchema>;
+declare function createLspPrepareRename(_projectRoot: string): AgentTool<PrepareRenameArgs>;
+declare const RenameArgsSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  line: z.ZodNumber;
+  character: z.ZodNumber;
+  newName: z.ZodString;
+}, z.core.$strip>;
+type RenameArgs = z.infer<typeof RenameArgsSchema>;
+declare function createLspRename(_projectRoot: string): AgentTool<RenameArgs>;
+//#endregion
+//#region src/shell/sandbox/noop.d.ts
+declare function createNoopSandbox(): SandboxStrategy;
+//#endregion
+//#region src/shell/sandbox/macos-seatbelt.d.ts
+/**
+ * macOS Seatbelt 沙箱选项。
+ */
+interface MacOsSeatbeltOptions {
+  /**
+   * 网络访问策略。默认 'allow'。
+   * 'deny' 时禁止沙箱内进程发起网络连接。
+   */
+  network?: 'allow' | 'deny';
+  /**
+   * 额外可写路径（绝对路径）。
+   * 项目根目录和临时目录已默认允许；额外路径按需添加。
+   */
+  writablePaths?: string[];
+  /**
+   * 凭证读隔离（opt-in，endgame review 余 backlog #1 的真正落点）：拒绝读取这些子树。
+   * seatbelt 默认 `(allow file-read* /)` 整盘可读 → 凭证目录（~/.ssh 等）默认可被读出外泄；
+   * 此项在 profile 末尾追加 `(deny file-read* (subpath ...))`（SBPL 末匹配胜，deny 盖过前面的
+   * allow，包括可写根内的子树）。仅拦读、不拦写（写由 file-guard/protected-paths 另管）。
+   * 注意：deny 后沙箱内 git-over-ssh / aws-cli / gpg 会因读不到密钥而失败——故为 opt-in。
+   */
+  denyReadPaths?: string[];
+}
+/**
+ * macOS Seatbelt（sandbox-exec）沙箱策略。
+ *
+ * 用 `/usr/bin/sandbox-exec -f <profile>` 包装
+ * 命令执行。动态生成 .sb 文件，执行后清理。
+ *
+ * 约束：
+ * - 文件系统：只读访问系统路径，可写仅限 projectRoot + /tmp + 指定额外路径
+ * - 网络：按 options.network 控制
+ * - 进程：允许 fork（bash 命令常需 fork 子进程）
+ *
+ * 注意：仅在 macOS 平台可用（sandbox-exec 是 macOS 特有工具）。
+ */
+declare class MacOsSeatbeltSandbox implements SandboxStrategy {
+  readonly name = "macos-seatbelt";
+  private readonly options;
+  private readonly profilePathByContent;
+  constructor(options?: MacOsSeatbeltOptions);
+  wrap(input: SandboxWrapInput): SandboxWrapResult;
+  dispose(): Promise<void>;
+  /** 生成 Seatbelt profile 文本 */
+  private buildProfile;
+  /**
+   * 同步确保 profile 临时文件存在（spawn 调用点同步执行，需要文件立即可读）。
+   * 同内容复用缓存路径；文件被外部清理（如系统 tmp 清扫）时重写。
+   */
+  private ensureProfileSync;
+}
+declare function createMacOsSeatbeltSandbox(options?: MacOsSeatbeltOptions): MacOsSeatbeltSandbox;
+//#endregion
+//#region src/shell/sandbox/bubblewrap.d.ts
+/**
+ * Linux Bubblewrap 沙箱选项。
+ */
+interface BubblewrapOptions {
+  /**
+   * 网络访问策略。默认 'allow'。
+   * 'deny' 时不创建网络命名空间（去 --share-net），进程无网络访问。
+   */
+  network?: 'allow' | 'deny';
+  /**
+   * 额外可写路径（绝对路径）。
+   * 项目根目录通过 --bind 已可写；系统路径（/usr /lib /bin /etc）通过 --ro-bind 只读挂载。
+   * 临时目录（/tmp）由 bwrap 自动创建 tmpfs 隔离。
+   */
+  writablePaths?: string[];
+  /**
+   * 凭证读隔离（opt-in）：拒绝读取这些子树。
+   * bwrap 是 allowlist-bind 模型——未绑定的路径在沙箱内**根本不可见**，故 `~/.ssh` 在项目目录
+   * 外时本就读不到（ENOENT），无需处理。此项只覆盖边角：凭证目录**落在已绑定区内**（如项目根
+   * 恰为 $HOME → `--bind $HOME` 把 ~/.ssh 也暴露了）时，用 `--tmpfs <dir>` 以空 tmpfs 遮蔽。
+   */
+  denyReadPaths?: string[];
+}
+/**
+ * Linux Bubblewrap (bwrap) 沙箱策略。
+ *
+ * 使用 bwrap 子进程包装（用户态，无需内核模块或 root 权限）。
+ * bwrap 比 Firejail 更轻量，是 Flatpak/snap 使用的底层沙箱技术。
+ *
+ * 约束：
+ * - 文件系统：系统路径只读绑定（--ro-bind），项目目录可写（--bind），/tmp 隔离（--tmpfs）
+ * - 网络：按 options.network 控制（--share-net 显式保留 / --unshare-net 隔离）
+ * - 进程/命名空间：--unshare-all 全命名空间隔离 + --cap-drop ALL 去特权
+ *
+ * 威胁模型（M16a-R1，与 seatbelt 对称）：写保护 + 网络开关，**不承诺** env/文件读隔离
+ * （seatbelt 同样允许 file-read* /）。env 透传宿主：--clearenv 会丢 PATH/HOME，
+ * node/git 等真实命令直接不可用，且读隔离在 file-read* 全放行下本就不成立。
+ *
+ * 前置要求：系统中需安装 bwrap（`which bwrap`，常见于 flatpak 或 bubblewrap 包）。
+ * 未安装时 spawn 会收到 ENOENT 错误（子进程 spawn 失败，由调用方的错误传递链处理）。
+ */
+declare class BubblewrapSandbox implements SandboxStrategy {
+  readonly name = "bubblewrap";
+  private readonly options;
+  constructor(options?: BubblewrapOptions);
+  wrap(input: SandboxWrapInput): SandboxWrapResult;
+  dispose(): Promise<void>;
+}
+declare function createBubblewrapSandbox(options?: BubblewrapOptions): BubblewrapSandbox;
+//#endregion
+//#region src/shell/sandbox/platform.d.ts
+/**
+ * 平台沙箱选项（联合 macOS Seatbelt 与 Linux Bubblewrap 的可配字段）。
+ */
+interface PlatformSandboxOptions {
+  /** 网络访问策略。默认 'allow'。 */
+  network?: 'allow' | 'deny';
+  /**
+   * 额外可写路径（绝对路径）。
+   * 项目根目录和 /tmp 已默认允许，无需在此列出。
+   */
+  writablePaths?: string[];
+  /**
+   * 凭证读隔离（opt-in）：拒绝读取这些子树（绝对路径）。
+   * 标准凭证集见 {@link credentialDenyReadPaths}。seatbelt 末尾追加 deny；bwrap 仅遮蔽落在绑定区内者。
+   */
+  denyReadPaths?: string[];
+  /**
+   * 强制指定平台策略名，跳过 process.platform 自动检测。
+   * 用于测试或强制使用特定后端。
+   */
+  force?: 'seatbelt' | 'bubblewrap' | 'noop';
+}
+/**
+ * 标准凭证读隔离路径集（opt-in `protectCredentials` 展开为此）：
+ * `~/.ssh`、`~/.aws`、`~/.gnupg` + otto auth store 目录（默认 `~/.config/otto`，
+ * 经 OTTO_AUTH_PATH 覆盖时取其所在目录）。
+ */
+declare function credentialDenyReadPaths(): string[];
+/**
+ * 按平台自动选择沙箱策略：
+ * - darwin → macOS Seatbelt (sandbox-exec)
+ * - linux  → Bubblewrap (bwrap)
+ * - 其他   → Noop（Windows 等回退）
+ *
+ * 每个平台使用最优 OS 级沙箱技术，无需调用方判断平台。
+ */
+declare function createPlatformSandbox(options?: PlatformSandboxOptions): SandboxStrategy;
+/**
+ * M4 Phase 2 preflight：当前平台的 OS 沙箱是否**实际可用**。
+ * - darwin：`sandbox-exec` 是 macOS 内置 → true。
+ * - linux：需安装 `bwrap`（bubblewrap）→ 探测 PATH/常见路径；缺失 → false。
+ * - 其它平台：无沙箱 → false。
+ *
+ * 默认开（Phase 2）必须先过此关：缺 bwrap 的 Linux 主机若强行套 bwrap，spawn ENOENT
+ * 会让**每条命令失败**（fail-closed 但用户体验=全挂）。preflight 让默认开在不可用时
+ * 优雅降级为「无沙箱 + 一次告警」，而非破坏。
+ */
+declare function isPlatformSandboxAvailable(): boolean;
+//#endregion
+export { type BackgroundProcessInfo, type BackgroundProcessPort, type BackgroundProcessRegisterInput, type BackgroundProcessStatus, BinaryToolExecutorRegistry, type BubblewrapOptions, type CapabilityGapHit, type CaptureFileState, type DocumentSymbol, type ExecuteSkill, type ForkRunner, LSPClient, type LSPServerConfig, type LearnCallback, type LoadSkill, type Location, type LocationLink, type MacOsSeatbeltOptions, ORCHESTRATION_TOOL_NAMES, type PlatformSandboxOptions, type PrepareRenameResult, type ReadMemory, type RecordMemory, type RegisterBuiltinOptions, type RegisteredTool, type ResolvedServer, type RunTeam, type SandboxConfig, type SandboxProvider, type SandboxStrategy, type SandboxWrapInput, type SandboxWrapResult, type SearchEcosystem, type ServerLookupResult, type SessionGrill, type SessionManagerTool, type SymbolInfo, TOOL_NODES, type ToolMetadata, type ToolNode, type ToolNodeContext, type ToolRegistrationOptions, ToolRegistry, type WorkspaceEdit, buildDelegationAgentListDescription, capabilityGapDedupKey, createBinaryToolExecutorRegistry, createBubblewrapSandbox, createCapabilityGap, createCaptureFileState, createEdit, createGrillMe, createLearn, createLspDefinition, createLspDiagnostics, createLspPrepareRename, createLspReferences, createLspRename, createLspSymbols, createMacOsSeatbeltSandbox, createNoopSandbox, createPlatformSandbox, createRead, createSessionManagerTool, createTaskControl, createTaskInspect, createToolRegistry, createToolSearch, createWebFetch, createWebSearch, createWrite, createWriteTodos, credentialDenyReadPaths, findWorkspaceRoot, isPlatformSandboxAvailable, lspManager, registerBuiltinTools, withLspClient };
+//# sourceMappingURL=index.d.ts.map