@librechat/agents 3.1.67 → 3.1.68-dev.1

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,7 +7,14 @@ export * from './graphs';
 export * from './summarization';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
+export * from './tools/BashProgrammaticToolCalling';
+export * from './tools/SkillTool';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
+export * from './tools/ReadFile';
+export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
 export * from './tools/schema';
@@ -15,6 +22,7 @@ export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';
 export * from './utils';
+export * from './hooks';
 export type * from './types';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

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

@@ -104,9 +104,10 @@ 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.
  * @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>) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
     /** Cross-run summary extracted from the payload. Should be forwarded to the

package/dist/types/run.d.ts

@@ -9,6 +9,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     id: string;
     private tokenCounter?;
     private handlerRegistry?;
+    private hookRegistry?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;

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

@@ -1,4 +1,6 @@
 import type { SummarizationTrigger } from '@/types';
+/** For tests only. Resets the dedup set so warnings can be observed again. */
+export declare function _resetUnrecognizedTriggerWarnings(): void;
 /**
  * Determines whether summarization should be triggered based on the configured trigger
  * and current context state.

package/dist/types/summarization/node.d.ts

@@ -1,6 +1,7 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 /** Structured checkpoint prompt for fresh summarization (no prior summary). */
 export declare const DEFAULT_SUMMARIZATION_PROMPT = "Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.\n\nDon't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.\n\n## Checkpoint\n\n## Goal\nWhat I asked you to do and any sub-goals you identified.\n\n## Constraints & Preferences\nAny rules, preferences, or configuration I established.\n\n## Progress\n### Done\n- What you completed and the outcomes\n\n### In Progress\n- What you're currently working on\n\n## Key Decisions\nDecisions you made and why.\n\n## Next Steps\nConcrete task actions remaining, in priority order.\n\n## Critical Context\nExact identifiers, names, error messages, URLs, and details you need to preserve verbatim.\n\nRules:\n- Record what you did and observed, don't judge or re-evaluate it\n- For each tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Short declarative sentences\n- Skip empty sections";
@@ -14,6 +15,7 @@ interface CreateSummarizeNodeParams {
         config?: RunnableConfig;
         runId?: string;
         isMultiAgent: boolean;
+        hookRegistry?: HookRegistry;
         dispatchRunStep: (runStep: t.RunStep, config?: RunnableConfig) => Promise<void>;
         dispatchRunStepCompleted: (stepId: string, result: t.StepCompleted, config?: RunnableConfig) => Promise<void>;
     };

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

@@ -0,0 +1,45 @@
+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;
+export declare const BashExecutionToolName = Constants.BASH_TOOL;
+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/ProgrammaticToolCalling.d.ts

@@ -75,21 +75,19 @@ export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, d
  * Fetches files from a previous session to make them available for the current execution.
  * Files are returned as CodeEnvFile references to be included in the request.
  * @param baseUrl - The base URL for the Code API
- * @param apiKey - The API key for authentication
  * @param sessionId - The session ID to fetch files from
  * @param proxy - Optional HTTP proxy URL
  * @returns Array of CodeEnvFile references, or empty array if fetch fails
  */
-export declare function fetchSessionFiles(baseUrl: string, apiKey: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
+export declare function fetchSessionFiles(baseUrl: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL
- * @param apiKey - The API key for authentication
  * @param body - The request body
  * @param proxy - Optional HTTP proxy URL
  * @returns The parsed API response
  */
-export declare function makeRequest(endpoint: string, apiKey: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
+export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
 /**
  * Unwraps tool responses that may be formatted as tuples or content blocks.
  * MCP tools return [content, artifacts], we need to extract the raw data.
@@ -121,14 +119,11 @@ export declare function formatCompletedResponse(response: t.ProgrammaticExecutio
  *
  * The tool map must be provided at runtime via config.configurable.toolMap.
  *
- * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)
+ * @param params - Configuration parameters (baseUrl, maxRoundTrips, proxy)
  * @returns A LangChain DynamicStructuredTool for programmatic tool calling
  *
  * @example
- * const ptcTool = createProgrammaticToolCallingTool({
- *   apiKey: process.env.CODE_API_KEY,
- *   maxRoundTrips: 20
- * });
+ * const ptcTool = createProgrammaticToolCallingTool({ maxRoundTrips: 20 });
  *
  * const [output, artifact] = await ptcTool.invoke(
  *   { code, tools },

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"];
+    };
+};