@illuma-ai/agents 1.1.28 → 1.3.1

package/dist/cjs/tools/memory/memoryGetTool.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+var tools = require('@langchain/core/tools');
+var constants = require('../../memory/constants.cjs');
+var shared = require('./shared.cjs');
+
+/**
+ * `memory_get` — safe snippet read.
+ *
+ * Port of upstream `createMemoryGetTool` at
+ * `upstream reference`.
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+function createMemoryGetTool(binding) {
+    return tools.tool(async (args) => {
+        try {
+            const result = await binding.backend.get(binding.scope, {
+                path: args.path,
+                from: args.from,
+                lines: args.lines,
+            });
+            if (!result) {
+                const payload = { path: args.path, text: '' };
+                return JSON.stringify(payload);
+            }
+            const payload = {
+                path: result.path,
+                text: result.text,
+            };
+            return JSON.stringify(payload);
+        }
+        catch (err) {
+            const payload = {
+                path: args.path,
+                text: '',
+                disabled: true,
+                error: err instanceof Error ? err.message : String(err),
+            };
+            return JSON.stringify(payload);
+        }
+    }, {
+        name: constants.MEMORY_GET_TOOL_NAME,
+        description: constants.MEMORY_GET_DESCRIPTION,
+        schema: shared.MemoryGetSchema,
+    });
+}
+
+exports.createMemoryGetTool = createMemoryGetTool;
+//# sourceMappingURL=memoryGetTool.cjs.map

package/dist/cjs/tools/memory/memoryGetTool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryGetTool.cjs","sources":["../../../../src/tools/memory/memoryGetTool.ts"],"sourcesContent":["/**\n * `memory_get` — safe snippet read.\n *\n * Port of upstream `createMemoryGetTool` at\n * `upstream reference`.\n */\nimport { tool } from '@langchain/core/tools';\nimport {\n  MEMORY_GET_DESCRIPTION,\n  MEMORY_GET_TOOL_NAME,\n} from '@/memory/constants';\nimport {\n  MemoryGetSchema,\n  type MemoryGetToolResult,\n  type MemoryToolBinding,\n} from './shared';\n\n// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\nexport function createMemoryGetTool(binding: MemoryToolBinding) {\n  return tool(\n    async (args): Promise<string> => {\n      try {\n        const result = await binding.backend.get(binding.scope, {\n          path: args.path,\n          from: args.from,\n          lines: args.lines,\n        });\n        if (!result) {\n          const payload: MemoryGetToolResult = { path: args.path, text: '' };\n          return JSON.stringify(payload);\n        }\n        const payload: MemoryGetToolResult = {\n          path: result.path,\n          text: result.text,\n        };\n        return JSON.stringify(payload);\n      } catch (err) {\n        const payload: MemoryGetToolResult = {\n          path: args.path,\n          text: '',\n          disabled: true,\n          error: err instanceof Error ? err.message : String(err),\n        };\n        return JSON.stringify(payload);\n      }\n    },\n    {\n      name: MEMORY_GET_TOOL_NAME,\n      description: MEMORY_GET_DESCRIPTION,\n      schema: MemoryGetSchema,\n    }\n  );\n}\n"],"names":["tool","MEMORY_GET_TOOL_NAME","MEMORY_GET_DESCRIPTION","MemoryGetSchema"],"mappings":";;;;;;AAAA;;;;;AAKG;AAYH;AACM,SAAU,mBAAmB,CAAC,OAA0B,EAAA;AAC5D,IAAA,OAAOA,UAAI,CACT,OAAO,IAAI,KAAqB;AAC9B,QAAA,IAAI;AACF,YAAA,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE;gBACtD,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;AAClB,aAAA,CAAC;YACF,IAAI,CAAC,MAAM,EAAE;AACX,gBAAA,MAAM,OAAO,GAAwB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;AAClE,gBAAA,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAChC;AACA,YAAA,MAAM,OAAO,GAAwB;gBACnC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB;AACD,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAChC;QAAE,OAAO,GAAG,EAAE;AACZ,YAAA,MAAM,OAAO,GAAwB;gBACnC,IAAI,EAAE,IAAI,CAAC,IAAI;AACf,gBAAA,IAAI,EAAE,EAAE;AACR,gBAAA,QAAQ,EAAE,IAAI;AACd,gBAAA,KAAK,EAAE,GAAG,YAAY,KAAK,GAAG,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC;aACxD;AACD,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAChC;AACF,IAAA,CAAC,EACD;AACE,QAAA,IAAI,EAAEC,8BAAoB;AAC1B,QAAA,WAAW,EAAEC,gCAAsB;AACnC,QAAA,MAAM,EAAEC,sBAAe;AACxB,KAAA,CACF;AACH;;;;"}

package/dist/cjs/tools/memory/memorySearchTool.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+var tools = require('@langchain/core/tools');
+var constants = require('../../memory/constants.cjs');
+var shared = require('./shared.cjs');
+
+/**
+ * `memory_search` — the mandatory-recall tool.
+ *
+ * Port of upstream `createMemorySearchTool` at
+ * `upstream reference`. The tool description
+ * is verbatim "Mandatory recall step..." from upstream — this is the load-
+ * bearing line that turns "the agent may recall" into "the agent will recall".
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+function createMemorySearchTool(binding) {
+    return tools.tool(async (args) => {
+        try {
+            const entries = await binding.backend.search(binding.scope, args.query, {
+                maxResults: args.maxResults,
+                minScore: args.minScore,
+                mmr: binding.searchOptions?.mmr,
+                temporalDecay: binding.searchOptions?.temporalDecay,
+                citations: binding.searchOptions?.citations,
+            });
+            const clamped = shared.clampResultsByInjectedChars(entries, binding.maxInjectedChars);
+            // [phase2-recall-tracking] debug: fire-and-forget best-effort record
+            if (binding.recallTracker && clamped.length > 0) {
+                void binding.recallTracker
+                    .record({
+                    agentId: binding.scope.agentId,
+                    query: args.query,
+                    hits: clamped.map((e) => ({
+                        id: e.id,
+                        path: e.path,
+                        score: e.score,
+                    })),
+                })
+                    .catch(() => undefined);
+            }
+            const payload = {
+                results: clamped.map((entry) => ({
+                    id: entry.id,
+                    path: entry.path,
+                    content: entry.content,
+                    score: entry.score,
+                    createdAt: entry.createdAt,
+                    citation: entry.citation,
+                })),
+            };
+            return JSON.stringify(payload);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return JSON.stringify(shared.buildMemorySearchUnavailableResult(message));
+        }
+    }, {
+        name: constants.MEMORY_SEARCH_TOOL_NAME,
+        description: constants.MEMORY_SEARCH_DESCRIPTION,
+        schema: shared.MemorySearchSchema,
+    });
+}
+
+exports.createMemorySearchTool = createMemorySearchTool;
+//# sourceMappingURL=memorySearchTool.cjs.map

package/dist/cjs/tools/memory/memorySearchTool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memorySearchTool.cjs","sources":["../../../../src/tools/memory/memorySearchTool.ts"],"sourcesContent":["/**\n * `memory_search` — the mandatory-recall tool.\n *\n * Port of upstream `createMemorySearchTool` at\n * `upstream reference`. The tool description\n * is verbatim \"Mandatory recall step...\" from upstream — this is the load-\n * bearing line that turns \"the agent may recall\" into \"the agent will recall\".\n */\nimport { tool } from '@langchain/core/tools';\nimport {\n  MEMORY_SEARCH_DESCRIPTION,\n  MEMORY_SEARCH_TOOL_NAME,\n} from '@/memory/constants';\nimport {\n  buildMemorySearchUnavailableResult,\n  clampResultsByInjectedChars,\n  MemorySearchSchema,\n  type MemorySearchToolResult,\n  type MemoryToolBinding,\n} from './shared';\n\n// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\nexport function createMemorySearchTool(binding: MemoryToolBinding) {\n  return tool(\n    async (args): Promise<string> => {\n      try {\n        const entries = await binding.backend.search(\n          binding.scope,\n          args.query,\n          {\n            maxResults: args.maxResults,\n            minScore: args.minScore,\n            mmr: binding.searchOptions?.mmr,\n            temporalDecay: binding.searchOptions?.temporalDecay,\n            citations: binding.searchOptions?.citations,\n          }\n        );\n        const clamped = clampResultsByInjectedChars(\n          entries,\n          binding.maxInjectedChars\n        );\n\n        // [phase2-recall-tracking] debug: fire-and-forget best-effort record\n        if (binding.recallTracker && clamped.length > 0) {\n          void binding.recallTracker\n            .record({\n              agentId: binding.scope.agentId,\n              query: args.query,\n              hits: clamped.map((e) => ({\n                id: e.id,\n                path: e.path,\n                score: e.score,\n              })),\n            })\n            .catch(() => undefined);\n        }\n\n        const payload: MemorySearchToolResult = {\n          results: clamped.map((entry) => ({\n            id: entry.id,\n            path: entry.path,\n            content: entry.content,\n            score: entry.score,\n            createdAt: entry.createdAt,\n            citation: entry.citation,\n          })),\n        };\n        return JSON.stringify(payload);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        return JSON.stringify(buildMemorySearchUnavailableResult(message));\n      }\n    },\n    {\n      name: MEMORY_SEARCH_TOOL_NAME,\n      description: MEMORY_SEARCH_DESCRIPTION,\n      schema: MemorySearchSchema,\n    }\n  );\n}\n"],"names":["tool","clampResultsByInjectedChars","buildMemorySearchUnavailableResult","MEMORY_SEARCH_TOOL_NAME","MEMORY_SEARCH_DESCRIPTION","MemorySearchSchema"],"mappings":";;;;;;AAAA;;;;;;;AAOG;AAcH;AACM,SAAU,sBAAsB,CAAC,OAA0B,EAAA;AAC/D,IAAA,OAAOA,UAAI,CACT,OAAO,IAAI,KAAqB;AAC9B,QAAA,IAAI;AACF,YAAA,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAC1C,OAAO,CAAC,KAAK,EACb,IAAI,CAAC,KAAK,EACV;gBACE,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;AACvB,gBAAA,GAAG,EAAE,OAAO,CAAC,aAAa,EAAE,GAAG;AAC/B,gBAAA,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,aAAa;AACnD,gBAAA,SAAS,EAAE,OAAO,CAAC,aAAa,EAAE,SAAS;AAC5C,aAAA,CACF;YACD,MAAM,OAAO,GAAGC,kCAA2B,CACzC,OAAO,EACP,OAAO,CAAC,gBAAgB,CACzB;;YAGD,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE;gBAC/C,KAAK,OAAO,CAAC;AACV,qBAAA,MAAM,CAAC;AACN,oBAAA,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;oBAC9B,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM;wBACxB,EAAE,EAAE,CAAC,CAAC,EAAE;wBACR,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,KAAK,EAAE,CAAC,CAAC,KAAK;AACf,qBAAA,CAAC,CAAC;iBACJ;AACA,qBAAA,KAAK,CAAC,MAAM,SAAS,CAAC;YAC3B;AAEA,YAAA,MAAM,OAAO,GAA2B;gBACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM;oBAC/B,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;AACzB,iBAAA,CAAC,CAAC;aACJ;AACD,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAChC;QAAE,OAAO,GAAG,EAAE;AACZ,YAAA,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,GAAG,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC;YAChE,OAAO,IAAI,CAAC,SAAS,CAACC,yCAAkC,CAAC,OAAO,CAAC,CAAC;QACpE;AACF,IAAA,CAAC,EACD;AACE,QAAA,IAAI,EAAEC,iCAAuB;AAC7B,QAAA,WAAW,EAAEC,mCAAyB;AACtC,QAAA,MAAM,EAAEC,yBAAkB;AAC3B,KAAA,CACF;AACH;;;;"}

package/dist/cjs/tools/memory/shared.cjs

@@ -0,0 +1,106 @@
+'use strict';
+
+var zod = require('zod');
+var constants = require('../../memory/constants.cjs');
+
+/**
+ * Shared Zod schemas + helpers for the memory tool family.
+ *
+ * The tool schemas deliberately do NOT expose `agent_id` or `user_id`. Scope
+ * is captured in a closure at tool construction time by {@link buildMemoryTools},
+ * so even a hallucinated tool call with extra fields cannot influence it.
+ */
+const MemorySearchSchema = zod.z.object({
+    query: zod.z.string().describe('Natural-language query to search memory for'),
+    maxResults: zod.z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe('Maximum number of results to return (default 10)'),
+    minScore: zod.z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Minimum hybrid score (0..1) below which results are dropped'),
+});
+const MemoryGetSchema = zod.z.object({
+    path: zod.z
+        .string()
+        .describe('Memory path, e.g. "memory/decisions.md". Must start with "memory/"'),
+    from: zod.z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Starting line number (1-indexed)'),
+    lines: zod.z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Number of lines to read starting at `from`'),
+});
+const MemoryAppendSchema = zod.z.object({
+    path: zod.z
+        .string()
+        .describe('Memory path to append to (e.g. "memory/decisions.md"). Must start with "memory/"'),
+    content: zod.z
+        .string()
+        .min(1)
+        .describe("Note content in the agent's own voice. Markdown allowed. Each call appends an immutable entry."),
+});
+function buildMemorySearchUnavailableResult(error) {
+    const reason = (error ?? 'memory search unavailable').trim() ||
+        'memory search unavailable';
+    const isQuota = /insufficient_quota|quota|429/i.test(reason);
+    return {
+        results: [],
+        disabled: true,
+        unavailable: true,
+        error: reason,
+        warning: isQuota
+            ? 'Memory search is unavailable because the embedding provider quota is exhausted.'
+            : 'Memory search is unavailable due to an embedding/provider error.',
+        action: isQuota
+            ? 'Top up or switch embedding provider, then retry memory_search.'
+            : 'Check embedding provider configuration and retry memory_search.',
+    };
+}
+/**
+ * Clamp a ranked result list to a total character budget.
+ * Ported from upstream `tools.citations.ts::clampResultsByInjectedChars`.
+ */
+function clampResultsByInjectedChars(results, maxInjectedChars = constants.DEFAULT_MAX_INJECTED_CHARS) {
+    const out = [];
+    let total = 0;
+    for (const result of results) {
+        const size = result.content.length ?? 0;
+        if (total + size > maxInjectedChars && out.length > 0)
+            break;
+        out.push(result);
+        total += size;
+    }
+    return out;
+}
+function assertAppendAllowed(path) {
+    if (!path || !path.startsWith(constants.MEMORY_PATH_PREFIX)) {
+        throw new Error(`memory_append path must start with "${constants.MEMORY_PATH_PREFIX}"`);
+    }
+}
+/** Normalise an append call into the backend input shape. */
+function toAppendInput(args) {
+    assertAppendAllowed(args.path);
+    return { path: args.path, content: args.content };
+}
+
+exports.MemoryAppendSchema = MemoryAppendSchema;
+exports.MemoryGetSchema = MemoryGetSchema;
+exports.MemorySearchSchema = MemorySearchSchema;
+exports.assertAppendAllowed = assertAppendAllowed;
+exports.buildMemorySearchUnavailableResult = buildMemorySearchUnavailableResult;
+exports.clampResultsByInjectedChars = clampResultsByInjectedChars;
+exports.toAppendInput = toAppendInput;
+//# sourceMappingURL=shared.cjs.map

package/dist/cjs/tools/memory/shared.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.cjs","sources":["../../../../src/tools/memory/shared.ts"],"sourcesContent":["/**\n * Shared Zod schemas + helpers for the memory tool family.\n *\n * The tool schemas deliberately do NOT expose `agent_id` or `user_id`. Scope\n * is captured in a closure at tool construction time by {@link buildMemoryTools},\n * so even a hallucinated tool call with extra fields cannot influence it.\n */\nimport { z } from 'zod';\nimport {\n  DEFAULT_MAX_INJECTED_CHARS,\n  MEMORY_PATH_PREFIX,\n} from '@/memory/constants';\nimport type {\n  MemoryAppendInput,\n  MemoryBackend,\n  MemoryEntry,\n  MemoryScope,\n} from '@/memory/types';\n\nexport const MemorySearchSchema = z.object({\n  query: z.string().describe('Natural-language query to search memory for'),\n  maxResults: z\n    .number()\n    .int()\n    .min(1)\n    .max(50)\n    .optional()\n    .describe('Maximum number of results to return (default 10)'),\n  minScore: z\n    .number()\n    .min(0)\n    .max(1)\n    .optional()\n    .describe('Minimum hybrid score (0..1) below which results are dropped'),\n});\n\nexport const MemoryGetSchema = z.object({\n  path: z\n    .string()\n    .describe(\n      'Memory path, e.g. \"memory/decisions.md\". Must start with \"memory/\"'\n    ),\n  from: z\n    .number()\n    .int()\n    .min(1)\n    .optional()\n    .describe('Starting line number (1-indexed)'),\n  lines: z\n    .number()\n    .int()\n    .min(1)\n    .optional()\n    .describe('Number of lines to read starting at `from`'),\n});\n\nexport const MemoryAppendSchema = z.object({\n  path: z\n    .string()\n    .describe(\n      'Memory path to append to (e.g. \"memory/decisions.md\"). Must start with \"memory/\"'\n    ),\n  content: z\n    .string()\n    .min(1)\n    .describe(\n      \"Note content in the agent's own voice. Markdown allowed. Each call appends an immutable entry.\"\n    ),\n});\n\nexport type MemorySearchArgs = z.infer<typeof MemorySearchSchema>;\nexport type MemoryGetArgs = z.infer<typeof MemoryGetSchema>;\nexport type MemoryAppendArgs = z.infer<typeof MemoryAppendSchema>;\n\n/** Shape returned by `memory_search` — serialised as the tool result string. */\nexport interface MemorySearchToolResult {\n  results: Array<\n    Pick<MemoryEntry, 'id' | 'path' | 'content' | 'score' | 'createdAt'> & {\n      citation?: string;\n    }\n  >;\n  disabled?: boolean;\n  unavailable?: boolean;\n  error?: string;\n  warning?: string;\n  action?: string;\n}\n\n/** Shape returned by `memory_get`. */\nexport interface MemoryGetToolResult {\n  path: string;\n  text: string;\n  disabled?: boolean;\n  error?: string;\n}\n\nexport function buildMemorySearchUnavailableResult(\n  error: string | undefined\n): MemorySearchToolResult {\n  const reason =\n    (error ?? 'memory search unavailable').trim() ||\n    'memory search unavailable';\n  const isQuota = /insufficient_quota|quota|429/i.test(reason);\n  return {\n    results: [],\n    disabled: true,\n    unavailable: true,\n    error: reason,\n    warning: isQuota\n      ? 'Memory search is unavailable because the embedding provider quota is exhausted.'\n      : 'Memory search is unavailable due to an embedding/provider error.',\n    action: isQuota\n      ? 'Top up or switch embedding provider, then retry memory_search.'\n      : 'Check embedding provider configuration and retry memory_search.',\n  };\n}\n\n/**\n * Clamp a ranked result list to a total character budget.\n * Ported from upstream `tools.citations.ts::clampResultsByInjectedChars`.\n */\nexport function clampResultsByInjectedChars<T extends { content: string }>(\n  results: T[],\n  maxInjectedChars: number = DEFAULT_MAX_INJECTED_CHARS\n): T[] {\n  const out: T[] = [];\n  let total = 0;\n  for (const result of results) {\n    const size = result.content.length ?? 0;\n    if (total + size > maxInjectedChars && out.length > 0) break;\n    out.push(result);\n    total += size;\n  }\n  return out;\n}\n\nexport interface MemoryToolBinding {\n  backend: MemoryBackend;\n  scope: MemoryScope;\n  maxInjectedChars?: number;\n  /** Phase 2 — per-call search options propagated into backend.search. */\n  searchOptions?: {\n    mmr?: { enabled?: boolean; lambda?: number };\n    temporalDecay?: { enabled?: boolean; halfLifeDays?: number };\n    citations?: 'on' | 'off' | 'auto';\n  };\n  /** Phase 2 — optional best-effort recall recorder. */\n  recallTracker?: {\n    record(params: {\n      agentId: string;\n      query: string;\n      hits: Array<{ id: string; path: string; score: number }>;\n    }): Promise<void>;\n  };\n}\n\nexport function assertAppendAllowed(path: string): void {\n  if (!path || !path.startsWith(MEMORY_PATH_PREFIX)) {\n    throw new Error(\n      `memory_append path must start with \"${MEMORY_PATH_PREFIX}\"`\n    );\n  }\n}\n\n/** Normalise an append call into the backend input shape. */\nexport function toAppendInput(args: MemoryAppendArgs): MemoryAppendInput {\n  assertAppendAllowed(args.path);\n  return { path: args.path, content: args.content };\n}\n"],"names":["z","DEFAULT_MAX_INJECTED_CHARS","MEMORY_PATH_PREFIX"],"mappings":";;;;;AAAA;;;;;;AAMG;AAaI,MAAM,kBAAkB,GAAGA,KAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;AACzE,IAAA,UAAU,EAAEA;AACT,SAAA,MAAM;AACN,SAAA,GAAG;SACH,GAAG,CAAC,CAAC;SACL,GAAG,CAAC,EAAE;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,kDAAkD,CAAC;AAC/D,IAAA,QAAQ,EAAEA;AACP,SAAA,MAAM;SACN,GAAG,CAAC,CAAC;SACL,GAAG,CAAC,CAAC;AACL,SAAA,QAAQ;SACR,QAAQ,CAAC,6DAA6D,CAAC;AAC3E,CAAA;AAEM,MAAM,eAAe,GAAGA,KAAC,CAAC,MAAM,CAAC;AACtC,IAAA,IAAI,EAAEA;AACH,SAAA,MAAM;SACN,QAAQ,CACP,oEAAoE,CACrE;AACH,IAAA,IAAI,EAAEA;AACH,SAAA,MAAM;AACN,SAAA,GAAG;SACH,GAAG,CAAC,CAAC;AACL,SAAA,QAAQ;SACR,QAAQ,CAAC,kCAAkC,CAAC;AAC/C,IAAA,KAAK,EAAEA;AACJ,SAAA,MAAM;AACN,SAAA,GAAG;SACH,GAAG,CAAC,CAAC;AACL,SAAA,QAAQ;SACR,QAAQ,CAAC,4CAA4C,CAAC;AAC1D,CAAA;AAEM,MAAM,kBAAkB,GAAGA,KAAC,CAAC,MAAM,CAAC;AACzC,IAAA,IAAI,EAAEA;AACH,SAAA,MAAM;SACN,QAAQ,CACP,kFAAkF,CACnF;AACH,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;SACN,GAAG,CAAC,CAAC;SACL,QAAQ,CACP,gGAAgG,CACjG;AACJ,CAAA;AA4BK,SAAU,kCAAkC,CAChD,KAAyB,EAAA;IAEzB,MAAM,MAAM,GACV,CAAC,KAAK,IAAI,2BAA2B,EAAE,IAAI,EAAE;AAC7C,QAAA,2BAA2B;IAC7B,MAAM,OAAO,GAAG,+BAA+B,CAAC,IAAI,CAAC,MAAM,CAAC;IAC5D,OAAO;AACL,QAAA,OAAO,EAAE,EAAE;AACX,QAAA,QAAQ,EAAE,IAAI;AACd,QAAA,WAAW,EAAE,IAAI;AACjB,QAAA,KAAK,EAAE,MAAM;AACb,QAAA,OAAO,EAAE;AACP,cAAE;AACF,cAAE,kEAAkE;AACtE,QAAA,MAAM,EAAE;AACN,cAAE;AACF,cAAE,iEAAiE;KACtE;AACH;AAEA;;;AAGG;SACa,2BAA2B,CACzC,OAAY,EACZ,mBAA2BC,oCAA0B,EAAA;IAErD,MAAM,GAAG,GAAQ,EAAE;IACnB,IAAI,KAAK,GAAG,CAAC;AACb,IAAA,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC;QACvC,IAAI,KAAK,GAAG,IAAI,GAAG,gBAAgB,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;YAAE;AACvD,QAAA,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;QAChB,KAAK,IAAI,IAAI;IACf;AACA,IAAA,OAAO,GAAG;AACZ;AAsBM,SAAU,mBAAmB,CAAC,IAAY,EAAA;IAC9C,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAACC,4BAAkB,CAAC,EAAE;AACjD,QAAA,MAAM,IAAI,KAAK,CACb,uCAAuCA,4BAAkB,CAAA,CAAA,CAAG,CAC7D;IACH;AACF;AAEA;AACM,SAAU,aAAa,CAAC,IAAsB,EAAA;AAClD,IAAA,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC;AAC9B,IAAA,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;AACnD;;;;;;;;;;"}

package/dist/cjs/types/graph.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"graph.cjs","sources":["../../../src/types/graph.ts"],"sourcesContent":["// src/types/graph.ts\nimport type {\n  START,\n  StateType,\n  UpdateType,\n  StateGraph,\n  StateGraphArgs,\n  StateDefinition,\n  CompiledStateGraph,\n  BinaryOperatorAggregate,\n} from '@langchain/langgraph';\nimport type { BindToolsInput } from '@langchain/core/language_models/chat_models';\nimport type {\n  BaseMessage,\n  AIMessageChunk,\n  SystemMessage,\n} from '@langchain/core/messages';\nimport type { RunnableConfig, Runnable } from '@langchain/core/runnables';\nimport type { ChatGenerationChunk } from '@langchain/core/outputs';\nimport type { GoogleAIToolType } from '@langchain/google-common';\nimport type {\n  ToolMap,\n  ToolEndEvent,\n  GenericTool,\n  LCTool,\n  ToolApprovalConfig,\n} from '@/types/tools';\nimport type { Providers, Callback, GraphNodeKeys } from '@/common';\nimport type { StandardGraph, MultiAgentGraph } from '@/graphs';\nimport type { ClientOptions } from '@/types/llm';\nimport type {\n  RunStep,\n  RunStepDeltaEvent,\n  MessageDeltaEvent,\n  ReasoningDeltaEvent,\n} from '@/types/stream';\nimport type { TokenCounter } from '@/types/run';\n\n/** Interface for bound model with stream and invoke methods */\nexport interface ChatModel {\n  stream?: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AsyncIterable<AIMessageChunk>>;\n  invoke: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AIMessageChunk>;\n}\n\n/** Payload for ON_AGENT_TRANSITION events */\nexport type AgentTransitionEvent = {\n  sourceAgentId?: string;\n  sourceAgentName?: string;\n  destinationAgentId: string;\n  destinationAgentName: string;\n  edgeType: string; // 'handoff' | 'transfer' | 'sequence'\n  timestamp: number;\n  /** When true, this event signals handoff completion (child → parent return) */\n  isCompletion?: boolean;\n  /** Duration of child agent execution in milliseconds (only on completion events) */\n  durationMs?: number;\n  /** Length of child agent result text in characters (only on completion events) */\n  resultLength?: number;\n};\n\nexport type GraphNode = GraphNodeKeys | typeof START;\nexport type ClientCallback<T extends unknown[]> = (\n  graph: StandardGraph,\n  ...args: T\n) => void;\n\nexport type ClientCallbacks = {\n  [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;\n  [Callback.TOOL_START]?: ClientCallback<unknown[]>;\n  [Callback.TOOL_END]?: ClientCallback<unknown[]>;\n};\n\nexport type SystemCallbacks = {\n  [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<\n    infer Args\n  >\n    ? (...args: Args) => void\n    : never;\n};\n\nexport type BaseGraphState = {\n  messages: BaseMessage[];\n  /**\n   * Structured response when using structured output mode.\n   * Contains the validated JSON response conforming to the configured schema.\n   */\n  structuredResponse?: Record<string, unknown>;\n};\n\nexport type MultiAgentGraphState = BaseGraphState & {\n  agentMessages?: BaseMessage[];\n};\n\nexport type IState = BaseGraphState;\n\nexport interface EventHandler {\n  handle(\n    event: string,\n    data:\n      | StreamEventData\n      | ModelEndData\n      | RunStep\n      | RunStepDeltaEvent\n      | MessageDeltaEvent\n      | ReasoningDeltaEvent\n      | { result: ToolEndEvent },\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): void | Promise<void>;\n}\n\nexport type GraphStateChannels<T extends BaseGraphState> =\n  StateGraphArgs<T>['channels'];\n\nexport type Workflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = StateGraph<T, U, N>;\n\nexport type CompiledWorkflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = CompiledStateGraph<T, U, N>;\n\nexport type CompiledStateWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledMultiAgentWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledAgentWorfklow = CompiledStateGraph<\n  {\n    messages: BaseMessage[];\n  },\n  {\n    messages?: BaseMessage[] | undefined;\n  },\n  '__start__' | `agent=${string}` | `tools=${string}`,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition,\n  {\n    [x: `agent=${string}`]: Partial<BaseGraphState>;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [x: `tools=${string}`]: any;\n  }\n>;\n\nexport type SystemRunnable =\n  | Runnable<\n      BaseMessage[],\n      (BaseMessage | SystemMessage)[],\n      RunnableConfig<Record<string, unknown>>\n    >\n  | undefined;\n\n/**\n * Optional compile options passed to workflow.compile().\n * These are intentionally untyped to avoid coupling to library internals.\n */\nexport type CompileOptions = {\n  // A checkpointer instance (e.g., MemorySaver, SQL saver)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  checkpointer?: any;\n  interruptBefore?: string[];\n  interruptAfter?: string[];\n  /**\n   * Human-in-the-loop tool approval configuration.\n   * When set, tools matching the policy will trigger an interrupt()\n   * before execution, pausing the graph for human approval.\n   * Requires a checkpointer to be set for interrupt/resume to work.\n   */\n  toolApprovalConfig?: ToolApprovalConfig;\n};\n\nexport type EventStreamCallbackHandlerInput =\n  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<\n    infer T,\n    'autoClose'\n  >\n    ? T\n    : never;\n\nexport type StreamChunk =\n  | (ChatGenerationChunk & {\n      message: AIMessageChunk;\n    })\n  | AIMessageChunk;\n\n/**\n * Data associated with a StreamEvent.\n */\nexport type StreamEventData = {\n  /**\n   * The input passed to the runnable that generated the event.\n   * Inputs will sometimes be available at the *START* of the runnable, and\n   * sometimes at the *END* of the runnable.\n   * If a runnable is able to stream its inputs, then its input by definition\n   * won't be known until the *END* of the runnable when it has finished streaming\n   * its inputs.\n   */\n  input?: unknown;\n  /**\n   * The output of the runnable that generated the event.\n   * Outputs will only be available at the *END* of the runnable.\n   * For most runnables, this field can be inferred from the `chunk` field,\n   * though there might be some exceptions for special cased runnables (e.g., like\n   * chat models), which may return more information.\n   */\n  output?: unknown;\n  /**\n   * A streaming chunk from the output that generated the event.\n   * chunks support addition in general, and adding them up should result\n   * in the output of the runnable that generated the event.\n   */\n  chunk?: StreamChunk;\n  /**\n   * Runnable config for invoking other runnables within handlers.\n   */\n  config?: RunnableConfig;\n  /**\n   * Custom result from the runnable that generated the event.\n   */\n  result?: unknown;\n  /**\n   * Custom field to indicate the event was manually emitted, and may have been handled already\n   */\n  emitted?: boolean;\n};\n\n/**\n * A streaming event.\n *\n * Schema of a streaming event which is produced from the streamEvents method.\n */\nexport type StreamEvent = {\n  /**\n   * Event names are of the format: on_[runnable_type]_(start|stream|end).\n   *\n   * Runnable types are one of:\n   * - llm - used by non chat models\n   * - chat_model - used by chat models\n   * - prompt --  e.g., ChatPromptTemplate\n   * - tool -- LangChain tools\n   * - chain - most Runnables are of this type\n   *\n   * Further, the events are categorized as one of:\n   * - start - when the runnable starts\n   * - stream - when the runnable is streaming\n   * - end - when the runnable ends\n   *\n   * start, stream and end are associated with slightly different `data` payload.\n   *\n   * Please see the documentation for `EventData` for more details.\n   */\n  event: string;\n  /** The name of the runnable that generated the event. */\n  name: string;\n  /**\n   * An randomly generated ID to keep track of the execution of the given runnable.\n   *\n   * Each child runnable that gets invoked as part of the execution of a parent runnable\n   * is assigned its own unique ID.\n   */\n  run_id: string;\n  /**\n   * Tags associated with the runnable that generated this event.\n   * Tags are always inherited from parent runnables.\n   */\n  tags?: string[];\n  /** Metadata associated with the runnable that generated this event. */\n  metadata: Record<string, unknown>;\n  /**\n   * Event data.\n   *\n   * The contents of the event data depend on the event type.\n   */\n  data: StreamEventData;\n};\n\nexport type GraphConfig = {\n  provider: string;\n  thread_id?: string;\n  run_id?: string;\n};\n\nexport type PartMetadata = {\n  progress?: number;\n  asset_pointer?: string;\n  status?: string;\n  action?: boolean;\n  output?: string;\n};\n\nexport type ModelEndData =\n  | (StreamEventData & { output: AIMessageChunk | undefined })\n  | undefined;\nexport type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];\nexport type StandardGraphInput = {\n  runId?: string;\n  signal?: AbortSignal;\n  agents: AgentInputs[];\n  tokenCounter?: TokenCounter;\n  indexTokenCountMap?: Record<string, number>;\n};\n\n/**\n * Configuration for an approval gate placed on a sequence edge.\n * When present, the graph inserts an approval gate node between the source\n * and destination agents. The gate ALWAYS fires (regardless of ExecutionContext)\n * and calls interrupt() to pause the graph for human approval.\n */\nexport type ApprovalGateConfig = {\n  /** Unique identifier for this gate (used as node ID suffix) */\n  gateId: string;\n  /**\n   * Approval channel — where the approval UI is rendered.\n   * - 'chat': SSE-based chat UI (default)\n   * - 'outlook': MS Graph Actionable Messages\n   * - 'telegram': Telegram Bot inline keyboard\n   */\n  channel?: 'chat' | 'outlook' | 'telegram';\n  /** Optional human-readable prompt shown to the approver */\n  prompt?: string;\n  /** Optional approver identifier (e.g., email, user ID) */\n  approver?: string;\n  /** Timeout in ms before the gate auto-expires (default: 5 minutes) */\n  timeoutMs?: number;\n  /** What to do on denial: 'stop' ends the graph, 'skip' skips the destination agent */\n  onDeny?: 'stop' | 'skip';\n};\n\nexport type GraphEdge = {\n  /** Agent ID, use a list for multiple sources */\n  from: string | string[];\n  /** Agent ID, use a list for multiple destinations */\n  to: string | string[];\n  description?: string;\n  /** Can return boolean or specific destination(s) */\n  condition?: (state: BaseGraphState) => boolean | string | string[];\n  /**\n   * EdgeType.HANDOFF — true agent handoff, parent calls child inline and gets result back.\n   * EdgeType.TRANSFER — one-way transfer, parent exits and child takes over.\n   * EdgeType.SEQUENCE — fixed graph edges for sequential/parallel transitions.\n   */\n  edgeType?: import('@/common').EdgeType;\n  /**\n   * For sequence edges: Optional prompt to add when transitioning through this edge.\n   * String prompts can include variables like {results} which will be replaced with\n   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.\n   *\n   * For transfer edges: Description for the input parameter that the transfer tool accepts,\n   * allowing the supervisor to pass specific instructions/context to the transferred agent.\n   */\n  prompt?:\n    | string\n    | ((\n        messages: BaseMessage[],\n        runStartIndex: number\n      ) => string | Promise<string> | undefined);\n  /**\n   * When true, excludes messages from startIndex when adding prompt.\n   * Automatically set to true when {results} variable is used in prompt.\n   */\n  excludeResults?: boolean;\n  /**\n   * For transfer edges: Customizes the parameter name for the transfer input.\n   * Defaults to \"instructions\" if not specified.\n   * Only applies when prompt is provided for transfer edges.\n   *\n   * For handoff edges: Customizes the parameter name for the handoff instruction input.\n   */\n  promptKey?: string;\n  /**\n   * For handoff edges: Maximum characters for the result returned to the parent.\n   * Uses head/tail truncation (60/40 split) to preserve key findings and conclusions.\n   * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).\n   */\n  maxResultChars?: number;\n  /**\n   * Approval gate configuration for sequence edges.\n   * When set, inserts an approval gate node between source and destination.\n   * The gate ALWAYS fires regardless of ExecutionContext (unlike tool approval).\n   */\n  approvalGate?: ApprovalGateConfig;\n};\n\nexport type MultiAgentGraphInput = StandardGraphInput & {\n  edges: GraphEdge[];\n  /**\n   * When set, the graph routes START to this agent instead of the default starting nodes.\n   * Used for multi-turn resumption: the caller reads `lastActiveAgentId` from the\n   * previous turn's metadata and passes it here so follow-up messages route to the\n   * agent that last handled the conversation.\n   *\n   * If the agent ID is invalid (not in the graph), falls back to default starting nodes.\n   */\n  resumeFromAgentId?: string;\n};\n\n/**\n * Structured output mode determines how the agent returns structured data.\n * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)\n * - 'provider': Uses provider-native structured output via LangChain's jsonMode (OpenAI, Anthropic, etc.)\n * - 'native': Uses provider's constrained decoding API directly for guaranteed schema compliance\n *   (Anthropic output_config.format, OpenAI response_format.json_schema). Falls back to 'tool' for unsupported providers.\n * - 'auto': Automatically selects the best strategy — 'native' for supported providers, 'tool' for others\n */\nexport type StructuredOutputMode = 'tool' | 'provider' | 'native' | 'auto';\n\n/**\n * Resolved method used internally after mode resolution.\n * Maps to LangChain's withStructuredOutput method parameter plus our native path.\n */\nexport type ResolvedStructuredOutputMethod =\n  | 'functionCalling'\n  | 'jsonMode'\n  | 'jsonSchema'\n  | 'native'\n  | undefined;\n\n/**\n * Error thrown when the model refuses to produce structured output due to safety policies.\n */\nexport class StructuredOutputRefusalError extends Error {\n  constructor(public refusalText: string) {\n    super(`Model refused to produce structured output: ${refusalText}`);\n    this.name = 'StructuredOutputRefusalError';\n  }\n}\n\n/**\n * Error thrown when the structured output response was truncated due to max_tokens.\n */\nexport class StructuredOutputTruncatedError extends Error {\n  constructor(public stopReason: string) {\n    super(\n      `Structured output was truncated (stop_reason: ${stopReason}). ` +\n        'Increase max_tokens to allow the full JSON response to be generated.'\n    );\n    this.name = 'StructuredOutputTruncatedError';\n  }\n}\n\n/**\n * Configuration for structured JSON output from agents.\n * When configured, the agent will return a validated JSON response\n * instead of streaming text.\n */\nexport interface StructuredOutputConfig {\n  /**\n   * JSON Schema defining the output structure.\n   * The model will be forced to return data conforming to this schema.\n   */\n  schema: Record<string, unknown>;\n  /**\n   * Name for the structured output format (used in tool mode).\n   * @default 'StructuredResponse'\n   */\n  name?: string;\n  /**\n   * Description of what the structured output represents.\n   * Helps the model understand the expected format.\n   */\n  description?: string;\n  /**\n   * Output mode strategy.\n   * @default 'auto'\n   */\n  mode?: StructuredOutputMode;\n  /**\n   * Enable strict schema validation.\n   * When true, the response must exactly match the schema.\n   * @default true\n   */\n  strict?: boolean;\n  /**\n   * Error handling configuration.\n   * - true: Auto-retry on validation errors (default)\n   * - false: Throw error on validation failure\n   * - string: Custom error message for retry\n   */\n  handleErrors?: boolean | string;\n  /**\n   * Maximum number of retry attempts on validation failure.\n   * @default 2\n   */\n  maxRetries?: number;\n  /**\n   * Include the raw AI message along with structured response.\n   * Useful for debugging.\n   * @default false\n   */\n  includeRaw?: boolean;\n}\n\n/**\n * Database/API structured output format (snake_case with enabled flag).\n * This matches the format stored in MongoDB and sent from frontends.\n */\nexport interface StructuredOutputInput {\n  /** Whether structured output is enabled */\n  enabled?: boolean;\n  /** JSON Schema defining the expected response structure */\n  schema?: Record<string, unknown>;\n  /** Name identifier for the structured output */\n  name?: string;\n  /** Description of what the structured output represents */\n  description?: string;\n  /** Mode for structured output: 'tool' | 'provider' | 'native' | 'auto' */\n  mode?: StructuredOutputMode;\n  /** Whether to enforce strict schema validation */\n  strict?: boolean;\n}\n\n/**\n * Trigger strategy for when summarization should activate.\n * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage\n * - 'messageCount': Trigger when pruned message count exceeds a threshold\n * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold\n */\nexport type SummarizationTriggerType =\n  | 'contextPercentage'\n  | 'messageCount'\n  | 'tokenThreshold';\n\n/**\n * Configuration for summarization behavior within the agent pipeline.\n * All fields are optional — sensible defaults are provided via constants.\n *\n * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA\n */\nexport interface SummarizationConfig {\n  /**\n   * Strategy for when summarization triggers.\n   * @default 'contextPercentage'\n   */\n  triggerType?: SummarizationTriggerType;\n\n  /**\n   * Threshold value interpreted based on triggerType:\n   * - contextPercentage: 0-100 (percentage of context window)\n   * - messageCount: absolute count of messages pruned\n   * - tokenThreshold: absolute token count\n   * @default 80 (for contextPercentage)\n   */\n  triggerThreshold?: number;\n\n  /**\n   * Fraction of context window (0-1) reserved for recent messages.\n   * Prevents over-pruning by ensuring at least this fraction of the\n   * context budget is preserved as recent conversation history.\n   * @default 0.3\n   */\n  reserveRatio?: number;\n\n  /**\n   * Whether context pruning is enabled (can be disabled for debugging).\n   * @default true\n   */\n  contextPruning?: boolean;\n\n  /**\n   * Initial summary text to seed across runs.\n   * Different from persistedSummary: this is provided by the caller as a\n   * cross-conversation seed (e.g., agent personality or recurring context),\n   * while persistedSummary is loaded from the conversation's own history.\n   */\n  initialSummary?: string;\n}\n\n/**\n * Runtime state for EMA-based pruning calibration.\n * Maintained across iterations within a single run to smooth pruning decisions.\n */\nexport interface PruneCalibrationState {\n  /** Current EMA calibration ratio */\n  ratio: number;\n  /** Number of calibration updates applied */\n  iterations: number;\n}\n\n/**\n * Lightweight file metadata entry for conversation-level file awareness.\n * Contains only IDs and names — NOT full content — so the agent always knows\n * what files exist in the conversation even after compaction pushes old messages\n * behind the summary window. The agent can retrieve full content on-demand\n * via file_search (RAG) or content_tool read (by contentId).\n */\nexport interface FileManifestEntry {\n  /** Unique file identifier (e.g., MongoDB ObjectId or UUID) */\n  fileId: string;\n  /** Original filename (e.g., \"quarterly-report.pdf\") */\n  filename: string;\n  /** Content identifier for on-demand retrieval via content_tool read */\n  contentId?: string;\n  /** File source (e.g., \"local\", \"sharepoint\", \"onedrive\") */\n  source?: string;\n  /** Index of the message that introduced this file (0-based in the original message array) */\n  messageIndex?: number;\n}\n\nexport interface AgentInputs {\n  agentId: string;\n  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */\n  name?: string;\n  /** Description of what this agent does (used to enrich handoff tool descriptions). */\n  description?: string;\n  toolEnd?: boolean;\n  toolMap?: ToolMap;\n  tools?: GraphTools;\n  provider: Providers;\n  instructions?: string;\n  streamBuffer?: number;\n  maxContextTokens?: number;\n  clientOptions?: ClientOptions;\n  additional_instructions?: string;\n  reasoningKey?: 'reasoning_content' | 'reasoning';\n  /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */\n  useLegacyContent?: boolean;\n  /**\n   * Tool definitions for all tools, including deferred and programmatic.\n   * Used for tool search and programmatic tool calling.\n   * Maps tool name to LCTool definition.\n   */\n  toolRegistry?: Map<string, LCTool>;\n  /**\n   * Dynamic context that changes per-request (e.g., current time, user info).\n   * This is injected as a user message rather than system prompt to preserve cache.\n   * Keeping this separate from instructions ensures the system message stays static\n   * and can be cached by Bedrock/Anthropic prompt caching.\n   */\n  dynamicContext?: string;\n  /**\n   * Structured output configuration (camelCase).\n   * When set, disables streaming and returns a validated JSON response\n   * conforming to the specified schema.\n   */\n  structuredOutput?: StructuredOutputConfig;\n  /**\n   * Structured output configuration (snake_case - database/API format).\n   * Alternative to structuredOutput for compatibility with MongoDB/frontend.\n   * Uses an `enabled` flag to control activation.\n   * @deprecated Use structuredOutput instead when possible\n   */\n  structured_output?: StructuredOutputInput;\n  /**\n   * Serializable tool definitions for event-driven execution.\n   * When provided, ToolNode operates in event-driven mode, dispatching\n   * ON_TOOL_EXECUTE events instead of invoking tools directly.\n   */\n  toolDefinitions?: LCTool[];\n  /**\n   * Tool names discovered from previous conversation history.\n   * These tools will be pre-marked as discovered so they're included\n   * in tool binding without requiring tool_search.\n   */\n  discoveredTools?: string[];\n  /**\n   * Optional callback for summarizing messages that were pruned from context.\n   * When provided, discarded messages are summarized by the caller (e.g., Ranger)\n   * using a cheap LLM call, and the summary is prepended to the context.\n   */\n  summarizeCallback?: (\n    messagesToRefine: import('@langchain/core/messages').BaseMessage[]\n  ) => Promise<string | undefined>;\n  /**\n   * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).\n   * When provided, this summary is injected into the initial message context\n   * so the agent has prior conversation history even on new turns.\n   * Set by Ranger's SummaryStore when resuming a conversation.\n   */\n  persistedSummary?: string;\n  /**\n   * Summarization configuration controlling trigger strategy, reserve ratio,\n   * and EMA calibration for pruning. When omitted, sensible defaults apply.\n   * @see SummarizationConfig\n   */\n  summarizationConfig?: SummarizationConfig;\n  /**\n   * Lightweight file manifest for the conversation.\n   * Contains file IDs, names, and metadata — NOT full content.\n   *\n   * Used by the compaction engine to inject a [Conversation Files] block\n   * into the windowed view, ensuring the LLM always knows what files exist\n   * even when old messages (with full file content) are behind the summary.\n   *\n   * The agent can retrieve full content on-demand via:\n   *   - file_search (RAG semantic search over embedded files)\n   *   - content_tool read (by contentId for exact file retrieval)\n   *\n   * Built by the orchestrator (e.g., Ranger) from message_file_map\n   * and metadata.context_files across all conversation messages.\n   */\n  fileManifest?: FileManifestEntry[];\n}\n"],"names":[],"mappings":";;AAidA;;AAEG;AACG,MAAO,4BAA6B,SAAQ,KAAK,CAAA;AAClC,IAAA,WAAA;AAAnB,IAAA,WAAA,CAAmB,WAAmB,EAAA;AACpC,QAAA,KAAK,CAAC,CAAA,4CAAA,EAA+C,WAAW,CAAA,CAAE,CAAC;QADlD,IAAA,CAAA,WAAW,GAAX,WAAW;AAE5B,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B;IAC5C;AACD;AAED;;AAEG;AACG,MAAO,8BAA+B,SAAQ,KAAK,CAAA;AACpC,IAAA,UAAA;AAAnB,IAAA,WAAA,CAAmB,UAAkB,EAAA;QACnC,KAAK,CACH,CAAA,8CAAA,EAAiD,UAAU,CAAA,GAAA,CAAK;AAC9D,YAAA,sEAAsE,CACzE;QAJgB,IAAA,CAAA,UAAU,GAAV,UAAU;AAK3B,QAAA,IAAI,CAAC,IAAI,GAAG,gCAAgC;IAC9C;AACD;;;;;"}
+{"version":3,"file":"graph.cjs","sources":["../../../src/types/graph.ts"],"sourcesContent":["// src/types/graph.ts\nimport type {\n  START,\n  StateType,\n  UpdateType,\n  StateGraph,\n  StateGraphArgs,\n  StateDefinition,\n  CompiledStateGraph,\n  BinaryOperatorAggregate,\n} from '@langchain/langgraph';\nimport type { BindToolsInput } from '@langchain/core/language_models/chat_models';\nimport type {\n  BaseMessage,\n  AIMessageChunk,\n  SystemMessage,\n} from '@langchain/core/messages';\nimport type { RunnableConfig, Runnable } from '@langchain/core/runnables';\nimport type { ChatGenerationChunk } from '@langchain/core/outputs';\nimport type { GoogleAIToolType } from '@langchain/google-common';\nimport type {\n  ToolMap,\n  ToolEndEvent,\n  GenericTool,\n  LCTool,\n  ToolApprovalConfig,\n} from '@/types/tools';\nimport type { Providers, Callback, GraphNodeKeys } from '@/common';\nimport type { StandardGraph, MultiAgentGraph } from '@/graphs';\nimport type { ClientOptions } from '@/types/llm';\nimport type {\n  RunStep,\n  RunStepDeltaEvent,\n  MessageDeltaEvent,\n  ReasoningDeltaEvent,\n} from '@/types/stream';\nimport type { TokenCounter } from '@/types/run';\n\n/** Interface for bound model with stream and invoke methods */\nexport interface ChatModel {\n  stream?: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AsyncIterable<AIMessageChunk>>;\n  invoke: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AIMessageChunk>;\n}\n\n/** Payload for ON_AGENT_TRANSITION events */\nexport type AgentTransitionEvent = {\n  sourceAgentId?: string;\n  sourceAgentName?: string;\n  destinationAgentId: string;\n  destinationAgentName: string;\n  edgeType: string; // 'handoff' | 'transfer' | 'sequence'\n  timestamp: number;\n  /** When true, this event signals handoff completion (child → parent return) */\n  isCompletion?: boolean;\n  /** Duration of child agent execution in milliseconds (only on completion events) */\n  durationMs?: number;\n  /** Length of child agent result text in characters (only on completion events) */\n  resultLength?: number;\n};\n\nexport type GraphNode = GraphNodeKeys | typeof START;\nexport type ClientCallback<T extends unknown[]> = (\n  graph: StandardGraph,\n  ...args: T\n) => void;\n\nexport type ClientCallbacks = {\n  [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;\n  [Callback.TOOL_START]?: ClientCallback<unknown[]>;\n  [Callback.TOOL_END]?: ClientCallback<unknown[]>;\n};\n\nexport type SystemCallbacks = {\n  [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<\n    infer Args\n  >\n    ? (...args: Args) => void\n    : never;\n};\n\nexport type BaseGraphState = {\n  messages: BaseMessage[];\n  /**\n   * Structured response when using structured output mode.\n   * Contains the validated JSON response conforming to the configured schema.\n   */\n  structuredResponse?: Record<string, unknown>;\n};\n\nexport type MultiAgentGraphState = BaseGraphState & {\n  agentMessages?: BaseMessage[];\n};\n\nexport type IState = BaseGraphState;\n\nexport interface EventHandler {\n  handle(\n    event: string,\n    data:\n      | StreamEventData\n      | ModelEndData\n      | RunStep\n      | RunStepDeltaEvent\n      | MessageDeltaEvent\n      | ReasoningDeltaEvent\n      | { result: ToolEndEvent },\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): void | Promise<void>;\n}\n\nexport type GraphStateChannels<T extends BaseGraphState> =\n  StateGraphArgs<T>['channels'];\n\nexport type Workflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = StateGraph<T, U, N>;\n\nexport type CompiledWorkflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = CompiledStateGraph<T, U, N>;\n\nexport type CompiledStateWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledMultiAgentWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledAgentWorfklow = CompiledStateGraph<\n  {\n    messages: BaseMessage[];\n  },\n  {\n    messages?: BaseMessage[] | undefined;\n  },\n  '__start__' | `agent=${string}` | `tools=${string}`,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition,\n  {\n    [x: `agent=${string}`]: Partial<BaseGraphState>;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [x: `tools=${string}`]: any;\n  }\n>;\n\nexport type SystemRunnable =\n  | Runnable<\n      BaseMessage[],\n      (BaseMessage | SystemMessage)[],\n      RunnableConfig<Record<string, unknown>>\n    >\n  | undefined;\n\n/**\n * Optional compile options passed to workflow.compile().\n * These are intentionally untyped to avoid coupling to library internals.\n */\nexport type CompileOptions = {\n  // A checkpointer instance (e.g., MemorySaver, SQL saver)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  checkpointer?: any;\n  interruptBefore?: string[];\n  interruptAfter?: string[];\n  /**\n   * Human-in-the-loop tool approval configuration.\n   * When set, tools matching the policy will trigger an interrupt()\n   * before execution, pausing the graph for human approval.\n   * Requires a checkpointer to be set for interrupt/resume to work.\n   */\n  toolApprovalConfig?: ToolApprovalConfig;\n};\n\nexport type EventStreamCallbackHandlerInput =\n  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<\n    infer T,\n    'autoClose'\n  >\n    ? T\n    : never;\n\nexport type StreamChunk =\n  | (ChatGenerationChunk & {\n      message: AIMessageChunk;\n    })\n  | AIMessageChunk;\n\n/**\n * Data associated with a StreamEvent.\n */\nexport type StreamEventData = {\n  /**\n   * The input passed to the runnable that generated the event.\n   * Inputs will sometimes be available at the *START* of the runnable, and\n   * sometimes at the *END* of the runnable.\n   * If a runnable is able to stream its inputs, then its input by definition\n   * won't be known until the *END* of the runnable when it has finished streaming\n   * its inputs.\n   */\n  input?: unknown;\n  /**\n   * The output of the runnable that generated the event.\n   * Outputs will only be available at the *END* of the runnable.\n   * For most runnables, this field can be inferred from the `chunk` field,\n   * though there might be some exceptions for special cased runnables (e.g., like\n   * chat models), which may return more information.\n   */\n  output?: unknown;\n  /**\n   * A streaming chunk from the output that generated the event.\n   * chunks support addition in general, and adding them up should result\n   * in the output of the runnable that generated the event.\n   */\n  chunk?: StreamChunk;\n  /**\n   * Runnable config for invoking other runnables within handlers.\n   */\n  config?: RunnableConfig;\n  /**\n   * Custom result from the runnable that generated the event.\n   */\n  result?: unknown;\n  /**\n   * Custom field to indicate the event was manually emitted, and may have been handled already\n   */\n  emitted?: boolean;\n};\n\n/**\n * A streaming event.\n *\n * Schema of a streaming event which is produced from the streamEvents method.\n */\nexport type StreamEvent = {\n  /**\n   * Event names are of the format: on_[runnable_type]_(start|stream|end).\n   *\n   * Runnable types are one of:\n   * - llm - used by non chat models\n   * - chat_model - used by chat models\n   * - prompt --  e.g., ChatPromptTemplate\n   * - tool -- LangChain tools\n   * - chain - most Runnables are of this type\n   *\n   * Further, the events are categorized as one of:\n   * - start - when the runnable starts\n   * - stream - when the runnable is streaming\n   * - end - when the runnable ends\n   *\n   * start, stream and end are associated with slightly different `data` payload.\n   *\n   * Please see the documentation for `EventData` for more details.\n   */\n  event: string;\n  /** The name of the runnable that generated the event. */\n  name: string;\n  /**\n   * An randomly generated ID to keep track of the execution of the given runnable.\n   *\n   * Each child runnable that gets invoked as part of the execution of a parent runnable\n   * is assigned its own unique ID.\n   */\n  run_id: string;\n  /**\n   * Tags associated with the runnable that generated this event.\n   * Tags are always inherited from parent runnables.\n   */\n  tags?: string[];\n  /** Metadata associated with the runnable that generated this event. */\n  metadata: Record<string, unknown>;\n  /**\n   * Event data.\n   *\n   * The contents of the event data depend on the event type.\n   */\n  data: StreamEventData;\n};\n\nexport type GraphConfig = {\n  provider: string;\n  thread_id?: string;\n  run_id?: string;\n};\n\nexport type PartMetadata = {\n  progress?: number;\n  asset_pointer?: string;\n  status?: string;\n  action?: boolean;\n  output?: string;\n};\n\nexport type ModelEndData =\n  | (StreamEventData & { output: AIMessageChunk | undefined })\n  | undefined;\nexport type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];\nexport type StandardGraphInput = {\n  runId?: string;\n  signal?: AbortSignal;\n  agents: AgentInputs[];\n  tokenCounter?: TokenCounter;\n  indexTokenCountMap?: Record<string, number>;\n};\n\n/**\n * Configuration for an approval gate placed on a sequence edge.\n * When present, the graph inserts an approval gate node between the source\n * and destination agents. The gate ALWAYS fires (regardless of ExecutionContext)\n * and calls interrupt() to pause the graph for human approval.\n */\nexport type ApprovalGateConfig = {\n  /** Unique identifier for this gate (used as node ID suffix) */\n  gateId: string;\n  /**\n   * Approval channel — where the approval UI is rendered.\n   * - 'chat': SSE-based chat UI (default)\n   * - 'outlook': MS Graph Actionable Messages\n   * - 'telegram': Telegram Bot inline keyboard\n   */\n  channel?: 'chat' | 'outlook' | 'telegram';\n  /** Optional human-readable prompt shown to the approver */\n  prompt?: string;\n  /** Optional approver identifier (e.g., email, user ID) */\n  approver?: string;\n  /** Timeout in ms before the gate auto-expires (default: 5 minutes) */\n  timeoutMs?: number;\n  /** What to do on denial: 'stop' ends the graph, 'skip' skips the destination agent */\n  onDeny?: 'stop' | 'skip';\n};\n\nexport type GraphEdge = {\n  /** Agent ID, use a list for multiple sources */\n  from: string | string[];\n  /** Agent ID, use a list for multiple destinations */\n  to: string | string[];\n  description?: string;\n  /** Can return boolean or specific destination(s) */\n  condition?: (state: BaseGraphState) => boolean | string | string[];\n  /**\n   * EdgeType.HANDOFF — true agent handoff, parent calls child inline and gets result back.\n   * EdgeType.TRANSFER — one-way transfer, parent exits and child takes over.\n   * EdgeType.SEQUENCE — fixed graph edges for sequential/parallel transitions.\n   */\n  edgeType?: import('@/common').EdgeType;\n  /**\n   * For sequence edges: Optional prompt to add when transitioning through this edge.\n   * String prompts can include variables like {results} which will be replaced with\n   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.\n   *\n   * For transfer edges: Description for the input parameter that the transfer tool accepts,\n   * allowing the supervisor to pass specific instructions/context to the transferred agent.\n   */\n  prompt?:\n    | string\n    | ((\n        messages: BaseMessage[],\n        runStartIndex: number\n      ) => string | Promise<string> | undefined);\n  /**\n   * When true, excludes messages from startIndex when adding prompt.\n   * Automatically set to true when {results} variable is used in prompt.\n   */\n  excludeResults?: boolean;\n  /**\n   * For transfer edges: Customizes the parameter name for the transfer input.\n   * Defaults to \"instructions\" if not specified.\n   * Only applies when prompt is provided for transfer edges.\n   *\n   * For handoff edges: Customizes the parameter name for the handoff instruction input.\n   */\n  promptKey?: string;\n  /**\n   * For handoff edges: Maximum characters for the result returned to the parent.\n   * Uses head/tail truncation (60/40 split) to preserve key findings and conclusions.\n   * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).\n   */\n  maxResultChars?: number;\n  /**\n   * For handoff edges: When true, the child agent receives the full parent\n   * conversation history plus the orchestrator's instructions appended.\n   * When false (default), the child only receives the orchestrator's scoped\n   * instructions — isolated from the parent conversation.\n   */\n  passthrough?: boolean;\n  /**\n   * Approval gate configuration for sequence edges.\n   * When set, inserts an approval gate node between source and destination.\n   * The gate ALWAYS fires regardless of ExecutionContext (unlike tool approval).\n   */\n  approvalGate?: ApprovalGateConfig;\n};\n\nexport type MultiAgentGraphInput = StandardGraphInput & {\n  edges: GraphEdge[];\n  /**\n   * When set, the graph routes START to this agent instead of the default starting nodes.\n   * Used for multi-turn resumption: the caller reads `lastActiveAgentId` from the\n   * previous turn's metadata and passes it here so follow-up messages route to the\n   * agent that last handled the conversation.\n   *\n   * If the agent ID is invalid (not in the graph), falls back to default starting nodes.\n   */\n  resumeFromAgentId?: string;\n};\n\n/**\n * Structured output mode determines how the agent returns structured data.\n * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)\n * - 'provider': Uses provider-native structured output via LangChain's jsonMode (OpenAI, Anthropic, etc.)\n * - 'native': Uses provider's constrained decoding API directly for guaranteed schema compliance\n *   (Anthropic output_config.format, OpenAI response_format.json_schema). Falls back to 'tool' for unsupported providers.\n * - 'auto': Automatically selects the best strategy — 'native' for supported providers, 'tool' for others\n */\nexport type StructuredOutputMode = 'tool' | 'provider' | 'native' | 'auto';\n\n/**\n * Resolved method used internally after mode resolution.\n * Maps to LangChain's withStructuredOutput method parameter plus our native path.\n */\nexport type ResolvedStructuredOutputMethod =\n  | 'functionCalling'\n  | 'jsonMode'\n  | 'jsonSchema'\n  | 'native'\n  | undefined;\n\n/**\n * Error thrown when the model refuses to produce structured output due to safety policies.\n */\nexport class StructuredOutputRefusalError extends Error {\n  constructor(public refusalText: string) {\n    super(`Model refused to produce structured output: ${refusalText}`);\n    this.name = 'StructuredOutputRefusalError';\n  }\n}\n\n/**\n * Error thrown when the structured output response was truncated due to max_tokens.\n */\nexport class StructuredOutputTruncatedError extends Error {\n  constructor(public stopReason: string) {\n    super(\n      `Structured output was truncated (stop_reason: ${stopReason}). ` +\n        'Increase max_tokens to allow the full JSON response to be generated.'\n    );\n    this.name = 'StructuredOutputTruncatedError';\n  }\n}\n\n/**\n * Configuration for structured JSON output from agents.\n * When configured, the agent will return a validated JSON response\n * instead of streaming text.\n */\nexport interface StructuredOutputConfig {\n  /**\n   * JSON Schema defining the output structure.\n   * The model will be forced to return data conforming to this schema.\n   */\n  schema: Record<string, unknown>;\n  /**\n   * Name for the structured output format (used in tool mode).\n   * @default 'StructuredResponse'\n   */\n  name?: string;\n  /**\n   * Description of what the structured output represents.\n   * Helps the model understand the expected format.\n   */\n  description?: string;\n  /**\n   * Output mode strategy.\n   * @default 'auto'\n   */\n  mode?: StructuredOutputMode;\n  /**\n   * Enable strict schema validation.\n   * When true, the response must exactly match the schema.\n   * @default true\n   */\n  strict?: boolean;\n  /**\n   * Error handling configuration.\n   * - true: Auto-retry on validation errors (default)\n   * - false: Throw error on validation failure\n   * - string: Custom error message for retry\n   */\n  handleErrors?: boolean | string;\n  /**\n   * Maximum number of retry attempts on validation failure.\n   * @default 2\n   */\n  maxRetries?: number;\n  /**\n   * Include the raw AI message along with structured response.\n   * Useful for debugging.\n   * @default false\n   */\n  includeRaw?: boolean;\n}\n\n/**\n * Database/API structured output format (snake_case with enabled flag).\n * This matches the format stored in MongoDB and sent from frontends.\n */\nexport interface StructuredOutputInput {\n  /** Whether structured output is enabled */\n  enabled?: boolean;\n  /** JSON Schema defining the expected response structure */\n  schema?: Record<string, unknown>;\n  /** Name identifier for the structured output */\n  name?: string;\n  /** Description of what the structured output represents */\n  description?: string;\n  /** Mode for structured output: 'tool' | 'provider' | 'native' | 'auto' */\n  mode?: StructuredOutputMode;\n  /** Whether to enforce strict schema validation */\n  strict?: boolean;\n}\n\n/**\n * Trigger strategy for when summarization should activate.\n * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage\n * - 'messageCount': Trigger when pruned message count exceeds a threshold\n * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold\n */\nexport type SummarizationTriggerType =\n  | 'contextPercentage'\n  | 'messageCount'\n  | 'tokenThreshold';\n\n/**\n * Configuration for summarization behavior within the agent pipeline.\n * All fields are optional — sensible defaults are provided via constants.\n *\n * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA\n */\nexport interface SummarizationConfig {\n  /**\n   * Strategy for when summarization triggers.\n   * @default 'contextPercentage'\n   */\n  triggerType?: SummarizationTriggerType;\n\n  /**\n   * Threshold value interpreted based on triggerType:\n   * - contextPercentage: 0-100 (percentage of context window)\n   * - messageCount: absolute count of messages pruned\n   * - tokenThreshold: absolute token count\n   * @default 80 (for contextPercentage)\n   */\n  triggerThreshold?: number;\n\n  /**\n   * Fraction of context window (0-1) reserved for recent messages.\n   * Prevents over-pruning by ensuring at least this fraction of the\n   * context budget is preserved as recent conversation history.\n   * @default 0.3\n   */\n  reserveRatio?: number;\n\n  /**\n   * Whether context pruning is enabled (can be disabled for debugging).\n   * @default true\n   */\n  contextPruning?: boolean;\n\n  /**\n   * Initial summary text to seed across runs.\n   * Different from persistedSummary: this is provided by the caller as a\n   * cross-conversation seed (e.g., agent personality or recurring context),\n   * while persistedSummary is loaded from the conversation's own history.\n   */\n  initialSummary?: string;\n}\n\n/**\n * Runtime state for EMA-based pruning calibration.\n * Maintained across iterations within a single run to smooth pruning decisions.\n */\nexport interface PruneCalibrationState {\n  /** Current EMA calibration ratio */\n  ratio: number;\n  /** Number of calibration updates applied */\n  iterations: number;\n}\n\n/**\n * Lightweight file metadata entry for conversation-level file awareness.\n * Contains only IDs and names — NOT full content — so the agent always knows\n * what files exist in the conversation even after compaction pushes old messages\n * behind the summary window. The agent can retrieve full content on-demand\n * via file_search (RAG) or content_tool read (by contentId).\n */\nexport interface FileManifestEntry {\n  /** Unique file identifier (e.g., MongoDB ObjectId or UUID) */\n  fileId: string;\n  /** Original filename (e.g., \"quarterly-report.pdf\") */\n  filename: string;\n  /** Content identifier for on-demand retrieval via content_tool read */\n  contentId?: string;\n  /** File source (e.g., \"local\", \"sharepoint\", \"onedrive\") */\n  source?: string;\n  /** Index of the message that introduced this file (0-based in the original message array) */\n  messageIndex?: number;\n}\n\nexport interface AgentInputs {\n  agentId: string;\n  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */\n  name?: string;\n  /** Description of what this agent does (used to enrich handoff tool descriptions). */\n  description?: string;\n  toolEnd?: boolean;\n  toolMap?: ToolMap;\n  tools?: GraphTools;\n  provider: Providers;\n  instructions?: string;\n  streamBuffer?: number;\n  maxContextTokens?: number;\n  clientOptions?: ClientOptions;\n  additional_instructions?: string;\n  reasoningKey?: 'reasoning_content' | 'reasoning';\n  /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */\n  useLegacyContent?: boolean;\n  /**\n   * Tool definitions for all tools, including deferred and programmatic.\n   * Used for tool search and programmatic tool calling.\n   * Maps tool name to LCTool definition.\n   */\n  toolRegistry?: Map<string, LCTool>;\n  /**\n   * Dynamic context that changes per-request (e.g., current time, user info).\n   * This is injected as a user message rather than system prompt to preserve cache.\n   * Keeping this separate from instructions ensures the system message stays static\n   * and can be cached by Bedrock/Anthropic prompt caching.\n   */\n  dynamicContext?: string;\n  /**\n   * Structured output configuration (camelCase).\n   * When set, disables streaming and returns a validated JSON response\n   * conforming to the specified schema.\n   */\n  structuredOutput?: StructuredOutputConfig;\n  /**\n   * Structured output configuration (snake_case - database/API format).\n   * Alternative to structuredOutput for compatibility with MongoDB/frontend.\n   * Uses an `enabled` flag to control activation.\n   * @deprecated Use structuredOutput instead when possible\n   */\n  structured_output?: StructuredOutputInput;\n  /**\n   * Serializable tool definitions for event-driven execution.\n   * When provided, ToolNode operates in event-driven mode, dispatching\n   * ON_TOOL_EXECUTE events instead of invoking tools directly.\n   */\n  toolDefinitions?: LCTool[];\n  /**\n   * Tool names discovered from previous conversation history.\n   * These tools will be pre-marked as discovered so they're included\n   * in tool binding without requiring tool_search.\n   */\n  discoveredTools?: string[];\n  /**\n   * Optional callback for summarizing messages that were pruned from context.\n   * When provided, discarded messages are summarized by the host caller\n   * using a cheap LLM call, and the summary is prepended to the context.\n   */\n  summarizeCallback?: (\n    messagesToRefine: import('@langchain/core/messages').BaseMessage[]\n  ) => Promise<string | undefined>;\n  /**\n   * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).\n   * When provided, this summary is injected into the initial message context\n   * so the agent has prior conversation history even on new turns.\n   * Set by the host's summary store when resuming a conversation.\n   */\n  persistedSummary?: string;\n  /**\n   * Summarization configuration controlling trigger strategy, reserve ratio,\n   * and EMA calibration for pruning. When omitted, sensible defaults apply.\n   * @see SummarizationConfig\n   */\n  summarizationConfig?: SummarizationConfig;\n  /**\n   * Lightweight file manifest for the conversation.\n   * Contains file IDs, names, and metadata — NOT full content.\n   *\n   * Used by the compaction engine to inject a [Conversation Files] block\n   * into the windowed view, ensuring the LLM always knows what files exist\n   * even when old messages (with full file content) are behind the summary.\n   *\n   * The agent can retrieve full content on-demand via:\n   *   - file_search (RAG semantic search over embedded files)\n   *   - content_tool read (by contentId for exact file retrieval)\n   *\n   * Built by the host orchestrator from message_file_map\n   * and metadata.context_files across all conversation messages.\n   */\n  fileManifest?: FileManifestEntry[];\n}\n"],"names":[],"mappings":";;AAwdA;;AAEG;AACG,MAAO,4BAA6B,SAAQ,KAAK,CAAA;AAClC,IAAA,WAAA;AAAnB,IAAA,WAAA,CAAmB,WAAmB,EAAA;AACpC,QAAA,KAAK,CAAC,CAAA,4CAAA,EAA+C,WAAW,CAAA,CAAE,CAAC;QADlD,IAAA,CAAA,WAAW,GAAX,WAAW;AAE5B,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B;IAC5C;AACD;AAED;;AAEG;AACG,MAAO,8BAA+B,SAAQ,KAAK,CAAA;AACpC,IAAA,UAAA;AAAnB,IAAA,WAAA,CAAmB,UAAkB,EAAA;QACnC,KAAK,CACH,CAAA,8CAAA,EAAiD,UAAU,CAAA,GAAA,CAAK;AAC9D,YAAA,sEAAsE,CACzE;QAJgB,IAAA,CAAA,UAAU,GAAV,UAAU;AAK3B,QAAA,IAAI,CAAC,IAAI,GAAG,gCAAgC;IAC9C;AACD;;;;;"}

package/dist/cjs/utils/childAgentContext.cjs

@@ -0,0 +1,242 @@
+'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