@cuylabs/agent-core 4.9.0 → 4.10.0

package/dist/tool/registry.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Tool registry for @cuylabs/agent-core
+ *
+ * Manages available tools, named groups, and resolution from specs.
+ */
+import type { Tool } from "./tool.js";
+/**
+ * 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.
+ */
+export 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
+ * ```
+ */
+export 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.
+ */
+export declare const defaultRegistry: ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tool/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAWtC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC;AAMpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,MAAM,CAA+B;IAM7C;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,GAAG,IAAI;IAOlC,sDAAsD;IACtD,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI;IAMxC,2CAA2C;IAC3C,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,GAAG,IAAI;IAI7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,wBAAwB;IACxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,OAAO,GAAG,SAAS;IAIzC,qCAAqC;IACrC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,wBAAwB;IACxB,GAAG,IAAI,MAAM,EAAE;IAIf,qBAAqB;IACrB,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE;IAIrB,kCAAkC;IAClC,KAAK,IAAI,IAAI;IAKb,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAMD;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpD,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,SAAS;IAQlD,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,4BAA4B;IAC5B,UAAU,IAAI,MAAM,EAAE;IAQtB;;;;;;;;OAQG;IACH,SAAS,IAAI;QAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;KAAE;IAahE;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,IAAI,CAAC,OAAO,EAAE;IAkD7D;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE;CA0ExC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,cAAqB,CAAC"}

package/dist/tool/replay.d.ts

@@ -0,0 +1,11 @@
+import type { FileOperationMeta, NormalizedToolReplayPolicy, ToolReplayPolicy } from "../types/tool.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`
+ */
+export declare function normalizeToolReplayPolicy(policy?: ToolReplayPolicy, fileOps?: FileOperationMeta): NormalizedToolReplayPolicy;
+//# sourceMappingURL=replay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/tool/replay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,gBAAgB,EAGjB,MAAM,kBAAkB,CAAC;AAiC1B;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,CAAC,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,0BAA0B,CAY5B"}

package/dist/tool/tool-search.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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).
+ */
+import { Tool } from "./tool.js";
+import type { ToolRegistry } from "./registry.js";
+/**
+ * Options for creating a tool_search tool.
+ */
+export 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);
+ *   },
+ * });
+ * ```
+ */
+export declare function createToolSearchTool(options: ToolSearchOptions): Tool.Info;
+//# sourceMappingURL=tool-search.d.ts.map

package/dist/tool/tool-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-search.d.ts","sourceRoot":"","sources":["../../src/tool/tool-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,EAAE,YAAY,CAAC;IACvB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC,IAAI,CA6G1E"}

package/dist/tool/tool.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Tool definition namespace for @cuylabs/agent-core
+ *
+ * Provides consistent tool creation via Tool.define.
+ */
+import { z } from "zod";
+import type { ToolContext, ToolMetadata, FileOperationMeta, ToolCapabilities, ToolHostRequirements, InputCheckResult } from "../types/index.js";
+import type { ToolReplayPolicy } from "../types/index.js";
+/**
+ * A schema type compatible with both Zod 3 and Zod 4.
+ *
+ * Uses structural typing so that schemas from either Zod version satisfy
+ * the constraint. This avoids the problem where Zod 3's `ZodType` class
+ * and Zod 4's `ZodType` class have incompatible internal shapes, causing
+ * type errors when a library compiled against one version is consumed with
+ * the other.
+ *
+ * Both Zod 3 and Zod 4 (classic API) schemas have `parse()` and `_output`.
+ */
+export interface CompatibleSchema<T = any> {
+    /** Parse and validate input data. Present in both Zod 3 and Zod 4. */
+    parse(data: unknown): T;
+    /**
+     * Type-level output marker used by both Zod versions:
+     * - Zod 3: `readonly _output!: T` (definite assignment assertion)
+     * - Zod 4 classic: `get _output(): T` (getter)
+     */
+    readonly _output: T;
+}
+/**
+ * Infer the output type from a compatible schema.
+ * Equivalent to `z.infer<T>` but works with both Zod 3 and Zod 4 schemas.
+ */
+export type InferSchemaOutput<T extends CompatibleSchema> = T["_output"];
+/**
+ * Tool namespace - tool definition utilities
+ */
+export declare namespace Tool {
+    type ProviderOptionValue = null | string | number | boolean | ProviderOptionValue[] | {
+        [key: string]: ProviderOptionValue;
+    };
+    type ProviderOptions = Record<string, {
+        [key: string]: ProviderOptionValue;
+    }>;
+    /**
+     * Tool info interface - the shape of a defined tool
+     */
+    interface Info<TParams extends CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Unique tool identifier */
+        id: string;
+        /** Static capability hints for inventory and runtime routing. */
+        capabilitiesHint?: ToolCapabilities;
+        /** Recovery semantics for resume-capable runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+        /**
+         * When `true`, this tool's full schema is NOT sent to the LLM on the
+         * first turn. The model must discover it via a tool-search mechanism.
+         * Use for rarely-needed tools to save context window space.
+         */
+        deferred?: boolean;
+        /**
+         * Short keyword phrases (3-10 words) that help a tool-search mechanism
+         * find this tool when it is deferred. Include terms NOT already in the
+         * tool id (e.g. `["jupyter", "notebook cells"]` for a notebook editor).
+         */
+        searchKeywords?: string[];
+        /** Initialize the tool (can be async for dynamic descriptions) */
+        init: (ctx?: InitContext) => Promise<InitResult<TParams, TMeta>> | InitResult<TParams, TMeta>;
+    }
+    /**
+     * Any tool info - for use in arrays and collections where generic types vary
+     */
+    type AnyInfo = Info<any, any>;
+    /**
+     * Context passed during tool initialization
+     */
+    interface InitContext {
+        /** Working directory */
+        cwd?: string;
+        /** Agent name (if known) */
+        agent?: string;
+    }
+    /**
+     * Result of tool initialization
+     */
+    interface InitResult<TParams extends CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Tool description for the LLM */
+        description: string;
+        /** Zod schema for parameters */
+        parameters: TParams;
+        /** Execute the tool */
+        execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        /** Optional custom validation error formatter */
+        formatValidationError?: (error: z.ZodError) => string;
+        /**
+         * File operation metadata for automatic turn tracking.
+         * When set, the agent will automatically capture file baselines
+         * before tool execution for undo/diff capabilities.
+         *
+         * @example
+         * ```typescript
+         * // For a write tool
+         * fileOps: {
+         *   pathArgs: ['path'],
+         *   operationType: 'write'
+         * }
+         * ```
+         */
+        fileOps?: FileOperationMeta;
+        /** Optional replay metadata for resume-capable runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+        /**
+         * Runtime capability declarations.
+         *
+         * Tells the framework how this tool behaves so it can make informed
+         * decisions about parallelism, approval, truncation, and interruption.
+         *
+         * @example
+         * ```typescript
+         * capabilities: {
+         *   parallelSafe: true,
+         *   readOnly: true,
+         *   riskLevel: "safe",
+         * }
+         * ```
+         */
+        capabilities?: ToolCapabilities;
+        /**
+         * Describe whether the tool depends on the configured execution host.
+         *
+         * Use this for tools that call `ctx.host.*` so inventories and runtimes
+         * can distinguish host-backed tools from pure in-process tools.
+         */
+        hostRequirements?: ToolHostRequirements;
+        /**
+         * Validate tool input before any middleware hooks or approval checks run.
+         *
+         * Use this for structural/semantic checks that should fail fast
+         * (file exists, argument constraints, size limits). The executor
+         * calls this before `beforeToolCall` middleware so a bad input
+         * never triggers side effects or user prompts.
+         *
+         * @example
+         * ```typescript
+         * validate: async (params) => {
+         *   if (params.old_string === params.new_string) {
+         *     return { ok: false, reason: "No changes to apply" };
+         *   }
+         *   return { ok: true };
+         * }
+         * ```
+         */
+        validate?: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<InputCheckResult> | InputCheckResult;
+        /**
+         * Extract permission patterns from tool input for the approval system.
+         *
+         * When set, the approval handler uses these patterns instead of the
+         * generic heuristic in `extractApprovalPatterns`. This lets each tool
+         * control how its inputs map to glob-matchable strings.
+         *
+         * @example
+         * ```typescript
+         * // bash: match the first word of the command
+         * permissionPatterns: (input) => {
+         *   const cmd = input.command.split(/\s+/)[0];
+         *   return [cmd];
+         * },
+         *
+         * // edit: match the file path
+         * permissionPatterns: (input) => [input.path],
+         * ```
+         */
+        permissionPatterns?: (params: InferSchemaOutput<TParams>) => string[];
+        /**
+         * Enable strict tool calling when supported by the provider.
+         *
+         * When `true`, providers like OpenAI enforce JSON schema conformance
+         * on the generated tool call arguments — the model is guaranteed to
+         * produce valid inputs. Not all schemas are supported in strict mode;
+         * unsupported schemas are silently downgraded by the provider.
+         *
+         * @default false
+         */
+        strict?: boolean;
+        /**
+         * Example inputs that help guide the model on how to call this tool.
+         *
+         * Passed directly to the AI SDK's `tool({ inputExamples })`.
+         * Currently only Anthropic uses these natively; other providers
+         * ignore the setting.
+         *
+         * @example
+         * ```typescript
+         * inputExamples: [
+         *   { input: { location: "San Francisco" } },
+         *   { input: { location: "London" } },
+         * ]
+         * ```
+         */
+        inputExamples?: Array<{
+            input: InferSchemaOutput<TParams>;
+        }>;
+        /**
+         * Human-readable title for the tool, surfaced in AI SDK metadata and UIs.
+         *
+         * Forwarded to the AI SDK's `tool({ title })`. This is runtime/UI
+         * metadata; provider tool-definition payloads still use the tool id
+         * plus description/schema for model-facing selection.
+         */
+        title?: string;
+        /**
+         * Provider-specific tool metadata forwarded to the AI SDK.
+         *
+         * Use this for provider features that attach to one tool definition
+         * rather than to the whole model call.
+         */
+        providerOptions?: ProviderOptions;
+        /**
+         * Custom function that controls how this tool's output is presented
+         * to the model. Use this to wrap or annotate the tool result that
+         * flows through the AI SDK with structured multi-part content.
+         *
+         * Forwarded to the AI SDK's `tool({ toModelOutput })`.
+         *
+         * Note: framework tools still return `ExecuteResult.output` as text at
+         * the execution boundary. This hook customizes the AI SDK-facing
+         * representation of that result; it does not currently widen the
+         * framework's own stored tool-result contract.
+         *
+         * The return value must conform to the AI SDK's `ToolResultOutput`
+         * type. Import it from `"ai"` for full type safety, or use the
+         * simplified union below.
+         *
+         * @example
+         * ```typescript
+         * toModelOutput: ({ output }) => ({
+         *   type: "json" as const,
+         *   value: output,
+         * })
+         * ```
+         */
+        toModelOutput?: (options: {
+            toolCallId: string;
+            input: InferSchemaOutput<TParams>;
+            output: unknown;
+        }) => unknown | Promise<unknown>;
+    }
+    /**
+     * Result of tool execution.
+     *
+     * `metadata` is optional — omit it when the tool has nothing extra to
+     * report.  The framework defaults it to `{}` at the execution boundary
+     * so downstream middleware and consumers always see a defined object.
+     */
+    interface ExecuteResult<TMeta extends ToolMetadata = ToolMetadata> {
+        /** Short title for display */
+        title: string;
+        /** Main output text */
+        output: string;
+        /**
+         * Arbitrary key/value bag surfaced in events and middleware.
+         * Defaults to `{}` when omitted.
+         */
+        metadata?: TMeta;
+    }
+    interface DefineOptions {
+        /** Static replay metadata exposed to higher-level runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+        /**
+         * When `true`, this tool's schema is not sent to the LLM initially.
+         * The model must discover it via tool-search. Saves context window
+         * space when you have many tools but only a few are used per turn.
+         */
+        deferred?: boolean;
+        /**
+         * Keywords that help the tool-search mechanism find this tool.
+         * Only meaningful when `deferred` is `true`.
+         */
+        searchKeywords?: string[];
+        /**
+         * Static capability hints exposed without calling `init()`.
+         *
+         * Use this when a runtime needs to route tools by capability before
+         * running initialization, for example durable human-input detection.
+         */
+        capabilitiesHint?: ToolCapabilities;
+    }
+    /**
+     * Define a tool with standard patterns
+     *
+     * @example
+     * ```typescript
+     * const myTool = Tool.define("my_tool", {
+     *   description: "Does something useful",
+     *   parameters: z.object({
+     *     input: z.string().describe("The input to process"),
+     *   }),
+     *   execute: async (params, ctx) => ({
+     *     title: "Processed",
+     *     output: `Result: ${params.input}`,
+     *     metadata: {},
+     *   }),
+     * });
+     * ```
+     */
+    function define<TParams extends CompatibleSchema, TMeta extends ToolMetadata = ToolMetadata>(id: string, init: Info<TParams, TMeta>["init"] | Awaited<ReturnType<Info<TParams, TMeta>["init"]>>, options?: DefineOptions): Info<TParams, TMeta>;
+}
+//# sourceMappingURL=tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tool/tool.ts"],"names":[],"mappings":"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"}

package/dist/tool/truncation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Output truncation utilities for @cuylabs/agent-core
+ */
+/** Maximum lines before truncation */
+export declare const MAX_LINES = 2000;
+/** Maximum bytes before truncation */
+export declare const MAX_BYTES = 100000;
+/** Directory for storing truncated outputs */
+export declare const TRUNCATE_DIR: string;
+/** Glob pattern for truncation directory */
+export declare const TRUNCATE_GLOB: string;
+export 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.
+ */
+export declare function truncateOutput(output: string, options?: {
+    maxLines?: number;
+    maxBytes?: number;
+}): TruncateResult;
+/**
+ * Format file size for display
+ */
+export declare function formatSize(bytes: number): string;
+//# sourceMappingURL=truncation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../../src/tool/truncation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,sCAAsC;AACtC,eAAO,MAAM,SAAS,OAAO,CAAC;AAE9B,sCAAsC;AACtC,eAAO,MAAM,SAAS,SAAU,CAAC;AAEjC,8CAA8C;AAC9C,eAAO,MAAM,YAAY,QAAkD,CAAC;AAE5E,4CAA4C;AAC5C,eAAO,MAAM,aAAa,QAA+B,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,GACL,cAAc,CA2DhB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD"}

package/dist/tool/turn-tools.d.ts

@@ -0,0 +1,71 @@
+import type { ToolSet } from "ai";
+import type { Tool } from "./tool.js";
+/**
+ * Context provided to turn-scoped tool providers.
+ *
+ * This is intentionally platform-neutral. Channel packages can expose richer
+ * ambient context through their own AsyncLocalStorage helpers while the core
+ * package stays independent of Teams, Slack, M365, or Agent365 SDK types.
+ *
+ * Providers that need platform state such as a Microsoft `TurnContext`,
+ * authorization object, Slack client, tenant metadata, or request-scoped
+ * tokens should read that state from their channel package's ambient context at
+ * `resolveTools()` time. Do not close over per-request platform objects when
+ * constructing a provider, because providers may be inherited by forked agents.
+ */
+export interface AgentTurnToolContext {
+    sessionId: string;
+    turnId: string;
+    /**
+     * Current user message. Use this only for local tool selection/gating. Avoid
+     * forwarding it to external services unless the provider explicitly owns that
+     * data flow.
+     */
+    message: string;
+    cwd: string;
+    /**
+     * Providers should observe this signal when doing network or token-exchange
+     * work. Agent-core passes the signal through but does not forcibly cancel
+     * provider code.
+     */
+    abort: AbortSignal;
+}
+export interface AgentTurnToolProviderResult {
+    /**
+     * Framework tools available only for the active turn.
+     */
+    tools?: Tool.AnyInfo[];
+    /**
+     * AI SDK-compatible MCP tools available only for the active turn.
+     */
+    mcpTools?: ToolSet;
+    /**
+     * Called after the turn completes or errors.
+     *
+     * Use this to close per-turn MCP clients, revoke short-lived resources, or
+     * clean up temporary transport state. Cleanup callbacks run in reverse
+     * provider resolution order, matching stack semantics. If provider B depends
+     * on resources from provider A, register B after A so B is cleaned up first.
+     */
+    cleanup?: () => void | Promise<void>;
+}
+export interface AgentTurnToolProvider {
+    name: string;
+    /**
+     * Resolve tools for the active chat turn only.
+     *
+     * Returned tools are not added to the agent's global tool registry and are
+     * cleaned up after the turn completes or fails.
+     *
+     * Resolution happens before chat lifecycle middleware starts. If resolution
+     * fails, agent-core emits structured `status: "error"` and `error` events,
+     * then rejects the turn; chat lifecycle middleware is not called for that
+     * failed resolution. Subscribe to `AgentEvent`s for full failure coverage.
+     *
+     * `resolveTools()` may be called concurrently for different sessions. Provider
+     * implementations must be reentrant or key mutable state by `sessionId` and
+     * `turnId`.
+     */
+    resolveTools(context: AgentTurnToolContext): AgentTurnToolProviderResult | Promise<AgentTurnToolProviderResult>;
+}
+//# sourceMappingURL=turn-tools.d.ts.map

package/dist/tool/turn-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-tools.d.ts","sourceRoot":"","sources":["../../src/tool/turn-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;OAcG;IACH,YAAY,CACV,OAAO,EAAE,oBAAoB,GAC5B,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACvE"}

package/dist/tracking/file-tracking.d.ts

@@ -0,0 +1,25 @@
+import type { FileOperationMeta } from "../types/tool.js";
+import type { TurnChangeTracker } from "./turn-tracker/index.js";
+export type { FileOperationMeta };
+/**
+ * Extended tool metadata with file operation info.
+ */
+export interface TrackedToolMetadata {
+    /** File operation metadata for auto-tracking */
+    fileOps?: FileOperationMeta;
+    /** Other metadata */
+    [key: string]: unknown;
+}
+/**
+ * Extract file paths from tool arguments based on metadata.
+ */
+export declare function extractFilePathsFromArgs(args: Record<string, unknown>, meta: FileOperationMeta): string[];
+/**
+ * Check whether a tool operation should trigger baseline capture.
+ */
+export declare function shouldCaptureBaseline(meta: FileOperationMeta): boolean;
+/**
+ * Wrap a tool execute function with automatic file tracking.
+ */
+export declare function withFileTracking<T extends (...args: unknown[]) => Promise<unknown>>(tracker: TurnChangeTracker, meta: FileOperationMeta, execute: T): T;
+//# sourceMappingURL=file-tracking.d.ts.map

package/dist/tracking/file-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-tracking.d.ts","sourceRoot":"","sources":["../../src/tracking/file-tracking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,qBAAqB;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,iBAAiB,GACtB,MAAM,EAAE,CAoBV;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAClD,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAapE"}