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

package/dist/types/types/agent-cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Agent system-message prompt-cache types.
+ * ==========================================
+ *
+ * `@illuma-ai/agents` exposes a generic primitive — `system_cache_blocks` —
+ * for composing a system message that gets explicit cache markers
+ * (cachePoint on Bedrock, cache_control on Anthropic) at consumer-defined
+ * boundaries. The library encodes each entry into the right wire format
+ * for the active provider; consumers decide what content to put in each
+ * block.
+ *
+ * Why this is generic rather than ranger-specific
+ * ------------------------------------------------
+ * Earlier iterations exposed `platform_instructions` and `cache_ttl:
+ * { platform, agent }` — vocabulary borrowed from a multi-tenant chat
+ * platform's mental model. That leaked a specific consumer's domain into
+ * the library and made it confusing for other consumers (CLI tools,
+ * desktop apps, gateways) which have no notion of "platforms" or "agents".
+ *
+ * The current shape lets every consumer define their own cache-tier
+ * organization without the library knowing or caring.
+ *
+ * Cache key composition
+ * ---------------------
+ * Both Anthropic and Bedrock hash the message bytes leading up to each
+ * cache marker. So entry N's cache key is the concatenation of bytes
+ * 0..N. Stable content (universal rules, framework docs) goes earlier;
+ * volatile content (per-agent identity, per-tool docs) goes later. The
+ * earlier entries get cross-tenant cache hits; the later entries get
+ * narrower hits.
+ *
+ * Provider budget
+ * ---------------
+ * Bedrock's Converse API supports up to 4 cachePoint blocks per request.
+ * The default tools-array cache strategy (see `IllumaBedrockConverse`)
+ * uses up to 2 of those. So at most 2 entries should appear in
+ * `system_cache_blocks` to leave budget for the trailing
+ * `instructions` block. The library throws on more than 2.
+ *
+ * Anthropic supports up to 4 cache breakpoints per request workspace-wide;
+ * the same constraint applies to keep tools + system within budget.
+ */
+/** Provider TTL hint applied to a cachePoint / cache_control marker. */
+export type AgentCacheTTL = '5m' | '1h';
+/**
+ * One cacheable system content block. Each entry produces a text block
+ * followed by a provider-specific cache marker in the assembled system
+ * message. Entries are emitted in array order — earlier = more stable
+ * = wider cache key.
+ */
+export interface SystemCacheBlock {
+    /**
+     * Text payload. Caller is responsible for keeping this byte-stable
+     * across requests that should share a cache entry. ANY change to
+     * these bytes invalidates every cache key that includes this entry.
+     */
+    text: string;
+    /**
+     * Optional TTL hint for the cache marker. Defaults to '5m' when
+     * omitted. '1h' costs more to write (2× base vs 1.25×) but survives
+     * longer idle, which is the right tradeoff for low-traffic blocks.
+     */
+    ttl?: AgentCacheTTL;
+}
+/**
+ * Maximum number of `system_cache_blocks` entries the library accepts.
+ * Higher than this would exceed Bedrock's 4-cachePoint budget once the
+ * tools array and trailing `instructions` block are counted.
+ */
+export declare const MAX_SYSTEM_CACHE_BLOCKS = 2;

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

@@ -4,12 +4,13 @@ import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolApprovalConfig } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolApprovalConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 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>>;
@@ -53,7 +54,7 @@ export type MultiAgentGraphState = BaseGraphState & {
 };
 export type IState = BaseGraphState;
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | {
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SubagentUpdateEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -261,9 +262,12 @@ export type GraphEdge = {
     /** Can return boolean or specific destination(s) */
     condition?: (state: BaseGraphState) => boolean | string | string[];
     /**
-     * EdgeType.HANDOFF — true agent handoff, parent calls child inline and gets result back.
-     * EdgeType.TRANSFER — one-way transfer, parent exits and child takes over.
-     * EdgeType.SEQUENCE — fixed graph edges for sequential/parallel transitions.
+     * 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 upstream's handoff semantics.
+     * EdgeType.DIRECT — fixed graph edges for automatic sequential / parallel
+     *   transitions. Ranger preserves its enriched wiring (fan-in with prompt,
+     *   parallel groups, ApprovalGateNode, excludeResults / agentMessages).
      */
     edgeType?: import('@/common').EdgeType;
     /**
@@ -288,19 +292,6 @@ export type GraphEdge = {
      * For handoff edges: Customizes the parameter name for the handoff instruction input.
      */
     promptKey?: string;
-    /**
-     * For handoff edges: Maximum characters for the result returned to the parent.
-     * Uses head/tail truncation (60/40 split) to preserve key findings and conclusions.
-     * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
-     */
-    maxResultChars?: number;
-    /**
-     * For handoff edges: When true, the child agent receives the full parent
-     * conversation history plus the orchestrator's instructions appended.
-     * When false (default), the child only receives the orchestrator's scoped
-     * instructions — isolated from the parent conversation.
-     */
-    passthrough?: boolean;
     /**
      * Approval gate configuration for sequence edges.
      * When set, inserts an approval gate node between source and destination.
@@ -311,12 +302,15 @@ export type GraphEdge = {
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
     /**
-     * When set, the graph routes START to this agent instead of the default starting nodes.
-     * Used for multi-turn resumption: the caller reads `lastActiveAgentId` from the
-     * previous turn's metadata and passes it here so follow-up messages route to the
+     * When set, the graph routes START to this agent instead of the default
+     * starting nodes. Used for multi-turn resumption: the caller reads the
+     * last active agent id from the previous turn (e.g. via
+     * `Run.getLastActiveAgentId()`, which derives it from the run's content
+     * data trail) and passes it here so follow-up messages route to the
      * agent that last handled the conversation.
      *
-     * If the agent ID is invalid (not in the graph), falls back to default starting nodes.
+     * If the agent ID is invalid (not in the graph), falls back to default
+     * starting nodes.
      */
     resumeFromAgentId?: string;
 };
@@ -463,6 +457,22 @@ export interface SummarizationConfig {
      * while persistedSummary is loaded from the conversation's own history.
      */
     initialSummary?: string;
+    /**
+     * 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.
+     */
+    provider?: Providers;
+    model?: string;
+    parameters?: Record<string, unknown>;
+    prompt?: string;
+    updatePrompt?: string;
+    trigger?: {
+        type: string;
+        value: number;
+    };
+    maxSummaryTokens?: number;
 }
 /**
  * Runtime state for EMA-based pruning calibration.
@@ -493,6 +503,61 @@ export interface FileManifestEntry {
     /** Index of the message that introduced this file (0-based in the original message array) */
     messageIndex?: number;
 }
+/** Configuration for a subagent type that can be spawned by a parent agent. */
+export type SubagentConfig = {
+    /** Identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
+    type: string;
+    /** Human-readable display name. */
+    name: string;
+    /** What this subagent specializes in — shown to the LLM. */
+    description: string;
+    /** Full agent config for the child graph. Omit when `self` is true. */
+    agentInputs?: AgentInputs;
+    /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
+    self?: boolean;
+    /** Max AGENT→TOOLS cycles before forced stop (default: 25). */
+    maxTurns?: number;
+    /** Allow this subagent to spawn its own subagents (default: false). */
+    allowNested?: boolean;
+};
+/** SubagentConfig with agentInputs guaranteed present (self-spawn resolved). */
+export type ResolvedSubagentConfig = SubagentConfig & {
+    agentInputs: AgentInputs;
+};
+/** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+/**
+ * Wrapper event emitted when a subagent's child graph dispatches activity.
+ * Lets hosts show subagent progress in a UI surface separate from the parent
+ * conversation without having to untangle events by agent ID.
+ */
+export interface SubagentUpdateEvent {
+    /** Parent run ID. */
+    runId: string;
+    /** Child run ID (unique per subagent execution). */
+    subagentRunId: string;
+    /**
+     * Parent-side `tool_call_id` for the `subagent` tool invocation that
+     * triggered this run. Stable for the duration of the child; lets hosts
+     * correlate updates deterministically instead of inferring by ordering.
+     * Omitted when the executor was invoked outside of a tool-call context.
+     */
+    parentToolCallId?: string;
+    /** Subagent `type` identifier from the SubagentConfig. */
+    subagentType: string;
+    /** Child agent ID assigned to this subagent execution. */
+    subagentAgentId: string;
+    /** Parent agent ID that spawned this subagent. */
+    parentAgentId?: string;
+    /** Lifecycle phase carried by this update. */
+    phase: SubagentUpdatePhase;
+    /** Underlying event payload (shape depends on phase). */
+    data?: unknown;
+    /** Short human-readable description. Hosts can render this directly. */
+    label?: string;
+    /** ISO timestamp for ordering / display. */
+    timestamp: string;
+}
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -503,12 +568,67 @@ 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';
+    /**
+     * Subagent types this agent may spawn. When non-empty, Graph injects the
+     * `subagent` tool into the agent's toolset with the per-config enum and
+     * description populated.
+     */
+    subagentConfigs?: SubagentConfig[];
+    /**
+     * Maximum subagent depth allowed below this agent. Used by SubagentExecutor
+     * to abort runaway nesting. Defaults to a small constant.
+     */
+    maxSubagentDepth?: number;
+    /**
+     * Pre-existing summary injected into the system message via
+     * AgentContext.buildInstructionsString. Populated by SubagentExecutor when
+     * spawning a self-config subagent that should inherit the parent's prior
+     * compaction summary; otherwise host-supplied at run time.
+     */
+    initialSummary?: {
+        text: string;
+        tokenCount: number;
+    };
+    /**
+     * 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 in Ranger to preserve prior
+     * behaviour); hosts that want strict opt-in semantics should set it
+     * explicitly.
+     */
+    summarizationEnabled?: boolean;
     /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
     useLegacyContent?: boolean;
     /**
@@ -585,3 +705,23 @@ export interface AgentInputs {
      */
     fileManifest?: FileManifestEntry[];
 }
+/**
+ * Tunable knobs for position-based content degradation.
+ * See `messages/contextPruning.ts` and `messages/contextPruningSettings.ts`.
+ */
+export interface ContextPruningConfig {
+    enabled?: boolean;
+    keepLastAssistants?: number;
+    softTrimRatio?: number;
+    hardClearRatio?: number;
+    minPrunableToolChars?: number;
+    softTrim?: {
+        maxChars?: number;
+        headChars?: number;
+        tailChars?: number;
+    };
+    hardClear?: {
+        enabled?: boolean;
+        placeholder?: string;
+    };
+}

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

@@ -1,5 +1,8 @@
+export * from './agent-cache';
 export * from './graph';
 export * from './llm';
+export * from './messages';
 export * from './run';
 export * from './stream';
 export * from './tools';
+export * from './skill';

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

@@ -2,3 +2,29 @@ import type Anthropic from '@anthropic-ai/sdk';
 import type { BaseMessage } from '@langchain/core/messages';
 export type AnthropicMessages = Array<AnthropicMessage | BaseMessage>;
 export type AnthropicMessage = Anthropic.MessageParam;
+/**
+ * Per-message ref metadata stamped onto a `ToolMessage` at execution time
+ * (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.
+ *
+ * Lives in `ToolMessage.additional_kwargs`. LangChain's provider
+ * serializers don't transmit `additional_kwargs` to provider APIs, so the
+ * metadata never leaks even if you forget to clean it.
+ */
+export interface ToolMessageRefMetadata {
+    /** Key under which this message's untruncated output was registered. */
+    _refKey?: string;
+    /**
+     * Registry bucket scope under which `_refKey` was stored. For named runs
+     * this equals `config.configurable.run_id`; for anonymous invocations
+     * (no `run_id`) ToolNode mints a per-batch synthetic scope
+     * (`\0anon-<n>`) so concurrent batches don't collide. Stamping the
+     * scope on the message itself lets `annotateMessagesForLLM` recover it
+     * without re-deriving from config — which is impossible for the
+     * anonymous case, since the scope is internal to ToolNode.
+     */
+    _refScope?: string;
+    /** Placeholders the model used that could not be resolved this batch. */
+    _unresolvedRefs?: string[];
+}

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

@@ -7,6 +7,7 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { HookRegistry } from '@/hooks';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
     llmConfig: l.LLMConfig;
@@ -61,7 +62,9 @@ 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 {
@@ -106,6 +109,25 @@ export type RunConfig = {
     runId: string;
     graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
     customHandlers?: Record<string, g.EventHandler>;
+    /**
+     * Optional {@link HookRegistry} that wires host-defined hook callbacks
+     * (PreToolUse / PostToolUse / PreCompact / etc.) into this run.
+     *
+     * Hooks fire synchronously inside ToolNode and processStream; returning
+     * `deny` from a PreToolUse hook short-circuits the tool call. Lifetime
+     * is per-run — the host should construct a fresh registry (or reuse a
+     * shared one) and dispose of it together with the conversation block
+     * to prevent leaks.
+     */
+    hooks?: HookRegistry;
+    /**
+     * 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.
+     * Defaults to disabled (registry not constructed).
+     */
+    toolOutputReferences?: import('@/types/tools').ToolOutputReferencesConfig;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;

package/dist/types/types/skill.d.ts

@@ -0,0 +1,9 @@
+/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
+export type SkillCatalogEntry = {
+    /** Kebab-case identifier (what the model passes to SkillTool) */
+    name: string;
+    /** One-line description for the catalog listing */
+    description: string;
+    /** Optional human-readable label (UI only, not shown to model) */
+    displayTitle?: string;
+};

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

@@ -1,6 +1,7 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { MessageContentComplex } from '@langchain/core/messages';
 import type { ToolErrorData } from './stream';
 import { EnvVar, ExecutionContext } from '@/common';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
@@ -50,6 +51,35 @@ export type ToolNodeOptions = {
      * When provided, tools matching the policy will call interrupt() before execution.
      */
     toolApprovalConfig?: ToolApprovalConfig;
+    /**
+     * Optional hook registry threaded down from Run. When set, ToolNode
+     * fires PreToolUse / PostToolUse / PostToolUseFailure / PermissionDenied
+     * lifecycle events through executeHooks during event-driven dispatch.
+     */
+    hookRegistry?: import('@/hooks').HookRegistry;
+    /**
+     * 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. 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 (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
+     * registry wins).
+     */
+    toolOutputReferences?: ToolOutputReferencesConfig;
+    /**
+     * Pre-constructed registry instance shared across ToolNodes for the run.
+     * Graphs pass the same registry to every ToolNode they compile so
+     * cross-agent `{{tool<i>turn<n>}}` substitutions resolve. Takes
+     * precedence over `toolOutputReferences` when both are set.
+     */
+    toolOutputRegistry?: import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -73,12 +103,35 @@ export type CodeExecutionToolParams = undefined | {
     files?: CodeEnvFile[];
     [EnvVar.CODE_API_KEY]?: string;
 };
+/**
+ * Bash execution tool params. Same shape as CodeExecutionToolParams —
+ * BashExecutor reuses the /exec endpoint with `lang: 'bash'`.
+ */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+/**
+ * Read-file tool params. Resolution of the `file_path` to actual bytes is
+ * delegated to a host-supplied resolver in `RunConfig` (skill files, code
+ * exec session files, etc.).
+ */
+export type ReadFileToolParams = undefined | {
+    apiKey?: string;
+    [EnvVar.CODE_API_KEY]?: string;
+};
 export type FileRef = {
     id: string;
     name: string;
     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 = {
@@ -158,6 +211,26 @@ export type ToolExecuteBatchRequest = {
     /** Promise rejector - handler calls this on fatal error */
     reject: (error: Error) => void;
 };
+/**
+ * Generic message-injection envelope used by SkillTool, hooks, and any other
+ * tool execution handler that needs to push extra context into graph state
+ * after the ToolMessage. The host's message formatter is responsible for
+ * placement and any per-provider merging rules.
+ */
+export type InjectedMessage = {
+    /** 'user' for skill body injection, 'system' for context hints.
+     *  Both are converted to HumanMessage at runtime; the original role
+     *  is preserved in additional_kwargs.role. */
+    role: 'user' | 'system';
+    /** Message content: string for simple text, array for complex multi-part content */
+    content: string | MessageContentComplex[];
+    /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+    isMeta?: boolean;
+    /** Origin tag for downstream consumers (UI, pruner, compaction) */
+    source?: 'skill' | 'hook' | 'system';
+    /** Only set when source is 'skill', for compaction preservation */
+    skillName?: string;
+};
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
     /** Matches ToolCallRequest.id */
@@ -170,9 +243,41 @@ export type ToolExecuteResult = {
     status: 'success' | 'error';
     /** Error message if status is 'error' */
     errorMessage?: string;
+    /**
+     * Messages to inject into graph state after the ToolMessage for this call.
+     * Placed after tool results to respect provider message ordering
+     * (tool_call -> tool_result adjacency). The host's message formatter may
+     * merge injected user messages with the preceding tool_result turn.
+     * Generic mechanism: any tool execution handler can use this.
+     */
+    injectedMessages?: InjectedMessage[];
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
+/**
+ * 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
+ * into a subsequent tool's args via the literal placeholder
+ * `{{tool<idx>turn<turn>}}`. Substitution happens immediately before tool
+ * invocation; the LLM-visible ToolMessage.content is annotated with a
+ * `_ref` JSON field or a `[ref: tool<idx>turn<turn>]` prefix so the model
+ * knows which key the output is stored under.
+ *
+ * Disabled by default. Hosts that want to opt in pass
+ * `toolOutputReferences: { enabled: true }` on RunConfig and (optionally)
+ * append the bash tool's tool-output-references guide to the bash tool
+ * description so the LLM learns the substitution syntax.
+ */
+export type ToolOutputReferencesConfig = {
+    /** Enable the registry and placeholder substitution. Defaults to `false`. */
+    enabled?: boolean;
+    /** Maximum characters stored (and substituted) per registered output. */
+    maxOutputSize?: number;
+    /** Hard cap on total characters retained across all registered outputs for the run. */
+    maxTotalSize?: number;
+};
 export type ProgrammaticCache = {
     toolMap: ToolMap;
     toolDefs: LCTool[];
@@ -389,6 +494,12 @@ export type ProgrammaticToolCallingParams = {
     /** Environment variable key for API key */
     [key: string]: unknown;
 };
+/**
+ * Initialization parameters for the BashPTC tool. Same shape as
+ * {@link ProgrammaticToolCallingParams}; the bash variant just runs
+ * generated code through `lang: 'bash'` instead of `lang: 'python'`.
+ */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
 /**
  * Tracks code execution session state for automatic file persistence.
  * Stored in Graph.sessions and injected into subsequent tool invocations.

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

@@ -13,6 +13,4 @@ export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
 export * from './fileManifest';
 export * from './errors';
-export * from './httpClient';
-export * from './credentials';
-export * from './toolManifest';
+export * from './truncation';

package/dist/types/utils/truncation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Ingestion-time and pre-flight truncation utilities for tool results.
+ *
+ * Prevents oversized tool outputs from entering the message array and
+ * consuming the entire context window.
+ */
+/**
+ * Absolute hard cap on tool result length (characters).
+ * Even if the model has a 1M-token context, a single tool result
+ * larger than this is almost certainly a bug (e.g., dumping a binary file).
+ */
+export declare const HARD_MAX_TOOL_RESULT_CHARS = 400000;
+/**
+ * Absolute hard cap on the aggregate size (characters) of all registered
+ * tool outputs kept for `{{tool<i>turn<n>}}` substitution. Set at 5 MB
+ * because the registry stores *raw, untruncated* tool output — full
+ * fidelity for piping into downstream bash/jq — so the budget needs
+ * enough headroom to keep a handful of large responses without
+ * ballooning unbounded.
+ */
+export declare const HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE = 5000000;
+/**
+ * Computes the dynamic max tool result size based on the model's context window.
+ * Uses 30% of the context window (in estimated characters, ~4 chars/token)
+ * capped at HARD_MAX_TOOL_RESULT_CHARS.
+ *
+ * @param contextWindowTokens - The model's max context tokens (optional).
+ * @returns Maximum allowed characters for a single tool result.
+ */
+export declare function calculateMaxToolResultChars(contextWindowTokens?: number): number;
+/**
+ * Computes the default aggregate size (characters) for the tool output
+ * reference registry based on the per-output budget. Mirrors
+ * `calculateMaxToolResultChars`'s shape: a multiple of the per-output
+ * cap, clamped to `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE`.
+ *
+ * @param maxOutputSize - Per-output maximum characters (e.g., the
+ *   ToolNode's `maxToolResultChars`). When omitted or non-positive,
+ *   falls back to the absolute total cap.
+ * @returns Maximum total characters retained across the registry.
+ */
+export declare function calculateMaxTotalToolOutputSize(maxOutputSize?: number): number;
+/**
+ * Truncates a tool-call input (the arguments/payload of a tool_use block)
+ * using head+tail strategy. Returns an object with `_truncated` (the
+ * truncated string) and `_originalChars` (for diagnostics).
+ *
+ * Accepts any type — objects are JSON-serialized before truncation.
+ *
+ * @param input - The tool input (string, object, etc.).
+ * @param maxChars - Maximum allowed characters.
+ */
+export declare function truncateToolInput(input: unknown, maxChars: number): {
+    _truncated: string;
+    _originalChars: number;
+};
+/**
+ * Truncates tool result content that exceeds `maxChars` using a head+tail
+ * strategy. Keeps the beginning (structure/headers) and end (return value /
+ * conclusion) of the content so the model retains both the opening context
+ * and the final outcome.
+ *
+ * Head gets ~70% of the budget, tail gets ~30%. Falls back to head-only
+ * when the budget is too small for a meaningful tail.
+ *
+ * @param content - The tool result string content.
+ * @param maxChars - Maximum allowed characters.
+ * @returns The (possibly truncated) content string.
+ */
+export declare function truncateToolResultContent(content: string, maxChars: number): string;