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

package/dist/cjs/tools/fileSearch/tool.cjs

@@ -1,155 +0,0 @@
-'use strict';
-
-var tools = require('@langchain/core/tools');
-var schema = require('./schema.cjs');
-var formatter = require('./formatter.cjs');
-
-/**
- * file_search tool factory — library-native equivalent of the CodeExecutor
- * pattern. Runtimes supply a `RagClient`, the file list for this turn, and
- * an optional formatter (ranger uses citation anchors; CLI/A2A use plain
- * text).
- *
- * The tool itself:
- *   1. Accepts `{ query, target_files? }` from the LLM.
- *   2. Filters files by `target_files` substring match when provided.
- *   3. Queries each file in bounded concurrent batches.
- *   4. Enforces per-file timeouts (failures isolated per file).
- *   5. Flattens chunks, deprioritizes stale-turn files, caps results.
- *   6. Hands formatted output to the runtime's formatter for final shape.
- */
-const DEFAULT_QUERY_TIMEOUT_MS = 15_000;
-const DEFAULT_CONCURRENCY = 10;
-const DEFAULT_TOP_K = 10;
-/**
- * Build the tool description. Runtimes that use citation anchors supply
- * `fileCitations: true` (via the formatter); the description includes the
- * citation ruleset only when that's on.
- */
-function buildDescription(opts) {
-    const core = `Performs semantic search across the attached "${schema.FileSearchToolName}" documents using natural language queries. Analyzes the content of loaded files to find relevant information, quotes, and passages matching the query.
-
-**Use target_files to narrow the search:**
-When you know which file(s) contain the relevant information, ALWAYS pass target_files. This is faster and returns more focused results. Pass partial filenames — they match via substring.
-
-**Multiple searches for thorough analysis:**
-For summaries/overviews, call this tool MULTIPLE times with DIFFERENT queries targeting different aspects (intro, methodology, results, conclusions). A single search only returns chunks from one part of the document.`;
-    if (!opts.fileCitations)
-        return core;
-    return `${core}
-
-**CITING FILE SEARCH RESULTS — MANDATORY:**
-Cite EVERY statement derived from file content. Place the citation anchor IMMEDIATELY after each paragraph using that source. Each search result has a unique source index — use DIFFERENT indices for different claims; do not reuse the same anchor for all paragraphs. Format: \`\\ue202turn0fileN\`. With a page: include \`(p. N)\` inline. Multiple sources: \`\\ue200\\ue202turn0file0\\ue202turn0file1\\ue201\`. NEVER substitute with footnotes, brackets, or symbols.`;
-}
-function createFileSearchTool(config) {
-    const { ragClient, files, entity_id, scope, getAuthHeaders, formatter: formatter$1 = formatter.plainTextFormatter, queryTimeoutMs = DEFAULT_QUERY_TIMEOUT_MS, concurrencyLimit = DEFAULT_CONCURRENCY, topK = DEFAULT_TOP_K, resultCap, callbacks, logger, } = config;
-    // Monotonic call counter used by citation-style formatters to keep source
-    // indices unique across multiple invocations within a single turn.
-    let callIndex = 0;
-    // Infer whether the formatter wants citations from the artifact it emits
-    // on an empty-chunk format. This keeps the description/behavior aligned
-    // without forcing the host to declare `fileCitations` twice.
-    const fileCitations = formatter$1 !== formatter.plainTextFormatter;
-    return tools.tool(async (rawInput) => {
-        const { query, target_files } = rawInput;
-        if (files.length === 0) {
-            return [
-                'No files to search. Instruct the user to add files for the search.',
-                undefined,
-            ];
-        }
-        // target_files: case-insensitive substring match, fallback to all
-        // files with a warning if the filter excludes everything.
-        let filesToQuery = files;
-        if (target_files && target_files.length > 0) {
-            const lowerTargets = target_files.map((t) => t.toLowerCase());
-            const matched = files.filter((f) => lowerTargets.some((t) => f.filename.toLowerCase().includes(t)));
-            if (matched.length === 0) {
-                logger?.warn(`[file_search] No files matched target_files ${target_files.join(', ')}; falling back to all files`);
-                filesToQuery = files;
-            }
-            else {
-                logger?.info(`[file_search] Filtered to ${matched.length}/${files.length} via target_files`);
-                filesToQuery = matched;
-            }
-        }
-        const authHeaders = getAuthHeaders ? await getAuthHeaders() : undefined;
-        const queryOne = async (file) => {
-            const params = {
-                file_id: file.file_id,
-                query,
-                k: topK,
-                entity_id,
-                scope,
-                authHeaders,
-                timeoutMs: queryTimeoutMs,
-            };
-            try {
-                const chunks = await ragClient.query(params);
-                callbacks?.onFileQueried?.(file, chunks.length);
-                return chunks;
-            }
-            catch (err) {
-                const e = err instanceof Error ? err : new Error(String(err));
-                logger?.error(`[file_search] Query failed for ${file.filename}: ${e.message}`);
-                callbacks?.onFileError?.(file, e);
-                return [];
-            }
-        };
-        // Bounded-concurrency batching. Server-side rerankers handle their
-        // own concurrency; this protects the HTTP connection pool when the
-        // agent has many files.
-        const allChunks = [];
-        for (let i = 0; i < filesToQuery.length; i += concurrencyLimit) {
-            const batch = filesToQuery.slice(i, i + concurrencyLimit);
-            const batchResults = await Promise.all(batch.map(queryOne));
-            for (const chunks of batchResults)
-                allChunks.push(...chunks);
-        }
-        if (allChunks.length === 0) {
-            return [
-                'No content found in the files. The files may not have been processed correctly or the query may need refinement.',
-                undefined,
-            ];
-        }
-        // Build annotated results: attach filename + isCurrentMessage via
-        // a file-id lookup (metadata wins, factory list is fallback).
-        const fileById = new Map(files.map((f) => [f.file_id, f]));
-        const annotated = allChunks.map((c) => {
-            const matched = fileById.get(c.file_id);
-            const filename = (c.metadata?.source
-                ? String(c.metadata.source).split(/[/\\]/).pop()
-                : undefined) ??
-                matched?.filename ??
-                'Unknown';
-            return {
-                ...c,
-                filename,
-                isCurrentMessage: matched?.isCurrentMessage === true,
-            };
-        });
-        // Sort: current-turn files first, then by relevance (lower distance).
-        annotated.sort((a, b) => {
-            if (a.isCurrentMessage !== b.isCurrentMessage)
-                return a.isCurrentMessage ? -1 : 1;
-            return a.distance - b.distance;
-        });
-        const cap = resultCap ?? Math.max(10, filesToQuery.length * 3);
-        const limited = annotated.slice(0, cap);
-        const { message, artifact } = formatter$1.format(limited, {
-            callIndex,
-            files,
-        });
-        callIndex += 1;
-        return [message, artifact];
-    }, {
-        name: schema.FileSearchToolName,
-        responseFormat: 'content_and_artifact',
-        description: buildDescription({ fileCitations }),
-        schema: schema.fileSearchInputSchema,
-    });
-}
-
-exports.FileSearchToolName = schema.FileSearchToolName;
-exports.createFileSearchTool = createFileSearchTool;
-//# sourceMappingURL=tool.cjs.map

package/dist/cjs/tools/fileSearch/tool.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tool.cjs","sources":["../../../../src/tools/fileSearch/tool.ts"],"sourcesContent":["/**\n * file_search tool factory — library-native equivalent of the CodeExecutor\n * pattern. Runtimes supply a `RagClient`, the file list for this turn, and\n * an optional formatter (ranger uses citation anchors; CLI/A2A use plain\n * text).\n *\n * The tool itself:\n *   1. Accepts `{ query, target_files? }` from the LLM.\n *   2. Filters files by `target_files` substring match when provided.\n *   3. Queries each file in bounded concurrent batches.\n *   4. Enforces per-file timeouts (failures isolated per file).\n *   5. Flattens chunks, deprioritizes stale-turn files, caps results.\n *   6. Hands formatted output to the runtime's formatter for final shape.\n */\n\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport {\n  fileSearchInputSchema,\n  type FileSearchInput,\n  FileSearchToolName,\n} from './schema';\nimport type {\n  FileSearchToolConfig,\n  FileSearchFile,\n  RagChunk,\n  RagQueryParams,\n} from './types';\nimport { plainTextFormatter } from './formatter';\n\nconst DEFAULT_QUERY_TIMEOUT_MS = 15_000;\nconst DEFAULT_CONCURRENCY = 10;\nconst DEFAULT_TOP_K = 10;\n\n/**\n * Build the tool description. Runtimes that use citation anchors supply\n * `fileCitations: true` (via the formatter); the description includes the\n * citation ruleset only when that's on.\n */\nfunction buildDescription(opts: { fileCitations: boolean }): string {\n  const core = `Performs semantic search across the attached \"${FileSearchToolName}\" documents using natural language queries. Analyzes the content of loaded files to find relevant information, quotes, and passages matching the query.\n\n**Use target_files to narrow the search:**\nWhen you know which file(s) contain the relevant information, ALWAYS pass target_files. This is faster and returns more focused results. Pass partial filenames — they match via substring.\n\n**Multiple searches for thorough analysis:**\nFor summaries/overviews, call this tool MULTIPLE times with DIFFERENT queries targeting different aspects (intro, methodology, results, conclusions). A single search only returns chunks from one part of the document.`;\n\n  if (!opts.fileCitations) return core;\n\n  return `${core}\n\n**CITING FILE SEARCH RESULTS — MANDATORY:**\nCite EVERY statement derived from file content. Place the citation anchor IMMEDIATELY after each paragraph using that source. Each search result has a unique source index — use DIFFERENT indices for different claims; do not reuse the same anchor for all paragraphs. Format: \\`\\\\ue202turn0fileN\\`. With a page: include \\`(p. N)\\` inline. Multiple sources: \\`\\\\ue200\\\\ue202turn0file0\\\\ue202turn0file1\\\\ue201\\`. NEVER substitute with footnotes, brackets, or symbols.`;\n}\n\nexport function createFileSearchTool(\n  config: FileSearchToolConfig\n): DynamicStructuredTool {\n  const {\n    ragClient,\n    files,\n    entity_id,\n    scope,\n    getAuthHeaders,\n    formatter = plainTextFormatter,\n    queryTimeoutMs = DEFAULT_QUERY_TIMEOUT_MS,\n    concurrencyLimit = DEFAULT_CONCURRENCY,\n    topK = DEFAULT_TOP_K,\n    resultCap,\n    callbacks,\n    logger,\n  } = config;\n\n  // Monotonic call counter used by citation-style formatters to keep source\n  // indices unique across multiple invocations within a single turn.\n  let callIndex = 0;\n\n  // Infer whether the formatter wants citations from the artifact it emits\n  // on an empty-chunk format. This keeps the description/behavior aligned\n  // without forcing the host to declare `fileCitations` twice.\n  const fileCitations = formatter !== plainTextFormatter;\n\n  return tool(\n    async (rawInput: FileSearchInput) => {\n      const { query, target_files } = rawInput;\n\n      if (files.length === 0) {\n        return [\n          'No files to search. Instruct the user to add files for the search.',\n          undefined,\n        ];\n      }\n\n      // target_files: case-insensitive substring match, fallback to all\n      // files with a warning if the filter excludes everything.\n      let filesToQuery: FileSearchFile[] = files;\n      if (target_files && target_files.length > 0) {\n        const lowerTargets = target_files.map((t) => t.toLowerCase());\n        const matched = files.filter((f) =>\n          lowerTargets.some((t) => f.filename.toLowerCase().includes(t))\n        );\n        if (matched.length === 0) {\n          logger?.warn(\n            `[file_search] No files matched target_files ${target_files.join(', ')}; falling back to all files`\n          );\n          filesToQuery = files;\n        } else {\n          logger?.info(\n            `[file_search] Filtered to ${matched.length}/${files.length} via target_files`\n          );\n          filesToQuery = matched;\n        }\n      }\n\n      const authHeaders = getAuthHeaders ? await getAuthHeaders() : undefined;\n\n      const queryOne = async (file: FileSearchFile): Promise<RagChunk[]> => {\n        const params: RagQueryParams = {\n          file_id: file.file_id,\n          query,\n          k: topK,\n          entity_id,\n          scope,\n          authHeaders,\n          timeoutMs: queryTimeoutMs,\n        };\n        try {\n          const chunks = await ragClient.query(params);\n          callbacks?.onFileQueried?.(file, chunks.length);\n          return chunks;\n        } catch (err) {\n          const e = err instanceof Error ? err : new Error(String(err));\n          logger?.error(\n            `[file_search] Query failed for ${file.filename}: ${e.message}`\n          );\n          callbacks?.onFileError?.(file, e);\n          return [];\n        }\n      };\n\n      // Bounded-concurrency batching. Server-side rerankers handle their\n      // own concurrency; this protects the HTTP connection pool when the\n      // agent has many files.\n      const allChunks: RagChunk[] = [];\n      for (let i = 0; i < filesToQuery.length; i += concurrencyLimit) {\n        const batch = filesToQuery.slice(i, i + concurrencyLimit);\n        const batchResults = await Promise.all(batch.map(queryOne));\n        for (const chunks of batchResults) allChunks.push(...chunks);\n      }\n\n      if (allChunks.length === 0) {\n        return [\n          'No content found in the files. The files may not have been processed correctly or the query may need refinement.',\n          undefined,\n        ];\n      }\n\n      // Build annotated results: attach filename + isCurrentMessage via\n      // a file-id lookup (metadata wins, factory list is fallback).\n      const fileById = new Map(files.map((f) => [f.file_id, f]));\n      const annotated = allChunks.map((c) => {\n        const matched = fileById.get(c.file_id);\n        const filename =\n          (c.metadata?.source\n            ? String(c.metadata.source).split(/[/\\\\]/).pop()\n            : undefined) ??\n          matched?.filename ??\n          'Unknown';\n        return {\n          ...c,\n          filename,\n          isCurrentMessage: matched?.isCurrentMessage === true,\n        };\n      });\n\n      // Sort: current-turn files first, then by relevance (lower distance).\n      annotated.sort((a, b) => {\n        if (a.isCurrentMessage !== b.isCurrentMessage)\n          return a.isCurrentMessage ? -1 : 1;\n        return a.distance - b.distance;\n      });\n\n      const cap = resultCap ?? Math.max(10, filesToQuery.length * 3);\n      const limited = annotated.slice(0, cap);\n\n      const { message, artifact } = formatter.format(limited, {\n        callIndex,\n        files,\n      });\n      callIndex += 1;\n\n      // Suppress unused-variable warning for fileCitations (currently only\n      // used to gate description; kept in case formatters need it).\n      void fileCitations;\n\n      return [message, artifact];\n    },\n    {\n      name: FileSearchToolName,\n      responseFormat: 'content_and_artifact',\n      description: buildDescription({ fileCitations }),\n      schema: fileSearchInputSchema,\n    }\n  );\n}\n\nexport { FileSearchToolName } from './schema';\n"],"names":["FileSearchToolName","formatter","plainTextFormatter","tool","fileSearchInputSchema"],"mappings":"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"}

package/dist/cjs/tools/proxyTool.cjs

@@ -1,102 +0,0 @@
-'use strict';
-
-var tools = require('@langchain/core/tools');
-var httpClient = require('../utils/httpClient.cjs');
-
-/**
- * proxyTool — wraps a Capability into a LangChain StructuredTool that
- * dispatches execution to a remote backend (e.g., tools-server) over HTTP.
- *
- * The LLM sees this tool identically to a locally-implemented tool:
- *   - same name
- *   - same description
- *   - same input schema (JSON Schema)
- *   - same invoke(input) contract
- *
- * Under the hood, invoke() POSTs to the backend's execute endpoint with
- * the input and a caller-supplied credential map. The backend returns
- * { success, result, error, timing } which this wrapper unpacks.
- */
-/**
- * Build a StructuredTool that proxies to a remote backend.
- *
- * The credentialMap is baked into the closure — callers that need
- * per-invocation credential rotation should rebuild the tool.
- */
-function buildProxyTool(capability, credentials, options) {
-    const { client, executePath = '/execute/:name', onExecute, getAuthHeaders, } = options;
-    const url = executePath.replace(':name', encodeURIComponent(capability.name));
-    return tools.tool(async (input) => {
-        const startMs = Date.now();
-        const debugPrefix = `[proxyTool:${capability.name}]`;
-        try {
-            // DEBUG: log (remove after POC stabilizes)
-            // eslint-disable-next-line no-console
-            console.debug(`${debugPrefix} invoking — inputKeys=${input && typeof input === 'object' ? Object.keys(input).length : 0}`);
-            const extraHeaders = getAuthHeaders
-                ? await getAuthHeaders()
-                : undefined;
-            const res = await client.post(url, { input, credentials }, extraHeaders && Object.keys(extraHeaders).length > 0
-                ? { headers: extraHeaders }
-                : undefined);
-            const durationMs = Date.now() - startMs;
-            if (res.status < 200 || res.status >= 300) {
-                throw new httpClient.HttpError(res.status, url, res.data);
-            }
-            const body = res.data;
-            if (onExecute) {
-                try {
-                    onExecute({
-                        capabilityName: capability.name,
-                        input,
-                        response: body,
-                        durationMs,
-                    });
-                }
-                catch {
-                    // hook errors are non-fatal
-                }
-            }
-            if (!body.success) {
-                // DEBUG
-                // eslint-disable-next-line no-console
-                console.debug(`${debugPrefix} backend reported failure — ${body.error}`);
-                throw new Error(body.error ?? 'Tool execution failed');
-            }
-            // LangChain tools typically return strings; stringify non-string results
-            if (typeof body.result === 'string') {
-                return body.result;
-            }
-            return JSON.stringify(body.result);
-        }
-        catch (err) {
-            const durationMs = Date.now() - startMs;
-            const error = err instanceof Error ? err : new Error(String(err));
-            if (onExecute) {
-                try {
-                    onExecute({
-                        capabilityName: capability.name,
-                        input,
-                        error,
-                        durationMs,
-                    });
-                }
-                catch {
-                    // hook errors are non-fatal
-                }
-            }
-            throw error;
-        }
-    }, {
-        name: capability.name,
-        description: capability.description,
-        schema: capability.schema ?? {
-            type: 'object',
-            properties: {},
-        },
-        responseFormat: 'content',
-    });
-}
-
-exports.buildProxyTool = buildProxyTool;
-//# sourceMappingURL=proxyTool.cjs.map

package/dist/cjs/tools/proxyTool.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"proxyTool.cjs","sources":["../../../src/tools/proxyTool.ts"],"sourcesContent":["/**\n * proxyTool — wraps a Capability into a LangChain StructuredTool that\n * dispatches execution to a remote backend (e.g., tools-server) over HTTP.\n *\n * The LLM sees this tool identically to a locally-implemented tool:\n *   - same name\n *   - same description\n *   - same input schema (JSON Schema)\n *   - same invoke(input) contract\n *\n * Under the hood, invoke() POSTs to the backend's execute endpoint with\n * the input and a caller-supplied credential map. The backend returns\n * { success, result, error, timing } which this wrapper unpacks.\n */\n\nimport type { AxiosInstance } from 'axios';\nimport { tool, type StructuredToolInterface } from '@langchain/core/tools';\nimport type { Capability, CredentialMap } from '@/providers/types';\nimport { HttpError } from '@/utils/httpClient';\n\n/** Shape of the backend's execute response. Matches tools-server. */\nexport interface ExecuteResponse {\n  success: boolean;\n  result?: unknown;\n  error?: string;\n  timing?: { durationMs: number };\n}\n\n/** Options passed to buildProxyTool. */\nexport interface ProxyToolOptions {\n  /** HTTP client configured with backend base URL + auth. */\n  client: AxiosInstance;\n  /**\n   * Path template for execution. The literal `:name` is replaced with the\n   * capability's name. Defaults to `/execute/:name` (tools-server convention).\n   */\n  executePath?: string;\n  /**\n   * Optional callback invoked on every execution — used for metrics,\n   * telemetry, debug logging. Errors in the hook are swallowed.\n   */\n  onExecute?: (ctx: ExecuteCallbackContext) => void;\n  /**\n   * Optional per-invocation auth header builder. Called on every tool\n   * invocation before POSTing; returned headers are merged into the\n   * request alongside the base client's headers. Typical use: pass a\n   * freshly minted per-user JWT for admin-gated tools.\n   */\n  getAuthHeaders?: () =>\n    | Record<string, string>\n    | Promise<Record<string, string>>;\n}\n\nexport interface ExecuteCallbackContext {\n  capabilityName: string;\n  input: unknown;\n  response?: ExecuteResponse;\n  error?: Error;\n  durationMs: number;\n}\n\n/**\n * Build a StructuredTool that proxies to a remote backend.\n *\n * The credentialMap is baked into the closure — callers that need\n * per-invocation credential rotation should rebuild the tool.\n */\nexport function buildProxyTool(\n  capability: Capability,\n  credentials: CredentialMap,\n  options: ProxyToolOptions\n): StructuredToolInterface {\n  const {\n    client,\n    executePath = '/execute/:name',\n    onExecute,\n    getAuthHeaders,\n  } = options;\n  const url = executePath.replace(':name', encodeURIComponent(capability.name));\n\n  return tool(\n    async (input: unknown): Promise<string> => {\n      const startMs = Date.now();\n      const debugPrefix = `[proxyTool:${capability.name}]`;\n\n      try {\n        // DEBUG: log (remove after POC stabilizes)\n        // eslint-disable-next-line no-console\n        console.debug(\n          `${debugPrefix} invoking — inputKeys=${input && typeof input === 'object' ? Object.keys(input as object).length : 0}`\n        );\n\n        const extraHeaders = getAuthHeaders\n          ? await getAuthHeaders()\n          : undefined;\n        const res = await client.post<ExecuteResponse>(\n          url,\n          { input, credentials },\n          extraHeaders && Object.keys(extraHeaders).length > 0\n            ? { headers: extraHeaders }\n            : undefined\n        );\n\n        const durationMs = Date.now() - startMs;\n\n        if (res.status < 200 || res.status >= 300) {\n          throw new HttpError(res.status, url, res.data);\n        }\n\n        const body = res.data;\n        if (onExecute) {\n          try {\n            onExecute({\n              capabilityName: capability.name,\n              input,\n              response: body,\n              durationMs,\n            });\n          } catch {\n            // hook errors are non-fatal\n          }\n        }\n\n        if (!body.success) {\n          // DEBUG\n          // eslint-disable-next-line no-console\n          console.debug(\n            `${debugPrefix} backend reported failure — ${body.error}`\n          );\n          throw new Error(body.error ?? 'Tool execution failed');\n        }\n\n        // LangChain tools typically return strings; stringify non-string results\n        if (typeof body.result === 'string') {\n          return body.result;\n        }\n        return JSON.stringify(body.result);\n      } catch (err) {\n        const durationMs = Date.now() - startMs;\n        const error = err instanceof Error ? err : new Error(String(err));\n        if (onExecute) {\n          try {\n            onExecute({\n              capabilityName: capability.name,\n              input,\n              error,\n              durationMs,\n            });\n          } catch {\n            // hook errors are non-fatal\n          }\n        }\n        throw error;\n      }\n    },\n    {\n      name: capability.name,\n      description: capability.description,\n      schema: (capability.schema as object) ?? {\n        type: 'object',\n        properties: {},\n      },\n      responseFormat: 'content',\n    }\n  );\n}\n"],"names":["tool","HttpError"],"mappings":";;;;;AAAA;;;;;;;;;;;;;AAaG;AAgDH;;;;;AAKG;SACa,cAAc,CAC5B,UAAsB,EACtB,WAA0B,EAC1B,OAAyB,EAAA;AAEzB,IAAA,MAAM,EACJ,MAAM,EACN,WAAW,GAAG,gBAAgB,EAC9B,SAAS,EACT,cAAc,GACf,GAAG,OAAO;AACX,IAAA,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAE7E,IAAA,OAAOA,UAAI,CACT,OAAO,KAAc,KAAqB;AACxC,QAAA,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE;AAC1B,QAAA,MAAM,WAAW,GAAG,CAAA,WAAA,EAAc,UAAU,CAAC,IAAI,GAAG;AAEpD,QAAA,IAAI;;;AAGF,YAAA,OAAO,CAAC,KAAK,CACX,CAAA,EAAG,WAAW,CAAA,sBAAA,EAAyB,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA,CAAE,CACtH;YAED,MAAM,YAAY,GAAG;kBACjB,MAAM,cAAc;kBACpB,SAAS;YACb,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAC3B,GAAG,EACH,EAAE,KAAK,EAAE,WAAW,EAAE,EACtB,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,GAAG;AACjD,kBAAE,EAAE,OAAO,EAAE,YAAY;kBACvB,SAAS,CACd;YAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;AAEvC,YAAA,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE;AACzC,gBAAA,MAAM,IAAIC,oBAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC;YAChD;AAEA,YAAA,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI;YACrB,IAAI,SAAS,EAAE;AACb,gBAAA,IAAI;AACF,oBAAA,SAAS,CAAC;wBACR,cAAc,EAAE,UAAU,CAAC,IAAI;wBAC/B,KAAK;AACL,wBAAA,QAAQ,EAAE,IAAI;wBACd,UAAU;AACX,qBAAA,CAAC;gBACJ;AAAE,gBAAA,MAAM;;gBAER;YACF;AAEA,YAAA,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;;;gBAGjB,OAAO,CAAC,KAAK,CACX,CAAA,EAAG,WAAW,CAAA,4BAAA,EAA+B,IAAI,CAAC,KAAK,CAAA,CAAE,CAC1D;gBACD,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,uBAAuB,CAAC;YACxD;;AAGA,YAAA,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE;gBACnC,OAAO,IAAI,CAAC,MAAM;YACpB;YACA,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QACpC;QAAE,OAAO,GAAG,EAAE;YACZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;YACvC,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,IAAI,SAAS,EAAE;AACb,gBAAA,IAAI;AACF,oBAAA,SAAS,CAAC;wBACR,cAAc,EAAE,UAAU,CAAC,IAAI;wBAC/B,KAAK;wBACL,KAAK;wBACL,UAAU;AACX,qBAAA,CAAC;gBACJ;AAAE,gBAAA,MAAM;;gBAER;YACF;AACA,YAAA,MAAM,KAAK;QACb;AACF,IAAA,CAAC,EACD;QACE,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,WAAW,EAAE,UAAU,CAAC,WAAW;AACnC,QAAA,MAAM,EAAG,UAAU,CAAC,MAAiB,IAAI;AACvC,YAAA,IAAI,EAAE,QAAQ;AACd,YAAA,UAAU,EAAE,EAAE;AACf,SAAA;AACD,QAAA,cAAc,EAAE,SAAS;AAC1B,KAAA,CACF;AACH;;;;"}

package/dist/cjs/utils/childAgentContext.cjs

@@ -1,242 +0,0 @@
-'use strict';
-
-var messages = require('@langchain/core/messages');
-
-/**
- * Child-agent context preparation utilities.
- *
- * When a parent agent invokes a child agent — via handoff, sequence edge,
- * or scoped subgraph — the child cannot just receive `state.messages`
- * verbatim. The parent's conversation contains tool_use/tool_result blocks
- * that are (a) often incompatible with the child's tool registry, and
- * (b) actively harmful to the child's ability to reason cleanly about its
- * own task (noise → schema confusion → malformed tool_use).
- *
- * This module provides the two canonical strategies, extracted from
- * `MultiAgentGraph` so they can be unit-tested in isolation and reused by
- * future sub-agent orchestrators:
- *
- *   1. `prepareHandoffMessages` — "cleaned parent history"
- *      Used when the child still needs the orchestrator's context (it's
- *      the handoff target). Drops orphaned tool_use, compacts paired
- *      tool_use/tool_result into text summaries, and guarantees the tail
- *      is a HumanMessage so Bedrock/VertexAI won't reject the conversation
- *      with "assistant message prefill" errors.
- *
- *   2. `prepareIsolatedChildMessages` — "fresh session"
- *      Used for downstream sequence-node children inside a scoped subgraph.
- *      The child sees only the original user request plus a synthetic
- *      HumanMessage summarizing the upstream agent's final text output and
- *      directing the child to act. Raw upstream tool_use/tool_result blocks
- *      are discarded.
- *
- * Both helpers are pure functions over message arrays — no I/O, no
- * LangGraph coupling — so they can be exercised by unit tests with
- * synthetic message fixtures.
- */
-/* -------------------------------------------------------------------------- */
-/*  Prompt template constants (kept outside the functions for reuse/tuning)   */
-/* -------------------------------------------------------------------------- */
-/**
- * Prefix injected in front of a trailing AIMessage when we flip it to a
- * HumanMessage to satisfy provider "last message must be user" rules.
- */
-const HANDOFF_TAIL_CONTEXT_PREFIX = '[Context from orchestrator]: ';
-/**
- * Directive task-framing wrapper for downstream scoped-subgraph children.
- *
- * Design notes — each line is load-bearing:
- *  - "Prior step output" names the upstream role without leaking the
- *    agent's internal id.
- *  - "You MUST now perform..." replaces ambiguity with obligation.
- *  - "system instructions" references the agent's stored system prompt
- *    as the source of task definition — so operators can tune behavior
- *    via data, not code.
- *  - The tool-first clause prevents small/fast models from stalling on a
- *    text-only acknowledgement when a tool action is expected.
- */
-function buildIsolatedChildPrompt(upstreamText) {
-    return ('## Prior step output\n\n' +
-        upstreamText +
-        '\n\n---\n\n' +
-        '## Your task\n\n' +
-        'The previous step in this workflow has completed. You MUST now ' +
-        'perform your own task as defined in your system instructions, ' +
-        "using the prior step's output as input where relevant.\n\n" +
-        'If your task requires calling a tool, call it directly — do not ' +
-        'ask for clarification and do not produce a text-only response when ' +
-        'a tool action is expected.');
-}
-/* -------------------------------------------------------------------------- */
-/*  Internal helpers                                                          */
-/* -------------------------------------------------------------------------- */
-/**
- * Extract concatenated text content from an AI message's content field.
- * Handles both the string shape (OpenAI/plain) and the array-of-blocks
- * shape (Anthropic/Bedrock).
- */
-function extractAIText(msg) {
-    const content = msg.content;
-    if (typeof content === 'string')
-        return content;
-    if (!Array.isArray(content))
-        return '';
-    return content
-        .filter((b) => b.type === 'text' && typeof b.text === 'string')
-        .map((b) => b.text ?? '')
-        .join('\n');
-}
-/* -------------------------------------------------------------------------- */
-/*  Strategy 1: cleaned parent history (handoff target / root subgraph)       */
-/* -------------------------------------------------------------------------- */
-/**
- * Prepare messages for a handoff child agent.
- *
- * Handles two problems that break Bedrock/Anthropic conversations:
- *
- * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use`
- *    block for the handoff tool itself, with no matching `tool_result`.
- *    Providers (Bedrock/Anthropic) reject this.
- *
- * 2. **Paired tool_use/tool_result in history**: The child may not have
- *    the same tools as the parent. Bedrock requires `toolConfig` when any
- *    tool_use/tool_result blocks exist in the history. Compacting these
- *    into text summaries avoids the requirement and reduces context bloat.
- *
- * Also ensures the tail is a HumanMessage — some providers reject a
- * conversation that ends with an assistant message.
- *
- * @param messages - Current state messages from the parent
- * @returns A sanitized copy, safe to pass to any provider as the child's
- *          input regardless of which tools the child has registered.
- */
-function prepareHandoffMessages(messages$1) {
-    if (messages$1.length === 0)
-        return messages$1;
-    /** Collect tool_result IDs so we know which tool_use blocks are paired */
-    const pairedToolCallIds = new Set();
-    for (const msg of messages$1) {
-        if (msg.getType() === 'tool') {
-            const tm = msg;
-            if (tm.tool_call_id)
-                pairedToolCallIds.add(tm.tool_call_id);
-        }
-    }
-    /**
-     * Pass 1: Drop all ToolMessages (paired ones are compacted in pass 2),
-     * rewrite AI messages with tool_calls into plain-text summaries, leave
-     * other messages untouched.
-     */
-    const cleaned = [];
-    for (const msg of messages$1) {
-        if (msg.getType() === 'tool')
-            continue;
-        if (msg.getType() !== 'ai') {
-            cleaned.push(msg);
-            continue;
-        }
-        const aiMsg = msg;
-        const toolCalls = aiMsg.tool_calls ?? [];
-        if (toolCalls.length === 0) {
-            cleaned.push(msg);
-            continue;
-        }
-        const textContent = extractAIText(aiMsg);
-        const toolSummaries = [];
-        for (const tc of toolCalls) {
-            if (tc.id != null && pairedToolCallIds.has(tc.id)) {
-                const toolResult = messages$1.find((m) => m.getType() === 'tool' && m.tool_call_id === tc.id);
-                const resultContent = toolResult
-                    ? typeof toolResult.content === 'string'
-                        ? toolResult.content.slice(0, 500)
-                        : '[complex result]'
-                    : '[no result]';
-                toolSummaries.push(`[Tool "${tc.name}": ${resultContent}]`);
-            }
-            // Orphaned tool_use blocks (no matching result) are silently dropped.
-        }
-        const parts = [textContent, ...toolSummaries].filter(Boolean);
-        if (parts.length > 0) {
-            cleaned.push(new messages.AIMessage({ content: parts.join('\n\n'), id: aiMsg.id }));
-        }
-    }
-    /**
-     * Ensure messages end with a HumanMessage. After stripping tool artifacts
-     * the tail may be an AIMessage, which Bedrock/VertexAI reject. Convert it
-     * to a HumanMessage preserving whatever text content was present, or drop
-     * it entirely if empty.
-     */
-    if (cleaned.length > 0 && cleaned[cleaned.length - 1].getType() === 'ai') {
-        const lastAI = cleaned[cleaned.length - 1];
-        const content = typeof lastAI.content === 'string' ? lastAI.content : '';
-        if (content.trim()) {
-            cleaned[cleaned.length - 1] = new messages.HumanMessage(`${HANDOFF_TAIL_CONTEXT_PREFIX}${content}`);
-        }
-        else {
-            cleaned.pop();
-        }
-    }
-    return cleaned;
-}
-/* -------------------------------------------------------------------------- */
-/*  Strategy 2: isolated fresh session (downstream scoped-subgraph child)     */
-/* -------------------------------------------------------------------------- */
-/**
- * Build an ISOLATED message context for a downstream scoped-subgraph node.
- *
- * Unlike `prepareHandoffMessages` (which cleans up tool_use artifacts but
- * preserves most of the parent history), this helper produces a fresh
- * minimal context containing only:
- *
- *   1. The original user request (first HumanMessage in the history)
- *   2. A synthetic HumanMessage summarizing the upstream agent's final
- *      text output and directing the downstream agent to act on it
- *
- * Tool_use / tool_result blocks from the upstream agent are discarded —
- * the downstream agent shouldn't reason about how the upstream agent did
- * its work, only about the result.
- *
- * This "fresh subagent session" pattern is the primary defense against
- * schema confusion / malformed tool_use JSON that occurs when downstream
- * models see a noisy upstream conversation.
- *
- * Defensive fallback: if the messages array contains neither a user
- * message nor a non-empty upstream AI message, return the input unchanged
- * so the caller still has something to invoke on. This only matters for
- * malformed state fixtures in tests.
- */
-function prepareIsolatedChildMessages(messages$1) {
-    if (messages$1.length === 0)
-        return messages$1;
-    /** First HumanMessage is the original user request */
-    const originalUser = messages$1.find((m) => m.getType() === 'human');
-    /** Most recent AIMessage with non-empty text content */
-    let upstreamText = '';
-    for (let i = messages$1.length - 1; i >= 0; i--) {
-        const msg = messages$1[i];
-        if (msg.getType() !== 'ai')
-            continue;
-        const text = extractAIText(msg);
-        if (text.trim()) {
-            upstreamText = text;
-            break;
-        }
-    }
-    const result = [];
-    if (originalUser)
-        result.push(originalUser);
-    if (upstreamText.trim()) {
-        result.push(new messages.HumanMessage(buildIsolatedChildPrompt(upstreamText)));
-    }
-    else if (result.length === 0) {
-        /** Defensive: nothing to isolate — fall back to raw messages */
-        return messages$1;
-    }
-    return result;
-}
-
-exports.HANDOFF_TAIL_CONTEXT_PREFIX = HANDOFF_TAIL_CONTEXT_PREFIX;
-exports.buildIsolatedChildPrompt = buildIsolatedChildPrompt;
-exports.prepareHandoffMessages = prepareHandoffMessages;
-exports.prepareIsolatedChildMessages = prepareIsolatedChildMessages;
-//# sourceMappingURL=childAgentContext.cjs.map

package/dist/cjs/utils/childAgentContext.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"childAgentContext.cjs","sources":["../../../src/utils/childAgentContext.ts"],"sourcesContent":["/**\n * Child-agent context preparation utilities.\n *\n * When a parent agent invokes a child agent — via handoff, sequence edge,\n * or scoped subgraph — the child cannot just receive `state.messages`\n * verbatim. The parent's conversation contains tool_use/tool_result blocks\n * that are (a) often incompatible with the child's tool registry, and\n * (b) actively harmful to the child's ability to reason cleanly about its\n * own task (noise → schema confusion → malformed tool_use).\n *\n * This module provides the two canonical strategies, extracted from\n * `MultiAgentGraph` so they can be unit-tested in isolation and reused by\n * future sub-agent orchestrators:\n *\n *   1. `prepareHandoffMessages` — \"cleaned parent history\"\n *      Used when the child still needs the orchestrator's context (it's\n *      the handoff target). Drops orphaned tool_use, compacts paired\n *      tool_use/tool_result into text summaries, and guarantees the tail\n *      is a HumanMessage so Bedrock/VertexAI won't reject the conversation\n *      with \"assistant message prefill\" errors.\n *\n *   2. `prepareIsolatedChildMessages` — \"fresh session\"\n *      Used for downstream sequence-node children inside a scoped subgraph.\n *      The child sees only the original user request plus a synthetic\n *      HumanMessage summarizing the upstream agent's final text output and\n *      directing the child to act. Raw upstream tool_use/tool_result blocks\n *      are discarded.\n *\n * Both helpers are pure functions over message arrays — no I/O, no\n * LangGraph coupling — so they can be exercised by unit tests with\n * synthetic message fixtures.\n */\n\nimport { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';\nimport type { AIMessageChunk, BaseMessage } from '@langchain/core/messages';\n\n/* -------------------------------------------------------------------------- */\n/*  Prompt template constants (kept outside the functions for reuse/tuning)   */\n/* -------------------------------------------------------------------------- */\n\n/**\n * Prefix injected in front of a trailing AIMessage when we flip it to a\n * HumanMessage to satisfy provider \"last message must be user\" rules.\n */\nexport const HANDOFF_TAIL_CONTEXT_PREFIX = '[Context from orchestrator]: ';\n\n/**\n * Directive task-framing wrapper for downstream scoped-subgraph children.\n *\n * Design notes — each line is load-bearing:\n *  - \"Prior step output\" names the upstream role without leaking the\n *    agent's internal id.\n *  - \"You MUST now perform...\" replaces ambiguity with obligation.\n *  - \"system instructions\" references the agent's stored system prompt\n *    as the source of task definition — so operators can tune behavior\n *    via data, not code.\n *  - The tool-first clause prevents small/fast models from stalling on a\n *    text-only acknowledgement when a tool action is expected.\n */\nexport function buildIsolatedChildPrompt(upstreamText: string): string {\n  return (\n    '## Prior step output\\n\\n' +\n    upstreamText +\n    '\\n\\n---\\n\\n' +\n    '## Your task\\n\\n' +\n    'The previous step in this workflow has completed. You MUST now ' +\n    'perform your own task as defined in your system instructions, ' +\n    \"using the prior step's output as input where relevant.\\n\\n\" +\n    'If your task requires calling a tool, call it directly — do not ' +\n    'ask for clarification and do not produce a text-only response when ' +\n    'a tool action is expected.'\n  );\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Internal helpers                                                          */\n/* -------------------------------------------------------------------------- */\n\n/**\n * Extract concatenated text content from an AI message's content field.\n * Handles both the string shape (OpenAI/plain) and the array-of-blocks\n * shape (Anthropic/Bedrock).\n */\nfunction extractAIText(msg: AIMessage | AIMessageChunk): string {\n  const content = msg.content;\n  if (typeof content === 'string') return content;\n  if (!Array.isArray(content)) return '';\n  return (content as Array<{ type?: string; text?: string }>)\n    .filter((b) => b.type === 'text' && typeof b.text === 'string')\n    .map((b) => b.text ?? '')\n    .join('\\n');\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Strategy 1: cleaned parent history (handoff target / root subgraph)       */\n/* -------------------------------------------------------------------------- */\n\n/**\n * Prepare messages for a handoff child agent.\n *\n * Handles two problems that break Bedrock/Anthropic conversations:\n *\n * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use`\n *    block for the handoff tool itself, with no matching `tool_result`.\n *    Providers (Bedrock/Anthropic) reject this.\n *\n * 2. **Paired tool_use/tool_result in history**: The child may not have\n *    the same tools as the parent. Bedrock requires `toolConfig` when any\n *    tool_use/tool_result blocks exist in the history. Compacting these\n *    into text summaries avoids the requirement and reduces context bloat.\n *\n * Also ensures the tail is a HumanMessage — some providers reject a\n * conversation that ends with an assistant message.\n *\n * @param messages - Current state messages from the parent\n * @returns A sanitized copy, safe to pass to any provider as the child's\n *          input regardless of which tools the child has registered.\n */\nexport function prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[] {\n  if (messages.length === 0) return messages;\n\n  /** Collect tool_result IDs so we know which tool_use blocks are paired */\n  const pairedToolCallIds = new Set<string>();\n  for (const msg of messages) {\n    if (msg.getType() === 'tool') {\n      const tm = msg as ToolMessage;\n      if (tm.tool_call_id) pairedToolCallIds.add(tm.tool_call_id);\n    }\n  }\n\n  /**\n   * Pass 1: Drop all ToolMessages (paired ones are compacted in pass 2),\n   * rewrite AI messages with tool_calls into plain-text summaries, leave\n   * other messages untouched.\n   */\n  const cleaned: BaseMessage[] = [];\n  for (const msg of messages) {\n    if (msg.getType() === 'tool') continue;\n\n    if (msg.getType() !== 'ai') {\n      cleaned.push(msg);\n      continue;\n    }\n\n    const aiMsg = msg as AIMessage | AIMessageChunk;\n    const toolCalls = aiMsg.tool_calls ?? [];\n    if (toolCalls.length === 0) {\n      cleaned.push(msg);\n      continue;\n    }\n\n    const textContent = extractAIText(aiMsg);\n\n    const toolSummaries: string[] = [];\n    for (const tc of toolCalls) {\n      if (tc.id != null && pairedToolCallIds.has(tc.id)) {\n        const toolResult = messages.find(\n          (m) =>\n            m.getType() === 'tool' && (m as ToolMessage).tool_call_id === tc.id\n        ) as ToolMessage | undefined;\n        const resultContent = toolResult\n          ? typeof toolResult.content === 'string'\n            ? toolResult.content.slice(0, 500)\n            : '[complex result]'\n          : '[no result]';\n        toolSummaries.push(`[Tool \"${tc.name}\": ${resultContent}]`);\n      }\n      // Orphaned tool_use blocks (no matching result) are silently dropped.\n    }\n\n    const parts = [textContent, ...toolSummaries].filter(Boolean);\n    if (parts.length > 0) {\n      cleaned.push(\n        new AIMessage({ content: parts.join('\\n\\n'), id: aiMsg.id })\n      );\n    }\n  }\n\n  /**\n   * Ensure messages end with a HumanMessage. After stripping tool artifacts\n   * the tail may be an AIMessage, which Bedrock/VertexAI reject. Convert it\n   * to a HumanMessage preserving whatever text content was present, or drop\n   * it entirely if empty.\n   */\n  if (cleaned.length > 0 && cleaned[cleaned.length - 1].getType() === 'ai') {\n    const lastAI = cleaned[cleaned.length - 1];\n    const content = typeof lastAI.content === 'string' ? lastAI.content : '';\n    if (content.trim()) {\n      cleaned[cleaned.length - 1] = new HumanMessage(\n        `${HANDOFF_TAIL_CONTEXT_PREFIX}${content}`\n      );\n    } else {\n      cleaned.pop();\n    }\n  }\n\n  return cleaned;\n}\n\n/* -------------------------------------------------------------------------- */\n/*  Strategy 2: isolated fresh session (downstream scoped-subgraph child)     */\n/* -------------------------------------------------------------------------- */\n\n/**\n * Build an ISOLATED message context for a downstream scoped-subgraph node.\n *\n * Unlike `prepareHandoffMessages` (which cleans up tool_use artifacts but\n * preserves most of the parent history), this helper produces a fresh\n * minimal context containing only:\n *\n *   1. The original user request (first HumanMessage in the history)\n *   2. A synthetic HumanMessage summarizing the upstream agent's final\n *      text output and directing the downstream agent to act on it\n *\n * Tool_use / tool_result blocks from the upstream agent are discarded —\n * the downstream agent shouldn't reason about how the upstream agent did\n * its work, only about the result.\n *\n * This \"fresh subagent session\" pattern is the primary defense against\n * schema confusion / malformed tool_use JSON that occurs when downstream\n * models see a noisy upstream conversation.\n *\n * Defensive fallback: if the messages array contains neither a user\n * message nor a non-empty upstream AI message, return the input unchanged\n * so the caller still has something to invoke on. This only matters for\n * malformed state fixtures in tests.\n */\nexport function prepareIsolatedChildMessages(\n  messages: BaseMessage[]\n): BaseMessage[] {\n  if (messages.length === 0) return messages;\n\n  /** First HumanMessage is the original user request */\n  const originalUser = messages.find((m) => m.getType() === 'human');\n\n  /** Most recent AIMessage with non-empty text content */\n  let upstreamText = '';\n  for (let i = messages.length - 1; i >= 0; i--) {\n    const msg = messages[i];\n    if (msg.getType() !== 'ai') continue;\n    const text = extractAIText(msg as AIMessage | AIMessageChunk);\n    if (text.trim()) {\n      upstreamText = text;\n      break;\n    }\n  }\n\n  const result: BaseMessage[] = [];\n  if (originalUser) result.push(originalUser);\n\n  if (upstreamText.trim()) {\n    result.push(new HumanMessage(buildIsolatedChildPrompt(upstreamText)));\n  } else if (result.length === 0) {\n    /** Defensive: nothing to isolate — fall back to raw messages */\n    return messages;\n  }\n\n  return result;\n}\n"],"names":["messages","AIMessage","HumanMessage"],"mappings":"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"}