indusagi 0.12.34 → 0.13.0

package/dist/types/capabilities/kernel/spec.d.ts

@@ -40,12 +40,63 @@ export interface ToolResult {
     readonly content: ToolContentBlock[];
     readonly isError?: boolean;
 }
+/**
+ * The per-session record a {@link ReadStateHandle} keeps for one file.
+ *
+ * It captures just enough to detect that a file has drifted on disk since it was
+ * last read: the floored modification time and byte size at read time, an
+ * optional content hash for a future exact-match fallback, and the wall-clock
+ * moment the read happened. The handle keys these by absolute path.
+ */
+export interface ReadStateRecord {
+    /** Last-modified time at read, epoch milliseconds (floored). */
+    readonly mtimeMs: number;
+    /** Byte size at read time. */
+    readonly size: number;
+    /** Optional content hash for an exact-equality fallback; absent today. */
+    readonly contentHash?: string;
+    /** Wall-clock moment the read was recorded, epoch milliseconds. */
+    readonly readAt: number;
+}
+/**
+ * The minimal, duck-typed handle a host may stash on {@link ToolContext.framework}
+ * under {@link READ_STATE_HANDLE_KEY} to enable the read-before-edit gate.
+ *
+ * Deliberately tiny — `get` / `set` / `has` keyed by absolute path — so the
+ * framework consumer and the product injector can agree on the *shape* without a
+ * cross-package type import. The product supplies a concrete store; the framework
+ * only ever reads/writes through these three methods.
+ */
+export interface ReadStateHandle {
+    /** The recorded state for a path, or undefined if it was never read. */
+    get(absPath: string): ReadStateRecord | undefined;
+    /** Record (or refresh) the state for a path. */
+    set(absPath: string, record: ReadStateRecord): void;
+    /** Whether a path has any recorded read state this session. */
+    has(absPath: string): boolean;
+}
+/**
+ * The string-literal key under which a {@link ReadStateHandle} lives on
+ * {@link ToolContext.framework}.
+ *
+ * Mirrors the existing `DELEGATE_HANDLE_KEY = "delegate"` /
+ * `MEMORY_HANDLE_KEY = "memoryStore"` convention: a shared literal both the
+ * framework consumer and the product injector reference so they agree without a
+ * cross-package type import.
+ */
+export declare const READ_STATE_HANDLE_KEY: "readState";
 /**
  * Everything a tool's `run` is handed besides its own parsed input.
  *
  * It carries the working directory, the two coarse I/O backends, a cancellation
  * `signal`, and the default {@link OutputBudget} a tool should apply when its
  * output risks overflowing the model's window.
+ *
+ * `framework` is an open bag of optional host-injected handles, keyed by string
+ * literals (e.g. {@link READ_STATE_HANDLE_KEY}). It is the additive seam through
+ * which a host can opt a session into behaviors like the read-before-edit gate
+ * without changing any tool signature; when a handle is absent the tools behave
+ * exactly as they did before.
  */
 export interface ToolContext {
     readonly cwd: string;
@@ -53,6 +104,10 @@ export interface ToolContext {
     readonly shell: Shell;
     readonly signal: AbortSignal;
     readonly budget: OutputBudget;
+    /** Open record of optional, host-injected framework handles. */
+    readonly framework?: {
+        readonly [key: string]: unknown;
+    };
 }
 /**
  * The declarative description of one tool.

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

@@ -1,5 +1,6 @@
 import type { AgentTool } from "../types.js";
 import type { HookRunner } from "./kit/hook-runner.js";
+import { type SandboxConfig } from "./sandbox-backend.js";
 import { type TruncationResult } from "./truncate.js";
 export interface BashSecurityConfig {
     /** Patterns that, when matched, stop a command from running. */
@@ -44,8 +45,22 @@ export interface BashToolOptions {
     hookRunner?: HookRunner;
     /** Settings that decide which commands are allowed to run. */
     security?: BashSecurityConfig;
+    /**
+     * OPT-IN OS sandbox. OFF by default: when omitted or `enabled` is false the
+     * bash tool spawns exactly as before. When enabled, each command is wrapped
+     * in the platform's OS sandbox (macOS `sandbox-exec`, Linux `bwrap`); if no
+     * sandbox tool is available the command runs un-sandboxed and a note is
+     * recorded via `onSandboxNote` rather than silently claiming sandboxing.
+     */
+    sandbox?: SandboxConfig;
+    /** Receives an honest note describing whether the sandbox was applied or skipped. */
+    onSandboxNote?: (note: string) => void;
     /** Optional log that collects the commands as they are issued. */
     commandHistory?: string[];
+    /** Time budget, in seconds, applied when the model omits `timeout`. Defaults to 120s. */
+    defaultTimeoutSeconds?: number;
+    /** Hard ceiling, in seconds, that any supplied `timeout` is clamped to. Defaults to 600s (and is never lower than the default). */
+    maxTimeoutSeconds?: number;
 }
 export declare function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema>;
 /** Ready-made bash tool bound to the process working directory. */

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * File-checkpoint hook for the WIRED facade tool layer.
+ *
+ * This is the framework half of the rewind feature. The product (the coding
+ * agent) constructs a `CheckpointStore`, exposes a small duck-typed
+ * {@link CheckpointHandle} on the shared `ctx.framework` bag under the literal
+ * key `'checkpoint'`, and passes it into the `write` / `edit` factories — the
+ * same place the read-before-edit gate's `readState` handle is wired. When a
+ * handle is present, every mutating file tool captures the file's pre-mutation
+ * on-disk content EXACTLY ONCE per mutated path, so a later rewind can roll the
+ * working tree back to that snapshot.
+ *
+ * Like the read-edit gate, 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.
+ */
+/**
+ * Duck-typed sink the host injects to receive pre-mutation snapshots.
+ *
+ * `record` is called once per mutated path, before the write lands, with the
+ * file's OLD on-disk content — or `null` when the file did not exist on disk
+ * before this mutation (so a rewind that visits this snapshot knows to DELETE
+ * the file rather than restore stale bytes).
+ */
+export interface CheckpointHandle {
+    /**
+     * Capture the pre-mutation state of `absPath`.
+     *
+     * @param absPath  Absolute path of the file about to be written.
+     * @param previous The file's content before this mutation, or `null` if the
+     *                 file did not exist on disk beforehand.
+     */
+    record(absPath: string, previous: string | null): void;
+}
+/**
+ * Read the CURRENT on-disk content of `absPath` and hand it to the checkpoint
+ * handle, capturing the PRE-mutation state.
+ *
+ * This MUST be invoked synchronously-ordered immediately before the write so the
+ * captured snapshot is the OLD content (no read/write race). When the file does
+ * not exist on disk, `null` is recorded so a rewind knows to delete it.
+ *
+ * No-op when no handle is present. A read/stat failure that is NOT a plain
+ * "missing file" is swallowed: checkpointing is best-effort and must never mask
+ * the real operation's outcome. (A genuine ENOENT is reported as `null`, the
+ * meaningful "file absent" snapshot.)
+ */
+export declare function recordCheckpoint(handle: CheckpointHandle | undefined, absPath: string): void;

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

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

package/dist/types/facade/bot/actions/edit-utils.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Precision helpers for the edit tool. None of these change the default
+ * behaviour of an edit — they kick in only on the recovery / preservation
+ * paths:
+ *
+ *  - {@link preserveQuoteStyle} re-applies a file's curly-quote typography to
+ *    replacement text when the match was found only after folding curly quotes
+ *    to straight ones, so an edit doesn't quietly downgrade `"` → `“`.
+ *  - {@link desanitizeMatchString} repairs the handful of tag tokens an API
+ *    transport may mangle (`<o>` → `<output>`, `\n\nH:` → `\n\nHuman:`, …) so a
+ *    snippet that lost its angle-bracket words can still be located. It is only
+ *    ever used as a *fallback* (try the literal text first) because several of
+ *    the rules collide with ordinary code.
+ *  - {@link findSimilarFile} and {@link suggestPathUnderCwd} build the "did you
+ *    mean …?" hint when a path doesn't resolve.
+ *  - {@link replaceAllLiteral} swaps every non-overlapping literal occurrence of
+ *    a needle, used for the `replaceAll` edit mode.
+ *
+ * Everything here is pure / node-fs only and carries no dependency on the rest
+ * of the edit pipeline.
+ */
+export declare const LEFT_SINGLE_CURLY_QUOTE = "\u2018";
+export declare const RIGHT_SINGLE_CURLY_QUOTE = "\u2019";
+export declare const LEFT_DOUBLE_CURLY_QUOTE = "\u201C";
+export declare const RIGHT_DOUBLE_CURLY_QUOTE = "\u201D";
+/**
+ * When `oldText` only matched the file after curly quotes were folded to
+ * straight quotes, re-apply the file's curly typography to `newString` so the
+ * edit preserves the original quote style. A no-op when `oldString` already
+ * equals the matched text (no folding happened) or when the matched text holds
+ * no curly quotes.
+ *
+ * @param oldString The text the model supplied (straight quotes).
+ * @param actualOldString The text actually located in the file (may be curly).
+ * @param newString The replacement text the model supplied (straight quotes).
+ */
+export declare function preserveQuoteStyle(oldString: string, actualOldString: string, newString: string): string;
+/**
+ * Tag tokens an API transport sometimes mangles, mapped back to their full
+ * form. Several of these (`<n>`, `\n\nH:`) appear in ordinary source, so the
+ * table must only ever be consulted as a *fallback* after a literal match
+ * misses — never preemptively.
+ */
+export declare const DESANITIZATIONS: Record<string, string>;
+/**
+ * Expand any mangled tag tokens in `matchString`, reporting which replacements
+ * fired so the caller can mirror them onto the replacement text.
+ */
+export declare function desanitizeMatchString(matchString: string): {
+    result: string;
+    appliedReplacements: Array<{
+        from: string;
+        to: string;
+    }>;
+};
+/**
+ * Look in `filePath`'s directory for a file that shares its base name but has a
+ * different extension (e.g. `foo.ts` when `foo.js` was requested). Returns the
+ * sibling's bare filename, or `undefined` when there is no such neighbour.
+ */
+export declare function findSimilarFile(filePath: string): string | undefined;
+/**
+ * Marker embedded in file-not-found messages that carry a cwd note. A UI
+ * renderer can key off this to collapse the long message into a short
+ * "File not found" badge.
+ */
+export declare const FILE_NOT_FOUND_CWD_NOTE = "Note: your current working directory is";
+/**
+ * Suggest a corrected path under `cwd` when an absolute path doesn't resolve.
+ * Catches the "dropped repo folder" pattern: the model builds an absolute path
+ * that sits beside the repo rather than inside it.
+ *
+ *   cwd           = /Users/x/src/currentRepo
+ *   requestedPath = /Users/x/src/foobar           (missing)
+ *   returns         /Users/x/src/currentRepo/foobar (when it exists)
+ *
+ * @param requestedPath The absolute path that was not found.
+ * @param cwd The working directory to re-root the suggestion under.
+ */
+export declare function suggestPathUnderCwd(requestedPath: string, cwd: string): Promise<string | undefined>;
+/**
+ * Replace every non-overlapping literal occurrence of `needle` in `haystack`
+ * with `value`. Ported verbatim from the kernel `edit` capability so the
+ * `replaceAll` edit mode shares one definition of "replace all".
+ */
+export declare function replaceAllLiteral(haystack: string, needle: string, value: string): string;

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

@@ -1,5 +1,7 @@
 import type { AgentTool } from "../types.js";
 import { fuzzyFindText } from "./edit-diff.js";
+import { type CheckpointHandle } from "./checkpoint.js";
+import { type ReadStateHandle } from "./read-state.js";
 export interface MatchingStrategy {
     find(content: string, oldText: string): ReturnType<typeof fuzzyFindText>;
 }
@@ -7,6 +9,7 @@ declare const editSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     oldText: import("@sinclair/typebox").TString;
     newText: import("@sinclair/typebox").TString;
+    replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
 export interface EditToolDetails {
     /** Formatted diff showing what changed. */
@@ -30,6 +33,20 @@ export interface EditToolOptions {
     /** Swap out the filesystem callbacks; the local disk is used by default. */
     operations?: EditOperations;
     matchingStrategy?: MatchingStrategy;
+    /**
+     * Optional read-before-edit gate store. When present, the edit is refused
+     * unless the file was read this session and has not drifted on disk since.
+     * Absent → no gate (no-op), preserving the prior behaviour exactly.
+     */
+    readState?: ReadStateHandle;
+    /**
+     * Optional file-checkpoint sink. When present, the file's ORIGINAL
+     * pre-edit on-disk content is captured exactly once before the edit is
+     * applied, so a later rewind can roll the working tree back. The edit tool
+     * only ever targets an existing file, so the snapshot is its old bytes (never
+     * `null`). Absent → no snapshot (no-op).
+     */
+    checkpoint?: CheckpointHandle;
 }
 export declare function createEditTool(cwd: string, options?: EditToolOptions): AgentTool<typeof editSchema>;
 /** Ready-to-use edit tool bound to the current working directory. */
@@ -37,5 +54,6 @@ export declare const editTool: AgentTool<import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     oldText: import("@sinclair/typebox").TString;
     newText: import("@sinclair/typebox").TString;
+    replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>, any>;
 export {};

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

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

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

@@ -3,6 +3,7 @@ import { type TruncationResult } from "./truncate.js";
 declare const findSchema: import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>;
 export interface FindToolDetails {
@@ -20,6 +21,7 @@ export declare function createFindTool(cwd: string, options?: FindToolOptions):
 export declare const findTool: AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any>;
 export {};

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

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

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

@@ -6,6 +6,11 @@ declare const grepSchema: import("@sinclair/typebox").TObject<{
     ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+    glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>;
 export interface GrepToolDetails {
@@ -38,6 +43,11 @@ export declare const grepTool: AgentTool<import("@sinclair/typebox").TObject<{
     ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+    glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any>;
 export {};

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

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

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

@@ -3,6 +3,7 @@ export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, truncat
 export { expandPath, resolveReadPath, resolveToCwd } from "./path-utils.js";
 export { createReadTool, readTool, type ReadOperations, type ReadToolOptions, type ReadToolDetails, } from "./read.js";
 export { createBashTool, bashTool, type BashOperations, type BashToolOptions, type BashToolDetails, } from "./bash.js";
+export { buildSeatbeltProfile, buildSeatbeltArgv, buildBwrapArgv, buildSandboxArgv, argvToCommandString, sandboxAvailability, createSandboxedBashOperations, type SandboxConfig, type SandboxAvailability, type SandboxedOperationsOptions, } from "./sandbox-backend.js";
 export { createEditTool, editTool, type EditOperations, type EditToolOptions, type EditToolDetails, } from "./edit.js";
 export { createWriteTool, writeTool, type WriteOperations, type WriteToolOptions, } from "./write.js";
 export { createGrepTool, grepTool, type GrepOperations, type GrepToolOptions, type GrepToolDetails, } from "./grep.js";
@@ -15,6 +16,7 @@ export { createWebSearchTool, webSearchTool, type WebSearchToolOptions, type Web
 export { createWebFetchTool, webFetchTool, type WebFetchToolOptions, type WebFetchToolDetails, } from "./webfetch.js";
 export * from "./composio/index.js";
 export { computeEditDiff, generateDiffString } from "./edit-diff.js";
+export { DESANITIZATIONS, desanitizeMatchString, FILE_NOT_FOUND_CWD_NOTE, findSimilarFile, preserveQuoteStyle, replaceAllLiteral, suggestPathUnderCwd, } from "./edit-utils.js";
 export { ToolFactory, ToolRegistry, type ToolMetadata, type ToolCategory } from "./registry.js";
 export * from "./crew/index.js";
 export declare const TOOL_METADATA: Record<string, ToolMetadata>;
@@ -26,6 +28,7 @@ export declare const codingTools: (import("../types.js").AgentTool<import("@sinc
     path: import("@sinclair/typebox").TString;
     oldText: import("@sinclair/typebox").TString;
     newText: import("@sinclair/typebox").TString;
+    replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>, any> | import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
@@ -101,6 +104,7 @@ export declare const codingTools: (import("../types.js").AgentTool<import("@sinc
 export declare const readOnlyTools: (import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any> | import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
@@ -108,6 +112,11 @@ export declare const readOnlyTools: (import("../types.js").AgentTool<import("@si
     ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+    glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any> | import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -162,6 +171,7 @@ export declare const allTools: {
         path: import("@sinclair/typebox").TString;
         oldText: import("@sinclair/typebox").TString;
         newText: import("@sinclair/typebox").TString;
+        replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     }>, any>;
     readonly write: import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TString;
@@ -173,11 +183,17 @@ export declare const allTools: {
         ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+        glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     }>, any>;
     readonly find: import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
         pattern: import("@sinclair/typebox").TString;
         path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     }>, any>;
     readonly ls: import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{

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

@@ -1,4 +1,5 @@
 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;
@@ -25,6 +26,12 @@ export interface ReadToolOptions {
     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. */

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

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

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/websearch.d.ts

@@ -1,8 +1,11 @@
 /**
  * Web Search Tool
  *
- * Performs real-time web searches using DuckDuckGo API.
- * Provides up-to-date information for current events and recent data.
+ * 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<{

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

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