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

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

@@ -1,6 +1,7 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { MessageContentComplex } from '@langchain/core/messages';
 import type { ToolErrorData } from './stream';
 import { EnvVar, ExecutionContext } from '@/common';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
@@ -50,6 +51,35 @@ export type ToolNodeOptions = {
      * When provided, tools matching the policy will call interrupt() before execution.
      */
     toolApprovalConfig?: ToolApprovalConfig;
+    /**
+     * Optional hook registry threaded down from Run. When set, ToolNode
+     * fires PreToolUse / PostToolUse / PostToolUseFailure / PermissionDenied
+     * lifecycle events through executeHooks during event-driven dispatch.
+     */
+    hookRegistry?: import('@/hooks').HookRegistry;
+    /**
+     * Maximum characters for a single tool result (head+tail truncation).
+     * When omitted, derived from the agent's `maxContextTokens` (30%
+     * heuristic), capped at HARD_MAX_TOOL_RESULT_CHARS. —
+     * downstream consumers may drive truncation through other knobs;
+     * accepting this option keeps the test surface portable.
+     */
+    maxToolResultChars?: number;
+    /**
+     * Run-scoped tool output reference configuration (PR #114).
+     * When `enabled` is true, ToolNode registers successful outputs and
+     * substitutes `{{tool<i>turn<n>}}` placeholders found in string args.
+     * Ignored when `toolOutputRegistry` is also provided (the host-supplied
+     * registry wins).
+     */
+    toolOutputReferences?: ToolOutputReferencesConfig;
+    /**
+     * Pre-constructed registry instance shared across ToolNodes for the run.
+     * Graphs pass the same registry to every ToolNode they compile so
+     * cross-agent `{{tool<i>turn<n>}}` substitutions resolve. Takes
+     * precedence over `toolOutputReferences` when both are set.
+     */
+    toolOutputRegistry?: import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -73,12 +103,35 @@ export type CodeExecutionToolParams = undefined | {
     files?: CodeEnvFile[];
     [EnvVar.CODE_API_KEY]?: string;
 };
+/**
+ * Bash execution tool params. Same shape as CodeExecutionToolParams —
+ * BashExecutor reuses the /exec endpoint with `lang: 'bash'`.
+ */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+/**
+ * Read-file tool params. Resolution of the `file_path` to actual bytes is
+ * delegated to a host-supplied resolver in `RunConfig` (skill files, code
+ * exec session files, etc.).
+ */
+export type ReadFileToolParams = undefined | {
+    apiKey?: string;
+    [EnvVar.CODE_API_KEY]?: string;
+};
 export type FileRef = {
     id: string;
     name: string;
     path?: string;
     /** Session ID this file belongs to (for multi-session file tracking) */
     session_id?: string;
+    /**
+     * `true` when the codeapi sandbox echoed this entry as an unchanged
+     * passthrough of an input the caller already owns (skill files,
+     * downloaded inputs whose hash matched the baseline, inherited
+     * `.dirkeep` markers). The tool-result formatter renders these as
+     * "Available files" rather than "Generated files" so the LLM doesn't
+     * conflate infrastructure inputs with newly-produced outputs.
+     */
+    inherited?: true;
 };
 export type FileRefs = FileRef[];
 export type ExecuteResult = {
@@ -158,6 +211,26 @@ export type ToolExecuteBatchRequest = {
     /** Promise rejector - handler calls this on fatal error */
     reject: (error: Error) => void;
 };
+/**
+ * Generic message-injection envelope used by SkillTool, hooks, and any other
+ * tool execution handler that needs to push extra context into graph state
+ * after the ToolMessage. The host's message formatter is responsible for
+ * placement and any per-provider merging rules.
+ */
+export type InjectedMessage = {
+    /** 'user' for skill body injection, 'system' for context hints.
+     *  Both are converted to HumanMessage at runtime; the original role
+     *  is preserved in additional_kwargs.role. */
+    role: 'user' | 'system';
+    /** Message content: string for simple text, array for complex multi-part content */
+    content: string | MessageContentComplex[];
+    /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+    isMeta?: boolean;
+    /** Origin tag for downstream consumers (UI, pruner, compaction) */
+    source?: 'skill' | 'hook' | 'system';
+    /** Only set when source is 'skill', for compaction preservation */
+    skillName?: string;
+};
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
     /** Matches ToolCallRequest.id */
@@ -170,9 +243,41 @@ export type ToolExecuteResult = {
     status: 'success' | 'error';
     /** Error message if status is 'error' */
     errorMessage?: string;
+    /**
+     * Messages to inject into graph state after the ToolMessage for this call.
+     * Placed after tool results to respect provider message ordering
+     * (tool_call -> tool_result adjacency). The host's message formatter may
+     * merge injected user messages with the preceding tool_result turn.
+     * Generic mechanism: any tool execution handler can use this.
+     */
+    injectedMessages?: InjectedMessage[];
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
+/**
+ * Configuration for the tool output reference feature (PR #114).
+ *
+ * When `enabled: true`, ToolNode stores each successful tool output under
+ * a stable key `tool<idx>turn<turn>` and the LLM can pipe a previous output
+ * into a subsequent tool's args via the literal placeholder
+ * `{{tool<idx>turn<turn>}}`. Substitution happens immediately before tool
+ * invocation; the LLM-visible ToolMessage.content is annotated with a
+ * `_ref` JSON field or a `[ref: tool<idx>turn<turn>]` prefix so the model
+ * knows which key the output is stored under.
+ *
+ * Disabled by default. Hosts that want to opt in pass
+ * `toolOutputReferences: { enabled: true }` on RunConfig and (optionally)
+ * append the bash tool's tool-output-references guide to the bash tool
+ * description so the LLM learns the substitution syntax.
+ */
+export type ToolOutputReferencesConfig = {
+    /** Enable the registry and placeholder substitution. Defaults to `false`. */
+    enabled?: boolean;
+    /** Maximum characters stored (and substituted) per registered output. */
+    maxOutputSize?: number;
+    /** Hard cap on total characters retained across all registered outputs for the run. */
+    maxTotalSize?: number;
+};
 export type ProgrammaticCache = {
     toolMap: ToolMap;
     toolDefs: LCTool[];
@@ -389,6 +494,12 @@ export type ProgrammaticToolCallingParams = {
     /** Environment variable key for API key */
     [key: string]: unknown;
 };
+/**
+ * Initialization parameters for the BashPTC tool. Same shape as
+ * {@link ProgrammaticToolCallingParams}; the bash variant just runs
+ * generated code through `lang: 'bash'` instead of `lang: 'python'`.
+ */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
 /**
  * Tracks code execution session state for automatic file persistence.
  * Stored in Graph.sessions and injected into subsequent tool invocations.

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

@@ -13,6 +13,4 @@ export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
 export * from './fileManifest';
 export * from './errors';
-export * from './httpClient';
-export * from './credentials';
-export * from './toolManifest';
+export * from './truncation';

package/dist/types/utils/truncation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Ingestion-time and pre-flight truncation utilities for tool results.
+ *
+ * Prevents oversized tool outputs from entering the message array and
+ * consuming the entire context window.
+ */
+/**
+ * Absolute hard cap on tool result length (characters).
+ * Even if the model has a 1M-token context, a single tool result
+ * larger than this is almost certainly a bug (e.g., dumping a binary file).
+ */
+export declare const HARD_MAX_TOOL_RESULT_CHARS = 400000;
+/**
+ * Absolute hard cap on the aggregate size (characters) of all registered
+ * tool outputs kept for `{{tool<i>turn<n>}}` substitution. Set at 5 MB
+ * because the registry stores *raw, untruncated* tool output — full
+ * fidelity for piping into downstream bash/jq — so the budget needs
+ * enough headroom to keep a handful of large responses without
+ * ballooning unbounded.
+ */
+export declare const HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE = 5000000;
+/**
+ * Computes the dynamic max tool result size based on the model's context window.
+ * Uses 30% of the context window (in estimated characters, ~4 chars/token)
+ * capped at HARD_MAX_TOOL_RESULT_CHARS.
+ *
+ * @param contextWindowTokens - The model's max context tokens (optional).
+ * @returns Maximum allowed characters for a single tool result.
+ */
+export declare function calculateMaxToolResultChars(contextWindowTokens?: number): number;
+/**
+ * Computes the default aggregate size (characters) for the tool output
+ * reference registry based on the per-output budget. Mirrors
+ * `calculateMaxToolResultChars`'s shape: a multiple of the per-output
+ * cap, clamped to `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE`.
+ *
+ * @param maxOutputSize - Per-output maximum characters (e.g., the
+ *   ToolNode's `maxToolResultChars`). When omitted or non-positive,
+ *   falls back to the absolute total cap.
+ * @returns Maximum total characters retained across the registry.
+ */
+export declare function calculateMaxTotalToolOutputSize(maxOutputSize?: number): number;
+/**
+ * Truncates a tool-call input (the arguments/payload of a tool_use block)
+ * using head+tail strategy. Returns an object with `_truncated` (the
+ * truncated string) and `_originalChars` (for diagnostics).
+ *
+ * Accepts any type — objects are JSON-serialized before truncation.
+ *
+ * @param input - The tool input (string, object, etc.).
+ * @param maxChars - Maximum allowed characters.
+ */
+export declare function truncateToolInput(input: unknown, maxChars: number): {
+    _truncated: string;
+    _originalChars: number;
+};
+/**
+ * Truncates tool result content that exceeds `maxChars` using a head+tail
+ * strategy. Keeps the beginning (structure/headers) and end (return value /
+ * conclusion) of the content so the model retains both the opening context
+ * and the final outcome.
+ *
+ * Head gets ~70% of the budget, tail gets ~30%. Falls back to head-only
+ * when the budget is too small for a meaningful tail.
+ *
+ * @param content - The tool result string content.
+ * @param maxChars - Maximum allowed characters.
+ * @returns The (possibly truncated) content string.
+ */
+export declare function truncateToolResultContent(content: string, maxChars: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.4.0-alpha.6",
+  "version": "1.5.1",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -10,25 +10,65 @@
       "require": "./dist/cjs/main.cjs",
       "types": "./dist/types/index.d.ts"
     },
-    "./providers/tools-server": {
-      "import": "./dist/esm/providers/tools-server/ToolsServerCapabilityProvider.mjs",
-      "require": "./dist/cjs/providers/tools-server/ToolsServerCapabilityProvider.cjs",
-      "types": "./dist/types/providers/tools-server/ToolsServerCapabilityProvider.d.ts"
+    "./langchain": {
+      "import": "./dist/esm/langchain/index.mjs",
+      "require": "./dist/cjs/langchain/index.cjs",
+      "types": "./dist/types/langchain/index.d.ts"
     },
-    "./providers/mcp": {
-      "import": "./dist/esm/providers/mcp/MCPCapabilityProvider.mjs",
-      "require": "./dist/cjs/providers/mcp/MCPCapabilityProvider.cjs",
-      "types": "./dist/types/providers/mcp/MCPCapabilityProvider.d.ts"
+    "./langchain/language_models/chat_models": {
+      "import": "./dist/esm/langchain/language_models/chat_models.mjs",
+      "require": "./dist/cjs/langchain/language_models/chat_models.cjs",
+      "types": "./dist/types/langchain/language_models/chat_models.d.ts"
     },
-    "./providers/a2a": {
-      "import": "./dist/esm/providers/a2a/A2ACapabilityProvider.mjs",
-      "require": "./dist/cjs/providers/a2a/A2ACapabilityProvider.cjs",
-      "types": "./dist/types/providers/a2a/A2ACapabilityProvider.d.ts"
+    "./langchain/messages": {
+      "import": "./dist/esm/langchain/messages.mjs",
+      "require": "./dist/cjs/langchain/messages.cjs",
+      "types": "./dist/types/langchain/messages.d.ts"
     },
-    "./content": {
-      "import": "./dist/esm/content/index.mjs",
-      "require": "./dist/cjs/content/index.cjs",
-      "types": "./dist/types/content/index.d.ts"
+    "./langchain/messages/tool": {
+      "import": "./dist/esm/langchain/messages/tool.mjs",
+      "require": "./dist/cjs/langchain/messages/tool.cjs",
+      "types": "./dist/types/langchain/messages/tool.d.ts"
+    },
+    "./langchain/google-common": {
+      "import": "./dist/esm/langchain/google-common.mjs",
+      "require": "./dist/cjs/langchain/google-common.cjs",
+      "types": "./dist/types/langchain/google-common.d.ts"
+    },
+    "./langchain/openai": {
+      "import": "./dist/esm/langchain/openai.mjs",
+      "require": "./dist/cjs/langchain/openai.cjs",
+      "types": "./dist/types/langchain/openai.d.ts"
+    },
+    "./langchain/prompts": {
+      "import": "./dist/esm/langchain/prompts.mjs",
+      "require": "./dist/cjs/langchain/prompts.cjs",
+      "types": "./dist/types/langchain/prompts.d.ts"
+    },
+    "./langchain/runnables": {
+      "import": "./dist/esm/langchain/runnables.mjs",
+      "require": "./dist/cjs/langchain/runnables.cjs",
+      "types": "./dist/types/langchain/runnables.d.ts"
+    },
+    "./langchain/tools": {
+      "import": "./dist/esm/langchain/tools.mjs",
+      "require": "./dist/cjs/langchain/tools.cjs",
+      "types": "./dist/types/langchain/tools.d.ts"
+    },
+    "./langchain/utils/env": {
+      "import": "./dist/esm/langchain/utils/env.mjs",
+      "require": "./dist/cjs/langchain/utils/env.cjs",
+      "types": "./dist/types/langchain/utils/env.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "langchain": [
+        "dist/types/langchain/index.d.ts"
+      ],
+      "langchain/*": [
+        "dist/types/langchain/*"
+      ]
     }
   },
   "type": "module",