@cuylabs/agent-core 4.9.0 → 4.10.0

package/dist/tool/executor.d.ts

@@ -0,0 +1,59 @@
+import type { ToolHost } from "./host/types.js";
+import type { HumanInputController } from "../human/controller.js";
+import type { MiddlewareRunner } from "../middleware/runner.js";
+import type { Tool } from "./tool.js";
+import type { ToolMetadata, ToolCapabilities, TurnTrackerContext } from "../types/tool.js";
+export interface ExecuteAgentToolCallOptions {
+    toolName: string;
+    tool: Tool.Info;
+    toolCallId?: string;
+    params: unknown;
+    cwd: string;
+    abort: AbortSignal;
+    sessionID: string;
+    turnID?: string;
+    messageID: string;
+    agent?: string;
+    host?: ToolHost;
+    humanInputController?: HumanInputController;
+    turnTracker?: TurnTrackerContext;
+    middleware?: MiddlewareRunner;
+    onEvent?: (event: import("../types/events.js").AgentEvent) => void | Promise<void>;
+    /**
+     * Pre-initialized tool result. When provided the executor skips
+     * `tool.init()` and uses this directly, avoiding double-init when
+     * the caller (e.g. `buildToolSet`) has already initialized the tool.
+     */
+    initialized?: Awaited<ReturnType<Tool.Info["init"]>>;
+}
+export interface ExecuteAgentToolCallResult {
+    output: string;
+    /** Short title for display (populated when middleware preserves it). */
+    title?: string;
+    /** Tool metadata (populated when middleware preserves it). */
+    metadata?: ToolMetadata;
+    /**
+     * Capabilities declared by the tool after initialization.
+     * Exposed so callers (e.g. tool-batch dispatch) can use them
+     * for parallelism and approval decisions without re-initializing.
+     */
+    capabilities?: ToolCapabilities;
+}
+/**
+ * Execute one initialized framework tool with the same semantics used by the
+ * standard AI SDK path.
+ *
+ * Execution pipeline (in order):
+ *  1. Init — resolve tool description, schema, capabilities
+ *  2. Schema validation — parse params against Zod schema (handled by Tool.define wrapper)
+ *  3. Input validation — tool-specific `validate()` check (fail-fast, no side effects)
+ *  4. Middleware pre-hook — `beforeToolCall` (approval, gating, arg rewriting)
+ *  5. Baseline capture — turn tracker snapshots files before writes
+ *  6. Execute — run the tool (with potentially rewritten args from step 4)
+ *  7. Middleware post-hook — `afterToolCall` (transform output, add supplements)
+ *
+ * This keeps middleware, baseline capture, and output normalization in one
+ * place so resumable runtimes do not need a second tool execution stack.
+ */
+export declare function executeAgentToolCall(options: ExecuteAgentToolCallOptions): Promise<ExecuteAgentToolCallResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/tool/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/tool/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAOhE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAEV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,OAAO,oBAAoB,EAAE,UAAU,KAC3C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAoKrC"}

package/dist/tool/host/index.d.ts

@@ -1,41 +1,10 @@
-import { T as ToolHost } from '../../types-C_LCeYNg.js';
-export { D as DirEntry, E as ExecOptions, a as ExecResult, F as FileStat } from '../../types-C_LCeYNg.js';
-
-interface ToolHostProviderSummary {
-    name: string;
-    description?: string;
-}
-interface ToolHostProvider<Options = unknown> extends ToolHostProviderSummary {
-    create(options?: Options): ToolHost | Promise<ToolHost>;
-}
-declare class ToolHostRegistry {
-    private readonly providers;
-    register<Options>(provider: ToolHostProvider<Options>): this;
-    unregister(name: string): boolean;
-    get(name: string): ToolHostProvider<unknown> | undefined;
-    list(): ToolHostProviderSummary[];
-    create(name: string, options?: unknown): Promise<ToolHost>;
-}
-
-/**
- * LocalHost — executes tools on the local machine.
- *
- * Default ToolHost implementation. Uses Node's `child_process.spawn`
- * for commands and `node:fs/promises` for file operations.
- */
-
-/**
- * Create a ToolHost that runs everything on the local machine.
- *
- * @param defaultCwd  Working directory for commands when none is specified.
- *                    Defaults to `process.cwd()`.
- */
-declare function localHost(defaultCwd?: string): ToolHost;
-
 /**
  * Tool host module — execution environment abstraction for tools.
  */
-
-declare const defaultToolHostRegistry: ToolHostRegistry;
-
-export { ToolHost, type ToolHostProvider, type ToolHostProviderSummary, ToolHostRegistry, defaultToolHostRegistry, localHost };
+export type { ToolHost, ExecOptions, ExecResult, FileStat, DirEntry, } from "./types.js";
+export type { ToolHostProvider, ToolHostProviderSummary } from "./registry.js";
+export { localHost } from "./local.js";
+export { ToolHostRegistry } from "./registry.js";
+import { ToolHostRegistry } from "./registry.js";
+export declare const defaultToolHostRegistry: ToolHostRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/tool/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tool/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,eAAO,MAAM,uBAAuB,kBAIlC,CAAC"}

package/dist/tool/host/local.d.ts

@@ -0,0 +1,15 @@
+/**
+ * LocalHost — executes tools on the local machine.
+ *
+ * Default ToolHost implementation. Uses Node's `child_process.spawn`
+ * for commands and `node:fs/promises` for file operations.
+ */
+import type { ToolHost } from "./types.js";
+/**
+ * Create a ToolHost that runs everything on the local machine.
+ *
+ * @param defaultCwd  Working directory for commands when none is specified.
+ *                    Defaults to `process.cwd()`.
+ */
+export declare function localHost(defaultCwd?: string): ToolHost;
+//# sourceMappingURL=local.d.ts.map

package/dist/tool/host/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/tool/host/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EACV,QAAQ,EAKT,MAAM,YAAY,CAAC;AAwCpB;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAyJvD"}

package/dist/tool/host/registry.d.ts

@@ -0,0 +1,17 @@
+import type { ToolHost } from "./types.js";
+export interface ToolHostProviderSummary {
+    name: string;
+    description?: string;
+}
+export interface ToolHostProvider<Options = unknown> extends ToolHostProviderSummary {
+    create(options?: Options): ToolHost | Promise<ToolHost>;
+}
+export declare class ToolHostRegistry {
+    private readonly providers;
+    register<Options>(provider: ToolHostProvider<Options>): this;
+    unregister(name: string): boolean;
+    get(name: string): ToolHostProvider<unknown> | undefined;
+    list(): ToolHostProviderSummary[];
+    create(name: string, options?: unknown): Promise<ToolHost>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tool/host/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/tool/host/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB,CAC/B,OAAO,GAAG,OAAO,CACjB,SAAQ,uBAAuB;IAC/B,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACzD;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgD;IAE1E,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,IAAI;IAK5D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,SAAS;IAIxD,IAAI,IAAI,uBAAuB,EAAE;IAO3B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;CAOjE"}

package/dist/{types-C_LCeYNg.d.ts → tool/host/types.d.ts}

@@ -20,7 +20,7 @@
  * ```
  */
 /** Options for spawning a process. */
-interface ExecOptions {
+export interface ExecOptions {
     /** Working directory for the command. */
     cwd?: string;
     /** Environment variables (merged with host defaults). */
@@ -35,7 +35,7 @@ interface ExecOptions {
     onStderr?: (data: Buffer) => void;
 }
 /** Result of a process execution. */
-interface ExecResult {
+export interface ExecResult {
     /** Combined stdout output. */
     stdout: string;
     /** Combined stderr output. */
@@ -46,7 +46,7 @@ interface ExecResult {
     timedOut: boolean;
 }
 /** Minimal stat result — only the fields tools actually need. */
-interface FileStat {
+export interface FileStat {
     /** File size in bytes. */
     size: number;
     /** Last modification time. */
@@ -57,7 +57,7 @@ interface FileStat {
     isFile: boolean;
 }
 /** A directory entry returned by `readdir`. */
-interface DirEntry {
+export interface DirEntry {
     /** Entry name (not full path). */
     name: string;
     /** Whether this entry is a directory. */
@@ -71,7 +71,7 @@ interface DirEntry {
  * Abstracts filesystem and process operations so tools work identically
  * whether running locally, in a container, over SSH, or in any other environment.
  */
-interface ToolHost {
+export interface ToolHost {
     /** Human-readable host identifier (e.g. "local", "container:workspace"). */
     readonly name: string;
     /** Read a file as a UTF-8 string. Throws if the file doesn't exist. */
@@ -96,5 +96,4 @@ interface ToolHost {
      */
     exec(command: string, options?: ExecOptions): Promise<ExecResult>;
 }
-
-export type { DirEntry as D, ExecOptions as E, FileStat as F, ToolHost as T, ExecResult as a };
+//# sourceMappingURL=types.d.ts.map

package/dist/tool/host/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tool/host/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,qCAAqC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,EAAE,IAAI,CAAC;IACZ,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAMtB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC,oEAAoE;IACpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzE,4EAA4E;IAC5E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD,4CAA4C;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEtC,qEAAqE;IACrE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE3C,mEAAmE;IACnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAMnC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE"}

package/dist/tool/index.d.ts

@@ -1,286 +1,22 @@
-import { dD as ToolReplayPolicy, F as FileOperationMeta, bW as NormalizedToolReplayPolicy, T as Tool, H as HumanInputController, a as TurnTrackerContext, b as MiddlewareRunner, A as AgentEvent, dB as ToolMetadata, dx as ToolCapabilities } from '../instance-Bg61WSyz.js';
-export { aG as CompatibleSchema, bw as InferSchemaOutput, bx as InputCheckResult, dY as getRequiredToolHost, e2 as resolveCapability } from '../instance-Bg61WSyz.js';
-import { T as ToolHost } from '../types-C_LCeYNg.js';
-export { D as DirEntry, E as ExecOptions, a as ExecResult, F as FileStat } from '../types-C_LCeYNg.js';
-export { ToolHostProvider, ToolHostProviderSummary, ToolHostRegistry, defaultToolHostRegistry, localHost } from './host/index.js';
-import 'ai';
-import '../types-RSCv7nQ4.js';
-import 'zod';
-import '../types-CQaXbRsS.js';
-import '../types-DMjoFKKv.js';
-import '@modelcontextprotocol/sdk/client/auth.js';
-import '@modelcontextprotocol/sdk/types.js';
-import '@ai-sdk/provider-utils';
-import '../sandbox/index.js';
-import '../llm-error-D93FNNLY.js';
-
 /**
- * Normalize a tool replay policy into explicit, infrastructure-agnostic
- * recovery semantics.
- *
- * The defaults are intentionally conservative:
- * - read-only tools default to `replay`
- * - mutating or unknown tools default to `manual`
- */
-declare function normalizeToolReplayPolicy(policy?: ToolReplayPolicy, fileOps?: FileOperationMeta): NormalizedToolReplayPolicy;
-
-/**
- * Tool registry for @cuylabs/agent-core
- *
- * Manages available tools, named groups, and resolution from specs.
- */
-
-/**
- * A tool spec that can be resolved to an array of tools.
- *
- * - `string`   — group name (`"read-only"`), single tool ID (`"bash"`),
- *                or comma-separated list (`"read,grep,glob"`).
- *                Prefix with `-` to exclude: `"all,-bash"`.
- * - `string[]` — array of tool IDs and/or group names.
- * - `Tool.AnyInfo[]` — pass-through (already resolved).
- * - `true`     — all registered tools.
- * - `false`    — no tools.
- */
-type ToolSpec = string | string[] | Tool.AnyInfo[] | boolean;
-/**
- * Tool registry — manages available tools and named groups.
- *
- * Tools are registered individually. Groups are named collections of tool IDs
- * that resolve against the registry at lookup time.
- *
- * @example
- * ```typescript
- * const reg = new ToolRegistry();
- * reg.registerAll([readTool, grepTool, bashTool]);
- * reg.registerGroup("read-only", ["read", "grep", "glob"]);
- *
- * // Resolve a spec to a tool array
- * reg.resolve("read-only");             // → [readTool, grepTool]
- * reg.resolve("all,-bash");             // → [readTool, grepTool]
- * reg.resolve(["read", "grep"]);        // → [readTool, grepTool]
- * reg.resolve(true);                    // → all tools
- * ```
- */
-declare class ToolRegistry {
-    private tools;
-    private groups;
-    /**
-     * Register a tool. Throws if a tool with the same ID is already registered.
-     * Use `set()` for upsert semantics.
-     */
-    register(tool: Tool.AnyInfo): void;
-    /** Register multiple tools (throws on duplicates). */
-    registerAll(tools: Tool.AnyInfo[]): void;
-    /** Register or replace a tool (upsert). */
-    set(tool: Tool.AnyInfo): void;
-    /** Unregister a tool by ID. Returns `true` if it existed. */
-    unregister(id: string): boolean;
-    /** Get a tool by ID. */
-    get(id: string): Tool.AnyInfo | undefined;
-    /** Check if a tool is registered. */
-    has(id: string): boolean;
-    /** Get all tool IDs. */
-    ids(): string[];
-    /** Get all tools. */
-    all(): Tool.AnyInfo[];
-    /** Clear all tools and groups. */
-    clear(): void;
-    /** Number of registered tools. */
-    get size(): number;
-    /**
-     * Register a named group of tool IDs.
-     * The group name can be used in `resolve()` specs.
-     * Tool IDs don't need to be registered yet — resolution is lazy.
-     */
-    registerGroup(name: string, toolIds: string[]): void;
-    /** Get tools in a group (only returns registered tools). */
-    getGroup(name: string): Tool.AnyInfo[] | undefined;
-    /** Check if a group is registered. */
-    hasGroup(name: string): boolean;
-    /** List all group names. */
-    listGroups(): string[];
-    /**
-     * Partition registered tools into eager and deferred sets.
-     *
-     * Eager tools have their full schemas sent to the LLM on turn 1.
-     * Deferred tools are held back — the model discovers them via a
-     * search mechanism when needed, saving context window space.
-     *
-     * @returns `{ eager, deferred }` arrays of tool infos.
-     */
-    partition(): {
-        eager: Tool.AnyInfo[];
-        deferred: Tool.AnyInfo[];
-    };
-    /**
-     * Search deferred tools by keyword with multi-signal weighted scoring.
-     *
-     * Scoring per term:
-     *  - Exact tool ID match: +10
-     *  - Partial tool ID match (substring): +5
-     *  - Keyword word-boundary match: +4
-     *  - Keyword substring match: +2
-     *
-     * @param query - Space-separated search terms
-     * @param maxResults - Maximum results to return (default: 5)
-     * @returns Matching deferred tools sorted by relevance (highest score first)
-     */
-    searchDeferred(query: string, maxResults?: number): Tool.AnyInfo[];
-    /**
-     * Resolve a `ToolSpec` to an array of tools.
-     *
-     * Supports group names, individual tool IDs, comma-separated strings,
-     * exclusions with `-` prefix, booleans, and pass-through arrays.
-     *
-     * @example
-     * ```typescript
-     * registry.resolve("read-only");          // group name
-     * registry.resolve("read,grep,glob");     // comma-separated IDs
-     * registry.resolve("all,-bash");          // all except bash
-     * registry.resolve(["read", "grep"]);     // array of IDs
-     * registry.resolve(true);                 // all registered tools
-     * registry.resolve(false);                // empty array
-     * ```
-     */
-    resolve(spec: ToolSpec): Tool.AnyInfo[];
-}
-/**
- * Default tool registry instance.
- * Shared across the application — register tools here for global access.
- *
- * **Single-process only.** In multi-agent or multi-tenant setups where
- * agents share a process, create a dedicated `new ToolRegistry()` per
- * agent to avoid cross-contamination of tool registrations.
- */
-declare const defaultRegistry: ToolRegistry;
-
-/**
- * Tool Search — lets the model discover deferred tools at runtime.
- *
- * When an agent has many tools, sending all schemas on turn 1 wastes
- * context window. Tools marked `deferred: true` are held back. The
- * model calls `tool_search` to find them by keyword, and the matching
- * schemas are added to subsequent turns.
- *
- * The search tool itself is always eager (never deferred).
- */
-
-/**
- * Options for creating a tool_search tool.
- */
-interface ToolSearchOptions {
-    /** Registry to search. Falls back to the default registry if not provided. */
-    registry: ToolRegistry;
-    /** Maximum results per search (default: 5). */
-    maxResults?: number;
-    /**
-     * Callback invoked with the matched tools after each search.
-     *
-     * The agent setup should use this to add the discovered tools
-     * to the active tool set for subsequent model calls.
-     */
-    onMatch: (tools: Tool.AnyInfo[]) => void;
-}
-/**
- * Create a `tool_search` tool that the model can call to discover
- * deferred tools by keyword.
- *
- * @example
- * ```typescript
- * import { createToolSearchTool, ToolRegistry } from "@cuylabs/agent-core";
- *
- * const registry = new ToolRegistry();
- * // ... register tools including deferred ones ...
- *
- * const activeTools = new Map<string, Tool.AnyInfo>();
- * const search = createToolSearchTool({
- *   registry,
- *   onMatch: (tools) => {
- *     for (const t of tools) activeTools.set(t.id, t);
- *   },
- * });
- * ```
- */
-declare function createToolSearchTool(options: ToolSearchOptions): Tool.Info;
-
-/**
- * Output truncation utilities for @cuylabs/agent-core
- */
-/** Maximum lines before truncation */
-declare const MAX_LINES = 2000;
-/** Maximum bytes before truncation */
-declare const MAX_BYTES = 100000;
-interface TruncateResult {
-    /** The (possibly truncated) content */
-    content: string;
-    /** Whether the content was truncated */
-    truncated: boolean;
-    /** Path to full output if truncated */
-    outputPath?: string;
-}
-/**
- * Truncate output if it exceeds limits.
- *
- * When truncation occurs the full output is written to a temp file
- * **synchronously** so the path is valid immediately.
- */
-declare function truncateOutput(output: string, options?: {
-    maxLines?: number;
-    maxBytes?: number;
-}): TruncateResult;
-
-interface ExecuteAgentToolCallOptions {
-    toolName: string;
-    tool: Tool.Info;
-    toolCallId?: string;
-    params: unknown;
-    cwd: string;
-    abort: AbortSignal;
-    sessionID: string;
-    turnID?: string;
-    messageID: string;
-    agent?: string;
-    host?: ToolHost;
-    humanInputController?: HumanInputController;
-    turnTracker?: TurnTrackerContext;
-    middleware?: MiddlewareRunner;
-    onEvent?: (event: AgentEvent) => void | Promise<void>;
-    /**
-     * Pre-initialized tool result. When provided the executor skips
-     * `tool.init()` and uses this directly, avoiding double-init when
-     * the caller (e.g. `buildToolSet`) has already initialized the tool.
-     */
-    initialized?: Awaited<ReturnType<Tool.Info["init"]>>;
-}
-interface ExecuteAgentToolCallResult {
-    output: string;
-    /** Short title for display (populated when middleware preserves it). */
-    title?: string;
-    /** Tool metadata (populated when middleware preserves it). */
-    metadata?: ToolMetadata;
-    /**
-     * Capabilities declared by the tool after initialization.
-     * Exposed so callers (e.g. tool-batch dispatch) can use them
-     * for parallelism and approval decisions without re-initializing.
-     */
-    capabilities?: ToolCapabilities;
-}
-/**
- * Execute one initialized framework tool with the same semantics used by the
- * standard AI SDK path.
- *
- * Execution pipeline (in order):
- *  1. Init — resolve tool description, schema, capabilities
- *  2. Schema validation — parse params against Zod schema (handled by Tool.define wrapper)
- *  3. Input validation — tool-specific `validate()` check (fail-fast, no side effects)
- *  4. Middleware pre-hook — `beforeToolCall` (approval, gating, arg rewriting)
- *  5. Baseline capture — turn tracker snapshots files before writes
- *  6. Execute — run the tool (with potentially rewritten args from step 4)
- *  7. Middleware post-hook — `afterToolCall` (transform output, add supplements)
- *
- * This keeps middleware, baseline capture, and output normalization in one
- * place so resumable runtimes do not need a second tool execution stack.
- */
-declare function executeAgentToolCall(options: ExecuteAgentToolCallOptions): Promise<ExecuteAgentToolCallResult>;
-
-export { type ExecuteAgentToolCallOptions, type ExecuteAgentToolCallResult, MAX_BYTES, MAX_LINES, Tool, ToolCapabilities, ToolHost, ToolRegistry, type ToolSearchOptions, type ToolSpec, type TruncateResult, createToolSearchTool, defaultRegistry, executeAgentToolCall, normalizeToolReplayPolicy, truncateOutput };
+ * Tool Module
+ *
+ * This is the focused surface for framework tools:
+ * - `Tool` defines the public tool contract
+ * - `ToolRegistry` manages lookup, composition, and deferred loading
+ * - replay helpers describe how resumable runtimes should treat side effects
+ * - truncation helpers keep large tool outputs safe for prompts
+ * - `executeAgentToolCall` centralizes validation, middleware, tracking, and output flow
+ * - tool hosts define where tool-side filesystem/process work runs
+ */
+export { Tool, type CompatibleSchema, type InferSchemaOutput } from "./tool.js";
+export type { AgentTurnToolContext, AgentTurnToolProvider, AgentTurnToolProviderResult, } from "./turn-tools.js";
+export { normalizeToolReplayPolicy } from "./replay.js";
+export { ToolRegistry, defaultRegistry, type ToolSpec } from "./registry.js";
+export { createToolSearchTool, type ToolSearchOptions } from "./tool-search.js";
+export { truncateOutput, MAX_LINES, MAX_BYTES, type TruncateResult, } from "./truncation.js";
+export { executeAgentToolCall, type ExecuteAgentToolCallOptions, type ExecuteAgentToolCallResult, } from "./executor.js";
+export * from "./host/index.js";
+export type { ToolCapabilities, InputCheckResult } from "../types/tool.js";
+export { resolveCapability, getRequiredToolHost } from "../types/tool.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,IAAI,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGhF,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG7E,OAAO,EAAE,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,SAAS,EACT,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,eAAe,CAAC;AAGvB,cAAc,iBAAiB,CAAC;AAGhC,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tool/index.js

@@ -2,7 +2,7 @@ import {
   ToolRegistry,
   createToolSearchTool,
   defaultRegistry
-} from "../chunk-KYLPMBHD.js";
+} from "../chunk-336EDIBL.js";
 import {
   ToolHostRegistry,
   defaultToolHostRegistry,
@@ -14,10 +14,11 @@ import {
   Tool,
   normalizeToolReplayPolicy,
   truncateOutput
-} from "../chunk-Q742PSH3.js";
+} from "../chunk-MJML3A2F.js";
 import {
   executeAgentToolCall
-} from "../chunk-MWPU2EVV.js";
+} from "../chunk-JUIL2NJC.js";
+import "../chunk-AHDCR7SX.js";
 import "../chunk-T33MQXUP.js";
 import {
   getRequiredToolHost,