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

package/src/types/agent-cache.ts

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

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,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;
   /**
@@ -415,19 +423,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 +434,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 +616,20 @@ 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;
 }
 
 /**
@@ -651,6 +663,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 +740,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 };
+  /**
+   * 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;
   /**
@@ -745,3 +876,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.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/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
+ * (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.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 (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/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. —
+   * downstream consumers may drive truncation through other knobs;
+   * accepting this option keeps the test surface portable.
+   */
+  maxToolResultChars?: number;
+  /**
+   * Run-scoped tool output reference configuration (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 (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
 // ============================================================================

package/src/utils/__tests__/truncation.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  HARD_MAX_TOOL_RESULT_CHARS,
+  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
+  calculateMaxToolResultChars,
+  calculateMaxTotalToolOutputSize,
+} from '@/utils/truncation';
+
+describe('truncation helpers', () => {
+  describe('calculateMaxToolResultChars', () => {
+    it('returns the hard cap when context tokens are missing', () => {
+      expect(calculateMaxToolResultChars()).toBe(HARD_MAX_TOOL_RESULT_CHARS);
+      expect(calculateMaxToolResultChars(undefined)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+      expect(calculateMaxToolResultChars(0)).toBe(HARD_MAX_TOOL_RESULT_CHARS);
+      expect(calculateMaxToolResultChars(-100)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+    });
+
+    it('computes 30% of context-window characters for normal inputs', () => {
+      // 100k tokens * 0.3 = 30k tokens * 4 chars/token = 120k chars
+      expect(calculateMaxToolResultChars(100_000)).toBe(120_000);
+    });
+
+    it('clamps to the hard cap for large context windows', () => {
+      // 1M tokens * 0.3 * 4 = 1.2M chars, exceeds 400k cap
+      expect(calculateMaxToolResultChars(1_000_000)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+    });
+  });
+
+  describe('calculateMaxTotalToolOutputSize', () => {
+    it('returns the absolute hard cap when no per-output is provided', () => {
+      expect(calculateMaxTotalToolOutputSize()).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      expect(calculateMaxTotalToolOutputSize(0)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      expect(calculateMaxTotalToolOutputSize(-1)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+    });
+
+    it('doubles the per-output cap by default', () => {
+      expect(calculateMaxTotalToolOutputSize(100_000)).toBe(200_000);
+      expect(calculateMaxTotalToolOutputSize(1)).toBe(2);
+    });
+
+    it('clamps the doubled value to HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE', () => {
+      // 4M * 2 = 8M, exceeds 5M
+      expect(calculateMaxTotalToolOutputSize(4_000_000)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      // Right at the boundary: 2.5M * 2 = 5M (no clamp).
+      expect(calculateMaxTotalToolOutputSize(2_500_000)).toBe(5_000_000);
+      // Just past it: 2_500_001 * 2 = 5_000_002 -> clamped.
+      expect(calculateMaxTotalToolOutputSize(2_500_001)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+    });
+  });
+});

package/src/utils/index.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';