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

package/dist/types/memory/mmr.d.ts

@@ -1,7 +1,7 @@
 /**
  * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.
  *
- * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with
+ * Ported from a reference implementation `extensions/memory-core/src/memory/mmr.ts` with
  * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs
  * path+startLine). Behavior is identical: normalize scores, iteratively
  * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`
@@ -10,9 +10,9 @@
  * @see Carbonell & Goldstein, "The Use of MMR, Diversity-Based Reranking" (1998)
  */
 export interface MMRConfig {
-    /** Opt-in. Upstream default is false. */
+    /** Opt-in. Default is false. */
     enabled: boolean;
-    /** 0 = max diversity, 1 = max relevance. Upstream default 0.7. */
+    /** 0 = max diversity, 1 = max relevance. Default 0.7. */
     lambda: number;
 }
 export declare const DEFAULT_MMR_CONFIG: MMRConfig;

package/dist/types/memory/paths.d.ts

@@ -8,7 +8,7 @@
  *
  * ## Why a whitelist?
  *
- * Earlier upstream-faithful designs used date-keyed files
+ * Earlier historical designs used date-keyed files
  * (`memory/YYYY-MM-DD.md`), which have three problems for a persistent
  * multi-user agent:
  *

package/dist/types/memory/temporalDecay.d.ts

@@ -1,14 +1,14 @@
 /**
  * Temporal decay — Phase 2.
  *
- * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.
+ * Ported from a reference implementation `extensions/memory-core/src/memory/temporal-decay.ts`.
  * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay
  * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the
  * score is exactly halved.
  *
  * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside
  * memory/) do NOT decay — they represent durable knowledge and should stay
- * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.
+ * hot regardless of age. This mirrors the standard `isEvergreenMemoryPath`.
  *
  * Since our pgvector rows carry `createdAt`, we don't need filesystem stat
  * fallback — the row timestamp is authoritative for any file without a

package/dist/types/memory/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Autonomous memory — core types.
  *
- * Ported from upstream's memory-core pattern, adapted for Postgres + pgvector
+ * Ported from the reference implementation's memory-core pattern, adapted for Postgres + pgvector
  * and shaped so a future graph-backend layer (Graphiti, Neo4j agent-memory, etc.)
  * can be added alongside the vector store without changing the tool contracts.
  *
@@ -75,7 +75,7 @@ export interface MemorySearchOptions {
     minScore?: number;
     /**
      * Phase 2 toggles — when the backend supports them. Each is independently
-     * opt-in; all false = upstream Phase 1 behavior.
+     * opt-in; all false = Phase 1 behavior.
      */
     mmr?: {
         enabled?: boolean;
@@ -144,7 +144,7 @@ export interface MemoryConfig {
     search?: {
         maxResults?: number;
         maxInjectedChars?: number;
-        /** Phase 2 — enable MMR reranking (upstream-aligned defaults when true). */
+        /** Phase 2 — enable MMR reranking (defaults when true). */
         mmr?: {
             enabled?: boolean;
             lambda?: number;

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. 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';

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

@@ -1,6 +1,7 @@
 import { BaseMessage, UsageMetadata } from '@langchain/core/messages';
 import type { TokenCounter } from '@/types/run';
 import { ContentTypes, Providers } from '@/common';
+import type { ContextPruningConfig } from '@/types/graph';
 export type PruneMessagesFactoryParams = {
     provider?: Providers;
     maxTokens: number;
@@ -8,6 +9,15 @@ export type PruneMessagesFactoryParams = {
     tokenCounter: TokenCounter;
     indexTokenCountMap: Record<string, number | undefined>;
     thinkingEnabled?: boolean;
+    /**
+     * Optional position-based content degradation config. When `enabled: true`,
+     * tool result messages outside the protected zone (system + last N assistant
+     * turns + image content) are soft-trimmed (head + tail) once their
+     * position-age exceeds `softTrimRatio`, then hard-cleared with a placeholder
+     * once age exceeds `hardClearRatio`. Defaults disabled to preserve existing
+     * behavior — opt in per deployment.
+     */
+    contextPruningConfig?: ContextPruningConfig;
 };
 export type PruneMessagesParams = {
     messages: BaseMessage[];
@@ -27,7 +37,7 @@ export type PruningResult = {
     messagesToRefine: BaseMessage[];
     thinkingStartIndex?: number;
 };
-export declare function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, indexTokenCountMap, startType: _startType, thinkingEnabled, tokenCounter, thinkingStartIndex: _thinkingStartIndex, reasoningType, }: {
+export declare function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, indexTokenCountMap, startType: _startType, thinkingEnabled, tokenCounter, thinkingStartIndex: _thinkingStartIndex, reasoningType, instructionTokens: _instructionTokens, }: {
     messages: BaseMessage[];
     maxContextTokens: number;
     indexTokenCountMap: Record<string, number | undefined>;
@@ -36,12 +46,92 @@ export declare function getMessagesWithinTokenLimit({ messages: _messages, maxCo
     tokenCounter: TokenCounter;
     thinkingStartIndex?: number;
     reasoningType?: ContentTypes.THINKING | ContentTypes.REASONING_CONTENT;
+    /**
+     * Token overhead for instructions (system message + tool schemas + summary)
+     * that are NOT included in `messages`. When messages[0] is already a
+     * SystemMessage the budget is deducted from its indexTokenCountMap entry
+     * as before; otherwise this value is subtracted from the available budget.
+     */
+    instructionTokens?: number;
 }): PruningResult;
 export declare function checkValidNumber(value: unknown): value is number;
+/**
+ * Repairs orphan tool messages in a pruned context. Drops `ToolMessage`s whose
+ * matching `AIMessage` was pruned, and strips orphan `tool_use` content blocks
+ * (and `tool_calls` entries) from `AIMessage`s whose corresponding tool results
+ * are missing. Without this, Anthropic / Bedrock / OpenAI reject the request
+ * with a structural validation 400.
+ *
+ * Intended to run on the post-prune `context` array (not the pre-prune
+ * `allMessages`). The dropped messages are returned so the caller can append
+ * them to `messagesToRefine` for summarization fidelity.
+ */
+export declare function repairOrphanedToolMessages({ context, allMessages, tokenCounter, indexTokenCountMap, }: {
+    context: BaseMessage[];
+    allMessages: BaseMessage[];
+    tokenCounter: TokenCounter;
+    indexTokenCountMap: Record<string, number | undefined>;
+}): {
+    context: BaseMessage[];
+    reclaimedTokens: number;
+    droppedOrphanCount: number;
+    /** Messages removed from context during orphan repair.  These should be
+     *  appended to `messagesToRefine` so that summarization can still see them
+     *  (e.g. a ToolMessage whose parent AI was pruned). */
+    droppedMessages: BaseMessage[];
+};
+/**
+ * Lightweight structural cleanup: strips orphan tool_use blocks from AI messages
+ * and drops orphan ToolMessages whose AI counterpart is missing.
+ *
+ * Unlike `repairOrphanedToolMessages`, this does NOT track tokens — it is
+ * intended as a final safety net right before model invocation to prevent
+ * Anthropic / Bedrock structural validation errors.
+ *
+ * Uses duck-typing instead of `getType()` because messages at this stage
+ * may be plain objects (from LangGraph state serialization) rather than
+ * proper BaseMessage class instances.
+ *
+ * Includes a fast-path: if every tool_call has a matching tool_result and
+ * vice-versa, the original array is returned immediately with zero allocation.
+ */
+export declare function sanitizeOrphanToolBlocks(messages: BaseMessage[]): BaseMessage[];
+/**
+ * Pre-flight truncation: truncates oversized tool result string content before
+ * the budget walker runs. Older results get smaller budgets (recency factor),
+ * with a 200-char floor so even ancient entries keep diagnostic signal. Returns
+ * the number of ToolMessages truncated.
+ */
+export declare function preFlightTruncateToolResults(params: {
+    messages: BaseMessage[];
+    maxContextTokens: number;
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+}): number;
+/**
+ * Pre-flight truncation: truncates oversized `tool_use` input fields in AI messages.
+ *
+ * Tool call inputs (arguments) can be very large — e.g., code evaluation payloads from
+ * MCP tools like chrome-devtools. Since these tool calls have already been executed,
+ * the model only needs a summary of what was called, not the full arguments. Truncating
+ * them before pruning can prevent entire messages from being dropped.
+ *
+ * Uses 15% of the context window (in estimated characters, ~4 chars/token) as the
+ * per-input cap, capped at 200K chars.
+ *
+ * @returns The number of AI messages that had tool_use inputs truncated.
+ */
+export declare function preFlightTruncateToolCallInputs(params: {
+    messages: BaseMessage[];
+    maxContextTokens: number;
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+}): number;
 export declare function createPruneMessages(factoryParams: PruneMessagesFactoryParams): (params: PruneMessagesParams) => {
     context: BaseMessage[];
     indexTokenCountMap: Record<string, number | undefined>;
     messagesToRefine: BaseMessage[];
+    originalToolContent?: Map<number, string>;
 };
 /** Calculates context utilization as a percentage (0-100) */
 export declare function getContextUtilization(indexTokenCountMap: Record<string, number | undefined>, instructionTokens: number, maxContextTokens: number): number;

package/dist/types/run.d.ts

@@ -10,6 +10,8 @@ export declare class Run<_T extends t.BaseGraphState> {
     id: string;
     private tokenCounter?;
     private handlerRegistry?;
+    private hookRegistry?;
+    private toolOutputRegistry?;
     private indexTokenCountMap?;
     graphRunnable?: t.CompiledStateWorkflow;
     Graph: StandardGraph | MultiAgentGraph | undefined;

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

@@ -0,0 +1,76 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const BashExecutionToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly command: {
+            readonly type: "string";
+            readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";
+        };
+        readonly args: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.";
+        };
+    };
+    readonly required: readonly ["command"];
+};
+export declare const BashExecutionToolDescription: string;
+/**
+ * Supplemental prompt documenting the tool-output reference feature.
+ *
+ * Hosts should append this (separated by a blank line) to the base
+ * {@link BashExecutionToolDescription} only when
+ * `RunConfig.toolOutputReferences.enabled` is `true`. When the feature
+ * is disabled, including this text would tell the LLM to emit
+ * `{{tool0turn0}}` placeholders that pass through unsubstituted and
+ * leak into the shell.
+ */
+export declare const BashToolOutputReferencesGuide: string;
+/**
+ * Composes the bash tool description, optionally appending the
+ * tool-output references guide. Hosts that enable
+ * `RunConfig.toolOutputReferences` should pass `enableToolOutputReferences: true`
+ * when registering the tool so the LLM learns the `{{…}}` syntax it
+ * will actually be able to use.
+ */
+export declare function buildBashExecutionToolDescription(options?: {
+    enableToolOutputReferences?: boolean;
+}): string;
+export declare const BashExecutionToolName = Constants.BASH_TOOL;
+/**
+ * Default bash tool definition using the base description.
+ *
+ * When `RunConfig.toolOutputReferences.enabled` is `true`, build a
+ * reference-aware description with
+ * {@link buildBashExecutionToolDescription}
+ * (`{ enableToolOutputReferences: true }`) and construct a custom
+ * definition using it — using this constant as-is leaves the LLM
+ * unaware of the `{{tool<i>turn<n>}}` syntax.
+ */
+export declare const BashExecutionToolDefinition: {
+    readonly name: Constants.BASH_TOOL;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly command: {
+                readonly type: "string";
+                readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";
+            };
+            readonly args: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.";
+            };
+        };
+        readonly required: readonly ["command"];
+    };
+};
+declare function createBashExecutionTool(params?: t.BashExecutionToolParams): DynamicStructuredTool;
+export { createBashExecutionTool };

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

@@ -0,0 +1,72 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const BashProgrammaticToolCallingSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Bash code that calls tools programmatically. Tools are available as bash functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\nExample (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions";
+        };
+        readonly timeout: {
+            readonly type: "integer";
+            readonly minimum: 1000;
+            readonly maximum: 300000;
+            readonly default: 60000;
+            readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+        };
+    };
+    readonly required: readonly ["code"];
+};
+export declare const BashProgrammaticToolCallingName = Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+export declare const BashProgrammaticToolCallingDescription: string;
+export declare const BashProgrammaticToolCallingDefinition: {
+    readonly name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly code: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Bash code that calls tools programmatically. Tools are available as bash functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\nExample (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions";
+            };
+            readonly timeout: {
+                readonly type: "integer";
+                readonly minimum: 1000;
+                readonly maximum: 300000;
+                readonly default: 60000;
+                readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+            };
+        };
+        readonly required: readonly ["code"];
+    };
+};
+/**
+ * Normalizes a tool name to a valid bash function identifier.
+ * 1. Replace hyphens, spaces, dots with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a bash reserved word
+ */
+export declare function normalizeToBashIdentifier(name: string): string;
+/**
+ * Extracts tool names that are actually called in the bash code.
+ * Bash functions are invoked as commands (no parentheses), so we match
+ * the normalized name as a word boundary.
+ */
+export declare function extractUsedBashToolNames(code: string, toolNameMap: Map<string, string>): Set<string>;
+/**
+ * Filters tool definitions to only include tools actually used in the bash code.
+ */
+export declare function filterBashToolsByUsage(toolDefs: t.LCTool[], code: string, debug?: boolean): t.LCTool[];
+/**
+ * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.
+ *
+ * This tool enables AI agents to write bash scripts that orchestrate multiple
+ * tool calls programmatically via the remote Code API, reducing LLM round-trips.
+ *
+ * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).
+ */
+export declare function createBashProgrammaticToolCallingTool(initParams?: t.BashProgrammaticToolCallingParams): DynamicStructuredTool;

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

@@ -3,6 +3,12 @@ import type * as t from '@/types';
 import { Constants } from '@/common';
 export declare const imageExtRegex: RegExp;
 export declare const getCodeBaseURL: () => string;
+/**
+ * Renders one section of the post-execution file listing. Used by the
+ * code/bash tool formatters to keep generated outputs and inherited
+ * inputs visually separated. See BashExecutor for full docs.
+ */
+export declare function renderFileSection(header: string, files: t.FileRefs, defaultMessage: string): string;
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {
@@ -22,20 +28,8 @@ export declare const CodeExecutionToolSchema: {
             };
             readonly description: "Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.";
         };
-        readonly code_id: {
-            readonly type: "string";
-            readonly description: "ID of previously stored code (returned by a prior execute_code call). Use with old_str/new_str to edit stored code instead of rewriting it.";
-        };
-        readonly old_str: {
-            readonly type: "string";
-            readonly description: "Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.";
-        };
-        readonly new_str: {
-            readonly type: "string";
-            readonly description: "Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.";
-        };
     };
-    readonly required: readonly ["lang"];
+    readonly required: readonly [];
 };
 export declare const CodeExecutionToolDescription: string;
 export declare const CodeExecutionToolName = Constants.EXECUTE_CODE;
@@ -61,20 +55,8 @@ export declare const CodeExecutionToolDefinition: {
                 };
                 readonly description: "Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.";
             };
-            readonly code_id: {
-                readonly type: "string";
-                readonly description: "ID of previously stored code (returned by a prior execute_code call). Use with old_str/new_str to edit stored code instead of rewriting it.";
-            };
-            readonly old_str: {
-                readonly type: "string";
-                readonly description: "Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.";
-            };
-            readonly new_str: {
-                readonly type: "string";
-                readonly description: "Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.";
-            };
         };
-        readonly required: readonly ["lang"];
+        readonly required: readonly [];
     };
 };
 declare function createCodeExecutionTool(params?: t.CodeExecutionToolParams): DynamicStructuredTool;

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

@@ -0,0 +1,28 @@
+import { Constants } from '@/common';
+export declare const ReadFileToolName = Constants.READ_FILE;
+export declare const ReadFileToolDescription = "Read the contents of a file. Returns text content with line numbers for easy reference.\n\nFor skill files, use the path format: {skillName}/{filePath} (e.g. \"pdf-analyzer/src/utils.py\", \"code-review/SKILL.md\").\n\nBEHAVIOR:\n- Text files: returned with numbered lines.\n- Images (png, jpeg, gif, webp): returned as visual content the model can see.\n- PDFs: returned as document content.\n- Other binary files: metadata returned with a note to use bash for processing.\n- Large files (>256KB text, >10MB binary): metadata only.\n- SKILL.md: returns the skill's instructions directly.\n\nCONSTRAINTS:\n- Only files from invoked skills or code execution output are accessible.\n- Do not guess file paths. Use paths from the skill documentation or tool output.";
+export declare const ReadFileToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_path: {
+            readonly type: "string";
+            readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
+        };
+    };
+    readonly required: readonly ["file_path"];
+};
+export declare const ReadFileToolDefinition: {
+    readonly name: Constants.READ_FILE;
+    readonly description: "Read the contents of a file. Returns text content with line numbers for easy reference.\n\nFor skill files, use the path format: {skillName}/{filePath} (e.g. \"pdf-analyzer/src/utils.py\", \"code-review/SKILL.md\").\n\nBEHAVIOR:\n- Text files: returned with numbered lines.\n- Images (png, jpeg, gif, webp): returned as visual content the model can see.\n- PDFs: returned as document content.\n- Other binary files: metadata returned with a note to use bash for processing.\n- Large files (>256KB text, >10MB binary): metadata only.\n- SKILL.md: returns the skill's instructions directly.\n\nCONSTRAINTS:\n- Only files from invoked skills or code execution output are accessible.\n- Do not guess file paths. Use paths from the skill documentation or tool output.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
+            };
+        };
+        readonly required: readonly ["file_path"];
+    };
+    readonly responseFormat: "content_and_artifact";
+};

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

@@ -0,0 +1,40 @@
+import { Constants } from '@/common';
+export declare const SkillToolName = Constants.SKILL_TOOL;
+export declare const SkillToolDescription = "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
+/**
+ * JSON Schema for the SkillTool parameters.
+ * Single source of truth used by both SkillToolDefinition (LCTool registry)
+ * and createSkillTool() (DynamicStructuredTool instance).
+ */
+export declare const SkillToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly skillName: {
+            readonly type: "string";
+            readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
+        };
+        readonly args: {
+            readonly type: "string";
+            readonly description: "Optional freeform arguments string passed to the skill.";
+        };
+    };
+    readonly required: readonly ["skillName"];
+};
+export declare const SkillToolDefinition: {
+    readonly name: Constants.SKILL_TOOL;
+    readonly description: "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly skillName: {
+                readonly type: "string";
+                readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
+            };
+            readonly args: {
+                readonly type: "string";
+                readonly description: "Optional freeform arguments string passed to the skill.";
+            };
+        };
+        readonly required: readonly ["skillName"];
+    };
+};