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

package/src/types/agent-cache.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 const MAX_SYSTEM_CACHE_BLOCKS = 2;

package/src/types/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AA4YA;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAClC;IAAnB,YAAmB,WAAmB;QACpC,KAAK,CAAC,+CAA+C,WAAW,EAAE,CAAC,CAAC;QADnD,gBAAW,GAAX,WAAW,CAAQ;QAEpC,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACpC;IAAnB,YAAmB,UAAkB;QACnC,KAAK,CACH,iDAAiD,UAAU,KAAK;YAC9D,sEAAsE,CACzE,CAAC;QAJe,eAAU,GAAV,UAAU,CAAQ;QAKnC,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF"}

package/src/types/graph.test.js.map

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

package/src/types/graph.ts

@@ -24,6 +24,7 @@ import type {
   GenericTool,
   LCTool,
   ToolApprovalConfig,
+  ToolExecuteBatchRequest,
 } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
@@ -35,6 +36,7 @@ import type {
   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 {
@@ -109,6 +111,8 @@ export interface EventHandler {
       | RunStepDeltaEvent
       | MessageDeltaEvent
       | ReasoningDeltaEvent
+      | SubagentUpdateEvent
+      | ToolExecuteBatchRequest
       | { result: ToolEndEvent },
     metadata?: Record<string, unknown>,
     graph?: StandardGraph | MultiAgentGraph
@@ -383,9 +387,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;
   /**
@@ -415,19 +422,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.
@@ -439,12 +433,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;
 };
@@ -618,6 +615,20 @@ 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;
 }
 
 /**
@@ -651,6 +662,73 @@ export interface FileManifestEntry {
   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. */
@@ -661,12 +739,64 @@ 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;
   /**
@@ -745,3 +875,24 @@ 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/src/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/src/types/index.ts

@@ -1,6 +1,9 @@
 // src/types/index.ts
+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/src/types/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["llm.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/src/types/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["messages.ts"],"names":[],"mappings":""}

package/src/types/messages.ts

@@ -2,3 +2,30 @@ 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/src/types/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["run.ts"],"names":[],"mappings":""}

package/src/types/run.ts

@@ -11,6 +11,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';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
@@ -73,7 +74,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;
 }
 
@@ -118,6 +121,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/src/types/skill.ts

@@ -0,0 +1,11 @@
+// src/types/skill.ts
+
+/** 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/src/types/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["stream.ts"],"names":[],"mappings":"AAaA,OAAO,EAA2B,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/src/types/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["tools.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/src/types/tools.ts

@@ -2,6 +2,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';
 
@@ -60,6 +61,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;
@@ -90,12 +120,39 @@ export type CodeExecutionToolParams =
       [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[];
@@ -190,6 +247,27 @@ export type ToolExecuteBatchRequest = {
   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 */
@@ -202,11 +280,44 @@ 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[] };
 
 // ============================================================================
@@ -456,6 +567,13 @@ export type ProgrammaticToolCallingParams = {
   [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;
+
 // ============================================================================
 // Tool Session Context Types
 // ============================================================================