indusagi 0.13.7 → 0.13.8

package/dist/types/facade/bot/actions/read-state.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Read-before-edit gate for the WIRED facade tool layer.
+ *
+ * This is the product-side half of the read-edit-gate feature. The framework's
+ * `capabilities/files/read-state-gate.ts` carries the same discipline, but the
+ * product wires the `read` / `edit` / `write` factories exported from
+ * `indusagi/agent` (i.e. these `facade/bot/actions/` factories), so the gate had
+ * to live here too to actually take effect.
+ *
+ * When — and ONLY when — a host passes a {@link ReadStateHandle} via the tool's
+ * options bag, the file tools enforce a small discipline borrowed from
+ * interactive coding agents:
+ *
+ *   1. A file may not be edited or overwritten until it has been *read* in this
+ *      session (so the model is never blindly clobbering content it has not
+ *      seen). Brand-new files (those that do not yet exist on disk) are exempt
+ *      from the write tool's gate.
+ *   2. A file may not be mutated if it has drifted on disk since that read — its
+ *      modification time or byte size advanced past what was recorded — because
+ *      that usually means a human or a linter changed it underneath us.
+ *
+ * After every successful read (and every successful mutation) the recorded state
+ * is refreshed from the fresh on-disk stat, so the next gate check compares
+ * against the latest known-good snapshot.
+ *
+ * The whole mechanism is *additive*: with no handle present, every helper here
+ * is a no-op and the tools behave exactly as they did before. The handle is
+ * duck-typed so the host and these factories agree on shape without a
+ * cross-package type import.
+ */
+/** A single recorded read: the on-disk shape captured at read time. */
+export interface ReadStateRecord {
+    /** File modification time in ms, floored to a whole millisecond. */
+    mtimeMs: number;
+    /** File byte size at read time. */
+    size: number;
+    /** Optional content hash; unused by the default gate but reserved for hosts. */
+    contentHash?: string;
+    /** When the read was recorded; the gate mirrors this to `mtimeMs`. */
+    readAt: number;
+}
+/**
+ * Duck-typed store the host injects to drive the gate. Any object exposing this
+ * shape (e.g. a `Map`-backed wrapper) works; nothing is imported across packages.
+ */
+export interface ReadStateHandle {
+    get(path: string): ReadStateRecord | undefined;
+    set(path: string, rec: ReadStateRecord): void;
+    has(path: string): boolean;
+}
+/** The two byte-stable refusal messages the gate emits. */
+export declare const READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+export declare const MODIFIED_SINCE_READ_MESSAGE = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+/**
+ * Record (or refresh) the read state for `absPath` from a fresh stat.
+ *
+ * No-op when no handle is present. The mtime is floored to a whole millisecond
+ * so a sub-ms clock skew between read and a later compare can never spuriously
+ * trip the staleness check. `readAt` mirrors the floored mtime — no wall-clock
+ * call is made. A failed stat is swallowed: state-keeping is best-effort and
+ * must never mask the real operation's outcome.
+ */
+export declare function recordReadState(handle: ReadStateHandle | undefined, absPath: string): void;
+/** Outcome of a gate check: either cleared, or refused with a message. */
+export type GateOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Enforce the read-before-edit + staleness gate ahead of a mutation.
+ *
+ * With no handle present this always clears (the gate is opt-in). With a handle:
+ *   - refuse when `absPath` has no recorded read this session;
+ *   - refuse when the on-disk modification time or byte size has advanced past
+ *     the recorded read.
+ *
+ * The on-disk mtime is floored the same way the recorded mtime is, so the
+ * comparison is apples-to-apples. A stat failure (e.g. the file vanished) clears
+ * the gate so the underlying tool can surface its own, more specific error.
+ */
+export declare function enforceReadGate(handle: ReadStateHandle | undefined, absPath: string): GateOutcome;

package/dist/types/facade/bot/actions/read-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/read.d.ts

@@ -0,0 +1,43 @@
+import type { AgentTool } from "../types.js";
+import { type ReadStateHandle } from "./read-state.js";
+import { type TruncationResult } from "./truncate.js";
+declare const readSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface ReadToolDetails {
+    truncation?: TruncationResult;
+}
+/**
+ * Pluggable filesystem callbacks for the read tool. Override them to fetch
+ * files from an alternate backend, for instance an SSH or remote-mount layer.
+ */
+export interface ReadOperations {
+    /** Read a file's raw bytes. */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Verify the file can be read, raising if not. */
+    access: (absolutePath: string) => Promise<void>;
+    /** Return the file's image MIME type, or null/undefined for non-image files. */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+export interface ReadToolOptions {
+    /** Default true; when set, large images are shrunk to fit within 2000x2000. */
+    autoResizeImages?: boolean;
+    /** Swap out the filesystem callbacks; the local disk is used by default. */
+    operations?: ReadOperations;
+    /**
+     * Optional read-before-edit gate store. When present, a successful read
+     * records the file's on-disk stat so a later edit/write can verify it was
+     * read first and has not drifted. Absent → no gate bookkeeping (no-op).
+     */
+    readState?: ReadStateHandle;
+}
+export declare function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema>;
+/** Ready-to-use read tool bound to the current working directory. */
+export declare const readTool: AgentTool<import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/read.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/registry.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTool } from "../types.js";
+export type ToolCategory = "core" | "search" | "management" | "web" | "filesystem" | "mcp";
+export interface ToolMetadata {
+    name: string;
+    label: string;
+    category: ToolCategory;
+    description?: string;
+}
+export declare abstract class ToolFactory<TTool extends AgentTool<any> = AgentTool<any>> {
+    abstract readonly metadata: ToolMetadata;
+    abstract create(): TTool;
+}
+export declare class ToolRegistry {
+    private readonly metadata;
+    private readonly factories;
+    register<TTool extends AgentTool<any>>(meta: ToolMetadata, create: () => TTool): void;
+    create(name: string): AgentTool<any>;
+    createMany(names: string[]): AgentTool<any>[];
+    listMetadata(): ToolMetadata[];
+}

package/dist/types/facade/bot/actions/sandbox-backend.d.ts

@@ -0,0 +1,99 @@
+import type { BashOperations } from "./bash.js";
+/** Configuration for the OPT-IN OS sandbox applied to bash command execution. */
+export interface SandboxConfig {
+    /** Master switch. When false/undefined the sandbox seam is a pure no-op. */
+    enabled?: boolean;
+    /**
+     * When true, the sandbox permits outbound network access. When false (the
+     * default) all network traffic is denied at the OS level.
+     */
+    allowNetwork?: boolean;
+    /**
+     * Extra absolute paths the command is allowed to write to, in addition to the
+     * working directory and the OS temp directory which are always writable.
+     */
+    writableRoots?: string[];
+    /**
+     * Override for the temp directory treated as writable. Defaults to the OS
+     * temp directory. Exposed mainly so tests can pin a deterministic value.
+     */
+    tmpDir?: string;
+}
+/** A platform/availability probe result for the OS sandbox tooling. */
+export interface SandboxAvailability {
+    platform: "macos" | "linux" | "unsupported";
+    /** The sandbox launcher binary for this platform, if one exists. */
+    binary: "sandbox-exec" | "bwrap" | null;
+    /** True only when the launcher binary is actually present on PATH. */
+    binaryPresent: boolean;
+    /** Human-readable explanation when the sandbox cannot be applied. */
+    reason?: string;
+}
+/**
+ * Build a Seatbelt profile string for `sandbox-exec -p`.
+ *
+ * Policy: deny by default, allow process exec + read everywhere, allow write
+ * only under the resolved writable roots (cwd + tmp + extras), and deny network
+ * unless `allowNetwork` is set. This is a PURE function — no I/O, no spawning —
+ * so the generated text is unit-testable on any platform.
+ */
+export declare function buildSeatbeltProfile(config: SandboxConfig, cwd: string): string;
+/**
+ * Build the `sandbox-exec` argv that runs `command` under the generated
+ * profile. PURE: returns the argv vector without spawning anything.
+ *
+ * Shape: `sandbox-exec -p <profile> /bin/sh -c <command>`.
+ */
+export declare function buildSeatbeltArgv(config: SandboxConfig, cwd: string, command: string): string[];
+/**
+ * Build the `bwrap` argv that runs `command` with the writable roots bind
+ * mounted read-write over an otherwise read-only root. PURE: no spawning.
+ *
+ * Shape: `bwrap --ro-bind / / [--bind <root> <root> ...] [--unshare-net]
+ *         --dev /dev --proc /proc /bin/sh -c <command>`.
+ *
+ * Network is denied by unsharing the network namespace unless `allowNetwork`.
+ */
+export declare function buildBwrapArgv(config: SandboxConfig, cwd: string, command: string): string[];
+/**
+ * Probe the current platform for OS-sandbox support. Never throws and never
+ * spawns the sandbox itself — it only checks for the launcher binary so callers
+ * can decide between sandboxed execution and an honest passthrough fallback.
+ *
+ * The optional `platform`/`probe` parameters are seams for unit tests so the
+ * pure decision logic can be exercised without depending on the host OS.
+ */
+export declare function sandboxAvailability(platform?: NodeJS.Platform, probe?: (binary: string) => boolean): SandboxAvailability;
+/**
+ * Build the platform-appropriate sandbox argv for `command`, or `null` when no
+ * sandbox can be applied. PURE with respect to the OS: callers pass an
+ * availability result (or rely on the live probe) and get back either the
+ * wrapped argv or `null`, never a spawn.
+ */
+export declare function buildSandboxArgv(config: SandboxConfig, cwd: string, command: string, availability?: SandboxAvailability): string[] | null;
+/** Renders an argv vector into a single `sh -c`-safe command string. */
+export declare function argvToCommandString(argv: string[]): string;
+/** Optional reporting hook so callers can surface sandbox status honestly. */
+export interface SandboxedOperationsOptions {
+    /** Underlying backend that actually spawns. Defaults are supplied by bash.ts. */
+    base: BashOperations;
+    /** Availability probe override (mainly for tests). */
+    availability?: SandboxAvailability;
+    /**
+     * Called once per exec with a human-readable note describing whether the
+     * sandbox was applied or why it was skipped. Lets the caller record the
+     * truth instead of the wrapper silently claiming sandboxing.
+     */
+    onNote?: (note: string) => void;
+}
+/**
+ * Wrap a `BashOperations` backend so each command is executed inside the OS
+ * sandbox when one is available. When the sandbox tool is missing or the
+ * platform is unsupported, the command is passed through UNCHANGED and an
+ * honest note is emitted via `onNote` — we never pretend a command was
+ * sandboxed when it was not.
+ *
+ * When `config.enabled` is falsy this returns the base operations unchanged so
+ * the seam is a guaranteed no-op for the default (off) path.
+ */
+export declare function createSandboxedBashOperations(config: SandboxConfig, options: SandboxedOperationsOptions): BashOperations;

package/dist/types/facade/bot/actions/sandbox-backend.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/todo-store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Todo Store - Persistent todo list management
+ *
+ * @module agent/tools/todo-store
+ * @description
+ * Manages a todo list with optional persistence callbacks.
+ * The coding-agent uses this to integrate with SessionManager for session persistence.
+ *
+ * ## Architecture
+ *
+ * The TodoStore supports two modes:
+ * 1. **Simple mode** (default): Stores todos in memory only
+ * 2. **Persistent mode**: Uses callbacks to persist/load todos
+ *
+ * ## Usage
+ *
+ * ### Simple mode
+ * ```typescript
+ * const store = new TodoStore();
+ * store.setTodos([{ content: "Task", status: "pending", priority: "high" }]);
+ * ```
+ *
+ * ### Persistent mode (coding-agent style)
+ * ```typescript
+ * const store = new TodoStore({
+ *   persist: (todos) => sessionManager.appendCustomEntry('todo', { todos }),
+ *   load: () => loadFromSession(),
+ *   rebuildFromBranch: () => rebuildFromSession(),
+ * });
+ * ```
+ */
+import type { TodoItem, TodoStatus, TodoStoreOptions } from "./todo-types.js";
+export type { TodoItem, TodoStatus, TodoPriority, TodoStoreOptions, TodoToolDetails } from "./todo-types.js";
+declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "cancelled"];
+declare const TODO_PRIORITIES: readonly ["high", "medium", "low"];
+/**
+ * Simple Todo Store for the todo tool.
+ * Supports optional persistence callbacks for session integration.
+ */
+export declare class TodoStore {
+    private todos;
+    private options?;
+    /**
+     * Create a new TodoStore
+     * @param initialTodos - Optional initial todos (takes precedence over load callback)
+     * @param options - Optional persistence callbacks
+     */
+    constructor(initialTodos?: TodoItem[], options?: TodoStoreOptions);
+    constructor(options?: TodoStoreOptions);
+    /**
+     * Get all todos (returns a copy)
+     */
+    getTodos(): TodoItem[];
+    /**
+     * Set todos and persist
+     */
+    setTodos(todos: TodoItem[]): void;
+    /**
+     * Find todos matching a query
+     */
+    find(query: string): TodoItem[];
+    /**
+     * Filter todos by status
+     */
+    filterByStatus(status: TodoStatus): TodoItem[];
+    /**
+     * Rebuild todos from session branch
+     * Called when navigating the session tree
+     */
+    rebuildFromBranch(): void;
+    /**
+     * Remove expired todos
+     */
+    private removeExpired;
+}
+export { TODO_STATUSES, TODO_PRIORITIES };

package/dist/types/facade/bot/actions/todo-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Todo Tool Types - Interfaces for extensible todo storage
+ *
+ * These interfaces allow the todo tool to be extended with custom persistence.
+ * The coding-agent uses these to integrate with SessionManager for session persistence.
+ */
+/**
+ * Todo item status
+ */
+export type TodoStatus = "pending" | "in_progress" | "completed" | "cancelled";
+/**
+ * Todo item priority
+ */
+export type TodoPriority = "high" | "medium" | "low";
+/**
+ * Todo item structure
+ */
+export interface TodoItem {
+    content: string;
+    status: TodoStatus;
+    priority: TodoPriority;
+    expiresAt?: number;
+}
+/**
+ * Todo tool details - returned after todo operations
+ */
+export interface TodoToolDetails {
+    todos: TodoItem[];
+    incompleteCount: number;
+}
+/**
+ * Options for TodoStore - allows custom persistence
+ *
+ * The coding-agent implements these to:
+ * - persist: Save todos to session entries
+ * - load: Load todos from session on startup
+ * - rebuildFromBranch: Restore todos when navigating session tree
+ */
+export interface TodoStoreOptions {
+    /**
+     * Persist todos to storage
+     * Called whenever todos are updated
+     */
+    persist?: (todos: TodoItem[]) => void;
+    /**
+     * Load todos from storage
+     * Called on TodoStore construction
+     */
+    load?: () => TodoItem[];
+    /**
+     * Rebuild todos from session branch
+     * Called when navigating the session tree
+     */
+    rebuildFromBranch?: () => TodoItem[];
+    /**
+     * Callback when todos change
+     * Useful for triggering UI updates
+     */
+    onChange?: (todos: TodoItem[]) => void;
+}
+/**
+ * Session manager interface for type safety
+ * The coding-agent's SessionManager implements this
+ */
+export interface TodoSessionManager {
+    appendCustomEntry(type: string, data: unknown): void;
+    getBranch(): Array<{
+        type?: string;
+        customType?: string;
+        data?: unknown;
+    }>;
+}

package/dist/types/facade/bot/actions/todo.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Todo Tools - Read and write todo lists
+ *
+ * @module agent/tools/todo
+ * @description
+ * Provides tools for managing todo lists. The todos are stored in a TodoStore
+ * which can optionally persist to external storage (e.g., session entries).
+ *
+ * ## Architecture
+ *
+ * Two tools are provided:
+ * - `todoread`: Read the current todo list
+ * - `todowrite`: Update the todo list
+ *
+ * Both tools share the same TodoStore instance for consistency.
+ *
+ * ## Usage
+ *
+ * ### Simple mode
+ * ```typescript
+ * import { todoReadTool, todoWriteTool } from "indusvx/agent";
+ * // Uses default in-memory store
+ * ```
+ *
+ * ### With custom store (persistent mode)
+ * ```typescript
+ * import { createTodoReadTool, createTodoWriteTool, TodoStore } from "indusvx/agent";
+ *
+ * const store = new TodoStore({
+ *   persist: (todos) => sessionManager.appendCustomEntry('todo', { todos }),
+ *   load: () => loadFromSession(),
+ * });
+ *
+ * const todoReadTool = createTodoReadTool(store);
+ * const todoWriteTool = createTodoWriteTool(store);
+ * ```
+ */
+import type { AgentTool } from "../types.js";
+import { TodoStore } from "./todo-store.js";
+import type { TodoToolDetails } from "./todo-types.js";
+export type { TodoItem, TodoStatus, TodoPriority, TodoStoreOptions, TodoToolDetails } from "./todo-types.js";
+export { TodoStore, TODO_PRIORITIES, TODO_STATUSES } from "./todo-store.js";
+declare const TodoReadSchema: import("@sinclair/typebox").TObject<{}>;
+declare const TodoWriteSchema: import("@sinclair/typebox").TObject<{
+    todos: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        content: import("@sinclair/typebox").TString;
+        status: import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">;
+        priority: import("@sinclair/typebox").TUnsafe<"low" | "medium" | "high">;
+    }>>;
+    search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">>;
+}>;
+/**
+ * Create a todo read tool
+ * @param store - The TodoStore to read from
+ * @returns The todoread tool
+ */
+export declare function createTodoReadTool(store: TodoStore): AgentTool<typeof TodoReadSchema, TodoToolDetails>;
+/**
+ * Create a todo write tool
+ * @param store - The TodoStore to write to
+ * @returns The todowrite tool
+ */
+export declare function createTodoWriteTool(store: TodoStore): AgentTool<typeof TodoWriteSchema, TodoToolDetails>;
+/** Default todo read tool using in-memory store */
+export declare const todoReadTool: AgentTool<import("@sinclair/typebox").TObject<{}>, TodoToolDetails>;
+/** Default todo write tool using in-memory store */
+export declare const todoWriteTool: AgentTool<import("@sinclair/typebox").TObject<{
+    todos: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        content: import("@sinclair/typebox").TString;
+        status: import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">;
+        priority: import("@sinclair/typebox").TUnsafe<"low" | "medium" | "high">;
+    }>>;
+    search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">>;
+}>, TodoToolDetails>;

package/dist/types/facade/bot/actions/truncate.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Routines that trim oversized tool output before it reaches the model.
+ *
+ * Two separate ceilings are checked at once, and trimming kicks in the moment
+ * either is reached:
+ *   - a maximum count of lines that may be returned (2500 by default)
+ *   - a maximum count of bytes that may be returned (64KB by default)
+ *
+ * Trims occur at line breaks, so output is never left holding a partial line.
+ * The single exception is when trimming from the tail: should the very last line
+ * by itself blow past the byte ceiling, that line gets cut mid-way.
+ */
+export declare const DEFAULT_MAX_LINES = 2500;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const GREP_MAX_LINE_LENGTH = 512;
+export interface TruncationResult {
+    /** Final text once the budgets have been enforced. */
+    content: string;
+    /** Whether any budget actually forced something to be dropped. */
+    truncated: boolean;
+    /** Which budget caused the cut, or null if everything fit. */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Number of lines the original input had prior to any trimming. */
+    totalLines: number;
+    /** Number of bytes the original input had prior to any trimming. */
+    totalBytes: number;
+    /** How many complete lines survived into the result. */
+    outputLines: number;
+    /** How many bytes the result occupies. */
+    outputBytes: number;
+    /** Set only in the tail case where the closing line had to be cut mid-line. */
+    lastLinePartial: boolean;
+    /** Set when even the leading line by itself blows past the byte budget (head case). */
+    firstLineExceedsLimit: boolean;
+    /** The active line budget. */
+    maxLines: number;
+    /** The active byte budget. */
+    maxBytes: number;
+}
+export interface TruncationOptions {
+    /** Custom line budget; defaults to 2500 when omitted. */
+    maxLines?: number;
+    /** Custom byte budget; defaults to 64KB when omitted. */
+    maxBytes?: number;
+}
+export interface TruncationStrategy {
+    truncate(content: string, options?: TruncationOptions): TruncationResult;
+}
+/**
+ * Render a raw byte count as a compact label a person can read at a glance,
+ * picking B, KB, or MB depending on magnitude.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Retain the leading slice of the content (its first lines/bytes) and discard
+ * what follows. Suited to reading files, where the beginning is most relevant.
+ *
+ * Whole lines are preserved. Should the opening line on its own exceed the byte
+ * budget, an empty result is returned with firstLineExceedsLimit set.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Retain the trailing slice of the content (its last lines/bytes) and discard
+ * what precedes it. Suited to command output, where errors and results land at
+ * the end.
+ *
+ * When the closing line by itself overshoots the byte budget, the returned text
+ * can start partway through that line.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Shorten one line to a character budget, tacking on a marker if it was cut.
+ * Used on search hits whose lines would otherwise run too long.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};

package/dist/types/facade/bot/actions/webfetch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Web Fetch Tool
+ *
+ * Fetches content from a specified URL.
+ * Supports text, markdown, and HTML format options.
+ */
+import type { AgentTool } from "../types.js";
+declare const webFetchSchema: import("@sinclair/typebox").TObject<{
+    url: import("@sinclair/typebox").TString;
+    format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"markdown">, import("@sinclair/typebox").TLiteral<"html">]>>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface WebFetchToolDetails {
+    url: string;
+    format?: "text" | "markdown" | "html";
+    timeout?: number;
+    contentType?: string;
+    fetchedBytes?: number;
+}
+export interface WebFetchToolOptions {
+    /** Maximum response size in bytes (default: 5MB) */
+    maxResponseSize?: number;
+    /** Default timeout in milliseconds (default: 30000) */
+    defaultTimeout?: number;
+    /** Optional proxy base URL that forwards target URL via ?url= */
+    proxyUrl?: string;
+}
+export declare function createWebFetchTool(options?: WebFetchToolOptions): AgentTool<typeof webFetchSchema>;
+/** Default web fetch tool */
+export declare const webFetchTool: AgentTool<import("@sinclair/typebox").TObject<{
+    url: import("@sinclair/typebox").TString;
+    format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"markdown">, import("@sinclair/typebox").TLiteral<"html">]>>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/websearch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Web Search Tool
+ *
+ * Performs real-time web searches by scraping DuckDuckGo's lightweight HTML
+ * results endpoint. Each organic hit is distilled to the three fields a model
+ * reasons over — title, destination URL, and a short snippet — and rendered as a
+ * compact numbered list. Provides up-to-date information for current events and
+ * recent data.
+ */
+import type { AgentTool } from "../types.js";
+declare const webSearchSchema: import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    numResults: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface WebSearchToolDetails {
+    query: string;
+    numResults?: number;
+}
+export interface WebSearchToolOptions {
+    /** Custom API base URL (for testing or alternative endpoints) */
+    baseUrl?: string;
+    /** API key for Exa AI (if required) */
+    apiKey?: string;
+    /** Max requests per process window */
+    rateLimitPerMinute?: number;
+    /** Optional result filtering hook */
+    filterResult?: (raw: string) => string;
+    /** Optional fallback implementation */
+    fallbackSearch?: (query: string, numResults?: number, signal?: AbortSignal) => Promise<string>;
+}
+export declare function createWebSearchTool(options?: WebSearchToolOptions): AgentTool<typeof webSearchSchema>;
+/** Default web search tool */
+export declare const webSearchTool: AgentTool<import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    numResults: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/websearch.test.d.ts

@@ -0,0 +1 @@
+export {};