{"version":3,"file":"memoryAppendTool.mjs","sources":["../../../../src/tools/memory/memoryAppendTool.ts"],"sourcesContent":["/**\n * `memory_append` — the reflection-phase-only write tool.\n *\n * New (not present in upstream verbatim). Upstream enforces append-only via\n * `wrapToolMemoryFlushAppendOnlyWrite`; we combine the tool and the phase\n * gate in one place because the agents library has a simpler graph state.\n *\n * Behaviour:\n * - Outside `memory_flushing` phase: returns an error object instead of\n *   calling the backend. The LLM sees this and stops trying.\n * - Inside `memory_flushing`: persists the note via {@link MemoryBackend.append}.\n * - Hard-caps total appends per flush (protects against runaway writes).\n */\nimport { tool } from '@langchain/core/tools';\nimport {\n  DEFAULT_MAX_APPENDS_PER_FLUSH,\n  MEMORY_APPEND_DESCRIPTION,\n  MEMORY_APPEND_TOOL_NAME,\n  MEMORY_PHASE_FLUSHING,\n} from '@/memory/constants';\nimport type { MemoryPhase } from '@/memory/types';\nimport {\n  MemoryAppendSchema,\n  toAppendInput,\n  type MemoryToolBinding,\n} from './shared';\n\nexport interface MemoryAppendBinding extends MemoryToolBinding {\n  /**\n   * Reads the current phase at call-time. Required — without it the append\n   * tool rejects every call. Supplied by the graph runtime.\n   */\n  getPhase: () => MemoryPhase;\n  /** Hard cap on appends per flush phase. Default 20. */\n  maxAppendsPerFlush?: number;\n}\n\ninterface AppendResult {\n  ok: boolean;\n  error?: string;\n  path?: string;\n}\n\n// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\nexport function createMemoryAppendTool(binding: MemoryAppendBinding) {\n  const maxAppends =\n    binding.maxAppendsPerFlush ?? DEFAULT_MAX_APPENDS_PER_FLUSH;\n  let appendsInCurrentFlush = 0;\n  let lastSeenPhase: MemoryPhase = 'normal';\n\n  return tool(\n    async (args): Promise<string> => {\n      const phase = binding.getPhase();\n\n      // Reset counter on entry to a new flush.\n      if (\n        phase === MEMORY_PHASE_FLUSHING &&\n        lastSeenPhase !== MEMORY_PHASE_FLUSHING\n      ) {\n        appendsInCurrentFlush = 0;\n      }\n      lastSeenPhase = phase;\n\n      if (phase !== MEMORY_PHASE_FLUSHING) {\n        const result: AppendResult = {\n          ok: false,\n          error:\n            'memory_append can only be called during the reflection (memory_flushing) phase',\n        };\n        return JSON.stringify(result);\n      }\n\n      if (appendsInCurrentFlush >= maxAppends) {\n        const result: AppendResult = {\n          ok: false,\n          error: `memory_append hit the per-flush cap of ${maxAppends} notes`,\n        };\n        return JSON.stringify(result);\n      }\n\n      try {\n        const input = toAppendInput(args);\n        await binding.backend.append(binding.scope, input);\n        appendsInCurrentFlush += 1;\n        const result: AppendResult = { ok: true, path: input.path };\n        return JSON.stringify(result);\n      } catch (err) {\n        const result: AppendResult = {\n          ok: false,\n          error: err instanceof Error ? err.message : String(err),\n        };\n        return JSON.stringify(result);\n      }\n    },\n    {\n      name: MEMORY_APPEND_TOOL_NAME,\n      description: MEMORY_APPEND_DESCRIPTION,\n      schema: MemoryAppendSchema,\n    }\n  );\n}\n"],"names":[],"mappings":";;;;AAAA;;;;;;;;;;;;AAYG;AA+BH;AACM,SAAU,sBAAsB,CAAC,OAA4B,EAAA;AACjE,IAAA,MAAM,UAAU,GACd,OAAO,CAAC,kBAAkB,IAAI,6BAA6B;IAC7D,IAAI,qBAAqB,GAAG,CAAC;IAC7B,IAAI,aAAa,GAAgB,QAAQ;AAEzC,IAAA,OAAO,IAAI,CACT,OAAO,IAAI,KAAqB;AAC9B,QAAA,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE;;QAGhC,IACE,KAAK,KAAK,qBAAqB;YAC/B,aAAa,KAAK,qBAAqB,EACvC;YACA,qBAAqB,GAAG,CAAC;QAC3B;QACA,aAAa,GAAG,KAAK;AAErB,QAAA,IAAI,KAAK,KAAK,qBAAqB,EAAE;AACnC,YAAA,MAAM,MAAM,GAAiB;AAC3B,gBAAA,EAAE,EAAE,KAAK;AACT,gBAAA,KAAK,EACH,gFAAgF;aACnF;AACD,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAC/B;AAEA,QAAA,IAAI,qBAAqB,IAAI,UAAU,EAAE;AACvC,YAAA,MAAM,MAAM,GAAiB;AAC3B,gBAAA,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,CAAA,uCAAA,EAA0C,UAAU,CAAA,MAAA,CAAQ;aACpE;AACD,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAC/B;AAEA,QAAA,IAAI;AACF,YAAA,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC;AACjC,YAAA,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;YAClD,qBAAqB,IAAI,CAAC;AAC1B,YAAA,MAAM,MAAM,GAAiB,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;AAC3D,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAC/B;QAAE,OAAO,GAAG,EAAE;AACZ,YAAA,MAAM,MAAM,GAAiB;AAC3B,gBAAA,EAAE,EAAE,KAAK;AACT,gBAAA,KAAK,EAAE,GAAG,YAAY,KAAK,GAAG,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC;aACxD;AACD,YAAA,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAC/B;AACF,IAAA,CAAC,EACD;AACE,QAAA,IAAI,EAAE,uBAAuB;AAC7B,QAAA,WAAW,EAAE,yBAAyB;AACtC,QAAA,MAAM,EAAE,kBAAkB;AAC3B,KAAA,CACF;AACH;;;;"}