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

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

@@ -0,0 +1,36 @@
+import { Constants } from '@/common';
+import type { SubagentConfig } from '@/types';
+import type { JsonSchemaType, LCTool } from '@/types/tools';
+export declare const SubagentToolName = Constants.SUBAGENT;
+export declare const SubagentToolDescription = "Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent is created with the task description as its only input.\n- The subagent runs to completion using its own tools and context.\n- Only the final text response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
+export declare const SubagentToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";
+        };
+        readonly subagent_type: {
+            readonly type: "string";
+            readonly description: "Which subagent type to delegate to. Must be one of the available types.";
+        };
+    };
+    readonly required: string[];
+};
+export declare const SubagentToolDefinition: LCTool;
+/**
+ * Build the name, schema, and description params for `tool()` from available configs.
+ * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
+ * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
+ */
+export declare function buildSubagentToolParams(configs: SubagentConfig[]): {
+    name: string;
+    schema: JsonSchemaType;
+    description: string;
+};
+/**
+ * Create a SubagentTool LCTool definition with dynamic enum and description
+ * populated from the available subagent configs.
+ * Used for the tool registry in event-driven mode.
+ */
+export declare function createSubagentToolDefinition(configs: SubagentConfig[]): LCTool;

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

@@ -4,6 +4,23 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
+/**
+ * Per-call batch context for `runTool`. Bundles every optional batch-scoped
+ * value the method needs so the signature stays at three positional params
+ * even as new context fields are added. (PR #117).
+ */
+type RunToolBatchContext = {
+    /** Position of this call within the parent ToolNode batch. */
+    batchIndex?: number;
+    /** Batch turn shared across every call in the batch. */
+    turn?: number;
+    /** Registry partition scope (run id or anonymous batch id). */
+    batchScopeId?: string;
+    /** Batch-local sink for post-substitution args. */
+    resolvedArgsByCallId?: ResolvedArgsByCallId;
+};
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolMap;
     private loadRuntimeTools?;
@@ -30,7 +47,37 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolApprovalConfig?;
     /** Buffer for recovering truncated tool call arguments from streaming data */
     private streamingToolCallBuffer?;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, streamingToolCallBuffer, toolApprovalConfig, }: t.ToolNodeConstructorParams);
+    /** Hook registry threaded down from Run for tool-lifecycle events. */
+    private hookRegistry?;
+    /**
+     * Tool output reference registry threaded down from Run / Graph
+     * (PR #114). When set, dispatchToolEvents resolves
+     * `{{tool<i>turn<n>}}` placeholders in args before invoking each tool
+     * and stores successful outputs under their stable reference keys for
+     * subsequent calls in the same run to pipe through.
+     */
+    private toolOutputRegistry?;
+    /**
+     * Per-batch turn counter for the registry. Increments once per
+     * `dispatchToolEvents` invocation so `tool<i>turn<n>` keys remain
+     * unique across overlapping batches in a single run.
+     */
+    private toolOutputTurn;
+    /**
+     * Counter for synthesising scope ids when `run()` is called without a
+     * `run_id` in config. Each anonymous batch gets a unique
+     * `\0anon-<n>` scope so concurrent invocations don't collide on the
+     * shared `toolOutputRegistry`.
+     */
+    private anonBatchCounter;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, streamingToolCallBuffer, toolApprovalConfig, hookRegistry, toolOutputRegistry, toolOutputReferences, maxToolResultChars: _maxToolResultChars, }: t.ToolNodeConstructorParams);
+    /**
+     * Test-observation accessor for the tool-output reference registry.
+     * @internal Exposed for test observation only. Host code should rely on
+     * `{{tool<i>turn<n>}}` substitution at tool-invocation time and not
+     * mutate the registry directly.
+     */
+    _unsafeGetToolOutputRegistry(): ToolOutputReferenceRegistry | undefined;
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -63,9 +110,15 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private requestApproval;
     /**
-     * Runs a single tool call with error handling
+     * Runs a single tool call with error handling.
+     *
+     * @param batchContext  Optional per-batch context (PR #117).
+     *   Threaded from `run()` for tool output reference annotation. The
+     *   `batchScopeId` field carries an anonymous synthetic scope when the
+     *   caller has no `run_id`, so concurrent batches don't collide on the
+     *   shared registry.
      */
-    protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
+    protected runTool(call: ToolCall, config: RunnableConfig, batchContext?: RunToolBatchContext): Promise<BaseMessage | Command>;
     /**
      * Recover truncated tool call arguments using the raw streaming buffer.
      *
@@ -89,6 +142,14 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * @returns The args with recovered fields merged in
      */
     private recoverTruncatedArgs;
+    /**
+     * Stores the raw, untruncated tool output in the registry under `refKey`
+     * (when registry + refKey are both present) and returns the metadata
+     * envelope to stamp on `ToolMessage.additional_kwargs`. The lazy
+     * annotation transform reads `_refKey` / `_refScope` / `_unresolvedRefs`
+     * at LLM request time to produce the transient annotated copy.
+     */
+    private recordOutputReference;
     /**
      * Builds code session context for injection into event-driven tool calls.
      * Mirrors the session injection logic in runTool() for direct execution.
@@ -110,8 +171,18 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private handleRunToolCompletions;
     /**
-     * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
-     * Core logic for event-driven execution, separated from output shaping.
+     * Converts InjectedMessage entries into LangChain HumanMessages.
+     * 'user' and 'system' both become HumanMessage to avoid provider rejections
+     * (Anthropic/Google reject non-leading SystemMessages); the original role
+     * and metadata are preserved in additional_kwargs for downstream consumers.
+     */
+    private convertInjectedMessages;
+    /**
+     * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns
+     * the resulting ToolMessages along with any injected messages emitted by
+     * the host (e.g. SkillTool body injection). Injected messages must be
+     * placed AFTER the ToolMessages so the AIMessage tool_calls -> ToolMessage
+     * adjacency required by some providers is preserved.
      */
     private dispatchToolEvents;
     /**
@@ -124,3 +195,4 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private isMessagesState;
 }
 export declare function toolsCondition<T extends string>(state: BaseMessage[] | typeof MessagesAnnotation.State, toolNode: T, invokedToolIds?: Set<string>): T | typeof END;
+export {};

package/dist/types/tools/memory/shared.d.ts

@@ -67,7 +67,7 @@ export interface MemoryGetToolResult {
 export declare function buildMemorySearchUnavailableResult(error: string | undefined): MemorySearchToolResult;
 /**
  * Clamp a ranked result list to a total character budget.
- * Ported from upstream `tools.citations.ts::clampResultsByInjectedChars`.
+ * Ported from a reference implementation `tools.citations.ts::clampResultsByInjectedChars`.
  */
 export declare function clampResultsByInjectedChars<T extends {
     content: string;

package/dist/types/tools/search/tavily-scraper.d.ts

@@ -0,0 +1,19 @@
+import type * as t from './types';
+export declare class TavilyScraper implements t.BaseScraper {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private payloadTimeout;
+    private logger;
+    private extractDepth;
+    private includeImages;
+    private includeFavicon;
+    private format;
+    constructor(config?: t.TavilyScraperConfig);
+    scrapeUrl(url: string, options?: t.TavilyScrapeOptions): Promise<[string, t.TavilyScrapeResponse]>;
+    scrapeUrls(urls: string[], options?: t.TavilyScrapeOptions): Promise<Array<[string, t.TavilyScrapeResponse]>>;
+    private extractBatch;
+    extractContent(response: t.TavilyScrapeResponse): [string, undefined | t.References];
+    extractMetadata(response: t.TavilyScrapeResponse): t.GenericScrapeMetadata;
+}
+export declare const createTavilyScraper: (config?: t.TavilyScraperConfig) => TavilyScraper;

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

@@ -0,0 +1,4 @@
+import type * as t from './types';
+export declare const createTavilyAPI: (apiKey?: string, apiUrl?: string, options?: t.TavilySearchOptions) => {
+    getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
+};

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>;