@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/dist/types/tools/search/types.d.ts

@@ -2,8 +2,8 @@ import type { Logger as WinstonLogger } from 'winston';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
-export type SearchProvider = 'serper' | 'searxng';
-export type ScraperProvider = 'firecrawl' | 'serper';
+export type SearchProvider = 'serper' | 'searxng' | 'tavily';
+export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 export interface Highlight {
     score: number;
@@ -56,11 +56,50 @@ export interface Source {
     snippet?: string;
     date?: string;
 }
+export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
+export type TavilyTimeRangeInput = TavilyTimeRange | 'h' | 'd' | 'w' | 'm' | 'y';
+export interface TavilySearchOptions {
+    searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
+    maxResults?: number;
+    includeImages?: boolean;
+    includeAnswer?: boolean | 'basic' | 'advanced';
+    includeRawContent?: boolean | 'markdown' | 'text';
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    topic?: 'general' | 'news' | 'finance';
+    timeRange?: TavilyTimeRangeInput;
+    includeImageDescriptions?: boolean;
+    includeFavicon?: boolean;
+    chunksPerSource?: number;
+    safeSearch?: boolean;
+    timeout?: number;
+}
+export interface TavilySearchPayload {
+    query: string;
+    search_depth: NonNullable<TavilySearchOptions['searchDepth']>;
+    topic: NonNullable<TavilySearchOptions['topic']>;
+    max_results: number;
+    safe_search?: boolean;
+    time_range?: TavilyTimeRange;
+    country?: string;
+    include_images?: boolean;
+    include_answer?: NonNullable<TavilySearchOptions['includeAnswer']>;
+    include_raw_content?: NonNullable<TavilySearchOptions['includeRawContent']>;
+    include_domains?: string[];
+    exclude_domains?: string[];
+    include_image_descriptions?: boolean;
+    include_favicon?: boolean;
+    chunks_per_source?: number;
+}
 export interface SearchConfig {
     searchProvider?: SearchProvider;
     serperApiKey?: string;
     searxngInstanceUrl?: string;
     searxngApiKey?: string;
+    tavilyApiKey?: string;
+    tavilySearchUrl?: string;
+    tavilyExtractUrl?: string;
+    tavilySearchOptions?: TavilySearchOptions;
     /** Domains to exclude from search results (e.g., 'reddit.com', 'twitter.com').
      *  Appended as -site: operators to the search query. */
     domainBlocklist?: string[];
@@ -101,6 +140,16 @@ export interface SerperScraperConfig {
     logger?: Logger;
     includeMarkdown?: boolean;
 }
+export interface TavilyScraperConfig {
+    apiKey?: string;
+    apiUrl?: string;
+    timeout?: number;
+    logger?: Logger;
+    extractDepth?: 'basic' | 'advanced';
+    includeImages?: boolean;
+    includeFavicon?: boolean;
+    format?: 'markdown' | 'text';
+}
 export interface ScraperContentResult {
     content: string;
 }
@@ -141,6 +190,7 @@ export interface CohereRerankerResponse {
 export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
+    tavilyScraperOptions?: TavilyScraperConfig;
     logger?: Logger;
     safeSearch?: SafeSearchLevel;
     jinaApiKey?: string;
@@ -163,15 +213,27 @@ export type UsedReferences = {
     originalIndex: number;
     reference: MediaReference;
 }[];
+export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse;
 /** Base Scraper Interface */
 export interface BaseScraper {
-    scrapeUrl(url: string, options?: unknown): Promise<[string, FirecrawlScrapeResponse | SerperScrapeResponse]>;
-    extractContent(response: FirecrawlScrapeResponse | SerperScrapeResponse): [string, undefined | References];
-    extractMetadata(response: FirecrawlScrapeResponse | SerperScrapeResponse): ScrapeMetadata | Record<string, string | number | boolean | null | undefined>;
+    scrapeUrl(url: string, options?: unknown): Promise<[string, AnyScraperResponse]>;
+    scrapeUrls?(urls: string[], options?: unknown): Promise<Array<[string, AnyScraperResponse]>>;
+    extractContent(response: AnyScraperResponse): [string, undefined | References];
+    extractMetadata(response: AnyScraperResponse): ScrapeMetadata | GenericScrapeMetadata;
 }
 /** Firecrawl */
 export type FirecrawlScrapeOptions = Omit<FirecrawlScraperConfig, 'apiKey' | 'apiUrl' | 'version' | 'logger'>;
 export type SerperScrapeOptions = Omit<SerperScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+export type TavilyScrapeOptions = Omit<TavilyScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+export interface TavilyExtractPayload {
+    urls: string[];
+    extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
+    include_images: boolean;
+    include_favicon?: boolean;
+    format?: NonNullable<TavilyScraperConfig['format']>;
+    timeout?: number;
+}
+export type GenericScrapeMetadata = Record<string, string | number | boolean | null | undefined>;
 export interface ScrapeMetadata {
     sourceURL?: string;
     url?: string;
@@ -247,6 +309,38 @@ export interface SerperScrapeResponse {
     };
     error?: string;
 }
+export interface TavilyScrapeResponse {
+    success: boolean;
+    data?: {
+        rawContent?: string;
+        images?: string[];
+        favicon?: string;
+    };
+    error?: string;
+}
+export interface TavilySearchResult {
+    title?: string;
+    url?: string;
+    content?: string;
+    score?: number;
+    published_date?: string;
+}
+export type TavilyImageResult = string | {
+    url?: string;
+    description?: string;
+};
+export interface TavilySearchResponse {
+    answer?: string;
+    images?: TavilyImageResult[];
+    results?: TavilySearchResult[];
+}
+export interface TavilyExtractResult {
+    url: string;
+    raw_content?: string;
+    images?: string[];
+    favicon?: string;
+    error?: string;
+}
 export interface FirecrawlScraperConfig {
     apiKey?: string;
     apiUrl?: string;

package/dist/types/tools/search/utils.d.ts

@@ -6,5 +6,5 @@ import type * as t from './types';
  */
 export declare const createDefaultLogger: () => t.Logger;
 export declare const fileExtRegex: RegExp;
-export declare const getDomainName: (link: string, metadata?: t.ScrapeMetadata, logger?: t.Logger) => string | undefined;
-export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata, logger?: t.Logger): string | undefined;
+export declare const getDomainName: (link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger) => string | undefined;
+export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger): string | undefined;

package/dist/types/tools/skillCatalog.d.ts

@@ -0,0 +1,19 @@
+import type { SkillCatalogEntry } from '@/types';
+export type SkillCatalogOptions = {
+    /** Total context window in tokens. Default: 200_000 */
+    contextWindowTokens?: number;
+    /** Fraction of context budget for catalog. Default: 0.01 (1%) */
+    budgetPercent?: number;
+    /** Max chars per entry description. Default: 250 */
+    maxEntryChars?: number;
+    /** Descriptions below this length trigger names-only fallback. Default: 20 */
+    minDescLength?: number;
+    /** Approximate chars per token for budget calculation. Default: 4 */
+    charsPerToken?: number;
+};
+/**
+ * Formats a skill catalog for injection into agent context.
+ * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
+ * Returns empty string for empty input.
+ */
+export declare function formatSkillCatalog(skills: SkillCatalogEntry[], opts?: SkillCatalogOptions): string;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -0,0 +1,137 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, TokenCounter } from '@/types';
+import type { HookRegistry } from '@/hooks';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs/Graph';
+import type { HandlerRegistry } from '@/events';
+export type SubagentExecuteParams = {
+    description: string;
+    subagentType: string;
+    threadId?: string;
+    /**
+     * Parent-side `tool_call_id` of the `subagent` tool invocation that
+     * triggered this execution. Surfaced on {@link SubagentUpdateEvent} so
+     * hosts can correlate child updates back to the originating tool call
+     * without relying on event ordering heuristics.
+     */
+    parentToolCallId?: string;
+};
+export type SubagentExecuteResult = {
+    content: string;
+    messages: BaseMessage[];
+};
+/**
+ * Factory that constructs a child graph for subagent execution. Injected
+ * rather than imported so that `SubagentExecutor` does not have a runtime
+ * dependency on `StandardGraph` — this avoids a circular dependency between
+ * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break
+ * Rollup's chunking under `preserveModules`.
+ */
+export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
+export type SubagentExecutorOptions = {
+    configs: Map<string, ResolvedSubagentConfig>;
+    parentSignal?: AbortSignal;
+    hookRegistry?: HookRegistry;
+    parentRunId: string;
+    parentAgentId?: string;
+    tokenCounter?: TokenCounter;
+    /** Remaining nesting budget. 0 or negative blocks execution. */
+    maxDepth?: number;
+    /**
+     * Factory for constructing the isolated child graph. Callers pass
+     * `(input) => new StandardGraph(input)` — injected to break a circular
+     * module dependency.
+     */
+    createChildGraph: ChildGraphFactory;
+    /**
+     * Parent's event handler registry. When provided, child-graph events are
+     * forwarded through this registry so hosts can:
+     *   (a) execute event-driven tools (`ON_TOOL_EXECUTE` routed to parent's handler),
+     *   (b) surface child activity to a UI via wrapped {@link GraphEvents.ON_SUBAGENT_UPDATE}.
+     * When omitted, the child runs fully isolated (legacy behavior).
+     *
+     * Can be a direct `HandlerRegistry` or a zero-arg getter — use the getter
+     * form when the registry is assigned to the graph AFTER the executor is
+     * constructed (the current `Run.create` flow sets `handlerRegistry`
+     * post-`createWorkflow`, so `createAgentNode` must capture lazily).
+     */
+    parentHandlerRegistry?: HandlerRegistry | (() => HandlerRegistry | undefined);
+};
+export declare class SubagentExecutor {
+    private readonly configs;
+    private readonly parentSignal?;
+    private readonly hookRegistry?;
+    private readonly parentRunId;
+    private readonly parentAgentId?;
+    private readonly tokenCounter?;
+    private readonly maxDepth;
+    private readonly createChildGraph;
+    private readonly resolveParentHandlerRegistry?;
+    constructor(options: SubagentExecutorOptions);
+    /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
+    private getParentHandlerRegistry;
+    execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
+    /**
+     * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
+     * parent's handler registry. Silent no-op when no parent registry is set.
+     * Errors are swallowed — update events are observational.
+     */
+    private emitSubagentUpdate;
+    /**
+     * Builds a BaseCallbackHandler that intercepts the child graph's custom
+     * events. Routing rules:
+     *   - `ON_TOOL_EXECUTE` → forwarded as-is to the parent's ON_TOOL_EXECUTE
+     *     handler (so event-driven tools work identically for child and parent).
+     *   - `ON_RUN_STEP` / `ON_RUN_STEP_DELTA` / `ON_RUN_STEP_COMPLETED` /
+     *     `ON_MESSAGE_DELTA` / `ON_REASONING_DELTA` → wrapped in a
+     *     {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope with a human-readable
+     *     label, delivered to the parent's subagent-update handler.
+     *   - Everything else → ignored (keeps parent's UI scoped to the events it
+     *     cares about; host apps can extend by registering more phases).
+     */
+    private createForwarderCallback;
+}
+/**
+ * Produces a short single-line label for an arbitrary forwarded child event.
+ * Used to populate {@link SubagentUpdateEvent.label} so the host UI can show
+ * a compact status ticker without parsing the raw payload.
+ */
+export declare function summarizeEvent(eventName: string, data: unknown): string;
+/**
+ * Walk messages from last to first, returning the text content of the most
+ * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
+ * redacted_thinking, tool_result) are stripped. If the last AIMessage is
+ * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
+ * continues to earlier AIMessages so partial progress is salvaged — this
+ * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Returns "Task completed" only when no AIMessage in the history contains
+ * any text.
+ */
+export declare function filterSubagentResult(messages: BaseMessage[]): string;
+/**
+ * Resolve self-spawn configs by filling in agentInputs from the parent context.
+ * Returns configs with agentInputs guaranteed present. Throws on duplicate
+ * `type` values to prevent silent config shadowing.
+ */
+export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
+/**
+ * Build child AgentInputs from a resolved config, stripping nesting and
+ * (optionally) event-driven fields. When `allowNested: true`, the child's
+ * `maxSubagentDepth` is decremented so that depth is consumed as the call
+ * chain deepens across graph boundaries — the parent's executor-level check
+ * alone cannot see into the child graph's separate executor.
+ *
+ * When `keepToolDefinitions` is `true`, the child retains the parent's
+ * `toolDefinitions` so event-driven tools remain usable. This is only safe
+ * when the caller has wired a forwarder for `ON_TOOL_EXECUTE` to a
+ * registered handler — otherwise the child will hang on tool dispatch.
+ *
+ * @remarks Advanced utility: exported primarily for testing and by
+ * {@link SubagentExecutor}. Host applications configuring subagents should
+ * not need to call this directly — it is invoked internally when a subagent
+ * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
+ * child's decremented `maxSubagentDepth` on the returned inputs) is the
+ * mechanism that bounds nesting across graph boundaries; callers must
+ * respect it.
+ */
+export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number, keepToolDefinitions?: boolean): AgentInputs;

package/dist/types/tools/subagent/index.d.ts

@@ -0,0 +1,2 @@
+export { SubagentExecutor, filterSubagentResult, resolveSubagentConfigs, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
+export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';

package/dist/types/tools/subagent/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared types for the subagent file-passing pipeline.
+ *
+ * Single source of truth for:
+ *   - the `file_ids` shape carried on the `subagent` tool's input schema
+ *   - the manifest line format the host renders into the supervisor's
+ *     trailing user-message channel (cache-stable, never the system block)
+ *   - the resolver hook signature host applications implement to map
+ *     parent-side `file_id`s into the child's `tool_resources` + first
+ *     HumanMessage context blocks
+ *
+ * Keeping these in one place lets the lib, the host, and tests all
+ * reference the SAME constants — drift would silently break selective
+ * file passing (parent claims a file is available, child gets `null`).
+ */
+/**
+ * One entry in the parent's file manifest. The host serializes an array of
+ * these into a short newline-delimited block that lives in the supervisor's
+ * trailing user-message channel — see `MANIFEST_PREFIX` /
+ * `formatFileManifest` for the canonical line format.
+ */
+export interface SubagentFileManifestEntry {
+    /** Stable file ID. Parent's LLM passes this back via `subagent({ file_ids })`. */
+    file_id: string;
+    /** Display name, used in the manifest line. */
+    name: string;
+    /** MIME type. Optional — only included in the manifest when present. */
+    type?: string;
+    /** Size in bytes. Optional — formatted for human readability when present. */
+    size?: number;
+}
+/** Header line that begins every parent file manifest block. */
+export declare const MANIFEST_PREFIX = "Files available for delegation:";
+/**
+ * Format a single manifest entry as a `- key: value, key: value, ...` line.
+ * Pure function — keeps the format consistent across host injection paths
+ * and test assertions.
+ */
+export declare function formatManifestEntry(entry: SubagentFileManifestEntry): string;
+/**
+ * Format a full manifest block for injection below the cache breakpoint.
+ * Returns `null` for empty input so callers can `if (block) push(block)`.
+ */
+export declare function formatFileManifest(entries: readonly SubagentFileManifestEntry[]): string | null;
+/**
+ * Result of resolving parent-side `file_ids` for a child subagent invocation.
+ * Each field is shaped to slot directly into the child's runtime:
+ *   - `toolResources` is merged into the child's `agentInputs.tool_resources`
+ *     so file_search / execute_code tools see the file
+ *   - `messageContextBlocks` is prepended to the child's first HumanMessage
+ *     (alongside the supervisor's task description) so the child sees image
+ *     blocks for vision models and a short text reference for everything else
+ */
+export interface ResolvedSubagentFiles {
+    /**
+     * Augmented tool_resources object merged into the child's `agentInputs`.
+     * Shape matches `AgentToolResources` from the host (kept untyped here to
+     * avoid pulling host types into the lib).
+     */
+    toolResources?: Record<string, unknown>;
+    /**
+     * Files the resolver successfully looked up. Forwarded verbatim into the
+     * child's first message metadata for downstream attachment rendering.
+     */
+    attachments?: Array<Record<string, unknown>>;
+    /**
+     * LangChain `HumanMessage.content` blocks (text or image_url) that should
+     * be prepended to the child's first message. Empty array for the common
+     * case where files are referenced only via tool_resources.
+     */
+    messageContextBlocks?: Array<Record<string, unknown>>;
+}
+/**
+ * Hook the host injects to resolve parent-side `file_id`s into child runtime
+ * context. Called once per `subagent` tool invocation that includes
+ * `file_ids`. Must be cheap on the empty-array path — the lib calls it for
+ * every subagent dispatch.
+ *
+ * @param fileIds - ID strings the supervisor's LLM picked from the manifest.
+ * @param childAgentId - ID assigned to the child for this invocation.
+ * @returns Resolved file context for the child, or `undefined` when nothing
+ *   could be resolved (treated as a soft no-op — the child still runs).
+ */
+export type ResolveSubagentFiles = (fileIds: string[], childAgentId: string) => Promise<ResolvedSubagentFiles | undefined>;

package/dist/types/tools/toolOutputReferences.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Tool output reference registry.
+ *
+ * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode
+ * stores each successful tool output under a stable key
+ * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a
+ * ToolNode batch and `turn` is the batch index within the run
+ * (incremented once per ToolNode invocation).
+ *
+ * Subsequent tool calls can pipe a previous output into their args by
+ * embedding `{{tool<idx>turn<turn>}}` inside any string argument;
+ * {@link ToolOutputReferenceRegistry.resolve} walks the args and
+ * substitutes the placeholders immediately before invocation.
+ *
+ * The registry stores the *raw, untruncated* tool output so a later
+ * `{{…}}` substitution pipes the full payload into the next tool —
+ * even when the LLM only saw a head+tail-truncated preview in
+ * `ToolMessage.content`. Outputs are stored without any annotation
+ * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is
+ * strictly a UX signal attached to `ToolMessage.content`). Keeping the
+ * registry pristine means downstream bash/jq piping receives the
+ * complete, verbatim output with no injected fields.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
+ * Exported for consumers that want to detect references (e.g., syntax
+ * highlighting, docs). The stateful `g` variant lives inside the
+ * registry so nobody trips on `lastIndex`.
+ */
+export declare const TOOL_OUTPUT_REF_PATTERN: RegExp;
+/** Object key used when a parsed-object output has `_ref` injected. */
+export declare const TOOL_OUTPUT_REF_KEY = "_ref";
+/**
+ * Object key used to carry unresolved reference warnings on a parsed-
+ * object output. Using a dedicated field instead of a trailing text
+ * line keeps the annotated `ToolMessage.content` parseable as JSON for
+ * downstream consumers that rely on the object shape.
+ */
+export declare const TOOL_OUTPUT_UNRESOLVED_KEY = "_unresolved_refs";
+/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */
+export declare function buildReferencePrefix(key: string): string;
+/** Stable registry key for a tool output. */
+export declare function buildReferenceKey(toolIndex: number, turn: number): string;
+export type ToolOutputReferenceRegistryOptions = {
+    /** Maximum characters stored per registered output. */
+    maxOutputSize?: number;
+    /** Maximum total characters retained across all registered outputs. */
+    maxTotalSize?: number;
+    /**
+     * Upper bound on the number of concurrently-tracked runs. When
+     * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.
+     */
+    maxActiveRuns?: number;
+};
+/**
+ * Result of resolving placeholders in tool args.
+ */
+export type ResolveResult<T> = {
+    /** Arguments with placeholders replaced. Same shape as the input. */
+    resolved: T;
+    /** Reference keys that were referenced but had no stored value. */
+    unresolved: string[];
+};
+/**
+ * Read-only view over a frozen registry snapshot. Returned by
+ * {@link ToolOutputReferenceRegistry.snapshot} for callers that need
+ * to resolve placeholders against the registry state at a specific
+ * point in time, ignoring any subsequent registrations.
+ */
+export interface ToolOutputResolveView {
+    resolve<T>(args: T): ResolveResult<T>;
+}
+/**
+ * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed
+ * direct+event dispatch path to feed event calls' resolved args
+ * (captured pre-batch) into the dispatcher without re-resolving
+ * against the now-stale live registry.
+ */
+export type PreResolvedArgsMap = Map<string, {
+    resolved: Record<string, unknown>;
+    unresolved: string[];
+}>;
+/**
+ * Per-call sink for resolved args, keyed by `toolCallId`. Threaded
+ * as a per-batch local map so concurrent `ToolNode.run()` calls do
+ * not race on shared sink state.
+ */
+export type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;
+/**
+ * Ordered map of reference-key → stored output, partitioned by run so
+ * concurrent / interleaved runs sharing one registry cannot leak
+ * outputs between each other.
+ *
+ * Each public method takes a `runId` which selects the run's bucket.
+ * Hosts typically get one registry per run via `Graph`, in which
+ * case only a single bucket is ever populated; the partitioning
+ * exists so the registry also behaves correctly when a single
+ * instance is reused directly.
+ */
+export declare class ToolOutputReferenceRegistry {
+    private runStates;
+    private readonly maxOutputSize;
+    private readonly maxTotalSize;
+    private readonly maxActiveRuns;
+    /**
+     * Local stateful matcher used only by `replaceInString`. Kept
+     * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`
+     * never see a stale `lastIndex`.
+     */
+    private static readonly PLACEHOLDER_MATCHER;
+    constructor(options?: ToolOutputReferenceRegistryOptions);
+    private keyFor;
+    private getOrCreate;
+    /** Registers (or replaces) the output stored under `key` for `runId`. */
+    set(runId: string | undefined, key: string, value: string): void;
+    /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */
+    get(runId: string | undefined, key: string): string | undefined;
+    /**
+     * Returns `true` when `key` is currently stored in `runId`'s bucket.
+     * Used by {@link annotateMessagesForLLM} to gate transient annotation
+     * on whether the registry still owns the referenced output (a stale
+     * `_refKey` from a prior run silently no-ops here).
+     */
+    has(runId: string | undefined, key: string): boolean;
+    /** Total number of registered outputs across every run bucket. */
+    get size(): number;
+    /** Maximum characters retained per output (post-clip). */
+    get perOutputLimit(): number;
+    /** Maximum total characters retained *per run*. */
+    get totalLimit(): number;
+    /** Drops every run's state. */
+    clear(): void;
+    /**
+     * Explicitly release `runId`'s state. Safe to call when a run has
+     * finished. Hosts sharing one registry across runs should call this
+     * to reclaim memory deterministically; otherwise LRU eviction kicks
+     * in when `maxActiveRuns` runs accumulate.
+     */
+    releaseRun(runId: string | undefined): void;
+    /**
+     * Claims the next batch turn synchronously from `runId`'s bucket.
+     *
+     * Must be called once at the start of each ToolNode batch before
+     * any `await`, so concurrent invocations within the same run see
+     * distinct turn values (reads are effectively atomic by JS's
+     * single-threaded execution of the sync prefix).
+     *
+     * If `runId` is missing the anonymous bucket is dropped and a
+     * fresh one created so each anonymous call behaves as its own run.
+     */
+    nextTurn(runId: string | undefined): number;
+    /**
+     * Records that `toolName` has been warned about in `runId` (returns
+     * `true` on the first call per run, `false` after). Used by
+     * ToolNode to emit one log line per offending tool per run when a
+     * `ToolMessage.content` isn't a string.
+     */
+    claimWarnOnce(runId: string | undefined, toolName: string): boolean;
+    /**
+     * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in
+     * string values with the stored output *from `runId`'s bucket*. Non-
+     * string values and object keys are left untouched. Unresolved
+     * references are left in-place and reported so the caller can
+     * surface them to the LLM. When no placeholder appears anywhere in
+     * the serialized args, the original input is returned without
+     * walking the tree.
+     */
+    resolve<T>(runId: string | undefined, args: T): ResolveResult<T>;
+    /**
+     * Captures a frozen snapshot of `runId`'s current entries and
+     * returns a view that resolves placeholders against *only* that
+     * snapshot. The snapshot is decoupled from the live registry, so
+     * subsequent `set()` calls (for example, same-turn direct outputs
+     * registering while an event branch is still in flight) are
+     * invisible to the snapshot's `resolve`. Used by the mixed
+     * direct+event dispatch path to preserve same-turn isolation when
+     * a `PreToolUse` hook rewrites event args after directs have
+     * completed.
+     */
+    snapshot(runId: string | undefined): ToolOutputResolveView;
+    private resolveAgainst;
+    private transform;
+    private replaceInString;
+    private evictWithinBucket;
+}
+/**
+ * Annotates `content` with a reference key and/or unresolved-ref
+ * warnings so the LLM sees both alongside the tool output.
+ *
+ * Behavior:
+ *  - If `content` parses as a plain (non-array, non-null) JSON object
+ *    and the object does not already have a conflicting `_ref` key,
+ *    the reference key and (when present) `_unresolved_refs` array
+ *    are injected as object fields, preserving JSON validity for
+ *    downstream consumers that parse the output.
+ *  - Otherwise (string output, JSON array/primitive, parse failure,
+ *    or `_ref` collision), a `[ref: <key>]\n` prefix line is
+ *    prepended and unresolved refs are appended as a trailing
+ *    `[unresolved refs: …]` line.
+ *
+ * The annotated string is what the LLM sees as `ToolMessage.content`.
+ * The *original* (un-annotated) value is what gets stored in the
+ * registry, so downstream piping remains pristine.
+ *
+ * @param content     Raw (post-truncation) tool output.
+ * @param key         Reference key for this output, or undefined when
+ *                    there is nothing to register (errors etc.).
+ * @param unresolved  Reference keys that failed to resolve during
+ *                    argument substitution. Surfaced so the LLM can
+ *                    self-correct its next tool call.
+ */
+export declare function annotateToolOutputWithReference(content: string, key: string | undefined, unresolved?: string[]): string;
+/**
+ * Lazy projection that, given a registry and a runId, returns a new
+ * `messages` array where each `ToolMessage` carrying ref metadata is
+ * projected into a transient copy with annotated content (when the ref
+ * is live in the registry) and with the framework-owned `additional_
+ * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped
+ * regardless of whether annotation applied. The original input array
+ * and its messages are never mutated.
+ *
+ * Annotation is gated on registry presence: a stale `_refKey` from a
+ * prior run (e.g. one that survived in persisted history) silently
+ * no-ops on the *content* side. The strip-metadata side still runs so
+ * stale framework keys never leak onto the wire under any custom or
+ * future provider serializer that might transmit `additional_kwargs`.
+ * `_unresolvedRefs` is always meaningful and is not gated.
+ *
+ * **Feature-disabled fast path:** when the host hasn't enabled the
+ * tool-output-reference feature, the registry is `undefined` and this
+ * function returns the input array reference-equal *without iterating
+ * a single message*. The loop is exclusive to the feature-enabled
+ * code path.
+ */
+export declare function annotateMessagesForLLM(messages: BaseMessage[], registry: ToolOutputReferenceRegistry | undefined, runId: string | undefined): BaseMessage[];