@robota-sdk/agent-tools 3.0.0-beta.8 → 3.0.0-beta.81

package/dist/node/index.d.ts

@@ -1,370 +1,1047 @@
-import { IToolRegistry, ITool, IToolSchema, TToolParameters, TUniversalValue, IFunctionTool, TToolExecutor, IEventService, IToolExecutionContext, IToolResult, IParameterValidationResult, IOpenAPIToolConfig } from '@robota-sdk/agent-core';
-
+import { FunctionTool, IToolSchema, TToolExecutor, TToolParameters, TUniversalValue, ToolExecutionError } from "@robota-sdk/agent-core";
+import { TypeOf, ZodType, z } from "zod";
+import { IEgressDeps, IEgressPolicy } from "@robota-sdk/agent-core/node";
+import fg from "fast-glob";
+//#region src/types/tool-result.d.ts
 /**
  * Result returned by a CLI tool invocation
  */
-interface TToolResult {
-    success: boolean;
-    output: string;
-    error?: string;
-    exitCode?: number;
-}
-
-/**
- * Tool registry implementation
- * Manages tool registration, validation, and retrieval
- */
-declare class ToolRegistry implements IToolRegistry {
-    private tools;
-    /**
-     * Register a tool
-     */
-    register(tool: ITool): void;
-    /**
-     * Unregister a tool
-     */
-    unregister(name: string): void;
-    /**
-     * Get tool by name
-     */
-    get(name: string): ITool | undefined;
-    /**
-     * Get all registered tools
-     */
-    getAll(): ITool[];
-    /**
-     * Get tool schemas
-     */
-    getSchemas(): IToolSchema[];
-    /**
-     * Check if tool exists
-     */
-    has(name: string): boolean;
-    /**
-     * Clear all tools
-     */
-    clear(): void;
-    /**
-     * Get tool names
-     */
-    getToolNames(): string[];
-    /**
-     * Get tools by pattern
-     */
-    getToolsByPattern(pattern: string | RegExp): ITool[];
-    /**
-     * Get tool count
-     */
-    size(): number;
-    /**
-     * Validate tool schema
-     */
-    private validateToolSchema;
-}
-
-/**
- * FunctionTool - Type definitions for Facade pattern implementation
- *
- * REASON: Complex Zod schema type compatibility requires separation of concerns
- * ALTERNATIVES_CONSIDERED:
- * 1. Fix all Zod undefined issues in single file (creates maintenance burden)
- * 2. Use any types strategically (reduces type safety)
- * 3. Remove Zod support entirely (breaks existing functionality)
- * 4. Create complex conditional types (adds cognitive overhead)
- * 5. Use type assertions everywhere (increases runtime risk)
- * NOTE: Tool functionality is now integrated into @robota-sdk/agent-tools package
- */
-
-/**
- * Zod schema compatibility types
- */
-interface IZodParseResult {
-    success: boolean;
-    data?: TToolParameters;
-    error?: string | Error;
-}
-interface IZodSchemaDef {
-    typeName?: string;
-    innerType?: IZodSchema;
-    valueType?: IZodSchema;
-    checks?: Array<{
-        kind: string;
-        value?: TUniversalValue;
-    }>;
-    shape?: () => Record<string, IZodSchema>;
-    type?: IZodSchema;
-    values?: TUniversalValue[];
-    description?: string;
-}
-interface IZodSchema {
-    parse(value: TToolParameters): TToolParameters;
-    safeParse(value: TToolParameters): IZodParseResult;
-    _def?: IZodSchemaDef;
+interface IToolInvocationResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  exitCode?: number;
+  /** Start line number of the edit in the original file (Edit tool only) */
+  startLine?: number;
+}
+//#endregion
+//#region src/sandbox/types.d.ts
+interface ISandboxRunOptions {
+  timeoutMs?: number;
+  workingDirectory?: string;
+}
+interface ISandboxRunResult {
+  stdout: string;
+  stderr?: string;
+  exitCode: number;
+}
+interface IWorkspaceManifestFileEntry {
+  type: 'file';
+  content: string;
+  encoding?: 'utf8';
+}
+interface IWorkspaceManifestDirectoryEntry {
+  type: 'dir';
+}
+interface IWorkspaceManifestLocalFileEntry {
+  type: 'localFile';
+  src: string;
+}
+interface IWorkspaceManifestLocalDirectoryEntry {
+  type: 'localDir';
+  src: string;
+}
+interface IWorkspaceManifestGitRepositoryEntry {
+  type: 'gitRepo';
+  url: string;
+  ref?: string;
+  shallow?: boolean;
+}
+interface IWorkspaceManifestS3MountEntry {
+  type: 's3Mount';
+  bucket: string;
+  prefix?: string;
+  region: string;
+}
+interface IWorkspaceManifestGcsMountEntry {
+  type: 'gcsMount';
+  bucket: string;
+  prefix?: string;
+}
+interface IWorkspaceManifestR2MountEntry {
+  type: 'r2Mount';
+  bucket: string;
+  accountId: string;
+  prefix?: string;
+}
+interface IWorkspaceManifestAzureBlobMountEntry {
+  type: 'azureBlobMount';
+  container: string;
+  account: string;
+  prefix?: string;
+}
+type TWorkspaceManifestEntry = IWorkspaceManifestFileEntry | IWorkspaceManifestDirectoryEntry | IWorkspaceManifestLocalFileEntry | IWorkspaceManifestLocalDirectoryEntry | IWorkspaceManifestGitRepositoryEntry | IWorkspaceManifestS3MountEntry | IWorkspaceManifestGcsMountEntry | IWorkspaceManifestR2MountEntry | IWorkspaceManifestAzureBlobMountEntry;
+interface IWorkspaceManifestPermissions {
+  read?: string[];
+  write?: string[];
+}
+interface IWorkspaceManifest {
+  entries: Record<string, TWorkspaceManifestEntry>;
+  environment?: Record<string, string>;
+  permissions?: IWorkspaceManifestPermissions;
+}
+interface IWorkspaceManifestApplyOptions {
+  targetRoot?: string;
+  hostRoot?: string;
+}
+type TWorkspaceManifestApplyStatus = 'applied' | 'unsupported';
+interface IWorkspaceManifestAppliedEntry {
+  path: string;
+  type: TWorkspaceManifestEntry['type'];
+  status: TWorkspaceManifestApplyStatus;
+  message?: string;
+}
+interface IWorkspaceManifestApplyResult {
+  entries: IWorkspaceManifestAppliedEntry[];
 }
 /**
- * Parameter type validation options
+ * How a sandbox's filesystem relates to the host's (issue #3081).
+ *
+ * - `shared` — OS-level confinement of commands over the host filesystem (Seatbelt, bubblewrap).
+ *   File tools stay on the host, bounded by the path guard and the permission rules.
+ * - `separate` — a remote or VM filesystem (E2B, in-memory). EVERY file tool must route through the
+ *   sandbox, or a search would read one filesystem while an edit writes another.
  */
-interface IFunctionToolValidationOptions {
-    strict?: boolean;
-    allowUnknown?: boolean;
-    validateTypes?: boolean;
+type TSandboxFilesystem = 'shared' | 'separate';
+/** A process to start: the executable, its arguments, and where it runs. */
+interface ICommandInvocation {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  /** Data handed to the process on descriptors 3, 4, …, each written whole and then closed. */
+  readonly inputDescriptors?: readonly Uint8Array[];
+  /** Runs once the process has exited; a returned note is appended to the command's output. */
+  readonly afterExit?: () => string | undefined;
 }
+interface ISandboxClient {
+  /** Absent means `separate`: every client before this field existed had its own filesystem. */
+  readonly filesystem?: TSandboxFilesystem;
+  /**
+   * A `shared` client that confines a host process in place: the shell tool starts the returned
+   * invocation itself, so timeouts, cancellation, output limits and process-group kill stay the
+   * tool's. Returning the invocation unchanged runs the command unconfined.
+   */
+  wrapCommand?(invocation: ICommandInvocation, shellCommand: string): ICommandInvocation;
+  /**
+   * Whether this client confines `shellCommand` and its settings let a confined command run without
+   * a prompt. The permission gate still refuses or asks first for deny rules, ask rules and the
+   * never-auto set.
+   */
+  autoApproves?(shellCommand: string): boolean;
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  applyManifest?(manifest: IWorkspaceManifest, options?: IWorkspaceManifestApplyOptions): Promise<IWorkspaceManifestApplyResult>;
+  /** Return a provider-owned resumable workspace reference. */
+  snapshot?(): Promise<string>;
+  /** Hydrate this client from a provider-owned workspace reference. */
+  restore?(snapshotId: string): Promise<void>;
+}
+interface ISandboxToolOptions {
+  sandboxClient?: ISandboxClient;
+  /** Abort a host file read between bounded chunks. */
+  signal?: AbortSignal;
+  /**
+   * The tool's working-directory root on the host (non-sandbox) path. REQUIRED — ARCH-010.
+   *
+   * For the tools that read and enumerate — `Read`/`Write`/`Edit` and, since SEC-007, `Glob`/`Grep` —
+   * this is a CONTAINMENT boundary: access outside it is refused, decided on canonical (symlink-
+   * resolved) paths. For `Shell`/`Bash` it is the DEFAULT working directory and deliberately not a
+   * boundary — a cwd guard on arbitrary command execution is undone by the first `cd` (see the
+   * shell-tool file header).
+   *
+   * It is required because it was optional: with no root the containment guard used to answer
+   * "allowed", so a construction site that simply forgot supplied an unsandboxed `Read`. The audit
+   * found three layers that had. Optional here means the boundary is a convention each caller may or
+   * may not follow, and a boundary nobody is obliged to supply is not a boundary. Callers that
+   * genuinely mean "this process's directory" now say `process.cwd()` where a reader can see it.
+   */
+  cwd: string;
+}
+//#endregion
+//#region src/sandbox/e2b-sandbox-client.d.ts
+interface IE2BCommandStartOptions {
+  timeoutMs?: number;
+  cwd?: string;
+  background?: false;
+}
+interface IE2BCommandResult {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+  exit_code?: number;
+}
+interface IE2BCommands {
+  run(command: string, options?: IE2BCommandStartOptions): Promise<IE2BCommandResult>;
+}
+interface IE2BFiles {
+  read(path: string): Promise<string | Uint8Array>;
+  write(path: string, content: string): Promise<void>;
+}
+interface IE2BSnapshot {
+  snapshotId?: string;
+  id?: string;
+}
+interface IE2BSandboxAdapter {
+  sandboxId?: string;
+  commands: IE2BCommands;
+  files: IE2BFiles;
+  pause?(): Promise<boolean | string | void>;
+  connect?(): Promise<IE2BSandboxAdapter>;
+  createSnapshot?(): Promise<IE2BSnapshot>;
+}
+interface IE2BSandboxClientOptions {
+  sandbox: IE2BSandboxAdapter;
+  connectSandbox?: (sandboxId: string) => Promise<IE2BSandboxAdapter>;
+  createSandboxFromSnapshot?: (snapshotId: string) => Promise<IE2BSandboxAdapter>;
+}
+declare class E2BSandboxClient implements ISandboxClient {
+  private sandbox;
+  private readonly connectSandbox?;
+  private readonly createSandboxFromSnapshot?;
+  constructor(options: IE2BSandboxClientOptions);
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  snapshot(): Promise<string>;
+  restore(snapshotId: string): Promise<void>;
+}
+//#endregion
+//#region src/sandbox/in-memory-sandbox-client.d.ts
+type TInMemorySandboxRunHandler = (command: string, options: ISandboxRunOptions | undefined, files: ReadonlyMap<string, string>) => Promise<ISandboxRunResult> | ISandboxRunResult;
+interface IInMemorySandboxClientOptions {
+  files?: Record<string, string>;
+  runHandler?: TInMemorySandboxRunHandler;
+}
+declare class InMemorySandboxClient implements ISandboxClient {
+  private readonly files;
+  private readonly snapshots;
+  private readonly runHandler?;
+  private snapshotSequence;
+  constructor(options?: IInMemorySandboxClientOptions);
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  snapshot(): Promise<string>;
+  restore(snapshotId: string): Promise<void>;
+  getFile(path: string): string | undefined;
+}
+//#endregion
+//#region src/sandbox/containment.d.ts
+type TExecutionContainment = 'host' | `sandbox-${TSandboxFilesystem}`;
+declare function describeExecutionContainment(client: ISandboxClient | undefined): TExecutionContainment;
+/** Whether file tools must read and write through the sandbox rather than the host filesystem. */
+declare function routesFilesThroughSandbox(client: ISandboxClient | undefined): boolean;
+//#endregion
+//#region src/sandbox/workspace-manifest.d.ts
+declare function applyWorkspaceManifest(sandboxClient: ISandboxClient, manifest: IWorkspaceManifest, options?: IWorkspaceManifestApplyOptions): Promise<IWorkspaceManifestApplyResult>;
+declare function validateWorkspaceManifestPath(path: string): string;
+//#endregion
+//#region src/sandbox/os-sandbox-policy.d.ts
 /**
- * Schema conversion options
+ * What an OS-level sandbox lets a command touch, written once per backend (issue #3082).
+ *
+ * The same policy becomes bubblewrap arguments on Linux and a Seatbelt profile on macOS:
+ * - the whole filesystem is readable except the `denyRead` paths;
+ * - writes are allowed only inside the workspace, the temporary directories and `allowWrite`;
+ * - inside the workspace, the files that configure git, the agent, MCP servers and shells stay
+ *   read-only, so a confined command cannot change what the next session trusts;
+ * - the network is either reachable or not. There is no per-domain allowlist: that needs a proxy
+ *   process the OS cannot enforce, and a boundary here is only worth what the OS enforces.
  */
-interface ISchemaConversionOptions {
-    includeDescription?: boolean;
-    strictTypes?: boolean;
-    allowAdditionalProperties?: boolean;
+interface IOsSandboxPolicy {
+  /** The workspace root, real path. Writable. */
+  readonly root: string;
+  /** Temporary directories, real paths. Writable. */
+  readonly tempDirectories: readonly string[];
+  /** Further writable paths, absolute. */
+  readonly allowWrite: readonly string[];
+  /** Paths hidden from the command, absolute, with whether each is a directory. */
+  readonly denyRead: readonly {
+    readonly path: string;
+    readonly directory: boolean;
+  }[];
+  readonly network: boolean;
 }
 /**
- * Tool execution metadata
+ * Workspace entries a confined command must not write, relative to the root. `.git` is read-only
+ * as a whole: the files that make git run something (config, hooks, `commondir`, per-worktree
+ * config) are too many and too easy to add to for a list inside it to stay complete, so git
+ * commands that write run unconfined, through the ordinary permission path.
  */
-interface IFunctionToolExecutionMetadata {
-    executionTime: number;
-    toolName: string;
-    parameters: TToolParameters;
+declare function protectedWorkspaceEntries(): readonly string[];
+interface IBubblewrapInput {
+  readonly policy: IOsSandboxPolicy;
+  /** Which of `protectedWorkspaceEntries()` and the writable worktree folders exist. */
+  readonly exists: (path: string) => boolean;
+  /** Entry names in a directory, for the worktrees whose `.git` file must stay put. */
+  readonly listDirectory: (path: string) => readonly string[];
+  readonly cwd: string;
+  readonly command: string;
+  readonly args: readonly string[];
+  /**
+   * The descriptor `bwrap --seccomp` reads the Unix-socket filter from. Required when the network
+   * is off: without it a daemon's socket is still reachable.
+   */
+  readonly seccompDescriptor?: number;
 }
+/** The `bwrap` argument vector that runs `command args` under the policy. */
+declare function bubblewrapArguments(input: IBubblewrapInput): string[];
 /**
- * Tool result with metadata
+ * The Seatbelt profile for `sandbox-exec -p`. Later rules win, so the order below is the policy:
+ * deny writes, allow the writable places, deny the protected entries again, reopen worktrees.
  */
-interface IFunctionToolResult {
-    success: boolean;
-    data: TUniversalValue;
-    metadata?: IFunctionToolExecutionMetadata;
+declare function seatbeltProfile(policy: IOsSandboxPolicy): string;
+//#endregion
+//#region src/sandbox/os-sandbox-client.d.ts
+type TOsSandboxBackend = 'bubblewrap' | 'seatbelt';
+interface IOsSandboxSettings {
+  /** Confine shell commands. */
+  readonly enabled: boolean;
+  /** A confined command runs without a prompt; deny and ask rules still apply first. */
+  readonly autoAllowBashIfSandboxed: boolean;
+  /** Commands (first word) that run unconfined and take the ordinary permission path. */
+  readonly excludedCommands: readonly string[];
+  /** Further writable paths: absolute, `~/`-relative, or relative to the workspace. */
+  readonly allowWrite: readonly string[];
+  /** Paths hidden from confined commands, written the same way. */
+  readonly denyRead: readonly string[];
+  /** Whether confined commands may reach the network. */
+  readonly network: boolean;
+}
+declare const DEFAULT_OS_SANDBOX_SETTINGS: IOsSandboxSettings;
+/** What this machine can do, found once at startup. */
+interface IOsSandboxAvailability {
+  readonly backend?: TOsSandboxBackend;
+  /** The backend's executable, when found and working. */
+  readonly executable?: string;
+  /** What to install or fix, when the platform has a backend but it cannot run. */
+  readonly missing: readonly string[];
+  /** Set when the platform has no backend at all. */
+  readonly unsupportedPlatform?: string;
+}
+interface IDetectOsSandboxOptions {
+  readonly platform?: NodeJS.Platform;
+  readonly arch?: string;
+  /** Test seam; production runs the probe with `spawnSync`. */
+  readonly probe?: (command: string, args: readonly string[]) => {
+    ok: boolean;
+    detail?: string;
+  };
 }
-
+/** Find the platform's backend and check it can actually start a sandbox here. */
+declare function detectOsSandbox(options?: IDetectOsSandboxOptions): IOsSandboxAvailability;
+interface IOsSandboxClientOptions {
+  /** The workspace root. */
+  readonly root: string;
+  readonly availability: IOsSandboxAvailability;
+  readonly settings?: Partial<IOsSandboxSettings>;
+  readonly homeDirectory?: string;
+}
+interface IOsSandboxStatus {
+  readonly settings: IOsSandboxSettings;
+  readonly availability: IOsSandboxAvailability;
+  /** Settings ask for confinement and the backend can provide it. */
+  readonly active: boolean;
+}
+declare class OsSandboxClient implements ISandboxClient {
+  readonly filesystem: "shared";
+  private readonly root;
+  private readonly availability;
+  private readonly homeDirectory;
+  private current;
+  private inFlight;
+  private baseline;
+  /** Entries a clean-up could not restore, with the state they must return to. */
+  private readonly unresolved;
+  constructor(options: IOsSandboxClientOptions);
+  status(): IOsSandboxStatus;
+  /** Change the settings for the next command. */
+  configure(settings: Partial<IOsSandboxSettings>): void;
+  /** Whether `shellCommand` would run confined. */
+  confines(shellCommand: string): boolean;
+  autoApproves(shellCommand: string): boolean;
+  wrapCommand(invocation: ICommandInvocation, shellCommand: string): ICommandInvocation;
+  /**
+   * How each protected entry stands before a command: bubblewrap can mount an existing entry
+   * read-only, but not one that does not exist yet, and a symlink it mounts through to its target
+   * while the link itself stays replaceable. Read with `lstat`, so a dangling link is not "missing".
+   */
+  private protectedEntryStates;
+  /**
+   * Undo what the command did to protected entries it could reach: one it created where none
+   * existed is moved into `.robota/sandbox-quarantine`, and a symlink it replaced is restored. Moved,
+   * not deleted, so nothing the host wrote meanwhile is lost.
+   */
+  /** Whether a path's real location is under the read-only mounts: not the workspace, temp or `allowWrite`. */
+  private resolvesOutsideWritableWorkspace;
+  /**
+   * Never throws: this runs as the command's process closes, and an exception there would take the
+   * host down and leave the entry in place. The quarantine is outside the workspace, under the
+   * user's `~/.robota`, where the command cannot reach it; what cannot be moved there is removed.
+   */
+  private restoreProtectedEntries;
+  /**
+   * Where set-aside entries go: the workspace's own `.robota`, when it was a real directory before
+   * the command — then it was mounted read-only, so the command could not reach it, and a rename
+   * within one filesystem needs no permission inside the entry. Otherwise the user's `~/.robota`.
+   * Decided from the baseline: what is there now may be the command's own replacement.
+   */
+  private quarantineRoot;
+  private setAside;
+  /** The policy for the current settings, with every path made absolute and real. */
+  policy(): IOsSandboxPolicy;
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+}
+//#endregion
+//#region src/retrieval/types.d.ts
 /**
- * Function tool implementation
- * Wraps a JavaScript function as a tool with schema validation
+ * SELFHOST-003: codebase-retrieval adapter contract (v1).
  *
- * Implements IFunctionTool without extending AbstractTool to avoid
- * circular runtime dependency (tools → agents → tools).
- */
-declare class FunctionTool implements IFunctionTool {
-    readonly schema: IToolSchema;
-    readonly fn: TToolExecutor;
-    private eventService;
-    constructor(schema: IToolSchema, fn: TToolExecutor);
-    /**
-     * Get tool name
-     */
-    getName(): string;
-    /**
-     * Set EventService for post-construction injection.
-     * Accepts EventService as-is without transformation.
-     * Caller is responsible for providing properly configured EventService.
-     */
-    setEventService(eventService: IEventService | undefined): void;
-    /**
-     * Execute the function tool
-     */
-    execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
-    /**
-     * Validate parameters (simple boolean result)
-     */
-    validate(parameters: TToolParameters): boolean;
-    /**
-     * Validate tool parameters with detailed result
-     */
-    validateParameters(parameters: TToolParameters): IParameterValidationResult;
-    /**
-     * Get tool description
-     */
-    getDescription(): string;
-    /**
-     * Get detailed validation errors
-     */
-    private getValidationErrors;
-    /**
-     * Validate individual parameter type
-     */
-    private validateParameterType;
-    /**
-     * Validate constructor inputs
-     */
-    private validateConstructorInputs;
+ * Mirrors the sandbox port precedent (`ISandboxClient` in `../sandbox/types.ts`): the port + types live
+ * in `agent-tools` and `createRetrievalTool({ adapter })` composes over the port. The neutral repo-map
+ * ranking adapter (`./repo-map-adapter.ts`) implements this port; the heavy source parser is injected as
+ * the duck-typed `IRetrievalSourceParser` (like `IE2BSandboxAdapter`), and the corpus is supplied from the
+ * surface — so NO heavy parser SDK and NO repo paths live in this package.
+ *
+ * v1 backend = repo-map graph-centrality ranking (no natural-language query). The embedding-vector
+ * backend (`query(nl_text) → top-k`) is a consciously deferred follow-up (P4) that may revise this port.
+ */
+/** A symbol (definition) extracted from a source file by the injected parser. */
+interface IRetrievalSymbol {
+  /** Repo-relative file the symbol is defined in. */
+  file: string;
+  /** Symbol name (function/class/const/…). */
+  name: string;
+  /** Neutral definition kind (e.g. `function`, `class`); opaque to the ranker. */
+  kind: string;
+  /** 1-based line of the definition. */
+  line: number;
+}
+/** One source file parsed into its definitions + the identifiers it references (graph edges). */
+interface IRetrievalParsedFile {
+  /** Symbols defined in this file. */
+  definitions: IRetrievalSymbol[];
+  /** Identifiers this file references (edges toward other files' definitions). */
+  references: string[];
 }
 /**
- * Helper function to create a function tool from a simple function
+ * Duck-typed source-parser port (mirror `IE2BSandboxAdapter`): parse one file's source into its
+ * definitions + references. Injected so no heavy parser SDK becomes an `agent-tools` dependency.
  */
-declare function createFunctionTool(name: string, description: string, parameters: IToolSchema['parameters'], fn: TToolExecutor): FunctionTool;
+interface IRetrievalSourceParser {
+  parse(file: string, content: string): IRetrievalParsedFile;
+}
+/** One corpus file (supplied from the surface — the package holds no repo paths). */
+interface IRetrievalCorpusFile {
+  /** Repo-relative path. */
+  path: string;
+  /** File source. */
+  content: string;
+}
 /**
- * Helper function to create a function tool from Zod schema
+ * A retrieval request: rank the corpus relative to the active files / mentioned identifiers within a
+ * token budget. There is NO natural-language query in v1 (repo-map ranking) — that is the deferred
+ * vector backend's shape.
+ */
+interface IRetrievalRequest {
+  /** Repo-relative files currently in focus; their references seed the ranking (personalization). */
+  activeFiles?: string[];
+  /** Extra identifiers to bias the ranking toward. */
+  mentionedIdentifiers?: string[];
+  /** Maximum tokens the ranked result may consume. */
+  tokenBudget: number;
+}
+/** One ranked result entry (a relevant symbol), with its centrality score + token cost. */
+interface IRetrievalRankedSymbol {
+  file: string;
+  name: string;
+  kind: string;
+  line: number;
+  /** Relevance score (higher = more central/relevant); ranker-defined, monotonic. */
+  score: number;
+  /** Estimated tokens this entry contributes to the budget. */
+  tokens: number;
+}
+/** The result of a retrieval: ranked entries whose total tokens ≤ the request budget. */
+interface IRetrievalResult {
+  /** Ranked entries, most relevant first; `sum(tokens) ≤ request.tokenBudget`. */
+  symbols: IRetrievalRankedSymbol[];
+  /** Total tokens across `symbols` (≤ budget). */
+  totalTokens: number;
+}
+/** The retrieval adapter port (mirror `ISandboxClient`). `createRetrievalTool` composes over this. */
+interface IRetrievalAdapter {
+  retrieve(request: IRetrievalRequest): Promise<IRetrievalResult>;
+}
+/** Tool options carrying the retrieval adapter (mirror `ISandboxToolOptions`). */
+interface IRetrievalToolOptions {
+  adapter?: IRetrievalAdapter;
+}
+/**
+ * One indexed corpus file (SELFHOST-003 P2): its parsed definitions + references. This is the parsed
+ * form the ranker consumes, so a built index lets the adapter rank WITHOUT re-parsing the corpus on
+ * every `retrieve()`.
  */
-declare function createZodFunctionTool(name: string, description: string, zodSchema: IZodSchema, fn: TToolExecutor): FunctionTool;
-
+interface IRepoMapIndexEntry {
+  /** Repo-relative path. */
+  path: string;
+  /** Symbols defined in this file. */
+  definitions: IRetrievalSymbol[];
+  /** Identifiers this file references. */
+  references: string[];
+}
 /**
- * OpenAPI tool implementation
- * Executes API calls based on OpenAPI 3.0 specifications
+ * A built, serializable repo-map index (SELFHOST-003 P2): the whole corpus parsed once. Persist it
+ * (see `serializeRepoMapIndex`/`deserializeRepoMapIndex`) so retrieval is build-once, rank-many. The
+ * `version` guards forward-compatibility of the persisted form.
+ */
+interface IRepoMapIndex {
+  /** Persisted-schema version. */
+  version: number;
+  /** One entry per corpus file, parsed. */
+  entries: IRepoMapIndexEntry[];
+}
+/**
+ * A set of corpus changes to apply incrementally to a built index (SELFHOST-003 P3): only the changed
+ * files are re-parsed; the rest of the index is reused unchanged.
+ */
+interface IRepoMapIndexChanges {
+  /** Files added or modified — re-parsed and upserted into the index. */
+  upserted?: IRetrievalCorpusFile[];
+  /** Repo-relative paths removed — their entries are dropped from the index. */
+  removed?: string[];
+}
+//#endregion
+//#region src/retrieval/repo-map-index.d.ts
+/** Persisted-schema version — bump when `IRepoMapIndex`'s serialized shape changes incompatibly. */
+declare const REPO_MAP_INDEX_VERSION = 1;
+interface IBuildRepoMapIndexOptions {
+  /** Injected source parser (duck-typed; no heavy parser SDK becomes an `agent-tools` dependency). */
+  parser: IRetrievalSourceParser;
+  /** The corpus to index, supplied from the surface (no repo paths live in this package). */
+  corpus: IRetrievalCorpusFile[];
+}
+/** Parse the whole corpus once into a serializable repo-map index. */
+declare function buildRepoMapIndex(options: IBuildRepoMapIndexOptions): IRepoMapIndex;
+/**
+ * Apply corpus changes to a built index INCREMENTALLY (SELFHOST-003 P3): re-parse only the `upserted`
+ * files and drop `removed` paths, reusing every unchanged entry. Returns a new index (the input is not
+ * mutated). A file present in both `removed` and `upserted` is upserted (re-parse wins); a path repeated
+ * within `upserted` is de-duplicated last-wins, so the result always has one entry per path — matching a
+ * full rebuild (entry order does not affect ranking). Unchanged entries are REUSED BY REFERENCE; index
+ * entries are treated as immutable, so callers must not mutate an entry in place.
+ */
+declare function updateRepoMapIndex(index: IRepoMapIndex, changes: IRepoMapIndexChanges, parser: IRetrievalSourceParser): IRepoMapIndex;
+/** Serialize a built index to a neutral JSON string for persistence by the surface. */
+declare function serializeRepoMapIndex(index: IRepoMapIndex): string;
+/**
+ * Restore a built index from its serialized form. Throws on malformed JSON or an unsupported
+ * `version` — a stale/incompatible persisted index must be rebuilt, never silently mis-ranked.
+ */
+declare function deserializeRepoMapIndex(serialized: string): IRepoMapIndex;
+//#endregion
+//#region src/retrieval/repo-map-adapter.d.ts
+/**
+ * Construct from EITHER a prebuilt/persisted `index` (P2) OR a `parser` + `corpus` (parsed once at
+ * construction). At least one form must be supplied (else the constructor throws); if both are given,
+ * `index` takes precedence.
+ */
+interface IRepoMapRetrievalAdapterOptions {
+  /** Injected source parser (duck-typed) — required when building from a corpus. */
+  parser?: IRetrievalSourceParser;
+  /** The corpus to index, supplied from the surface — required when building from a corpus. */
+  corpus?: IRetrievalCorpusFile[];
+  /** A prebuilt/persisted index (SELFHOST-003 P2) — rank over this without re-parsing. */
+  index?: IRepoMapIndex;
+}
+declare class RepoMapRetrievalAdapter implements IRetrievalAdapter {
+  private readonly index;
+  constructor(options: IRepoMapRetrievalAdapterOptions);
+  retrieve(request: IRetrievalRequest): Promise<IRetrievalResult>;
+}
+//#endregion
+//#region src/retrieval/retrieval-tool.d.ts
+declare function createRetrievalTool(options?: IRetrievalToolOptions): FunctionTool;
+//#endregion
+//#region src/computer-use/types.d.ts
+/**
+ * SELFHOST-010: computer-use driver port + perceive→act contract (v1).
  *
- * Implements ITool without extending AbstractTool to avoid
- * circular runtime dependency (tools → agents → tools).
- */
-declare class OpenAPITool implements ITool {
-    readonly schema: IToolSchema;
-    private readonly apiSpec;
-    private readonly operationId;
-    private readonly baseURL;
-    private readonly config;
-    private eventService;
-    constructor(config: IOpenAPIToolConfig);
-    /**
-     * Execute the OpenAPI tool
-     */
-    execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
-    /**
-     * Validate tool parameters
-     */
-    validate(parameters: TToolParameters): boolean;
-    /**
-     * Validate tool parameters with detailed result
-     */
-    validateParameters(parameters: TToolParameters): IParameterValidationResult;
-    /**
-     * Get tool name
-     */
-    getName(): string;
-    /**
-     * Set EventService for post-construction injection.
-     */
-    setEventService(eventService: IEventService | undefined): void;
-    /**
-     * Get tool description
-     */
-    getDescription(): string;
-    /**
-     * Execute the actual API call
-     * @private
-     */
-    private executeAPICall;
-    /**
-     * Find the operation in the OpenAPI specification
-     */
-    private findOperation;
-    /**
-     * Build HTTP request configuration from OpenAPI operation and parameters
-     */
-    private buildRequestConfig;
-    /**
-     * Create tool schema from OpenAPI operation specification
-     */
-    private createSchemaFromOpenAPI;
-    /**
-     * Convert OpenAPI parameter to tool parameter schema
-     */
-    private convertOpenAPIParamToSchema;
-    /**
-     * Convert OpenAPI schema to parameter schema
-     */
-    private convertOpenAPISchemaToParameterSchema;
-    /**
-     * Map OpenAPI type to JSON schema type
-     */
-    private mapOpenAPIType;
-}
-/**
- * Factory function to create OpenAPI tools from specification
- */
-declare function createOpenAPITool(config: IOpenAPIToolConfig): OpenAPITool;
-
-/**
- * FunctionTool - Schema conversion utilities for Facade pattern
+ * Mirrors the sandbox port precedent (`ISandboxClient` in `../sandbox/types.ts`): the port + the typed
+ * action contract live in `agent-tools`, and the tool factory (`createComputerTool({ driver })`) composes
+ * over the port. A neutral `ScriptedComputerDriver` (test-support, under `./testing`) and a zero-dependency
+ * duck-typed `PageComputerDriver` reference adapter (`./page-computer-driver.ts`, mirror `E2BSandboxClient`)
+ * implement this port — so NO heavy browser SDK and NO concrete target (URL/host) live in this package; the
+ * surface supplies the concrete driver + target env.
  *
- * REASON: Complex Zod to JSON schema conversion requires isolated utility functions
- * ALTERNATIVES_CONSIDERED:
- * 1. Keep conversion logic in main class (violates single responsibility)
- * 2. Use third-party library (adds external dependency)
- * 3. Manual conversion each time (code duplication)
- * 4. Runtime type checking only (loses compile-time safety)
- * 5. Remove Zod support (breaks backward compatibility)
- * TODO: Consider caching conversion results for performance
+ * The contract is the OpenAI/Hermes perceive→act loop expressed once, neutrally: `screenshot()` perceives,
+ * and `act(action)` executes one typed mutating action and returns the resulting screenshot so the model
+ * re-perceives. The permission-bearing tool boundary splits in two (`ComputerView` perceives, `Computer`
+ * acts) but the typed action union stays WHOLE here in the driver contract.
  */
-
+/** A perceived screenshot: encoded image bytes the surface produced. */
+interface IComputerScreenshot {
+  /** Base64-encoded image bytes. */
+  data: string;
+  /** IANA media type of the encoded bytes (e.g. `image/png`). */
+  mediaType: string;
+  /** Optional pixel width of the captured surface. */
+  width?: number;
+  /** Optional pixel height of the captured surface. */
+  height?: number;
+}
+/** Mouse button for click/drag actions. */
+type TComputerMouseButton = 'left' | 'right' | 'middle';
+/** A screen coordinate (device-independent pixels from the top-left of the perceived surface). */
+interface IComputerPoint {
+  x: number;
+  y: number;
+}
+/** Click at a coordinate. */
+interface IComputerClickAction {
+  type: 'click';
+  x: number;
+  y: number;
+  button?: TComputerMouseButton;
+}
+/** Double-click at a coordinate. */
+interface IComputerDoubleClickAction {
+  type: 'double_click';
+  x: number;
+  y: number;
+  button?: TComputerMouseButton;
+}
+/** Type literal text at the current focus. */
+interface IComputerTypeAction {
+  type: 'type';
+  text: string;
+}
+/** Press a chord/sequence of keys (e.g. `['Control', 'a']`). */
+interface IComputerKeypressAction {
+  type: 'keypress';
+  keys: string[];
+}
+/** Scroll at a coordinate by a wheel delta. */
+interface IComputerScrollAction {
+  type: 'scroll';
+  x: number;
+  y: number;
+  deltaX: number;
+  deltaY: number;
+}
+/** Drag along a path of points (press at the first point, move through the rest, release at the last). */
+interface IComputerDragAction {
+  type: 'drag';
+  path: IComputerPoint[];
+  button?: TComputerMouseButton;
+}
+/** Wait for the surface to settle. */
+interface IComputerWaitAction {
+  type: 'wait';
+  /** Milliseconds to wait; the driver applies a sensible default when omitted. */
+  ms?: number;
+}
+/**
+ * Hand control to the human (halt-for-user). Executing this suspends the action loop and PAUSES perception
+ * (no screenshot is captured for its duration) so a secret the human types never enters the model context;
+ * control resumes only on an explicit resume signal (`endTakeover()`).
+ */
+interface IComputerTakeoverAction {
+  type: 'takeover';
+  /** Optional human-readable reason surfaced to the user (e.g. `enter your password`). */
+  reason?: string;
+}
+/** The whole typed mutating-action union — stays WHOLE in the driver contract. */
+type TComputerAction = IComputerClickAction | IComputerDoubleClickAction | IComputerTypeAction | IComputerKeypressAction | IComputerScrollAction | IComputerDragAction | IComputerWaitAction | IComputerTakeoverAction;
+/** The discriminant literals of {@link TComputerAction}. */
+type TComputerActionType = TComputerAction['type'];
 /**
- * Convert Zod schema to JSON Schema format with safe undefined handling
+ * The result of executing one action through the driver.
+ *
+ * For every non-takeover action the fresh post-action `screenshot` is present so the model re-perceives.
+ * While a takeover suspends the action loop, perception is paused: `screenshot` is ABSENT and
+ * `takeover` is `true`.
  */
-declare function zodToJsonSchema(schema: IZodSchema, options?: ISchemaConversionOptions): IToolSchema['parameters'];
-
+interface IComputerActionResult {
+  /** Fresh screenshot AFTER the action; absent while a takeover pauses perception. */
+  screenshot?: IComputerScreenshot;
+  /** True while a human takeover suspends the action loop (perception is paused for its duration). */
+  takeover?: boolean;
+}
 /**
- * BashTool — execute shell commands via child_process.spawn
+ * The computer-use driver port (mirror `ISandboxClient`). `createComputerTool` composes over this.
  *
- * Returns TToolResult JSON string. Non-zero exit is returned as success:true
- * with exitCode set, matching Claude Code behaviour (the command ran, it just
- * exited non-zero — the LLM can decide what to do with that information).
+ * `screenshot()` perceives (returns `undefined` while a takeover pauses perception). `act(action)` executes
+ * one typed mutating action and returns the resulting screenshot. `beginTakeover()`/`endTakeover()` are the
+ * optional halt-for-user hooks the surface implements (surface the real window, block/resume perception).
+ */
+interface IComputerDriver {
+  /** Perceive the current surface; `undefined` while a takeover pauses perception. */
+  screenshot(): Promise<IComputerScreenshot | undefined>;
+  /** Execute one typed mutating action and return its result (a fresh screenshot, unless paused). */
+  act(action: TComputerAction): Promise<IComputerActionResult>;
+  /** Optional: begin a human takeover (surface the real window, pause perception). */
+  beginTakeover?(reason?: string): Promise<void>;
+  /** Optional: end a human takeover and resume the action loop + perception. */
+  endTakeover?(): Promise<void>;
+}
+/** Tool options carrying the computer-use driver (mirror `ISandboxToolOptions`). */
+interface IComputerToolOptions {
+  driver?: IComputerDriver;
+}
+/**
+ * Duck-typed browser-page port for the zero-dep `PageComputerDriver` reference adapter (mirror
+ * `IE2BSandboxAdapter`). It is a STRUCTURAL description of a browser-page-shaped object (Playwright/CDP
+ * page); the surface passes the real page. Declaring it here keeps `agent-tools` free of any browser SDK
+ * import — the neutrality invariant (TC-06).
  */
+interface IBrowserPageMouseAdapter {
+  click(x: number, y: number, options?: {
+    button?: TComputerMouseButton;
+    clickCount?: number;
+  }): Promise<void>;
+  move(x: number, y: number): Promise<void>;
+  down(options?: {
+    button?: TComputerMouseButton;
+  }): Promise<void>;
+  up(options?: {
+    button?: TComputerMouseButton;
+  }): Promise<void>;
+  wheel(deltaX: number, deltaY: number): Promise<void>;
+}
+interface IBrowserPageKeyboardAdapter {
+  type(text: string): Promise<void>;
+  press(key: string): Promise<void>;
+}
+interface IBrowserPageAdapter {
+  /** Capture the page as encoded image bytes. */
+  screenshot(options?: {
+    type?: string;
+  }): Promise<Uint8Array | string>;
+  mouse: IBrowserPageMouseAdapter;
+  keyboard: IBrowserPageKeyboardAdapter;
+  /** Optional wait; the driver falls back to a timer when the page does not expose one. */
+  waitForTimeout?(ms: number): Promise<void>;
+}
+//#endregion
+//#region src/computer-use/computer-tool.d.ts
+/** The tool-boundary result shape returned (as JSON) by both `ComputerView` and `Computer`. */
+interface IComputerToolResult {
+  success: boolean;
+  /** Fresh screenshot after the perceive/act; absent while a takeover pauses perception. */
+  screenshot?: IComputerScreenshot;
+  /** True when a human takeover suspends the action loop (perception paused). */
+  takeover?: boolean;
+  /** Error message when the tool could not run (no driver, or an invalid action). */
+  error?: string;
+}
+/** Build the `ComputerView` perceive tool over the injected driver. */
+declare function createComputerViewTool(options?: IComputerToolOptions): FunctionTool;
+/** Build the `Computer` act tool over the injected driver. */
+declare function createComputerActTool(options?: IComputerToolOptions): FunctionTool;
 /**
- * BashTool instance — register with Robota agent tools registry.
+ * Create BOTH computer-use tools — `ComputerView` (perceive) and `Computer` (act) — over one injected
+ * driver. Mirrors `create*Tool(options)`; returns the pair so the assembly layer can spread them into the
+ * default set adapter-gated (see `createDefaultTools`).
  */
-declare const bashTool: FunctionTool;
-
+declare function createComputerTool(options?: IComputerToolOptions): FunctionTool[];
+//#endregion
+//#region src/computer-use/page-computer-driver.d.ts
+interface IPageComputerDriverOptions {
+  /** The real browser page (duck-typed; the surface supplies it). */
+  page: IBrowserPageAdapter;
+  /** Media type of the captured bytes (default `image/png`). */
+  mediaType?: string;
+  /** Default wait when a `wait` action omits `ms` (default 500ms). */
+  defaultWaitMs?: number;
+}
+declare class PageComputerDriver implements IComputerDriver {
+  private readonly page;
+  private readonly mediaType;
+  private readonly defaultWaitMs;
+  private suspended;
+  constructor(options: IPageComputerDriverOptions);
+  private capture;
+  private wait;
+  screenshot(): Promise<IComputerScreenshot | undefined>;
+  act(action: TComputerAction): Promise<IComputerActionResult>;
+  /** Move the pointer along a multi-point path with the button held (mouse down → moves → up). */
+  private performDrag;
+  beginTakeover(_reason?: string): Promise<void>;
+  endTakeover(): Promise<void>;
+}
+//#endregion
+//#region src/implementations/function-tool.d.ts
 /**
- * ReadTool — read a file and return its contents with line numbers (cat -n style).
+ * Helper function to create a function tool from a simple function
+ */
+declare function createFunctionTool(name: string, description: string, parameters: IToolSchema['parameters'], fn: TToolExecutor): FunctionTool;
+/**
+ * What a tool declares about itself beyond its callable shape (CLI-1990).
  *
- * Supports offset/limit for partial reads. Detects binary files and refuses to
- * return their raw bytes. Default limit is 2000 lines.
+ * Optional, and omission is a declaration too: a tool that says nothing is RESIDENT — its schema is
+ * sent on every request, which is what every tool in the tree does today.
  */
+interface IFunctionToolResidencyOptions {
+  /**
+   * Withhold this tool's schema from the model until it is loaded by `ToolSearch` or forced by a
+   * `toolChoice`. Only honoured while the tool-search policy is engaged, so declaring it on a small
+   * tool set costs nothing.
+   */
+  deferLoading?: boolean;
+}
 /**
- * ReadTool instance — register with Robota agent tools registry.
+ * Helper function to create a function tool from Zod schema
  */
-declare const readTool: FunctionTool;
-
+declare function createZodFunctionTool<S extends ZodType>(name: string, description: string, zodSchema: S, fn: TToolExecutor<TypeOf<S>>, residency?: IFunctionToolResidencyOptions): FunctionTool;
+//#endregion
+//#region src/implementations/function-tool/types.d.ts
 /**
- * WriteTool — write content to a file, auto-creating parent directories.
+ * Parameter type validation options
  */
+interface IFunctionToolValidationOptions {
+  strict?: boolean;
+  allowUnknown?: boolean;
+  validateTypes?: boolean;
+}
 /**
- * WriteTool instance — register with Robota agent tools registry.
+ * Tool execution metadata
  */
-declare const writeTool: FunctionTool;
-
+interface IFunctionToolExecutionMetadata {
+  executionTime: number;
+  toolName: string;
+  parameters: TToolParameters;
+}
 /**
- * EditTool — perform string-replace edits on a file.
+ * Tool result with metadata
+ */
+interface IFunctionToolResult {
+  success: boolean;
+  data: TUniversalValue;
+  metadata?: IFunctionToolExecutionMetadata;
+}
+//#endregion
+//#region src/builtins/tool-options.d.ts
+/** Options every builtin tool factory accepts: override the model-facing description. */
+interface IBuiltinToolDescriptionOptions {
+  /** Replaces the default model-facing description verbatim when provided. */
+  description?: string;
+}
+/**
+ * Options for a builtin that touches the host filesystem WITHOUT a sandbox seam (SEC-007).
  *
- * By default, requires the oldString to appear exactly once in the file
- * (ensuring surgical edits). Pass replaceAll:true to replace all occurrences.
+ * `Glob` and `Grep` enumerate; they have no provider-sandbox mode to route through, so a containment
+ * root is the only boundary they can have. Splitting this out of {@link ISandboxBuiltinToolOptions}
+ * keeps them from advertising a `sandboxClient` they would silently ignore.
  */
+interface IContainedBuiltinToolOptions extends IBuiltinToolDescriptionOptions {
+  /**
+   * The directory the tool's filesystem access is confined to. REQUIRED — ARCH-010. An out-of-root
+   * search root is refused, no entry whose CANONICAL path escapes the root is enumerated, and relative
+   * paths the model supplies resolve against this root rather than `process.cwd()`.
+   *
+   * Required rather than optional because the guard used to be fail-open when it was absent, so
+   * omitting it produced an unbounded enumerator rather than an error.
+   */
+  cwd: string;
+}
+/** Options for builtin factories that also operate on the sandbox/host filesystem. */
+interface ISandboxBuiltinToolOptions extends ISandboxToolOptions, IBuiltinToolDescriptionOptions {}
+//#endregion
+//#region src/builtins/shell-tool.d.ts
+/** Options for the shell tool factories (sandbox + description seam + routing-hint derivation). */
+interface IShellToolOptions extends ISandboxBuiltinToolOptions {
+  /** Host-selected executable; absence uses the neutral platform/SHELL default. */
+  shellExecutable?: string;
+  /**
+   * Registered names of the sibling tools available in this assembly (NEUT-002). When provided,
+   * the default description's dedicated-tool routing hints are restricted to this set; when
+   * omitted, the full default hint set is used. Ignored when `description` overrides the text.
+   */
+  availableTools?: readonly string[];
+}
 /**
- * EditTool instance — register with Robota agent tools registry.
+ * Create a `Shell` tool instance — register with the Robota agent tools registry.
+ * The description is resolved at creation time for the host's active shell.
  */
-declare const editTool: FunctionTool;
-
+declare function createShellTool(options: IShellToolOptions): FunctionTool;
 /**
- * GlobTool — fast file pattern search using fast-glob.
- *
- * Excludes node_modules and .git by default.
- * Results are sorted by modification time (most recently modified first).
+ * Create a `Bash` tool instance — the model-familiar alias of the same OS-aware shell tool.
  */
+declare function createBashTool(options: IShellToolOptions): FunctionTool;
+//#endregion
+//#region src/builtins/read-tool.d.ts
+/** A budget refusal is a hard failure so a workflow cannot treat it as file content. */
+declare class ReadByteLimitError extends ToolExecutionError {
+  readonly boundary: 'input' | 'output';
+  constructor(boundary: 'input' | 'output');
+}
+/** Abort is a hard failure; the workflow must not accept a partial read. */
+declare class ReadCancelledError extends ToolExecutionError {
+  constructor();
+}
 /**
- * GlobTool instance — register with Robota agent tools registry.
+ * Create a ReadTool instance — register with Robota agent tools registry.
  */
-declare const globTool: FunctionTool;
-
+declare function createReadTool(options: ISandboxBuiltinToolOptions): FunctionTool;
+//#endregion
+//#region src/builtins/write-tool.d.ts
 /**
- * GrepTool — recursive regex content search.
- *
- * Supports two output modes:
- * - files_with_matches (default): return only file paths that contain a match
- * - content: return matching lines with optional context lines
+ * Create a WriteTool instance — register with Robota agent tools registry.
  */
+declare function createWriteTool(options: ISandboxBuiltinToolOptions): FunctionTool;
+//#endregion
+//#region src/builtins/edit-tool.d.ts
 /**
- * GrepTool instance — register with Robota agent tools registry.
+ * Create an EditTool instance — register with Robota agent tools registry.
  */
-declare const grepTool: FunctionTool;
-
+declare function createEditTool(options: ISandboxBuiltinToolOptions): FunctionTool;
+//#endregion
+//#region src/builtins/glob-tool.d.ts
 /**
- * WebFetchTool — fetch a URL and return its content as text.
- *
- * HTML is stripped to plain text for readability. Uses Node.js native fetch.
- * Output is capped at 30K chars (same as other tools).
+ * Create a GlobTool instance — register with Robota agent tools registry.
+ */
+declare function createGlobTool(options: IContainedBuiltinToolOptions): FunctionTool;
+//#endregion
+//#region src/builtins/grep-tool.d.ts
+/** A grep isolation failure is a hard tool failure, distinct from ordinary no-match/invalid-input results. */
+declare class GrepIsolationError extends ToolExecutionError {
+  readonly reason: 'timeout' | 'cancelled' | 'limit' | 'failed';
+  constructor(reason: 'timeout' | 'cancelled' | 'limit' | 'failed');
+}
+/** Options for the grep tool factory: containment root + description seam + shell-tool reference. */
+interface IGrepToolOptions extends IContainedBuiltinToolOptions {
+  /** Cancels the isolated regex search and waits for its worker to exit. */
+  signal?: AbortSignal;
+  /**
+   * Registered name of the shell tool the default description references (default: `Shell`).
+   * Ignored when `description` overrides the text.
+   */
+  shellToolName?: string;
+}
+/**
+ * Create a GrepTool instance — register with Robota agent tools registry.
+ */
+declare function createGrepTool(options: IGrepToolOptions): FunctionTool;
+//#endregion
+//#region src/builtins/web-fetch-tool.d.ts
+/** #2026: the egress policy this tool fetches under, and the deps a test injects (fetch, DNS lookup). */
+interface IWebFetchEgressOptions {
+  policy?: IEgressPolicy;
+  deps?: IEgressDeps;
+}
+interface IWebFetchToolOptions extends IBuiltinToolDescriptionOptions {
+  egress?: IWebFetchEgressOptions;
+}
+/**
+ * Create a WebFetchTool instance — register with Robota agent tools registry.
+ */
+declare function createWebFetchTool(options?: IWebFetchToolOptions): FunctionTool;
+/**
+ * WebFetchTool instance — register with Robota agent tools registry.
  */
 declare const webFetchTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/web-search-provider.d.ts
 /**
- * WebSearchTool — search the web and return results.
+ * NEUT-008: web-search provider port.
  *
- * Uses Brave Search API when BRAVE_API_KEY is set.
- * Returns an error with setup instructions otherwise.
+ * Mirrors the retrieval/computer-use port precedent (`IRetrievalAdapter`, `IComputerDriver`):
+ * the duck-typed port lives in `agent-tools` and `createWebSearchTool({ provider })` composes
+ * over it. The vendor-specific default adapter (`./brave-search-provider.ts`) implements this
+ * port and is the only place a vendor endpoint may live — the TOOL layer holds no vendor
+ * literals.
+ */
+/** One web search result entry (the tool serializes these verbatim for the model). */
+interface IWebSearchResultItem {
+  title: string;
+  url: string;
+  snippet: string;
+}
+/** A search request: the query plus the maximum number of results the caller wants. */
+interface IWebSearchQuery {
+  query: string;
+  /** Requested maximum result count; a provider may cap it lower (vendor API limits). */
+  limit: number;
+}
+/**
+ * The web-search provider port. Implementations resolve their own credentials/endpoint and
+ * THROW on failure (missing configuration, HTTP error, network error) — the tool layer converts
+ * the thrown message into a structured `IToolInvocationResult` error.
+ */
+interface IWebSearchProvider {
+  search(request: IWebSearchQuery, signal?: AbortSignal): Promise<IWebSearchResultItem[]>;
+}
+/** Options for `createWebSearchTool`: inject a provider (default: the Brave Search adapter). */
+interface IWebSearchToolProviderOptions {
+  provider?: IWebSearchProvider;
+}
+//#endregion
+//#region src/builtins/web-search-tool.d.ts
+/** Options for the web-search tool factory: description seam + provider port injection. */
+interface IWebSearchToolOptions extends IBuiltinToolDescriptionOptions, IWebSearchToolProviderOptions {}
+/**
+ * Create a WebSearchTool instance — register with Robota agent tools registry.
+ */
+declare function createWebSearchTool(options?: IWebSearchToolOptions): FunctionTool;
+/**
+ * WebSearchTool instance — register with Robota agent tools registry.
  */
 declare const webSearchTool: FunctionTool;
-
-export { FunctionTool, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type ISchemaConversionOptions, type IZodParseResult, type IZodSchema, type IZodSchemaDef, OpenAPITool, type TToolResult, ToolRegistry, bashTool, createFunctionTool, createOpenAPITool, createZodFunctionTool, editTool, globTool, grepTool, readTool, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };
+//#endregion
+//#region src/builtins/brave-search-provider.d.ts
+/**
+ * Create the Brave Search provider. Throws from `search()` when `BRAVE_API_KEY` is not set or
+ * the API responds with an error — the tool layer surfaces the message as a structured result.
+ */
+declare function createBraveSearchProvider(): IWebSearchProvider;
+//#endregion
+//#region src/builtins/ask-user-question-tool.d.ts
+/**
+ * Create an `AskUserQuestion` tool instance — register with the Robota agent tools registry.
+ */
+declare function createAskUserQuestionTool(options?: IBuiltinToolDescriptionOptions): FunctionTool;
+/** `AskUserQuestion` tool instance — register with the Robota agent tools registry. */
+declare const askUserQuestionTool: FunctionTool;
+//#endregion
+//#region src/builtins/tool-search-tool.d.ts
+/**
+ * The registered name — agent-core's own constant, re-exported under this package's name so the
+ * execution layer's unknown-tool remedy and this tool can never name two different things.
+ */
+declare const TOOL_SEARCH_NAME = "ToolSearch";
+/** What the model gets back: what is now callable, and what could not be consulted. */
+interface IToolSearchOutput {
+  loaded: Array<{
+    name: string;
+    description: string;
+  }>;
+  unavailableSources: string[];
+}
+/**
+ * Create a `ToolSearch` tool instance — register it RESIDENT with the agent's tool registry.
+ *
+ * It must never itself be deferred: a search tool the model cannot see is a catalog with no way in,
+ * which is the state the vendor's own "at least one tool must stay resident" invariant forbids.
+ */
+declare function createToolSearchTool(options?: IBuiltinToolDescriptionOptions): FunctionTool;
+/** `ToolSearch` tool instance — register with the Robota agent tools registry. */
+declare const toolSearchTool: FunctionTool;
+//#endregion
+//#region src/builtins/tool-search-matching.d.ts
+/** Both vendors default a tool search to five results; so does this one. */
+declare const DEFAULT_TOOL_SEARCH_LIMIT = 5;
+/**
+ * The tools a query selects, best match first and capped at `limit`.
+ *
+ * Ordering is total and deterministic: rank first, then name, so two tools that matched the same way
+ * never trade places between calls. An empty query string matches nothing rather than everything —
+ * "search for nothing" is a question with an empty answer, not a request for the whole catalog.
+ */
+declare function matchDeferredTools(schemas: readonly IToolSchema[], query: string, limit: number): IToolSchema[];
+//#endregion
+export { DEFAULT_OS_SANDBOX_SETTINGS, DEFAULT_TOOL_SEARCH_LIMIT, E2BSandboxClient, GrepIsolationError, type IBrowserPageAdapter, type IBrowserPageKeyboardAdapter, type IBrowserPageMouseAdapter, type IBubblewrapInput, type IBuildRepoMapIndexOptions, type IBuiltinToolDescriptionOptions, type ICommandInvocation, type IComputerActionResult, type IComputerClickAction, type IComputerDoubleClickAction, type IComputerDragAction, type IComputerDriver, type IComputerKeypressAction, type IComputerPoint, type IComputerScreenshot, type IComputerScrollAction, type IComputerTakeoverAction, type IComputerToolOptions, type IComputerToolResult, type IComputerTypeAction, type IComputerWaitAction, type IContainedBuiltinToolOptions, type IDetectOsSandboxOptions, type IE2BSandboxAdapter, type IE2BSandboxClientOptions, type IFunctionToolExecutionMetadata, type IFunctionToolResidencyOptions, type IFunctionToolResult, type IFunctionToolValidationOptions, type IGrepToolOptions, type IInMemorySandboxClientOptions, type IOsSandboxAvailability, type IOsSandboxClientOptions, type IOsSandboxPolicy, type IOsSandboxSettings, type IOsSandboxStatus, type IPageComputerDriverOptions, type IRepoMapIndex, type IRepoMapIndexChanges, type IRepoMapIndexEntry, type IRepoMapRetrievalAdapterOptions, type IRetrievalAdapter, type IRetrievalCorpusFile, type IRetrievalParsedFile, type IRetrievalRankedSymbol, type IRetrievalRequest, type IRetrievalResult, type IRetrievalSourceParser, type IRetrievalSymbol, type IRetrievalToolOptions, type ISandboxBuiltinToolOptions, type ISandboxClient, type ISandboxRunOptions, type ISandboxRunResult, type ISandboxToolOptions, type IShellToolOptions, type IToolInvocationResult, type IToolSearchOutput, type IWebFetchToolOptions, type IWebSearchProvider, type IWebSearchQuery, type IWebSearchResultItem, type IWebSearchToolOptions, type IWebSearchToolProviderOptions, type IWorkspaceManifest, type IWorkspaceManifestAppliedEntry, type IWorkspaceManifestApplyOptions, type IWorkspaceManifestApplyResult, type IWorkspaceManifestAzureBlobMountEntry, type IWorkspaceManifestDirectoryEntry, type IWorkspaceManifestFileEntry, type IWorkspaceManifestGcsMountEntry, type IWorkspaceManifestGitRepositoryEntry, type IWorkspaceManifestLocalDirectoryEntry, type IWorkspaceManifestLocalFileEntry, type IWorkspaceManifestPermissions, type IWorkspaceManifestR2MountEntry, type IWorkspaceManifestS3MountEntry, InMemorySandboxClient, OsSandboxClient, PageComputerDriver, REPO_MAP_INDEX_VERSION, ReadByteLimitError, ReadCancelledError, RepoMapRetrievalAdapter, type TComputerAction, type TComputerActionType, type TComputerMouseButton, type TExecutionContainment, type TInMemorySandboxRunHandler, TOOL_SEARCH_NAME, type TOsSandboxBackend, type TSandboxFilesystem, type TWorkspaceManifestApplyStatus, type TWorkspaceManifestEntry, applyWorkspaceManifest, askUserQuestionTool, bubblewrapArguments, buildRepoMapIndex, createAskUserQuestionTool, createBashTool, createBraveSearchProvider, createComputerActTool, createComputerTool, createComputerViewTool, createEditTool, createFunctionTool, createGlobTool, createGrepTool, createReadTool, createRetrievalTool, createShellTool, createToolSearchTool, createWebFetchTool, createWebSearchTool, createWriteTool, createZodFunctionTool, describeExecutionContainment, deserializeRepoMapIndex, detectOsSandbox, matchDeferredTools, protectedWorkspaceEntries, routesFilesThroughSandbox, seatbeltProfile, serializeRepoMapIndex, toolSearchTool, updateRepoMapIndex, validateWorkspaceManifestPath, webFetchTool, webSearchTool };
+//# sourceMappingURL=index.d.ts.map