@illuma-ai/agents 1.0.96 → 1.1.0

package/dist/esm/utils/pruneCalibration.mjs

@@ -0,0 +1,74 @@
+import { PRUNING_EMA_ALPHA, PRUNING_INITIAL_CALIBRATION } from '../common/constants.mjs';
+
+/**
+ * Creates an initial pruning calibration state.
+ *
+ * @param initialRatio - Starting calibration ratio (default: 1.0)
+ * @returns Fresh calibration state
+ */
+function createPruneCalibration(initialRatio) {
+    return {
+        ratio: initialRatio ?? PRUNING_INITIAL_CALIBRATION,
+        iterations: 0,
+    };
+}
+/**
+ * Updates the pruning calibration using Exponential Moving Average (EMA).
+ *
+ * Problem: Without calibration, the pruner's token estimates can diverge from
+ * reality across iterations, causing either:
+ * - Over-pruning (context cliff): Too many messages removed at once, losing critical tool results
+ * - Under-pruning: Not enough messages removed, hitting hard token limits
+ *
+ * Solution: Track the ratio between actual token usage (from API response) and
+ * estimated token usage (from our token counter). Apply EMA smoothing so the
+ * calibration adjusts gradually, preventing oscillation.
+ *
+ * The calibration ratio is applied to maxTokens in the pruner:
+ *   effectiveMaxTokens = maxTokens * calibrationRatio
+ *
+ * If actual > estimated → ratio decreases → prune more aggressively
+ * If actual < estimated → ratio increases → prune less aggressively
+ *
+ * @param state - Current calibration state
+ * @param actualTokens - Actual token count from API response (UsageMetadata)
+ * @param estimatedTokens - Estimated token count from token counter
+ * @param alpha - EMA smoothing factor (default: PRUNING_EMA_ALPHA)
+ * @returns Updated calibration state (new object, does not mutate input)
+ */
+function updatePruneCalibration(state, actualTokens, estimatedTokens, alpha = PRUNING_EMA_ALPHA) {
+    // Guard against division by zero or invalid inputs
+    if (estimatedTokens <= 0 || actualTokens <= 0) {
+        return state;
+    }
+    // Raw ratio: how much our estimate differs from reality
+    const observedRatio = estimatedTokens / actualTokens;
+    // Clamp to prevent extreme adjustments from outlier readings
+    // Range [0.5, 2.0] means we never more than double or halve the budget
+    const clampedRatio = Math.max(0.5, Math.min(2.0, observedRatio));
+    // Apply EMA: new_ratio = α * observed + (1 - α) * previous
+    const newRatio = alpha * clampedRatio + (1 - alpha) * state.ratio;
+    return {
+        ratio: newRatio,
+        iterations: state.iterations + 1,
+    };
+}
+/**
+ * Applies the calibration ratio to a max token budget.
+ * The ratio adjusts the effective budget so pruning is more or less aggressive
+ * based on observed vs. estimated token divergence.
+ *
+ * @param maxTokens - Raw max token budget
+ * @param state - Current calibration state
+ * @returns Adjusted max token budget
+ */
+function applyCalibration(maxTokens, state) {
+    if (state.iterations === 0) {
+        // No calibration data yet — use raw budget
+        return maxTokens;
+    }
+    return Math.floor(maxTokens * state.ratio);
+}
+
+export { applyCalibration, createPruneCalibration, updatePruneCalibration };
+//# sourceMappingURL=pruneCalibration.mjs.map

package/dist/esm/utils/pruneCalibration.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pruneCalibration.mjs","sources":["../../../src/utils/pruneCalibration.ts"],"sourcesContent":["// src/utils/pruneCalibration.ts\nimport type { PruneCalibrationState } from '@/types/graph';\nimport {\n  PRUNING_EMA_ALPHA,\n  PRUNING_INITIAL_CALIBRATION,\n} from '@/common/constants';\n\n/**\n * Creates an initial pruning calibration state.\n *\n * @param initialRatio - Starting calibration ratio (default: 1.0)\n * @returns Fresh calibration state\n */\nexport function createPruneCalibration(\n  initialRatio?: number\n): PruneCalibrationState {\n  return {\n    ratio: initialRatio ?? PRUNING_INITIAL_CALIBRATION,\n    iterations: 0,\n  };\n}\n\n/**\n * Updates the pruning calibration using Exponential Moving Average (EMA).\n *\n * Problem: Without calibration, the pruner's token estimates can diverge from\n * reality across iterations, causing either:\n * - Over-pruning (context cliff): Too many messages removed at once, losing critical tool results\n * - Under-pruning: Not enough messages removed, hitting hard token limits\n *\n * Solution: Track the ratio between actual token usage (from API response) and\n * estimated token usage (from our token counter). Apply EMA smoothing so the\n * calibration adjusts gradually, preventing oscillation.\n *\n * The calibration ratio is applied to maxTokens in the pruner:\n *   effectiveMaxTokens = maxTokens * calibrationRatio\n *\n * If actual > estimated → ratio decreases → prune more aggressively\n * If actual < estimated → ratio increases → prune less aggressively\n *\n * @param state - Current calibration state\n * @param actualTokens - Actual token count from API response (UsageMetadata)\n * @param estimatedTokens - Estimated token count from token counter\n * @param alpha - EMA smoothing factor (default: PRUNING_EMA_ALPHA)\n * @returns Updated calibration state (new object, does not mutate input)\n */\nexport function updatePruneCalibration(\n  state: PruneCalibrationState,\n  actualTokens: number,\n  estimatedTokens: number,\n  alpha: number = PRUNING_EMA_ALPHA\n): PruneCalibrationState {\n  // Guard against division by zero or invalid inputs\n  if (estimatedTokens <= 0 || actualTokens <= 0) {\n    return state;\n  }\n\n  // Raw ratio: how much our estimate differs from reality\n  const observedRatio = estimatedTokens / actualTokens;\n\n  // Clamp to prevent extreme adjustments from outlier readings\n  // Range [0.5, 2.0] means we never more than double or halve the budget\n  const clampedRatio = Math.max(0.5, Math.min(2.0, observedRatio));\n\n  // Apply EMA: new_ratio = α * observed + (1 - α) * previous\n  const newRatio = alpha * clampedRatio + (1 - alpha) * state.ratio;\n\n  return {\n    ratio: newRatio,\n    iterations: state.iterations + 1,\n  };\n}\n\n/**\n * Applies the calibration ratio to a max token budget.\n * The ratio adjusts the effective budget so pruning is more or less aggressive\n * based on observed vs. estimated token divergence.\n *\n * @param maxTokens - Raw max token budget\n * @param state - Current calibration state\n * @returns Adjusted max token budget\n */\nexport function applyCalibration(\n  maxTokens: number,\n  state: PruneCalibrationState\n): number {\n  if (state.iterations === 0) {\n    // No calibration data yet — use raw budget\n    return maxTokens;\n  }\n  return Math.floor(maxTokens * state.ratio);\n}\n"],"names":[],"mappings":";;AAOA;;;;;AAKG;AACG,SAAU,sBAAsB,CACpC,YAAqB,EAAA;IAErB,OAAO;QACL,KAAK,EAAE,YAAY,IAAI,2BAA2B;AAClD,QAAA,UAAU,EAAE,CAAC;KACd;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACG,SAAU,sBAAsB,CACpC,KAA4B,EAC5B,YAAoB,EACpB,eAAuB,EACvB,KAAA,GAAgB,iBAAiB,EAAA;;IAGjC,IAAI,eAAe,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC,EAAE;AAC7C,QAAA,OAAO,KAAK;IACd;;AAGA,IAAA,MAAM,aAAa,GAAG,eAAe,GAAG,YAAY;;;AAIpD,IAAA,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;;AAGhE,IAAA,MAAM,QAAQ,GAAG,KAAK,GAAG,YAAY,GAAG,CAAC,CAAC,GAAG,KAAK,IAAI,KAAK,CAAC,KAAK;IAEjE,OAAO;AACL,QAAA,KAAK,EAAE,QAAQ;AACf,QAAA,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,CAAC;KACjC;AACH;AAEA;;;;;;;;AAQG;AACG,SAAU,gBAAgB,CAC9B,SAAiB,EACjB,KAA4B,EAAA;AAE5B,IAAA,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC,EAAE;;AAE1B,QAAA,OAAO,SAAS;IAClB;IACA,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;AAC5C;;;;"}

package/dist/esm/utils/run.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run.mjs","sources":["../../../src/utils/run.ts"],"sourcesContent":["import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';\r\nimport {\r\n  mergeConfigs,\r\n  patchConfig,\r\n  Runnable,\r\n  RunnableConfig,\r\n} from '@langchain/core/runnables';\r\nimport { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';\r\n\r\n/**\r\n * Delays the execution for a specified number of milliseconds.\r\n *\r\n * @param {number} ms - The number of milliseconds to delay.\r\n * @return {Promise<void>} A promise that resolves after the specified delay.\r\n */\r\nexport function sleep(ms: number): Promise<void> {\r\n  return new Promise((resolve) => setTimeout(resolve, ms));\r\n}\r\n\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nexport interface RunnableCallableArgs extends Partial<any> {\r\n  name?: string;\r\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n  func: (...args: any[]) => any;\r\n  tags?: string[];\r\n  trace?: boolean;\r\n  recurse?: boolean;\r\n}\r\n\r\nexport class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {\r\n  lc_namespace: string[] = ['langgraph'];\r\n\r\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n  func: (...args: any[]) => any;\r\n\r\n  tags?: string[];\r\n\r\n  config?: RunnableConfig;\r\n\r\n  trace: boolean = true;\r\n\r\n  recurse: boolean = true;\r\n\r\n  constructor(fields: RunnableCallableArgs) {\r\n    super();\r\n    this.name = fields.name ?? fields.func.name;\r\n    this.func = fields.func;\r\n    this.config = fields.tags ? { tags: fields.tags } : undefined;\r\n    this.trace = fields.trace ?? this.trace;\r\n    this.recurse = fields.recurse ?? this.recurse;\r\n  }\r\n\r\n  protected async _tracedInvoke(\r\n    input: I,\r\n    config?: Partial<RunnableConfig>,\r\n    runManager?: CallbackManagerForChainRun\r\n  ): Promise<O> {\r\n    return new Promise<O>((resolve, reject) => {\r\n      // Defensive check: ensure runManager has getChild method before calling\r\n      const childCallbacks =\r\n        typeof runManager?.getChild === 'function'\r\n          ? runManager.getChild()\r\n          : undefined;\r\n      let childConfig: Partial<RunnableConfig> | null = patchConfig(config, {\r\n        callbacks: childCallbacks,\r\n      });\r\n      void AsyncLocalStorageProviderSingleton.runWithConfig(\r\n        childConfig,\r\n        async () => {\r\n          try {\r\n            const output = await this.func(input, childConfig);\r\n            childConfig = null;\r\n            resolve(output);\r\n          } catch (e) {\r\n            childConfig = null;\r\n            reject(e);\r\n          }\r\n        }\r\n      );\r\n    });\r\n  }\r\n\r\n  async invoke(\r\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n    input: any,\r\n    options?: Partial<RunnableConfig> | undefined\r\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n  ): Promise<any> {\r\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n    let returnValue: any;\r\n\r\n    if (this.trace) {\r\n      returnValue = await this._callWithConfig(\r\n        this._tracedInvoke,\r\n        input,\r\n        mergeConfigs(this.config, options)\r\n      );\r\n    } else {\r\n      returnValue = await this.func(input, mergeConfigs(this.config, options));\r\n    }\r\n\r\n    if (Runnable.isRunnable(returnValue) && this.recurse) {\r\n      return await returnValue.invoke(input, options);\r\n    }\r\n\r\n    return returnValue;\r\n  }\r\n}\r\n"],"names":[],"mappings":";;;AASA;;;;;AAKG;AACG,SAAU,KAAK,CAAC,EAAU,EAAA;AAC9B,IAAA,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1D;AAYM,MAAO,gBAA2C,SAAQ,QAAc,CAAA;AAC5E,IAAA,YAAY,GAAa,CAAC,WAAW,CAAC;;AAGtC,IAAA,IAAI;AAEJ,IAAA,IAAI;AAEJ,IAAA,MAAM;IAEN,KAAK,GAAY,IAAI;IAErB,OAAO,GAAY,IAAI;AAEvB,IAAA,WAAA,CAAY,MAA4B,EAAA;AACtC,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;AAC3C,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS;QAC7D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;QACvC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;IAC/C;AAEU,IAAA,MAAM,aAAa,CAC3B,KAAQ,EACR,MAAgC,EAChC,UAAuC,EAAA;QAEvC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,KAAI;;AAExC,YAAA,MAAM,cAAc,GAClB,OAAO,UAAU,EAAE,QAAQ,KAAK;AAC9B,kBAAE,UAAU,CAAC,QAAQ;kBACnB,SAAS;AACf,YAAA,IAAI,WAAW,GAAmC,WAAW,CAAC,MAAM,EAAE;AACpE,gBAAA,SAAS,EAAE,cAAc;AAC1B,aAAA,CAAC;YACF,KAAK,kCAAkC,CAAC,aAAa,CACnD,WAAW,EACX,YAAW;AACT,gBAAA,IAAI;oBACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;oBAClD,WAAW,GAAG,IAAI;oBAClB,OAAO,CAAC,MAAM,CAAC;gBACjB;gBAAE,OAAO,CAAC,EAAE;oBACV,WAAW,GAAG,IAAI;oBAClB,MAAM,CAAC,CAAC,CAAC;gBACX;AACF,YAAA,CAAC,CACF;AACH,QAAA,CAAC,CAAC;IACJ;AAEA,IAAA,MAAM,MAAM;;AAEV,IAAA,KAAU,EACV;;;;AAIA,QAAA,IAAI,WAAgB;AAEpB,QAAA,IAAI,IAAI,CAAC,KAAK,EAAE;YACd,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,CACtC,IAAI,CAAC,aAAa,EAClB,KAAK,EACL,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CACnC;QACH;aAAO;AACL,YAAA,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1E;QAEA,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE;YACpD,OAAO,MAAM,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;QACjD;AAEA,QAAA,OAAO,WAAW;IACpB;AACD;;;;"}
+{"version":3,"file":"run.mjs","sources":["../../../src/utils/run.ts"],"sourcesContent":["import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';\nimport {\n  mergeConfigs,\n  patchConfig,\n  Runnable,\n  RunnableConfig,\n} from '@langchain/core/runnables';\nimport { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';\n\n/**\n * Delays the execution for a specified number of milliseconds.\n *\n * @param {number} ms - The number of milliseconds to delay.\n * @return {Promise<void>} A promise that resolves after the specified delay.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RunnableCallableArgs extends Partial<any> {\n  name?: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  func: (...args: any[]) => any;\n  tags?: string[];\n  trace?: boolean;\n  recurse?: boolean;\n}\n\nexport class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {\n  lc_namespace: string[] = ['langgraph'];\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  func: (...args: any[]) => any;\n\n  tags?: string[];\n\n  config?: RunnableConfig;\n\n  trace: boolean = true;\n\n  recurse: boolean = true;\n\n  constructor(fields: RunnableCallableArgs) {\n    super();\n    this.name = fields.name ?? fields.func.name;\n    this.func = fields.func;\n    this.config = fields.tags ? { tags: fields.tags } : undefined;\n    this.trace = fields.trace ?? this.trace;\n    this.recurse = fields.recurse ?? this.recurse;\n  }\n\n  protected async _tracedInvoke(\n    input: I,\n    config?: Partial<RunnableConfig>,\n    runManager?: CallbackManagerForChainRun\n  ): Promise<O> {\n    return new Promise<O>((resolve, reject) => {\n      // Defensive check: ensure runManager has getChild method before calling\n      const childCallbacks =\n        typeof runManager?.getChild === 'function'\n          ? runManager.getChild()\n          : undefined;\n      let childConfig: Partial<RunnableConfig> | null = patchConfig(config, {\n        callbacks: childCallbacks,\n      });\n      void AsyncLocalStorageProviderSingleton.runWithConfig(\n        childConfig,\n        async () => {\n          try {\n            const output = await this.func(input, childConfig);\n            childConfig = null;\n            resolve(output);\n          } catch (e) {\n            childConfig = null;\n            reject(e);\n          }\n        }\n      );\n    });\n  }\n\n  async invoke(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    input: any,\n    options?: Partial<RunnableConfig> | undefined\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let returnValue: any;\n\n    if (this.trace) {\n      returnValue = await this._callWithConfig(\n        this._tracedInvoke,\n        input,\n        mergeConfigs(this.config, options)\n      );\n    } else {\n      returnValue = await this.func(input, mergeConfigs(this.config, options));\n    }\n\n    if (Runnable.isRunnable(returnValue) && this.recurse) {\n      return await returnValue.invoke(input, options);\n    }\n\n    return returnValue;\n  }\n}\n"],"names":[],"mappings":";;;AASA;;;;;AAKG;AACG,SAAU,KAAK,CAAC,EAAU,EAAA;AAC9B,IAAA,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1D;AAYM,MAAO,gBAA2C,SAAQ,QAAc,CAAA;AAC5E,IAAA,YAAY,GAAa,CAAC,WAAW,CAAC;;AAGtC,IAAA,IAAI;AAEJ,IAAA,IAAI;AAEJ,IAAA,MAAM;IAEN,KAAK,GAAY,IAAI;IAErB,OAAO,GAAY,IAAI;AAEvB,IAAA,WAAA,CAAY,MAA4B,EAAA;AACtC,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;AAC3C,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS;QAC7D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;QACvC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;IAC/C;AAEU,IAAA,MAAM,aAAa,CAC3B,KAAQ,EACR,MAAgC,EAChC,UAAuC,EAAA;QAEvC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,KAAI;;AAExC,YAAA,MAAM,cAAc,GAClB,OAAO,UAAU,EAAE,QAAQ,KAAK;AAC9B,kBAAE,UAAU,CAAC,QAAQ;kBACnB,SAAS;AACf,YAAA,IAAI,WAAW,GAAmC,WAAW,CAAC,MAAM,EAAE;AACpE,gBAAA,SAAS,EAAE,cAAc;AAC1B,aAAA,CAAC;YACF,KAAK,kCAAkC,CAAC,aAAa,CACnD,WAAW,EACX,YAAW;AACT,gBAAA,IAAI;oBACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;oBAClD,WAAW,GAAG,IAAI;oBAClB,OAAO,CAAC,MAAM,CAAC;gBACjB;gBAAE,OAAO,CAAC,EAAE;oBACV,WAAW,GAAG,IAAI;oBAClB,MAAM,CAAC,CAAC,CAAC;gBACX;AACF,YAAA,CAAC,CACF;AACH,QAAA,CAAC,CAAC;IACJ;AAEA,IAAA,MAAM,MAAM;;AAEV,IAAA,KAAU,EACV;;;;AAIA,QAAA,IAAI,WAAgB;AAEpB,QAAA,IAAI,IAAI,CAAC,KAAK,EAAE;YACd,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,CACtC,IAAI,CAAC,aAAa,EAClB,KAAK,EACL,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CACnC;QACH;aAAO;AACL,YAAA,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1E;QAEA,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE;YACpD,OAAO,MAAM,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;QACjD;AAEA,QAAA,OAAO,WAAW;IACpB;AACD;;;;"}

package/dist/esm/utils/tokens.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.mjs","sources":["../../../src/utils/tokens.ts"],"sourcesContent":["import { Tokenizer } from 'ai-tokenizer';\r\nimport type { BaseMessage } from '@langchain/core/messages';\r\nimport { ContentTypes } from '@/common/enum';\r\n\r\nexport type EncodingName = 'o200k_base' | 'claude';\r\n\r\nconst tokenizers: Partial<Record<EncodingName, Tokenizer>> = {};\r\n\r\nasync function getTokenizer(\r\n  encoding: EncodingName = 'o200k_base'\r\n): Promise<Tokenizer> {\r\n  const cached = tokenizers[encoding];\r\n  if (cached) {\r\n    return cached;\r\n  }\r\n  const data =\r\n    encoding === 'claude'\r\n      ? await import('ai-tokenizer/encoding/claude')\r\n      : await import('ai-tokenizer/encoding/o200k_base');\r\n  const instance = new Tokenizer(data);\r\n  tokenizers[encoding] = instance;\r\n  return instance;\r\n}\r\n\r\nexport function encodingForModel(model: string): EncodingName {\r\n  if (model.toLowerCase().includes('claude')) {\r\n    return 'claude';\r\n  }\r\n  return 'o200k_base';\r\n}\r\n\r\nexport function getTokenCountForMessage(\r\n  message: BaseMessage,\r\n  getTokenCount: (text: string) => number\r\n): number {\r\n  const tokensPerMessage = 3;\r\n\r\n  const processValue = (value: unknown): void => {\r\n    if (Array.isArray(value)) {\r\n      for (const item of value) {\r\n        if (\r\n          !item ||\r\n          !item.type ||\r\n          item.type === ContentTypes.ERROR ||\r\n          item.type === ContentTypes.IMAGE_URL\r\n        ) {\r\n          continue;\r\n        }\r\n\r\n        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {\r\n          const toolName = item.tool_call?.name || '';\r\n          if (toolName != null && toolName && typeof toolName === 'string') {\r\n            numTokens += getTokenCount(toolName);\r\n          }\r\n\r\n          const args = item.tool_call?.args || '';\r\n          if (args != null && args && typeof args === 'string') {\r\n            numTokens += getTokenCount(args);\r\n          }\r\n\r\n          const output = item.tool_call?.output || '';\r\n          if (output != null && output && typeof output === 'string') {\r\n            numTokens += getTokenCount(output);\r\n          }\r\n          continue;\r\n        }\r\n\r\n        const nestedValue = item[item.type];\r\n\r\n        if (!nestedValue) {\r\n          continue;\r\n        }\r\n\r\n        processValue(nestedValue);\r\n      }\r\n    } else if (typeof value === 'string') {\r\n      numTokens += getTokenCount(value);\r\n    } else if (typeof value === 'number') {\r\n      numTokens += getTokenCount(value.toString());\r\n    } else if (typeof value === 'boolean') {\r\n      numTokens += getTokenCount(value.toString());\r\n    }\r\n  };\r\n\r\n  let numTokens = tokensPerMessage;\r\n  processValue(message.content);\r\n  return numTokens;\r\n}\r\n\r\n/**\r\n * Creates a token counter function using the specified encoding.\r\n * Lazily loads the encoding data on first use via dynamic import.\r\n */\r\nexport const createTokenCounter = async (\r\n  encoding: EncodingName = 'o200k_base'\r\n): Promise<(message: BaseMessage) => number> => {\r\n  const tok = await getTokenizer(encoding);\r\n  const countTokens = (text: string): number => tok.count(text);\r\n  return (message: BaseMessage): number =>\r\n    getTokenCountForMessage(message, countTokens);\r\n};\r\n\r\n/** Utility to manage the token encoder lifecycle explicitly. */\r\nexport const TokenEncoderManager = {\r\n  async initialize(): Promise<void> {\r\n    // No-op: ai-tokenizer is synchronously initialized from bundled data.\r\n  },\r\n\r\n  reset(): void {\r\n    for (const key of Object.keys(tokenizers)) {\r\n      delete tokenizers[key as EncodingName];\r\n    }\r\n  },\r\n\r\n  isInitialized(): boolean {\r\n    return Object.keys(tokenizers).length > 0;\r\n  },\r\n};\r\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"tokens.mjs","sources":["../../../src/utils/tokens.ts"],"sourcesContent":["import { Tokenizer } from 'ai-tokenizer';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { ContentTypes } from '@/common/enum';\n\nexport type EncodingName = 'o200k_base' | 'claude';\n\nconst tokenizers: Partial<Record<EncodingName, Tokenizer>> = {};\n\nasync function getTokenizer(\n  encoding: EncodingName = 'o200k_base'\n): Promise<Tokenizer> {\n  const cached = tokenizers[encoding];\n  if (cached) {\n    return cached;\n  }\n  const data =\n    encoding === 'claude'\n      ? await import('ai-tokenizer/encoding/claude')\n      : await import('ai-tokenizer/encoding/o200k_base');\n  const instance = new Tokenizer(data);\n  tokenizers[encoding] = instance;\n  return instance;\n}\n\nexport function encodingForModel(model: string): EncodingName {\n  if (model.toLowerCase().includes('claude')) {\n    return 'claude';\n  }\n  return 'o200k_base';\n}\n\nexport function getTokenCountForMessage(\n  message: BaseMessage,\n  getTokenCount: (text: string) => number\n): number {\n  const tokensPerMessage = 3;\n\n  const processValue = (value: unknown): void => {\n    if (Array.isArray(value)) {\n      for (const item of value) {\n        if (\n          !item ||\n          !item.type ||\n          item.type === ContentTypes.ERROR ||\n          item.type === ContentTypes.IMAGE_URL\n        ) {\n          continue;\n        }\n\n        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {\n          const toolName = item.tool_call?.name || '';\n          if (toolName != null && toolName && typeof toolName === 'string') {\n            numTokens += getTokenCount(toolName);\n          }\n\n          const args = item.tool_call?.args || '';\n          if (args != null && args && typeof args === 'string') {\n            numTokens += getTokenCount(args);\n          }\n\n          const output = item.tool_call?.output || '';\n          if (output != null && output && typeof output === 'string') {\n            numTokens += getTokenCount(output);\n          }\n          continue;\n        }\n\n        const nestedValue = item[item.type];\n\n        if (!nestedValue) {\n          continue;\n        }\n\n        processValue(nestedValue);\n      }\n    } else if (typeof value === 'string') {\n      numTokens += getTokenCount(value);\n    } else if (typeof value === 'number') {\n      numTokens += getTokenCount(value.toString());\n    } else if (typeof value === 'boolean') {\n      numTokens += getTokenCount(value.toString());\n    }\n  };\n\n  let numTokens = tokensPerMessage;\n  processValue(message.content);\n  return numTokens;\n}\n\n/**\n * Creates a token counter function using the specified encoding.\n * Lazily loads the encoding data on first use via dynamic import.\n */\nexport const createTokenCounter = async (\n  encoding: EncodingName = 'o200k_base'\n): Promise<(message: BaseMessage) => number> => {\n  const tok = await getTokenizer(encoding);\n  const countTokens = (text: string): number => tok.count(text);\n  return (message: BaseMessage): number =>\n    getTokenCountForMessage(message, countTokens);\n};\n\n/** Utility to manage the token encoder lifecycle explicitly. */\nexport const TokenEncoderManager = {\n  async initialize(): Promise<void> {\n    // No-op: ai-tokenizer is synchronously initialized from bundled data.\n  },\n\n  reset(): void {\n    for (const key of Object.keys(tokenizers)) {\n      delete tokenizers[key as EncodingName];\n    }\n  },\n\n  isInitialized(): boolean {\n    return Object.keys(tokenizers).length > 0;\n  },\n};\n"],"names":[],"mappings":"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"}

package/dist/esm/utils/toolDiscoveryCache.mjs

@@ -0,0 +1,125 @@
+import { MessageTypes, Constants } from '../common/enum.mjs';
+import { TOOL_DISCOVERY_CACHE_MAX_SIZE } from '../common/constants.mjs';
+
+/**
+ * ToolDiscoveryCache provides a run-scoped cache of tool search results.
+ *
+ * Problem: Without caching, every LLM iteration re-parses the full message
+ * history via extractToolDiscoveries() to find tool_search results. In long
+ * conversations with many tool iterations, this is redundant work.
+ *
+ * Solution: Cache discovered tool names by message index. On each iteration,
+ * only scan messages AFTER the last scanned index. Already-seen discoveries
+ * are returned from cache instantly.
+ *
+ * This mirrors the pattern used by VS Code Copilot Chat where tool search
+ * results from prior turns are cached to avoid re-discovery.
+ *
+ * @example
+ * ```ts
+ * const cache = new ToolDiscoveryCache();
+ *
+ * // First call: scans all messages
+ * const newTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['web_search', 'file_read']
+ *
+ * // Second call (3 new messages added): only scans new messages
+ * const moreTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['code_exec'] (only newly discovered)
+ * ```
+ */
+class ToolDiscoveryCache {
+    /** Set of all discovered tool names (deduped) */
+    _discoveredTools = new Set();
+    /** Last message index that was scanned */
+    _lastScannedIndex = -1;
+    /**
+     * Scan messages for new tool_search results since the last scan.
+     * Only processes messages after `_lastScannedIndex` to avoid redundant work.
+     *
+     * @param messages - Full conversation message array
+     * @returns Array of newly discovered tool names (not previously cached)
+     */
+    getNewDiscoveries(messages) {
+        if (messages.length === 0) {
+            return [];
+        }
+        const startIndex = this._lastScannedIndex + 1;
+        if (startIndex >= messages.length) {
+            return [];
+        }
+        const newDiscoveries = [];
+        for (let i = startIndex; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg.getType() !== MessageTypes.TOOL) {
+                continue;
+            }
+            // Check if this is a tool_search result
+            if (msg.name !== Constants.TOOL_SEARCH) {
+                continue;
+            }
+            // Extract tool references from artifact
+            const artifact = msg.artifact;
+            if (typeof artifact === 'object' && artifact != null) {
+                const refs = artifact.tool_references;
+                if (refs && refs.length > 0) {
+                    for (const ref of refs) {
+                        if (!this._discoveredTools.has(ref.tool_name)) {
+                            // Enforce cache size limit
+                            if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {
+                                break;
+                            }
+                            this._discoveredTools.add(ref.tool_name);
+                            newDiscoveries.push(ref.tool_name);
+                        }
+                    }
+                }
+            }
+        }
+        this._lastScannedIndex = messages.length - 1;
+        return newDiscoveries;
+    }
+    /**
+     * Returns all tool names discovered so far (across all scans).
+     */
+    getAllDiscoveredTools() {
+        return [...this._discoveredTools];
+    }
+    /**
+     * Check if a specific tool has been discovered.
+     */
+    has(toolName) {
+        return this._discoveredTools.has(toolName);
+    }
+    /**
+     * Number of unique tools discovered.
+     */
+    get size() {
+        return this._discoveredTools.size;
+    }
+    /**
+     * Reset the cache (e.g., on graph reset).
+     */
+    reset() {
+        this._discoveredTools.clear();
+        this._lastScannedIndex = -1;
+    }
+    /**
+     * Seed the cache with previously known tool names (e.g., from prior conversation turns).
+     * Does not affect _lastScannedIndex — the next getNewDiscoveries call will still
+     * scan all messages from the beginning.
+     *
+     * @param toolNames - Tool names to pre-seed into the cache
+     */
+    seed(toolNames) {
+        for (const name of toolNames) {
+            if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {
+                break;
+            }
+            this._discoveredTools.add(name);
+        }
+    }
+}
+
+export { ToolDiscoveryCache };
+//# sourceMappingURL=toolDiscoveryCache.mjs.map

package/dist/esm/utils/toolDiscoveryCache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolDiscoveryCache.mjs","sources":["../../../src/utils/toolDiscoveryCache.ts"],"sourcesContent":["// src/utils/toolDiscoveryCache.ts\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { Constants, MessageTypes } from '@/common';\nimport { TOOL_DISCOVERY_CACHE_MAX_SIZE } from '@/common/constants';\n\n/**\n * Cached tool discovery entry.\n * Stores the tool name and the message index where it was discovered,\n * enabling efficient lookups without re-parsing conversation history.\n */\nexport interface ToolDiscoveryEntry {\n  /** The tool name that was discovered */\n  toolName: string;\n  /** Message index in conversation history where discovery occurred */\n  discoveredAtIndex: number;\n}\n\n/**\n * ToolDiscoveryCache provides a run-scoped cache of tool search results.\n *\n * Problem: Without caching, every LLM iteration re-parses the full message\n * history via extractToolDiscoveries() to find tool_search results. In long\n * conversations with many tool iterations, this is redundant work.\n *\n * Solution: Cache discovered tool names by message index. On each iteration,\n * only scan messages AFTER the last scanned index. Already-seen discoveries\n * are returned from cache instantly.\n *\n * This mirrors the pattern used by VS Code Copilot Chat where tool search\n * results from prior turns are cached to avoid re-discovery.\n *\n * @example\n * ```ts\n * const cache = new ToolDiscoveryCache();\n *\n * // First call: scans all messages\n * const newTools = cache.getNewDiscoveries(messages);\n * // Returns: ['web_search', 'file_read']\n *\n * // Second call (3 new messages added): only scans new messages\n * const moreTools = cache.getNewDiscoveries(messages);\n * // Returns: ['code_exec'] (only newly discovered)\n * ```\n */\nexport class ToolDiscoveryCache {\n  /** Set of all discovered tool names (deduped) */\n  private _discoveredTools: Set<string> = new Set();\n  /** Last message index that was scanned */\n  private _lastScannedIndex: number = -1;\n\n  /**\n   * Scan messages for new tool_search results since the last scan.\n   * Only processes messages after `_lastScannedIndex` to avoid redundant work.\n   *\n   * @param messages - Full conversation message array\n   * @returns Array of newly discovered tool names (not previously cached)\n   */\n  getNewDiscoveries(messages: BaseMessage[]): string[] {\n    if (messages.length === 0) {\n      return [];\n    }\n\n    const startIndex = this._lastScannedIndex + 1;\n    if (startIndex >= messages.length) {\n      return [];\n    }\n\n    const newDiscoveries: string[] = [];\n\n    for (let i = startIndex; i < messages.length; i++) {\n      const msg = messages[i];\n      if (msg.getType() !== MessageTypes.TOOL) {\n        continue;\n      }\n\n      // Check if this is a tool_search result\n      if ((msg as { name?: string }).name !== Constants.TOOL_SEARCH) {\n        continue;\n      }\n\n      // Extract tool references from artifact\n      const artifact = (msg as { artifact?: unknown }).artifact;\n      if (typeof artifact === 'object' && artifact != null) {\n        const refs = (\n          artifact as { tool_references?: Array<{ tool_name: string }> }\n        ).tool_references;\n        if (refs && refs.length > 0) {\n          for (const ref of refs) {\n            if (!this._discoveredTools.has(ref.tool_name)) {\n              // Enforce cache size limit\n              if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {\n                break;\n              }\n              this._discoveredTools.add(ref.tool_name);\n              newDiscoveries.push(ref.tool_name);\n            }\n          }\n        }\n      }\n    }\n\n    this._lastScannedIndex = messages.length - 1;\n    return newDiscoveries;\n  }\n\n  /**\n   * Returns all tool names discovered so far (across all scans).\n   */\n  getAllDiscoveredTools(): string[] {\n    return [...this._discoveredTools];\n  }\n\n  /**\n   * Check if a specific tool has been discovered.\n   */\n  has(toolName: string): boolean {\n    return this._discoveredTools.has(toolName);\n  }\n\n  /**\n   * Number of unique tools discovered.\n   */\n  get size(): number {\n    return this._discoveredTools.size;\n  }\n\n  /**\n   * Reset the cache (e.g., on graph reset).\n   */\n  reset(): void {\n    this._discoveredTools.clear();\n    this._lastScannedIndex = -1;\n  }\n\n  /**\n   * Seed the cache with previously known tool names (e.g., from prior conversation turns).\n   * Does not affect _lastScannedIndex — the next getNewDiscoveries call will still\n   * scan all messages from the beginning.\n   *\n   * @param toolNames - Tool names to pre-seed into the cache\n   */\n  seed(toolNames: string[]): void {\n    for (const name of toolNames) {\n      if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {\n        break;\n      }\n      this._discoveredTools.add(name);\n    }\n  }\n}\n"],"names":[],"mappings":";;;AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;MACU,kBAAkB,CAAA;;AAErB,IAAA,gBAAgB,GAAgB,IAAI,GAAG,EAAE;;IAEzC,iBAAiB,GAAW,EAAE;AAEtC;;;;;;AAMG;AACH,IAAA,iBAAiB,CAAC,QAAuB,EAAA;AACvC,QAAA,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE;AACzB,YAAA,OAAO,EAAE;QACX;AAEA,QAAA,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,GAAG,CAAC;AAC7C,QAAA,IAAI,UAAU,IAAI,QAAQ,CAAC,MAAM,EAAE;AACjC,YAAA,OAAO,EAAE;QACX;QAEA,MAAM,cAAc,GAAa,EAAE;AAEnC,QAAA,KAAK,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;AACjD,YAAA,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC;YACvB,IAAI,GAAG,CAAC,OAAO,EAAE,KAAK,YAAY,CAAC,IAAI,EAAE;gBACvC;YACF;;YAGA,IAAK,GAAyB,CAAC,IAAI,KAAK,SAAS,CAAC,WAAW,EAAE;gBAC7D;YACF;;AAGA,YAAA,MAAM,QAAQ,GAAI,GAA8B,CAAC,QAAQ;YACzD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpD,gBAAA,MAAM,IAAI,GACR,QACD,CAAC,eAAe;gBACjB,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE;AAC3B,oBAAA,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE;AACtB,wBAAA,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;;4BAE7C,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,6BAA6B,EAAE;gCAC/D;4BACF;4BACA,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;AACxC,4BAAA,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;wBACpC;oBACF;gBACF;YACF;QACF;QAEA,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC;AAC5C,QAAA,OAAO,cAAc;IACvB;AAEA;;AAEG;IACH,qBAAqB,GAAA;AACnB,QAAA,OAAO,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC;IACnC;AAEA;;AAEG;AACH,IAAA,GAAG,CAAC,QAAgB,EAAA;QAClB,OAAO,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC5C;AAEA;;AAEG;AACH,IAAA,IAAI,IAAI,GAAA;AACN,QAAA,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI;IACnC;AAEA;;AAEG;IACH,KAAK,GAAA;AACH,QAAA,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE;AAC7B,QAAA,IAAI,CAAC,iBAAiB,GAAG,EAAE;IAC7B;AAEA;;;;;;AAMG;AACH,IAAA,IAAI,CAAC,SAAmB,EAAA;AACtB,QAAA,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE;YAC5B,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,6BAA6B,EAAE;gBAC/D;YACF;AACA,YAAA,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QACjC;IACF;AACD;;;;"}

package/dist/types/agents/AgentContext.d.ts

@@ -116,7 +116,9 @@ export declare class AgentContext {
     summarizeCallback?: (messages: BaseMessage[]) => Promise<string | undefined>;
     /** Pre-existing summary loaded from persistent storage, injected into context on new turns */
     persistedSummary?: string;
-    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, }: {
+    /** Summarization configuration controlling trigger strategy, reserve ratio, and EMA calibration */
+    summarizationConfig?: t.SummarizationConfig;
+    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, }: {
         agentId: string;
         name?: string;
         description?: string;
@@ -140,6 +142,7 @@ export declare class AgentContext {
         discoveredTools?: string[];
         summarizeCallback?: (messages: BaseMessage[]) => Promise<string | undefined>;
         persistedSummary?: string;
+        summarizationConfig?: t.SummarizationConfig;
     });
     /**
      * Checks if structured output mode is enabled for this agent.

package/dist/types/common/constants.d.ts

@@ -16,3 +16,52 @@ export declare const MIN_THINKING_BUDGET = 1024;
  * compounding across multi-tool conversations (e.g., 10 tool calls).
  */
 export declare const TOOL_TURN_THINKING_BUDGET = 1024;
+/**
+ * Minimum number of attached documents before the multi-document delegation
+ * hint is injected. Below this threshold, the agent processes documents
+ * directly within its own context.
+ */
+export declare const MULTI_DOCUMENT_THRESHOLD = 3;
+/**
+ * Context utilization safety buffer multiplier (0-1).
+ * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER
+ *
+ * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.
+ * 0.9 = 10% reserved for safety.
+ */
+export declare const CONTEXT_SAFETY_BUFFER = 0.9;
+/**
+ * Default context utilization percentage (0-100) at which summarization triggers.
+ * When the context window is ≥80% full, pruning + summarization activates.
+ */
+export declare const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
+/**
+ * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.
+ * 0.3 means 30% of the context budget is reserved for the most recent messages,
+ * ensuring the model always has immediate conversation history even after aggressive pruning.
+ */
+export declare const SUMMARIZATION_RESERVE_RATIO = 0.3;
+/**
+ * Default EMA (Exponential Moving Average) alpha for pruning calibration.
+ * Controls how quickly the calibration adapts to new token counts.
+ * Higher α = faster adaptation (more responsive to recent changes).
+ * Lower α = smoother adaptation (more stable across iterations).
+ * 0.3 provides a balance between responsiveness and stability.
+ */
+export declare const PRUNING_EMA_ALPHA = 0.3;
+/**
+ * Default initial calibration ratio for EMA pruning.
+ * 1.0 means no adjustment on the first iteration (trust the raw token counts).
+ * Subsequent iterations will adjust based on actual vs. estimated token usage.
+ */
+export declare const PRUNING_INITIAL_CALIBRATION = 1;
+/**
+ * Maximum number of tool discovery entries to cache per conversation.
+ * Prevents unbounded memory growth in very long conversations.
+ */
+export declare const TOOL_DISCOVERY_CACHE_MAX_SIZE = 200;
+/**
+ * Maximum length of system message content to hash for deduplication.
+ * Messages longer than this are always considered unique (hashing would be expensive).
+ */
+export declare const DEDUP_MAX_CONTENT_LENGTH = 10000;

package/dist/types/graphs/Graph.d.ts

@@ -73,6 +73,13 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     runId: string | undefined;
     startIndex: number;
     signal?: AbortSignal;
+    /** Cached summary from the first prune in this run.
+     * Reused for subsequent prunes to avoid blocking LLM calls on every tool iteration. */
+    private _cachedRunSummary;
+    /** EMA-based pruning calibration state — smooths token budget adjustments across iterations */
+    private _pruneCalibration;
+    /** Run-scoped tool discovery cache — avoids re-parsing conversation history on every iteration */
+    private _toolDiscoveryCache;
     /** Map of agent contexts by agent ID */
     agentContexts: Map<string, AgentContext>;
     /** Default agent ID to use */
@@ -105,6 +112,24 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * @returns Shallow-cloned clientOptions with reduced thinking budget, or the original if no reduction needed
      */
     getAdaptiveClientOptions(clientOptions: t.ClientOptions, provider: Providers): t.ClientOptions;
+    /**
+     * Determines whether summarization should trigger based on SummarizationConfig.
+     *
+     * Supports three trigger strategies:
+     * - contextPercentage (default): Trigger when context utilization >= threshold%
+     * - messageCount: Trigger when pruned message count >= threshold
+     * - tokenThreshold: Trigger when total estimated tokens >= threshold
+     *
+     * When no config is provided, always triggers (preserves backward compatibility).
+     *
+     * @param prunedMessageCount - Number of messages that were pruned
+     * @param maxContextTokens - Maximum context token budget
+     * @param indexTokenCountMap - Token count map by message index
+     * @param instructionTokens - Token count for instructions/system message
+     * @param config - Optional SummarizationConfig
+     * @returns Whether summarization should be triggered
+     */
+    private shouldTriggerSummarization;
     /**
      * Returns the normalized finish/stop reason from the last LLM invocation.
      * Used by callers to detect when the response was truncated due to max_tokens.

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

@@ -0,0 +1,25 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Deduplicates consecutive identical system messages in the context window.
+ *
+ * Problem: In long tool-use chains, the same system messages (e.g., post-prune notes,
+ * conversation summaries) can accumulate when the context is rebuilt on each iteration.
+ * These duplicates waste tokens without adding information.
+ *
+ * Strategy: Only deduplicate system messages that appear consecutively or are exact
+ * duplicates of an earlier system message. The FIRST occurrence is always kept.
+ * Non-system messages (human, ai, tool) are never touched.
+ *
+ * Important constraints:
+ * - The first system message (index 0) is ALWAYS preserved (it's the main system prompt)
+ * - Only system messages are candidates for deduplication
+ * - Messages with content longer than DEDUP_MAX_CONTENT_LENGTH are skipped (too expensive to compare)
+ * - Content comparison is by string equality (fast and deterministic)
+ *
+ * @param messages - The message array to deduplicate (not mutated)
+ * @returns A new array with duplicate system messages removed, and the count of removed messages
+ */
+export declare function deduplicateSystemMessages(messages: BaseMessage[]): {
+    messages: BaseMessage[];
+    removedCount: number;
+};

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

@@ -6,3 +6,4 @@ export * from './cache';
 export * from './content';
 export * from './tools';
 export * from './summarize';
+export * from './dedup';

package/dist/types/types/graph.d.ts

@@ -343,6 +343,63 @@ export interface StructuredOutputInput {
     /** Whether to enforce strict schema validation */
     strict?: boolean;
 }
+/**
+ * Trigger strategy for when summarization should activate.
+ * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage
+ * - 'messageCount': Trigger when pruned message count exceeds a threshold
+ * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold
+ */
+export type SummarizationTriggerType = 'contextPercentage' | 'messageCount' | 'tokenThreshold';
+/**
+ * Configuration for summarization behavior within the agent pipeline.
+ * All fields are optional — sensible defaults are provided via constants.
+ *
+ * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA
+ */
+export interface SummarizationConfig {
+    /**
+     * Strategy for when summarization triggers.
+     * @default 'contextPercentage'
+     */
+    triggerType?: SummarizationTriggerType;
+    /**
+     * Threshold value interpreted based on triggerType:
+     * - contextPercentage: 0-100 (percentage of context window)
+     * - messageCount: absolute count of messages pruned
+     * - tokenThreshold: absolute token count
+     * @default 80 (for contextPercentage)
+     */
+    triggerThreshold?: number;
+    /**
+     * Fraction of context window (0-1) reserved for recent messages.
+     * Prevents over-pruning by ensuring at least this fraction of the
+     * context budget is preserved as recent conversation history.
+     * @default 0.3
+     */
+    reserveRatio?: number;
+    /**
+     * Whether context pruning is enabled (can be disabled for debugging).
+     * @default true
+     */
+    contextPruning?: boolean;
+    /**
+     * Initial summary text to seed across runs.
+     * Different from persistedSummary: this is provided by the caller as a
+     * cross-conversation seed (e.g., agent personality or recurring context),
+     * while persistedSummary is loaded from the conversation's own history.
+     */
+    initialSummary?: string;
+}
+/**
+ * Runtime state for EMA-based pruning calibration.
+ * Maintained across iterations within a single run to smooth pruning decisions.
+ */
+export interface PruneCalibrationState {
+    /** Current EMA calibration ratio */
+    ratio: number;
+    /** Number of calibration updates applied */
+    iterations: number;
+}
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -412,4 +469,10 @@ export interface AgentInputs {
      * Set by Ranger's SummaryStore when resuming a conversation.
      */
     persistedSummary?: string;
+    /**
+     * Summarization configuration controlling trigger strategy, reserve ratio,
+     * and EMA calibration for pruning. When omitted, sensible defaults apply.
+     * @see SummarizationConfig
+     */
+    summarizationConfig?: SummarizationConfig;
 }

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

@@ -0,0 +1,72 @@
+/**
+ * Context Pressure Utilities
+ *
+ * Pure functions for context overflow management. These handle:
+ * 1. Multi-document detection — counting attached documents in messages
+ * 2. Multi-document delegation hint — injected when 3+ documents detected
+ * 3. Post-prune context note — injected after pruning/summarization
+ *
+ * DESIGN PRINCIPLE: The LLM never sees raw token numbers. Context overflow
+ * is handled mechanically by pruning (Graph) + auto-continuation (client.js).
+ * Only task-driven hints (multi-document) are injected — never budget-based.
+ *
+ * @see docs/context-overflow-architecture.md
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+/** Result of scanning messages for attached documents */
+export interface DocumentDetectionResult {
+    /** Total unique documents detected */
+    count: number;
+    /** Names of detected documents */
+    names: string[];
+}
+/**
+ * Scan messages for attached documents using known content patterns.
+ *
+ * Detects documents from:
+ * 1. `# "filename"` headers in "Attached document(s):" blocks (text content)
+ * 2. `**filename1, filename2**` in "The user has attached:" blocks (embedded files)
+ *
+ * @param messages - Conversation messages to scan
+ * @returns Document count and names (deduplicated)
+ */
+export declare function detectDocuments(messages: BaseMessage[]): DocumentDetectionResult;
+/**
+ * Determine whether the multi-document delegation hint should be injected.
+ *
+ * Only fires on the first iteration (before any AI response) when the
+ * document count meets the threshold. This ensures the agent delegates
+ * upfront rather than trying to process all documents itself.
+ *
+ * @param documentCount - Number of detected documents
+ * @param hasAiResponse - Whether the agent has already responded in this chain
+ * @returns Whether to inject the delegation hint
+ */
+export declare function shouldInjectMultiDocHint(documentCount: number, hasAiResponse: boolean): boolean;
+/**
+ * Build the multi-document delegation hint message content.
+ *
+ * @param documentCount - Number of detected documents
+ * @param documentNames - Names of detected documents
+ * @returns Message content string for injection as HumanMessage
+ */
+export declare function buildMultiDocHintContent(documentCount: number, documentNames: string[]): string;
+/**
+ * Build the post-prune context note injected after messages are pruned
+ * and summarized. No token numbers — just a contextual signal that
+ * earlier conversation was compressed.
+ *
+ * @param discardedCount - Number of messages that were pruned
+ * @param hasSummary - Whether a summary was successfully generated
+ * @returns Message content string for injection as SystemMessage, or null if no note needed
+ */
+export declare function buildPostPruneNote(discardedCount: number, hasSummary: boolean): string | null;
+/**
+ * Check whether a tool named "task" exists in the agent's tool set.
+ *
+ * @param tools - Array of tool objects or structured tools
+ * @returns Whether the task tool is available
+ */
+export declare function hasTaskTool(tools: Array<{
+    name?: string;
+} | unknown> | undefined): boolean;

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

@@ -8,3 +8,6 @@ export * from './toonFormat';
 export * from './contextAnalytics';
 export * from './schema';
 export * from './toolCallContinuation';
+export * from './contextPressure';
+export * from './toolDiscoveryCache';
+export * from './pruneCalibration';

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

@@ -0,0 +1,43 @@
+import type { PruneCalibrationState } from '@/types/graph';
+/**
+ * Creates an initial pruning calibration state.
+ *
+ * @param initialRatio - Starting calibration ratio (default: 1.0)
+ * @returns Fresh calibration state
+ */
+export declare function createPruneCalibration(initialRatio?: number): PruneCalibrationState;
+/**
+ * Updates the pruning calibration using Exponential Moving Average (EMA).
+ *
+ * Problem: Without calibration, the pruner's token estimates can diverge from
+ * reality across iterations, causing either:
+ * - Over-pruning (context cliff): Too many messages removed at once, losing critical tool results
+ * - Under-pruning: Not enough messages removed, hitting hard token limits
+ *
+ * Solution: Track the ratio between actual token usage (from API response) and
+ * estimated token usage (from our token counter). Apply EMA smoothing so the
+ * calibration adjusts gradually, preventing oscillation.
+ *
+ * The calibration ratio is applied to maxTokens in the pruner:
+ *   effectiveMaxTokens = maxTokens * calibrationRatio
+ *
+ * If actual > estimated → ratio decreases → prune more aggressively
+ * If actual < estimated → ratio increases → prune less aggressively
+ *
+ * @param state - Current calibration state
+ * @param actualTokens - Actual token count from API response (UsageMetadata)
+ * @param estimatedTokens - Estimated token count from token counter
+ * @param alpha - EMA smoothing factor (default: PRUNING_EMA_ALPHA)
+ * @returns Updated calibration state (new object, does not mutate input)
+ */
+export declare function updatePruneCalibration(state: PruneCalibrationState, actualTokens: number, estimatedTokens: number, alpha?: number): PruneCalibrationState;
+/**
+ * Applies the calibration ratio to a max token budget.
+ * The ratio adjusts the effective budget so pruning is more or less aggressive
+ * based on observed vs. estimated token divergence.
+ *
+ * @param maxTokens - Raw max token budget
+ * @param state - Current calibration state
+ * @returns Adjusted max token budget
+ */
+export declare function applyCalibration(maxTokens: number, state: PruneCalibrationState): number;