@illuma-ai/agents 1.5.1 → 2.1.1

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

@@ -3,12 +3,6 @@ import type * as t from '@/types';
 import { Constants } from '@/common';
 export declare const imageExtRegex: RegExp;
 export declare const getCodeBaseURL: () => string;
-/**
- * Renders one section of the post-execution file listing. Used by the
- * code/bash tool formatters to keep generated outputs and inherited
- * inputs visually separated. See BashExecutor for full docs.
- */
-export declare function renderFileSection(header: string, files: t.FileRefs, defaultMessage: string): string;
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {

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

@@ -9,7 +9,7 @@ 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).
+ * even as new context fields are added. Upstream-aligned (PR #117).
  */
 type RunToolBatchContext = {
     /** Position of this call within the parent ToolNode batch. */
@@ -51,7 +51,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private hookRegistry?;
     /**
      * Tool output reference registry threaded down from Run / Graph
-     * (PR #114). When set, dispatchToolEvents resolves
+     * (upstream 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.
@@ -112,7 +112,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     /**
      * Runs a single tool call with error handling.
      *
-     * @param batchContext  Optional per-batch context (PR #117).
+     * @param batchContext  Optional per-batch context (upstream 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

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 a reference implementation `tools.citations.ts::clampResultsByInjectedChars`.
+ * Ported from upstream `tools.citations.ts::clampResultsByInjectedChars`.
  */
 export declare function clampResultsByInjectedChars<T extends {
     content: string;

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

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

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' | 'tavily';
-export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
+export type SearchProvider = 'serper' | 'searxng';
+export type ScraperProvider = 'firecrawl' | 'serper';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 export interface Highlight {
     score: number;
@@ -56,50 +56,11 @@ 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[];
@@ -140,16 +101,6 @@ 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;
 }
@@ -190,7 +141,6 @@ 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;
@@ -213,27 +163,15 @@ 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, AnyScraperResponse]>;
-    scrapeUrls?(urls: string[], options?: unknown): Promise<Array<[string, AnyScraperResponse]>>;
-    extractContent(response: AnyScraperResponse): [string, undefined | References];
-    extractMetadata(response: AnyScraperResponse): ScrapeMetadata | GenericScrapeMetadata;
+    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>;
 }
 /** 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;
@@ -309,38 +247,6 @@ 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 | t.GenericScrapeMetadata, logger?: t.Logger) => string | undefined;
-export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger): string | undefined;
+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;

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

@@ -15,6 +15,35 @@ export type SubagentExecuteParams = {
      * without relying on event ordering heuristics.
      */
     parentToolCallId?: string;
+    /**
+     * Snapshot of the parent invocation's `config.configurable` at the
+     * spawn-tool call site. Inherited verbatim into the child workflow's
+     * `configurable` so host-set fields (`requestBody`, `user`,
+     * `userMCPAuthMap`, etc.) propagate — fixing MCP body-placeholder
+     * substitution and per-user lookups for subagent tool calls.
+     *
+     * Inheritance details (verified empirically against LangGraph):
+     *   - host-set keys propagate as-is into the child's tool dispatches;
+     *   - `thread_id` propagates (with `childRunId` as a fallback when
+     *     parent did not supply one) — matches the "subagent is part of
+     *     the same conversation" mental model and aligns with the
+     *     `sessionId: this.parentRunId` convention this executor already
+     *     uses for `SubagentStart` / `SubagentStop` hooks;
+     *   - `parent_run_id` propagates when the host put it on parent's
+     *     configurable;
+     *   - `run_id` is *overwritten by the LangGraph runtime* at child
+     *     invoke time regardless of what we forward — child's tool
+     *     dispatches see the child graph's runtime runId in
+     *     `configurable.run_id`, not the parent's. Hosts that need
+     *     parent-scoped run identity for downstream consumers should
+     *     plumb it via a host-defined key (e.g. `requestBody.messageId`),
+     *     not `run_id`.
+     *
+     * A future revision will likely make this inheritance configurable
+     * per spawn type — background / async subagents may want isolation
+     * rather than sharing parent's host context.
+     */
+    parentConfigurable?: Record<string, unknown>;
 };
 export type SubagentExecuteResult = {
     content: string;

package/dist/types/types/graph.d.ts

@@ -10,7 +10,6 @@ import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
 import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { TokenCounter } from '@/types/run';
-import type { SystemCacheBlock, AgentCacheTTL } from '@/types/agent-cache';
 /** Interface for bound model with stream and invoke methods */
 export interface ChatModel {
     stream?: (messages: BaseMessage[], config?: RunnableConfig) => Promise<AsyncIterable<AIMessageChunk>>;
@@ -264,11 +263,10 @@ export type GraphEdge = {
     /**
      * EdgeType.HANDOFF — one-way routing: parent emits an `lc_transfer_to_*`
      *   tool call and exits, child takes over and responds directly to the
-     *   user. Aligns with the standard handoff semantics.
+     *   user. Aligns with upstream's handoff semantics.
      * EdgeType.DIRECT — fixed graph edges for automatic sequential / parallel
-     *   transitions. Downstream consumers may layer additional wiring on top
-     *   (fan-in with prompt, parallel groups, approval-gate nodes,
-     *   excludeResults / agentMessages).
+     *   transitions. Ranger preserves its enriched wiring (fan-in with prompt,
+     *   parallel groups, ApprovalGateNode, excludeResults / agentMessages).
      */
     edgeType?: import('@/common').EdgeType;
     /**
@@ -459,7 +457,7 @@ export interface SummarizationConfig {
      */
     initialSummary?: string;
     /**
-     * optional fields. When the host wants the summarization
+     * Upstream-aligned optional fields. When the host wants the summarization
      * pass to run on a different LLM than the agent's own (e.g. a cheaper
      * model for compaction), these provider/model overrides flow through to
      * the summarize callback.
@@ -569,36 +567,10 @@ export interface AgentInputs {
     toolMap?: ToolMap;
     tools?: GraphTools;
     provider: Providers;
-    /**
-     * Ordered list of cacheable system content blocks emitted BEFORE
-     * `instructions` in the system message. Each block gets its own cache
-     * marker (cachePoint on Bedrock, cache_control on Anthropic) so the
-     * cache key for each block includes only the bytes up to and including
-     * its own marker. Entries are emitted in array order — earlier =
-     * stabler = wider cache key (best for cross-tenant sharing).
-     *
-     * See `src/types/agent-cache.ts` for full semantics. Capped at
-     * `MAX_SYSTEM_CACHE_BLOCKS` (2) entries to stay within Bedrock's
-     * 4-cachePoint budget after the tools array consumes 2.
-     */
-    system_cache_blocks?: SystemCacheBlock[];
-    /**
-     * Stable/cacheable system instructions for this agent. Always emitted
-     * with its own trailing cache marker (when caching is supported by
-     * the provider/model). Use `instructions_cache_ttl` to override the
-     * default '5m' TTL.
-     */
     instructions?: string;
-    /** TTL for the trailing `instructions` cache marker. Defaults to '5m'. */
-    instructions_cache_ttl?: AgentCacheTTL;
     streamBuffer?: number;
     maxContextTokens?: number;
     clientOptions?: ClientOptions;
-    /**
-     * Dynamic system tail appended after the cacheable instructions
-     * without any cache marker. Per-user / per-message context belongs
-     * here so it does not invalidate the cacheable prefix.
-     */
     additional_instructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
     /**
@@ -623,9 +595,9 @@ export interface AgentInputs {
         tokenCount: number;
     };
     /**
-     * opt-in for summarization. When false, the agent never
+     * Upstream-aligned opt-in for summarization. When false, the agent never
      * invokes the summarize callback regardless of context utilization.
-     * Defaults to undefined (treated as enabled by default to preserve prior
+     * Defaults to undefined (treated as enabled in Ranger to preserve prior
      * behaviour); hosts that want strict opt-in semantics should set it
      * explicitly.
      */
@@ -689,6 +661,30 @@ export interface AgentInputs {
      * @see SummarizationConfig
      */
     summarizationConfig?: SummarizationConfig;
+    /**
+     * Workspace-shared system-message tiers. Each entry becomes a separate
+     * text block in the SystemMessage with its own cachePoint / cache_control
+     * marker, allowing the platform-tier bytes (e.g. shared branding, tool
+     * routing rules, code-executor instructions) to be hashed independently
+     * from the per-agent `instructions` block. Hosts that don't use tiered
+     * caching can leave this undefined; behavior falls back to the legacy
+     * single SystemMessage.
+     *
+     * Anthropic / Bedrock prompt-cache lookups are forward-prefix-hash, so
+     * blocks are emitted in array order BEFORE `instructions`. Up to 4 blocks
+     * are supported (the LLM cap on cache breakpoints).
+     */
+    system_cache_blocks?: Array<{
+        text: string;
+        ttl?: '5m' | '1h';
+    }>;
+    /**
+     * TTL hint for the per-agent `instructions` block's cache marker.
+     * Defaults to '5m' (matching addCacheControl message-level behavior).
+     * Only consulted when `system_cache_blocks` is set; otherwise the
+     * legacy SystemMessage path is unchanged.
+     */
+    instructions_cache_ttl?: '5m' | '1h';
     /**
      * Lightweight file manifest for the conversation.
      * Contains file IDs, names, and metadata — NOT full content.

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

@@ -1,4 +1,3 @@
-export * from './agent-cache';
 export * from './graph';
 export * from './llm';
 export * from './messages';

package/dist/types/types/messages.d.ts

@@ -4,7 +4,7 @@ export type AnthropicMessages = Array<AnthropicMessage | BaseMessage>;
 export type AnthropicMessage = Anthropic.MessageParam;
 /**
  * Per-message ref metadata stamped onto a `ToolMessage` at execution time
- * (PR #117). Read by `annotateMessagesForLLM` to apply transient
+ * (upstream PR #117). Read by `annotateMessagesForLLM` to apply transient
  * annotation to a copy of the message right before it goes on the wire to
  * the provider. Never read after the run-scoped registry has been cleared.
  *

package/dist/types/types/run.d.ts

@@ -62,9 +62,7 @@ export interface AgentStateChannels {
     messages: BaseMessage[];
     next: string;
     [key: string]: unknown;
-    /** Stable/cacheable system instructions for this agent. */
     instructions?: string;
-    /** Dynamic system tail appended after stable instructions. */
     additional_instructions?: string;
 }
 export interface Member {
@@ -121,7 +119,7 @@ export type RunConfig = {
      */
     hooks?: HookRegistry;
     /**
-     * Tool output reference configuration (PRs #114 / #117).
+     * Tool output reference configuration (upstream PRs #114 / #117).
      * When `enabled` is true, the Run constructs a single
      * ToolOutputReferenceRegistry and threads it to every ToolNode built by
      * the graph so `{{tool<i>turn<n>}}` placeholders resolve across agents.

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

@@ -60,13 +60,13 @@ export type ToolNodeOptions = {
     /**
      * Maximum characters for a single tool result (head+tail truncation).
      * When omitted, derived from the agent's `maxContextTokens` (30%
-     * heuristic), capped at HARD_MAX_TOOL_RESULT_CHARS. —
-     * downstream consumers may drive truncation through other knobs;
-     * accepting this option keeps the test surface portable.
+     * heuristic), capped at HARD_MAX_TOOL_RESULT_CHARS. Upstream-aligned —
+     * Ranger's truncation today is driven by other knobs, but accepting
+     * this option keeps the test surface portable.
      */
     maxToolResultChars?: number;
     /**
-     * Run-scoped tool output reference configuration (PR #114).
+     * Run-scoped tool output reference configuration (upstream PR #114).
      * When `enabled` is true, ToolNode registers successful outputs and
      * substitutes `{{tool<i>turn<n>}}` placeholders found in string args.
      * Ignored when `toolOutputRegistry` is also provided (the host-supplied
@@ -123,15 +123,6 @@ export type FileRef = {
     path?: string;
     /** Session ID this file belongs to (for multi-session file tracking) */
     session_id?: string;
-    /**
-     * `true` when the codeapi sandbox echoed this entry as an unchanged
-     * passthrough of an input the caller already owns (skill files,
-     * downloaded inputs whose hash matched the baseline, inherited
-     * `.dirkeep` markers). The tool-result formatter renders these as
-     * "Available files" rather than "Generated files" so the LLM doesn't
-     * conflate infrastructure inputs with newly-produced outputs.
-     */
-    inherited?: true;
 };
 export type FileRefs = FileRef[];
 export type ExecuteResult = {
@@ -255,7 +246,7 @@ export type ToolExecuteResult = {
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
 /**
- * Configuration for the tool output reference feature (PR #114).
+ * Configuration for the tool output reference feature (upstream PR #114).
  *
  * When `enabled: true`, ToolNode stores each successful tool output under
  * a stable key `tool<idx>turn<turn>` and the LLM can pipe a previous output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.5.1",
+  "version": "2.1.1",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -9,66 +9,6 @@
       "import": "./dist/esm/main.mjs",
       "require": "./dist/cjs/main.cjs",
       "types": "./dist/types/index.d.ts"
-    },
-    "./langchain": {
-      "import": "./dist/esm/langchain/index.mjs",
-      "require": "./dist/cjs/langchain/index.cjs",
-      "types": "./dist/types/langchain/index.d.ts"
-    },
-    "./langchain/language_models/chat_models": {
-      "import": "./dist/esm/langchain/language_models/chat_models.mjs",
-      "require": "./dist/cjs/langchain/language_models/chat_models.cjs",
-      "types": "./dist/types/langchain/language_models/chat_models.d.ts"
-    },
-    "./langchain/messages": {
-      "import": "./dist/esm/langchain/messages.mjs",
-      "require": "./dist/cjs/langchain/messages.cjs",
-      "types": "./dist/types/langchain/messages.d.ts"
-    },
-    "./langchain/messages/tool": {
-      "import": "./dist/esm/langchain/messages/tool.mjs",
-      "require": "./dist/cjs/langchain/messages/tool.cjs",
-      "types": "./dist/types/langchain/messages/tool.d.ts"
-    },
-    "./langchain/google-common": {
-      "import": "./dist/esm/langchain/google-common.mjs",
-      "require": "./dist/cjs/langchain/google-common.cjs",
-      "types": "./dist/types/langchain/google-common.d.ts"
-    },
-    "./langchain/openai": {
-      "import": "./dist/esm/langchain/openai.mjs",
-      "require": "./dist/cjs/langchain/openai.cjs",
-      "types": "./dist/types/langchain/openai.d.ts"
-    },
-    "./langchain/prompts": {
-      "import": "./dist/esm/langchain/prompts.mjs",
-      "require": "./dist/cjs/langchain/prompts.cjs",
-      "types": "./dist/types/langchain/prompts.d.ts"
-    },
-    "./langchain/runnables": {
-      "import": "./dist/esm/langchain/runnables.mjs",
-      "require": "./dist/cjs/langchain/runnables.cjs",
-      "types": "./dist/types/langchain/runnables.d.ts"
-    },
-    "./langchain/tools": {
-      "import": "./dist/esm/langchain/tools.mjs",
-      "require": "./dist/cjs/langchain/tools.cjs",
-      "types": "./dist/types/langchain/tools.d.ts"
-    },
-    "./langchain/utils/env": {
-      "import": "./dist/esm/langchain/utils/env.mjs",
-      "require": "./dist/cjs/langchain/utils/env.cjs",
-      "types": "./dist/types/langchain/utils/env.d.ts"
-    }
-  },
-  "typesVersions": {
-    "*": {
-      "langchain": [
-        "dist/types/langchain/index.d.ts"
-      ],
-      "langchain/*": [
-        "dist/types/langchain/*"
-      ]
     }
   },
   "type": "module",