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

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

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

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

@@ -0,0 +1,71 @@
+/**
+ * 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 tier-named
+ * ------------------------------------------------
+ * Earlier iterations exposed `platform_instructions` and `cache_ttl:
+ * { platform, agent }` — vocabulary borrowed from a specific consumer's
+ * multi-tenant chat-platform mental model. That leaked one 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,13 @@ 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 the standard 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).
      */
     edgeType?: import('@/common').EdgeType;
     /**
@@ -288,19 +293,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 +303,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 +458,22 @@ export interface SummarizationConfig {
      * while persistedSummary is loaded from the conversation's own history.
      */
     initialSummary?: string;
+    /**
+     * 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 +504,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 +569,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;
+    };
+    /**
+     * 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
+     * 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 +706,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
+ * (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 (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;
+};