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

package/dist/types/hooks/types.d.ts

@@ -0,0 +1,320 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Closed set of hook lifecycle events supported by the hooks system.
+ *
+ * These mirror the subset of Claude Code's event surface that makes sense
+ * for a library context (no filesystem/CLI-specific events). See
+ * `docs/hooks-design-report.md` §3.2 for the mapping to existing
+ * `@librechat/agents` emission points.
+ */
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
+export type ToolDecision = 'allow' | 'deny' | 'ask';
+/** Stop-loop decision; `block` means "do not stop, run another turn". Any `block` wins. */
+export type StopDecision = 'continue' | 'block';
+/**
+ * Fields shared by every `HookInput`. Discriminated by `hook_event_name`.
+ *
+ * - `runId` identifies the current agent run and is always present.
+ * - `threadId` identifies the conversation thread when the host has one.
+ * - `agentId` is only set when the hook fires inside a subagent scope.
+ */
+export interface BaseHookInput {
+    runId: string;
+    threadId?: string;
+    agentId?: string;
+}
+export interface RunStartHookInput extends BaseHookInput {
+    hook_event_name: 'RunStart';
+    messages: BaseMessage[];
+}
+export interface UserPromptSubmitHookInput extends BaseHookInput {
+    hook_event_name: 'UserPromptSubmit';
+    prompt: string;
+    attachments?: BaseMessage[];
+}
+/**
+ * Fires before a tool is invoked. Hook may return `deny`/`ask`/`allow` and/or
+ * an `updatedInput` that replaces the tool arguments before invocation.
+ *
+ * `toolInput` is intentionally typed as `Record<string, unknown>` because the
+ * SDK is tool-agnostic — concrete tool argument shapes are only known at the
+ * call site and are narrowed by the host. This is the one escape hatch in
+ * the hook type system.
+ */
+export interface PreToolUseHookInput extends BaseHookInput {
+    hook_event_name: 'PreToolUse';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    stepId?: string;
+    /**
+     * Number of times this tool has been invoked in prior batches within the
+     * current run. Within a single batch of parallel calls, all calls to the
+     * same tool share the same turn value — per-call discrimination within a
+     * batch is not supported in v1.
+     */
+    turn?: number;
+}
+export interface PostToolUseHookInput extends BaseHookInput {
+    hook_event_name: 'PostToolUse';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolOutput: unknown;
+    toolUseId: string;
+    stepId?: string;
+    turn?: number;
+}
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    hook_event_name: 'PostToolUseFailure';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    error: string;
+    stepId?: string;
+    turn?: number;
+}
+export interface PermissionDeniedHookInput extends BaseHookInput {
+    hook_event_name: 'PermissionDenied';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    reason: string;
+}
+export interface SubagentStartHookInput extends BaseHookInput {
+    hook_event_name: 'SubagentStart';
+    parentAgentId?: string;
+    agentId: string;
+    agentType: string;
+    inputs: BaseMessage[];
+}
+export interface SubagentStopHookInput extends BaseHookInput {
+    hook_event_name: 'SubagentStop';
+    agentId: string;
+    agentType: string;
+    messages: BaseMessage[];
+}
+export interface StopHookInput extends BaseHookInput {
+    hook_event_name: 'Stop';
+    messages: BaseMessage[];
+    stopReason?: string;
+    stopHookActive: boolean;
+}
+export interface StopFailureHookInput extends BaseHookInput {
+    hook_event_name: 'StopFailure';
+    error: string;
+    lastAssistantMessage?: BaseMessage;
+}
+export interface PreCompactHookInput extends BaseHookInput {
+    hook_event_name: 'PreCompact';
+    messagesBeforeCount: number;
+    /**
+     * What triggered compaction. Matches `SummarizationTrigger.type` from the
+     * agent's summarization config. `'default'` means no trigger was
+     * configured and compaction fired because messages were pruned.
+     */
+    trigger: 'token_ratio' | 'remaining_tokens' | 'messages_to_refine' | 'default' | (string & {});
+}
+export interface PostCompactHookInput extends BaseHookInput {
+    hook_event_name: 'PostCompact';
+    summary: string;
+    /**
+     * Number of messages remaining after compaction. The summarize node
+     * returns a `removeAll` signal that clears all messages from state;
+     * the summary itself is injected into the system prompt, not as a
+     * message. This is `0` at the point of hook dispatch.
+     */
+    messagesAfterCount: number;
+}
+/** Discriminated union of every hook input shape. */
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+/** Compile-time map from event name to its input shape. */
+export type HookInputByEvent = {
+    RunStart: RunStartHookInput;
+    UserPromptSubmit: UserPromptSubmitHookInput;
+    PreToolUse: PreToolUseHookInput;
+    PostToolUse: PostToolUseHookInput;
+    PostToolUseFailure: PostToolUseFailureHookInput;
+    PermissionDenied: PermissionDeniedHookInput;
+    SubagentStart: SubagentStartHookInput;
+    SubagentStop: SubagentStopHookInput;
+    Stop: StopHookInput;
+    StopFailure: StopFailureHookInput;
+    PreCompact: PreCompactHookInput;
+    PostCompact: PostCompactHookInput;
+};
+/**
+ * Fields common to every hook output. Hooks that have nothing to say simply
+ * return `{}` (or omit the fields below).
+ */
+export interface BaseHookOutput {
+    /** Context string to inject into the conversation. Accumulated across hooks. */
+    additionalContext?: string;
+    /** True to prevent the next model turn. Any hook can set this. */
+    preventContinuation?: boolean;
+    /** Reason reported alongside `preventContinuation`. */
+    stopReason?: string;
+}
+export type RunStartHookOutput = BaseHookOutput;
+export interface UserPromptSubmitHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+}
+export interface PreToolUseHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+    /**
+     * Replacement tool input. Merged into the pending tool call by the host.
+     *
+     * When multiple hooks set `updatedInput` within a single `executeHooks`
+     * call, the last writer in registration order wins (outer loop: matcher
+     * registration order; inner loop: hook position within the matcher). The
+     * winner is deterministic — `Promise.all` preserves input-array order.
+     * Consumers that need a single authoritative rewrite should still scope
+     * `updatedInput` to one hook per matcher to avoid confusing precedence.
+     */
+    updatedInput?: Record<string, unknown>;
+}
+export interface PostToolUseHookOutput extends BaseHookOutput {
+    /**
+     * Replacement tool output. Flows through the aggregated result so the
+     * host can substitute it before appending the tool result message.
+     * Ordering semantics match `PreToolUseHookOutput.updatedInput`:
+     * last-writer-wins in registration order.
+     */
+    updatedOutput?: unknown;
+}
+export type PostToolUseFailureHookOutput = BaseHookOutput;
+export type PermissionDeniedHookOutput = BaseHookOutput;
+export interface SubagentStartHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+}
+export type SubagentStopHookOutput = BaseHookOutput;
+export interface StopHookOutput extends BaseHookOutput {
+    decision?: StopDecision;
+    reason?: string;
+}
+export type StopFailureHookOutput = BaseHookOutput;
+export type PreCompactHookOutput = BaseHookOutput;
+export type PostCompactHookOutput = BaseHookOutput;
+/** Compile-time map from event name to its output shape. */
+export type HookOutputByEvent = {
+    RunStart: RunStartHookOutput;
+    UserPromptSubmit: UserPromptSubmitHookOutput;
+    PreToolUse: PreToolUseHookOutput;
+    PostToolUse: PostToolUseHookOutput;
+    PostToolUseFailure: PostToolUseFailureHookOutput;
+    PermissionDenied: PermissionDeniedHookOutput;
+    SubagentStart: SubagentStartHookOutput;
+    SubagentStop: SubagentStopHookOutput;
+    Stop: StopHookOutput;
+    StopFailure: StopFailureHookOutput;
+    PreCompact: PreCompactHookOutput;
+    PostCompact: PostCompactHookOutput;
+};
+/** Superset output shape used by the executor's fold loop. */
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+/**
+ * A hook callback is a plain async function registered against a specific
+ * event. The `signal` is always supplied by `executeHooks` and combines the
+ * batch's parent signal with the per-hook timeout — callbacks that perform
+ * long-running work should observe it.
+ */
+export type HookCallback<E extends HookEvent = HookEvent> = (input: HookInputByEvent[E], signal: AbortSignal) => HookOutputByEvent[E] | Promise<HookOutputByEvent[E]>;
+/**
+ * A matcher groups one or more callbacks under a shared regex filter and
+ * shared timeout/once/internal flags. The generic `E` ties the callback
+ * types to the event the matcher is registered against.
+ */
+export interface HookMatcher<E extends HookEvent = HookEvent> {
+    /**
+     * Regex pattern matched against the event's primary query string (e.g.
+     * the tool name for `PreToolUse`, the agent type for `SubagentStart`).
+     *
+     * Omitted or empty means "always match". For events that do not supply a
+     * query string (`RunStart`, `Stop`, etc.), only wildcard matchers fire —
+     * a non-empty pattern on such events will never match.
+     *
+     * Patterns are treated as trusted input: `executeHooks` compiles them
+     * with `new RegExp(pattern)` without any sandbox, and a pathological
+     * pattern can block the event loop. Host registration code is expected
+     * to validate or length-bound patterns that originate from user input.
+     */
+    pattern?: string;
+    /** Callbacks that fire when the matcher hits. Executed in parallel. */
+    hooks: HookCallback<E>[];
+    /** Per-matcher timeout in ms. Defaults to the executor's batch timeout. */
+    timeout?: number;
+    /**
+     * Atomically remove the matcher before its first dispatch.
+     *
+     * `executeHooks` claims `once: true` matchers synchronously — between
+     * `getMatchers` and its first `await` — so two concurrent calls cannot
+     * both dispatch the same matcher. Whichever call runs its sync prefix
+     * first wins the matcher; the other sees an empty bucket.
+     *
+     * Semantics are "at most one dispatch, ever" — if every hook in the
+     * matcher throws, the matcher is still gone. Use `once` for
+     * fire-and-forget bootstrapping (registration, telemetry, setup). Hosts
+     * that need retry semantics should register a normal matcher and
+     * self-unregister via the callback returned from `registry.register`.
+     */
+    once?: boolean;
+    /** Internal hooks are excluded from telemetry and non-fatal error logging. */
+    internal?: boolean;
+}
+/**
+ * Storage shape for matchers keyed by event. Each event's matcher list is
+ * a generic array parameterized by that event type, so lookup via
+ * `HooksByEvent[E]` preserves type-safe callback signatures.
+ */
+export type HooksByEvent = {
+    [E in HookEvent]?: HookMatcher<E>[];
+};
+/**
+ * Aggregated result of a single `executeHooks` call. Fields are populated
+ * according to the fold rules in `executeHooks.ts`.
+ */
+export interface AggregatedHookResult {
+    /** Folded tool-gating decision; `deny > ask > allow`. */
+    decision?: ToolDecision;
+    /** Folded stop decision; any `block` wins. */
+    stopDecision?: StopDecision;
+    /** Reason from the hook that set the winning decision. */
+    reason?: string;
+    /**
+     * Replacement tool input from a `PreToolUse` hook.
+     *
+     * Last-writer-wins in **registration order**: `executeHooks` uses
+     * `Promise.all`, which preserves input-array order, so the fold iterates
+     * outcomes in the same order they were pushed — outer loop over matchers
+     * as they sit in the registry, inner loop over each matcher's `hooks`
+     * array. The winner is therefore deterministic but may not match the
+     * order in which hooks actually completed. Consumers that want a single
+     * authoritative rewrite should still register one `updatedInput`-setting
+     * hook per matcher to avoid subtle precedence bugs.
+     */
+    updatedInput?: Record<string, unknown>;
+    /**
+     * Replacement tool output from a `PostToolUse` hook.
+     *
+     * Same last-writer-wins-in-registration-order semantics as
+     * `updatedInput`. Present only when at least one hook set it; `undefined`
+     * means "use the original tool output".
+     */
+    updatedOutput?: unknown;
+    /** Accumulated `additionalContext` strings from every hook, in order. */
+    additionalContexts: string[];
+    /** True if any hook returned `preventContinuation`. */
+    preventContinuation?: boolean;
+    /**
+     * Reason recorded alongside `preventContinuation`. First winner wins:
+     * once a hook sets both flags, later hooks that also set
+     * `preventContinuation` do not overwrite the reason.
+     */
+    stopReason?: string;
+    /** Error messages from hooks that threw; always present (possibly empty). */
+    errors: string[];
+}

package/dist/types/index.d.ts

@@ -7,6 +7,13 @@ export type { GuardrailTraceData, GuardrailOutcome, } from '@illuma-ai/observabi
 export * from './graphs';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BashExecutor';
+export * from './tools/BashProgrammaticToolCalling';
+export * from './tools/ReadFile';
+export * from './tools/SkillTool';
+export * from './tools/skillCatalog';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
 export * from './tools/BrowserTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
@@ -16,15 +23,7 @@ export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './tools/memory';
-export * from './tools/fileSearch';
-export * from './tools/artifacts';
-export * from './tools/proxyTool';
-export * from './providers';
-export { ContentStore, CONTENT_TTL_MS } from './content/ContentStore';
-export { ArtifactStore, sanitizeName } from './content/ArtifactStore';
-export type { S3Strategy, FileModel, Logger as ContentLogger, } from './content/ArtifactStore';
-export { interceptMcpResult, extractUiMarkers, buildCachedResponse, } from './content/mcpAutoCache';
-export type { AutoCacheContext, AutoCacheResult } from './content/mcpAutoCache';
+export * from './hooks';
 export * from './memory';
 export { MEMORY_FLUSH_SYSTEM_PROMPT } from './prompts/memoryFlushPrompt';
 export { shouldFlushMemory, runMemoryFlush, } from './graphs/phases/memoryFlushPhase';
@@ -36,6 +35,7 @@ export * from './nodes';
 export * from './common';
 export * from './utils';
 export type * from './types';
+export * from './langchain';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';
 export type { OpenRouterReasoning, OpenRouterReasoningEffort, ChatOpenRouterCallOptions, } from './llm/openrouter';

package/dist/types/langchain/google-common.d.ts

@@ -0,0 +1 @@
+export type { GoogleAIToolType } from '@langchain/google-common';

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

@@ -0,0 +1,8 @@
+export * from './messages';
+export * from './prompts';
+export * from './runnables';
+export * from './tools';
+export * from './google-common';
+export * from './language_models/chat_models';
+export * from './messages/tool';
+export * from './openai';

package/dist/types/langchain/language_models/chat_models.d.ts

@@ -0,0 +1 @@
+export type { BindToolsInput } from '@langchain/core/language_models/chat_models';

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

@@ -0,0 +1 @@
+export type { InvalidToolCall, ToolCall, ToolCallChunk, } from '@langchain/core/messages/tool';

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

@@ -0,0 +1,2 @@
+export { AIMessage, AIMessageChunk, BaseMessage, BaseMessageChunk, HumanMessage, SystemMessage, ToolMessage, getBufferString, isAIMessage, isBaseMessage, isToolMessage, } from '@langchain/core/messages';
+export type { BaseMessageFields, MessageContent, MessageContentText, MessageContentImageUrl, UsageMetadata, } from '@langchain/core/messages';

package/dist/types/langchain/openai.d.ts

@@ -0,0 +1 @@
+export type { AzureOpenAIInput } from '@langchain/openai';

package/dist/types/langchain/prompts.d.ts

@@ -0,0 +1 @@
+export { PromptTemplate } from '@langchain/core/prompts';

package/dist/types/langchain/runnables.d.ts

@@ -0,0 +1,2 @@
+export { Runnable, RunnableLambda, RunnableSequence, } from '@langchain/core/runnables';
+export type { RunnableConfig } from '@langchain/core/runnables';

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

@@ -0,0 +1,2 @@
+export { DynamicStructuredTool, StructuredTool, Tool, tool, } from '@langchain/core/tools';
+export type { StructuredToolInterface } from '@langchain/core/tools';

package/dist/types/langchain/utils/env.d.ts

@@ -0,0 +1 @@
+export { getEnvironmentVariable } from '@langchain/core/utils/env';

package/dist/types/llm/bedrock/cacheSupport.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bedrock prompt-cache model support detection.
+ * ===============================================
+ *
+ * Bedrock prompt caching (via `cachePoint` blocks) is only supported on
+ * specific model families. Other families silently reject or ignore the
+ * markers. We maintain an allowlist instead of a substring heuristic so
+ * a future model with an unfortunate name (e.g. `llama-claude-killer`)
+ * doesn't accidentally match.
+ *
+ * Consumers can extend the allowlist with `bedrockCacheModelPatterns` in
+ * `clientOptions` for proprietary or pre-release model IDs not yet in
+ * the upstream library.
+ */
+/**
+ * Default allowlist of Bedrock model ID patterns that support cachePoint.
+ * Sourced from AWS Bedrock documentation (verified against us-east-1
+ * 2026-05).
+ *
+ * Adding a new model: append a RegExp here AND add a regression test in
+ * `cacheSupport.test.ts` covering at least one full model ID for that
+ * family. Removing a model: do not remove without operator confirmation
+ * — silent removal would suddenly stop emitting cachePoint markers and
+ * regress cost savings.
+ */
+export declare const DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS: readonly RegExp[];
+/**
+ * Returns true when the given Bedrock model ID belongs to a family that
+ * supports cachePoint blocks. `additionalPatterns` lets consumers extend
+ * the allowlist for models the library doesn't know about yet.
+ *
+ * @param modelId  Bedrock model ID (e.g. `us.anthropic.claude-sonnet-4-5-20250929-v1:0`)
+ * @param additionalPatterns  Extra patterns from consumer config
+ */
+export declare function isBedrockCacheSupported(modelId: string | undefined, additionalPatterns?: readonly RegExp[]): boolean;

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

@@ -41,18 +41,65 @@ import type { ChatBedrockConverseInput } from '@langchain/aws';
  * @see https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html
  */
 export type ServiceTierType = 'priority' | 'default' | 'flex' | 'reserved';
+/**
+ * Tool cachePoint allocation strategy.
+ *
+ *   - 'single':  one cachePoint at the END of the tools array (whole array
+ *                cached as one unit). Lightest budget use (1 cachePoint).
+ *   - 'split':   split tools into groups via `toolGroupSelector`. Each
+ *                non-empty group gets its own cachePoint. Use when groups
+ *                have different volatility (e.g. stable core tools vs
+ *                volatile MCP tools). Costs more cachePoint budget.
+ *   - 'none':    no cachePoint on tools array. Use when tool definitions
+ *                change every request anyway.
+ */
+export type ToolCacheStrategy = 'single' | 'split' | 'none';
+/**
+ * Group selector for `toolCacheStrategy: 'split'`. Receives the tool name
+ * and returns a stable group key — tools with the same key are grouped
+ * together. Group order in the output array follows first-encounter order.
+ */
+export type ToolGroupSelector = (toolName: string) => string;
+/**
+ * Default group selector — puts all tools in a single group named 'core'.
+ * Equivalent to 'single' strategy but explicit. Consumers override this
+ * to enable per-source grouping (e.g. ranger uses `_mcp_` substring to
+ * separate core from MCP tools).
+ */
+export declare const DEFAULT_TOOL_GROUP_SELECTOR: ToolGroupSelector;
 /**
  * Extended input interface with additional features:
  * - promptCache: Enable Bedrock prompt caching for tool definitions
  * - applicationInferenceProfile: Use an inference profile ARN instead of model ID
  * - serviceTier: Specify service tier (Priority, Standard, Flex, Reserved)
+ * - toolCacheStrategy: How to allocate cachePoints across tools array
+ * - toolGroupSelector: Group key resolver for the 'split' strategy
  */
 export interface IllumaBedrockConverseInput extends ChatBedrockConverseInput {
     /**
      * Enable Bedrock prompt caching for tool definitions.
-     * When true, adds cachePoint markers to tools array.
+     * When true, adds cachePoint marker(s) to tools array per
+     * `toolCacheStrategy`. Defaults to 'single'.
      */
     promptCache?: boolean;
+    /**
+     * Tool cachePoint allocation. Defaults to 'single' — one cachePoint at
+     * the end of the tools array. Set to 'split' (with `toolGroupSelector`)
+     * when different tool groups have different volatility.
+     */
+    toolCacheStrategy?: ToolCacheStrategy;
+    /**
+     * Group selector for 'split' strategy. Receives a tool name, returns
+     * a stable group key. Defaults to a one-group selector (equivalent
+     * to 'single').
+     */
+    toolGroupSelector?: ToolGroupSelector;
+    /**
+     * Additional model ID patterns to consider Bedrock-cache-supported.
+     * Defaults are in `src/llm/bedrock/cacheSupport.ts`. Use this when
+     * AWS adds a new model family before the next library release.
+     */
+    bedrockCacheModelPatterns?: readonly RegExp[];
     /**
      * Application Inference Profile ARN to use for the model.
      * For example, "arn:aws:bedrock:eu-west-1:123456789102:application-inference-profile/fm16bt65tzgx"
@@ -90,6 +137,12 @@ export declare class IllumaBedrockConverse extends ChatBedrockConverse {
     applicationInferenceProfile?: string;
     /** Service tier for model invocation */
     serviceTier?: ServiceTierType;
+    /** Tool cachePoint allocation strategy. */
+    toolCacheStrategy: ToolCacheStrategy;
+    /** Group selector for 'split' strategy. */
+    toolGroupSelector: ToolGroupSelector;
+    /** Optional consumer extensions to the cache-supported model allowlist. */
+    bedrockCacheModelPatterns?: readonly RegExp[];
     constructor(fields?: IllumaBedrockConverseInput);
     static lc_name(): string;
     /**

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

@@ -0,0 +1,42 @@
+/**
+ * Position-based context pruning for tool results.
+ *
+ * Uses position-based age: the distance of a message
+ * from the conversation end as a fraction of total messages.
+ *
+ * Two degradation levels:
+ * - Soft-trim: Keep head + tail of tool result content, drop middle.
+ * - Hard-clear: Replace entire content with a placeholder.
+ *
+ * Messages in the "protected zone" (recent assistant turns, system/pre-first-human
+ * messages, and messages with image content) are never pruned.
+ */
+import { type BaseMessage } from '@langchain/core/messages';
+import type { ContextPruningConfig } from '@/types/graph';
+import type { TokenCounter } from '@/types/run';
+import type { ContextPruningSettings } from './contextPruningSettings';
+export interface ContextPruningResult {
+    /** Number of messages that were soft-trimmed. */
+    softTrimmed: number;
+    /** Number of messages that were hard-cleared. */
+    hardCleared: number;
+}
+/**
+ * Applies position-based context pruning to tool result messages.
+ *
+ * Modifies messages in-place and updates indexTokenCountMap with recounted
+ * token values for modified messages.
+ *
+ * @param params.messages - The full message array (modified in-place).
+ * @param params.indexTokenCountMap - Token count map (updated in-place).
+ * @param params.tokenCounter - Function to recount tokens after modification.
+ * @param params.config - Partial context pruning config (merged with defaults).
+ * @returns Counts of soft-trimmed and hard-cleared messages.
+ */
+export declare function applyContextPruning(params: {
+    messages: BaseMessage[];
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+    config?: ContextPruningConfig;
+    resolvedSettings?: ContextPruningSettings;
+}): ContextPruningResult;

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

@@ -0,0 +1,44 @@
+/**
+ * Default settings for position-based context pruning.
+ *
+ * These are merged with user-provided overrides so any subset can be customized.
+ */
+export interface ContextPruningSettings {
+    /** Whether position-based pruning is enabled. Default: false (opt-in). */
+    enabled: boolean;
+    /** Number of recent assistant turns to protect from pruning. Default: 3 */
+    keepLastAssistants: number;
+    /** Age ratio (0-1) at which soft-trim fires. Default: 0.3 */
+    softTrimRatio: number;
+    /** Age ratio (0-1) at which hard-clear fires. Default: 0.5 */
+    hardClearRatio: number;
+    /** Minimum tool result size (chars) before pruning applies. Default: 50000 */
+    minPrunableToolChars: number;
+    softTrim: {
+        /** Maximum total chars after soft-trim. Default: 4000 */
+        maxChars: number;
+        /** Head portion to keep. Default: 1500 */
+        headChars: number;
+        /** Tail portion to keep. Default: 1500 */
+        tailChars: number;
+    };
+    hardClear: {
+        /** Whether hard-clear is enabled. Default: true */
+        enabled: boolean;
+        /** Placeholder text for hard-cleared content. */
+        placeholder: string;
+    };
+}
+export declare const DEFAULT_CONTEXT_PRUNING_SETTINGS: ContextPruningSettings;
+/**
+ * Merges user-provided partial overrides with the defaults.
+ */
+export declare function resolveContextPruningSettings(overrides?: Partial<{
+    enabled?: boolean;
+    keepLastAssistants?: number;
+    softTrimRatio?: number;
+    hardClearRatio?: number;
+    minPrunableToolChars?: number;
+    softTrim?: Partial<ContextPruningSettings['softTrim']>;
+    hardClear?: Partial<ContextPruningSettings['hardClear']>;
+}>): ContextPruningSettings;

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

@@ -83,6 +83,9 @@ interface LangChainMessage {
  * @returns - The formatted LangChain message.
  */
 export declare const formatFromLangChain: (message: LangChainMessage) => Record<string, any>;
+interface FormatAgentMessagesOptions {
+    provider?: Providers;
+}
 /**
  * Groups content parts by agent and formats them with agent labels
  * This preprocesses multi-agent content to prevent identity confusion
@@ -103,9 +106,14 @@ export declare const labelContentByAgent: (contentParts: MessageContentComplex[]
  * @param payload - The array of messages to format.
  * @param indexTokenCountMap - Optional map of message indices to token counts.
  * @param tools - Optional set of tool names that are allowed in the request.
+ * @param skills - Optional map of skill name to body for reconstructing skill HumanMessages.
+ *   When SkillTool is invoked, the body is injected as a HumanMessage into LangGraph state
+ *   but NOT persisted to conversation history. On follow-up runs the skill body is lost.
+ *   Pass `skills` to reconstruct the HumanMessage at the right position after each skill
+ *   ToolMessage. Upstream PRs #96 / #97.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>) => {
+export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>, options?: FormatAgentMessagesOptions) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
 };

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

@@ -7,3 +7,5 @@ export * from './content';
 export * from './tools';
 export * from './summarize';
 export * from './dedup';
+export * from './contextPruning';
+export * from './contextPruningSettings';