@illuma-ai/agents 1.1.28 → 1.3.0

package/dist/cjs/memory/schema.sql

@@ -0,0 +1,51 @@
+-- Autonomous memory — Postgres schema (v2: layered tier scoping).
+--
+-- Two-tier canonical-document model:
+--
+--   memory/agent/*   → shared across every user of the agent (user_id = NULL)
+--   memory/user/*    → private to a specific caller (user_id = <callerId>)
+--
+-- Uniqueness key is `(agent_id, user_id, path)` with NULLS NOT DISTINCT
+-- so two NULL user_id rows on the same path collide (exactly-one
+-- agent-tier row per path) while per-user rows on the same path coexist
+-- (one row per user for user-tier paths).
+--
+-- The read path filters with `(user_id IS NULL OR user_id = $caller)`,
+-- so callers see agent-tier rows + only their own user-tier rows —
+-- never another user's private memory. Enforcement is in SQL, not just
+-- the UI.
+--
+-- NULLS NOT DISTINCT requires PostgreSQL 15+. Host's production
+-- pgvector image is PG16, so this is safe. The migration in
+-- `migrate.ts` will drop the legacy `(agent_id, path)` constraint
+-- before creating the new one if it exists on an older database.
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS agent_memories (
+  id           BIGSERIAL   PRIMARY KEY,
+  agent_id     TEXT        NOT NULL,
+  user_id      TEXT,                                -- NULL = agent-tier, shared
+  path         TEXT        NOT NULL,
+  content      TEXT        NOT NULL,
+  embedding    VECTOR(1024),
+  tsv          TSVECTOR    GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_user_id TEXT,                                -- latest session to append
+  CONSTRAINT agent_memories_agent_user_path_uq
+    UNIQUE NULLS NOT DISTINCT (agent_id, user_id, path)
+);
+
+-- Primary lookup index for list/search/generate-prompt — matches the
+-- exact filter shape of every read query.
+CREATE INDEX IF NOT EXISTS agent_memories_scope_idx
+  ON agent_memories (agent_id, user_id, path);
+
+-- Vector ANN index — untouched by the scoping change.
+CREATE INDEX IF NOT EXISTS agent_memories_vector_idx
+  ON agent_memories USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+
+-- Full-text GIN index — untouched.
+CREATE INDEX IF NOT EXISTS agent_memories_tsv_idx
+  ON agent_memories USING GIN (tsv);

package/dist/cjs/memory/temporalDecay.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * Temporal decay — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.
+ * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay
+ * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the
+ * score is exactly halved.
+ *
+ * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside
+ * memory/) do NOT decay — they represent durable knowledge and should stay
+ * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.
+ *
+ * Since our pgvector rows carry `createdAt`, we don't need filesystem stat
+ * fallback — the row timestamp is authoritative for any file without a
+ * date in the path.
+ */
+const DEFAULT_TEMPORAL_DECAY_CONFIG = {
+    enabled: false,
+    halfLifeDays: 30,
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DATED_MEMORY_PATH_RE = /(?:^|\/)memory\/(\d{4})-(\d{2})-(\d{2})\.md$/;
+function toDecayLambda(halfLifeDays) {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0)
+        return 0;
+    return Math.LN2 / halfLifeDays;
+}
+function calculateTemporalDecayMultiplier(params) {
+    const lambda = toDecayLambda(params.halfLifeDays);
+    const age = Math.max(0, params.ageInDays);
+    if (lambda <= 0 || !Number.isFinite(age))
+        return 1;
+    return Math.exp(-lambda * age);
+}
+function applyTemporalDecayToScore(params) {
+    return params.score * calculateTemporalDecayMultiplier(params);
+}
+function normalizePath(p) {
+    return (p ?? '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** Parse a date out of `memory/YYYY-MM-DD.md` — returns null on non-match or invalid date. */
+function parseMemoryDateFromPath(filePath) {
+    const m = DATED_MEMORY_PATH_RE.exec(normalizePath(filePath));
+    if (!m)
+        return null;
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const d = Number(m[3]);
+    if (!Number.isInteger(y) || !Number.isInteger(mo) || !Number.isInteger(d))
+        return null;
+    const ts = Date.UTC(y, mo - 1, d);
+    const parsed = new Date(ts);
+    if (parsed.getUTCFullYear() !== y ||
+        parsed.getUTCMonth() !== mo - 1 ||
+        parsed.getUTCDate() !== d) {
+        return null;
+    }
+    return parsed;
+}
+/**
+ * Evergreen = durable knowledge file that should not decay.
+ * - `MEMORY.md` / `memory.md` at root
+ * - anything inside `memory/` that is NOT a dated `YYYY-MM-DD.md` file
+ */
+function isEvergreenMemoryPath(filePath) {
+    const n = normalizePath(filePath);
+    if (n === 'MEMORY.md' || n === 'memory.md')
+        return true;
+    if (!n.startsWith('memory/'))
+        return false;
+    return !DATED_MEMORY_PATH_RE.test(n);
+}
+function ageInDays(timestamp, nowMs) {
+    return Math.max(0, nowMs - timestamp.getTime()) / DAY_MS;
+}
+/**
+ * Apply temporal decay to a list of memory hits.
+ *
+ * Priority for the effective timestamp:
+ *   1. Dated path (`memory/YYYY-MM-DD.md`) — use the date in the path
+ *   2. Otherwise, if the path is evergreen — NO decay
+ *   3. Otherwise, use the row's `createdAt`
+ */
+function applyTemporalDecayToHits(hits, config = {}, nowMs = Date.now()) {
+    const merged = { ...DEFAULT_TEMPORAL_DECAY_CONFIG, ...config };
+    if (!merged.enabled)
+        return [...hits];
+    return hits.map((h) => {
+        const datedTs = parseMemoryDateFromPath(h.path);
+        let ts = datedTs;
+        if (!ts) {
+            if (isEvergreenMemoryPath(h.path))
+                return h;
+            ts = h.createdAt ?? null;
+        }
+        if (!ts)
+            return h;
+        return {
+            ...h,
+            score: applyTemporalDecayToScore({
+                score: h.score,
+                ageInDays: ageInDays(ts, nowMs),
+                halfLifeDays: merged.halfLifeDays,
+            }),
+        };
+    });
+}
+
+exports.DEFAULT_TEMPORAL_DECAY_CONFIG = DEFAULT_TEMPORAL_DECAY_CONFIG;
+exports.applyTemporalDecayToHits = applyTemporalDecayToHits;
+exports.applyTemporalDecayToScore = applyTemporalDecayToScore;
+exports.calculateTemporalDecayMultiplier = calculateTemporalDecayMultiplier;
+exports.isEvergreenMemoryPath = isEvergreenMemoryPath;
+exports.parseMemoryDateFromPath = parseMemoryDateFromPath;
+exports.toDecayLambda = toDecayLambda;
+//# sourceMappingURL=temporalDecay.cjs.map

package/dist/cjs/memory/temporalDecay.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporalDecay.cjs","sources":["../../../src/memory/temporalDecay.ts"],"sourcesContent":["/**\n * Temporal decay — Phase 2.\n *\n * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.\n * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay\n * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the\n * score is exactly halved.\n *\n * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside\n * memory/) do NOT decay — they represent durable knowledge and should stay\n * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.\n *\n * Since our pgvector rows carry `createdAt`, we don't need filesystem stat\n * fallback — the row timestamp is authoritative for any file without a\n * date in the path.\n */\n\nexport interface TemporalDecayConfig {\n  enabled: boolean;\n  halfLifeDays: number;\n}\n\nexport const DEFAULT_TEMPORAL_DECAY_CONFIG: TemporalDecayConfig = {\n  enabled: false,\n  halfLifeDays: 30,\n};\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\nconst DATED_MEMORY_PATH_RE = /(?:^|\\/)memory\\/(\\d{4})-(\\d{2})-(\\d{2})\\.md$/;\n\nexport function toDecayLambda(halfLifeDays: number): number {\n  if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0) return 0;\n  return Math.LN2 / halfLifeDays;\n}\n\nexport function calculateTemporalDecayMultiplier(params: {\n  ageInDays: number;\n  halfLifeDays: number;\n}): number {\n  const lambda = toDecayLambda(params.halfLifeDays);\n  const age = Math.max(0, params.ageInDays);\n  if (lambda <= 0 || !Number.isFinite(age)) return 1;\n  return Math.exp(-lambda * age);\n}\n\nexport function applyTemporalDecayToScore(params: {\n  score: number;\n  ageInDays: number;\n  halfLifeDays: number;\n}): number {\n  return params.score * calculateTemporalDecayMultiplier(params);\n}\n\nfunction normalizePath(p: string): string {\n  return (p ?? '').replace(/\\\\/g, '/').replace(/^\\.\\//, '');\n}\n\n/** Parse a date out of `memory/YYYY-MM-DD.md` — returns null on non-match or invalid date. */\nexport function parseMemoryDateFromPath(filePath: string): Date | null {\n  const m = DATED_MEMORY_PATH_RE.exec(normalizePath(filePath));\n  if (!m) return null;\n  const y = Number(m[1]);\n  const mo = Number(m[2]);\n  const d = Number(m[3]);\n  if (!Number.isInteger(y) || !Number.isInteger(mo) || !Number.isInteger(d))\n    return null;\n  const ts = Date.UTC(y, mo - 1, d);\n  const parsed = new Date(ts);\n  if (\n    parsed.getUTCFullYear() !== y ||\n    parsed.getUTCMonth() !== mo - 1 ||\n    parsed.getUTCDate() !== d\n  ) {\n    return null;\n  }\n  return parsed;\n}\n\n/**\n * Evergreen = durable knowledge file that should not decay.\n * - `MEMORY.md` / `memory.md` at root\n * - anything inside `memory/` that is NOT a dated `YYYY-MM-DD.md` file\n */\nexport function isEvergreenMemoryPath(filePath: string): boolean {\n  const n = normalizePath(filePath);\n  if (n === 'MEMORY.md' || n === 'memory.md') return true;\n  if (!n.startsWith('memory/')) return false;\n  return !DATED_MEMORY_PATH_RE.test(n);\n}\n\nfunction ageInDays(timestamp: Date, nowMs: number): number {\n  return Math.max(0, nowMs - timestamp.getTime()) / DAY_MS;\n}\n\nexport interface DecayCandidate {\n  path: string;\n  score: number;\n  createdAt?: Date;\n}\n\n/**\n * Apply temporal decay to a list of memory hits.\n *\n * Priority for the effective timestamp:\n *   1. Dated path (`memory/YYYY-MM-DD.md`) — use the date in the path\n *   2. Otherwise, if the path is evergreen — NO decay\n *   3. Otherwise, use the row's `createdAt`\n */\nexport function applyTemporalDecayToHits<T extends DecayCandidate>(\n  hits: T[],\n  config: Partial<TemporalDecayConfig> = {},\n  nowMs: number = Date.now()\n): T[] {\n  const merged = { ...DEFAULT_TEMPORAL_DECAY_CONFIG, ...config };\n  if (!merged.enabled) return [...hits];\n\n  return hits.map((h) => {\n    const datedTs = parseMemoryDateFromPath(h.path);\n    let ts: Date | null = datedTs;\n    if (!ts) {\n      if (isEvergreenMemoryPath(h.path)) return h;\n      ts = h.createdAt ?? null;\n    }\n    if (!ts) return h;\n    return {\n      ...h,\n      score: applyTemporalDecayToScore({\n        score: h.score,\n        ageInDays: ageInDays(ts, nowMs),\n        halfLifeDays: merged.halfLifeDays,\n      }),\n    };\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/nodes/ApprovalGateNode.cjs

@@ -25,7 +25,7 @@ var events = require('../utils/events.cjs');
  * @param destinationAgentId - The agent that follows this gate
  */
 function createApprovalGateNode(config, sourceAgentId, destinationAgentId) {
-    const { gateId, channel = 'chat', prompt, approver, timeoutMs, } = config;
+    const { gateId, channel = 'chat', prompt, approver, timeoutMs } = config;
     /**
      * The gate node function. Receives the current graph state,
      * dispatches a notification, calls interrupt(), and returns

package/dist/cjs/nodes/ApprovalGateNode.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"ApprovalGateNode.cjs","sources":["../../../src/nodes/ApprovalGateNode.ts"],"sourcesContent":["import { interrupt } from '@langchain/langgraph';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type { ApprovalGateConfig, BaseGraphState } from '@/types/graph';\nimport type { ToolApprovalResponse } from '@/types/tools';\nimport { GraphEvents } from '@/common';\nimport { safeDispatchCustomEvent } from '@/utils/events';\n\n/**\n * Interrupt payload for approval gate nodes.\n * Passed to interrupt() and persisted in the checkpoint.\n */\nexport interface ApprovalGateInterrupt {\n  /** Discriminator to distinguish from tool approval interrupts */\n  type: 'approval_gate';\n  /** Unique gate identifier */\n  gateId: string;\n  /** Approval channel (chat, outlook, telegram) */\n  channel: string;\n  /** Human-readable prompt for the approver */\n  prompt?: string;\n  /** Approver identifier */\n  approver?: string;\n  /** Timeout in ms */\n  timeoutMs?: number;\n  /** Source agent ID (who just finished) */\n  sourceAgentId?: string;\n  /** Destination agent ID (who will run next if approved) */\n  destinationAgentId?: string;\n}\n\n/**\n * Creates a graph node function that acts as an approval gate.\n *\n * Unlike tool approval (which respects ExecutionContext and can be auto-approved\n * in scheduled/handoff modes), approval gates ALWAYS fire. They are placed by\n * the builder between agents in a sequence and represent explicit human\n * checkpoints that cannot be bypassed.\n *\n * Flow:\n * 1. Dispatch ON_APPROVAL_GATE notification (for SSE/persistence)\n * 2. Call interrupt() — graph pauses, state is checkpointed\n * 3. On resume, interrupt() returns the ToolApprovalResponse\n * 4. If approved, pass state through (next agent runs)\n * 5. If denied, return state as-is (routing handled by conditional edge)\n *\n * @param config - The approval gate configuration from the edge definition\n * @param sourceAgentId - The agent that precedes this gate\n * @param destinationAgentId - The agent that follows this gate\n */\nexport function createApprovalGateNode(\n  config: ApprovalGateConfig,\n  sourceAgentId: string,\n  destinationAgentId: string,\n) {\n  const {\n    gateId,\n    channel = 'chat',\n    prompt,\n    approver,\n    timeoutMs,\n  } = config;\n\n  /**\n   * The gate node function. Receives the current graph state,\n   * dispatches a notification, calls interrupt(), and returns\n   * the state with an approval result annotation.\n   */\n  return async function approvalGateNode(\n    state: BaseGraphState,\n    runnableConfig?: RunnableConfig,\n  ): Promise<Partial<BaseGraphState>> {\n    const interruptPayload: ApprovalGateInterrupt = {\n      type: 'approval_gate',\n      gateId,\n      channel,\n      prompt,\n      approver,\n      timeoutMs,\n      sourceAgentId,\n      destinationAgentId,\n    };\n\n    // Dispatch notification event so the host can:\n    // 1. Persist the approval request to MongoDB\n    // 2. Route to the appropriate channel adapter\n    // 3. Emit SSE event for chat UI\n    safeDispatchCustomEvent(\n      GraphEvents.ON_APPROVAL_GATE,\n      interruptPayload,\n      runnableConfig,\n    );\n\n    // Pause the graph — state is checkpointed by the MongoDBSaver.\n    // On resume via Command({ resume: ToolApprovalResponse }), interrupt()\n    // returns the response value.\n    const response = interrupt(interruptPayload) as ToolApprovalResponse;\n\n    // Return empty state update — the graph structure (conditional edges)\n    // handles routing based on the approval result. We store the response\n    // in a message so downstream nodes can access it if needed.\n    if (response.approved) {\n      return {};\n    }\n\n    // On denial, we could add a system message noting the denial.\n    // The conditional edge after this node will route to END or skip.\n    return {};\n  };\n}\n\n/**\n * Node ID for an approval gate, derived from the gate configuration.\n * Used by MultiAgentGraph when inserting gate nodes into the graph.\n */\nexport function getApprovalGateNodeId(gateId: string): string {\n  return `approval_gate_${gateId}`;\n}\n"],"names":["safeDispatchCustomEvent","GraphEvents","interrupt"],"mappings":";;;;;;;AA8BA;;;;;;;;;;;;;;;;;;AAkBG;SACa,sBAAsB,CACpC,MAA0B,EAC1B,aAAqB,EACrB,kBAA0B,EAAA;AAE1B,IAAA,MAAM,EACJ,MAAM,EACN,OAAO,GAAG,MAAM,EAChB,MAAM,EACN,QAAQ,EACR,SAAS,GACV,GAAG,MAAM;AAEV;;;;AAIG;AACH,IAAA,OAAO,eAAe,gBAAgB,CACpC,KAAqB,EACrB,cAA+B,EAAA;AAE/B,QAAA,MAAM,gBAAgB,GAA0B;AAC9C,YAAA,IAAI,EAAE,eAAe;YACrB,MAAM;YACN,OAAO;YACP,MAAM;YACN,QAAQ;YACR,SAAS;YACT,aAAa;YACb,kBAAkB;SACnB;;;;;QAMDA,8BAAuB,CACrBC,iBAAW,CAAC,gBAAgB,EAC5B,gBAAgB,EAChB,cAAc,CACf;;;;AAKD,QAAA,MAAM,QAAQ,GAAGC,mBAAS,CAAC,gBAAgB,CAAyB;;;;AAKpE,QAAA,IAAI,QAAQ,CAAC,QAAQ,EAAE;AACrB,YAAA,OAAO,EAAE;QACX;;;AAIA,QAAA,OAAO,EAAE;AACX,IAAA,CAAC;AACH;AAEA;;;AAGG;AACG,SAAU,qBAAqB,CAAC,MAAc,EAAA;IAClD,OAAO,CAAA,cAAA,EAAiB,MAAM,CAAA,CAAE;AAClC;;;;;"}
+{"version":3,"file":"ApprovalGateNode.cjs","sources":["../../../src/nodes/ApprovalGateNode.ts"],"sourcesContent":["import { interrupt } from '@langchain/langgraph';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type { ApprovalGateConfig, BaseGraphState } from '@/types/graph';\nimport type { ToolApprovalResponse } from '@/types/tools';\nimport { GraphEvents } from '@/common';\nimport { safeDispatchCustomEvent } from '@/utils/events';\n\n/**\n * Interrupt payload for approval gate nodes.\n * Passed to interrupt() and persisted in the checkpoint.\n */\nexport interface ApprovalGateInterrupt {\n  /** Discriminator to distinguish from tool approval interrupts */\n  type: 'approval_gate';\n  /** Unique gate identifier */\n  gateId: string;\n  /** Approval channel (chat, outlook, telegram) */\n  channel: string;\n  /** Human-readable prompt for the approver */\n  prompt?: string;\n  /** Approver identifier */\n  approver?: string;\n  /** Timeout in ms */\n  timeoutMs?: number;\n  /** Source agent ID (who just finished) */\n  sourceAgentId?: string;\n  /** Destination agent ID (who will run next if approved) */\n  destinationAgentId?: string;\n}\n\n/**\n * Creates a graph node function that acts as an approval gate.\n *\n * Unlike tool approval (which respects ExecutionContext and can be auto-approved\n * in scheduled/handoff modes), approval gates ALWAYS fire. They are placed by\n * the builder between agents in a sequence and represent explicit human\n * checkpoints that cannot be bypassed.\n *\n * Flow:\n * 1. Dispatch ON_APPROVAL_GATE notification (for SSE/persistence)\n * 2. Call interrupt() — graph pauses, state is checkpointed\n * 3. On resume, interrupt() returns the ToolApprovalResponse\n * 4. If approved, pass state through (next agent runs)\n * 5. If denied, return state as-is (routing handled by conditional edge)\n *\n * @param config - The approval gate configuration from the edge definition\n * @param sourceAgentId - The agent that precedes this gate\n * @param destinationAgentId - The agent that follows this gate\n */\nexport function createApprovalGateNode(\n  config: ApprovalGateConfig,\n  sourceAgentId: string,\n  destinationAgentId: string\n) {\n  const { gateId, channel = 'chat', prompt, approver, timeoutMs } = config;\n\n  /**\n   * The gate node function. Receives the current graph state,\n   * dispatches a notification, calls interrupt(), and returns\n   * the state with an approval result annotation.\n   */\n  return async function approvalGateNode(\n    state: BaseGraphState,\n    runnableConfig?: RunnableConfig\n  ): Promise<Partial<BaseGraphState>> {\n    const interruptPayload: ApprovalGateInterrupt = {\n      type: 'approval_gate',\n      gateId,\n      channel,\n      prompt,\n      approver,\n      timeoutMs,\n      sourceAgentId,\n      destinationAgentId,\n    };\n\n    // Dispatch notification event so the host can:\n    // 1. Persist the approval request to MongoDB\n    // 2. Route to the appropriate channel adapter\n    // 3. Emit SSE event for chat UI\n    safeDispatchCustomEvent(\n      GraphEvents.ON_APPROVAL_GATE,\n      interruptPayload,\n      runnableConfig\n    );\n\n    // Pause the graph — state is checkpointed by the MongoDBSaver.\n    // On resume via Command({ resume: ToolApprovalResponse }), interrupt()\n    // returns the response value.\n    const response = interrupt(interruptPayload) as ToolApprovalResponse;\n\n    // Return empty state update — the graph structure (conditional edges)\n    // handles routing based on the approval result. We store the response\n    // in a message so downstream nodes can access it if needed.\n    if (response.approved) {\n      return {};\n    }\n\n    // On denial, we could add a system message noting the denial.\n    // The conditional edge after this node will route to END or skip.\n    return {};\n  };\n}\n\n/**\n * Node ID for an approval gate, derived from the gate configuration.\n * Used by MultiAgentGraph when inserting gate nodes into the graph.\n */\nexport function getApprovalGateNodeId(gateId: string): string {\n  return `approval_gate_${gateId}`;\n}\n"],"names":["safeDispatchCustomEvent","GraphEvents","interrupt"],"mappings":";;;;;;;AA8BA;;;;;;;;;;;;;;;;;;AAkBG;SACa,sBAAsB,CACpC,MAA0B,EAC1B,aAAqB,EACrB,kBAA0B,EAAA;AAE1B,IAAA,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM;AAExE;;;;AAIG;AACH,IAAA,OAAO,eAAe,gBAAgB,CACpC,KAAqB,EACrB,cAA+B,EAAA;AAE/B,QAAA,MAAM,gBAAgB,GAA0B;AAC9C,YAAA,IAAI,EAAE,eAAe;YACrB,MAAM;YACN,OAAO;YACP,MAAM;YACN,QAAQ;YACR,SAAS;YACT,aAAa;YACb,kBAAkB;SACnB;;;;;QAMDA,8BAAuB,CACrBC,iBAAW,CAAC,gBAAgB,EAC5B,gBAAgB,EAChB,cAAc,CACf;;;;AAKD,QAAA,MAAM,QAAQ,GAAGC,mBAAS,CAAC,gBAAgB,CAAyB;;;;AAKpE,QAAA,IAAI,QAAQ,CAAC,QAAQ,EAAE;AACrB,YAAA,OAAO,EAAE;QACX;;;AAIA,QAAA,OAAO,EAAE;AACX,IAAA,CAAC;AACH;AAEA;;;AAGG;AACG,SAAU,qBAAqB,CAAC,MAAc,EAAA;IAClD,OAAO,CAAA,cAAA,EAAiB,MAAM,CAAA,CAAE;AAClC;;;;;"}

package/dist/cjs/prompts/memoryFlushPrompt.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+var constants = require('../memory/constants.cjs');
+var paths = require('../memory/paths.cjs');
+
+/**
+ * Memory-flush prompt resolver.
+ *
+ * The raw prompt strings live in `src/memory/constants.ts` and contain a
+ * single `{{MEMORY_PATHS_RUBRIC}}` placeholder. This module substitutes
+ * the caller-scoped rubric (produced by `renderPathsRubric()` in
+ * `src/memory/paths.ts`) into that placeholder at flush time, so:
+ *
+ *   - a collaborative agent with a real caller sees all 8 paths
+ *   - an isolated/autonomous agent sees only the 4 agent-tier paths
+ *     (user-tier rows are physically omitted from the rubric the LLM
+ *      sees, so it cannot route writes there even by mistake)
+ *
+ * ## Why this lives in prompts/ and not memory/constants.ts
+ *
+ * The constants file is pure strings — no imports, no runtime work.
+ * Injecting the rubric needs access to `renderPathsRubric()` which
+ * needs `MemoryScope`, so the substitution has to happen one layer up.
+ * Keeping the placeholder in constants and the substitution here means
+ * tests of the raw prompt (no scope) and tests of the rendered prompt
+ * (scope-aware) stay independent.
+ */
+/** Back-compat alias so existing callers keep working. */
+const MEMORY_FLUSH_SYSTEM_PROMPT = constants.DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT;
+/**
+ * Substitutes the paths rubric into the raw prompts for a given scope.
+ *
+ * Idempotent (calling it twice on already-resolved strings is a no-op
+ * because the placeholder will have been replaced already). Safe to
+ * call per-flush; no caching needed — the string concat is microseconds.
+ */
+function resolveFlushPrompts(options) {
+    const rubric = paths.renderPathsRubric(options.scope);
+    return {
+        prompt: constants.DEFAULT_MEMORY_FLUSH_PROMPT.replaceAll(constants.FLUSH_PROMPT_RUBRIC_PLACEHOLDER, rubric),
+        systemPrompt: constants.DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT.replaceAll(constants.FLUSH_PROMPT_RUBRIC_PLACEHOLDER, rubric),
+    };
+}
+
+exports.DEFAULT_MEMORY_FLUSH_PROMPT = constants.DEFAULT_MEMORY_FLUSH_PROMPT;
+exports.DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT = constants.DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT;
+exports.MEMORY_FLUSH_SYSTEM_PROMPT = MEMORY_FLUSH_SYSTEM_PROMPT;
+exports.resolveFlushPrompts = resolveFlushPrompts;
+//# sourceMappingURL=memoryFlushPrompt.cjs.map

package/dist/cjs/prompts/memoryFlushPrompt.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryFlushPrompt.cjs","sources":["../../../src/prompts/memoryFlushPrompt.ts"],"sourcesContent":["/**\n * Memory-flush prompt resolver.\n *\n * The raw prompt strings live in `src/memory/constants.ts` and contain a\n * single `{{MEMORY_PATHS_RUBRIC}}` placeholder. This module substitutes\n * the caller-scoped rubric (produced by `renderPathsRubric()` in\n * `src/memory/paths.ts`) into that placeholder at flush time, so:\n *\n *   - a collaborative agent with a real caller sees all 8 paths\n *   - an isolated/autonomous agent sees only the 4 agent-tier paths\n *     (user-tier rows are physically omitted from the rubric the LLM\n *      sees, so it cannot route writes there even by mistake)\n *\n * ## Why this lives in prompts/ and not memory/constants.ts\n *\n * The constants file is pure strings — no imports, no runtime work.\n * Injecting the rubric needs access to `renderPathsRubric()` which\n * needs `MemoryScope`, so the substitution has to happen one layer up.\n * Keeping the placeholder in constants and the substitution here means\n * tests of the raw prompt (no scope) and tests of the rendered prompt\n * (scope-aware) stay independent.\n */\nimport {\n  DEFAULT_MEMORY_FLUSH_PROMPT,\n  DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT,\n  FLUSH_PROMPT_RUBRIC_PLACEHOLDER,\n} from '@/memory/constants';\nimport { renderPathsRubric } from '@/memory/paths';\nimport type { MemoryScope } from '@/memory/types';\n\nexport { DEFAULT_MEMORY_FLUSH_PROMPT, DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT };\n\n/** Back-compat alias so existing callers keep working. */\nexport const MEMORY_FLUSH_SYSTEM_PROMPT = DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT;\n\n/** Minimum scope shape needed to render the rubric. */\nexport interface ResolveFlushPromptsOptions {\n  /**\n   * The scope the memory tools were built with. Only `userId` matters\n   * for rubric rendering — if absent, the user-tier paths are filtered\n   * out of the rubric the LLM sees.\n   */\n  scope: Pick<MemoryScope, 'userId'>;\n}\n\n/**\n * Result shape returned to `runMemoryFlush`. `prompt` goes in the\n * HumanMessage, `systemPrompt` goes in the SystemMessage. Both already\n * have the rubric substituted — the caller should pass them through\n * verbatim.\n */\nexport interface ResolvedFlushPrompts {\n  prompt: string;\n  systemPrompt: string;\n}\n\n/**\n * Substitutes the paths rubric into the raw prompts for a given scope.\n *\n * Idempotent (calling it twice on already-resolved strings is a no-op\n * because the placeholder will have been replaced already). Safe to\n * call per-flush; no caching needed — the string concat is microseconds.\n */\nexport function resolveFlushPrompts(\n  options: ResolveFlushPromptsOptions\n): ResolvedFlushPrompts {\n  const rubric = renderPathsRubric(options.scope);\n  return {\n    prompt: DEFAULT_MEMORY_FLUSH_PROMPT.replaceAll(\n      FLUSH_PROMPT_RUBRIC_PLACEHOLDER,\n      rubric\n    ),\n    systemPrompt: DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT.replaceAll(\n      FLUSH_PROMPT_RUBRIC_PLACEHOLDER,\n      rubric\n    ),\n  };\n}\n"],"names":["DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT","renderPathsRubric","DEFAULT_MEMORY_FLUSH_PROMPT","FLUSH_PROMPT_RUBRIC_PLACEHOLDER"],"mappings":";;;;;AAAA;;;;;;;;;;;;;;;;;;;;;AAqBG;AAWH;AACO,MAAM,0BAA0B,GAAGA;AAuB1C;;;;;;AAMG;AACG,SAAU,mBAAmB,CACjC,OAAmC,EAAA;IAEnC,MAAM,MAAM,GAAGC,uBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC;IAC/C,OAAO;QACL,MAAM,EAAEC,qCAA2B,CAAC,UAAU,CAC5CC,yCAA+B,EAC/B,MAAM,CACP;QACD,YAAY,EAAEH,4CAAkC,CAAC,UAAU,CACzDG,yCAA+B,EAC/B,MAAM,CACP;KACF;AACH;;;;;;;"}

package/dist/cjs/run.cjs

@@ -39,6 +39,7 @@ class Run {
     Graph;
     returnContent = false;
     skipCleanup = false;
+    _originalCallbacksSnapshot;
     constructor(config) {
         const runId = config.runId ?? '';
         if (!runId) {
@@ -205,7 +206,19 @@ class Run {
         this.Graph.resetValues(streamOptions?.keepContent);
         /** Custom event callback to intercept and handle custom events */
         const customEventCallback = this.createCustomEventCallback();
-        const baseCallbacks = config.callbacks ?? [];
+        // IMPORTANT: snapshot the ORIGINAL caller-provided callbacks once and
+        // reuse that snapshot on every invocation. Previously we read
+        // `config.callbacks` on each call and concat'd onto it — but the same
+        // `config` object is passed back to processStream() on HITL resume, so
+        // the previous run's appended callbacks became the new "base" and we
+        // ended up stacking duplicate stream + custom handlers on every cycle.
+        // That produced N-times duplicated message_delta events on the SSE
+        // stream (character-interleaved text in the UI after tool approval).
+        if (!this._originalCallbacksSnapshot) {
+            this._originalCallbacksSnapshot =
+                config.callbacks ?? [];
+        }
+        const baseCallbacks = this._originalCallbacksSnapshot;
         const streamCallbacks = streamOptions?.callbacks
             ? this.getCallbacks(streamOptions.callbacks)
             : [];
@@ -339,7 +352,7 @@ class Run {
         }
         try {
             const state = await this.graphRunnable.getState(config);
-            return state.tasks?.some((task) => task.interrupts?.length > 0) ?? false;
+            return state.tasks.some((task) => task.interrupts.length > 0) ?? false;
         }
         catch {
             return false;
@@ -356,7 +369,7 @@ class Run {
         }
         try {
             const state = await this.graphRunnable.getState(config);
-            return (state.tasks?.flatMap((task) => (task.interrupts ?? []).map((i) => i.value)) ?? []);
+            return (state.tasks.flatMap((task) => (task.interrupts ?? []).map((i) => i.value)) ?? []);
         }
         catch {
             return [];

package/dist/cjs/run.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"run.cjs","sources":["../../src/run.ts"],"sourcesContent":["// src/run.ts\nimport './instrumentation';\nimport { ObservabilityCallbackHandler } from '@illuma-ai/observability-langchain';\nimport { Command, isGraphInterrupt } from '@langchain/langgraph';\nimport { PromptTemplate } from '@langchain/core/prompts';\nimport { RunnableLambda } from '@langchain/core/runnables';\nimport { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';\nimport { BaseCallbackHandler } from '@langchain/core/callbacks/base';\nimport type {\n  MessageContentComplex,\n  BaseMessage,\n} from '@langchain/core/messages';\nimport type { StringPromptValue } from '@langchain/core/prompt_values';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type * as t from '@/types';\nimport {\n  createCompletionTitleRunnable,\n  createTitleRunnable,\n} from '@/utils/title';\nimport { createTokenCounter, encodingForModel } from '@/utils/tokens';\nimport { GraphEvents, Callback, TitleMethod } from '@/common';\nimport { MultiAgentGraph } from '@/graphs/MultiAgentGraph';\nimport { StandardGraph } from '@/graphs/Graph';\nimport { HandlerRegistry } from '@/events';\nimport { isOpenAILike } from '@/utils/llm';\nimport { isPresent } from '@/utils/misc';\n\nexport const defaultOmitOptions = new Set([\n  'stream',\n  'thinking',\n  'streaming',\n  'maxTokens',\n  'clientOptions',\n  'thinkingConfig',\n  'thinkingBudget',\n  'includeThoughts',\n  'maxOutputTokens',\n  'additionalModelRequestFields',\n]);\n\nexport class Run<_T extends t.BaseGraphState> {\n  id: string;\n  private tokenCounter?: t.TokenCounter;\n  private handlerRegistry?: HandlerRegistry;\n  private indexTokenCountMap?: Record<string, number>;\n  graphRunnable?: t.CompiledStateWorkflow;\n  Graph: StandardGraph | MultiAgentGraph | undefined;\n  returnContent: boolean = false;\n  private skipCleanup: boolean = false;\n\n  private constructor(config: Partial<t.RunConfig>) {\n    const runId = config.runId ?? '';\n    if (!runId) {\n      throw new Error('Run ID not provided');\n    }\n\n    this.id = runId;\n    this.tokenCounter = config.tokenCounter;\n    this.indexTokenCountMap = config.indexTokenCountMap;\n\n    const handlerRegistry = new HandlerRegistry();\n\n    if (config.customHandlers) {\n      for (const [eventType, handler] of Object.entries(\n        config.customHandlers\n      )) {\n        handlerRegistry.register(eventType, handler);\n      }\n    }\n\n    this.handlerRegistry = handlerRegistry;\n\n    if (!config.graphConfig) {\n      throw new Error('Graph config not provided');\n    }\n\n    /** Handle different graph types */\n    if (config.graphConfig.type === 'multi-agent') {\n      this.graphRunnable = this.createMultiAgentGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    } else {\n      /** Default to legacy graph for 'standard' or undefined type */\n      this.graphRunnable = this.createLegacyGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.compileOptions =\n          config.graphConfig.compileOptions ?? this.Graph.compileOptions;\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    }\n\n    this.returnContent = config.returnContent ?? false;\n    this.skipCleanup = config.skipCleanup ?? false;\n  }\n\n  private createLegacyGraph(\n    config: t.LegacyGraphConfig | t.StandardGraphConfig\n  ): t.CompiledStateWorkflow {\n    let agentConfig: t.AgentInputs;\n    let signal: AbortSignal | undefined;\n\n    /** Check if this is a multi-agent style config (has agents array) */\n    if ('agents' in config && Array.isArray(config.agents)) {\n      if (config.agents.length === 0) {\n        throw new Error('At least one agent must be provided');\n      }\n      agentConfig = config.agents[0];\n      signal = config.signal;\n    } else {\n      /** Legacy path: build agent config from llmConfig */\n      const {\n        type: _type,\n        llmConfig,\n        signal: legacySignal,\n        tools = [],\n        ...agentInputs\n      } = config as t.LegacyGraphConfig;\n      const { provider, ...clientOptions } = llmConfig;\n\n      agentConfig = {\n        ...agentInputs,\n        tools,\n        provider,\n        clientOptions,\n        agentId: 'default',\n      };\n      signal = legacySignal;\n    }\n\n    const standardGraph = new StandardGraph({\n      signal,\n      runId: this.id,\n      agents: [agentConfig],\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n    /** Propagate compile options from graph config */\n    standardGraph.compileOptions = config.compileOptions;\n    this.Graph = standardGraph;\n    return standardGraph.createWorkflow();\n  }\n\n  private createMultiAgentGraph(\n    config: t.MultiAgentGraphConfig\n  ): t.CompiledStateWorkflow {\n    const { agents, edges, compileOptions, resumeFromAgentId } = config;\n\n    const multiAgentGraph = new MultiAgentGraph({\n      runId: this.id,\n      agents,\n      edges,\n      resumeFromAgentId,\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n\n    if (compileOptions != null) {\n      multiAgentGraph.compileOptions = compileOptions;\n    }\n\n    this.Graph = multiAgentGraph;\n    return multiAgentGraph.createWorkflow();\n  }\n\n  static async create<T extends t.BaseGraphState>(\n    config: t.RunConfig\n  ): Promise<Run<T>> {\n    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */\n    if (config.indexTokenCountMap && !config.tokenCounter) {\n      const gc = config.graphConfig;\n      const clientOpts =\n        'agents' in gc ? gc.agents[0]?.clientOptions : gc.clientOptions;\n      const model = (clientOpts as { model?: string } | undefined)?.model ?? '';\n      config.tokenCounter = await createTokenCounter(encodingForModel(model));\n    }\n    return new Run<T>(config);\n  }\n\n  getRunMessages(): BaseMessage[] | undefined {\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    return this.Graph.getRunMessages();\n  }\n\n  /**\n   * Manually trigger cleanup of heavy state (messages, config, etc.).\n   * Call this after all continuations are complete when using skipCleanup=true.\n   */\n  clearState(): void {\n    if (this.Graph) {\n      this.Graph.clearHeavyState();\n    }\n  }\n\n  /**\n   * Returns the normalized finish/stop reason from the last LLM invocation.\n   * Delegates to the underlying Graph instance.\n   */\n  getLastFinishReason(): string | undefined {\n    if (this.Graph && 'getLastFinishReason' in this.Graph) {\n      return (this.Graph as StandardGraph).getLastFinishReason();\n    }\n    return undefined;\n  }\n\n  /**\n   * Returns the ID of the last agent that produced output in a multi-agent graph.\n   * Used by auto-continuation to determine which agent's context to preserve\n   * when a response is truncated after an agent handoff.\n   * Returns undefined for single-agent graphs.\n   */\n  getLastActiveAgentId(): string | undefined {\n    if (this.Graph && this.Graph instanceof MultiAgentGraph) {\n      return this.Graph.getLastActiveAgentId();\n    }\n    return undefined;\n  }\n\n  /**\n   * Creates a custom event callback handler that intercepts custom events\n   * and processes them through our handler registry instead of EventStreamCallbackHandler\n   */\n  private createCustomEventCallback() {\n    return async (\n      eventName: string,\n      data: unknown,\n      runId: string,\n      tags?: string[],\n      metadata?: Record<string, unknown>\n    ): Promise<void> => {\n      const handler = this.handlerRegistry?.getHandler(eventName);\n      if (handler && this.Graph) {\n        return await handler.handle(\n          eventName,\n          data as\n            | t.StreamEventData\n            | t.ModelEndData\n            | t.RunStep\n            | t.RunStepDeltaEvent\n            | t.MessageDeltaEvent\n            | t.ReasoningDeltaEvent\n            | { result: t.ToolEndEvent },\n          metadata,\n          this.Graph\n        );\n      }\n    };\n  }\n\n  /**\n   * Processes the graph stream for a given input.\n   *\n   * @param inputs - Either the initial state (IState) for a new run, or a\n   *   Command (e.g., `new Command({ resume: ... })`) to resume from an interrupt.\n   * @param config - Runnable config with version and optional run_id.\n   * @param streamOptions - Optional stream event callbacks and options.\n   */\n  async processStream(\n    inputs: t.IState | Command,\n    config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; run_id?: string },\n    streamOptions?: t.EventStreamOptions\n  ): Promise<MessageContentComplex[] | undefined> {\n    if (this.graphRunnable == null) {\n      throw new Error(\n        'Run not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n\n    this.Graph.resetValues(streamOptions?.keepContent);\n\n    /** Custom event callback to intercept and handle custom events */\n    const customEventCallback = this.createCustomEventCallback();\n\n    const baseCallbacks = (config.callbacks as t.ProvidedCallbacks) ?? [];\n    const streamCallbacks = streamOptions?.callbacks\n      ? this.getCallbacks(streamOptions.callbacks)\n      : [];\n\n    const customHandler = BaseCallbackHandler.fromMethods({\n      [Callback.CUSTOM_EVENT]: customEventCallback,\n    });\n    customHandler.awaitHandlers = true;\n\n    config.callbacks = baseCallbacks\n      .concat(streamCallbacks)\n      .concat(customHandler);\n\n    const illumaSecretKey = process.env.ILLUMA_SECRET_KEY;\n    const illumaPublicKey = process.env.ILLUMA_PUBLIC_KEY;\n    const illumaBaseUrl = process.env.ILLUMA_BASE_URL;\n\n    if (\n      isPresent(illumaSecretKey) &&\n      isPresent(illumaPublicKey) &&\n      isPresent(illumaBaseUrl)\n    ) {\n      try {\n        const userId = config.configurable?.user_id;\n        const sessionId = config.configurable?.thread_id;\n        const handler = new ObservabilityCallbackHandler({\n          clientOptions: {\n            secretKey: illumaSecretKey!,\n            publicKey: illumaPublicKey!,\n            baseUrl: illumaBaseUrl!,\n          },\n          userId,\n          sessionId,\n          metadata: {\n            messageId: this.id,\n            parentMessageId: config.configurable?.requestBody?.parentMessageId,\n          },\n        });\n        config.callbacks = (\n          (config.callbacks as t.ProvidedCallbacks) ?? []\n        ).concat([handler]);\n      } catch {\n        // Gracefully skip if @illuma-ai/observability-node is not installed\n      }\n    }\n\n    if (!this.id) {\n      throw new Error('Run ID not provided');\n    }\n\n    config.run_id = this.id;\n    config.configurable = Object.assign(config.configurable ?? {}, {\n      run_id: this.id,\n    });\n\n    const stream = this.graphRunnable.streamEvents(inputs, config, {\n      raiseError: true,\n      /**\n       * Prevent EventStreamCallbackHandler from processing custom events.\n       * Custom events are already handled via our createCustomEventCallback()\n       * which routes them through the handlerRegistry.\n       * Without this flag, EventStreamCallbackHandler throws errors when\n       * custom events are dispatched for run IDs not in its internal map\n       * (due to timing issues in parallel execution or after run cleanup).\n       */\n      ignoreCustomEvent: true,\n    });\n\n    try {\n      for await (const event of stream) {\n        const { data, metadata, ...info } = event;\n\n        const eventName: t.EventName = info.event;\n\n        /** Skip custom events as they're handled by our callback */\n        if (eventName === GraphEvents.ON_CUSTOM_EVENT) {\n          continue;\n        }\n\n        const handler = this.handlerRegistry?.getHandler(eventName);\n        if (handler) {\n          await handler.handle(eventName, data, metadata, this.Graph);\n        }\n      }\n    } catch (e) {\n      // GraphInterrupt is expected when interrupt() fires (HITL approval flow).\n      // Exit gracefully so the host can check hasInterrupts() and resume.\n      if (isGraphInterrupt(e)) {\n        return undefined;\n      }\n      throw e;\n    }\n\n    /**\n     * Break the reference chain that keeps heavy data alive via\n     * LangGraph's internal `__pregel_scratchpad.currentTaskInput` →\n     * `@langchain/core` `RunTree.extra[lc:child_config]` →\n     * Node.js `AsyncLocalStorage` context captured by timers/promises.\n     *\n     * Without this, base64-encoded images/PDFs in message content remain\n     * reachable from lingering `Timeout` handles until GC runs.\n     */\n    if (!this.skipCleanup) {\n      if (\n        (config.configurable as Record<string, unknown> | undefined) != null\n      ) {\n        for (const key of Object.getOwnPropertySymbols(config.configurable)) {\n          const val = config.configurable[key as unknown as string] as\n            | Record<string, unknown>\n            | undefined;\n          if (\n            val != null &&\n            typeof val === 'object' &&\n            'currentTaskInput' in val\n          ) {\n            (val as Record<string, unknown>).currentTaskInput = undefined;\n          }\n          delete config.configurable[key as unknown as string];\n        }\n        config.configurable = undefined;\n      }\n      config.callbacks = undefined;\n    }\n\n    const result = this.returnContent\n      ? this.Graph.getContentParts()\n      : undefined;\n\n    if (!this.skipCleanup) {\n      this.Graph.clearHeavyState();\n    }\n    return result;\n  }\n\n  private createSystemCallback<K extends keyof t.ClientCallbacks>(\n    clientCallbacks: t.ClientCallbacks,\n    key: K\n  ): t.SystemCallbacks[K] {\n    return ((...args: unknown[]) => {\n      const clientCallback = clientCallbacks[key];\n      if (clientCallback && this.Graph) {\n        (clientCallback as (...args: unknown[]) => void)(this.Graph, ...args);\n      }\n    }) as t.SystemCallbacks[K];\n  }\n\n  /**\n   * Checks whether the graph was interrupted (e.g., by HITL tool approval).\n   * Call after processStream() returns to determine if the graph is waiting\n   * for a resume via Command({ resume }).\n   *\n   * Requires a checkpointer to be configured — without one, interrupt state\n   * is not persisted and this always returns false.\n   */\n  async hasInterrupts(\n    config: Partial<RunnableConfig>\n  ): Promise<boolean> {\n    if (!this.graphRunnable) {\n      return false;\n    }\n    try {\n      const state = await this.graphRunnable.getState(config);\n      return state.tasks?.some((task) => task.interrupts?.length > 0) ?? false;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Returns the interrupt values from the graph state.\n   * Each interrupt's `value` contains the data passed to `interrupt()` by the node\n   * (e.g., a ToolApprovalRequest for HITL).\n   */\n  async getInterruptValues(\n    config: Partial<RunnableConfig>\n  ): Promise<unknown[]> {\n    if (!this.graphRunnable) {\n      return [];\n    }\n    try {\n      const state = await this.graphRunnable.getState(config);\n      return (\n        state.tasks?.flatMap((task) =>\n          (task.interrupts ?? []).map((i) => i.value)\n        ) ?? []\n      );\n    } catch {\n      return [];\n    }\n  }\n\n  getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks {\n    return {\n      [Callback.TOOL_ERROR]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_ERROR\n      ),\n      [Callback.TOOL_START]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_START\n      ),\n      [Callback.TOOL_END]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_END\n      ),\n    };\n  }\n\n  async generateTitle({\n    provider,\n    inputText,\n    contentParts,\n    titlePrompt,\n    clientOptions,\n    chainOptions,\n    skipLanguage,\n    titleMethod = TitleMethod.COMPLETION,\n    titlePromptTemplate,\n  }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {\n    const titleSecretKey = process.env.ILLUMA_SECRET_KEY;\n    const titlePublicKey = process.env.ILLUMA_PUBLIC_KEY;\n    const titleBaseUrl = process.env.ILLUMA_BASE_URL;\n\n    if (\n      chainOptions != null &&\n      isPresent(titleSecretKey) &&\n      isPresent(titlePublicKey) &&\n      isPresent(titleBaseUrl)\n    ) {\n      try {\n        const userId = chainOptions.configurable?.user_id;\n        const sessionId = chainOptions.configurable?.thread_id;\n        const handler = new ObservabilityCallbackHandler({\n          clientOptions: {\n            secretKey: titleSecretKey!,\n            publicKey: titlePublicKey!,\n            baseUrl: titleBaseUrl!,\n          },\n          userId,\n          sessionId,\n          metadata: {\n            messageId: 'title-' + this.id,\n          },\n        });\n        chainOptions.callbacks = (\n          (chainOptions.callbacks as t.ProvidedCallbacks) ?? []\n        ).concat([handler]);\n      } catch {\n        // Gracefully skip if @illuma-ai/observability-node is not installed\n      }\n    }\n\n    const convoTemplate = PromptTemplate.fromTemplate(\n      titlePromptTemplate ?? 'User: {input}\\nAI: {output}'\n    );\n\n    const response = contentParts\n      .map((part) => {\n        if (part?.type === 'text') return part.text;\n        return '';\n      })\n      .join('\\n');\n\n    const model = this.Graph?.getNewModel({\n      provider,\n      clientOptions,\n    });\n    if (!model) {\n      return { language: '', title: '' };\n    }\n    if (\n      isOpenAILike(provider) &&\n      (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)\n    ) {\n      model.temperature = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.temperature as number;\n      model.topP = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.topP as number;\n      model.frequencyPenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.frequencyPenalty as number;\n      model.presencePenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.presencePenalty as number;\n      model.n = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.n as number;\n    }\n\n    const convoToTitleInput = new RunnableLambda({\n      func: (\n        promptValue: StringPromptValue\n      ): { convo: string; inputText: string; skipLanguage?: boolean } => ({\n        convo: promptValue.value,\n        inputText,\n        skipLanguage,\n      }),\n    }).withConfig({ runName: 'ConvoTransform' });\n\n    const titleChain =\n      titleMethod === TitleMethod.COMPLETION\n        ? await createCompletionTitleRunnable(model, titlePrompt)\n        : await createTitleRunnable(model, titlePrompt);\n\n    /** Pipes `convoTemplate` -> `transformer` -> `titleChain` */\n    const fullChain = convoTemplate\n      .withConfig({ runName: 'ConvoTemplate' })\n      .pipe(convoToTitleInput)\n      .pipe(titleChain)\n      .withConfig({ runName: 'TitleChain' });\n\n    const invokeConfig = Object.assign({}, chainOptions, {\n      run_id: this.id,\n      runId: this.id,\n    });\n\n    try {\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        invokeConfig\n      );\n    } catch (_e) {\n      // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments\n      // But preserve observability handler if it exists\n      const observabilityHandler = (\n        invokeConfig.callbacks as t.ProvidedCallbacks\n      )?.find((cb) => cb instanceof ObservabilityCallbackHandler);\n      const { callbacks: _cb, ...rest } = invokeConfig;\n      const safeConfig = Object.assign({}, rest, {\n        callbacks: observabilityHandler ? [observabilityHandler] : [],\n      });\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        safeConfig as Partial<RunnableConfig>\n      );\n    }\n  }\n}\n"],"names":["HandlerRegistry","StandardGraph","MultiAgentGraph","createTokenCounter","encodingForModel","BaseCallbackHandler","Callback","isPresent","ObservabilityCallbackHandler","GraphEvents","isGraphInterrupt","TitleMethod","PromptTemplate","isOpenAILike","ChatOpenAI","AzureChatOpenAI","RunnableLambda","createCompletionTitleRunnable","createTitleRunnable"],"mappings":"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"}
+{"version":3,"file":"run.cjs","sources":["../../src/run.ts"],"sourcesContent":["// src/run.ts\nimport './instrumentation';\nimport { ObservabilityCallbackHandler } from '@illuma-ai/observability-langchain';\nimport { Command, isGraphInterrupt } from '@langchain/langgraph';\nimport { PromptTemplate } from '@langchain/core/prompts';\nimport { RunnableLambda } from '@langchain/core/runnables';\nimport { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';\nimport { BaseCallbackHandler } from '@langchain/core/callbacks/base';\nimport type {\n  MessageContentComplex,\n  BaseMessage,\n} from '@langchain/core/messages';\nimport type { StringPromptValue } from '@langchain/core/prompt_values';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type * as t from '@/types';\nimport {\n  createCompletionTitleRunnable,\n  createTitleRunnable,\n} from '@/utils/title';\nimport { createTokenCounter, encodingForModel } from '@/utils/tokens';\nimport { GraphEvents, Callback, TitleMethod } from '@/common';\nimport { MultiAgentGraph } from '@/graphs/MultiAgentGraph';\nimport { StandardGraph } from '@/graphs/Graph';\nimport { HandlerRegistry } from '@/events';\nimport { isOpenAILike } from '@/utils/llm';\nimport { isPresent } from '@/utils/misc';\n\nexport const defaultOmitOptions = new Set([\n  'stream',\n  'thinking',\n  'streaming',\n  'maxTokens',\n  'clientOptions',\n  'thinkingConfig',\n  'thinkingBudget',\n  'includeThoughts',\n  'maxOutputTokens',\n  'additionalModelRequestFields',\n]);\n\nexport class Run<_T extends t.BaseGraphState> {\n  id: string;\n  private tokenCounter?: t.TokenCounter;\n  private handlerRegistry?: HandlerRegistry;\n  private indexTokenCountMap?: Record<string, number>;\n  graphRunnable?: t.CompiledStateWorkflow;\n  Graph: StandardGraph | MultiAgentGraph | undefined;\n  returnContent: boolean = false;\n  private skipCleanup: boolean = false;\n  private _originalCallbacksSnapshot?: t.ProvidedCallbacks;\n\n  private constructor(config: Partial<t.RunConfig>) {\n    const runId = config.runId ?? '';\n    if (!runId) {\n      throw new Error('Run ID not provided');\n    }\n\n    this.id = runId;\n    this.tokenCounter = config.tokenCounter;\n    this.indexTokenCountMap = config.indexTokenCountMap;\n\n    const handlerRegistry = new HandlerRegistry();\n\n    if (config.customHandlers) {\n      for (const [eventType, handler] of Object.entries(\n        config.customHandlers\n      )) {\n        handlerRegistry.register(eventType, handler);\n      }\n    }\n\n    this.handlerRegistry = handlerRegistry;\n\n    if (!config.graphConfig) {\n      throw new Error('Graph config not provided');\n    }\n\n    /** Handle different graph types */\n    if (config.graphConfig.type === 'multi-agent') {\n      this.graphRunnable = this.createMultiAgentGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    } else {\n      /** Default to legacy graph for 'standard' or undefined type */\n      this.graphRunnable = this.createLegacyGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.compileOptions =\n          config.graphConfig.compileOptions ?? this.Graph.compileOptions;\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    }\n\n    this.returnContent = config.returnContent ?? false;\n    this.skipCleanup = config.skipCleanup ?? false;\n  }\n\n  private createLegacyGraph(\n    config: t.LegacyGraphConfig | t.StandardGraphConfig\n  ): t.CompiledStateWorkflow {\n    let agentConfig: t.AgentInputs;\n    let signal: AbortSignal | undefined;\n\n    /** Check if this is a multi-agent style config (has agents array) */\n    if ('agents' in config && Array.isArray(config.agents)) {\n      if (config.agents.length === 0) {\n        throw new Error('At least one agent must be provided');\n      }\n      agentConfig = config.agents[0];\n      signal = config.signal;\n    } else {\n      /** Legacy path: build agent config from llmConfig */\n      const {\n        type: _type,\n        llmConfig,\n        signal: legacySignal,\n        tools = [],\n        ...agentInputs\n      } = config as t.LegacyGraphConfig;\n      const { provider, ...clientOptions } = llmConfig;\n\n      agentConfig = {\n        ...agentInputs,\n        tools,\n        provider,\n        clientOptions,\n        agentId: 'default',\n      };\n      signal = legacySignal;\n    }\n\n    const standardGraph = new StandardGraph({\n      signal,\n      runId: this.id,\n      agents: [agentConfig],\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n    /** Propagate compile options from graph config */\n    standardGraph.compileOptions = config.compileOptions;\n    this.Graph = standardGraph;\n    return standardGraph.createWorkflow();\n  }\n\n  private createMultiAgentGraph(\n    config: t.MultiAgentGraphConfig\n  ): t.CompiledStateWorkflow {\n    const { agents, edges, compileOptions, resumeFromAgentId } = config;\n\n    const multiAgentGraph = new MultiAgentGraph({\n      runId: this.id,\n      agents,\n      edges,\n      resumeFromAgentId,\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n\n    if (compileOptions != null) {\n      multiAgentGraph.compileOptions = compileOptions;\n    }\n\n    this.Graph = multiAgentGraph;\n    return multiAgentGraph.createWorkflow();\n  }\n\n  static async create<T extends t.BaseGraphState>(\n    config: t.RunConfig\n  ): Promise<Run<T>> {\n    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */\n    if (config.indexTokenCountMap && !config.tokenCounter) {\n      const gc = config.graphConfig;\n      const clientOpts =\n        'agents' in gc ? gc.agents[0]?.clientOptions : gc.clientOptions;\n      const model = (clientOpts as { model?: string } | undefined)?.model ?? '';\n      config.tokenCounter = await createTokenCounter(encodingForModel(model));\n    }\n    return new Run<T>(config);\n  }\n\n  getRunMessages(): BaseMessage[] | undefined {\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    return this.Graph.getRunMessages();\n  }\n\n  /**\n   * Manually trigger cleanup of heavy state (messages, config, etc.).\n   * Call this after all continuations are complete when using skipCleanup=true.\n   */\n  clearState(): void {\n    if (this.Graph) {\n      this.Graph.clearHeavyState();\n    }\n  }\n\n  /**\n   * Returns the normalized finish/stop reason from the last LLM invocation.\n   * Delegates to the underlying Graph instance.\n   */\n  getLastFinishReason(): string | undefined {\n    if (this.Graph && 'getLastFinishReason' in this.Graph) {\n      return (this.Graph as StandardGraph).getLastFinishReason();\n    }\n    return undefined;\n  }\n\n  /**\n   * Returns the ID of the last agent that produced output in a multi-agent graph.\n   * Used by auto-continuation to determine which agent's context to preserve\n   * when a response is truncated after an agent handoff.\n   * Returns undefined for single-agent graphs.\n   */\n  getLastActiveAgentId(): string | undefined {\n    if (this.Graph && this.Graph instanceof MultiAgentGraph) {\n      return this.Graph.getLastActiveAgentId();\n    }\n    return undefined;\n  }\n\n  /**\n   * Creates a custom event callback handler that intercepts custom events\n   * and processes them through our handler registry instead of EventStreamCallbackHandler\n   */\n  private createCustomEventCallback() {\n    return async (\n      eventName: string,\n      data: unknown,\n      runId: string,\n      tags?: string[],\n      metadata?: Record<string, unknown>\n    ): Promise<void> => {\n      const handler = this.handlerRegistry?.getHandler(eventName);\n      if (handler && this.Graph) {\n        return await handler.handle(\n          eventName,\n          data as\n            | t.StreamEventData\n            | t.ModelEndData\n            | t.RunStep\n            | t.RunStepDeltaEvent\n            | t.MessageDeltaEvent\n            | t.ReasoningDeltaEvent\n            | { result: t.ToolEndEvent },\n          metadata,\n          this.Graph\n        );\n      }\n    };\n  }\n\n  /**\n   * Processes the graph stream for a given input.\n   *\n   * @param inputs - Either the initial state (IState) for a new run, or a\n   *   Command (e.g., `new Command({ resume: ... })`) to resume from an interrupt.\n   * @param config - Runnable config with version and optional run_id.\n   * @param streamOptions - Optional stream event callbacks and options.\n   */\n  async processStream(\n    inputs: t.IState | Command,\n    config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; run_id?: string },\n    streamOptions?: t.EventStreamOptions\n  ): Promise<MessageContentComplex[] | undefined> {\n    if (this.graphRunnable == null) {\n      throw new Error(\n        'Run not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n\n    this.Graph.resetValues(streamOptions?.keepContent);\n\n    /** Custom event callback to intercept and handle custom events */\n    const customEventCallback = this.createCustomEventCallback();\n\n    // IMPORTANT: snapshot the ORIGINAL caller-provided callbacks once and\n    // reuse that snapshot on every invocation. Previously we read\n    // `config.callbacks` on each call and concat'd onto it — but the same\n    // `config` object is passed back to processStream() on HITL resume, so\n    // the previous run's appended callbacks became the new \"base\" and we\n    // ended up stacking duplicate stream + custom handlers on every cycle.\n    // That produced N-times duplicated message_delta events on the SSE\n    // stream (character-interleaved text in the UI after tool approval).\n    if (!this._originalCallbacksSnapshot) {\n      this._originalCallbacksSnapshot =\n        (config.callbacks as t.ProvidedCallbacks) ?? [];\n    }\n    const baseCallbacks = this._originalCallbacksSnapshot;\n    const streamCallbacks = streamOptions?.callbacks\n      ? this.getCallbacks(streamOptions.callbacks)\n      : [];\n\n    const customHandler = BaseCallbackHandler.fromMethods({\n      [Callback.CUSTOM_EVENT]: customEventCallback,\n    });\n    customHandler.awaitHandlers = true;\n\n    config.callbacks = baseCallbacks\n      .concat(streamCallbacks)\n      .concat(customHandler);\n\n    const illumaSecretKey = process.env.ILLUMA_SECRET_KEY;\n    const illumaPublicKey = process.env.ILLUMA_PUBLIC_KEY;\n    const illumaBaseUrl = process.env.ILLUMA_BASE_URL;\n\n    if (\n      isPresent(illumaSecretKey) &&\n      isPresent(illumaPublicKey) &&\n      isPresent(illumaBaseUrl)\n    ) {\n      try {\n        const userId = config.configurable?.user_id;\n        const sessionId = config.configurable?.thread_id;\n        const handler = new ObservabilityCallbackHandler({\n          clientOptions: {\n            secretKey: illumaSecretKey!,\n            publicKey: illumaPublicKey!,\n            baseUrl: illumaBaseUrl!,\n          },\n          userId,\n          sessionId,\n          metadata: {\n            messageId: this.id,\n            parentMessageId: config.configurable?.requestBody?.parentMessageId,\n          },\n        });\n        config.callbacks = (\n          (config.callbacks as t.ProvidedCallbacks) ?? []\n        ).concat([handler]);\n      } catch {\n        // Gracefully skip if @illuma-ai/observability-node is not installed\n      }\n    }\n\n    if (!this.id) {\n      throw new Error('Run ID not provided');\n    }\n\n    config.run_id = this.id;\n    config.configurable = Object.assign(config.configurable ?? {}, {\n      run_id: this.id,\n    });\n\n    const stream = this.graphRunnable.streamEvents(inputs, config, {\n      raiseError: true,\n      /**\n       * Prevent EventStreamCallbackHandler from processing custom events.\n       * Custom events are already handled via our createCustomEventCallback()\n       * which routes them through the handlerRegistry.\n       * Without this flag, EventStreamCallbackHandler throws errors when\n       * custom events are dispatched for run IDs not in its internal map\n       * (due to timing issues in parallel execution or after run cleanup).\n       */\n      ignoreCustomEvent: true,\n    });\n\n    try {\n      for await (const event of stream) {\n        const { data, metadata, ...info } = event;\n\n        const eventName: t.EventName = info.event;\n\n        /** Skip custom events as they're handled by our callback */\n        if (eventName === GraphEvents.ON_CUSTOM_EVENT) {\n          continue;\n        }\n\n        const handler = this.handlerRegistry?.getHandler(eventName);\n        if (handler) {\n          await handler.handle(eventName, data, metadata, this.Graph);\n        }\n      }\n    } catch (e) {\n      // GraphInterrupt is expected when interrupt() fires (HITL approval flow).\n      // Exit gracefully so the host can check hasInterrupts() and resume.\n      if (isGraphInterrupt(e)) {\n        return undefined;\n      }\n      throw e;\n    }\n\n    /**\n     * Break the reference chain that keeps heavy data alive via\n     * LangGraph's internal `__pregel_scratchpad.currentTaskInput` →\n     * `@langchain/core` `RunTree.extra[lc:child_config]` →\n     * Node.js `AsyncLocalStorage` context captured by timers/promises.\n     *\n     * Without this, base64-encoded images/PDFs in message content remain\n     * reachable from lingering `Timeout` handles until GC runs.\n     */\n    if (!this.skipCleanup) {\n      if (\n        (config.configurable as Record<string, unknown> | undefined) != null\n      ) {\n        for (const key of Object.getOwnPropertySymbols(config.configurable)) {\n          const val = config.configurable[key as unknown as string] as\n            | Record<string, unknown>\n            | undefined;\n          if (\n            val != null &&\n            typeof val === 'object' &&\n            'currentTaskInput' in val\n          ) {\n            (val as Record<string, unknown>).currentTaskInput = undefined;\n          }\n          delete config.configurable[key as unknown as string];\n        }\n        config.configurable = undefined;\n      }\n      config.callbacks = undefined;\n    }\n\n    const result = this.returnContent\n      ? this.Graph.getContentParts()\n      : undefined;\n\n    if (!this.skipCleanup) {\n      this.Graph.clearHeavyState();\n    }\n    return result;\n  }\n\n  private createSystemCallback<K extends keyof t.ClientCallbacks>(\n    clientCallbacks: t.ClientCallbacks,\n    key: K\n  ): t.SystemCallbacks[K] {\n    return ((...args: unknown[]) => {\n      const clientCallback = clientCallbacks[key];\n      if (clientCallback && this.Graph) {\n        (clientCallback as (...args: unknown[]) => void)(this.Graph, ...args);\n      }\n    }) as t.SystemCallbacks[K];\n  }\n\n  /**\n   * Checks whether the graph was interrupted (e.g., by HITL tool approval).\n   * Call after processStream() returns to determine if the graph is waiting\n   * for a resume via Command({ resume }).\n   *\n   * Requires a checkpointer to be configured — without one, interrupt state\n   * is not persisted and this always returns false.\n   */\n  async hasInterrupts(config: Partial<RunnableConfig>): Promise<boolean> {\n    if (!this.graphRunnable) {\n      return false;\n    }\n    try {\n      const state = await this.graphRunnable.getState(config);\n      return state.tasks.some((task) => task.interrupts.length > 0) ?? false;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Returns the interrupt values from the graph state.\n   * Each interrupt's `value` contains the data passed to `interrupt()` by the node\n   * (e.g., a ToolApprovalRequest for HITL).\n   */\n  async getInterruptValues(\n    config: Partial<RunnableConfig>\n  ): Promise<unknown[]> {\n    if (!this.graphRunnable) {\n      return [];\n    }\n    try {\n      const state = await this.graphRunnable.getState(config);\n      return (\n        state.tasks.flatMap((task) =>\n          (task.interrupts ?? []).map((i) => i.value)\n        ) ?? []\n      );\n    } catch {\n      return [];\n    }\n  }\n\n  getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks {\n    return {\n      [Callback.TOOL_ERROR]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_ERROR\n      ),\n      [Callback.TOOL_START]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_START\n      ),\n      [Callback.TOOL_END]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_END\n      ),\n    };\n  }\n\n  async generateTitle({\n    provider,\n    inputText,\n    contentParts,\n    titlePrompt,\n    clientOptions,\n    chainOptions,\n    skipLanguage,\n    titleMethod = TitleMethod.COMPLETION,\n    titlePromptTemplate,\n  }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {\n    const titleSecretKey = process.env.ILLUMA_SECRET_KEY;\n    const titlePublicKey = process.env.ILLUMA_PUBLIC_KEY;\n    const titleBaseUrl = process.env.ILLUMA_BASE_URL;\n\n    if (\n      chainOptions != null &&\n      isPresent(titleSecretKey) &&\n      isPresent(titlePublicKey) &&\n      isPresent(titleBaseUrl)\n    ) {\n      try {\n        const userId = chainOptions.configurable?.user_id;\n        const sessionId = chainOptions.configurable?.thread_id;\n        const handler = new ObservabilityCallbackHandler({\n          clientOptions: {\n            secretKey: titleSecretKey!,\n            publicKey: titlePublicKey!,\n            baseUrl: titleBaseUrl!,\n          },\n          userId,\n          sessionId,\n          metadata: {\n            messageId: 'title-' + this.id,\n          },\n        });\n        chainOptions.callbacks = (\n          (chainOptions.callbacks as t.ProvidedCallbacks) ?? []\n        ).concat([handler]);\n      } catch {\n        // Gracefully skip if @illuma-ai/observability-node is not installed\n      }\n    }\n\n    const convoTemplate = PromptTemplate.fromTemplate(\n      titlePromptTemplate ?? 'User: {input}\\nAI: {output}'\n    );\n\n    const response = contentParts\n      .map((part) => {\n        if (part?.type === 'text') return part.text;\n        return '';\n      })\n      .join('\\n');\n\n    const model = this.Graph?.getNewModel({\n      provider,\n      clientOptions,\n    });\n    if (!model) {\n      return { language: '', title: '' };\n    }\n    if (\n      isOpenAILike(provider) &&\n      (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)\n    ) {\n      model.temperature = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.temperature as number;\n      model.topP = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.topP as number;\n      model.frequencyPenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.frequencyPenalty as number;\n      model.presencePenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.presencePenalty as number;\n      model.n = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.n as number;\n    }\n\n    const convoToTitleInput = new RunnableLambda({\n      func: (\n        promptValue: StringPromptValue\n      ): { convo: string; inputText: string; skipLanguage?: boolean } => ({\n        convo: promptValue.value,\n        inputText,\n        skipLanguage,\n      }),\n    }).withConfig({ runName: 'ConvoTransform' });\n\n    const titleChain =\n      titleMethod === TitleMethod.COMPLETION\n        ? await createCompletionTitleRunnable(model, titlePrompt)\n        : await createTitleRunnable(model, titlePrompt);\n\n    /** Pipes `convoTemplate` -> `transformer` -> `titleChain` */\n    const fullChain = convoTemplate\n      .withConfig({ runName: 'ConvoTemplate' })\n      .pipe(convoToTitleInput)\n      .pipe(titleChain)\n      .withConfig({ runName: 'TitleChain' });\n\n    const invokeConfig = Object.assign({}, chainOptions, {\n      run_id: this.id,\n      runId: this.id,\n    });\n\n    try {\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        invokeConfig\n      );\n    } catch (_e) {\n      // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments\n      // But preserve observability handler if it exists\n      const observabilityHandler = (\n        invokeConfig.callbacks as t.ProvidedCallbacks\n      )?.find((cb) => cb instanceof ObservabilityCallbackHandler);\n      const { callbacks: _cb, ...rest } = invokeConfig;\n      const safeConfig = Object.assign({}, rest, {\n        callbacks: observabilityHandler ? [observabilityHandler] : [],\n      });\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        safeConfig as Partial<RunnableConfig>\n      );\n    }\n  }\n}\n"],"names":["HandlerRegistry","StandardGraph","MultiAgentGraph","createTokenCounter","encodingForModel","BaseCallbackHandler","Callback","isPresent","ObservabilityCallbackHandler","GraphEvents","isGraphInterrupt","TitleMethod","PromptTemplate","isOpenAILike","ChatOpenAI","AzureChatOpenAI","RunnableLambda","createCompletionTitleRunnable","createTitleRunnable"],"mappings":"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"}

package/dist/cjs/tools/AskUser.cjs

@@ -8,7 +8,12 @@ require('./approval/constants.cjs');
 const AskUserToolName = _enum.Constants.ASK_USER;
 const AskUserDescription = 'Ask the user clarification questions with structured options before taking action. ' +
     'For a single key question, use question+options. For multiple related questions, use steps[] (max 3 steps). ' +
-    'Each step can be single-select or multi-select. After receiving answers, proceed immediately.';
+    'Each step can be single-select or multi-select. After receiving answers, proceed immediately. ' +
+    'BEFORE calling this tool, ALWAYS emit one short sentence of plain-text output (one line, <= 20 words) ' +
+    'explaining why you need more information — e.g. "I need a few details to help with that.". ' +
+    'NEVER include an option like "I\'ll give it myself", "Other", "Something else", "Custom", "None of the above", ' +
+    'or any equivalent free-text escape hatch — the UI already provides a dedicated "Something else" button ' +
+    'for free-text responses. Only list concrete, mutually-exclusive choices.';
 const AskUserOptionSchema = zod.z.object({
     label: zod.z.string().describe('Short display label'),
     value: zod.z.string().describe('Machine-readable value returned when selected'),

package/dist/cjs/tools/AskUser.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AskUser.cjs","sources":["../../../src/tools/AskUser.ts"],"sourcesContent":["import { tool } from '@langchain/core/tools';\nimport { z } from 'zod';\nimport { Constants } from '@/common';\n\nexport const AskUserToolName = Constants.ASK_USER;\n\nexport const AskUserDescription =\n  'Ask the user clarification questions with structured options before taking action. ' +\n  'For a single key question, use question+options. For multiple related questions, use steps[] (max 3 steps). ' +\n  'Each step can be single-select or multi-select. After receiving answers, proceed immediately.';\n\nconst AskUserOptionSchema = z.object({\n  label: z.string().describe('Short display label'),\n  value: z.string().describe('Machine-readable value returned when selected'),\n  description: z.string().optional().describe('Optional longer description'),\n});\n\nexport const AskUserStepSchema = z.object({\n  question: z.string().describe('The question to ask the user for this step'),\n  options: z\n    .array(AskUserOptionSchema)\n    .min(2)\n    .max(6)\n    .describe('Structured options for this step (2-6 choices)'),\n  type: z\n    .enum(['single', 'multi'])\n    .default('single')\n    .describe('Selection type: single-select or multi-select'),\n});\n\nexport type AskUserStep = z.infer<typeof AskUserStepSchema>;\n\nconst AskUserSchema = z\n  .object({\n    question: z\n      .string()\n      .optional()\n      .describe('The question to ask the user. Be specific and clear.'),\n    options: z\n      .array(AskUserOptionSchema)\n      .min(2)\n      .max(6)\n      .optional()\n      .describe('Structured options for the user (2-6 choices)'),\n    context: z.string().optional().describe('Why you are asking this question'),\n    steps: z\n      .array(AskUserStepSchema)\n      .min(1)\n      .max(5)\n      .optional()\n      .describe('Multi-step wizard: array of question steps (1-5 steps)'),\n  })\n  // passthrough() preserves extra fields like _selectedOption injected by the\n  // approval flow's modifiedArgs — without this, Zod strips unknown keys.\n  .passthrough()\n  .refine(\n    (data) => {\n      // Must have either steps[] OR question+options (legacy format)\n      const hasSteps = Array.isArray(data.steps) && data.steps.length > 0;\n      const hasLegacy =\n        typeof data.question === 'string' && Array.isArray(data.options);\n      return hasSteps || hasLegacy;\n    },\n    {\n      message: 'Either steps[] or question+options must be provided',\n    }\n  );\n\n/**\n * Represents a single step selection from the multi-step wizard UI.\n * Exported for use by both ranger web client and browser extension.\n */\nexport type StepSelection = {\n  values: string[];\n  customInput?: string;\n};\n\n/** Field names injected into modifiedArgs by the approval flow */\nexport const HITL_FIELDS = {\n  SELECTIONS: '_selections',\n  SELECTED_OPTION: '_selectedOption',\n  CUSTOM_INPUT: '_customInput',\n} as const;\n\n/**\n * Creates an ask_user tool that lets the LLM ask clarification questions mid-conversation.\n *\n * How it works:\n * 1. LLM calls ask_user(question, options) OR ask_user(steps)\n * 2. ToolNode.requiresApproval() → always true (per-tool rule in askUserRules.js)\n * 3. ToolNode.requestApproval() promotes options/question/steps to top-level fields on the event\n * 4. Frontend HumanInputPopover renders option cards + freeform text input\n * 5. User selects option(s) OR types custom input →\n *    backend resolves with modifiedArgs containing _selections, _selectedOption, or _customInput\n * 6. Tool executes, reads the user's choice, returns result to LLM\n */\n// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\nexport function createAskUserTool() {\n  return tool(\n    async (args) => {\n      const extArgs = args as Record<string, unknown>;\n      const selections = extArgs[HITL_FIELDS.SELECTIONS] as\n        | StepSelection[]\n        | undefined;\n      const customInput = extArgs[HITL_FIELDS.CUSTOM_INPUT] as\n        | string\n        | undefined;\n      const selectedOption = extArgs[HITL_FIELDS.SELECTED_OPTION] as\n        | string\n        | undefined;\n\n      // Multi-step wizard flow: _selections is an array of { values, customInput? } per step\n      if (\n        selections &&\n        Array.isArray(selections) &&\n        Array.isArray(args.steps)\n      ) {\n        const lines: string[] = [];\n        for (let i = 0; i < args.steps.length; i++) {\n          const step = args.steps[i];\n          const sel = selections[i];\n          if (!sel || (sel.values.length === 0 && !sel.customInput)) {\n            lines.push(`${i + 1}. ${step.question} → (skipped)`);\n            continue;\n          }\n          if (sel.customInput) {\n            lines.push(`${i + 1}. ${step.question} → \"${sel.customInput}\"`);\n            continue;\n          }\n          // Resolve value(s) to labels\n          const labels = sel.values.map((v) => {\n            const opt = step.options.find((o) => o.value === v);\n            return opt?.label || v;\n          });\n          lines.push(`${i + 1}. ${step.question} → ${labels.join(', ')}`);\n        }\n        return `User responses:\\n${lines.join('\\n')}`;\n      }\n\n      // Legacy: custom freeform input takes priority — user explicitly chose \"none of these\"\n      if (customInput) {\n        return `User provided custom response: \"${customInput}\"`;\n      }\n\n      if (selectedOption) {\n        const option = args.options?.find((o) => o.value === selectedOption);\n        return `User selected: \"${option?.label || selectedOption}\" (value: ${selectedOption})`;\n      }\n\n      // Fallback — should not happen in interactive mode since approval always fires first\n      return 'No user response received.';\n    },\n    {\n      name: AskUserToolName,\n      description: AskUserDescription,\n      schema: AskUserSchema,\n    }\n  );\n}\n"],"names":["Constants","z","tool"],"mappings":"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"}
+{"version":3,"file":"AskUser.cjs","sources":["../../../src/tools/AskUser.ts"],"sourcesContent":["import { tool } from '@langchain/core/tools';\nimport { z } from 'zod';\nimport { Constants } from '@/common';\n\nexport const AskUserToolName = Constants.ASK_USER;\n\nexport const AskUserDescription =\n  'Ask the user clarification questions with structured options before taking action. ' +\n  'For a single key question, use question+options. For multiple related questions, use steps[] (max 3 steps). ' +\n  'Each step can be single-select or multi-select. After receiving answers, proceed immediately. ' +\n  'BEFORE calling this tool, ALWAYS emit one short sentence of plain-text output (one line, <= 20 words) ' +\n  'explaining why you need more information — e.g. \"I need a few details to help with that.\". ' +\n  'NEVER include an option like \"I\\'ll give it myself\", \"Other\", \"Something else\", \"Custom\", \"None of the above\", ' +\n  'or any equivalent free-text escape hatch — the UI already provides a dedicated \"Something else\" button ' +\n  'for free-text responses. Only list concrete, mutually-exclusive choices.';\n\nconst AskUserOptionSchema = z.object({\n  label: z.string().describe('Short display label'),\n  value: z.string().describe('Machine-readable value returned when selected'),\n  description: z.string().optional().describe('Optional longer description'),\n});\n\nexport const AskUserStepSchema = z.object({\n  question: z.string().describe('The question to ask the user for this step'),\n  options: z\n    .array(AskUserOptionSchema)\n    .min(2)\n    .max(6)\n    .describe('Structured options for this step (2-6 choices)'),\n  type: z\n    .enum(['single', 'multi'])\n    .default('single')\n    .describe('Selection type: single-select or multi-select'),\n});\n\nexport type AskUserStep = z.infer<typeof AskUserStepSchema>;\n\nconst AskUserSchema = z\n  .object({\n    question: z\n      .string()\n      .optional()\n      .describe('The question to ask the user. Be specific and clear.'),\n    options: z\n      .array(AskUserOptionSchema)\n      .min(2)\n      .max(6)\n      .optional()\n      .describe('Structured options for the user (2-6 choices)'),\n    context: z.string().optional().describe('Why you are asking this question'),\n    steps: z\n      .array(AskUserStepSchema)\n      .min(1)\n      .max(5)\n      .optional()\n      .describe('Multi-step wizard: array of question steps (1-5 steps)'),\n  })\n  // passthrough() preserves extra fields like _selectedOption injected by the\n  // approval flow's modifiedArgs — without this, Zod strips unknown keys.\n  .passthrough()\n  .refine(\n    (data) => {\n      // Must have either steps[] OR question+options (legacy format)\n      const hasSteps = Array.isArray(data.steps) && data.steps.length > 0;\n      const hasLegacy =\n        typeof data.question === 'string' && Array.isArray(data.options);\n      return hasSteps || hasLegacy;\n    },\n    {\n      message: 'Either steps[] or question+options must be provided',\n    }\n  );\n\n/**\n * Represents a single step selection from the multi-step wizard UI.\n * Exported for use by both the host web client and browser extension.\n */\nexport type StepSelection = {\n  values: string[];\n  customInput?: string;\n};\n\n/** Field names injected into modifiedArgs by the approval flow */\nexport const HITL_FIELDS = {\n  SELECTIONS: '_selections',\n  SELECTED_OPTION: '_selectedOption',\n  CUSTOM_INPUT: '_customInput',\n} as const;\n\n/**\n * Creates an ask_user tool that lets the LLM ask clarification questions mid-conversation.\n *\n * How it works:\n * 1. LLM calls ask_user(question, options) OR ask_user(steps)\n * 2. ToolNode.requiresApproval() → always true (per-tool rule in askUserRules.js)\n * 3. ToolNode.requestApproval() promotes options/question/steps to top-level fields on the event\n * 4. Frontend HumanInputPopover renders option cards + freeform text input\n * 5. User selects option(s) OR types custom input →\n *    backend resolves with modifiedArgs containing _selections, _selectedOption, or _customInput\n * 6. Tool executes, reads the user's choice, returns result to LLM\n */\n// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\nexport function createAskUserTool() {\n  return tool(\n    async (args) => {\n      const extArgs = args as Record<string, unknown>;\n      const selections = extArgs[HITL_FIELDS.SELECTIONS] as\n        | StepSelection[]\n        | undefined;\n      const customInput = extArgs[HITL_FIELDS.CUSTOM_INPUT] as\n        | string\n        | undefined;\n      const selectedOption = extArgs[HITL_FIELDS.SELECTED_OPTION] as\n        | string\n        | undefined;\n\n      // Multi-step wizard flow: _selections is an array of { values, customInput? } per step\n      if (\n        selections &&\n        Array.isArray(selections) &&\n        Array.isArray(args.steps)\n      ) {\n        const lines: string[] = [];\n        for (let i = 0; i < args.steps.length; i++) {\n          const step = args.steps[i];\n          const sel = selections[i];\n          if (!sel || (sel.values.length === 0 && !sel.customInput)) {\n            lines.push(`${i + 1}. ${step.question} → (skipped)`);\n            continue;\n          }\n          if (sel.customInput) {\n            lines.push(`${i + 1}. ${step.question} → \"${sel.customInput}\"`);\n            continue;\n          }\n          // Resolve value(s) to labels\n          const labels = sel.values.map((v) => {\n            const opt = step.options.find((o) => o.value === v);\n            return opt?.label || v;\n          });\n          lines.push(`${i + 1}. ${step.question} → ${labels.join(', ')}`);\n        }\n        return `User responses:\\n${lines.join('\\n')}`;\n      }\n\n      // Legacy: custom freeform input takes priority — user explicitly chose \"none of these\"\n      if (customInput) {\n        return `User provided custom response: \"${customInput}\"`;\n      }\n\n      if (selectedOption) {\n        const option = args.options?.find((o) => o.value === selectedOption);\n        return `User selected: \"${option?.label || selectedOption}\" (value: ${selectedOption})`;\n      }\n\n      // Fallback — should not happen in interactive mode since approval always fires first\n      return 'No user response received.';\n    },\n    {\n      name: AskUserToolName,\n      description: AskUserDescription,\n      schema: AskUserSchema,\n    }\n  );\n}\n"],"names":["Constants","z","tool"],"mappings":"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"}

package/dist/cjs/tools/BrowserTools.cjs

@@ -4,7 +4,7 @@ var zod = require('zod');
 var tools = require('@langchain/core/tools');
 
 /**
- * Browser tool names - keep in sync with ranger-browser extension
+ * Browser tool names - keep in sync with the browser extension
  * These tools execute locally in the browser extension, NOT on the server
  */
 const EBrowserTools = {