From 2973f9f67be08dbd3eca5a2cb24f958097d68eb1 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 6 Nov 2026 23:58:11 +0900 Subject: [PATCH 01/23] fix: preserve SDK recovery state and stop native restart loops --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 6 +- CHANGELOG.md | 14 ++ README.md | 2 +- READMEs/README.ar-SA.md | 2 +- READMEs/README.bn-BD.md | 2 +- READMEs/README.cs-CZ.md | 2 +- READMEs/README.da-DK.md | 2 +- READMEs/README.de-DE.md | 2 +- READMEs/README.el-GR.md | 2 +- READMEs/README.es-ES.md | 2 +- READMEs/README.fi-FI.md | 2 +- READMEs/README.fr-FR.md | 2 +- READMEs/README.he-IL.md | 2 +- READMEs/README.hi-IN.md | 2 +- READMEs/README.hu-HU.md | 2 +- READMEs/README.id-ID.md | 2 +- READMEs/README.it-IT.md | 2 +- READMEs/README.ja-JP.md | 2 +- READMEs/README.ko-KR.md | 2 +- READMEs/README.nb-NO.md | 2 +- READMEs/README.nl-NL.md | 2 +- READMEs/README.pl-PL.md | 2 +- READMEs/README.pt-BR.md | 2 +- READMEs/README.pt-PT.md | 2 +- READMEs/README.ro-RO.md | 2 +- READMEs/README.ru-RU.md | 2 +- READMEs/README.sv-SE.md | 2 +- READMEs/README.th-TH.md | 2 +- READMEs/README.tl-PH.md | 2 +- READMEs/README.tr-TR.md | 2 +- READMEs/README.uk-UA.md | 2 +- READMEs/README.ur-PK.md | 2 +- READMEs/README.vi-VN.md | 2 +- READMEs/README.zh-CN.md | 2 +- READMEs/README.zh-TW.md | 2 +- .../customizations/HOOK-TIMEOUT-2026-10-19.md | 2 +- docs/customizations/HOOK-UPSTREAM-20261102.md | 2 +- .../NATIVE-RECOVERY-DANIEL58.md | 11 ++ .../customizations/SCOPED-HOLD-RECOVERY-57.md | 7 + integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- .../skills/agentmemory-rest-api/REFERENCE.md | 3 +- scripts/docs-sync.state.json | 8 +- scripts/personal-release/kit-runtime.py | 2 + .../personal-release/test_dashboard_kit.py | 9 + src/capture/uncertain-inspection.ts | 29 +++ src/cli.ts | 11 +- src/functions/capture.ts | 52 ++++-- src/functions/export-import.ts | 2 +- src/functions/status.ts | 10 +- src/index.ts | 26 ++- src/ops/background-control.d.mts | 8 +- src/ops/background-control.mjs | 73 ++++++-- src/ops/memory-pressure.mjs | 3 +- src/state/index-persistence.ts | 135 ++++++++++++-- src/state/vector-index.ts | 6 + src/triggers/api.ts | 39 ++-- src/triggers/viewer-streams.ts | 2 +- src/types.ts | 2 +- src/version.ts | 2 +- src/viewer/index.html | 8 +- test/capture-durable.test.ts | 5 + test/capture-sdk-reconciliation-api.test.ts | 50 ++++++ test/cli-native-compat.test.ts | 7 +- test/foreground-vector-hold.test.ts | 25 +++ test/index-persistence.test.ts | 48 +++++ test/operations-background-control.test.ts | 30 ++++ test/operations-protection-recovery.test.ts | 65 ++++++- test/sdk-delivery-v2.test.ts | 1 + test/status.test.ts | 2 +- ...torage-hold-transitions-regression.test.ts | 7 + test/vector-pending-log.test.ts | 170 +++++++++++++++++- test/viewer-operations-browser.test.ts | 4 + 85 files changed, 848 insertions(+), 136 deletions(-) create mode 100644 docs/customizations/NATIVE-RECOVERY-DANIEL58.md create mode 100644 docs/customizations/SCOPED-HOLD-RECOVERY-57.md create mode 100644 src/capture/uncertain-inspection.ts create mode 100644 test/foreground-vector-hold.test.ts create mode 100644 test/storage-hold-transitions-regression.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index b845f693e6..f9c42490a4 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 7811057591..6c09bb3aa5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,13 +114,13 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.55) +## Current Stats (v0.9.32-daniel.58) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials -- 160 REST endpoints +- 161 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 17 skills -- 353+ iii functions +- 355+ iii functions - 6,300+ tests ## Personal fork verification isolation diff --git a/CHANGELOG.md b/CHANGELOG.md index 37c1fdc2a8..83ff811f13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ ## [Unreleased] +## [0.9.32-daniel.58] — 2026-11-06 (recovery review candidate) + +- Based on the installed .55 Git commit `4605974f337a50ed7e0ef74e3bb635b6e5d5a805` and the scoped .57 held-start changes from `3148e1d0a3df0241b69b2166085b10ed5979b99f`. This is a separate review candidate for the November 6 outage. +- Limit SDK vector checkpoint reads to one bucket at a time and stop on the first read error. Preserve concurrent reads for disk completion. Keep the .57 guard on vector work during an unresolved storage hold and skip full inbox scans by automatic Viewer updates. +- Give unresolved native worker ownership its own exit status (78). The managed native unit stops retrying that refusal and continues to retry transient failures. +- When memory and storage are both held, release only the memory hold after sustained recovery and a fresh post-wait memory sample. Keep the storage hold and require explicit storage recovery. +- Before an explicit SDK storage recovery, require an empty, readable vector pending log. Retain existing intent and refuse activation when there are entries, unconfirmed reads, or in-flight local log writes. +- The candidate passed 335 focused tests across 15 files, including Chromium, CLI startup, memory recovery and vector intent. All 38 build configurations, asset copying and the server SDK audit passed in sequential batches. The parallel build exceeded the configured V8 heap limits of 700 and 1280 MiB. TypeScript reported the same 30 pre-existing diagnostics as .55. +- Production remains on .55. The incident report records operational evidence and outstanding non-clean recovery admission. + +## [0.9.32-daniel.57] — 2026-11-06 +- Prepare scoped storage-hold protection and viewer status load mitigation; SDK completion remains distinct from disk persistence. Not deployed; compound-hold automatic release is not implemented. See docs/customizations/SCOPED-HOLD-RECOVERY-57.md. + ## [0.9.32-daniel.55] — 2026-11-04 ### Prepared integration (not deployed) @@ -554,6 +567,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.57]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.55...v0.9.32-daniel.57 [0.9.32-daniel.55]: https://github.com/rohitg00/agentmemory/compare/v0.9.31-daniel.54...v0.9.32-daniel.55 [0.9.31-daniel.54]: https://github.com/rohitg00/agentmemory/compare/v0.9.31-daniel.51...v0.9.31-daniel.54 diff --git a/README.md b/README.md index 85b3b82732..3d3e753031 100644 --- a/README.md +++ b/README.md @@ -1221,7 +1221,7 @@ The complete reference is [`.env.example`](.env.example), including provider cre

API

-160 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer `, and mesh sync endpoints require an explicitly set `AGENTMEMORY_SECRET` on both peers. +161 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer `, and mesh sync endpoints require an explicitly set `AGENTMEMORY_SECRET` on both peers. **Authentication is on by default.** When `AGENTMEMORY_SECRET` is not set (in the shell or in `~/.agentmemory/.env`), the CLI generates a random secret on first start and stores it at `~/.agentmemory/secret`, mirrored to the selected data directory as `secret`, with mode `0600` (the platform-specific default data directory is described above). Bundled clients read the canonical secret first when they talk to a local server: the CLI, the viewer, the hooks under `plugin/scripts`, the MCP server and the `@agentmemory/mcp` shim, the configs written by `agentmemory connect`, and the bundled OpenCode, Pi, OpenClaw, Hermes and filesystem-watcher integrations. The stored secret is only sent to loopback URLs (`localhost`, `127.0.0.0/8`, `::1`). An explicit `AGENTMEMORY_SECRET` always wins, and remote clients need the secret set in their environment. Repository-based Docker self-host deployments and the `deploy/` entrypoints generate and export their own secret. To call the API by hand: diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.md index 8b8b940dec..4cead55e59 100644 --- a/READMEs/README.ar-SA.md +++ b/READMEs/README.ar-SA.md @@ -1161,7 +1161,7 @@ EMBEDDING_PROVIDER=local

API

-160 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer `، وتتطلب نقاط نهاية مزامنة mesh ضبط `AGENTMEMORY_SECRET` صريحًا على كلا الطرفين. +161 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer `، وتتطلب نقاط نهاية مزامنة mesh ضبط `AGENTMEMORY_SECRET` صريحًا على كلا الطرفين. **المصادقة مُفعّلة افتراضيًا.** إذا لم يُضبط `AGENTMEMORY_SECRET`، ينشئ CLI عند التشغيل الأول سرًا عشوائيًا في `~/.agentmemory/secret` بصلاحيات `0600` وينسخه أيضًا إلى مجلد البيانات المحدد. يقرأ كل عميل مضمّن هذا السر عند الاتصال بخادم محلي: CLI والعارض والخطافات تحت `plugin/scripts` وخادم MCP ووسيط `@agentmemory/mcp` والإعدادات التي يكتبها `agentmemory connect` وتكاملات OpenCode وPi وOpenClaw وHermes ومراقب نظام الملفات المضمّنة. لا يُرسل السر المحفوظ إلا إلى عناوين loopback (`localhost` و`127.0.0.0/8` و`::1`). وتكون الأولوية دائمًا لقيمة `AGENTMEMORY_SECRET` الصريحة، كما يجب ضبط السر في بيئة العملاء البعيدين. تنشئ عمليات الاستضافة الذاتية عبر Docker من المستودع ونقاط دخول [`deploy/`](../deploy/) سرها وتصدّره. لاستدعاء API يدويًا: diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.md index 9349ab0c2e..d22af39ca9 100644 --- a/READMEs/README.bn-BD.md +++ b/READMEs/README.bn-BD.md @@ -1174,7 +1174,7 @@ EMBEDDING_PROVIDER=local

API

-`3111` পোর্টে 160 এন্ডপয়েন্ট। REST API ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে। প্রোটেক্টেড এন্ডপয়েন্টে `Authorization: Bearer ` লাগে, এবং mesh sync এন্ডপয়েন্টে দুই পিয়ারেই স্পষ্টভাবে সেট করা `AGENTMEMORY_SECRET` লাগে। +`3111` পোর্টে 161 এন্ডপয়েন্ট। REST API ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে। প্রোটেক্টেড এন্ডপয়েন্টে `Authorization: Bearer ` লাগে, এবং mesh sync এন্ডপয়েন্টে দুই পিয়ারেই স্পষ্টভাবে সেট করা `AGENTMEMORY_SECRET` লাগে। প্রমাণীকরণ ডিফল্টভাবে চালু। `AGENTMEMORY_SECRET` নির্ধারিত না থাকলে CLI প্রথমবার একটি random secret `~/.agentmemory/secret`-এ রাখে এবং নির্বাচিত ডেটা ডিরেক্টরির `secret`-এ কপি করে; অনুমতি `0600`। সঙ্গে থাকা ক্লায়েন্ট লোকাল সংযোগে মূল ফাইলটিকে অগ্রাধিকার দেয় এবং সংরক্ষিত secret শুধু loopback URL-এ পাঠায়। স্পষ্ট `AGENTMEMORY_SECRET` অগ্রাধিকার পায়; রিমোট ক্লায়েন্টকে environment-এ সেট করতে হয়। Docker নিজস্ব secret তৈরি করে। diff --git a/READMEs/README.cs-CZ.md b/READMEs/README.cs-CZ.md index 7944caa5ec..63b0abed3a 100644 --- a/READMEs/README.cs-CZ.md +++ b/READMEs/README.cs-CZ.md @@ -1160,7 +1160,7 @@ EMBEDDING_PROVIDER=local

API

-160 endpointů na portu `3111`. REST API se ve výchozím stavu váže na `127.0.0.1`. Chráněné endpointy vyžadují `Authorization: Bearer `, a endpointy pro mesh sync vyžadují explicitně nastavené `AGENTMEMORY_SECRET` na obou stranách. +161 endpointů na portu `3111`. REST API se ve výchozím stavu váže na `127.0.0.1`. Chráněné endpointy vyžadují `Authorization: Bearer `, a endpointy pro mesh sync vyžadují explicitně nastavené `AGENTMEMORY_SECRET` na obou stranách. **Autentizace je ve výchozím stavu zapnutá.** Pokud `AGENTMEMORY_SECRET` není nastaveno, CLI při prvním spuštění vygeneruje náhodný secret v `~/.agentmemory/secret` s oprávněním `0600` a zkopíruje jej také do vybraného datového adresáře. Všichni zabalení klienti jej načítají odtud při komunikaci s lokálním serverem: CLI, viewer, hooks v `plugin/scripts`, server MCP a shim `@agentmemory/mcp`, konfigurace zapsané pomocí `agentmemory connect` a zabalené integrace OpenCode, Pi, OpenClaw, Hermes a filesystem-watcher. Uložený secret se odesílá pouze na loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Výslovně nastavená `AGENTMEMORY_SECRET` má vždy přednost a vzdálení klienti ji musí mít ve svém prostředí. Self-host nasazení Dockeru z repozitáře a entrypointy `deploy/` generují a exportují vlastní secret. Pro ruční volání API: diff --git a/READMEs/README.da-DK.md b/READMEs/README.da-DK.md index 80575e8682..cd4fa4e137 100644 --- a/READMEs/README.da-DK.md +++ b/READMEs/README.da-DK.md @@ -1168,7 +1168,7 @@ Den fulde reference er [`.env.example`](../.env.example) med legitimationsoplysn

API

-160 endpoints på port `3111`. REST API'et binder til `127.0.0.1` som standard. Beskyttede endpoints kræver `Authorization: Bearer `, og mesh-sync-endpoints kræver en eksplicit sat `AGENTMEMORY_SECRET` på begge peers. +161 endpoints på port `3111`. REST API'et binder til `127.0.0.1` som standard. Beskyttede endpoints kræver `Authorization: Bearer `, og mesh-sync-endpoints kræver en eksplicit sat `AGENTMEMORY_SECRET` på begge peers. **Autentificering er slået til som standard.** Hvis `AGENTMEMORY_SECRET` hverken er sat i shellen eller i `~/.agentmemory/.env`, opretter CLI’en en tilfældig hemmelighed ved første start i `~/.agentmemory/secret` og en kopi med navnet `secret` i den valgte datamappe, med filtilstanden `0600`. Alle medfølgende klienter læser den derfra, når de taler med en lokal server: CLI’en, viewer, hooks under `plugin/scripts`, MCP-serveren og `@agentmemory/mcp`-shimmen, konfigurationerne skrevet af `agentmemory connect`, og de medfølgende OpenCode-, Pi-, OpenClaw-, Hermes- og filesystem-watcher-integrationer. Den lagrede secret sendes kun til loopback-URL’er (`localhost`, `127.0.0.0/8`, `::1`). En eksplicit `AGENTMEMORY_SECRET` vinder altid, og eksterne klienter skal have den i deres miljø. Docker-self-hosting fra repositoryet og `deploy/`-entrypoints genererer og eksporterer deres egen secret. Sådan kaldes API’et manuelt: diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md index 83f9181cd6..7f0521d964 100644 --- a/READMEs/README.de-DE.md +++ b/READMEs/README.de-DE.md @@ -1166,7 +1166,7 @@ Die vollständige Referenz steht in [`.env.example`](../.env.example), einschlie

API

-160 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer `, und Mesh-Sync-Endpunkte erfordern ein explizit gesetztes `AGENTMEMORY_SECRET` auf beiden Peers. +161 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer `, und Mesh-Sync-Endpunkte erfordern ein explizit gesetztes `AGENTMEMORY_SECRET` auf beiden Peers. **Authentifizierung ist standardmäßig aktiv.** Wenn `AGENTMEMORY_SECRET` weder in der Shell noch in `~/.agentmemory/.env` gesetzt ist, erzeugt die CLI beim ersten Start ein zufälliges Secret unter `~/.agentmemory/secret` und spiegelt es als `secret` in das ausgewählte Datenverzeichnis, jeweils mit Dateimodus `0600`. Jeder mitgelieferte Client liest es von dort, wenn er mit einem lokalen Server spricht: die CLI, der Viewer, die Hooks unter `plugin/scripts`, der MCP-Server und das `@agentmemory/mcp`-Shim, die von `agentmemory connect` geschriebenen Konfigs sowie die mitgelieferten Integrationen für OpenCode, Pi, OpenClaw, Hermes und den Filesystem-Watcher. Das gespeicherte Secret wird nur an Loopback-URLs gesendet (`localhost`, `127.0.0.0/8`, `::1`). Ein explizites `AGENTMEMORY_SECRET` gewinnt immer, und Remote-Clients benötigen es trotzdem gesetzt. Docker und die `deploy/`-Entrypoints erzeugen und exportieren bereits ihr eigenes Secret. Um die API von Hand aufzurufen: diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.md index 881e722a43..e702759fd6 100644 --- a/READMEs/README.el-GR.md +++ b/READMEs/README.el-GR.md @@ -1160,7 +1160,7 @@ EMBEDDING_PROVIDER=local

API

-160 endpoints στη θύρα `3111`. Το REST API συνδέεται στο `127.0.0.1` από προεπιλογή. Τα προστατευμένα endpoints απαιτούν `Authorization: Bearer `, και τα endpoints mesh sync απαιτούν ένα ρητά ρυθμισμένο `AGENTMEMORY_SECRET` και στους δύο peers. +161 endpoints στη θύρα `3111`. Το REST API συνδέεται στο `127.0.0.1` από προεπιλογή. Τα προστατευμένα endpoints απαιτούν `Authorization: Bearer `, και τα endpoints mesh sync απαιτούν ένα ρητά ρυθμισμένο `AGENTMEMORY_SECRET` και στους δύο peers. **Η πιστοποίηση είναι ενεργή από προεπιλογή.** Όταν δεν ορίζεται `AGENTMEMORY_SECRET`, στην πρώτη εκκίνηση το CLI δημιουργεί τυχαίο μυστικό στο `~/.agentmemory/secret` με δικαιώματα `0600` και το αντιγράφει και στον επιλεγμένο κατάλογο δεδομένων. Κάθε ενσωματωμένος client το διαβάζει από εκεί όταν μιλά με έναν τοπικό διακομιστή: το CLI, το viewer, τα hooks κάτω από το `plugin/scripts`, ο διακομιστής MCP και το shim `@agentmemory/mcp`, οι ρυθμίσεις που γράφει το `agentmemory connect`, και οι ενσωματωμένες ενσωματώσεις OpenCode, Pi, OpenClaw, Hermes, και filesystem-watcher. Το αποθηκευμένο secret αποστέλλεται μόνο σε loopback URLs (`localhost`, `127.0.0.0/8`, `::1`). Ένα ρητό `AGENTMEMORY_SECRET` υπερισχύει πάντα, και οι απομακρυσμένοι clients εξακολουθούν να το χρειάζονται ρυθμισμένο. Το Docker και τα entrypoints του `deploy/` δημιουργούν και εξάγουν ήδη το δικό τους secret. Για να καλέσετε το API χειροκίνητα: diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md index 38a5639c25..b3f8c715bb 100644 --- a/READMEs/README.es-ES.md +++ b/READMEs/README.es-ES.md @@ -1162,7 +1162,7 @@ La referencia completa está en [`.env.example`](../.env.example): credenciales,

API

-160 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer `, y los endpoints de mesh sync requieren un `AGENTMEMORY_SECRET` definido explícitamente en ambos peers. +161 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer `, y los endpoints de mesh sync requieren un `AGENTMEMORY_SECRET` definido explícitamente en ambos peers. **La autenticación está activada por defecto.** Si `AGENTMEMORY_SECRET` no está definida en la shell ni en `~/.agentmemory/.env`, la CLI genera un secreto aleatorio en el primer inicio en `~/.agentmemory/secret` y lo copia como `secret` en el directorio de datos seleccionado, con permisos `0600`. Todos los clientes incluidos lo leen desde allí al comunicarse con un servidor local: la CLI, el visor, los hooks de `plugin/scripts`, el servidor MCP y el shim `@agentmemory/mcp`, las configuraciones escritas por `agentmemory connect` y las integraciones incluidas de OpenCode, Pi, OpenClaw, Hermes y filesystem-watcher. El secreto guardado solo se envía a URL de loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explícito siempre tiene prioridad, y los clientes remotos necesitan que el secreto esté definido en su entorno. Los despliegues Docker alojados por cuenta propia desde el repositorio y los entrypoints de `deploy/` generan y exportan su propio secreto. Para llamar a la API manualmente: diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.md index 35ace71c3f..8f263eac21 100644 --- a/READMEs/README.fi-FI.md +++ b/READMEs/README.fi-FI.md @@ -1160,7 +1160,7 @@ Täydellinen [`.env.example`](../.env.example) kattaa palveluntarjoajat, tallenn

API

-160 endpointia portissa `3111`. REST-rajapinta sitoutuu oletuksena osoitteeseen `127.0.0.1`. Suojatut endpointit vaativat `Authorization: Bearer `, ja mesh-synkronointiendpointit vaativat nimenomaisesti asetetun `AGENTMEMORY_SECRET`-arvon molemmilla vertaisilla. +161 endpointia portissa `3111`. REST-rajapinta sitoutuu oletuksena osoitteeseen `127.0.0.1`. Suojatut endpointit vaativat `Authorization: Bearer `, ja mesh-synkronointiendpointit vaativat nimenomaisesti asetetun `AGENTMEMORY_SECRET`-arvon molemmilla vertaisilla. **Autentikointi on oletuksena päällä.** Jos `AGENTMEMORY_SECRET` puuttuu, CLI luo ensimmäisellä käynnistyksellä satunnaisen salaisuuden tiedostoon `~/.agentmemory/secret` oikeuksilla `0600` ja kopioi sen myös valittuun datahakemistoon. Kaikki mukana toimitetut asiakkaat lukevat salaisuuden sieltä käyttäessään paikallista palvelinta: CLI, katseluohjelma, `plugin/scripts`-hakemiston hookit, MCP-palvelin ja `@agentmemory/mcp`-shim, `agentmemory connect` -komennon luomat asetukset sekä mukana toimitetut OpenCode-, Pi-, OpenClaw-, Hermes- ja filesystem-watcher-integraatiot. Tallennettu salaisuus lähetetään vain loopback-osoitteisiin (`localhost`, `127.0.0.0/8`, `::1`). Nimenomainen `AGENTMEMORY_SECRET` voittaa aina, ja etäasiakkaiden on asetettava salaisuus ympäristöönsä. Repositorion Docker-itseylläpitokäyttöönotot ja `deploy/`-entrypointit luovat ja vievät oman salaisuutensa. Rajapinnan manuaalinen kutsu: diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.md index 145ef84eb3..c3e49d83cf 100644 --- a/READMEs/README.fr-FR.md +++ b/READMEs/README.fr-FR.md @@ -1169,7 +1169,7 @@ La référence complète est [`.env.example`](../.env.example) : identifiants de

API

-160 endpoints sur le port `3111`. L'API REST se lie à `127.0.0.1` par défaut. Les endpoints protégés requièrent `Authorization: Bearer `, et les endpoints de mesh sync requièrent un `AGENTMEMORY_SECRET` explicitement défini sur les deux pairs. +161 endpoints sur le port `3111`. L'API REST se lie à `127.0.0.1` par défaut. Les endpoints protégés requièrent `Authorization: Bearer `, et les endpoints de mesh sync requièrent un `AGENTMEMORY_SECRET` explicitement défini sur les deux pairs. **L'authentification est activée par défaut.** Si `AGENTMEMORY_SECRET` n'est défini ni dans le shell ni dans `~/.agentmemory/.env`, la CLI génère un secret aléatoire au premier lancement dans `~/.agentmemory/secret` et en conserve une copie nommée `secret` dans le répertoire de données choisi, avec les permissions `0600`. Chaque client embarqué le lit depuis là quand il parle à un serveur local : la CLI, le visualiseur, les hooks sous `plugin/scripts`, le serveur MCP et le shim `@agentmemory/mcp`, les configs écrites par `agentmemory connect`, et les intégrations embarquées OpenCode, Pi, OpenClaw, Hermes et filesystem-watcher. Le secret stocké n'est envoyé qu'à des URLs loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explicite prime toujours, et les clients distants en ont toujours besoin. Docker et les points d'entrée `deploy/` génèrent et exportent déjà leur propre secret. Pour appeler l'API à la main : diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.md index c991700ff7..000ac1b192 100644 --- a/READMEs/README.he-IL.md +++ b/READMEs/README.he-IL.md @@ -1161,7 +1161,7 @@ EMBEDDING_PROVIDER=local

API

-160 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer `, ו-endpoints של mesh sync דורשים `AGENTMEMORY_SECRET` מוגדר באופן מפורש בשני ה-peers. +161 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer `, ו-endpoints של mesh sync דורשים `AGENTMEMORY_SECRET` מוגדר באופן מפורש בשני ה-peers. **אימות (Authentication) פעיל כברירת מחדל.** אם `AGENTMEMORY_SECRET` לא מוגדר, בהפעלה הראשונה ה-CLI יוצר סוד אקראי ב-`~/.agentmemory/secret` עם הרשאות `0600`, ומעתיק אותו גם לתיקיית הנתונים שנבחרה. כל לקוח מצורף קורא אותו משם כשהוא מדבר עם שרת מקומי: ה-CLI, המציג, ה-hooks תחת `plugin/scripts`, שרת ה-MCP וה-shim `@agentmemory/mcp`, התצורות שנכתבות על ידי `agentmemory connect`, והאינטגרציות המצורפות של OpenCode, Pi, OpenClaw, Hermes וה-filesystem-watcher. ה-secret המאוחסן נשלח רק ל-URLs של loopback (`localhost`, `127.0.0.0/8`, `::1`). `AGENTMEMORY_SECRET` מפורש גובר תמיד, ולקוחות מרוחקים עדיין צריכים אותו מוגדר. Docker וה-entrypoints של `deploy/` כבר מייצרים ומייצאים את ה-secret שלהם. כדי לקרוא ל-API ביד: diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.md index 428ec3eea4..1c381e874d 100644 --- a/READMEs/README.hi-IN.md +++ b/READMEs/README.hi-IN.md @@ -1175,7 +1175,7 @@ EMBEDDING_PROVIDER=local

API

-Port `3111` पर 160 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। Protected endpoints `Authorization: Bearer ` की आवश्यकता रखते हैं, और mesh sync endpoints दोनों peers पर एक explicitly set `AGENTMEMORY_SECRET` की आवश्यकता रखते हैं। +Port `3111` पर 161 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। Protected endpoints `Authorization: Bearer ` की आवश्यकता रखते हैं, और mesh sync endpoints दोनों peers पर एक explicitly set `AGENTMEMORY_SECRET` की आवश्यकता रखते हैं। प्रमाणीकरण डिफ़ॉल्ट रूप से चालू है। `AGENTMEMORY_SECRET` सेट न होने पर CLI पहली बार एक random secret `~/.agentmemory/secret` में रखता है और चुनी हुई डेटा डायरेक्टरी के `secret` में उसकी प्रति बनाता है; permissions `0600` होती हैं। साथ आए क्लाइंट लोकल कनेक्शन में इस मूल फ़ाइल को प्राथमिकता देते हैं और सेव किया secret सिर्फ loopback URL को भेजते हैं। स्पष्ट `AGENTMEMORY_SECRET` प्राथमिकता रखता है; रिमोट क्लाइंट को इसे environment में सेट करना होता है। Docker अपना secret बनाता है। diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.md index ae152ce45f..236a52f2ee 100644 --- a/READMEs/README.hu-HU.md +++ b/READMEs/README.hu-HU.md @@ -1158,7 +1158,7 @@ A teljes [`.env.example`](../.env.example) leírja a szolgáltatókat, rögzít

API

-160 endpoint a `3111`-es porton. A REST API alapértelmezetten a `127.0.0.1`-hez kötődik. A védett végpontok `Authorization: Bearer `-et igényelnek, és a mesh-sync végpontok mindkét oldalon explicit módon beállított `AGENTMEMORY_SECRET`-et igényelnek. +161 endpoint a `3111`-es porton. A REST API alapértelmezetten a `127.0.0.1`-hez kötődik. A védett végpontok `Authorization: Bearer `-et igényelnek, és a mesh-sync végpontok mindkét oldalon explicit módon beállított `AGENTMEMORY_SECRET`-et igényelnek. **A hitelesítés alapértelmezetten be van kapcsolva.** Ha az `AGENTMEMORY_SECRET` nincs beállítva, a CLI első indításkor véletlen titkot hoz létre a `~/.agentmemory/secret` fájlban `0600` jogosultsággal, és a kiválasztott adatkönyvtárba is átmásolja. Minden becsomagolt kliens onnan olvassa, amikor egy lokális szerverrel beszél: a CLI, a megjelenítő, a `plugin/scripts` alatti hookok, az MCP szerver és a `@agentmemory/mcp` shim, az `agentmemory connect` által írt konfigurációk, és a becsomagolt OpenCode, Pi, OpenClaw, Hermes és fájlrendszer-figyelő integrációk. A tárolt secret csak loopback URL-eknek kerül elküldésre (`localhost`, `127.0.0.0/8`, `::1`). Egy explicit `AGENTMEMORY_SECRET` mindig elsőbbséget kap, és a távoli klienseknek továbbra is be kell állítaniuk. A Docker és a `deploy/` entrypointok már generálnak és exportálnak egy saját secretet. Az API kézi hívásához: diff --git a/READMEs/README.id-ID.md b/READMEs/README.id-ID.md index 1d772bdee5..bb15185d7b 100644 --- a/READMEs/README.id-ID.md +++ b/READMEs/README.id-ID.md @@ -1175,7 +1175,7 @@ Referensi lengkap ada di [`.env.example`](../.env.example), termasuk penyedia, f

API

-160 endpoint di port `3111`. REST API terbind ke `127.0.0.1` secara default. Endpoint yang terlindungi membutuhkan `Authorization: Bearer `, dan endpoint mesh sync membutuhkan `AGENTMEMORY_SECRET` yang diset secara eksplisit di kedua peer. +161 endpoint di port `3111`. REST API terbind ke `127.0.0.1` secara default. Endpoint yang terlindungi membutuhkan `Authorization: Bearer `, dan endpoint mesh sync membutuhkan `AGENTMEMORY_SECRET` yang diset secara eksplisit di kedua peer. Autentikasi aktif secara default. Jika `AGENTMEMORY_SECRET` tidak disetel, CLI membuat rahasia acak saat pertama dijalankan di `~/.agentmemory/secret` dan menyalinnya ke `secret` dalam direktori data terpilih, dengan mode `0600`. Klien bawaan mengutamakan file kanonis ini untuk koneksi lokal dan hanya mengirim rahasia tersimpan ke URL loopback. `AGENTMEMORY_SECRET` eksplisit selalu diutamakan; klien remote harus mengaturnya melalui environment. Deployment Docker membuat rahasianya sendiri. diff --git a/READMEs/README.it-IT.md b/READMEs/README.it-IT.md index 657e478eaf..8468029739 100644 --- a/READMEs/README.it-IT.md +++ b/READMEs/README.it-IT.md @@ -1168,7 +1168,7 @@ La documentazione completa è in [`.env.example`](../.env.example): credenziali,

API

-160 endpoint sulla porta `3111`. L'API REST si collega a `127.0.0.1` per impostazione predefinita. Gli endpoint protetti richiedono `Authorization: Bearer `, e gli endpoint di sincronizzazione mesh richiedono un `AGENTMEMORY_SECRET` impostato esplicitamente su entrambi i peer. +161 endpoint sulla porta `3111`. L'API REST si collega a `127.0.0.1` per impostazione predefinita. Gli endpoint protetti richiedono `Authorization: Bearer `, e gli endpoint di sincronizzazione mesh richiedono un `AGENTMEMORY_SECRET` impostato esplicitamente su entrambi i peer. **L'autenticazione è attiva per default.** Se `AGENTMEMORY_SECRET` non è impostato nella shell o in `~/.agentmemory/.env`, al primo avvio la CLI genera un segreto casuale in `~/.agentmemory/secret` e ne conserva una copia chiamata `secret` nella directory dati selezionata, con permessi `0600`. Ogni client incluso lo legge da lì quando parla con un server locale: la CLI, il viewer, gli hook sotto `plugin/scripts`, il server MCP e lo shim `@agentmemory/mcp`, le configurazioni scritte da `agentmemory connect`, e le integrazioni incluse OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. Il secret memorizzato viene inviato solo a URL loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` esplicito vince sempre, e i client remoti devono comunque averlo impostato. Docker e gli entrypoint di `deploy/` generano ed esportano già il proprio secret. Per chiamare l'API a mano: diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md index 17f7243c49..06f9971c45 100644 --- a/READMEs/README.ja-JP.md +++ b/READMEs/README.ja-JP.md @@ -1174,7 +1174,7 @@ EMBEDDING_PROVIDER=local

API

-ポート `3111` 上の 160 エンドポイント。REST API はデフォルトで `127.0.0.1` にバインドします。保護されたエンドポイントは `Authorization: Bearer ` を要求し、mesh sync エンドポイントは両ピアで明示的に設定された `AGENTMEMORY_SECRET` を要求します。 +ポート `3111` 上の 161 エンドポイント。REST API はデフォルトで `127.0.0.1` にバインドします。保護されたエンドポイントは `Authorization: Bearer ` を要求し、mesh sync エンドポイントは両ピアで明示的に設定された `AGENTMEMORY_SECRET` を要求します。 認証はデフォルトで有効です。`AGENTMEMORY_SECRET` が未設定なら、CLI は初回起動時にランダムなシークレットを `~/.agentmemory/secret` に保存し、選択したデータディレクトリの `secret` にも複製します。権限は `0600` です。同梱クライアントはローカル接続時にこの共通ファイルを優先し、保存されたシークレットを送るのはループバック URL だけです。明示的な `AGENTMEMORY_SECRET` が優先され、リモート接続には環境変数で指定します。Docker デプロイは独自のシークレットを生成します。 diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md index 3ca01235cc..1f94ec27f1 100644 --- a/READMEs/README.ko-KR.md +++ b/READMEs/README.ko-KR.md @@ -1173,7 +1173,7 @@ EMBEDDING_PROVIDER=local

API

-포트 `3111`의 엔드포인트 160개. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `Authorization: Bearer `을 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에 `AGENTMEMORY_SECRET`이 명시적으로 설정되어 있어야 합니다. +포트 `3111`의 엔드포인트 161개. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `Authorization: Bearer `을 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에 `AGENTMEMORY_SECRET`이 명시적으로 설정되어 있어야 합니다. 인증은 기본적으로 활성화됩니다. `AGENTMEMORY_SECRET`이 없으면 CLI가 처음 시작할 때 임의의 비밀값을 `~/.agentmemory/secret`에 저장하고 선택한 데이터 디렉터리의 `secret`에도 복사합니다. 권한은 `0600`입니다. 번들 클라이언트는 로컬 연결 시 이 공통 파일을 우선하며 저장된 비밀값은 루프백 URL에만 보냅니다. 명시적인 `AGENTMEMORY_SECRET`이 우선하고 원격 클라이언트는 환경 변수로 설정해야 합니다. Docker 배포는 자체 비밀값을 생성합니다. diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.md index 0c45f96aa1..40a00287b1 100644 --- a/READMEs/README.nb-NO.md +++ b/READMEs/README.nb-NO.md @@ -1166,7 +1166,7 @@ Den fullstendige referansen er [`.env.example`](../.env.example), med legitimasj

API

-160 endepunkter på port `3111`. REST-API-en bindes til `127.0.0.1` som standard. Beskyttede endepunkter krever `Authorization: Bearer `, og mesh-synkroniseringsendepunkter krever en uttrykkelig satt `AGENTMEMORY_SECRET` på begge sider. +161 endepunkter på port `3111`. REST-API-en bindes til `127.0.0.1` som standard. Beskyttede endepunkter krever `Authorization: Bearer `, og mesh-synkroniseringsendepunkter krever en uttrykkelig satt `AGENTMEMORY_SECRET` på begge sider. **Autentisering er på som standard.** Hvis `AGENTMEMORY_SECRET` verken er satt i skallet eller i `~/.agentmemory/.env`, oppretter CLI-en en tilfeldig hemmelighet ved første start i `~/.agentmemory/secret` og en kopi kalt `secret` i den valgte datamappen, med filmodus `0600`. Alle medfølgende klienter leser den derfra når de snakker med en lokal server: CLI-en, viewer, hookene under `plugin/scripts`, MCP-serveren og `@agentmemory/mcp`-shimmen, konfigurasjonene skrevet av `agentmemory connect` og de medfølgende OpenCode-, Pi-, OpenClaw-, Hermes- og filsystemovervåker-integrasjonene. Den lagrede hemmeligheten sendes bare til loopback-URL-er (`localhost`, `127.0.0.0/8`, `::1`). En uttrykkelig `AGENTMEMORY_SECRET` vinner alltid, og eksterne klienter trenger hemmeligheten i miljøet sitt. Docker-basert selvhosting fra repoet og `deploy/`-entrypointene genererer og eksporterer sin egen hemmelighet. Slik kaller du API-et manuelt: diff --git a/READMEs/README.nl-NL.md b/READMEs/README.nl-NL.md index 9d4f9ce74e..1031c868d2 100644 --- a/READMEs/README.nl-NL.md +++ b/READMEs/README.nl-NL.md @@ -1162,7 +1162,7 @@ De volledige referentie staat in [`.env.example`](../.env.example), met provider

API

-160 endpoints op poort `3111`. De REST API bindt standaard aan `127.0.0.1`. Beschermde endpoints vereisen `Authorization: Bearer `, en mesh-sync-endpoints vereisen een expliciet ingestelde `AGENTMEMORY_SECRET` op beide peers. +161 endpoints op poort `3111`. De REST API bindt standaard aan `127.0.0.1`. Beschermde endpoints vereisen `Authorization: Bearer `, en mesh-sync-endpoints vereisen een expliciet ingestelde `AGENTMEMORY_SECRET` op beide peers. **Authenticatie staat standaard aan.** Als `AGENTMEMORY_SECRET` niet in de shell of in `~/.agentmemory/.env` staat, maakt de CLI bij de eerste start een willekeurig secret in `~/.agentmemory/secret` en een kopie met de naam `secret` in de geselecteerde gegevensmap, met bestandsmodus `0600`. Elke gebundelde client leest het daar wanneer die met een lokale server communiceert: de CLI, viewer, hooks onder `plugin/scripts`, MCP-server en `@agentmemory/mcp`-shim, configs geschreven door `agentmemory connect`, en de gebundelde OpenCode-, Pi-, OpenClaw-, Hermes- en filesystem-watcher-integraties. Het opgeslagen secret wordt alleen verstuurd naar loopback-URL's (`localhost`, `127.0.0.0/8`, `::1`). Een expliciete `AGENTMEMORY_SECRET` wint altijd, en externe clients hebben het secret in hun omgeving nodig. Docker self-host deployments vanuit de repository en de `deploy/`-entrypoints genereren en exporteren hun eigen secret. Zo roep je de API handmatig aan: diff --git a/READMEs/README.pl-PL.md b/READMEs/README.pl-PL.md index 6c49f60af8..8e96d22c1e 100644 --- a/READMEs/README.pl-PL.md +++ b/READMEs/README.pl-PL.md @@ -1158,7 +1158,7 @@ Pełny opis w [`.env.example`](../.env.example) obejmuje dostawców, filtry prze

API

-160 endpointów na porcie `3111`. REST API domyślnie wiąże się z `127.0.0.1`. Chronione endpointy wymagają `Authorization: Bearer `, a endpointy synchronizacji mesh wymagają wyraźnie ustawionego `AGENTMEMORY_SECRET` na obu peerach. +161 endpointów na porcie `3111`. REST API domyślnie wiąże się z `127.0.0.1`. Chronione endpointy wymagają `Authorization: Bearer `, a endpointy synchronizacji mesh wymagają wyraźnie ustawionego `AGENTMEMORY_SECRET` na obu peerach. **Autoryzacja jest domyślnie włączona.** Gdy `AGENTMEMORY_SECRET` nie jest ustawiony, CLI przy pierwszym uruchomieniu generuje losowy sekret w `~/.agentmemory/secret` z uprawnieniami `0600` i kopiuje go także do wybranego katalogu danych. Wszystkie dołączone klienty odczytują go stamtąd, gdy łączą się z lokalnym serwerem: CLI, podgląd, hooki w `plugin/scripts`, serwer MCP i shim `@agentmemory/mcp`, konfiguracje tworzone przez `agentmemory connect` oraz dołączone integracje OpenCode, Pi, OpenClaw, Hermes i obserwator systemu plików. Zapisany sekret jest wysyłany tylko na adresy loopback (`localhost`, `127.0.0.0/8`, `::1`). Jawnie ustawione `AGENTMEMORY_SECRET` ma zawsze pierwszeństwo, a zdalni klienci muszą mieć sekret w swoim środowisku. Wdrożenia self-hosted Docker oparte na repozytorium i punkty wejścia `deploy/` generują i eksportują własny sekret. Aby ręcznie wywołać API: diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.md index 2f60bda7a1..64215dd7b5 100644 --- a/READMEs/README.pt-BR.md +++ b/READMEs/README.pt-BR.md @@ -1166,7 +1166,7 @@ A referência completa está em [`.env.example`](../.env.example): credenciais,

API

-160 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer `, e endpoints de mesh sync exigem um `AGENTMEMORY_SECRET` explicitamente definido em ambos os peers. +161 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer `, e endpoints de mesh sync exigem um `AGENTMEMORY_SECRET` explicitamente definido em ambos os peers. **A autenticação vem ativada por padrão.** Quando `AGENTMEMORY_SECRET` não está definida na shell nem em `~/.agentmemory/.env`, a CLI gera um segredo aleatório na primeira execução em `~/.agentmemory/secret` e grava uma cópia chamada `secret` no diretório de dados selecionado, com permissões `0600`. Todos os clientes empacotados o leem de lá ao falar com um servidor local: CLI, viewer, hooks em `plugin/scripts`, servidor MCP e shim `@agentmemory/mcp`, configurações escritas por `agentmemory connect` e integrações empacotadas de OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. O secret armazenado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Um `AGENTMEMORY_SECRET` explícito sempre prevalece, e clientes remotos precisam ter o secret definido em seu ambiente. Deploys self-hosted com Docker baseados no repositório e os entrypoints de `deploy/` geram e exportam seu próprio secret. Para chamar a API manualmente: diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.md index db51d1fc34..d794454cc5 100644 --- a/READMEs/README.pt-PT.md +++ b/READMEs/README.pt-PT.md @@ -1162,7 +1162,7 @@ A referência completa está em [`.env.example`](../.env.example): credenciais,

API

-160 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por predefinição. Os endpoints protegidos exigem `Authorization: Bearer `, e os endpoints de sincronização mesh exigem uma `AGENTMEMORY_SECRET` explicitamente definida em ambos os pares. +161 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por predefinição. Os endpoints protegidos exigem `Authorization: Bearer `, e os endpoints de sincronização mesh exigem uma `AGENTMEMORY_SECRET` explicitamente definida em ambos os pares. **A autenticação está ativa por predefinição.** Quando `AGENTMEMORY_SECRET` não está definida na shell nem em `~/.agentmemory/.env`, o CLI gera um segredo aleatório no primeiro arranque em `~/.agentmemory/secret` e guarda uma cópia chamada `secret` no diretório de dados selecionado, com permissões `0600`. Todos os clientes incluídos o leem daí quando comunicam com um servidor local: o CLI, o visualizador, os hooks em `plugin/scripts`, o servidor MCP e o shim `@agentmemory/mcp`, as configurações escritas por `agentmemory connect`, e as integrações incluídas de OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. O segredo guardado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Uma `AGENTMEMORY_SECRET` explícita prevalece sempre, e os clientes remotos precisam de ter o segredo definido no seu ambiente. As implementações Docker self-host a partir do repositório e os entrypoints de `deploy/` geram e exportam o seu próprio segredo. Para chamar a API manualmente: diff --git a/READMEs/README.ro-RO.md b/READMEs/README.ro-RO.md index 61b5e7be6c..04f017c7a7 100644 --- a/READMEs/README.ro-RO.md +++ b/READMEs/README.ro-RO.md @@ -1154,7 +1154,7 @@ Referința completă [`.env.example`](../.env.example) include furnizori, filtre

API

-160 de endpoint-uri pe portul `3111`. API-ul REST se leagă implicit la `127.0.0.1`. Endpoint-urile protejate necesită `Authorization: Bearer `, iar endpoint-urile de sincronizare mesh necesită un `AGENTMEMORY_SECRET` setat explicit pe ambii parteneri (peers). +161 de endpoint-uri pe portul `3111`. API-ul REST se leagă implicit la `127.0.0.1`. Endpoint-urile protejate necesită `Authorization: Bearer `, iar endpoint-urile de sincronizare mesh necesită un `AGENTMEMORY_SECRET` setat explicit pe ambii parteneri (peers). **Autentificarea este activată implicit.** Dacă `AGENTMEMORY_SECRET` nu este setat, CLI-ul generează la prima pornire un secret aleatoriu în `~/.agentmemory/secret`, cu permisiuni `0600`, și îl copiază și în directorul de date selectat. Toți clienții incluși îl citesc de acolo când comunică cu un server local: CLI-ul, vizualizatorul, hook-urile din `plugin/scripts`, serverul MCP și shim-ul `@agentmemory/mcp`, configurațiile scrise de `agentmemory connect` și integrările incluse OpenCode, Pi, OpenClaw, Hermes și filesystem-watcher. Secretul stocat este trimis doar către URL-uri loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explicit are întotdeauna prioritate, iar clienții la distanță trebuie să seteze secretul în mediul lor. Implementările Docker self-host pornite din repository și entrypoint-urile `deploy/` își generează și exportă propriul secret. Pentru a apela API-ul manual: diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md index 8059674f2c..24a14be6e7 100644 --- a/READMEs/README.ru-RU.md +++ b/READMEs/README.ru-RU.md @@ -1160,7 +1160,7 @@ EMBEDDING_PROVIDER=local

API

-160 эндпоинтов на порту `3111`. REST API по умолчанию слушает на `127.0.0.1`. Защищённые эндпоинты требуют `Authorization: Bearer `, а эндпоинты mesh-синхронизации требуют явно заданного `AGENTMEMORY_SECRET` на обоих узлах. +161 эндпоинтов на порту `3111`. REST API по умолчанию слушает на `127.0.0.1`. Защищённые эндпоинты требуют `Authorization: Bearer `, а эндпоинты mesh-синхронизации требуют явно заданного `AGENTMEMORY_SECRET` на обоих узлах. **Аутентификация включена по умолчанию.** Если `AGENTMEMORY_SECRET` не задан, при первом запуске CLI создаёт случайный секрет в `~/.agentmemory/secret` с правами `0600` и копирует его также в выбранный каталог данных. Каждый встроенный клиент читает его оттуда, когда говорит с локальным сервером: CLI, просмотрщик, хуки из `plugin/scripts`, MCP-сервер и shim `@agentmemory/mcp`, конфиги, записанные `agentmemory connect`, и встроенные интеграции OpenCode, Pi, OpenClaw, Hermes и filesystem-watcher. Сохранённый секрет отправляется только на loopback-адреса (`localhost`, `127.0.0.0/8`, `::1`). Явно заданный `AGENTMEMORY_SECRET` всегда выигрывает, и удалённым клиентам он всё равно нужен. Docker и entrypoint'ы `deploy/` уже генерируют и экспортируют собственный секрет. Чтобы вызвать API вручную: diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.md index aad166cfeb..d0db673202 100644 --- a/READMEs/README.sv-SE.md +++ b/READMEs/README.sv-SE.md @@ -1168,7 +1168,7 @@ Den fullständiga referensen finns i [`.env.example`](../.env.example): autentis

API

-160 endpoints på port `3111`. REST API:et binder till `127.0.0.1` som standard. Skyddade endpoints kräver `Authorization: Bearer `, och mesh-synk-endpoints kräver en explicit satt `AGENTMEMORY_SECRET` på båda parterna. +161 endpoints på port `3111`. REST API:et binder till `127.0.0.1` som standard. Skyddade endpoints kräver `Authorization: Bearer `, och mesh-synk-endpoints kräver en explicit satt `AGENTMEMORY_SECRET` på båda parterna. **Autentisering är aktiverad som standard.** Om `AGENTMEMORY_SECRET` inte är angiven i skalet eller i `~/.agentmemory/.env` skapar CLI:n en slumpmässig hemlighet vid första starten i `~/.agentmemory/secret` och en kopia med namnet `secret` i den valda datamappen, med filbehörigheten `0600`. Alla medföljande klienter läser den därifrån när de ansluter till en lokal server: CLI:n, viewern, hookarna under `plugin/scripts`, MCP-servern och `@agentmemory/mcp`-shimmen, konfigurationerna skrivna av `agentmemory connect` samt de medföljande integrationerna för OpenCode, Pi, OpenClaw, Hermes och filsystemsbevakaren. Den lagrade hemligheten skickas bara till loopback-URL:er (`localhost`, `127.0.0.0/8`, `::1`). En explicit `AGENTMEMORY_SECRET` har alltid företräde; fjärrklienter behöver hemligheten i sin miljö. Docker-baserad self-hosting från repot och startpunkterna i `deploy/` genererar och exporterar en egen hemlighet. För att anropa API:et för hand: diff --git a/READMEs/README.th-TH.md b/READMEs/README.th-TH.md index 89d3fe06e1..382fa94078 100644 --- a/READMEs/README.th-TH.md +++ b/READMEs/README.th-TH.md @@ -1161,7 +1161,7 @@ EMBEDDING_PROVIDER=local

API

-160 endpoint บนพอร์ต `3111` REST API จะ bind กับ `127.0.0.1` โดย default endpoint ที่ป้องกันไว้ต้องมี `Authorization: Bearer ` และ endpoint ของ mesh sync ต้องตั้งค่า `AGENTMEMORY_SECRET` ไว้อย่างชัดเจนทั้งสองฝั่ง +161 endpoint บนพอร์ต `3111` REST API จะ bind กับ `127.0.0.1` โดย default endpoint ที่ป้องกันไว้ต้องมี `Authorization: Bearer ` และ endpoint ของ mesh sync ต้องตั้งค่า `AGENTMEMORY_SECRET` ไว้อย่างชัดเจนทั้งสองฝั่ง เปิดการยืนยันตัวตนตามค่าเริ่มต้น หากไม่ตั้ง `AGENTMEMORY_SECRET` CLI จะสร้างรหัสลับสุ่มครั้งแรกที่ `~/.agentmemory/secret` และคัดลอกไปยัง `secret` ในไดเรกทอรีข้อมูลที่เลือก โดยใช้สิทธิ์ `0600` ไคลเอนต์ที่รวมมาจะอ่านไฟล์หลักนี้ก่อนเมื่อเชื่อมต่อในเครื่อง และส่งรหัสลับที่บันทึกไว้เฉพาะ URL แบบ loopback ค่า `AGENTMEMORY_SECRET` ที่ระบุเองมีลำดับความสำคัญสูงกว่า ไคลเอนต์ระยะไกลต้องตั้งผ่าน environment ส่วน Docker สร้างรหัสลับของตนเอง diff --git a/READMEs/README.tl-PH.md b/READMEs/README.tl-PH.md index 1be8927702..3a2d75e8a7 100644 --- a/READMEs/README.tl-PH.md +++ b/READMEs/README.tl-PH.md @@ -1170,7 +1170,7 @@ Nasa [`.env.example`](../.env.example) ang buong reference, kasama ang provider,

API

-160 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer `, at kinakailangan ng mga mesh sync endpoint ang tahasang naka-set na `AGENTMEMORY_SECRET` sa dalawang peer. +161 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer `, at kinakailangan ng mga mesh sync endpoint ang tahasang naka-set na `AGENTMEMORY_SECRET` sa dalawang peer. Naka-on ang authentication bilang default. Kapag walang `AGENTMEMORY_SECRET`, gumagawa ang CLI ng random secret sa unang start sa `~/.agentmemory/secret` at kinokopya sa `secret` ng napiling data directory, na may mode `0600`. Inuuna ng bundled clients ang canonical file sa local connection at ipinapadala lang ang naka-save na secret sa loopback URL. Mas mataas ang prayoridad ng explicit na `AGENTMEMORY_SECRET`; dapat itong itakda ng remote clients sa environment. Gumagawa ang Docker deployment ng sarili nitong secret. diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md index 16210031f6..cfd2199581 100644 --- a/READMEs/README.tr-TR.md +++ b/READMEs/README.tr-TR.md @@ -1159,7 +1159,7 @@ Tam [`.env.example`](../.env.example) sağlayıcıları, kayıt filtrelerini, sa

API

-`3111` portunda 160 endpoint. REST API, varsayılan olarak `127.0.0.1`'e bağlanır. Korumalı endpoint'ler `Authorization: Bearer ` gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir `AGENTMEMORY_SECRET` gerektirir. +`3111` portunda 161 endpoint. REST API, varsayılan olarak `127.0.0.1`'e bağlanır. Korumalı endpoint'ler `Authorization: Bearer ` gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir `AGENTMEMORY_SECRET` gerektirir. **Kimlik doğrulama varsayılan olarak açıktır.** `AGENTMEMORY_SECRET` ayarlanmamışsa CLI ilk başlatmada `~/.agentmemory/secret` dosyasında `0600` izinleriyle rastgele bir sır oluşturur ve seçilen veri dizinine de kopyalar. Paketli istemciler yerel sunucuya bağlanırken buradan okur; secret yalnız loopback URL’lerine (`localhost`, `127.0.0.0/8`, `::1`) gönderilir. Uzak istemciler secret’ı kendi ortamında sağlamalıdır. Docker self-host ve `deploy/` kendi secret’larını üretir. API’yi elle çağırmak için: diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.md index cd76b1d0c0..8d0a86f27d 100644 --- a/READMEs/README.uk-UA.md +++ b/READMEs/README.uk-UA.md @@ -1160,7 +1160,7 @@ EMBEDDING_PROVIDER=local

API

-160 ендпоінтів на порту `3111`. REST API за замовчуванням прив'язується до `127.0.0.1`. Захищені ендпоінти вимагають `Authorization: Bearer `, а ендпоінти синхронізації mesh вимагають явно встановленого `AGENTMEMORY_SECRET` на обох сторонах. +161 ендпоінтів на порту `3111`. REST API за замовчуванням прив'язується до `127.0.0.1`. Захищені ендпоінти вимагають `Authorization: Bearer `, а ендпоінти синхронізації mesh вимагають явно встановленого `AGENTMEMORY_SECRET` на обох сторонах. **Автентифікацію ввімкнено типово.** Якщо `AGENTMEMORY_SECRET` не задано, під час першого запуску CLI створює випадковий секрет у `~/.agentmemory/secret` з правами `0600` і копіює його також у вибраний каталог даних. Вбудовані клієнти читають його звідти для локального сервера; secret надсилається лише на loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Віддалені клієнти мають отримати secret через власне середовище. Docker self-host і `deploy/` створюють власні секрети. Щоб викликати API вручну: diff --git a/READMEs/README.ur-PK.md b/READMEs/README.ur-PK.md index 2e204782a2..7dd119c2f5 100644 --- a/READMEs/README.ur-PK.md +++ b/READMEs/README.ur-PK.md @@ -1165,7 +1165,7 @@ EMBEDDING_PROVIDER=local

API

-پورٹ `3111` پر 160 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer ` درکار ہے، اور mesh sync اینڈ پوائنٹس کو دونوں peers پر واضح طور پر سیٹ کیا گیا `AGENTMEMORY_SECRET` درکار ہے۔ +پورٹ `3111` پر 161 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer ` درکار ہے، اور mesh sync اینڈ پوائنٹس کو دونوں peers پر واضح طور پر سیٹ کیا گیا `AGENTMEMORY_SECRET` درکار ہے۔ توثیق بطور طے شدہ فعال ہے۔ `AGENTMEMORY_SECRET` مقرر نہ ہو تو CLI پہلی بار بے ترتیب راز `~/.agentmemory/secret` میں محفوظ کرتا ہے اور منتخب ڈیٹا ڈائریکٹری کے `secret` میں اس کی نقل رکھتا ہے؛ اجازت `0600` ہوتی ہے۔ ساتھ آنے والے کلائنٹس مقامی رابطے میں اس اصل فائل کو ترجیح دیتے ہیں اور محفوظ راز صرف loopback URL کو بھیجتے ہیں۔ واضح `AGENTMEMORY_SECRET` مقدم ہے؛ دور کے کلائنٹس اسے environment میں مقرر کریں۔ Docker اپنا راز بناتا ہے۔ diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.md index 6ed5a261d8..15f51b849f 100644 --- a/READMEs/README.vi-VN.md +++ b/READMEs/README.vi-VN.md @@ -1170,7 +1170,7 @@ Tham chiếu đầy đủ ở [`.env.example`](../.env.example), gồm nhà cung

API

-160 endpoint trên port `3111`. REST API bind vào `127.0.0.1` theo mặc định. Các endpoint được bảo vệ cần `Authorization: Bearer `, và các endpoint mesh sync cần `AGENTMEMORY_SECRET` được đặt rõ ràng trên cả hai phía. +161 endpoint trên port `3111`. REST API bind vào `127.0.0.1` theo mặc định. Các endpoint được bảo vệ cần `Authorization: Bearer `, và các endpoint mesh sync cần `AGENTMEMORY_SECRET` được đặt rõ ràng trên cả hai phía. Xác thực bật mặc định. Nếu chưa đặt `AGENTMEMORY_SECRET`, CLI tạo bí mật ngẫu nhiên lần đầu tại `~/.agentmemory/secret` và sao chép vào `secret` trong thư mục dữ liệu đã chọn, với quyền `0600`. Client đi kèm ưu tiên tệp chính này khi kết nối cục bộ và chỉ gửi bí mật đã lưu đến URL loopback. `AGENTMEMORY_SECRET` đặt tường minh luôn được ưu tiên; client từ xa phải đặt qua biến môi trường. Triển khai Docker tạo bí mật riêng. diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md index db8a614f9e..43a5626759 100644 --- a/READMEs/README.zh-CN.md +++ b/READMEs/README.zh-CN.md @@ -1171,7 +1171,7 @@ EMBEDDING_PROVIDER=local

API

-端口 `3111` 上有 160 个端点。REST API 默认绑定到 `127.0.0.1`。受保护的端点需要 `Authorization: Bearer `,mesh 同步端点则需要双方都显式设置 `AGENTMEMORY_SECRET`。 +端口 `3111` 上有 161 个端点。REST API 默认绑定到 `127.0.0.1`。受保护的端点需要 `Authorization: Bearer `,mesh 同步端点则需要双方都显式设置 `AGENTMEMORY_SECRET`。 认证默认开启。未设置 `AGENTMEMORY_SECRET` 时,CLI 首次启动会将随机密钥保存到 `~/.agentmemory/secret`,并镜像到所选数据目录的 `secret`,权限为 `0600`。内置客户端连接本地服务器时优先读取该公共文件,只向回环 URL 发送保存的密钥。显式设置的 `AGENTMEMORY_SECRET` 优先;远程客户端需通过环境变量设置密钥。Docker 部署生成自己的密钥。 diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md index 23e9cf9a06..efea17a5d2 100644 --- a/READMEs/README.zh-TW.md +++ b/READMEs/README.zh-TW.md @@ -1163,7 +1163,7 @@ EMBEDDING_PROVIDER=local

API

-連接埠 `3111` 上有 160 個端點。REST API 預設綁定 `127.0.0.1`。受保護的端點需要 `Authorization: Bearer `,而網狀同步端點要求兩端都明確設定 `AGENTMEMORY_SECRET`。 +連接埠 `3111` 上有 161 個端點。REST API 預設綁定 `127.0.0.1`。受保護的端點需要 `Authorization: Bearer `,而網狀同步端點要求兩端都明確設定 `AGENTMEMORY_SECRET`。 驗證預設開啟。未設定 `AGENTMEMORY_SECRET` 時,CLI 首次啟動會將隨機密鑰儲存到 `~/.agentmemory/secret`,並鏡像到所選資料目錄的 `secret`,權限為 `0600`。內建客戶端連接本機伺服器時優先讀取此共用檔案,只向回環 URL 傳送儲存的密鑰。明確設定的 `AGENTMEMORY_SECRET` 優先;遠端客戶端需透過環境變數設定密鑰。Docker 部署會產生自己的密鑰。 diff --git a/docs/customizations/HOOK-TIMEOUT-2026-10-19.md b/docs/customizations/HOOK-TIMEOUT-2026-10-19.md index 7bf9f41803..21586d9575 100644 --- a/docs/customizations/HOOK-TIMEOUT-2026-10-19.md +++ b/docs/customizations/HOOK-TIMEOUT-2026-10-19.md @@ -27,7 +27,7 @@ - TDD: 기존 구현에서 새 회귀 4개 중 3개 실패/1개 통과를 확인했다. 실패는 전체 조회 불가 시 저장된 중복도 실패하는 것과 단건 조회 이전 전체 조회를 실행하는 것이었다. - 초기 green 실행의 fixture에는 검색 색인이 요구하는 facts/concepts/files가 빠져 2개 실패했다. fixture를 실제 소비 형식에 맞췄다. 제품 코드를 우회하지 않았다. -- 관련 observe/capture/훅 deadline 16파일 **160개 통과/0실패**. 첫 sandbox 실행은 136통과/11실패였으며 실패 기록을 보존했다. 동일 시험을 로컬 HTTP listener가 허용된 임시 HOME 환경에서 다시 실행해 160개 통과했다. 첫 JSON reporter의 오류는 STACK_TRACE_ERROR로 축약돼 있어 실패별 원인을 모두 단정하지 않는다. +- 관련 observe/capture/훅 deadline 16파일 **161개 통과/0실패**. 첫 sandbox 실행은 136통과/11실패였으며 실패 기록을 보존했다. 동일 시험을 로컬 HTTP listener가 허용된 임시 HOME 환경에서 다시 실행해 161개 통과했다. 첫 JSON reporter의 오류는 STACK_TRACE_ERROR로 축약돼 있어 실패별 원인을 모두 단정하지 않는다. - build 성공. `tsc --noEmit`은 기존과 같은 24개 진단으로 exit 2이며 새 진단 0개다. 타입 검사 전체 성공으로 보고하지 않는다. - 신규 회귀는 tool/prompt의 durable replay, 원문 무변경, 검색 색인 복구, live prompt ledger, 상한에 도달한 기존 기록의 중복 응답, 새 ID의 상한 유지, 단건 조회 오류의 실패 전파를 확인한다. - 전체 suite 및 실제 운영/Windows 훅은 이번 변경으로 재검증하지 않았다. diff --git a/docs/customizations/HOOK-UPSTREAM-20261102.md b/docs/customizations/HOOK-UPSTREAM-20261102.md index 07a276dd19..a30109387c 100644 --- a/docs/customizations/HOOK-UPSTREAM-20261102.md +++ b/docs/customizations/HOOK-UPSTREAM-20261102.md @@ -42,7 +42,7 @@ the README and twelve translations; no generated count was changed by hand. Website metadata now uses the same source-derived REST count as docs-sync's complete trigger-directory AST collector, rather than counting just three upstream trigger files and omitting personal endpoints. `npm run gen-meta` -regenerated metadata as 0.9.31-daniel.51, 55 tools, 160 REST endpoints, 12 hooks +regenerated metadata as 0.9.31-daniel.51, 55 tools, 161 REST endpoints, 12 hooks and 6300+ test cases. Unavailable live popularity requests retained their prior values. No website dependencies were installed and no website build was run. diff --git a/docs/customizations/NATIVE-RECOVERY-DANIEL58.md b/docs/customizations/NATIVE-RECOVERY-DANIEL58.md new file mode 100644 index 0000000000..27637fc011 --- /dev/null +++ b/docs/customizations/NATIVE-RECOVERY-DANIEL58.md @@ -0,0 +1,11 @@ +# Native SDK recovery review candidate + +Production reference: 0.9.32-daniel.55, Git commit `4605974f337a50ed7e0ef74e3bb635b6e5d5a805`. The .57 held-start changes are sourced from the separately preserved `3148e1d0a3df0241b69b2166085b10ed5979b99f` candidate. The .55 reference in this tree retains its original Git ancestry. + +The November 6 incident reproduced unbounded retries of stale lifecycle evidence after reboot, eight concurrent SDK bucket read timeouts, and recurring whole-inbox reads from the automatic Viewer health event. The fixes separate lifecycle reconciliation from transient startup failures, serialize SDK bucket reads with early failure, and keep automatic Viewer reporting off the full inbox path. Explicit inbox inspection remains available. + +The running .55 later held both memory and storage. Memory recovery in the candidate can release the memory hold after its existing stability period and a fresh check after the storage wait. The storage hold continues to block background work. Both holds remain in the crash record until a subsequent verified transition, so another cold boot must observe stable memory again. An administrator's storage recovery is a separate operation. + +On recovery from a storage hold, retained vector intent needs a durable resolution. A known SDK response and an intact backup are insufficient to confirm that the corresponding vector checkpoint reached disk. The candidate refuses explicit SDK recovery when it cannot establish an empty pending set. Disk-confirmed recovery and ordinary successful SDK operation retain their established contracts. + +Acceptance requires a release-specific execution closure, retention of the actual storage and memory holds on non-clean startup, and preservation of original vector intent. SDK completion does not establish disk persistence. The existing .55 guard, cold-copy manifest and TypeScript baseline are separate checks. The new version is a review candidate; applying a package directly to the installation is outside this procedure. See the project incident report for the verified operational epoch and test results. diff --git a/docs/customizations/SCOPED-HOLD-RECOVERY-57.md b/docs/customizations/SCOPED-HOLD-RECOVERY-57.md new file mode 100644 index 0000000000..19d744ac24 --- /dev/null +++ b/docs/customizations/SCOPED-HOLD-RECOVERY-57.md @@ -0,0 +1,7 @@ +# Scoped storage-hold recovery candidate (.57) + +This is an unissued candidate based on a preserved .55 source snapshot imported into a new local Git root; the import commit is not the original upstream or installed source commit. It does not authorize deployment. + +The candidate suppresses automatic Viewer inbox scanning, protects held vector startup, guards foreground vector writes, exposes storage hold and pending transitions, and rejects an unsafe compound partial release. It includes read-only uncertain capture inspection. It does not automatically release compound holds or reconcile uncertain originals. SDK acknowledgments are not disk-flush proof. + +Five focused files passed 73 tests in this isolated worktree using an empty temporary HOME and a 768 MiB cgroup. The full suite and actual worker integration have not been established. The current non-clean administrative recovery runtime and root execution closure remain unavailable; no deployment or enrollment has happened. Existing .56 enrollment was denied before execution with no local reason and has not been retried. Replace these personal changes only after equivalent upstream behavior, held-start preservation and recovery tests are established. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 9f324efae8..e4439a3386 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.55 +version: 0.9.32-daniel.58 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index baeb3c68ef..4b47bd42bb 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index dd6be503e6..e751076164 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 8dd109c630..5e73efd16a 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index f809afd7b0..f8fafbefe5 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.55 +version: 0.9.32-daniel.58 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 98751a2508..23c71719c5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 7889acb965..02b72ab9d3 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.55" + "@agentmemory/agentmemory": "0.9.32-daniel.58" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 7dcb2cadb1..a691428211 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index d836982238..be3557f709 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index 3aefe96fdc..bd882142e8 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.55" + "@agentmemory/mcp@0.9.32-daniel.58" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 0bd579176b..91b8a920ab 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 977a1ae530..cac1987cba 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index de03059905..6d9c8e03fe 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.55"; +const VERSION = "0.9.32-daniel.58"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.md index 10b5139a44..e66420190b 100644 --- a/plugin/skills/agentmemory-rest-api/REFERENCE.md +++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md @@ -5,7 +5,7 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run ` The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). Send `Authorization: Bearer `: the value of `AGENTMEMORY_SECRET`, or the one generated into `~/.agentmemory/secret` on first start when it is unset. Writes must use `Content-Type: application/json`. -160 registered endpoints: +161 registered endpoints: | Method | Path | | --- | --- | @@ -24,6 +24,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | POST | `/agentmemory/capture/drain` | | GET | `/agentmemory/capture/index-evidence` | | GET | `/agentmemory/capture/index-membership` | +| POST | `/agentmemory/capture/inspect-uncertain` | | GET | `/agentmemory/capture/jobs` | | POST | `/agentmemory/capture/jobs` | | POST | `/agentmemory/capture/jobs/stop` | diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index c8f54bd353..56a454377f 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.55", + "version": "0.9.32-daniel.58", "facts": { "mcpTools": [ "55" @@ -11,7 +11,7 @@ "7" ], "restEndpoints": [ - "160" + "161" ], "skills": [ "17" @@ -23,10 +23,10 @@ "6300+" ], "functions": [ - "353" + "355" ], "sourceFiles": [ - "280" + "281" ], "loc": [ "63000" diff --git a/scripts/personal-release/kit-runtime.py b/scripts/personal-release/kit-runtime.py index f288f8a5a1..ed975dbd9b 100644 --- a/scripts/personal-release/kit-runtime.py +++ b/scripts/personal-release/kit-runtime.py @@ -353,6 +353,8 @@ def dropin_bytes(self): native = ' --native-compat' if self.sdk_native_compat else '' native_stop = native + ' --data-dir ' + str(self.paths['data']) if self.sdk_native_compat else '' native_env = ('Environment="AGENTMEMORY_NATIVE_III_BIN=' + str(self.paths['engine']) + '"\nEnvironment="AGENTMEMORY_III_CONFIG=' + str(self.paths['data'] / 'iii-config.yaml') + '"\n') if self.sdk_native_compat else '' + if self.sdk_native_compat: + native_env += 'RestartPreventExitStatus=78\n' provider_env = 'Environment=\"AGENTMEMORY_LLM_PROVIDER=openai\"\n' if self.service_provider_selection else '' return ('[Service]\nExecStart=\nExecStart=/usr/bin/node ' + str(self.version / 'dist/cli.mjs') + ' --data-dir ' + str(self.paths['data']) + native + '\nExecStop=\nExecStop=/usr/bin/node ' + str(self.version / 'dist/cli.mjs') + ' stop' + native_stop + '\nExecStartPre=\nExecStartPre=/usr/bin/python3 -I -B ' + str(self.public / 'kit-runtime.py') + ' --guard\nEnvironment="AGENTMEMORY_FEEDBACK_DIR=' + str(self.paths['feedback']) + '"\nEnvironment="AGENTMEMORY_RECEIPT_DIR=' + str(self.receipt.parent) + '"\n' + native_env + provider_env).encode() diff --git a/scripts/personal-release/test_dashboard_kit.py b/scripts/personal-release/test_dashboard_kit.py index e0d23e22ff..048d04718c 100644 --- a/scripts/personal-release/test_dashboard_kit.py +++ b/scripts/personal-release/test_dashboard_kit.py @@ -1,3 +1,4 @@ +import hashlib import importlib.util import json import os @@ -144,6 +145,14 @@ def api(self, path, body=None): return {'control': {'pausedRequested': True, 'status': 'paused' if self.system.started else 'pausing', 'activeOperations': 0 if self.system.started else 3, 'error': None}} return {'sessions': [], 'flags': [], 'scheduleEnabled': False} + def test_only_native_units_suppress_restarts_for_unresolved_lifecycle(self): + self.assertNotIn(b'RestartPreventExitStatus=', self.tx.dropin_bytes()) + self.tx.sdk_native_compat = True + dropin = self.tx.dropin_bytes() + self.assertEqual([line for line in dropin.splitlines() if line.startswith(b'RestartPreventExitStatus=')], + [b'RestartPreventExitStatus=78']) + self.assertEqual(self.tx.post_files()[str(self.paths['dropin'])], hashlib.sha256(dropin).hexdigest()) + def test_reviewed_snapshot_enrolls_without_apply_and_entire_transaction_preserves_data(self): self.assertEqual(self.calls[0][4], '--enroll') self.assertFalse(any('systemctl' in item or item == '--apply' for item in self.calls[0])) diff --git a/src/capture/uncertain-inspection.ts b/src/capture/uncertain-inspection.ts new file mode 100644 index 0000000000..69d418d6fa --- /dev/null +++ b/src/capture/uncertain-inspection.ts @@ -0,0 +1,29 @@ +import {createHash} from 'node:crypto'; +import {isDeepStrictEqual} from 'node:util'; +import type {StateKV} from '../state/kv.js'; +import type {InboxRecord} from '../functions/capture.js'; +import type {CompressedObservation} from '../types.js'; +import {KV} from '../state/schema.js'; +import {isValidEventId} from './event-id.js'; +import {isCaptureKey} from './event-record.js'; +import {capturePayloadDigest} from './receipt-digest.js'; +import {sdkObservationMatches} from './sdk-source-restore.js'; +export type UncertainInspection={key:string;eventId:string;sourceDigest:string;project:string;sessionId:string;cwd:string;hookType:string;timestamp:string}; +export function validUncertainInspection(input:unknown):input is UncertainInspection{ + if(!input||typeof input!=='object'||Array.isArray(input))return false; + const x=input as Record,keys=['key','eventId','sourceDigest','project','sessionId','cwd','hookType','timestamp']; + return Object.keys(x).length===keys.length&&Object.keys(x).every(k=>keys.includes(k))&&isCaptureKey(x.key)&&typeof x.eventId==='string'&&isValidEventId(x.eventId)&&typeof x.sourceDigest==='string'&&/^[a-f0-9]{64}$/.test(x.sourceDigest)&&['project','sessionId','cwd','hookType','timestamp'].every(k=>typeof x[k]==='string'&&(x[k] as string).length>0&&(x[k] as string).length<=2048)&&Number.isFinite(Date.parse(x.timestamp as string)); +} +export async function inspectUncertainCapture(kv:StateKV,input:UncertainInspection){ + if(!validUncertainInspection(input))throw Error('INVALID_UNCERTAIN_INSPECTION'); + const result=(outcome:string)=>({outcome,readOnly:true,diskVerified:false,synced:false,originalReplay:false,retryAuthorized:false,atomicSnapshot:false}); + const rec=structuredClone(await kv.get(KV.captureInbox,input.key)); + if(!rec)return result('source_not_found'); + const derived='cap_'+createHash('sha256').update(`${rec.project}\0${rec.sessionId}\0${rec.eventId}`).digest('hex').slice(0,40); + if(rec.eventSource!=='client'||rec.key!==input.key||derived!==input.key||rec.eventId!==input.eventId||!rec.payload||rec.project!==input.project||rec.sessionId!==input.sessionId||rec.hookType!==input.hookType||rec.payload.project!==input.project||rec.payload.sessionId!==input.sessionId||rec.payload.cwd!==input.cwd||rec.payload.hookType!==input.hookType||rec.payload.timestamp!==input.timestamp||capturePayloadDigest(rec.payload)!==input.sourceDigest)return result('source_conflict'); + const read=()=>kv.get(KV.observations(rec.sessionId),rec.observationId); + const first=structuredClone(await read()),again=structuredClone(await read()),recAgain=structuredClone(await kv.get(KV.captureInbox,input.key)); + if(!isDeepStrictEqual(rec,recAgain)||!isDeepStrictEqual(first,again))return result('changed_during_inspection'); + if(!first)return result('observation_not_found'); + return result(sdkObservationMatches(first,rec.payload,rec.key,rec.observationId,rec.eventId)?'observation_matches':'observation_conflict'); +} diff --git a/src/cli.ts b/src/cli.ts index be7ad222bb..ee8a563a9a 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1389,16 +1389,20 @@ function nativeCompatPidMatches(pid: number, state: NativeEngineState): boolean } catch { return false; } } +class UnresolvedNativeLifecycleError extends Error { + readonly exitCode = 78; +} + function assertNativeCompatStartupOwnership(): void { const previous = readEngineState(); if (previous?.kind === "native" && previous.compatVersion && previous.workerIdentity) { const pinned = previous.workerIdentity; let sameWorker = false; try { sameWorker = nativeCompatWorkerIdentityMatches(pinned, pinned.pid, nativeWorkerIdentity(pinned.pid)); } catch {} - if (sameWorker) throw new Error("Unresolved prior lifecycle has a live pinned native worker; no process was started and state was preserved."); + if (sameWorker) throw new UnresolvedNativeLifecycleError("Unresolved prior lifecycle has a live pinned native worker; no process was started and state was preserved."); } if (existsSync(engineStatePath()) || existsSync(enginePidfilePath()) || existsSync(workerPidfilePath())) { - throw new Error("Unresolved prior lifecycle evidence must be reconciled before native startup; no process was started and state was preserved."); + throw new UnresolvedNativeLifecycleError("Unresolved prior lifecycle evidence must be reconciled before native startup; no process was started and state was preserved."); } } @@ -3894,7 +3898,8 @@ async function unknownCommand(): Promise { const handler = commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main); handler().catch(async (err) => { p.log.error(err instanceof Error ? err.message : String(err)); - const exitCode = await runStartupCleanup(1).catch(() => 1); + const failureCode = err instanceof UnresolvedNativeLifecycleError ? err.exitCode : 1; + const exitCode = await runStartupCleanup(failureCode).catch(() => 1); if (args.includes("--native-compat") && importedStartupWorker) { process.exitCode = exitCode; return; diff --git a/src/functions/capture.ts b/src/functions/capture.ts index 04b10dff34..56782c5f94 100644 --- a/src/functions/capture.ts +++ b/src/functions/capture.ts @@ -1,3 +1,4 @@ +import {inspectUncertainCapture,validUncertainInspection} from "../capture/uncertain-inspection.js"; import { committedSdkResolution } from '../capture/sdk-resolution-record.js'; import {recordAudit} from "./audit.js"; import {requireSdkSourceWriter,sameSdkSource,sdkObservationMatches,sdkSourceKeys,sdkSourceFailure,assertSdkSourceClaim,assertSdkSourceLegacyProtection} from "../capture/sdk-source-restore.js"; @@ -28,7 +29,7 @@ import { } from "../capture/event-record.js"; import { captureReviewPage, recordCaptureFailure, resolveCaptureReview, reviewHistory } from "../capture/review.js"; import { createCaptureRetryJobs } from "../capture/retry-jobs.js"; -import { backgroundTask, backgroundPaused } from "../ops/background-control.mjs"; +import { backgroundTask, backgroundPaused, backgroundControl } from "../ops/background-control.mjs"; import { restoreIndexEntries,extractImage } from "./observe.js"; import { prunePromptLedgers } from "../capture/prompt-ledger.js"; import { scrubRecord,normalizeCaptureData } from "./privacy.js"; @@ -57,6 +58,7 @@ export interface InboxRecord { sdkRestoreState?:"pending"|"completed"; sdkResolutionId?:string; sdkResolutionState?:'pending'|'committed'; + deferredByStorageHold?: true; key: string; eventId: string; eventSource: "client" | "server"; @@ -83,7 +85,7 @@ export type CaptureResult = | { status: "accepted"; state: "completed" | "sdk_completed"; eventId: string; observationId: string; attempts: number } | { status: "accepted"; state: "retrying"; eventId: string; observationId: string; attempts: number; nextAttemptAt: string; error: string } | { status: "duplicate"; state: "completed" | "sdk_completed" | InboxState; eventId: string; observationId?: string; deduplicated: true } - | { status: "rejected"; eventId: string; error: string; retryable: boolean; observationId?: string }; + | { status: "rejected"; eventId: string; error: string; retryable: boolean; observationId?: string; reconciliationRequired?: true }; export interface CapturePolicy { maxAttempts: number; @@ -222,7 +224,7 @@ export interface CaptureController { sweep(): Promise<{ processed: number; recovered: number; deadLettered: number }>; prune(): Promise; drainLocalSpool(): Promise; - status(): Promise; + status(options?: { scanInbox?: boolean }): Promise; setAutomaticRecoveryEnabled(value:boolean):ReturnType["setEnabled"]>; progress(): CaptureProgress; durability(): SentMark | null; @@ -348,7 +350,7 @@ export function registerCaptureFunctions( async function attempt(rec: InboxRecord): Promise { rec.cycleAttempts = (rec.cycleAttempts ?? rec.attempts) + 1; rec.attempts++; - type ObserveResult = { observationId?: string; deduplicated?: boolean; success?: boolean; error?: string }; + type ObserveResult = { observationId?: string; deduplicated?: boolean; success?: boolean; error?: string; retryable?: boolean }; let result = null as ObserveResult | null; let failure: string | null = null; try { @@ -382,6 +384,11 @@ export function registerCaptureFunctions( counters.duplicates++; return { status: "duplicate", state: "completed", eventId: rec.eventId, deduplicated: true }; } + if (!failure && result?.success === false && result.retryable === true && result.error === "vector_recovery_paused") { + rec.attempts = Math.max(0, rec.attempts - 1); + rec.cycleAttempts = Math.max(0, (rec.cycleAttempts ?? 1) - 1); + } + if (!failure && result?.success === false && result.retryable === true) failure = typeof result.error === "string" ? result.error : "observation_temporarily_unavailable"; const permanent = !failure; const message = failure ?? (result && typeof result.error === "string" ? result.error : "mem::observe returned no observation"); if (permanent || rec.cycleAttempts >= policy.maxAttempts) { @@ -392,14 +399,15 @@ export function registerCaptureFunctions( updateActiveInbox(rec.key, false); counters.deadLettered++; logger.warn("capture moved to dead letters", { eventId: rec.eventId, attempts: rec.attempts, error: message }); - return { status: "rejected", eventId: rec.eventId, error: message, retryable: false, observationId: rec.observationId }; + return { status: "rejected", eventId: rec.eventId, error: message, retryable: false, observationId: rec.observationId, ...(sdkCompletion && message === "vector_recovery_interrupted" ? {reconciliationRequired:true as const} : {}) }; } const nextAttemptAt = new Date(now.getTime() + backoffMs(rec.cycleAttempts, policy)).toISOString(); - const retrying: InboxRecord = { ...rec, status: "retrying", updatedAt: now.toISOString(), nextAttemptAt, lastError: message }; + const retrying: InboxRecord = { ...rec, status: "retrying", updatedAt: now.toISOString(), nextAttemptAt, lastError: message, ...(sdkCompletion && message === 'vector_recovery_paused' && result?.retryable === true ? {deferredByStorageHold:true as const} : {}) }; await recordCaptureFailure(kv,retrying); await kv.set(KV.captureInbox, rec.key, retrying); counters.retried++; logger.warn("capture processing failed, will retry", { eventId: rec.eventId, attempts: rec.attempts, nextAttemptAt, error: message }); + if (sdkCompletion && retrying.deferredByStorageHold) return { status: "rejected", eventId: rec.eventId, error: "capture_reconciliation_required", retryable: false, reconciliationRequired: true, observationId: rec.observationId }; return { status: "accepted", state: "retrying", eventId: rec.eventId, observationId: rec.observationId, attempts: rec.attempts, nextAttemptAt, error: message }; } @@ -414,6 +422,10 @@ export function registerCaptureFunctions( const payload = input.payload; const clientEventId = isValidEventId(input.eventId) ? input.eventId : undefined; const eventId = clientEventId ?? generateId("evs"); + const state = backgroundControl?.snapshot(); + if (sdkCompletion && state && (state.holds.includes("storage_error") || state.status === "resuming" || state.status === "initializing")) { + return { status: "rejected", eventId, error: "vector_recovery_paused", retryable: true }; + } const key = captureKey(payload.project, payload.sessionId, eventId); return withKeyedLock(`capture:${key}`, async () => { let storedObservationId: string | undefined; @@ -434,7 +446,7 @@ export function registerCaptureFunctions( const stored = await storedObservation(done); if (stored === undefined && done.observationId) throw new Error("capture_existing_observation_unavailable"); if (stored !== null) { - if (stored) await restoreIndexEntries(stored); + if (stored) await restoreIndexEntriesAdmitted(stored); counters.duplicates++; return { status: "duplicate", state: "completed", eventId, observationId: done.observationId, deduplicated: true }; } @@ -447,6 +459,11 @@ export function registerCaptureFunctions( } const queued = await kv.get(KV.captureInbox, key); if (queued) { + if (sdkCompletion && queued.lastError === "vector_recovery_interrupted") return { status: "rejected", eventId, error: "vector_recovery_interrupted", retryable: false, reconciliationRequired: true, observationId: queued.observationId }; + if (sdkCompletion && queued.deferredByStorageHold === true && queued.status === "retrying" && queued.lastError === "vector_recovery_paused") { + if (!clientEventId || queued.eventSource !== "client" || !sameSdkSource(queued.payload, payload)) return { status: "rejected", eventId, error: "capture_deferred_source_mismatch", retryable: false }; + return { status: "rejected", eventId, error: "capture_reconciliation_required", retryable: false, reconciliationRequired: true, observationId: queued.observationId }; + } counters.duplicates++; return { status: "duplicate", state: queued.status, eventId, observationId: queued.observationId, deduplicated: true }; } @@ -477,6 +494,14 @@ export function registerCaptureFunctions( }); } + async function restoreIndexEntriesAdmitted(observation: CompressedObservation): Promise { + if (!backgroundControl) return restoreIndexEntries(observation); + const result = await backgroundControl.runVectorWrite(() => restoreIndexEntries(observation)); + if (result && typeof result === "object" && "success" in result && result.success === false) { + throw Object.assign(new Error(result.error), { code: result.error }); + } + } + async function restoreSdkSource(input:{payload:HookPayload;eventId:string}) { const {payload,eventId}=input,key=captureKey(payload.project,payload.sessionId,eventId); const base={eventId,completion:'sdk',durable:false,sourceRestore:'sdk-v1'}; @@ -504,7 +529,7 @@ export function registerCaptureFunctions( if(!rec&&inboxSize!==null)inboxSize++; })); if(!alreadyPresent){const outcome:any=await sdk.trigger({function_id:'mem::observe',payload:{...payload,eventId,captureKey:key,observationId:id,sdkSourceRestore:{key,requestId}}});alreadyPresent=outcome?.deduplicated===true;} - else await restoreIndexEntries((await kv.get(KV.observations(payload.sessionId),id))!); + else await restoreIndexEntriesAdmitted((await kv.get(KV.observations(payload.sessionId),id))!); await recordAudit(kv,'capture_sdk_source_restore','mem::capture-restore-sdk',[key],{completion:'sdk',stage:'verify_pending'}); await kv.recoveryWrite!.exclusive(keys,async()=>{ await assertSdkSourceClaim(kv,{...payload,eventId,captureKey:key,observationId:id},{key,requestId});if(stopped)throw sdkSourceFailure('SDK_SOURCE_STOPPED'); @@ -529,6 +554,7 @@ export function registerCaptureFunctions( const stored=await kv.get(KV.captureInbox,key); if (!stored) return "gone"; const rec={...stored}; + if(rec.lastError==='vector_recovery_interrupted')return 'waiting'; if(rec.eventSource==='client'&&(await kv.get(eventScope(key),key))?.state==='deleted'){ await kv.delete(KV.captureInbox,key); if(inboxSize!==null)inboxSize=Math.max(0,inboxSize-1); @@ -697,10 +723,10 @@ export function registerCaptureFunctions( return results; } - async function status(): Promise { + async function status(options: { scanInbox?: boolean } = {}): Promise { await automaticRecovery.initialize().catch(()=>{}); let inbox: CaptureStatus["inbox"] = null; - try { + if (options.scanInbox !== false) try { const records = (await kv.list(KV.captureInbox)).filter(Boolean); refreshInbox(records); let sdkCompleted=0; @@ -737,6 +763,12 @@ export function registerCaptureFunctions( return { automaticRecovery:automaticRecovery.snapshot(),policy, inbox, legacyOutbox:await inspectOutbox(), progress:progress(), sinceStart: { ...counters }, lastSweepAt, lastPruneAt, lastBootDrain, spool }; } + sdk.registerFunction('mem::capture-inspect-uncertain', async (input: unknown) => { + if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('INVALID_UNCERTAIN_INSPECTION'); + const { _caller_worker_id, ...selection } = input as Record; + if ((_caller_worker_id !== undefined && typeof _caller_worker_id !== 'string') || !validUncertainInspection(selection)) throw new Error('INVALID_UNCERTAIN_INSPECTION'); + return inspectUncertainCapture(kv, selection); + }); sdk.registerFunction("mem::capture-restore-sdk",(input:{payload:HookPayload;eventId:string})=>trackWork(()=>backgroundTask(restoreSdkSource)(input))); sdk.registerFunction('mem::capture-reconcile-sdk',input=>{ const selection=sdkReconciliationInvocation(input); diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index b7248988d7..e37fdace2a 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/functions/status.ts b/src/functions/status.ts index 860f764f30..c0d0f4d82f 100644 --- a/src/functions/status.ts +++ b/src/functions/status.ts @@ -477,12 +477,12 @@ export function evaluateStatus(input: StatusInputs): StatusReport { }); } - if (input.capture === null) { + if (input.capture === null || input.capture?.inbox === null) { problems.push({ level: "info", code: "capture-check-unavailable", - message: "The capture inbox did not answer in time, so capture was not checked.", - fix: "The check runs again on the next status request. If it keeps timing out, the state store is overloaded: check the server log.", + message: "The capture inbox was not checked or did not answer in time.", + fix: "Use the explicit capture status request to inspect the inbox. If that request times out, check the server log.", }); } problems.push(...captureProblems(input.capture ?? null, input.now, input.ports.rest)); @@ -718,10 +718,10 @@ function indexPersistenceRows(report: StatusReport): string { "Vector storage", escapeHtml(`${plural(persistence.buckets, "bucket")}, ${plural(persistence.pendingChanges, "unsaved change")}`), ); - if (persistence.pendingLog !== undefined) { + if (persistence.pendingLog !== undefined || persistence.pendingLogKnown === false) { rows += row( "Pending vector log", - escapeHtml(plural(persistence.pendingLog, "vector change")) + + (persistence.pendingLogKnown === false || persistence.pendingLog === undefined ? "not checked" : escapeHtml(plural(persistence.pendingLog, "vector change"))) + `

${escapeHtml(PENDING_LOG_EXPLAINER)}

`, ); } diff --git a/src/index.ts b/src/index.ts index 7cd9e67ee2..21b847d8d2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -371,6 +371,8 @@ async function main() { operationalState.backgroundControl = control; controlBackgroundFunctions(sdk); } + let indexForExplicitResume: IndexPersistence | undefined; + let scheduleBackfillAfterResume: (() => Promise) | undefined; const pressure = persistentBackground ? lifecycle.track(createMemoryPressureGuard({ control })) : null; pressure?.install(sdk, (req) => checkAuth(req, secret)); operationalState.memoryPressure = pressure; @@ -565,7 +567,7 @@ async function main() { markKeywordRebuildPending(); registerApiTriggers(sdk, kv, secret, metricsStore, provider); registerDashboardUpdateApi(sdk, secret, createDashboardUpdates({requestRoot: runtimeMetadataPath("update-requests"), version: VERSION})); - if (persistentBackground) registerBackgroundControlApi(sdk, secret, control); + if (persistentBackground) registerBackgroundControlApi(sdk, secret, control, async () => { await bootGate; if (bootFailed || !indexForExplicitResume || !scheduleBackfillAfterResume) return false; if (!await indexForExplicitResume.resumeStorageRecovery(embeddingProvider?.dimensions ?? 0)) return false; return scheduleBackfillAfterResume(); }); if (getEnvVar("AGENTMEMORY_FEEDBACK_DIR")) { const feedback = lifecycle.track(registerFeedbackRuntime(sdk, secret, { root: getEnvVar("AGENTMEMORY_FEEDBACK_DIR"), @@ -585,7 +587,8 @@ async function main() { registerMcpEndpoints(sdk, kv, secret); const healthMonitor = resources.health = registerHealthMonitor(sdk, kv); - const indexPersistence = resources.index = new IndexPersistence(kv, vectorIndex, { requireRecoveryPlan: true }); + const indexPersistence = resources.index = new IndexPersistence(kv, vectorIndex, { requireRecoveryPlan: true, isStorageHeld: () => persistentBackground && (control.snapshot().holds.includes('storage_error') || kv.mutationOutcomeUncertain), storageGeneration: () => persistentBackground ? control.generation() : 0 }); + indexForExplicitResume = indexPersistence; setIndexPersistence(indexPersistence); const loaded = await indexPersistence.load().catch((err) => { @@ -681,8 +684,9 @@ async function main() { const auditMigration = trackBoot(startAuditMigration(kv).catch(() => {})); - const keywordStart = Date.now(); - try { + const rebuildAndScheduleVectorBackfill = async (vectorBackfillSince: string | null | undefined): Promise => { + const keywordStart = Date.now(); + try { const keyword = await rebuildKeywordIndex(kv, vectorBackfillSince); bootLog( `Rebuilt BM25 index from stored content (${keyword.documents} docs in ${Date.now() - keywordStart} ms)`, @@ -699,6 +703,12 @@ async function main() { } else if (vectorBackfillSince !== undefined) { setVectorBackfillState(keyword.fullBackfillPending > 0 && !optedIn ? "waiting-for-opt-in" : backlogScanComplete ? "idle" : "paused"); } + if (!backlogScanComplete) { + setVectorBackfillState("paused"); + activeIds.clear(); + for (const job of keyword.vectorJobs) job.revision?.release(); + return false; + } if (keyword.fullBackfillPending > 0) { bootLog(optedIn ? `Vector backfill has ${keyword.fullBackfillPending} additional documents beyond this start's limit; restart to resume.` @@ -741,7 +751,13 @@ async function main() { } catch (err) { setVectorBackfillState("paused"); console.warn(`[agentmemory] Failed to rebuild the BM25 index:`, err); + return false; } + return !indexPersistence.isRecoveryPaused(); + + }; + scheduleBackfillAfterResume = () => rebuildAndScheduleVectorBackfill(indexPersistence.recoveryCutoff()); + await rebuildAndScheduleVectorBackfill(vectorBackfillSince); // Ready / Endpoints lines are emitted via `bootLog` so they're // buffered in quiet mode and printed verbatim under --verbose. The @@ -751,7 +767,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 160 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 161 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, diff --git a/src/ops/background-control.d.mts b/src/ops/background-control.d.mts index 3dda066908..1441e9740f 100644 --- a/src/ops/background-control.d.mts +++ b/src/ops/background-control.d.mts @@ -5,18 +5,20 @@ export interface BackgroundControl { init(store:StateKV,finish?:()=>Promise):Promise; snapshot():{formatVersion:2;holds:string[];recovery:{attempts:number;nextAttemptAt:number;maxAttempts:number};status:string;pausedRequested:boolean;activeOperations:number;error:string|null;diagnostics:unknown;transition:unknown}; isPaused():boolean; + generation():number; run(fn:()=>Promise):Promise; + runVectorWrite(fn:()=>Promise):Promise; infer(fn:()=>Promise):Promise; - change(action:"pause"|"resume",options?:{source?:"manual"|"deployment"|"memory";canResume?:()=>Promise}):Promise>; + change(action:"pause"|"resume",options?:{source?:"manual"|"deployment"|"memory";canResume?:()=>Promise;beforeResume?:()=>Promise}):Promise>; commitCleanShutdown():Promise<{success:boolean;paused:boolean}>; settled():Promise; } export const MEMORY_RECOVERY_MAX_ATTEMPTS:number; export let backgroundControl:BackgroundControl|null; export function createBackgroundControl(options?:{clock?:()=>number}):BackgroundControl; -export function installBackgroundControl(control:BackgroundControl):void; +export function installBackgroundControl(control:BackgroundControl,onExplicitResume?:()=>Promise):void; export function backgroundPaused():boolean; export function backgroundTaskunknown>(fn:T):T; export function controlBackgroundFunctions(sdk:IIIClient):void; export function backgroundViewerRequestAllowed(req:HttpRequest):boolean; -export function registerBackgroundControlApi(sdk:IIIClient,secret:string,control:BackgroundControl):void; +export function registerBackgroundControlApi(sdk:IIIClient,secret:string,control:BackgroundControl,onExplicitResume?:()=>Promise):void; diff --git a/src/ops/background-control.mjs b/src/ops/background-control.mjs index d03015228e..d2cab85550 100644 --- a/src/ops/background-control.mjs +++ b/src/ops/background-control.mjs @@ -14,16 +14,16 @@ export const backgroundTask=fn=>(...args)=>backgroundControl?backgroundControl.r export function createBackgroundControl({clock=Date.now}={}){ const context=new AsyncLocalStorage(),active=new Set(); let kv,drain=async()=>{},status='initializing',requested=true,error=null,diagnostics=null,completion=null,changes=Promise.resolve(); - let transition=null,holds=new Set(),revision=0,recovery={attempts:0,nextAttemptAt:0}; + let transition=null,holds=new Set(),revision=0,storageRevision=0,transitionsPending=0,recovery={attempts:0,nextAttemptAt:0}; const record=(paused,resumePending,remaining=holds)=>({version:2,paused,resumePending,holds:[...remaining].sort(),recovery:{...recovery}}); const writeRecord=(paused,resumePending,remaining)=>kv.set(NAMESPACE,'manual-pause',record(paused,resumePending,remaining)); - const snapshot=()=>({formatVersion:2,holds:[...holds].sort(),recovery:{...recovery,maxAttempts:MEMORY_RECOVERY_MAX_ATTEMPTS},status,pausedRequested:requested,activeOperations:active.size,error,diagnostics, - transition:transition?{...transition,elapsedMs:Math.max(0,(transition.completedAt??clock())-transition.startedAt),stageElapsedMs:Math.max(0,(transition.completedAt??clock())-transition.stageStartedAt)}:null}); - function begin(action){transition={action,stage:'request',startedAt:clock(),stageStartedAt:clock()};error=null;diagnostics=null;} + const snapshot=()=>({formatVersion:2,holds:[...holds].sort(),recovery:{...recovery,maxAttempts:MEMORY_RECOVERY_MAX_ATTEMPTS},status:holds.has('storage_error')?'error':status,pausedRequested:requested,activeOperations:active.size,error:holds.has('storage_error')?'background_storage_unavailable':error,diagnostics:holds.has('storage_error')?(diagnostics??{errorCode:'BACKGROUND_STORAGE_HOLD_RETAINED'}):diagnostics, + transition:transition?{...transition,pending:transitionsPending>0||!!completion,elapsedMs:Math.max(0,(transition.completedAt??clock())-transition.startedAt),stageElapsedMs:Math.max(0,(transition.completedAt??clock())-transition.stageStartedAt)}:null}); + function begin(action){transition={action,stage:'request',startedAt:clock(),stageStartedAt:clock()};if(!holds.has('storage_error')){error=null;diagnostics=null;}} function stage(value){transition.stage=value;transition.stageStartedAt=clock();if(value==='complete')transition.completedAt=clock();} const safeCode=value=>typeof value==='string'&&/^[A-Za-z0-9_.:-]{1,80}$/.test(value)?value:null; function fail(e){ - holds.add('storage_error');requested=true;status='error';error='background_storage_unavailable';if(transition)transition.completedAt=clock(); + revision++;storageRevision++;holds.add('storage_error');requested=true;status='error';error='background_storage_unavailable';if(transition)transition.completedAt=clock(); const details=e?.diagnostics??{}; diagnostics={errorCode:safeCode(e?.code)??'BACKGROUND_STORAGE_UNAVAILABLE',causeCode:safeCode(details.errorCode),stage:safeCode(details.stage)??transition?.stage??'request'}; for(const name of ['category','phase'])if(safeCode(details[name]))diagnostics[name]=details[name]; @@ -53,7 +53,7 @@ export function createBackgroundControl({clock=Date.now}={}){ await drain(); await persist(); await writeRecord(true,false);await confirmPauseRecord(); - status='paused';error=null;diagnostics=null;stage('complete'); + status='paused';if(!holds.has('storage_error')){error=null;diagnostics=null;}stage('complete'); })().catch(async e=>{fail(e);try{await writeRecord(true,true);await confirmPauseRecord(false);}catch{}}).finally(()=>{completion=null;}); } return { @@ -71,19 +71,31 @@ export function createBackgroundControl({clock=Date.now}={}){ await writeRecord(false,true);await confirmPauseRecord(false); requested=false;status='running'; }else{requested=true;status='paused';} - },snapshot,isPaused:()=>requested, + },snapshot,isPaused:()=>requested,generation:()=>storageRevision, run(fn){return requested?Promise.resolve(deferred()):track(fn);}, + runVectorWrite(fn){ + const blocked=()=>holds.has('storage_error')||status==='resuming'||status==='initializing'; + const denied=()=>({success:false,error:'vector_recovery_paused',retryable:true}); + if(blocked())return Promise.resolve(denied()); + const admitted=storageRevision; + return track(async()=>{ + if(blocked())return denied(); + try{const result=await fn();if(storageRevision!==admitted||holds.has('storage_error'))return{success:false,error:'vector_recovery_interrupted',partial:true,retryable:false,result};return result;} + catch(error){if(storageRevision!==admitted||holds.has('storage_error')||error?.code==='VECTOR_RECOVERY_PAUSED')return{success:false,error:'vector_recovery_interrupted',partial:true,retryable:false};throw error;} + }); + }, infer(fn){ // An admitted task finishes its current unit, including any subsequent writes. if(context.getStore()?.active)return Promise.resolve().then(fn); if(requested)return Promise.reject(Object.assign(Error('background_paused'),{providerUnavailable:true,code:'BACKGROUND_PAUSED'})); return track(fn); }, - change(action,{source='manual',canResume}={}){ + change(action,{source='manual',canResume,beforeResume}={}){ if(!['manual','deployment','memory'].includes(source)||!['pause','resume'].includes(action))return Promise.reject(Error('invalid_background_action')); // Close admission at request time, including while another transition awaits disk. const requestRevision=revision,added=action==='pause'&&!holds.has(source); if(action==='pause'){holds.add(source);requested=true;revision++;} + transitionsPending++; const operation=changes.then(async()=>{ if(action==='pause'){ if((status==='paused'||status==='pausing')&&!added)return snapshot(); @@ -93,14 +105,20 @@ export function createBackgroundControl({clock=Date.now}={}){ catch(e){fail(e);throw Error(error);} }else{ if(revision!==requestRevision)return snapshot(); - if(status==='pausing'||completion)throw Error('background_draining'); + if(status==='pausing'||completion||(beforeResume&&active.size))throw Error('background_draining'); const automatic=source==='memory'; - if(automatic&&(status!=='paused'||holds.size!==1||!holds.has('memory')||recovery.attempts>=MEMORY_RECOVERY_MAX_ATTEMPTS||clock()=MEMORY_RECOVERY_MAX_ATTEMPTS||clock(){});return operation; + const tracked=operation.finally(()=>{transitionsPending--;});changes=tracked.catch(()=>{});return tracked; },commitCleanShutdown(){ // The caller must first stop ingress/producers and verify the full disk fence. const operation=changes.then(async()=>{ @@ -155,15 +186,22 @@ export function createBackgroundControl({clock=Date.now}={}){ } const INFERENCE_FUNCTIONS=new Set(['mem::session-finalize','mem::summary-recover','mem::summary-repair','mem::compression-retry','mem::summarize','mem::compress','mem::graph-extract','mem::consolidate','mem::consolidate-pipeline','mem::reflect','mem::slot-reflect','mem::flow-compress','mem::crystallize','mem::skill-extract','mem::enrich-window','mem::temporal-graph-extract','mem::compress-file','mem::expand-query','mem::snapshot-create']); +const FOREGROUND_VECTOR_WRITES=new Set(['mem::import','mem::replay::import-jsonl','mem::observe','mem::remember','mem::forget','mem::evolve','mem::evict','mem::snapshot-restore','mem::retention-evict','mem::auto-forget','mem::governance-delete','mem::governance-bulk']); export function controlBackgroundFunctions(sdk){ const register=sdk.registerFunction.bind(sdk); - sdk.registerFunction=(id,handler,...rest)=>register(id,INFERENCE_FUNCTIONS.has(id)?backgroundTask(handler):handler,...rest); + sdk.registerFunction=(id,handler,...rest)=>{ + if(FOREGROUND_VECTOR_WRITES.has(id)){ + const guarded=(...args)=>backgroundControl?backgroundControl.runVectorWrite(()=>handler(...args)):handler(...args); + return register(id,guarded,...rest); + } + return register(id,INFERENCE_FUNCTIONS.has(id)?backgroundTask(handler):handler,...rest); + }; } export function backgroundViewerRequestAllowed(req){ return req.headers?.['x-agentmemory-background']==='1'&&/^application\/json(?:;|$)/i.test(req.headers?.['content-type']||'')&&!['cross-site','same-site'].includes(req.headers?.['sec-fetch-site']); } -export function registerBackgroundControlApi(sdk,secret,control){ +export function registerBackgroundControlApi(sdk,secret,control,onExplicitResume){ function auth(req){ if(!secret)return{status_code:503,body:{error:'background_control_requires_authentication'}}; const a=Buffer.from(req.headers?.authorization||req.headers?.Authorization||''),b=Buffer.from('Bearer '+secret); @@ -177,8 +215,11 @@ export function registerBackgroundControlApi(sdk,secret,control){ if(!backgroundViewerRequestAllowed(req))return{status_code:403,body:{error:'background_control_marker_required'}}; const body=req.body; if(!body||Array.isArray(body)||Object.keys(body).some(k=>!['action','reason'].includes(k))||body.reason!==undefined&&body.reason!=='deployment'||!['pause','resume'].includes(body.action))return{status_code:400,body:{error:'invalid_background_action'}}; - try{return{status_code:202,body:{success:true,control:await control.change(body.action,{source:body.reason??'manual'})}};} - catch(e){return{status_code:e.message==='background_draining'?409:503,body:{success:false,error:e.message==='background_draining'?'background_draining':'background_storage_unavailable',control:control.snapshot()}};} + try{ + const snapshot=await control.change(body.action,{source:body.reason??'manual',...(body.action==='resume'&&onExplicitResume?{beforeResume:onExplicitResume}:{})}); + return{status_code:202,body:{success:true,control:snapshot,...(body.action==='resume'&&snapshot.status==='running'&&onExplicitResume?{vectorRecovery:'replay_complete_backfill_pending'}:{})}}; + } + catch(e){const conflict=['background_draining','background_storage_recovery_requires_full_resume'].includes(e?.message);return{status_code:conflict?409:503,body:{success:false,error:e?.code==='VECTOR_RECOVERY_UNAVAILABLE'?'vector_recovery_unavailable':conflict?e.message:'background_storage_unavailable',control:control.snapshot()}};} }); sdk.registerTrigger({type:'http',function_id:id,config:{api_path:'/agentmemory/background/control',http_method:method,middleware_function_ids:['middleware::api-auth']}}); } diff --git a/src/ops/memory-pressure.mjs b/src/ops/memory-pressure.mjs index 7c5fe4b5b8..fee580b5bf 100644 --- a/src/ops/memory-pressure.mjs +++ b/src/ops/memory-pressure.mjs @@ -36,7 +36,8 @@ export function createMemoryPressureGuard({control,readSample=readHostMemory,sch if(pendingRecovery){state.recoveryStatus='recovering';return;} const c=control.snapshot(); if(!c.holds?.includes('memory')){state.recoveryStatus='observing';return;} - if(c.holds.length!==1||c.status==='error'){state.recoveryStatus='held';return;} + const memoryWithStorage=c.holds.length===2&&c.holds.includes('storage_error'); + if(!memoryWithStorage&&(c.holds.length!==1||c.status==='error')){state.recoveryStatus='held';return;} if(c.recovery.attempts>=c.recovery.maxAttempts){state.recoveryStatus='attempt_limit';return;} if(now number; requireRecoveryPlan?: boolean; + isStorageHeld?: () => boolean; + storageGeneration?: () => number; }; export interface IndexLegStatus { @@ -110,6 +112,7 @@ export interface IndexPersistenceStatus { vector: IndexLegStatus | null; vectorCountShortfall: VectorCountShortfall | null; pendingLog?: number; + pendingLogKnown?: boolean; pendingLogAcknowledged?: number; pendingLogError?: string | null; } @@ -179,13 +182,19 @@ function isPersistedVector(row: unknown): row is PersistedVector { return typeof candidate.id === "string" && typeof candidate.s === "string" && typeof candidate.e === "string"; } -async function inBatches(items: T[], size: number, run: (item: T) => Promise): Promise { +async function inBatches( + items: T[], + size: number, + run: (item: T) => Promise, + stopOnFailure = false, +): Promise { const failures: unknown[] = []; for (let offset = 0; offset < items.length; offset += size) { const results = await Promise.allSettled(items.slice(offset, offset + size).map(run)); for (const result of results) { if (result.status === "rejected") failures.push(result.reason); } + if (stopOnFailure && failures.length > 0) break; } return failures; } @@ -219,6 +228,12 @@ export class IndexPersistence { private readonly saveIntervalMs: number; private readonly bucketSize: number; private readonly now: () => number; + private readonly isStorageHeld: () => boolean; + private readonly storageGeneration: () => number; + private bootStorageGeneration: number; + private storageBlocked = false; + private storageResume: Promise | null = null; + private storageRecovering = false; private bucketOfId: Map = new Map(); private bucketCounts: Map = new Map(); // Retain the original address until the deletion is certified on disk. @@ -232,6 +247,7 @@ export class IndexPersistence { private logChains: Map> = new Map(); private logSuppressed = false; private pendingLogUnknown = false; + private pendingLogInspected = false; private pendingLogError: string | null = null; private earlySaveQueued = false; private backfillQueue: Promise = Promise.resolve(); @@ -248,7 +264,12 @@ export class IndexPersistence { options: IndexPersistenceOptions = {}, ) { this.recoveryReady = !options.requireRecoveryPlan || !vector; + this.pendingLogInspected = !options.requireRecoveryPlan || !vector; + this.isStorageHeld = options.isStorageHeld ?? (() => false); + this.storageGeneration = options.storageGeneration ?? (() => 0); + this.bootStorageGeneration = this.storageGeneration(); this.vector?.setChangeListener((id, entry) => this.logChange(id, entry)); + this.vector?.setMutationGuard(() => { if (!this.logSuppressed && (this.isStorageHeld() || this.storageBlocked || this.storageRecovering || this.storageGeneration() !== this.bootStorageGeneration)) throw Object.assign(new Error('VECTOR_RECOVERY_PAUSED'), { code: 'VECTOR_RECOVERY_PAUSED' }); }); this.now = options.now ?? Date.now; const interval = options.saveIntervalMs; this.saveIntervalMs = @@ -339,8 +360,9 @@ export class IndexPersistence { pendingChanges: this.vector?.pendingChanges ?? 0, vector: this.vector ? { ...this.leg } : null, vectorCountShortfall: this.vectorCountShortfall, - pendingLog: this.vector ? this.pendingLog.size : 0, - pendingLogAcknowledged: this.vector ? this.acknowledgedLog.size : 0, + pendingLog: this.pendingLogInspected && !this.pendingLogUnknown ? this.pendingLog.size : undefined, + pendingLogKnown: this.pendingLogInspected && !this.pendingLogUnknown, + pendingLogAcknowledged: this.pendingLogInspected && !this.pendingLogUnknown ? this.acknowledgedLog.size : undefined, pendingLogError: this.pendingLogError, }; } @@ -348,17 +370,36 @@ export class IndexPersistence { async replayPendingLog(expectedDimensions = 0): Promise { const result: PendingReplayResult = { entries: 0, added: 0, removed: 0, cleared: false, skipped: 0 }; const vector = this.vector; - if (!vector || this.recoveryError) return result; + if (!vector || this.blockIfStorageHeld() || this.recoveryError) return result; let rows: unknown[]; try { rows = await this.kv.list(KV.vectorPendingLog); } catch (err) { this.pendingLogUnknown = true; this.pendingLogError = errorMessage(err); + this.pauseRecovery(new Error("Pending vector log read failed")); logger.warn("index persistence: could not read the pending vector log", { message: this.pendingLogError }); return result; } + if (this.blockIfStorageHeld()) return result; + this.pendingLogInspected = true; + if (!Array.isArray(rows) || rows.some(row => !isPendingVectorRow(row))) { + this.pendingLogUnknown = true; + this.pauseRecovery(new Error('Pending vector log contains invalid records')); + return result; + } const valid = (Array.isArray(rows) ? rows : []).filter(isPendingVectorRow).sort((a, b) => a.q - b.q); + for (const row of valid) { + if (row.c === 1 || row.t === 1) continue; + try { + const decoded = base64ToFloat32(row.e!); + if (Buffer.from(row.e!, 'base64').toString('base64') !== row.e || !decoded.length || (expectedDimensions > 0 && decoded.length !== expectedDimensions) || decoded.some(value => !Number.isFinite(value))) throw new Error('invalid vector'); + } catch { + this.pendingLogUnknown = true; + this.pauseRecovery(new Error('Pending vector log contains invalid embeddings')); + return result; + } + } this.logSuppressed = true; try { for (const row of valid) { @@ -416,8 +457,9 @@ export class IndexPersistence { markBackfillSince(since: string | null): Promise { this.backfillRevision++; return this.queueBackfillChange(async () => { - if (!this.vector || (since !== null && !Number.isFinite(Date.parse(since)))) return; + if (!this.vector || this.blockIfStorageHeld() || (since !== null && !Number.isFinite(Date.parse(since)))) return; const current = await this.readBackfillMarker(); + if (this.blockIfStorageHeld()) throw new Error('Storage hold prevents vector recovery'); const next = earliestBackfillSince(current, this.backfillSince, since)!; if (current !== next) await this.kv.set(KV.bm25Index, BACKFILL_MARKER_KEY, { v: 2, since: next }); this.backfillSince = next; @@ -443,8 +485,70 @@ export class IndexPersistence { logger.warn(this.recoveryError); } + private blockIfStorageHeld(): boolean { + if (!this.isStorageHeld() && this.storageGeneration() === this.bootStorageGeneration) return false; + this.storageBlocked = true; + if (!this.recoveryError) this.pauseRecovery(new Error('Storage hold prevents vector recovery')); + return true; + } + + recoveryCutoff(): string | null | undefined { return this.backfillSince; } + + resumeStorageRecovery(expectedDimensions = 0): Promise { + if (this.storageResume) return this.storageResume; + this.storageRecovering = true; + const work = this.resumeStorageRecoveryOnce(expectedDimensions).finally(() => { this.storageRecovering = false; this.storageResume = null; }); + this.storageResume = work; + return work; + } + + private async requireEmptySdkPendingLog(): Promise { + const rows = await this.kv.list(KV.vectorPendingLog); + if (!Array.isArray(rows) || rows.length > 0 || this.pendingLog.size > 0 || this.logChains.size > 0) { + throw new Error('Pending vector records require durable reconciliation before SDK recovery'); + } + } + + private async resumeStorageRecoveryOnce(expectedDimensions: number): Promise { + if (this.stopped || this.isStorageHeld()) return false; + const generation = this.storageGeneration(); + const sdkRecovery = this.kv.durability?.completion === 'sdk' && + (this.storageBlocked || generation !== this.bootStorageGeneration); + if (!sdkRecovery && !this.vector) return true; + if (!sdkRecovery && !this.storageBlocked) return !this.isRecoveryPaused(); + try { + if (sdkRecovery) await this.requireEmptySdkPendingLog(); + if (this.isStorageHeld() || generation !== this.storageGeneration()) throw new Error('Storage hold changed during vector recovery'); + this.bootStorageGeneration = generation; + this.storageBlocked = false; + this.recoveryError = null; + if (!this.vector) return true; + const loaded = await this.load(); + if (this.blockIfStorageHeld() || !loaded || loaded.state === 'unavailable') throw new Error('Persisted vector checkpoint is unavailable'); + if (loaded.vector && expectedDimensions > 0 && loaded.vector.validateDimensions(expectedDimensions).mismatches.length) throw new Error('Persisted vector dimensions mismatch'); + // SDK checkpoint reads may span minutes. Recheck before the first backfill write. + if (sdkRecovery) { + await this.requireEmptySdkPendingLog(); + this.pendingLogInspected = true; + this.pendingLogUnknown = false; + } + await this.prepareBackfill(loaded); + if (this.blockIfStorageHeld() || this.isRecoveryPaused()) { this.storageBlocked = true; return false; } + if (loaded.vector && loaded.vector.size > 0) this.vector.restoreFrom(loaded.vector); + if (!sdkRecovery) await this.replayPendingLog(expectedDimensions); + if (this.blockIfStorageHeld() || this.isRecoveryPaused()) { this.storageBlocked = true; return false; } + this.pendingLogError = null; + this.leg.lastError = null; this.leg.lastErrorAt = null; + return true; + } catch (error) { + this.storageBlocked = true; + if (sdkRecovery || !this.recoveryError) this.pauseRecovery(error); + return false; + } + } + async prepareBackfill(loaded: VectorLoadResult | null, forceFull = false): Promise { - if (!this.vector || this.recoveryError) return undefined; + if (!this.vector || this.blockIfStorageHeld() || this.recoveryError) return undefined; if (!loaded || loaded.state === "unavailable") { this.pauseRecovery(new Error("Persisted vector checkpoint is unavailable")); return undefined; @@ -457,7 +561,9 @@ export class IndexPersistence { throw new Error("Invalid persisted vector recovery cutoff"); } await this.markBackfillSince(earliestBackfillSince(since, fallback)!); + if (this.blockIfStorageHeld() || this.recoveryError) return undefined; const marker = await this.readBackfillMarker(); + if (this.blockIfStorageHeld() || this.recoveryError) return undefined; this.recoveryReady = true; this.scheduleSave(); return marker; @@ -533,7 +639,7 @@ export class IndexPersistence { } private logChange(id: string | null, entry: VectorEntry | null): void { - if (this.logSuppressed || !this.recoveryReady || this.recoveryError) return; + if (this.logSuppressed || this.blockIfStorageHeld() || !this.recoveryReady || this.recoveryError) return; const key = id ?? PENDING_CLEAR_KEY; const q = this.nextSeq(); let row: PendingVectorRow; @@ -553,6 +659,7 @@ export class IndexPersistence { this.pendingLog.set(key, q); this.acknowledgedLog.delete(key); this.enqueueLog(key, async () => { + if (this.blockIfStorageHeld()) throw new Error('Storage hold prevents vector log write'); await this.kv.set(KV.vectorPendingLog, key, row); if (this.pendingLog.get(key) === q) this.acknowledgedLog.set(key, q); }).then( @@ -594,6 +701,7 @@ export class IndexPersistence { private deletePendingKey(key: string, q: number | undefined): Promise { return this.enqueueLog(key, async () => { if (this.pendingLog.get(key) !== q) return; + if (this.blockIfStorageHeld()) throw new Error('Storage hold prevents vector log deletion'); await this.kv.delete(KV.vectorPendingLog, key); if (this.pendingLog.get(key) === q) { this.pendingLog.delete(key); @@ -621,6 +729,7 @@ export class IndexPersistence { } async load(): Promise { + if (this.blockIfStorageHeld()) return { vector: null, state: 'unavailable', savedAt: null }; if (!this.vector) { await this.finishLegacyCleanup(); return { vector: null, state: "none", savedAt: null }; @@ -634,8 +743,11 @@ export class IndexPersistence { return { vector: null, state: "unavailable", savedAt: null }; } + if (this.blockIfStorageHeld()) return { vector: null, state: 'unavailable', savedAt: null }; + if (meta && meta.v === 3 && Number.isInteger(meta.bucketCount) && meta.bucketCount >= 0) { const loaded = await this.loadBuckets(meta.bucketCount); + if (this.blockIfStorageHeld()) return { vector: null, state: 'unavailable', savedAt: null }; if (!loaded) return { vector: null, state: "unavailable", savedAt: null }; this.hasVectorCheckpoint = loaded.size > 0; this.checkpointBackfillSince = meta.backfillSince; @@ -725,7 +837,7 @@ export class IndexPersistence { private async runSave(): Promise { const vector = this.vector; - if (!vector || this.isRecoveryPaused()) return; + if (!vector || this.blockIfStorageHeld() || this.isRecoveryPaused()) return; if (!vector.pendingChanges && !this.needsRecoveryCheckpoint()) return; const hasVectorChanges = vector.pendingChanges > 0; const epoch = this.dirtyEpoch; @@ -737,6 +849,7 @@ export class IndexPersistence { const coveredSeq = this.seq; try { await this.writeChanges(vector); + if (this.blockIfStorageHeld()) return; await this.clearCoveredPendingLog(coveredSeq).catch((err) => { this.pendingLogError = errorMessage(err); this.logFailure(err); @@ -820,7 +933,9 @@ export class IndexPersistence { const bucketOfId = new Map(); const bucketCounts = new Map(); const bucketIds = Array.from({ length: bucketCount }, (_, bucket) => bucket); - const failures = await inBatches(bucketIds, LOAD_CONCURRENCY, async (bucket) => { + // SDK bucket lists share the worker connection. Stop issuing reads once the checkpoint is unavailable. + const sdkReads = this.kv.durability?.completion === "sdk"; + const failures = await inBatches(bucketIds, sdkReads ? 1 : LOAD_CONCURRENCY, async (bucket) => { const rows = await this.kv.list(vectorBucketScope(bucket)); let count = 0; for (const row of rows) { @@ -834,7 +949,7 @@ export class IndexPersistence { count++; } if (count > 0) bucketCounts.set(bucket, count); - }); + }, sdkReads); if (failures.length > 0) { logger.warn("index persistence: vector bucket read failed", { failed: failures.length, diff --git a/src/state/vector-index.ts b/src/state/vector-index.ts index b31459655e..ad7f3022cc 100644 --- a/src/state/vector-index.ts +++ b/src/state/vector-index.ts @@ -37,12 +37,16 @@ export class VectorIndex { private vectors: Map = new Map(); private changes: Map = new Map(); private listener: VectorChangeListener | null = null; + private mutationGuard: (() => void) | null = null; + + setMutationGuard(guard: (() => void) | null): void { this.mutationGuard = guard; } setChangeListener(listener: VectorChangeListener | null): void { this.listener = listener; } add(obsId: string, sessionId: string, embedding: Float32Array): void { + this.mutationGuard?.(); const entry = { embedding, sessionId }; this.vectors.set(obsId, entry); this.changes.set(obsId, true); @@ -50,6 +54,7 @@ export class VectorIndex { } remove(obsId: string): void { + this.mutationGuard?.(); if (this.vectors.delete(obsId)) { this.changes.set(obsId, false); this.listener?.(obsId, null); @@ -157,6 +162,7 @@ export class VectorIndex { } clear(): void { + this.mutationGuard?.(); const hadVectors = this.vectors.size > 0; for (const obsId of this.vectors.keys()) this.changes.set(obsId, false); this.vectors.clear(); diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 24ff5dff2a..e601db46f3 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -1,3 +1,4 @@ +import {validUncertainInspection} from "../capture/uncertain-inspection.js"; import {liveResourceSample} from '../health/live-resource.js'; import {createSessionEndDiagnostics} from "../ops/session-end-diagnostics.js"; import {finishLongSession} from "../ops/long-session.mjs"; @@ -399,8 +400,12 @@ export interface StatusReporterDeps { provider?: ResilientProvider | { circuitState?: unknown }; } +function isVectorRecoveryPaused(result: unknown): boolean { + return typeof result === "object" && result !== null && "error" in result && (result.error === "vector_recovery_paused" || result.error === "vector_recovery_interrupted"); +} + export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusReporterDeps) { - return async function statusReport(options: { health?: HealthSnapshot | null; scanMaxAgeMs?: number; scanUnindexed?: boolean; functionMetrics?:ReturnType } = {}): Promise { + return async function statusReport(options: { health?: HealthSnapshot | null; scanMaxAgeMs?: number; scanUnindexed?: boolean; scanCaptureInbox?: boolean; functionMetrics?:ReturnType } = {}): Promise { const idx = getSearchIndex(); const keywordRebuildRunning = isKeywordRebuildInProgress(); const scan = unindexedScanFor(kv); @@ -420,7 +425,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe STATUS_CHECK_TIMEOUT_MS, ), probeStateStore(kv), - valueWithin(getCaptureController()?.status() ?? Promise.resolve(null), STATUS_CHECK_TIMEOUT_MS), + valueWithin(getCaptureController()?.status({scanInbox:options.scanCaptureInbox}) ?? Promise.resolve(null), STATUS_CHECK_TIMEOUT_MS), valueWithin(getGraphIndexMigrationStatus(kv), STATUS_CHECK_TIMEOUT_MS), ]); const observationsIndexed = [...idx.observationCountsBySession().values()].reduce((a, n) => a + n, 0); @@ -635,7 +640,8 @@ export function registerApiTriggers( const ops = await operationalHealth(); const hostLevel=ops.memoryPressure?.level; const backgroundStatus=ops.backgroundControl?.status; - const status = hostLevel==="critical"?"critical":hostLevel==="high"&&health?.status!=="critical"?"degraded":(backgroundStatus==="error"||ops.captureProgress?.stalled)&&health?.status!=="critical"?"degraded":health?.status||"healthy"; + const captureUnknown=ops.captureProgress?.pending===null; + const status = hostLevel==="critical"?"critical":hostLevel==="high"&&health?.status!=="critical"?"degraded":(backgroundStatus==="error"||ops.captureProgress?.stalled||captureUnknown)&&health?.status!=="critical"?"degraded":health?.status||"healthy"; const statusCode = status === "critical" ? 503 : 200; return { @@ -823,6 +829,14 @@ export function registerApiTriggers( catch{return{status_code:503,headers,body:{completed:false,code:'SDK_RECONCILIATION_UNAVAILABLE'}};} }); sdk.registerTrigger({type:'http',function_id:'api::capture-reconcile-sdk',config:{api_path:'/agentmemory/capture/reconcile-sdk',http_method:'POST'}}); + sdk.registerFunction('api::capture-inspect-uncertain',async(req:HttpRequest):Promise=>{ + const headers={'Cache-Control':'no-store'};if(!secret)return{status_code:503,headers,body:{error:'UNCERTAIN_INSPECTION_AUTH_REQUIRED'}};const denied=checkAuth(req,secret);if(denied)return{...denied,headers}; + const q=req.body;if(!validUncertainInspection(q))return{status_code:400,headers,body:{error:'INVALID_UNCERTAIN_INSPECTION'}}; + try{const value:any=await sdk.trigger({function_id:'mem::capture-inspect-uncertain',payload:q});return{status_code:['source_conflict','observation_conflict','changed_during_inspection'].includes(value?.outcome)?409:200,headers,body:value};} + catch{return{status_code:503,headers,body:{error:'UNCERTAIN_INSPECTION_UNAVAILABLE'}};} + }); + sdk.registerTrigger({type:'http',function_id:'api::capture-inspect-uncertain',config:{api_path:'/agentmemory/capture/inspect-uncertain',http_method:'POST'}}); + sdk.registerFunction('api::capture-reconcile-sdk-status',async(req:HttpRequest):Promise=>{ const headers={'Cache-Control':'no-store'},denied=checkAuth(req,secret);if(denied)return{...denied,headers}; const q=req.query_params??{}; @@ -1221,7 +1235,7 @@ export function registerApiTriggers( function_id: "mem::replay::import-jsonl", payload, }); - return { status_code: 202, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 202, body: result }; }, ); sdk.registerTrigger({ @@ -1862,7 +1876,7 @@ export function registerApiTriggers( : {}), }, }); - return { status_code: 201, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 201, body: result }; }, ); sdk.registerTrigger({ @@ -1888,7 +1902,7 @@ export function registerApiTriggers( }; } const result = await sdk.trigger({ function_id: "mem::forget", payload: req.body }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; }, ); sdk.registerTrigger({ @@ -1984,7 +1998,7 @@ export function registerApiTriggers( const dryRun = req.query_params?.["dryRun"] === "true" || req.body?.dryRun === true; const result = await sdk.trigger({ function_id: "mem::evict", payload: { dryRun } }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; }, ); sdk.registerTrigger({ @@ -2215,7 +2229,7 @@ export function registerApiTriggers( return { status_code: 400, body: { error: "exportData is required" } }; } const result = await sdk.trigger({ function_id: "mem::import", payload: req.body }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; }, ); sdk.registerTrigger({ @@ -2267,6 +2281,7 @@ export function registerApiTriggers( function_id: "mem::evolve", payload: req.body, }); + if (isVectorRecoveryPaused(result)) return { status_code: 503, body: result }; if (result && result.success === false) { const status = result.code === "not_found" ? 404 : result.code === "not_latest" ? 409 : 400; @@ -2288,7 +2303,7 @@ export function registerApiTriggers( const dryRun = req.query_params?.["dryRun"] === "true" || req.body?.dryRun === true; const result = await sdk.trigger({ function_id: "mem::auto-forget", payload: { dryRun } }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; }, ); sdk.registerTrigger({ @@ -2770,7 +2785,7 @@ export function registerApiTriggers( }; } const result = await sdk.trigger({ function_id: "mem::governance-delete", payload: req.body }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; }, ); sdk.registerTrigger({ @@ -2796,7 +2811,7 @@ export function registerApiTriggers( const authErr = checkAuth(req, secret); if (authErr) return authErr; const result = await sdk.trigger({ function_id: "mem::governance-bulk", payload: req.body || {} }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; }, ); sdk.registerTrigger({ @@ -2862,7 +2877,7 @@ export function registerApiTriggers( } try { const result = await sdk.trigger({ function_id: "mem::snapshot-restore", payload: req.body }); - return { status_code: 200, body: result }; + return { status_code: isVectorRecoveryPaused(result) ? 503 : 200, body: result }; } catch { return { status_code: 404, body: { error: "Snapshots not enabled" } }; } diff --git a/src/triggers/viewer-streams.ts b/src/triggers/viewer-streams.ts index 44419338f4..5084558cbc 100644 --- a/src/triggers/viewer-streams.ts +++ b/src/triggers/viewer-streams.ts @@ -96,7 +96,7 @@ export function registerViewerStreamTriggers( const [functionMetrics, counts, report] = await Promise.all([ metricsRead, getViewerCounts(kv), - statusReport({ health: snapshot, scanMaxAgeMs, scanUnindexed, functionMetrics:metricsRead }).catch(() => null), + statusReport({ health: snapshot, scanMaxAgeMs, scanUnindexed, scanCaptureInbox:false, functionMetrics:metricsRead }).catch(() => null), ]); return { status: snapshot?.status ?? "healthy", diff --git a/src/types.ts b/src/types.ts index 4b881ad6d4..a5d203b945 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index 9752b85c28..c66ade2008 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.55"; +export const VERSION = "0.9.32-daniel.58"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/src/viewer/index.html b/src/viewer/index.html index 6387fc95fd..6f7820c28a 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -2739,6 +2739,7 @@

agentmemory

if (!['running','pausing','resuming','paused','error'].includes(control.status)) html += '

백그라운드 실행 상태 미확인 · 현황을 다시 조회하세요.

'; if (work.quarantined) html += '

요약·후처리 격리 '+work.quarantined+'건 · 사용자 점검이 필요하며 자동 재처리하지 않습니다.

'; var inbox = ((store.report || {}).capture || {}).inbox; + if (!inbox) html += '

수집 inbox를 자동 조회하지 않아 격리·재시도·마지막 오류·SDK 복원 및 수집 정체 상태를 확인하지 못했습니다. 수집 격리·복구 이력의 수동 조회도 오래 걸리거나 실패할 수 있습니다.

'; if (inbox && inbox.sdkRestorePending) html += ''; if (inbox && inbox.sdkCompleted) html += '

SDK 저장 완료 · 원본 보존 '+fmtNum(inbox.sdkCompleted)+'건. 디스크 확정 영수증이 없어 자동 제거·재처리하지 않습니다.

'; if (inbox && (inbox.dead || inbox.retrying)) html += '

수집 저장 전 실패: 격리 '+fmtNum(inbox.dead || 0)+'건 · 재시도 '+fmtNum(inbox.retrying || 0)+'건 · 수집 격리·복구 이력에서 확인하세요.

'; @@ -7813,8 +7814,8 @@

agentmemory

html += hrow('Keyword rebuild', ri.bm25Incomplete ? 'incomplete' : 'complete', null, 'Rebuilt from stored data at every start, so it is never saved to disk.'); if (p) { html += hrow('Vector save', esc(legText(p.vector)), null, 'Saved at most every ' + esc(durationText(p.saveIntervalMs || 600000)) + ' (AGENTMEMORY_INDEX_SAVE_INTERVAL_MS). ' + esc(fmtNum(p.buckets) + ' bucket' + (p.buckets === 1 ? '' : 's') + ', ' + fmtNum(p.pendingChanges) + ' unsaved change' + (p.pendingChanges === 1 ? '' : 's') + (p.saving ? ', saving now' : '') + '.')); - if (typeof p.pendingLog === 'number') { - html += hrow('Pending vector log', esc(fmtNum(p.pendingLog) + ' vector change' + (p.pendingLog === 1 ? '' : 's')), null, + if (typeof p.pendingLog === 'number' || p.pendingLogKnown === false) { + html += hrow('Pending vector log', p.pendingLogKnown === false ? 'not checked' : esc(fmtNum(p.pendingLog) + ' vector change' + (p.pendingLog === 1 ? '' : 's')), null, p.pendingLogError ? '' + esc('Log writes failing: ' + p.pendingLogError) + '' : 'New and removed vectors are written here right away and replayed after a crash, so nothing is embedded twice. Each save empties it.'); } @@ -7900,7 +7901,8 @@

agentmemory

var drainedAt = (cap.spool || []).map(function(s) { return s.stats && s.stats.lastDrainAt; }).filter(Boolean).sort().pop(); var dropped = (cap.spool || []).reduce(function(n, s) { return n + ((s.stats && s.stats.dropped) || 0); }, 0); html += hrow('Inbox', inbox ? esc(fmtNum(inbox.pending) + ' pending · ' + fmtNum(inbox.retrying) + ' retrying · ' + fmtNum(inbox.dead) + ' dead' + (inbox.sdkCompleted ? ' · '+fmtNum(inbox.sdkCompleted)+' SDK 완료 원본 보존' : '')) : 'not checked', 'captureInbox', - inbox && inbox.dead ? '' + esc(inbox.lastError || 'Could not be stored.') + ' · 작업 관리에서 수집 격리·복구 이력을 확인하세요.' : + !inbox ? 'Inbox status is unknown; automatic capture checks are unavailable.' : + inbox.dead ? '' + esc(inbox.lastError || 'Could not be stored.') + ' · 작업 관리에서 수집 격리·복구 이력을 확인하세요.' : inbox && inbox.retrying ? '' + esc('Retried every ' + durationText(cap.policy.retryIntervalMs) + ' with backoff, up to ' + cap.policy.maxAttempts + ' attempts' + (inbox.lastError ? '. Last error: ' + inbox.lastError : '.')) + '' : 'Empty means every accepted observation is stored.'); html += hrow('Since start', esc(fmtNum(since.accepted || 0) + ' accepted · ' + fmtNum(since.completed || 0) + ' stored · ' + fmtNum(since.duplicates || 0) + ' duplicates skipped · ' + fmtNum(since.recovered || 0) + ' recovered by retry · ' + fmtNum(since.deadLettered || 0) + ' dead'), null, diff --git a/test/capture-durable.test.ts b/test/capture-durable.test.ts index a8954e4f32..6eb0badacd 100644 --- a/test/capture-durable.test.ts +++ b/test/capture-durable.test.ts @@ -517,3 +517,8 @@ describe("acceptance durability across a restart", () => { expect((await controller.status()).spool[0]).toMatchObject({ records: 0, retained: 1 }); }); }); +it('retains capture for retry when observation is temporarily blocked by vector recovery',async()=>{const kv=mockKV();const {sdk,capture,controller,dedup}=await boot(kv);try{sdk.fns.set('mem::observe',async()=>({success:false,error:'vector_recovery_paused',retryable:true}));const result=await capture(payload('synthetic-hold'),'evc_000000003333');expect(result).toMatchObject({status:'accepted',state:'retrying'});expect(inbox(kv)).toHaveLength(1);expect(inbox(kv)[0]).toMatchObject({status:'retrying'});expect(observations(kv)).toHaveLength(0)}finally{controller.stop();dedup.stop()}}); +it('does not exhaust capture attempts while vector recovery admission remains held',async()=>{vi.stubEnv('AGENTMEMORY_CAPTURE_MAX_ATTEMPTS','1');const kv=mockKV();const {sdk,capture,controller,dedup}=await boot(kv);try{sdk.fns.set('mem::observe',async()=>({success:false,error:'vector_recovery_paused',retryable:true}));const result=await capture(payload('synthetic-held-budget'),'evc_000000003334');expect(result).toMatchObject({status:'accepted',state:'retrying',attempts:0});expect(inbox(kv)[0]).toMatchObject({status:'retrying',attempts:0})}finally{controller.stop();dedup.stop()}}); +it('retains delayed captures across repeated holds and processes them after release',async()=>{vi.stubEnv('AGENTMEMORY_CAPTURE_MAX_ATTEMPTS','1');vi.stubEnv('AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS','1000');const kv=mockKV();const {sdk,capture,controller,dedup}=await boot(kv),observe=sdk.fns.get('mem::observe')!;try{vi.useFakeTimers({now:Date.now(),toFake:['Date']});sdk.fns.set('mem::observe',async()=>({success:false,error:'vector_recovery_paused',retryable:true}));await capture(payload('synthetic-long-hold'),'evc_000000003335');for(let i=0;i<3;i++){vi.setSystemTime(Date.now()+60000);await controller.sweep();expect(inbox(kv)[0]).toMatchObject({status:'retrying',attempts:0})}sdk.fns.set('mem::observe',observe);vi.setSystemTime(Date.now()+60000);await controller.sweep();expect(inbox(kv)).toHaveLength(0);expect(observations(kv)).toHaveLength(1)}finally{controller.stop();dedup.stop();vi.useRealTimers();vi.unstubAllEnvs()}}); +it('quarantines an interrupted observation and prevents blind manual retry',async()=>{const kv=mockKV();const {sdk,capture,controller,dedup}=await boot(kv);try{const observe=vi.fn(async()=>({success:false,error:'vector_recovery_interrupted',partial:true,retryable:false}));sdk.fns.set('mem::observe',observe);const first=await capture(payload('synthetic-interrupted'),'evc_000000003336');expect(first).toMatchObject({status:'rejected',retryable:false});expect(inbox(kv)[0]).toMatchObject({status:'dead',lastError:'vector_recovery_interrupted'});const again=await sdk.trigger('mem::capture-retry',{all:true}) as any;expect(again).toMatchObject({matched:1,waiting:1,recovered:0});expect(observe).toHaveBeenCalledTimes(1);expect(inbox(kv)).toHaveLength(1)}finally{controller.stop();dedup.stop()}}); +it('does not mutate the index for a duplicate capture while vector recovery is held',async()=>{const kv=mockKV();const {capture,controller,dedup}=await boot(kv);const {createBackgroundControl,installBackgroundControl}=await import('../src/ops/background-control.mjs');const first=await capture(payload('synthetic-duplicate-held'),'evc_000000003337');expect(first.status).toBe('accepted');const state={version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}};const control=createBackgroundControl();await control.init({get:async()=>state,set:async()=>{},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}} as any);installBackgroundControl(control);try{await expect(capture(payload('synthetic-duplicate-held'),'evc_000000003337')).rejects.toThrow(/vector_recovery_paused/);expect(observations(kv)).toHaveLength(1)}finally{controller.stop();dedup.stop()}}); diff --git a/test/capture-sdk-reconciliation-api.test.ts b/test/capture-sdk-reconciliation-api.test.ts index 842c075dc5..8166b021df 100644 --- a/test/capture-sdk-reconciliation-api.test.ts +++ b/test/capture-sdk-reconciliation-api.test.ts @@ -21,6 +21,44 @@ it('reads explicit recorded outcome without claiming disk proof or current sourc it('exposes current index membership in one body-free readonly function',async()=>{const f=await fixture();const result=await f.sdk.fns.get('api::capture-index-membership')!({headers:f.headers,query_params:{ids:id}})as any;expect(result).toMatchObject({status_code:200,body:{sourceVerified:false,diskVerified:false,items:[{id,keywordPresent:true,vectorPresent:true}]}});expect(JSON.stringify(result)).not.toContain('private synthetic original');expect(f.writes).not.toHaveBeenCalled()}); it('stops admission after capture shutdown and drains existing tracked work',async()=>{const f=await fixture();f.control.stop();expect((await f.call()).body.completed).toBe(false);await f.control.drain();expect(f.writes).not.toHaveBeenCalled()}); +it('does not read inbox for automatic viewer status and keeps result unknown',async()=>{ + const f=await fixture();const list=vi.spyOn(f.kv,'list'); + const {createStatusReporter}=await import('../src/triggers/api.js'); + const report=createStatusReporter(f.sdk as never,f.kv as never,{}); + const result=await report({health:null,scanUnindexed:false,scanCaptureInbox:false} as never); + expect(list.mock.calls.filter(([scope])=>scope===KV.captureInbox)).toHaveLength(0); + expect(result.capture?.inbox).toBeNull(); + expect(result.problems.some(p=>p.code==='capture-check-unavailable')).toBe(true); +}); +it('retains the explicit authenticated capture inbox check',async()=>{ + const f=await fixture();const list=vi.spyOn(f.kv,'list'); + const status=await f.control.status();expect(status.inbox).not.toBeNull(); + expect(list.mock.calls.filter(([scope])=>scope===KV.captureInbox)).toHaveLength(1); +}); +it('skips inbox reads in viewer snapshot and health events',async()=>{ + const f=await fixture();Object.assign(f.kv,{countSummaries:async()=>0}); + const {registerViewerStreamTriggers}=await import('../src/triggers/viewer-streams.js'); + registerViewerStreamTriggers(f.sdk as never,f.kv as never,{}); + const list=vi.spyOn(f.kv,'list'); + const snapshot=await f.sdk.fns.get('api::viewer-snapshot')!({headers:{}}) as any; + expect(snapshot.status_code).toBe(200);expect(snapshot.body.report.capture.inbox).toBeNull(); + list.mockClear(); + const healthEvent=await f.sdk.fns.get('event::viewer::health-changed')!({key:'latest',event_type:'state:updated',new_value:{status:'healthy',alerts:[]}}) as any; + expect(healthEvent).toMatchObject({emitted:true}); + expect(list.mock.calls.filter(([scope])=>scope===KV.captureInbox)).toHaveLength(0); +}); +it('does not report healthy when capture pending work is unknown',async()=>{ + const f=await fixture();const {operationalState}=await import('../src/ops/context.js'); + const prior=operationalState.captureProgress; + try{ + operationalState.captureProgress={snapshot:()=>({pending:null,stalled:false})} as never; + await f.kv.set(KV.health,'latest',{status:'healthy',alerts:[]}); + const response=await f.sdk.fns.get('api::health')!({}) as any; + expect(response.body.status).toBe('degraded'); + expect(response.body.captureProgress.pending).toBeNull(); + }finally{operationalState.captureProgress=prior} +}); + it('holds drain until an in-flight reconciliation exits and stops before further writes after shutdown',async()=>{ const f=await fixture();let entered!:()=>void,release!:()=>void;const reached=new Promise(r=>entered=r),blocked=new Promise(r=>release=r);const get=f.kv.get.bind(f.kv);let intercepted=false; f.kv.get=async(s,k)=>{if(!intercepted&&s===KV.captureInbox&&k===key){intercepted=true;entered();await blocked;}return get(s,k)}; @@ -52,3 +90,15 @@ it('bounds SDK archive status history reads to four while preserving validated c expect(active).toBe(0); expect(peak).toBeLessThanOrEqual(4); }); + +it('real viewer health update omits the inbox scan',async()=>{const f=await fixture();Object.assign(f.kv,{countSummaries:async()=>0});const {registerViewerStreamTriggers}=await import('../src/triggers/viewer-streams.js');registerViewerStreamTriggers(f.sdk as never,f.kv as never,{});const list=vi.spyOn(f.kv,'list');const event=await f.sdk.fns.get('event::viewer::health-changed')!({key:'latest',event_type:'state:updated',new_value:{status:'healthy',alerts:[]}}) as any;expect(event).toMatchObject({emitted:true});expect(list.mock.calls.filter(([scope])=>scope===KV.captureInbox)).toHaveLength(0)}); +it('returns a retryable service error when remember is refused by the vector hold',async()=>{const f=await fixture();f.sdk.fns.set('mem::remember',async()=>({success:false,error:'vector_recovery_paused',retryable:true}));const out=await f.sdk.fns.get('api::remember')!({headers:{authorization:'Bearer synthetic-secret'},body:{content:'synthetic'}}) as any;expect(out).toMatchObject({status_code:503,body:{success:false,error:'vector_recovery_paused',retryable:true}})}); +it.each([['forget','mem::forget',{memoryId:'synthetic'}],['evict','mem::evict',{}],['evolve','mem::evolve',{memoryId:'synthetic',newContent:'synthetic'}],['governance-delete','mem::governance-delete',{memoryIds:['synthetic']}],['governance-bulk','mem::governance-bulk',{}]])('returns a retryable 503 for held %s',async(api,fn,body)=>{const f=await fixture();f.sdk.fns.set(fn,async()=>({success:false,error:'vector_recovery_paused',retryable:true}));const out=await f.sdk.fns.get('api::'+api)!({headers:{authorization:'Bearer synthetic-secret'},body,query_params:{}}) as any;expect(out).toMatchObject({status_code:503,body:{success:false,error:'vector_recovery_paused',retryable:true}})}); +it.each([['auto-forget','mem::auto-forget',{}],['snapshot-restore','mem::snapshot-restore',{commitHash:'synthetic'}]])('returns retryable 503 for held %s',async(api,fn,body)=>{const f=await fixture();f.sdk.fns.set(fn,async()=>({success:false,error:'vector_recovery_paused',retryable:true}));const out=await f.sdk.fns.get('api::'+api)!({headers:{authorization:'Bearer synthetic-secret'},body,query_params:{}}) as any;expect(out).toMatchObject({status_code:503,body:{success:false,error:'vector_recovery_paused',retryable:true}})}); +it.each([['import','mem::import',{exportData:{}}],['replay::import','mem::replay::import-jsonl',{}]])('returns retryable 503 for held %s',async(api,fn,body)=>{const f=await fixture();f.sdk.fns.set(fn,async()=>({success:false,error:'vector_recovery_paused',retryable:true}));const out=await f.sdk.fns.get('api::'+api)!({headers:{authorization:'Bearer synthetic-secret'},body,query_params:{}}) as any;expect(out).toMatchObject({status_code:503,body:{success:false,error:'vector_recovery_paused',retryable:true}})}); +it('inspects an uncertain item by original identifiers and content without writes or replay',async()=>{const f=await fixture();const inspect=f.sdk.fns.get('api::capture-inspect-uncertain');expect(inspect).toBeTypeOf('function');const out=await inspect!({headers:f.headers,body:{key,eventId,sourceDigest:capturePayloadDigest(payload),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp}}) as any;expect(out).toMatchObject({status_code:200,body:{outcome:'observation_matches',readOnly:true,diskVerified:false,originalReplay:false,retryAuthorized:false}});expect(f.writes).not.toHaveBeenCalled()}); +it('does not infer retry is safe when an uncertain observation is absent or source differs',async()=>{const f=await fixture();await f.kv.delete(KV.observations(payload.sessionId),id);const inspect=f.sdk.fns.get('api::capture-inspect-uncertain');expect(inspect).toBeTypeOf('function');const absent=await inspect!({headers:f.headers,body:{key,eventId,sourceDigest:capturePayloadDigest(payload),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp}}) as any;expect(absent).toMatchObject({status_code:200,body:{outcome:'observation_not_found',retryAuthorized:false,diskVerified:false}});const mismatch=await inspect!({headers:f.headers,body:{key,eventId,sourceDigest:'0'.repeat(64),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp}}) as any;expect(mismatch.status_code).toBe(409);expect(f.writes).not.toHaveBeenCalled()}); +it('allows the SDK caller metadata without accepting extra inspection fields',async()=>{const f=await fixture();const direct=f.sdk.fns.get('mem::capture-inspect-uncertain')!;expect(await direct({key,eventId,sourceDigest:capturePayloadDigest(payload),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp,_caller_worker_id:'synthetic-worker'})).toMatchObject({outcome:'observation_matches',readOnly:true});await expect(direct({key,eventId,sourceDigest:capturePayloadDigest(payload),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp,extra:true})).rejects.toThrow();expect(f.writes).not.toHaveBeenCalled()}); + +it('requires a configured secret and exact original metadata for uncertain inspection',async()=>{const f=await fixture(),body={key,eventId,sourceDigest:capturePayloadDigest(payload),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp};const handler=f.sdk.fns.get('api::capture-inspect-uncertain')!;expect((await handler({headers:{},body}) as any).status_code).toBe(401);expect((await handler({headers:f.headers,body:{...body,cwd:'/different'}}) as any).status_code).toBe(409);registerApiTriggers(f.sdk as never,f.kv as never,'');const unconfigured=await f.sdk.fns.get('api::capture-inspect-uncertain')!({headers:{},body}) as any;expect(unconfigured.status_code).toBe(503);expect(f.writes).not.toHaveBeenCalled()}); +it('refuses changing observations and reports read failures without mutation',async()=>{const f=await fixture(),body={key,eventId,sourceDigest:capturePayloadDigest(payload),project:payload.project,sessionId:payload.sessionId,cwd:payload.cwd,hookType:payload.hookType,timestamp:payload.timestamp},handler=f.sdk.fns.get('api::capture-inspect-uncertain')!,get=f.kv.get;let reads=0;f.kv.get=async(scope:string,k:string)=>{const v=await get(scope,k);if(scope===KV.observations(payload.sessionId)&&++reads===2)return {...v as object,title:'changed'} as T;return v};expect((await handler({headers:f.headers,body}) as any)).toMatchObject({status_code:409,body:{outcome:'changed_during_inspection',retryAuthorized:false}});f.kv.get=async()=>{throw Error('synthetic read unavailable')};expect((await handler({headers:f.headers,body}) as any)).toMatchObject({status_code:503,body:{error:'UNCERTAIN_INSPECTION_UNAVAILABLE'}});expect(f.writes).not.toHaveBeenCalled()}); diff --git a/test/cli-native-compat.test.ts b/test/cli-native-compat.test.ts index 94b21f12d3..1c617fdda6 100644 --- a/test/cli-native-compat.test.ts +++ b/test/cli-native-compat.test.ts @@ -224,7 +224,12 @@ describe("native startup prior ownership", () => { for(const [saved,pidfile] of [[JSON.stringify(prior),undefined],[JSON.stringify(prior),"99999999"],["{malformed",undefined],[JSON.stringify({kind:"unknown"}),undefined],[JSON.stringify({...prior,workerIdentity:undefined}),undefined]]as const){ fs.writeFileSync(join(runtime,"engine-state.json"),saved);if(pidfile)fs.writeFileSync(join(runtime,"worker.pid"),pidfile);else fs.rmSync(join(runtime,"worker.pid"),{force:true}); const result=spawnSync(process.execPath,["--import","tsx",resolve("src/cli.ts"),"--native-compat","--port",String(port)],{env,cwd:process.cwd(),encoding:"utf8",timeout:15000}); - expect(result.error).toBeUndefined();expect(result.status).toBe(1);expect(result.stdout+result.stderr).toContain("prior lifecycle");expect(fs.existsSync(binLog)).toBe(false);expect(fs.existsSync(marker)).toBe(false);expect(fs.readFileSync(join(runtime,"engine-state.json"),"utf8")).toBe(saved); + expect(result.error).toBeUndefined(); + expect(result.stdout + result.stderr).toContain("prior lifecycle"); + expect(result.status).toBe(78); + expect(fs.existsSync(binLog)).toBe(false); + expect(fs.existsSync(marker)).toBe(false); + expect(fs.readFileSync(join(runtime, "engine-state.json"), "utf8")).toBe(saved); } for(const saved of [undefined,"{malformed",JSON.stringify({kind:"unknown"})]){ if(saved)fs.writeFileSync(join(runtime,"engine-state.json"),saved);else fs.rmSync(join(runtime,"engine-state.json"),{force:true});fs.writeFileSync(join(runtime,"worker.pid"),String(child.pid)); diff --git a/test/foreground-vector-hold.test.ts b/test/foreground-vector-hold.test.ts new file mode 100644 index 0000000000..8c85de17f4 --- /dev/null +++ b/test/foreground-vector-hold.test.ts @@ -0,0 +1,25 @@ +import {it,expect,vi} from 'vitest'; +import {mockKV,mockSdk} from './helpers/mocks.js'; +import {registerRememberFunction} from '../src/functions/remember.js'; +import {registerApiTriggers} from '../src/triggers/api.js'; +import {createBackgroundControl,installBackgroundControl,controlBackgroundFunctions} from '../src/ops/background-control.mjs'; +it('rejects held remember at the real API boundary before changing memory',async()=>{ + const state={version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}; + const control=createBackgroundControl();await control.init({get:async()=>state,set:async()=>{},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}} as any);installBackgroundControl(control); + const kv=mockKV(),writes=vi.spyOn(kv,'set'),sdk=mockSdk({looseTrigger:true});controlBackgroundFunctions(sdk as any);registerRememberFunction(sdk as any,kv as any);registerApiTriggers(sdk as any,kv as any,'fixture'); + const response=await sdk.fns.get('api::remember')!({headers:{authorization:'Bearer fixture'},body:{content:'synthetic'}}) as any; + expect(response).toMatchObject({status_code:503,body:{success:false,error:'vector_recovery_paused',retryable:true}});expect(writes).not.toHaveBeenCalled(); +}); +it('retains a hook capture for retry when observation admission is held',async()=>{ + const state={version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}};const control=createBackgroundControl();await control.init({get:async()=>state,set:async()=>{},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}} as any);installBackgroundControl(control); + const kv=mockKV(),sdk=mockSdk({looseTrigger:true}),observe=vi.fn(async()=>({observationId:'should-not-exist'}));controlBackgroundFunctions(sdk as any);sdk.registerFunction('mem::observe',observe);const {registerCaptureFunctions}=await import('../src/functions/capture.js');const capture=registerCaptureFunctions(sdk as any,kv as any); + try{const result=await sdk.trigger('mem::capture',{eventId:'evt_synthetic_00001',payload:{hookType:'post_tool_use',sessionId:'synthetic',project:'synthetic',cwd:'/synthetic',timestamp:'2026-01-01T00:00:00Z',data:{tool_output:'synthetic'}}}) as any;expect(result).toMatchObject({status:'accepted',state:'retrying'});expect(observe).not.toHaveBeenCalled();expect((kv.store.get('mem:capture:inbox')?.size??0)).toBe(1)}finally{capture.stop()} +}); +it('rejects SDK-mode capture before accepting it while storage recovery is held',async()=>{const state={version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}};const control=createBackgroundControl();await control.init({get:async()=>state,set:async()=>{},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}} as any);installBackgroundControl(control);const kv=mockKV();Object.assign(kv,{backend:'file',durability:{completion:'sdk'}});const writes=vi.spyOn(kv,'set'),sdk=mockSdk({looseTrigger:true});controlBackgroundFunctions(sdk as any);const {registerCaptureFunctions}=await import('../src/functions/capture.js');const capture=registerCaptureFunctions(sdk as any,kv as any);try{const out=await sdk.trigger('mem::capture',{eventId:'evt_synthetic_00002',payload:{hookType:'post_tool_use',sessionId:'synthetic',project:'synthetic',cwd:'/synthetic',timestamp:'2026-01-01T00:00:00Z',data:{tool_output:'synthetic'}}}) as any;expect(out).toMatchObject({status:'rejected',retryable:true,error:'vector_recovery_paused'});expect(writes).not.toHaveBeenCalled()}finally{capture.stop()}}); +it('parks the same SDK capture after hold starts during inbox admission without re-execution',async()=>{ + let saved:any={paused:false};const store={get:async()=>saved,set:async(_s:string,_k:string,v:any)=>{saved=v},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}};const control=createBackgroundControl();await control.init(store as any);installBackgroundControl(control); + const kv=mockKV();Object.assign(kv,{backend:'file',durability:{completion:'sdk'}});let enter!:()=>void,release!:()=>void;const arrived=new Promise(r=>enter=r),wait=new Promise(r=>release=r),get=kv.get;let blocked=false;kv.get=async(scope:string,key:string)=>{if(scope==='mem:capture:inbox'&&!blocked){blocked=true;enter();await wait}return get(scope,key)}; + const sdk=mockSdk({looseTrigger:true});controlBackgroundFunctions(sdk as any);const observe=vi.fn(async(input:any)=>{await kv.set('mem:obs:'+input.sessionId,input.observationId,{id:input.observationId,sessionId:input.sessionId});return{observationId:input.observationId}});sdk.registerFunction('mem::observe',observe);const {registerCaptureFunctions}=await import('../src/functions/capture.js');const capture=registerCaptureFunctions(sdk as any,kv as any);const body={eventId:'evt_synthetic_race01',payload:{hookType:'post_tool_use',sessionId:'synthetic',project:'synthetic',cwd:'/synthetic',timestamp:'2026-01-01T00:00:00Z',data:{tool_output:'synthetic'}}}; + try{const first=sdk.trigger('mem::capture',body) as Promise;await arrived;const set=store.set;store.set=async()=>{throw Error('synthetic storage failure')};await expect(control.change('pause')).rejects.toThrow();store.set=set;release();expect(await first).toMatchObject({status:'rejected',eventId:body.eventId,retryable:false,error:'capture_reconciliation_required',reconciliationRequired:true});expect(observe).not.toHaveBeenCalled();const row=[...(kv.store.get('mem:capture:inbox')?.values()??[])][0] as any;expect(row).toMatchObject({eventId:body.eventId,deferredByStorageHold:true});await control.change('resume');const mismatch=await sdk.trigger('mem::capture',{...body,payload:{...body.payload,data:{tool_output:'different'}}}) as any;expect(mismatch).toMatchObject({status:'rejected',retryable:false,error:'capture_deferred_source_mismatch'});expect(observe).not.toHaveBeenCalled();const second=await sdk.trigger('mem::capture',body) as any;expect(second).toMatchObject({status:'rejected',retryable:false,error:'capture_reconciliation_required',reconciliationRequired:true});expect(observe).not.toHaveBeenCalled()}finally{capture.stop()} +}); +it('parks an interrupted SDK observation and never blindly re-executes it',async()=>{const state={paused:false};const control=createBackgroundControl();await control.init({get:async()=>state,set:async()=>{},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}} as any);installBackgroundControl(control);const kv=mockKV();Object.assign(kv,{backend:'file',durability:{completion:'sdk'}});const sdk=mockSdk({looseTrigger:true}),observe=vi.fn(async()=>({success:false,error:'vector_recovery_interrupted',partial:true,retryable:false}));sdk.registerFunction('mem::observe',observe);const {registerCaptureFunctions}=await import('../src/functions/capture.js');const capture=registerCaptureFunctions(sdk as any,kv as any);const body={eventId:'evt_synthetic_unc01',payload:{hookType:'post_tool_use',sessionId:'synthetic',project:'synthetic',cwd:'/synthetic',timestamp:'2026-01-01T00:00:00Z',data:{tool_output:'synthetic'}}};try{expect(await sdk.trigger('mem::capture',body)).toMatchObject({status:'rejected',retryable:false,error:'vector_recovery_interrupted',reconciliationRequired:true});expect(await sdk.trigger('mem::capture',body)).toMatchObject({status:'rejected',retryable:false,error:'vector_recovery_interrupted',reconciliationRequired:true});expect(observe).toHaveBeenCalledTimes(1);expect(kv.store.get('mem:capture:inbox')?.size).toBe(1)}finally{capture.stop()}}); diff --git a/test/index-persistence.test.ts b/test/index-persistence.test.ts index db6e8e8d1f..1302943a3a 100644 --- a/test/index-persistence.test.ts +++ b/test/index-persistence.test.ts @@ -387,6 +387,54 @@ describe("IndexPersistence bucketed vector storage", () => { expect(loaded).toEqual({ vector: null, state: "unavailable", savedAt: null }); }); + it.each([["sdk", 1], ["disk", 8]] as const)( + "limits overlapping %s checkpoint bucket reads to %i", + async (completion, expectedPeak) => { + const bucketCount = 12; + await kv.set(INDEX_SCOPE, META_KEY, { v: 3, bucketCount, count: 1 }); + const entry = { id: "v_last", s: "session", e: Buffer.from(vec([1, 2, 3]).buffer).toString("base64") }; + await kv.set(vectorBucketScope(bucketCount - 1), entry.id, entry); + let active = 0, peak = 0; + const store = { + ...kv, + durability: { completion }, + async list(scope: string) { + peak = Math.max(peak, ++active); + try { + return await kv.list(scope); + } finally { + active--; + } + }, + }; + + const loaded = await new IndexPersistence(store as never, new VectorIndex()).load(); + expect(peak).toBe(expectedPeak); + expect(loaded.state).toBe("buckets"); + expect(loaded.vector?.get(entry.id)?.embedding).toEqual(vec([1, 2, 3])); + }, + ); + + it("stops SDK checkpoint reads on the first failure without publishing a partial index", async () => { + await kv.set(INDEX_SCOPE, META_KEY, { v: 3, bucketCount: 12, count: 0 }); + kv.ops.length = 0; + const visited: string[] = []; + const store = { + ...kv, + durability: { completion: "sdk" }, + async list(scope: string) { + visited.push(scope); + if (scope === vectorBucketScope(2)) throw new Error("SDK read timed out"); + return kv.list(scope); + }, + }; + + const loaded = await new IndexPersistence(store as never, new VectorIndex()).load(); + expect(loaded).toEqual({ vector: null, state: "unavailable", savedAt: null }); + expect(visited).toEqual([0, 1, 2].map(vectorBucketScope)); + expect(kv.ops.every(({ op }) => op === "list")).toBe(true); + }); + it("treats a missing store as empty, including adapters that return undefined", async () => { const undefinedKv = { ...kv, get: async () => undefined }; const loaded = await new IndexPersistence(undefinedKv as never, new VectorIndex(), { bucketSize: 16 }).load(); diff --git a/test/operations-background-control.test.ts b/test/operations-background-control.test.ts index 1f8cbd061f..f323b56e5e 100644 --- a/test/operations-background-control.test.ts +++ b/test/operations-background-control.test.ts @@ -11,6 +11,14 @@ function fixture(saved: unknown = null) { } describe("background transition status and safe diagnostics", () => { + it('changes storage generation on storage failure but not a successful manual pause',async()=>{ + const f=fixture({paused:false});const control=createBackgroundControl();await control.init(f.kv); + const initial=control.generation();await control.change('pause');await control.settled(); + expect(control.generation()).toBe(initial); + f.kv.durability.wait=async()=>{throw Error('synthetic_storage_failure')}; + await expect(control.change('resume')).rejects.toThrow(); + expect(control.generation()).toBeGreaterThan(initial); + }); it("keeps cold-start admission closed until the crash guard reaches disk", async () => { const f = fixture({ paused: false }), disk = gate(); f.kv.durability.waitForKeys = async () => { await disk.promise; }; @@ -148,3 +156,25 @@ it('fails closed when the full-dirty wait API is unavailable',async()=>{ const f=fixture({paused:true});delete (f.kv.durability as any).wait;const control=createBackgroundControl();await control.init(f.kv); await expect(control.change('resume')).rejects.toThrow('background_storage_unavailable');expect(control.snapshot()).toMatchObject({status:'error',pausedRequested:true}); }); + +describe('explicit resume vector recovery handoff',()=>{ + it('runs vector recovery after a successful explicit release',async()=>{ + const f=fixture({version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}),control=createBackgroundControl();await control.init(f.kv);const handlers=new Map();const resume=vi.fn(async()=>true); + registerBackgroundControlApi({registerFunction:(id:string,fn:any)=>handlers.set(id,fn),registerTrigger:()=>{}} as any,'fixture',control,resume); + const out=await handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body:{action:'resume'}}); + expect(resume).toHaveBeenCalledOnce();expect(out).toMatchObject({status_code:202,body:{success:true,vectorRecovery:'replay_complete_backfill_pending',control:{status:'running'}}}); + }); + it('keeps admission held when vector recovery fails',async()=>{ + const f=fixture({version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}),control=createBackgroundControl();await control.init(f.kv);const handlers=new Map(); + registerBackgroundControlApi({registerFunction:(id:string,fn:any)=>handlers.set(id,fn),registerTrigger:()=>{}} as any,'fixture',control,async()=>false); + const out=await handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body:{action:'resume'}}); + expect(out).toMatchObject({status_code:503,body:{success:false,error:'vector_recovery_unavailable',control:{status:'error',pausedRequested:true,holds:['storage_error']}}}); + }); +}); + +it('keeps background admission closed until explicit vector recovery completes',async()=>{const f=fixture({version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}),control=createBackgroundControl();await control.init(f.kv);const handlers=new Map(),pending=gate(),entered=gate();registerBackgroundControlApi({registerFunction:(id:string,fn:any)=>handlers.set(id,fn),registerTrigger:()=>{}} as any,'fixture',control,async()=>{entered.resolve();await pending.promise;return true});const request=handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body:{action:'resume'}});await entered.promise;expect(control.snapshot()).toMatchObject({status:'resuming',pausedRequested:true});expect(await control.run(()=>42)).toMatchObject({deferred:true});pending.resolve();expect(await request).toMatchObject({status_code:202,body:{success:true,control:{status:'running'}}})}); +it('retains a new pause requested during vector resume',async()=>{const f=fixture({version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}),control=createBackgroundControl();await control.init(f.kv);const handlers=new Map(),pending=gate(),entered=gate();registerBackgroundControlApi({registerFunction:(id:string,fn:any)=>handlers.set(id,fn),registerTrigger:()=>{}} as any,'fixture',control,async()=>{entered.resolve();await pending.promise;return true});const request=handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body:{action:'resume'}});await entered.promise;const pause=control.change('pause');pending.resolve();const response=await request;await pause;expect(response.status_code).toBe(202);expect(control.snapshot()).toMatchObject({status:'paused',pausedRequested:true,holds:['manual'],error:null})}); +it('rejects new foreground vector-writing work before its handler while storage is held',async()=>{const {installBackgroundControl,controlBackgroundFunctions}=await import('../src/ops/background-control.mjs');const f=fixture({version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}),control=createBackgroundControl();await control.init(f.kv);installBackgroundControl(control);const handlers=new Map(),run=vi.fn(async()=>({success:true}));const sdk={registerFunction:(id:string,fn:any)=>handlers.set(id,fn)};controlBackgroundFunctions(sdk as any);sdk.registerFunction('mem::remember',run);const result=await handlers.get('mem::remember')({content:'synthetic'});expect(result).toMatchObject({success:false,error:'vector_recovery_paused',retryable:true});expect(run).not.toHaveBeenCalled()}); +it('reports a potentially partial vector-writing request if storage fails while it runs',async()=>{const {installBackgroundControl,controlBackgroundFunctions}=await import('../src/ops/background-control.mjs');const f=fixture({paused:false}),control=createBackgroundControl();await control.init(f.kv);installBackgroundControl(control);const handlers=new Map(),entered=gate(),release=gate();const sdk={registerFunction:(id:string,fn:any)=>handlers.set(id,fn)};controlBackgroundFunctions(sdk as any);sdk.registerFunction('mem::remember',async()=>{entered.resolve();await release.promise;return {success:true,memory:{id:'synthetic'}}});const running=handlers.get('mem::remember')({content:'synthetic'});await entered.promise;f.kv.set=async()=>{throw Error('synthetic failure')};await expect(control.change('pause')).rejects.toThrow();release.resolve();expect(await running).toMatchObject({success:false,error:'vector_recovery_interrupted',partial:true,retryable:false})}); +it('refuses vector resume while an earlier foreground vector write remains active',async()=>{const {installBackgroundControl,controlBackgroundFunctions}=await import('../src/ops/background-control.mjs');const f=fixture({paused:false}),control=createBackgroundControl();await control.init(f.kv);installBackgroundControl(control);const handlers=new Map(),entered=gate(),release=gate(),resume=vi.fn(async()=>true);const sdk={registerFunction:(id:string,fn:any)=>handlers.set(id,fn),registerTrigger:()=>{}};controlBackgroundFunctions(sdk as any);sdk.registerFunction('mem::remember',async()=>{entered.resolve();await release.promise;return{success:true}});registerBackgroundControlApi(sdk as any,'fixture',control,resume);const work=handlers.get('mem::remember')({content:'synthetic'});await entered.promise;const set=f.kv.set;f.kv.set=async()=>{throw Error('storage failed')};await expect(control.change('pause')).rejects.toThrow();f.kv.set=set;const response=await handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body:{action:'resume'}});expect(response).toMatchObject({status_code:409,body:{error:'background_draining',control:{pausedRequested:true}}});expect(resume).not.toHaveBeenCalled();release.resolve();await work;expect(control.snapshot().holds).toContain('storage_error')}); +it.each(['mem::import','mem::replay::import-jsonl'])('rejects %s before import during storage recovery',async(id)=>{const {installBackgroundControl,controlBackgroundFunctions}=await import('../src/ops/background-control.mjs');const f=fixture({version:2,paused:false,resumePending:true,holds:[],recovery:{attempts:0,nextAttemptAt:0}}),control=createBackgroundControl();await control.init(f.kv);installBackgroundControl(control);const handlers=new Map(),run=vi.fn(async()=>({success:true}));const sdk={registerFunction:(name:string,fn:any)=>handlers.set(name,fn)};controlBackgroundFunctions(sdk as any);sdk.registerFunction(id,run);expect(await handlers.get(id)({})).toMatchObject({success:false,error:'vector_recovery_paused',retryable:true});expect(run).not.toHaveBeenCalled()}); diff --git a/test/operations-protection-recovery.test.ts b/test/operations-protection-recovery.test.ts index a2e5457e34..c0c80592b4 100644 --- a/test/operations-protection-recovery.test.ts +++ b/test/operations-protection-recovery.test.ts @@ -42,7 +42,70 @@ it('rechecks fresh pressure during activation and preserves memory hold if high }); it('persists storage failures as a hold and requires manual recovery',async()=>{ const f=fixture();await f.control.init(f.kv);f.kv.durability.wait=async()=>{throw Error('synthetic');};await f.guard.refresh();await f.control.settled();expect(f.control.snapshot().holds).toContain('storage_error'); - f.kv.durability.wait=async()=>({synced:true,mutationFailures:0});await f.normal();expect(f.control.isPaused()).toBe(true);await f.control.change('resume');expect(f.control.snapshot().holds).toEqual(['memory']); + f.kv.durability.wait=async()=>({synced:true,mutationFailures:0});await f.normal(); + expect(f.control.snapshot()).toMatchObject({status:'error',pausedRequested:true,holds:['storage_error']}); + let recoveries=0;await f.control.change('resume',{beforeResume:async()=>{recoveries++;return true;}}); + expect(recoveries).toBe(1);expect(f.control.snapshot().holds).toEqual([]); +}); + +it.each([false,true])('releases only recovered memory after held boot with resumePending=%s',async resumePending=>{ + const holds=['memory','storage_error']; + const f=fixture({version:2,paused:true,resumePending,holds,recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);await f.normal(115000);expect(f.control.snapshot().holds).toEqual(holds); + f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain(); + expect(f.control.snapshot()).toMatchObject({status:'error',pausedRequested:true,holds:['storage_error']}); + expect(await f.control.run(async()=>42)).toMatchObject({deferred:true}); + expect(await f.control.runVectorWrite(async()=>42)).toMatchObject({success:false}); + // An unclean restart must recheck memory even after this worker observed recovery. + const restarted=fixture(f.record());await restarted.control.init(restarted.kv); + expect(restarted.control.snapshot()).toMatchObject({status:'error',holds}); +}); + +it.each(['pressure','stale','pause','failed_fence'])('retains both holds on %s during compound memory recovery',async risk=>{ + const holds=['memory','storage_error']; + const f=fixture({version:2,paused:true,resumePending:true,holds,recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);await f.normal(115000); + let waits=0; + f.kv.durability.wait=async()=>{ + if(++waits===1){ + if(risk==='pressure')f.memory(GiB); + if(risk==='stale')f.time(f.clock()+10001); + if(risk==='pause')void f.control.change('pause',{source:'manual'}); + if(risk==='failed_fence')throw Error('synthetic storage failure'); + } + return {synced:true,mutationFailures:0}; + }; + f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain();await f.control.settled(); + expect(waits).toBeGreaterThan(0); + const expected=risk==='pause'?['manual',...holds]:holds; + expect(f.control.snapshot()).toMatchObject({status:'error',holds:expected,pausedRequested:true}); + expect(f.record().holds).toEqual(expected); +}); + +it('reports an unconfirmed rollback and keeps both holds when compound recovery loses storage',async()=>{ + const holds=['memory','storage_error']; + const f=fixture({version:2,paused:true,resumePending:true,holds,recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);await f.normal(115000); + f.kv.durability.wait=async()=>{f.fail(true);throw Error('fence unavailable');}; + f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain(); + expect(f.control.snapshot()).toMatchObject({holds,pausedRequested:true,diagnostics:{rollbackVerified:false}}); + expect(f.record()).toMatchObject({holds,paused:true,resumePending:true}); +}); + +it('requires a new manual resume after compound memory recovery completes',async()=>{ + const holds=['memory','storage_error']; + const f=fixture({version:2,paused:true,resumePending:true,holds,recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv); + let release!:()=>void; + const fence=new Promise(r=>{release=r;}); + f.kv.durability.wait=async()=>{await fence;return {synced:true,mutationFailures:0};}; + const partial=f.control.change('resume',{source:'memory',canResume:async()=>true}); + await new Promise(r=>setImmediate(r)); + let vectorAttempts=0; + const queued=f.control.change('resume',{beforeResume:async()=>{vectorAttempts++;return true;}}); + release();await partial;await queued; + expect(f.control.snapshot()).toMatchObject({holds:['storage_error'],pausedRequested:true}); + expect(vectorAttempts).toBe(0); }); it('bounds automatic attempts durably and honors persisted backoff',async()=>{ const f=fixture({version:2,paused:true,resumePending:false,holds:['memory'],recovery:{attempts:3,nextAttemptAt:0}});await f.control.init(f.kv);await f.normal();expect(f.control.isPaused()).toBe(true); diff --git a/test/sdk-delivery-v2.test.ts b/test/sdk-delivery-v2.test.ts index ed3b8962ad..23498b6b1c 100644 --- a/test/sdk-delivery-v2.test.ts +++ b/test/sdk-delivery-v2.test.ts @@ -16,3 +16,4 @@ it('treats mismatched event or disk-like ACKs as held and preserves original',as it('preserves prior source and makes no POST for a conflicting payload',async()=>{const m=await api();await m.deliverSdkCaptureV2(target,body(),async(b:any)=>ack(b),{dir});let calls=0;const changed={...body(),data:{image_data:'different'}};const r=await m.deliverSdkCaptureV2(target,changed,async()=>{calls++;return ack(changed)},{dir});expect(r).toMatchObject({outcome:'held',code:'SOURCE_CONFLICT'});expect(calls).toBe(0);}); it('does not POST if reference quota is full even though source retention succeeded',async()=>{const m=await api();let calls=0;await new m.SdkSpoolV2({dir}).usage();const orphan=join(dir,'queue','synthetic-partial.tmp');const fd=openSync(orphan,'wx',0o600);try{ftruncateSync(fd,5*1024*1024)}finally{closeSync(fd)}const r=await m.deliverSdkCaptureV2(target,body(),async(b:any)=>{calls++;return ack(b)},{dir});expect(r).toMatchObject({outcome:'dropped',sourceAcknowledged:true,code:'QUEUE_FULL'});expect(calls).toBe(0);expect((await new m.SdkSpoolV2({dir}).usage()).originalBytes).toBeGreaterThan(300*1024);}); it('refuses large/image guarded restore without POST or source deletion',async()=>{const m=await api();let calls=0;await m.deliverSdkCaptureV2(target,body(),async()=>({status:0,body:null,notSent:true}),{dir});const store=new m.SdkSpoolV2({dir}),id=(await store.pending(target))[0].sourceId;const before=await store.usage();const r=await m.restoreSdkCaptureV2(target,id,async()=>{calls++;return ack(body())},{dir});expect(r).toMatchObject({completed:false,status:'held',code:'SDK_SOURCE_FORMAT_UNSUPPORTED'});expect(calls).toBe(0);expect(await store.usage()).toEqual(before);}); +it('parks the original and does not auto-retry an explicit uncertain capture outcome',async()=>{const m=await api();const b=body('synthetic-uncertain',8),post=vi.fn(async()=>({status:422,body:{eventId:b.eventId,status:'rejected',retryable:false,error:'capture_reconciliation_required',reconciliationRequired:true}}));const r=await m.deliverSdkCaptureV2(target,b,post,{dir});expect(r).toMatchObject({outcome:'held',sourceAcknowledged:true,code:'SDK_ACK_UNVERIFIED'});const store=new m.SdkSpoolV2({dir}),pending=await store.pending(target);expect(pending).toHaveLength(1);expect(pending[0].state).toBe('held');expect(await store.load(target,pending[0].sourceId)).toEqual(b);expect((await m.deliverSdkCaptureV2(target,b,post,{dir})).outcome).toBe('held');expect(post).toHaveBeenCalledTimes(1)}); diff --git a/test/status.test.ts b/test/status.test.ts index 8ded5c9e49..62fc8a03f2 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -531,7 +531,7 @@ describe("status wiring", () => { it("streams reports with cached-only health ticks and explicit snapshot scans", () => { const streams = readFileSync("src/triggers/viewer-streams.ts", "utf-8"); - expect(streams).toMatch(/statusReport\(\{ health: snapshot, scanMaxAgeMs, scanUnindexed, functionMetrics:metricsRead \}\)/); + expect(streams).toMatch(/statusReport\(\{ health: snapshot, scanMaxAgeMs, scanUnindexed, scanCaptureInbox:false, functionMetrics:metricsRead \}\)/); expect(streams).toContain("healthPayload(payload.new_value ?? null, HEALTH_TICK_SCAN_MAX_AGE_MS, false)"); expect(streams).toContain("healthPayload(health ?? null, UNINDEXED_SCAN_REUSE_MS)"); }); diff --git a/test/storage-hold-transitions-regression.test.ts b/test/storage-hold-transitions-regression.test.ts new file mode 100644 index 0000000000..561e07f36f --- /dev/null +++ b/test/storage-hold-transitions-regression.test.ts @@ -0,0 +1,7 @@ +import {it,expect,vi} from 'vitest'; +import {createBackgroundControl} from '../src/ops/background-control.mjs'; +function fixture(holds:string[]){let saved:any={version:2,paused:true,resumePending:false,holds,recovery:{attempts:0,nextAttemptAt:0}};return {get:async()=>saved,set:async(_s:string,_k:string,v:any)=>{saved=v},durability:{wait:async()=>({synced:true,mutationFailures:0}),waitForKeys:async()=>{}}};} +it('reports a persisted storage error after boot and a subsequent pause',async()=>{const c=createBackgroundControl();await c.init(fixture(['storage_error']) as any);expect(c.snapshot()).toMatchObject({status:'error',error:'background_storage_unavailable',holds:['storage_error']});await c.change('pause',{source:'deployment'});await c.settled();expect(c.snapshot()).toMatchObject({status:'error',error:'background_storage_unavailable'});}); +it('does not release a storage hold as part of a partial resume without vector recovery',async()=>{const c=createBackgroundControl();await c.init(fixture(['memory','storage_error']) as any);const recovery=vi.fn(async()=>false);await expect(c.change('resume',{source:'manual',beforeResume:recovery})).rejects.toThrow();expect(recovery).not.toHaveBeenCalled();expect(c.snapshot().holds).toContain('storage_error');}); +it('reports a failed resume as pending until rollback confirmation completes',async()=>{let calls=0,release!:()=>void,entered!:()=>void;const arrived=new Promise(r=>entered=r),wait=new Promise(r=>release=r);const s=fixture(['storage_error']);s.durability.wait=async()=>({synced:false,mutationFailures:0});s.durability.waitForKeys=async()=>{if(++calls===2){entered();await wait;}};const c=createBackgroundControl();await c.init(s as any);const change=c.change('resume',{beforeResume:async()=>true});const caught=change.catch(()=>{});await arrived;expect(c.snapshot().transition).toMatchObject({pending:true});release();await caught;expect(c.snapshot().transition).toMatchObject({pending:false});}); +it('explains the other hold when refusing a partial storage recovery via API',async()=>{const c=createBackgroundControl();await c.init(fixture(['memory','storage_error']) as any);const {registerBackgroundControlApi}=await import('../src/ops/background-control.mjs');const handlers=new Map();registerBackgroundControlApi({registerFunction:(id:string,f:any)=>handlers.set(id,f),registerTrigger:()=>{}} as any,'fixture',c,async()=>true);const out=await handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body:{action:'resume'}});expect(out).toMatchObject({status_code:409,body:{error:'background_storage_recovery_requires_full_resume',control:{holds:['memory','storage_error']}}});}); diff --git a/test/vector-pending-log.test.ts b/test/vector-pending-log.test.ts index 8f39300d07..a8a3d4e125 100644 --- a/test/vector-pending-log.test.ts +++ b/test/vector-pending-log.test.ts @@ -1,6 +1,7 @@ import { describe, it, expect, afterEach, vi } from "vitest"; import { IndexPersistence } from "../src/state/index-persistence.js"; import { VectorIndex } from "../src/state/vector-index.js"; +import { createStateDurabilityFence } from "../src/ops/state-durability.mjs"; import { backfillVectorBacklog, getPendingVectorBackfillCount, @@ -69,6 +70,79 @@ describe("pending vector log", () => { setIndexPersistence(null); }); + it('keeps pending records and refuses vector recovery during storage-held startup', async () => { + const kv=mockKV();const original={q:1,id:'obs_held',s:'ses_held',e:Buffer.from(v(1).buffer).toString('base64')}; + await kv.set(PENDING_SCOPE,'obs_held',original);const before=structuredClone(original); + const vector=new VectorIndex();const persistence=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>true} as never); + try{ + const loaded=await persistence.load();await persistence.prepareBackfill(loaded);await persistence.replayPendingLog(3);await persistence.save(); + expect(pendingRows(kv).get('obs_held')).toEqual(before);expect(vector.size).toBe(0);expect(persistence.isRecoveryPaused()).toBe(true); + expect((persistence.status() as {pendingLogKnown?:boolean}).pendingLogKnown).toBe(false); + expect(persistence.status().pendingLog).toBeUndefined(); + expect(persistence.status().pendingLogAcknowledged).toBeUndefined(); + expect(kv.ops.filter(x=>x.op==='delete'&&x.scope===PENDING_SCOPE)).toEqual([]); + }finally{persistence.stop()} + }); + + it('retains every pending original and refuses replay when a pending row is malformed',async()=>{ + const kv=mockKV(),invalid={q:'malformed',c:1},valid={q:1,id:'obs_valid',s:'s',e:Buffer.from(v(1).buffer).toString('base64')}; + await kv.set(PENDING_SCOPE,'~clear',invalid);await kv.set(PENDING_SCOPE,'obs_valid',valid); + const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true}); + try{await p.prepareBackfill(await p.load());await p.replayPendingLog(3);await p.save();expect(pendingRows(kv).get('~clear')).toEqual(invalid);expect(pendingRows(kv).get('obs_valid')).toEqual(valid);expect(vector.has('obs_valid')).toBe(false);expect(p.isRecoveryPaused()).toBe(true);expect(p.status().pendingLogKnown).toBe(false)}finally{p.stop()} + }); + it('retains all pending originals when an embedding is undecodable',async()=>{ + const kv=mockKV(),invalid={q:1,id:'obs_bad',s:'s',e:'%%%'},valid={q:2,id:'obs_ok',s:'s',e:Buffer.from(v(1).buffer).toString('base64')}; + await kv.set(PENDING_SCOPE,'obs_bad',invalid);await kv.set(PENDING_SCOPE,'obs_ok',valid); + const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true}); + try{await p.prepareBackfill(await p.load());await p.replayPendingLog(3);await p.save();expect(pendingRows(kv).get('obs_bad')).toEqual(invalid);expect(pendingRows(kv).get('obs_ok')).toEqual(valid);expect(vector.size).toBe(0);expect(p.isRecoveryPaused()).toBe(true);expect(p.status().pendingLogKnown).toBe(false)}finally{p.stop()} + }); + + it('retains healthy startup replay when no storage hold is present', async () => { + const kv=mockKV();const original={q:1,id:'obs_healthy',s:'ses_healthy',e:Buffer.from(v(1).buffer).toString('base64')}; + await kv.set(PENDING_SCOPE,'obs_healthy',original);const vector=new VectorIndex(); + const persistence=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>false} as never); + try{const loaded=await persistence.load();await persistence.prepareBackfill(loaded);const replay=await persistence.replayPendingLog(3);expect(replay.added).toBe(1);expect(vector.has('obs_healthy')).toBe(true);expect(persistence.isRecoveryPaused()).toBe(false)}finally{persistence.stop()} + }); + + it('does not apply replay read when a storage hold appears before the read returns', async () => { + const kv=mockKV();const original={q:1,id:'obs_race',s:'ses_race',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_race',original); + let held=false,release!:()=>void,entered!:()=>void;const wait=new Promise(r=>release=r),started=new Promise(r=>entered=r),base=kv.list; + kv.list=async (scope:string)=>{if(scope===PENDING_SCOPE){entered();await wait}return base(scope)}; + const vector=new VectorIndex(),persistence=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never); + try{await persistence.prepareBackfill(await persistence.load());const replay=persistence.replayPendingLog(3);await started;held=true;release();await replay;await persistence.save();expect(vector.has('obs_race')).toBe(false);expect(pendingRows(kv).get('obs_race')).toEqual(original);expect(persistence.isRecoveryPaused()).toBe(true)}finally{persistence.stop()} + }); + + it('retains pending entries if a storage hold arrives during a checkpoint write', async () => { + const kv=mockKV(),original={q:1,id:'obs_during_save',s:'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_during_save',original); + let held=false,release!:()=>void,entered!:()=>void;const wait=new Promise(r=>release=r),started=new Promise(r=>entered=r),base=kv.set; + kv.set=async (scope:string,key:string,data:T)=>{if(scope===INDEX_SCOPE&&key==='vectors:meta'){entered();await wait}return base(scope,key,data)}; + const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never); + try{await p.prepareBackfill(await p.load());await p.replayPendingLog(3);const saving=p.save();await started;held=true;release();await saving;expect(pendingRows(kv).get('obs_during_save')).toEqual(original);expect(p.isRecoveryPaused()).toBe(true)}finally{p.stop()} + }); + + it('characterizes unresolved delete already sent when storage hold appears', async () => { + const kv=mockKV(),original={q:1,id:'obs_inflight',s:'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_inflight',original); + let held=false,release!:()=>void,entered!:()=>void;const wait=new Promise(r=>release=r),started=new Promise(r=>entered=r),base=kv.delete; + kv.delete=async(scope:string,key:string)=>{if(scope===PENDING_SCOPE&&key==='obs_inflight'){entered();await wait}await base(scope,key)}; + const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never); + try{await p.prepareBackfill(await p.load());await p.replayPendingLog(3);const saving=p.save();await started;held=true;release();await saving;expect(pendingRows(kv).has('obs_inflight')).toBe(false)}finally{p.stop()} + }); + + it('characterizes a transient storage hold missed between asynchronous checks', async () => { + const kv=mockKV(),original={q:1,id:'obs_aba',s:'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_aba',original); + let held=false,release!:()=>void,entered!:()=>void;const wait=new Promise(r=>release=r),started=new Promise(r=>entered=r),base=kv.list; + kv.list=async(scope:string)=>{if(scope===PENDING_SCOPE){entered();await wait}return base(scope)}; + const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never); + try{await p.prepareBackfill(await p.load());const replay=p.replayPendingLog(3);await started;held=true;held=false;release();await replay;expect(vector.has('obs_aba')).toBe(true)}finally{p.stop()} + }); + it('rejects replay when the admitted hold generation changes during a read', async () => { + const kv=mockKV(),original={q:1,id:'obs_epoch',s:'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_epoch',original); + let held=false,generation=0,release!:()=>void,entered!:()=>void;const wait=new Promise(r=>release=r),started=new Promise(r=>entered=r),base=kv.list; + kv.list=async(scope:string)=>{if(scope===PENDING_SCOPE){entered();await wait}return base(scope)}; + const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held,storageGeneration:()=>generation} as never); + try{await p.prepareBackfill(await p.load());const replay=p.replayPendingLog(3);await started;held=true;generation++;held=false;release();await replay;expect(vector.has('obs_epoch')).toBe(false);expect(pendingRows(kv).get('obs_epoch')).toEqual(original);expect(p.isRecoveryPaused()).toBe(true)}finally{p.stop()} + }); + it("writes a compact entry for every added vector and a tombstone for every removal", async () => { const kv = mockKV(); const vector = new VectorIndex(); @@ -233,7 +307,7 @@ describe("pending vector log", () => { expect([...third.vector.entries()].map(([id]) => id).sort()).toEqual(["obs_2", "obs_3", "obs_4"]); }); - it("skips logged vectors whose dimension does not match the active provider", async () => { + it("preserves the pending log when any vector dimension does not match", async () => { const kv = mockKV(); const first = await boot(kv); first.vector.add("obs_ok", "ses_1", v(1)); @@ -244,7 +318,10 @@ describe("pending vector log", () => { const persistence = new IndexPersistence(kv as never, vector); await persistence.load(); const replay = await persistence.replayPendingLog(3); - expect(replay).toMatchObject({ added: 1, skipped: 1 }); + expect(replay).toMatchObject({ added: 0 }); + expect(persistence.isRecoveryPaused()).toBe(true); + expect(pendingRows(kv).size).toBe(2); + expect(vector.has("obs_ok")).toBe(false); expect(vector.has("obs_wide")).toBe(false); }); @@ -449,3 +526,92 @@ describe("durable vector backlog", () => { } }); }); + +describe("SDK-only release after a storage hold", () => { + function fixture() { + const kv = Object.assign(mockKV(), { + durability: createStateDurabilityFence({ storePath: "/unused-synthetic-sdk-store", completion: "sdk" }), + }); + let held = true; + const vector = new VectorIndex(); + const persistence = new IndexPersistence(kv as never, vector, { + requireRecoveryPlan: true, isStorageHeld: () => held, saveIntervalMs: 600_000, + }); + return { kv, vector, persistence, release: () => { held = false; } }; + } + + it("retains three original pending records before any checkpoint writes or replay", async () => { + const { kv, vector, persistence, release } = fixture(); + for (const [q, id] of ["first", "second", "third"].entries()) { + await kv.set(PENDING_SCOPE, id, { q: q + 1, id, s: "test", e: Buffer.from(v(q).buffer).toString("base64") }); + } + const original = new Map(pendingRows(kv)); + try { + await persistence.load(); + release(); + kv.ops.length = 0; + const resumed = await persistence.resumeStorageRecovery(3); + await persistence.save(); + expect(pendingRows(kv)).toEqual(original); + expect(resumed).toBe(false); + expect(persistence.status().vector?.lastError).toContain("durable reconciliation"); + expect(vector.size).toBe(0); + expect(kv.ops.filter(op => op.op !== "list")).toEqual([]); + expect(persistence.isRecoveryPaused()).toBe(true); + } finally { persistence.stop(); } + }); + + it.each(["failed read", "invalid response", "new row after first read"])("keeps the SDK release held for %s", async mode => { + const { kv, vector, persistence, release } = fixture(); + const list = kv.list; + let reads = 0; + kv.list = async scope => { + if (scope === PENDING_SCOPE) { + reads++; + if (mode === "failed read") throw new Error("synthetic timeout"); + if (mode === "invalid response") return null as never; + if (reads === 2) return [{ q: 1, id: "later", t: 1 }] as never; + } + return list(scope); + }; + try { + await persistence.load(); + release(); + expect(await persistence.resumeStorageRecovery(3)).toBe(false); + expect(persistence.isRecoveryPaused()).toBe(true); + expect(vector.size).toBe(0); + expect(kv.ops.some(op => op.op === "delete")).toBe(false); + expect(kv.ops.some(op => op.op === "set")).toBe(false); + } finally { persistence.stop(); } + }); + + it("allows SDK release when the pending namespace is empty", async () => { + const { persistence, release } = fixture(); + try { + await persistence.load(); + release(); + expect(await persistence.resumeStorageRecovery(3)).toBe(true); + expect(persistence.isRecoveryPaused()).toBe(false); + } finally { persistence.stop(); } + }); +}); + +describe('explicit storage recovery release',()=>{ + it('retries held startup recovery in the same process only after release',async()=>{ + const kv=mockKV(),row={q:1,id:'obs_resume',s:'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_resume',row); + let held=true,generation=0;const vector=new VectorIndex();const p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held,storageGeneration:()=>generation} as never); + try{await p.load();expect(await (p as any).resumeStorageRecovery(3)).toBe(false);expect(pendingRows(kv).get('obs_resume')).toEqual(row);held=false;generation++;expect(await (p as any).resumeStorageRecovery(3)).toBe(true);expect(vector.has('obs_resume')).toBe(true);expect(p.isRecoveryPaused()).toBe(false)}finally{p.stop()} + }); + it('rejects vector mutation before changing memory while storage is held',async()=>{ + const kv=mockKV(),vector=new VectorIndex();let held=true;const p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never); + try{expect(()=>vector.add('new','s',v(1))).toThrow(/VECTOR_RECOVERY_PAUSED/);expect(vector.has('new')).toBe(false);expect(pendingRows(kv).size).toBe(0)}finally{p.stop()} + }); + it('keeps recovery paused and originals intact when release reload fails',async()=>{ + const kv=mockKV(),row={q:1,id:'obs_fail',s:'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'obs_fail',row);let held=true;const vector=new VectorIndex();const p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never); + try{await p.load();held=false;kv.get=async()=>{throw Error('synthetic read failure')};expect(await (p as any).resumeStorageRecovery(3)).toBe(false);expect(p.isRecoveryPaused()).toBe(true);expect(pendingRows(kv).get('obs_fail')).toEqual(row);expect(vector.size).toBe(0)}finally{p.stop()} + }); +}); + +it('rejects foreground vector changes while a released storage checkpoint is loading',async()=>{const kv=mockKV();let held=true,release!:()=>void,entered!:()=>void;const wait=new Promise(r=>release=r),started=new Promise(r=>entered=r),get=kv.get;const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never);try{await p.load();held=false;kv.get=async(scope:string,key:string)=>{if(scope===INDEX_SCOPE&&key==='vectors:meta'){entered();await wait}return get(scope,key)};const resume=(p as any).resumeStorageRecovery(3);await started;expect(()=>vector.add('during','s',v(1))).toThrow(/VECTOR_RECOVERY_PAUSED/);expect(vector.has('during')).toBe(false);release();expect(await resume).toBe(true)}finally{p.stop()}}); +it('does not claim successful vector recovery when pending-log read fails',async()=>{const kv=mockKV();let held=true;const list=kv.list;const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never);try{await p.load();held=false;kv.list=async(scope:string)=>{if(scope===PENDING_SCOPE)throw Error('synthetic pending read failure');return list(scope)};expect(await (p as any).resumeStorageRecovery(3)).toBe(false);expect(p.isRecoveryPaused()).toBe(true)}finally{p.stop()}}); +it('allows an explicit retry after a transient pending-log read failure',async()=>{const kv=mockKV(),row={q:1,id:'retry','s':'s',e:Buffer.from(v(1).buffer).toString('base64')};await kv.set(PENDING_SCOPE,'retry',row);let held=true;const list=kv.list;const vector=new VectorIndex(),p=new IndexPersistence(kv as never,vector,{requireRecoveryPlan:true,isStorageHeld:()=>held} as never);try{await p.load();held=false;kv.list=async(scope:string)=>{if(scope===PENDING_SCOPE)throw Error('temporary');return list(scope)};expect(await (p as any).resumeStorageRecovery(3)).toBe(false);kv.list=list;expect(await (p as any).resumeStorageRecovery(3)).toBe(true);expect(vector.has('retry')).toBe(true);expect(p.status().pendingLogError).toBeNull()}finally{p.stop()}}); diff --git a/test/viewer-operations-browser.test.ts b/test/viewer-operations-browser.test.ts index 5ee3f295bb..300fa2f6c3 100644 --- a/test/viewer-operations-browser.test.ts +++ b/test/viewer-operations-browser.test.ts @@ -95,6 +95,10 @@ describe.skipIf(spawnSync('google-chrome',['--version'],{encoding:'utf8',timeout await send('Page.enable'); await send('Page.bringToFront'); while(!(await evaluate("document.readyState==='complete' && typeof loadOperations==='function'")) && Date.now()setTimeout(resolve,25)); + const unknownCapture=await evaluate("captureCardHtml({capture:{inbox:null,spool:[],sinceStart:{},policy:{}}})"); + expect(unknownCapture).toContain('not checked'); + expect(unknownCapture).toContain('Inbox status is unknown'); + expect(unknownCapture).not.toContain('Empty means every accepted observation is stored.'); await evaluate("(async()=>{await loadSnapshot();await loadOperations();switchTab('health');await showTab('health');setAutoRefresh(false,30);document.querySelector('#operations-details>summary').focus();})()"); expect(await evaluate("document.activeElement===document.querySelector('#operations-details>summary')")).toBe(true); await send('Input.dispatchKeyEvent',{type:'keyDown',key:'Enter',code:'Enter',text:'\r',windowsVirtualKeyCode:13}); From 62266a8b79d31df355af4131c247bd5e7f116bd8 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 7 Nov 2026 01:26:42 +0900 Subject: [PATCH 02/23] fix: recover verified vector checkpoints without consuming the pending log --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 6 +- CHANGELOG.md | 6 + assets/tags/light/stat-tests.svg | 4 +- assets/tags/stat-tests.svg | 4 +- docs/customizations/HOOK-UPSTREAM-20261102.md | 2 +- integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 10 +- src/capture/sdk-reconciliation.ts | 8 +- src/functions/capture.ts | 3 +- src/functions/export-import.ts | 2 +- src/functions/search.ts | 5 + src/index.ts | 7 +- src/ops/background-control.d.mts | 2 +- src/ops/background-control.mjs | 4 +- src/ops/vector-checkpoint-proof.d.mts | 8 + src/ops/vector-checkpoint-proof.mjs | 179 ++++++++++++++++++ src/state/index-persistence.ts | 151 +++++++++++++-- src/state/kv.ts | 44 ++++- src/state/schema.ts | 1 + src/state/vector-checkpoint-reconciliation.ts | 118 ++++++++++++ src/state/vector-index.ts | 12 +- src/types.ts | 5 +- src/version.ts | 2 +- test/capture-sdk-reconciliation.test.ts | 13 +- .../manual-vector-checkpoint-recovery.test.ts | 102 ++++++++++ test/operations-protection-recovery.test.ts | 18 ++ test/vector-checkpoint-proof.test.ts | 136 +++++++++++++ test/vector-checkpoint-transaction.test.ts | 99 ++++++++++ 41 files changed, 921 insertions(+), 62 deletions(-) create mode 100644 src/ops/vector-checkpoint-proof.d.mts create mode 100644 src/ops/vector-checkpoint-proof.mjs create mode 100644 src/state/vector-checkpoint-reconciliation.ts create mode 100644 test/manual-vector-checkpoint-recovery.test.ts create mode 100644 test/vector-checkpoint-proof.test.ts create mode 100644 test/vector-checkpoint-transaction.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index f9c42490a4..318589c7d1 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 6c09bb3aa5..d3f7ad3c50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,20 +108,20 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Testing -- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (6,300+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests. +- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (6,400+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests. - Before any npm publish: `npm run release:gate` must pass. It installs the packed tarballs into a clean home and runs capture, recovery, restart, export/import, MCP and status checks against the installed CLI (see CONTRIBUTING.md, Release process) - Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list` - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.58) +## Current Stats (v0.9.32-daniel.59) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 17 skills - 355+ iii functions -- 6,300+ tests +- 6,400+ tests ## Personal fork verification isolation diff --git a/CHANGELOG.md b/CHANGELOG.md index 83ff811f13..58d9d9d6ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## [Unreleased] +## [0.9.32-daniel.59] — 2026-11-07 (held recovery candidate) + +- Support explicit authenticated recovery of a bounded set of vector upserts whose pending and checkpoint records agree in the native store. Preserve the original upserts and record their verified coverage separately. Revalidate coverage on restart and distinguish retained records from pending publication in the index status. +- Require the current cooperative writer, stable checkpoint, matching physical keys and vector bytes. Conflicting updates, clears or incomplete evidence leave recovery blocked. Automatic recovery and deployment resume cannot authorize new coverage. +- Record the deployment and operational acceptance separately from this source candidate in the November 7 incident report. + ## [0.9.32-daniel.58] — 2026-11-06 (recovery review candidate) - Based on the installed .55 Git commit `4605974f337a50ed7e0ef74e3bb635b6e5d5a805` and the scoped .57 held-start changes from `3148e1d0a3df0241b69b2166085b10ed5979b99f`. This is a separate review candidate for the November 6 outage. diff --git a/assets/tags/light/stat-tests.svg b/assets/tags/light/stat-tests.svg index 2e4f03ca44..dd258f45c7 100644 --- a/assets/tags/light/stat-tests.svg +++ b/assets/tags/light/stat-tests.svg @@ -1,5 +1,5 @@ - + - 6300+ + 6400+ TESTS PASSING diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg index 94ef4cf9c3..92b7fab072 100644 --- a/assets/tags/stat-tests.svg +++ b/assets/tags/stat-tests.svg @@ -1,5 +1,5 @@ - + - 6300+ + 6400+ TESTS PASSING diff --git a/docs/customizations/HOOK-UPSTREAM-20261102.md b/docs/customizations/HOOK-UPSTREAM-20261102.md index a30109387c..461dbd1716 100644 --- a/docs/customizations/HOOK-UPSTREAM-20261102.md +++ b/docs/customizations/HOOK-UPSTREAM-20261102.md @@ -43,7 +43,7 @@ Website metadata now uses the same source-derived REST count as docs-sync's complete trigger-directory AST collector, rather than counting just three upstream trigger files and omitting personal endpoints. `npm run gen-meta` regenerated metadata as 0.9.31-daniel.51, 55 tools, 161 REST endpoints, 12 hooks -and 6300+ test cases. Unavailable live popularity requests retained their prior +and 6,300-plus test cases. Unavailable live popularity requests retained their prior values. No website dependencies were installed and no website build was run. Verification: five stale MCP fixture cases failed before the helper fix, then diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index e4439a3386..66d675a92d 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.58 +version: 0.9.32-daniel.59 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 4b47bd42bb..51739bf077 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index e751076164..e8673af14d 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 5e73efd16a..db771c2040 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index f8fafbefe5..c4ea427bcd 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.58 +version: 0.9.32-daniel.59 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 23c71719c5..d30a6cedcf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 02b72ab9d3..7f4e6010a1 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.58" + "@agentmemory/agentmemory": "0.9.32-daniel.59" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index a691428211..821be7f559 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index be3557f709..e74a3f5d54 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index bd882142e8..b4f6a59d36 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.58" + "@agentmemory/mcp@0.9.32-daniel.59" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 91b8a920ab..364f35d4e8 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index cac1987cba..65af56a678 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 6d9c8e03fe..7748138cc8 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.58"; +const VERSION = "0.9.32-daniel.59"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 56a454377f..e5e23b3a78 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.58", + "version": "0.9.32-daniel.59", "facts": { "mcpTools": [ "55" @@ -20,19 +20,19 @@ "12" ], "tests": [ - "6300+" + "6400+" ], "functions": [ "355" ], "sourceFiles": [ - "281" + "282" ], "loc": [ - "63000" + "64000" ], "kvScopes": [ - "70" + "71" ] }, "engineVersion": "0.25.0" diff --git a/src/capture/sdk-reconciliation.ts b/src/capture/sdk-reconciliation.ts index 4406b1e994..b129037577 100644 --- a/src/capture/sdk-reconciliation.ts +++ b/src/capture/sdk-reconciliation.ts @@ -25,7 +25,7 @@ export function sdkReconciliationInvocation(input:unknown):Selection{ return body; } -export function createSdkCaptureReconciliation(kv:StateKV,options:{admitted:()=>boolean;indexEvidence:(observation:CompressedObservation)=>{keyword:{present:boolean;sessionId?:string};vectorSessionId?:string};audit:(selection:{key:string;requestId:string})=>Promise;now?:()=>number}){ +export function createSdkCaptureReconciliation(kv:StateKV,options:{admitted:()=>boolean;verifyCaptureVectorPending?:(id:string,sessionId:string,pending:unknown)=>Promise;indexEvidence:(observation:CompressedObservation)=>{keyword:{present:boolean;sessionId?:string};vectorSessionId?:string};audit:(selection:{key:string;requestId:string})=>Promise;now?:()=>number}){ const now=()=>new Date((options.now??Date.now)()).toISOString(); function admitted(){ if(kv.durability?.completion!=='sdk')throw fail('SDK_RECONCILIATION_UNSUPPORTED'); @@ -50,7 +50,11 @@ export function createSdkCaptureReconciliation(kv:StateKV,options:{admitted:()=> if(done?.state==='deleted')throw fail('SDK_RECONCILIATION_DELETED'); if(done&&(done.key!==rec.key||done.eventId!==rec.eventId||done.sessionId!==rec.sessionId||done.observationId!==rec.observationId||done.state!==undefined&&done.state!=='completed'))throw fail('SDK_RECONCILIATION_RECEIPT_CONFLICT'); if(!sdkObservationMatches(obs,rec.payload,rec.key,rec.observationId,rec.eventId))throw fail('SDK_RECONCILIATION_SOURCE_CONFLICT'); - if(retry!=null||pending!=null||clear!=null)throw fail('SDK_RECONCILIATION_INDEX_PENDING'); + if(retry!=null||clear!=null)throw fail('SDK_RECONCILIATION_INDEX_PENDING'); + const pendingVerified=options.verifyCaptureVectorPending + ? await options.verifyCaptureVectorPending(rec.observationId,rec.sessionId,pending) : pending==null; + if(!pendingVerified)throw fail('SDK_RECONCILIATION_INDEX_PENDING'); + admitted(); if(typeof obs!.title!=='string'||typeof obs!.narrative!=='string')throw fail('SDK_RECONCILIATION_SOURCE_CONFLICT'); const observedIndex=options.indexEvidence(obs!); const indexEvidence:CaptureSdkIndexEvidence={...observedIndex,vectorSessionId:observedIndex.vectorSessionId!,keyword:{...observedIndex.keyword,applicability:observationIndexEligible(obs!)?'required':obs!.title===''?(obs!.narrative===''?'excluded_empty_title_and_narrative':'excluded_empty_title'):'excluded_empty_narrative'}}; diff --git a/src/functions/capture.ts b/src/functions/capture.ts index 56782c5f94..06ac8b5339 100644 --- a/src/functions/capture.ts +++ b/src/functions/capture.ts @@ -4,7 +4,7 @@ import {recordAudit} from "./audit.js"; import {requireSdkSourceWriter,sameSdkSource,sdkObservationMatches,sdkSourceKeys,sdkSourceFailure,assertSdkSourceClaim,assertSdkSourceLegacyProtection} from "../capture/sdk-source-restore.js"; import{createSdkCaptureReconciliation,sdkReconciliationInvocation}from'../capture/sdk-reconciliation.js'; import {createCaptureAutoRecovery,type CaptureAutoRecoveryOptions} from "../capture/auto-recovery.js"; -import {getSearchIndex,getVectorIndex,getKeywordRebuildEpoch,isKeywordRebuildInProgress} from "./search.js"; +import {getSearchIndex,getVectorIndex,getKeywordRebuildEpoch,isKeywordRebuildInProgress,verifyCaptureVectorPending} from "./search.js"; import {createCaptureIndexEvidence,captureIndexEvidenceInvocationQuery} from "../capture/index-evidence.js"; import { createOutboxMetadata, type OutboxMetadata } from "../capture/outbox-metadata.js"; import { registerCaptureReceipts } from "../capture/receipts.js"; @@ -286,6 +286,7 @@ export function registerCaptureFunctions( } const trackMaintenance=(work:()=>Promise)=>{void trackWork(work).catch(()=>{});}; const sdkReconciliation=createSdkCaptureReconciliation(kv,{ + verifyCaptureVectorPending, admitted:()=>!stopped&&!backgroundPaused()&&(options.autoRecovery?.admitted()??true), indexEvidence:obs=>({keyword:{present:getSearchIndex().has(obs.id),sessionId:getSearchIndex().sessionOf(obs.id)},vectorSessionId:getVectorIndex()?.get(obs.id)?.sessionId}), audit:selection=>recordAudit(kv,'capture_sdk_reconciliation','api::capture-reconcile-sdk',[],{requestId:selection.requestId,completion:'sdk',stage:'verification_pending'}), diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index e37fdace2a..7a75aabfa0 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/functions/search.ts b/src/functions/search.ts index b305e37ff8..55f7c97ab1 100644 --- a/src/functions/search.ts +++ b/src/functions/search.ts @@ -189,6 +189,7 @@ type IndexPersistenceHook = { scheduleSave: () => void; save: () => Promise; status?: () => IndexPersistenceStatus; + verifyCaptureVectorPending?: (id: string, sessionId: string, pending: unknown) => Promise; }; let indexPersistence: IndexPersistenceHook | null = null; @@ -201,6 +202,10 @@ export function getIndexPersistenceStatus(): IndexPersistenceStatus | null { return indexPersistence?.status?.() ?? null; } +export async function verifyCaptureVectorPending(id: string, sessionId: string, pending: unknown): Promise { + return indexPersistence?.verifyCaptureVectorPending?.(id, sessionId, pending) ?? pending == null; +} + export function scheduleIndexSave(): void { indexPersistence?.scheduleSave(); } diff --git a/src/index.ts b/src/index.ts index 21b847d8d2..6f7bc2ad9f 100644 --- a/src/index.ts +++ b/src/index.ts @@ -567,7 +567,12 @@ async function main() { markKeywordRebuildPending(); registerApiTriggers(sdk, kv, secret, metricsStore, provider); registerDashboardUpdateApi(sdk, secret, createDashboardUpdates({requestRoot: runtimeMetadataPath("update-requests"), version: VERSION})); - if (persistentBackground) registerBackgroundControlApi(sdk, secret, control, async () => { await bootGate; if (bootFailed || !indexForExplicitResume || !scheduleBackfillAfterResume) return false; if (!await indexForExplicitResume.resumeStorageRecovery(embeddingProvider?.dimensions ?? 0)) return false; return scheduleBackfillAfterResume(); }); + if (persistentBackground) registerBackgroundControlApi(sdk, secret, control, async allowReconciliation => { + await bootGate; + if (bootFailed || !indexForExplicitResume || !scheduleBackfillAfterResume) return false; + if (!await indexForExplicitResume.resumeStorageRecovery(embeddingProvider?.dimensions ?? 0, allowReconciliation)) return false; + return scheduleBackfillAfterResume(); + }); if (getEnvVar("AGENTMEMORY_FEEDBACK_DIR")) { const feedback = lifecycle.track(registerFeedbackRuntime(sdk, secret, { root: getEnvVar("AGENTMEMORY_FEEDBACK_DIR"), diff --git a/src/ops/background-control.d.mts b/src/ops/background-control.d.mts index 1441e9740f..530f7e6702 100644 --- a/src/ops/background-control.d.mts +++ b/src/ops/background-control.d.mts @@ -21,4 +21,4 @@ export function backgroundPaused():boolean; export function backgroundTaskunknown>(fn:T):T; export function controlBackgroundFunctions(sdk:IIIClient):void; export function backgroundViewerRequestAllowed(req:HttpRequest):boolean; -export function registerBackgroundControlApi(sdk:IIIClient,secret:string,control:BackgroundControl,onExplicitResume?:()=>Promise):void; +export function registerBackgroundControlApi(sdk:IIIClient,secret:string,control:BackgroundControl,onExplicitResume?:(allowReconciliation:boolean)=>Promise):void; diff --git a/src/ops/background-control.mjs b/src/ops/background-control.mjs index d2cab85550..e56c19fed7 100644 --- a/src/ops/background-control.mjs +++ b/src/ops/background-control.mjs @@ -216,7 +216,9 @@ export function registerBackgroundControlApi(sdk,secret,control,onExplicitResume const body=req.body; if(!body||Array.isArray(body)||Object.keys(body).some(k=>!['action','reason'].includes(k))||body.reason!==undefined&&body.reason!=='deployment'||!['pause','resume'].includes(body.action))return{status_code:400,body:{error:'invalid_background_action'}}; try{ - const snapshot=await control.change(body.action,{source:body.reason??'manual',...(body.action==='resume'&&onExplicitResume?{beforeResume:onExplicitResume}:{})}); + const source=body.reason??'manual'; + const beforeResume=body.action==='resume'&&onExplicitResume?()=>onExplicitResume(source==='manual'):undefined; + const snapshot=await control.change(body.action,{source,beforeResume}); return{status_code:202,body:{success:true,control:snapshot,...(body.action==='resume'&&snapshot.status==='running'&&onExplicitResume?{vectorRecovery:'replay_complete_backfill_pending'}:{})}}; } catch(e){const conflict=['background_draining','background_storage_recovery_requires_full_resume'].includes(e?.message);return{status_code:conflict?409:503,body:{success:false,error:e?.code==='VECTOR_RECOVERY_UNAVAILABLE'?'vector_recovery_unavailable':conflict?e.message:'background_storage_unavailable',control:control.snapshot()}};} diff --git a/src/ops/vector-checkpoint-proof.d.mts b/src/ops/vector-checkpoint-proof.d.mts new file mode 100644 index 0000000000..80bfd2739f --- /dev/null +++ b/src/ops/vector-checkpoint-proof.d.mts @@ -0,0 +1,8 @@ +type Evidence = {storePath:string; pendingRows:readonly unknown[]; admitted:()=>boolean}; +export function verifyVectorCheckpointFiles(options: Evidence & { + meta:unknown; buckets:readonly {bucket:number; ids:readonly string[]}[]; +}):Promise<()=>Promise>; +export function verifyRemainingVectorPending(options: Evidence):Promise; +export function verifyVectorRetentionReceipts(options: { + storePath:string; receipts:Readonly>; admitted:()=>boolean; +}):Promise; diff --git a/src/ops/vector-checkpoint-proof.mjs b/src/ops/vector-checkpoint-proof.mjs new file mode 100644 index 0000000000..31a56d25f4 --- /dev/null +++ b/src/ops/vector-checkpoint-proof.mjs @@ -0,0 +1,179 @@ +import {createHash} from 'node:crypto'; +import {constants} from 'node:fs'; +import {open, lstat, realpath} from 'node:fs/promises'; +import {isAbsolute, join} from 'node:path'; +import {isDeepStrictEqual} from 'node:util'; + +const META = 'mem:index:bm25', PENDING = 'mem:index:vec-pending'; +const MiB = 1024 * 1024; +const READ_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK; +function requireProof(ok) { + if (!ok) throw Object.assign(new Error('VECTOR_CHECKPOINT_UNVERIFIED'), {code:'VECTOR_CHECKPOINT_UNVERIFIED'}); +} +const signature = s => [s.dev,s.ino,s.size,s.mtimeNs,s.ctimeNs].join(':'); + +// Native iii 0.22.1 stores KeyStorage(String) as a little-endian rkyv 0.8 archive. +// Accept only its canonical encoding. A valid JSON prefix alone cannot certify an archive. +function namespaceRows(bytes) { + requireProof(bytes.length >= 8 && bytes.length % 4 === 0); + const root = bytes.length - 8; + let length; + if (root === 0) { + length = bytes.indexOf(0xff); + if (length < 0) length = 8; + requireProof(bytes.subarray(length).every(b=>b===0xff)); + } else { + const size = bytes.readUInt32LE(root); + length = (size & 63) + Math.floor(size / 256) * 64; + requireProof((size & 192) === 128 && bytes.readInt32LE(root+4) === -root && + length > 8 && Math.ceil(length/4)*4 === root && bytes.subarray(length,root).every(b=>b===0)); + } + const json = new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes.subarray(0,length)); + const rows = JSON.parse(json); + // This narrow repair refuses duplicate keys, rounded numbers and noncanonical serializations. + requireProof(rows !== null && typeof rows === 'object' && !Array.isArray(rows) && JSON.stringify(rows) === json); + return rows; +} + +function pendingMap(rows) { + requireProof(Array.isArray(rows) && rows.length <= 16); + const byId = new Map(), sequences = new Set(); + for (const row of rows) { + requireProof(row && Object.keys(row).every(k=>['id','s','e','q','k'].includes(k)) && + typeof row.id === 'string' && row.id.length > 0 && row.id.length <= 1024 && row.id !== '~clear' && + typeof row.s === 'string' && row.s.length > 0 && row.s.length <= 1024 && + Number.isSafeInteger(row.q) && row.q > 0 && !sequences.has(row.q) && !byId.has(row.id) && + (row.k === undefined || row.k === 'memory' || row.k === 'observation') && + typeof row.e === 'string' && row.e.length > 0 && row.e.length <= 256*1024); + const embedding = Buffer.from(row.e,'base64'); + requireProof(embedding.length > 0 && embedding.length % 4 === 0 && embedding.toString('base64') === row.e); + for (let offset=0; offset0 && performance.now()=8 && size<=file.limit && total<=64*MiB); + const data=Buffer.allocUnsafe(size); + for(let offset=0;offset0 && performance.now() {await current();await verifyNames(storePath,true);await verifyNames(storePath);await current();}; +} + +export async function verifyVectorCheckpointFiles({storePath,pendingRows,meta,buckets,admitted}) { + const byId=pendingMap(pendingRows), selected=new Map(); + requireProof(byId.size>0 && meta?.v===3 && Number.isSafeInteger(meta.bucketCount) && meta.bucketCount>0 && + Number.isSafeInteger(meta.count) && meta.count>=byId.size && Array.isArray(buckets) && buckets.length>0 && buckets.length<=byId.size); + const expectedMeta=structuredClone(meta); + const files=[pendingFile(byId), {scope:META,limit:4*MiB,verify(rows){requireProof(isDeepStrictEqual(rows['vectors:meta'],expectedMeta));}}]; + const seenBuckets=new Set(); + for (const {bucket,ids} of buckets) { + requireProof(Number.isSafeInteger(bucket)&&bucket>=0&&bucket0&&ids.length<=byId.size); + seenBuckets.add(bucket); + for(const id of ids){requireProof(byId.has(id)&&!selected.has(id));selected.set(id,bucket);} + files.push({scope:META+':vec:'+String(bucket).padStart(4,'0'), limit:16*MiB, verify(rows) { + for (const [key,value] of Object.entries(rows)) { + if (!byId.has(key)&&!byId.has(value?.id))continue; + const row=byId.get(key); + requireProof(row && selected.get(key)===bucket && isDeepStrictEqual(value,{id:key,s:row.s,e:row.e})); + } + for(const [id,location] of selected)if(location===bucket)requireProof(Object.hasOwn(rows,id)); + }}); + } + requireProof(selected.size===byId.size); + return prove(storePath,admitted,files); +} + +export async function verifyRemainingVectorPending({storePath,pendingRows,admitted}) { + const verify=await prove(storePath,admitted,[pendingFile(pendingMap(pendingRows))]); + await verify(); +} + +export async function verifyVectorRetentionReceipts({storePath,receipts,admitted}) { + requireProof(receipts && typeof receipts === 'object' && + (Object.getPrototypeOf(receipts) === Object.prototype || Object.getPrototypeOf(receipts) === null)); + const entries = Object.entries(receipts); + requireProof(entries.length <= 16 && entries.length === Reflect.ownKeys(receipts).length); + const ids = new Set(), sequences = new Set(); + const expected = {}; + for (const [key, row] of entries) { + requireProof(key.length === 64 && /^[a-f0-9]+$/.test(key) && + row && typeof row === 'object' && Reflect.ownKeys(row).length === 5 && Object.keys(row).length === 5 && + ['v','id','q','bucket','digest'].every(field => Object.hasOwn(row,field)) && + row.v === 1 && row.digest === key && typeof row.id === 'string' && + row.id.length > 0 && row.id.length <= 512 && row.id !== '~clear' && !ids.has(row.id) && + Number.isSafeInteger(row.q) && row.q > 0 && !sequences.has(row.q) && + Number.isSafeInteger(row.bucket) && row.bucket >= 0); + ids.add(row.id); + sequences.add(row.q); + expected[key] = {...row}; + } + const recheck = await prove(storePath,admitted,[{ + scope:'mem:index:vec-retained:v1', limit:128*1024, allowMissing:entries.length === 0, + verify(rows) { requireProof(isDeepStrictEqual(rows,expected)); } + }]); + await recheck(); +} diff --git a/src/state/index-persistence.ts b/src/state/index-persistence.ts index e058982a95..e4c21bbd67 100644 --- a/src/state/index-persistence.ts +++ b/src/state/index-persistence.ts @@ -1,3 +1,4 @@ +import {recoveryUpserts, type RecoveryUpsert, type RecoverySelection} from './vector-checkpoint-reconciliation.js'; import { VectorIndex, base64ToFloat32, float32ToBase64, type VectorEntry } from "./vector-index.js"; import type { StateKV } from "./kv.js"; import { KV } from "./schema.js"; @@ -113,6 +114,7 @@ export interface IndexPersistenceStatus { vectorCountShortfall: VectorCountShortfall | null; pendingLog?: number; pendingLogKnown?: boolean; + retainedCheckpointRows?: number; pendingLogAcknowledged?: number; pendingLogError?: string | null; } @@ -124,6 +126,7 @@ export interface VectorLoadResult { state: VectorLoadState; savedAt: string | null; expectedCount?: number; + checkpointMeta?: VectorMeta; backfillSince?: string | null; } @@ -242,6 +245,8 @@ export class IndexPersistence { private hasOpenBucket = false; private vectorCountShortfall: VectorCountShortfall | null = null; private seq = 0; + private retainedRows = new Map(); + private retentionReady = true; private pendingLog: Map = new Map(); private acknowledgedLog: Map = new Map(); private logChains: Map> = new Map(); @@ -269,7 +274,14 @@ export class IndexPersistence { this.storageGeneration = options.storageGeneration ?? (() => 0); this.bootStorageGeneration = this.storageGeneration(); this.vector?.setChangeListener((id, entry) => this.logChange(id, entry)); - this.vector?.setMutationGuard(() => { if (!this.logSuppressed && (this.isStorageHeld() || this.storageBlocked || this.storageRecovering || this.storageGeneration() !== this.bootStorageGeneration)) throw Object.assign(new Error('VECTOR_RECOVERY_PAUSED'), { code: 'VECTOR_RECOVERY_PAUSED' }); }); + this.retentionReady = !this.hasRetentionStore(); + this.vector?.setMutationGuard(id => { + if (!this.retentionReady || (id === null ? this.retainedRows.size > 0 : this.retainedRows.has(id)) || + (!this.logSuppressed && (this.isStorageHeld() || this.storageBlocked || this.storageRecovering || + this.storageGeneration() !== this.bootStorageGeneration))) { + throw Object.assign(new Error('VECTOR_RECOVERY_PAUSED'), {code: 'VECTOR_RECOVERY_PAUSED'}); + } + }); this.now = options.now ?? Date.now; const interval = options.saveIntervalMs; this.saveIntervalMs = @@ -360,7 +372,8 @@ export class IndexPersistence { pendingChanges: this.vector?.pendingChanges ?? 0, vector: this.vector ? { ...this.leg } : null, vectorCountShortfall: this.vectorCountShortfall, - pendingLog: this.pendingLogInspected && !this.pendingLogUnknown ? this.pendingLog.size : undefined, + pendingLog: this.pendingLogInspected && !this.pendingLogUnknown ? this.pendingLog.size + this.retainedRows.size : undefined, + retainedCheckpointRows: this.retainedRows.size, pendingLogKnown: this.pendingLogInspected && !this.pendingLogUnknown, pendingLogAcknowledged: this.pendingLogInspected && !this.pendingLogUnknown ? this.acknowledgedLog.size : undefined, pendingLogError: this.pendingLogError, @@ -370,7 +383,7 @@ export class IndexPersistence { async replayPendingLog(expectedDimensions = 0): Promise { const result: PendingReplayResult = { entries: 0, added: 0, removed: 0, cleared: false, skipped: 0 }; const vector = this.vector; - if (!vector || this.blockIfStorageHeld() || this.recoveryError) return result; + if (!vector || !this.retentionReady || this.blockIfStorageHeld() || this.recoveryError) return result; let rows: unknown[]; try { rows = await this.kv.list(KV.vectorPendingLog); @@ -388,6 +401,15 @@ export class IndexPersistence { this.pauseRecovery(new Error('Pending vector log contains invalid records')); return result; } + if (this.retainedRows.size) { + if (rows.length !== this.retainedRows.size || + ![...this.retainedRows.values()].every(original => rows.some(row => isDeepStrictEqual(row, original)))) { + this.storageBlocked = true; + this.pendingLogUnknown = true; + this.pauseRecovery(new Error('Retained vector log changed')); + } + return result; + } const valid = (Array.isArray(rows) ? rows : []).filter(isPendingVectorRow).sort((a, b) => a.q - b.q); for (const row of valid) { if (row.c === 1 || row.t === 1) continue; @@ -494,14 +516,62 @@ export class IndexPersistence { recoveryCutoff(): string | null | undefined { return this.backfillSince; } - resumeStorageRecovery(expectedDimensions = 0): Promise { + resumeStorageRecovery(expectedDimensions = 0, manualReconcile = false): Promise { if (this.storageResume) return this.storageResume; this.storageRecovering = true; - const work = this.resumeStorageRecoveryOnce(expectedDimensions).finally(() => { this.storageRecovering = false; this.storageResume = null; }); + const work = this.resumeStorageRecoveryOnce(expectedDimensions,manualReconcile).finally(() => { this.storageRecovering = false; this.storageResume = null; }); this.storageResume = work; return work; } + private hasRetentionStore(): boolean { + return this.kv.backend === 'file' && typeof this.kv.readVectorRetention === 'function'; + } + + private checkpointSelection(loaded: VectorLoadResult, rows: RecoveryUpsert[]): RecoverySelection { + if (rows.length && (!loaded.vector || !loaded.checkpointMeta || loaded.vector.size !== loaded.expectedCount)) { + throw Error('vector_recovery_checkpoint_incomplete'); + } + const buckets = new Map(); + for (const row of rows) { + const entry = loaded.vector?.get(row.id), bucket = this.bucketOfId.get(row.id); + if (bucket === undefined || !entry || entry.sessionId !== row.s || float32ToBase64(entry.embedding) !== row.e) + throw Error('vector_recovery_checkpoint_mismatch'); + const ids = buckets.get(bucket) ?? []; + ids.push(row.id); + buckets.set(bucket, ids); + } + return {pendingRows: rows, meta: loaded.checkpointMeta ?? null, buckets: [...buckets].map(([bucket, ids]) => ({bucket, ids}))}; + } + + /** Revalidate existing WAL evidence for one explicitly selected capture, without creating receipts. */ + async verifyCaptureVectorPending(id: string, sessionId: string, pending: unknown): Promise { + if (!this.retentionReady || this.storageRecovering || this.storageBlocked || this.isRecoveryPaused()) return false; + const row = this.retainedRows.get(id); + if (!row) return pending == null; + if (!this.vector || row.s !== sessionId || !isDeepStrictEqual(row, pending)) return false; + const revision = this.kv.vectorCheckpointRevision; + const current = () => !this.stopped && !this.isStorageHeld() && this.storageGeneration() === this.bootStorageGeneration && + !this.storageBlocked && !this.storageRecovering && !this.isRecoveryPaused() && + !this.pendingLog.size && !this.logChains.size && !this.vector?.pendingChanges; + try { + if (!current()) return false; + const meta = await this.kv.get(KV.bm25Index, VECTOR_META_KEY); + if (meta?.v !== 3) return false; + const rows = [...this.retainedRows.values()]; + const selected = this.checkpointSelection({state: 'buckets', vector: this.vector, savedAt: meta.savedAt, + checkpointMeta: meta, expectedCount: meta.count}, rows); + await this.kv.reconcileVectorCheckpoint(selected, current, revision, false); + return current(); + } catch { return false; } + } + + private rememberRetained(rows: RecoveryUpsert[]): void { + this.retainedRows = new Map(rows.map(row => [row.id, row])); + for (const row of rows) this.seq = Math.max(this.seq, row.q); + this.retentionReady = true; + } + private async requireEmptySdkPendingLog(): Promise { const rows = await this.kv.list(KV.vectorPendingLog); if (!Array.isArray(rows) || rows.length > 0 || this.pendingLog.size > 0 || this.logChains.size > 0) { @@ -509,7 +579,7 @@ export class IndexPersistence { } } - private async resumeStorageRecoveryOnce(expectedDimensions: number): Promise { + private async resumeStorageRecoveryOnce(expectedDimensions: number, manualReconcile:boolean): Promise { if (this.stopped || this.isStorageHeld()) return false; const generation = this.storageGeneration(); const sdkRecovery = this.kv.durability?.completion === 'sdk' && @@ -517,18 +587,33 @@ export class IndexPersistence { if (!sdkRecovery && !this.vector) return true; if (!sdkRecovery && !this.storageBlocked) return !this.isRecoveryPaused(); try { - if (sdkRecovery) await this.requireEmptySdkPendingLog(); + let selected:RecoveryUpsert[] | undefined; + const checkpointRevision=this.kv.vectorCheckpointRevision; + const current=()=>!this.stopped && !this.isStorageHeld() && generation===this.storageGeneration() && + this.pendingLog.size===0 && this.logChains.size===0 && this.storageRecovering; + if (sdkRecovery && manualReconcile) { + if(!current())throw Error('vector_recovery_busy'); + selected=recoveryUpserts(await this.kv.list(KV.vectorPendingLog),expectedDimensions); + } else if (sdkRecovery) await this.requireEmptySdkPendingLog(); if (this.isStorageHeld() || generation !== this.storageGeneration()) throw new Error('Storage hold changed during vector recovery'); this.bootStorageGeneration = generation; this.storageBlocked = false; this.recoveryError = null; - if (!this.vector) return true; - const loaded = await this.load(); + if (!this.vector) { + if(selected?.length)throw Error('vector_recovery_index_unavailable'); + if(selected)await this.kv.reconcileVectorCheckpoint({pendingRows:[],buckets:[],meta:null},current,checkpointRevision,true); + return true; + } + const loaded = await this.load(Boolean(selected?.length), selected !== undefined); if (this.blockIfStorageHeld() || !loaded || loaded.state === 'unavailable') throw new Error('Persisted vector checkpoint is unavailable'); if (loaded.vector && expectedDimensions > 0 && loaded.vector.validateDimensions(expectedDimensions).mismatches.length) throw new Error('Persisted vector dimensions mismatch'); // SDK checkpoint reads may span minutes. Recheck before the first backfill write. if (sdkRecovery) { - await this.requireEmptySdkPendingLog(); + if (selected) { + await this.kv.reconcileVectorCheckpoint(this.checkpointSelection(loaded, selected), current, checkpointRevision, true); + if (!current()) throw Error('vector_recovery_epoch_changed'); + this.rememberRetained(selected); + } else await this.requireEmptySdkPendingLog(); this.pendingLogInspected = true; this.pendingLogUnknown = false; } @@ -700,6 +785,7 @@ export class IndexPersistence { private deletePendingKey(key: string, q: number | undefined): Promise { return this.enqueueLog(key, async () => { + if (this.retainedRows.has(key) || (key === PENDING_CLEAR_KEY && this.retainedRows.size)) throw Error('vector_retention_original_protected'); if (this.pendingLog.get(key) !== q) return; if (this.blockIfStorageHeld()) throw new Error('Storage hold prevents vector log deletion'); await this.kv.delete(KV.vectorPendingLog, key); @@ -728,9 +814,20 @@ export class IndexPersistence { this.clearTimer(); } - async load(): Promise { + async load(strictCheckpoint = false, operatorWillVerify = false): Promise { + const unavailable: VectorLoadResult = {vector: null, state: 'unavailable', savedAt: null}; if (this.blockIfStorageHeld()) return { vector: null, state: 'unavailable', savedAt: null }; + const revision = this.kv.vectorCheckpointRevision, generation = this.storageGeneration(); + let hasReceipts = false; + if (this.hasRetentionStore()) { + this.retentionReady = false; + try { hasReceipts = (await this.kv.readVectorRetention()).length > 0; } + catch (error) { this.storageBlocked = true; this.pauseRecovery(error); return unavailable; } + this.retentionReady = !hasReceipts && !operatorWillVerify; + strictCheckpoint ||= hasReceipts; + } if (!this.vector) { + if (hasReceipts) { this.storageBlocked = true; this.pauseRecovery(Error('vector_retention_index_unavailable')); return unavailable; } await this.finishLegacyCleanup(); return { vector: null, state: "none", savedAt: null }; } @@ -746,7 +843,7 @@ export class IndexPersistence { if (this.blockIfStorageHeld()) return { vector: null, state: 'unavailable', savedAt: null }; if (meta && meta.v === 3 && Number.isInteger(meta.bucketCount) && meta.bucketCount >= 0) { - const loaded = await this.loadBuckets(meta.bucketCount); + const loaded = await this.loadBuckets(meta.bucketCount,strictCheckpoint); if (this.blockIfStorageHeld()) return { vector: null, state: 'unavailable', savedAt: null }; if (!loaded) return { vector: null, state: "unavailable", savedAt: null }; this.hasVectorCheckpoint = loaded.size > 0; @@ -763,8 +860,25 @@ export class IndexPersistence { ...this.vectorCountShortfall, }); } - return { vector: loaded, state: replacementVerified ? "buckets" : "unavailable", savedAt: meta.savedAt ?? null, expectedCount, backfillSince: meta.backfillSince }; + const result: VectorLoadResult = { vector: loaded, state: replacementVerified ? "buckets" : "unavailable", savedAt: meta.savedAt ?? null, + expectedCount, ...(strictCheckpoint ? {checkpointMeta:meta} : {}), backfillSince: meta.backfillSince }; + if (hasReceipts && !operatorWillVerify) { + try { + if (!replacementVerified) throw Error('vector_retention_checkpoint_unavailable'); + const raw = await this.kv.list(KV.vectorPendingLog); + const first = raw?.[0]?.id; + const dimensions = typeof first === 'string' ? loaded.get(first)?.embedding.length ?? 0 : 0; + const rows = recoveryUpserts(raw, dimensions); + const current = () => !this.stopped && !this.isStorageHeld() && this.storageGeneration() === generation && + !this.pendingLog.size && !this.logChains.size; + await this.kv.reconcileVectorCheckpoint(this.checkpointSelection(result, rows), current, revision, false); + if (!current()) throw Error('vector_retention_epoch_changed'); + this.rememberRetained(rows); + } catch (error) { this.storageBlocked = true; this.pauseRecovery(error); return unavailable; } + } + return result; } + if (hasReceipts) { this.storageBlocked = true; this.pauseRecovery(Error('vector_retention_checkpoint_missing')); return unavailable; } return this.migrateLegacy(); } @@ -837,7 +951,7 @@ export class IndexPersistence { private async runSave(): Promise { const vector = this.vector; - if (!vector || this.blockIfStorageHeld() || this.isRecoveryPaused()) return; + if (!vector || !this.retentionReady || this.blockIfStorageHeld() || this.isRecoveryPaused()) return; if (!vector.pendingChanges && !this.needsRecoveryCheckpoint()) return; const hasVectorChanges = vector.pendingChanges > 0; const epoch = this.dirtyEpoch; @@ -928,7 +1042,7 @@ export class IndexPersistence { if (!this.hasVectorCheckpoint) this.firstVectorSaveAttempted = false; } - private async loadBuckets(bucketCount: number): Promise { + private async loadBuckets(bucketCount: number, strictCheckpoint = false): Promise { const loaded = new VectorIndex(); const bucketOfId = new Map(); const bucketCounts = new Map(); @@ -939,10 +1053,15 @@ export class IndexPersistence { const rows = await this.kv.list(vectorBucketScope(bucket)); let count = 0; for (const row of rows) { - if (!isPersistedVector(row)) continue; + if (!isPersistedVector(row)) { + if(strictCheckpoint)throw Error('vector_recovery_bucket_invalid'); + continue; + } + if(strictCheckpoint && bucketOfId.has(row.id))throw Error('vector_recovery_duplicate_id'); try { loaded.loadPersisted(row.id, row.s, base64ToFloat32(row.e)); } catch { + if(strictCheckpoint)throw Error('vector_recovery_bucket_invalid'); continue; } bucketOfId.set(row.id, bucket); diff --git a/src/state/kv.ts b/src/state/kv.ts index ca42624744..116c096deb 100644 --- a/src/state/kv.ts +++ b/src/state/kv.ts @@ -1,4 +1,6 @@ -import {createRecordRecoveryGate} from './recovery-write-gate.js' +import {bucketScope, reconcileCheckpoint, readRetention, receiptFor, RETAINED_SCOPE, type RetentionReceipt, type RecoverySelection} from './vector-checkpoint-reconciliation.js' +import {KV} from './schema.js' +import {createRecordRecoveryGate, createRecoveryWriteGate} from './recovery-write-gate.js' import {ownsFileWriterLease,fileWriterReadCurrent,fileWriterRecoveryAdmitted,fileWriterRecoveryReason,type FileWriterLease} from '../ops/file-writer-lease.mjs' import { createCaptureReceiptPage } from '../capture/receipt-page.js' import type { IIIClient } from 'iii-sdk' @@ -121,6 +123,10 @@ export class StateKV { private readonly summaryNamespaceLock = `summary-namespace:${++summaryLockSequence}` private writerLease?:FileWriterLease private writerStorePath?:string + private checkpointStorePath?:string + private readonly vectorWrites = createRecoveryWriteGate() + private vectorRevision = 0 + get vectorCheckpointRevision() { return this.vectorRevision } private uncertainMutation=false get recoveryBlockReason(){return this.uncertainMutation?'WRITER_MUTATION_UNCERTAIN':this.writerLease?fileWriterRecoveryReason(this.writerLease):'FILE_WRITER_UNSUPPORTED'} get mutationOutcomeUncertain(){return this.uncertainMutation} @@ -140,6 +146,7 @@ export class StateKV { ) { this.backend = options.backend ?? 'file' const storePath = this.backend === 'file' ? getEnvVar('AGENTMEMORY_STATE_STORE_PATH') : undefined + this.checkpointStorePath = storePath if (this.backend === 'file' && storePath && ownsFileWriterLease(options.writerLease,storePath)) {this.recoveryWrite=createRecordRecoveryGate();this.writerLease=options.writerLease;this.writerStorePath=storePath;} this.durability = this.backend === 'file' ? options.durability ?? (storePath ? createStateDurabilityFence({ storePath, completion: 'sdk' }) : null) @@ -157,7 +164,40 @@ export class StateKV { // Keep queued mutations visible to the durability/shutdown fence. The gate // belongs inside the tracked operation, rather than before performMutation. const perform=()=>{if(this.writerLease&&!ownsFileWriterLease(this.writerLease,this.writerStorePath!))return Promise.reject(Error('FILE_WRITER_LOST'));return this.performMutation(scope,key,()=>scope==='mem:summaries'?withKeyedLock(this.summaryNamespaceLock,serialized):operation())} - return this.recoveryWrite ? this.recoveryWrite.read(scope,key,perform) : perform() + if (!this.recoveryWrite) return perform() + const vectorNamespace = scope===KV.vectorPendingLog || scope===RETAINED_SCOPE || scope.startsWith(KV.bm25Index+':vec:') || + (scope===KV.bm25Index && key==='vectors:meta') + if (!vectorNamespace) return this.recoveryWrite.read(scope,key,perform) + return this.recoveryWrite.read(scope,key,()=>this.vectorWrites.read(async()=>{ + try { return await perform() } finally { this.vectorRevision++ } + })) + } + + async readVectorRetention():Promise { + if (this.backend !== 'file') return [] + if (!this.checkpointStorePath) throw Error('vector_retention_store_unverified') + return readRetention(this,this.checkpointStorePath,()=>!this.uncertainMutation && + (!this.writerLease || ownsFileWriterLease(this.writerLease,this.checkpointStorePath!))) + } + + async reconcileVectorCheckpoint(selection:RecoverySelection,current:()=>boolean,expectedRevision:number,authorize:boolean):Promise{ + const gate=this.recoveryWrite, storePath=this.writerStorePath + if(!gate || !storePath || !this.recoveryMutationSafe || (authorize && this.durability?.completion!=='sdk'))throw Error('vector_recovery_writer_unverified') + const keys:Array<{scope:string;key:string}>=[{scope:KV.vectorPendingLog,key:'~clear'},{scope:KV.bm25Index,key:'vectors:meta'}, + ...selection.pendingRows.map(({id})=>({scope:KV.vectorPendingLog,key:id}))] + for(const {bucket,ids} of selection.buckets)for(const id of ids){ + const row=selection.pendingRows.find(item=>item.id===id) + if(!row)throw Error('vector_recovery_selection_invalid') + keys.push({scope:bucketScope(bucket),key:id},{scope:RETAINED_SCOPE,key:receiptFor(row,bucket).digest}) + } + const verify=()=>this.vectorWrites.exclusive(async()=>{ + if (this.vectorRevision!==expectedRevision) throw Error('vector_recovery_checkpoint_changed') + const admitted=()=>current() && (!authorize || gate.inExclusive()) && this.recoveryMutationSafe + const existing=await readRetention(this,storePath,admitted) + return reconcileCheckpoint(this,storePath,selection,existing,authorize,admitted) + }) + // Read-only rechecks can run within capture's existing record gate. They never acquire another record lock. + return authorize ? gate.exclusive(keys,verify) : verify() } private markMutationUncertain(scope:string):void { diff --git a/src/state/schema.ts b/src/state/schema.ts index 33076b78d9..2a7d4ee3f4 100644 --- a/src/state/schema.ts +++ b/src/state/schema.ts @@ -12,6 +12,7 @@ export const KV = { health: "mem:health", embeddings: (obsId: string) => `mem:emb:${obsId}`, bm25Index: "mem:index:bm25", + vectorRetentionReceipts: "mem:index:vec-retained:v1", vectorPendingLog: "mem:index:vec-pending", embeddingRetry: "mem:embedding-retry:v1", embeddingCommitted: "mem:embedding-committed:v1", diff --git a/src/state/vector-checkpoint-reconciliation.ts b/src/state/vector-checkpoint-reconciliation.ts new file mode 100644 index 0000000000..8adeedc86b --- /dev/null +++ b/src/state/vector-checkpoint-reconciliation.ts @@ -0,0 +1,118 @@ +import { createHash } from 'node:crypto'; +import { isDeepStrictEqual } from 'node:util'; +import { createStateDurabilityFence } from '../ops/state-durability.mjs'; +import { verifyVectorCheckpointFiles, verifyRemainingVectorPending, verifyVectorRetentionReceipts } from '../ops/vector-checkpoint-proof.mjs'; +import type { VectorRetentionReceipt } from '../types.js'; +import type { StateKV } from './kv.js'; +import { KV } from './schema.js'; + +export type RetentionReceipt = VectorRetentionReceipt; +export type RecoveryUpsert = { id: string; q: number; s: string; e: string; k?: 'memory' | 'observation' }; +export type RecoverySelection = { + pendingRows: RecoveryUpsert[]; + meta: Record | null; + buckets: Array<{ bucket: number; ids: string[] }>; +}; + +export function recoveryUpserts(values: unknown, dimensions: number): RecoveryUpsert[] { + if (!Array.isArray(values) || values.length > 16) throw Error('vector_recovery_selection_invalid'); + const ids = new Set(), sequences = new Set(); + for (const row of values) { + if (!row || typeof row !== 'object' || Object.keys(row).some(key => !['id', 'q', 's', 'e', 'k'].includes(key)) || + !Number.isSafeInteger(row.q) || row.q <= 0 || row.q === Number.MAX_SAFE_INTEGER || sequences.has(row.q) || + typeof row.id !== 'string' || !row.id || row.id === '~clear' || row.id.length > 512 || ids.has(row.id) || + typeof row.s !== 'string' || !row.s || row.s.length > 512 || + (row.k !== undefined && row.k !== (row.id.startsWith('mem_') ? 'memory' : 'observation')) || + !Number.isSafeInteger(dimensions) || dimensions < 1 || dimensions > 8192 || + typeof row.e !== 'string' || row.e.length !== 4 * Math.ceil(dimensions * 4 / 3)) + throw Error('vector_recovery_selection_invalid'); + const bytes = Buffer.from(row.e, 'base64'); + if (bytes.length !== dimensions * 4 || bytes.toString('base64') !== row.e) throw Error('vector_recovery_embedding_invalid'); + for (let offset = 0; offset < bytes.length; offset += 4) { + if (!Number.isFinite(bytes.readFloatLE(offset))) throw Error('vector_recovery_embedding_invalid'); + } + ids.add(row.id); + sequences.add(row.q); + } + return [...values].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0); +} + +export const bucketScope = (bucket: number) => KV.bm25Index + ':vec:' + String(bucket).padStart(4, '0'); +export const RETAINED_SCOPE = KV.vectorRetentionReceipts; + +export function receiptFor(row: RecoveryUpsert, bucket: number): RetentionReceipt { + const digest = createHash('sha256').update(JSON.stringify([row.id, row.q, row.s, row.e, row.k ?? null, bucket])).digest('hex'); + return { v: 1, id: row.id, q: row.q, bucket, digest }; +} + +export async function readRetention(kv: StateKV, storePath: string, admitted: () => boolean): Promise { + const values = await kv.list(RETAINED_SCOPE); + if (!Array.isArray(values) || values.length > 16 || values.some(row => !row || typeof row.digest !== 'string')) + throw Error('vector_retention_receipts_invalid'); + const receipts = Object.fromEntries(values.map(row => [row.digest, row])); + if (Object.keys(receipts).length !== values.length) throw Error('vector_retention_receipts_invalid'); + await verifyVectorRetentionReceipts({ storePath, receipts, admitted }); + return values; +} + +export async function reconcileCheckpoint( + kv: StateKV, storePath: string, selection: RecoverySelection, existing: RetentionReceipt[], + authorize: boolean, admitted: () => boolean, +): Promise { + const { pendingRows, buckets, meta } = selection; + function check() { + if (!admitted()) throw Error('vector_recovery_epoch_changed'); + } + async function confirmPending() { + check(); + const current = await kv.list(KV.vectorPendingLog); + if (!Array.isArray(current) || current.length !== pendingRows.length || + !pendingRows.every(row => current.some(value => isDeepStrictEqual(value, row)))) throw Error('vector_recovery_pending_changed'); + check(); + } + + await confirmPending(); + if (!pendingRows.length) { + if (existing.length) throw Error('vector_retention_original_missing'); + await verifyRemainingVectorPending({ storePath, pendingRows, admitted }); + return []; + } + if (!meta || !isDeepStrictEqual(await kv.get(KV.bm25Index, 'vectors:meta'), meta)) throw Error('vector_recovery_meta_changed'); + const expected: RetentionReceipt[] = []; + for (const {bucket, ids} of buckets) { + for (const id of ids) { + check(); + const row = pendingRows.find(item => item.id === id); + if (!row || !isDeepStrictEqual(await kv.get(KV.vectorPendingLog, id), row) || + !isDeepStrictEqual(await kv.get(bucketScope(bucket), id), {id, s: row.s, e: row.e})) + throw Error('vector_recovery_checkpoint_changed'); + expected.push(receiptFor(row, bucket)); + } + } + if (existing.some(stamp => !expected.some(wanted => isDeepStrictEqual(stamp, wanted)))) + throw Error('vector_retention_original_changed'); + const missing = expected.filter(wanted => !existing.some(stamp => isDeepStrictEqual(stamp, wanted))); + if (missing.length && !authorize) throw Error('vector_retention_manual_verification_required'); + const recheck = await verifyVectorCheckpointFiles({storePath, pendingRows, meta, buckets, admitted}); + await recheck(); + + // iii has no conditional delete. Preserve the entire WAL. Immutable receipt keys make + // an interrupted batch retryable without replaying or rewriting even one vector. + for (const stamp of missing) { + check(); + await kv.set(RETAINED_SCOPE, stamp.digest, stamp); + } + if (missing.length) { + const disk = createStateDurabilityFence({storePath, completion: 'disk'}); + const keys = missing.map(stamp => ({scope: RETAINED_SCOPE, key: stamp.digest})); + const result = await disk.waitForKeys(kv, keys, {expectedValues: missing}); + if (result.synced !== true || result.keys !== keys.length || result.scopes !== 1 || result.mutationFailures !== 0) + throw Error('vector_retention_disk_sync_unconfirmed'); + } + const saved = await readRetention(kv, storePath, admitted); + if (saved.length !== expected.length || !expected.every(stamp => saved.some(actual => isDeepStrictEqual(stamp, actual)))) + throw Error('vector_retention_receipts_changed'); + await confirmPending(); + await recheck(); + return saved; +} diff --git a/src/state/vector-index.ts b/src/state/vector-index.ts index ad7f3022cc..ff3e671bcb 100644 --- a/src/state/vector-index.ts +++ b/src/state/vector-index.ts @@ -37,16 +37,16 @@ export class VectorIndex { private vectors: Map = new Map(); private changes: Map = new Map(); private listener: VectorChangeListener | null = null; - private mutationGuard: (() => void) | null = null; + private mutationGuard: ((id: string | null) => void) | null = null; - setMutationGuard(guard: (() => void) | null): void { this.mutationGuard = guard; } + setMutationGuard(guard: ((id: string | null) => void) | null): void { this.mutationGuard = guard; } setChangeListener(listener: VectorChangeListener | null): void { this.listener = listener; } add(obsId: string, sessionId: string, embedding: Float32Array): void { - this.mutationGuard?.(); + this.mutationGuard?.(obsId); const entry = { embedding, sessionId }; this.vectors.set(obsId, entry); this.changes.set(obsId, true); @@ -54,7 +54,7 @@ export class VectorIndex { } remove(obsId: string): void { - this.mutationGuard?.(); + this.mutationGuard?.(obsId); if (this.vectors.delete(obsId)) { this.changes.set(obsId, false); this.listener?.(obsId, null); @@ -94,10 +94,12 @@ export class VectorIndex { } markRemoved(obsId: string): void { + this.mutationGuard?.(obsId); if (!this.vectors.has(obsId)) this.changes.set(obsId, false); } markAllChanged(): void { + this.mutationGuard?.(null); for (const obsId of this.vectors.keys()) this.changes.set(obsId, true); } @@ -162,7 +164,7 @@ export class VectorIndex { } clear(): void { - this.mutationGuard?.(); + this.mutationGuard?.(null); const hadVectors = this.vectors.size > 0; for (const obsId of this.vectors.keys()) this.changes.set(obsId, false); this.vectors.clear(); diff --git a/src/types.ts b/src/types.ts index a5d203b945..62d007d1c4 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; @@ -1170,3 +1170,6 @@ export type CaptureRetryJob = { id: string; all: boolean; eventId?: string; key? export interface CaptureRecoveryFailure {operation:string;stage:string;code:string;elapsedMs?:number;reader?:{readerPhase:string;readerFailurePhase?:string;readerTimings:Record;bytesRead?:number;processCpuMs?:number;eventLoopActiveMs?:number;eventLoopIdleMs?:number;complete?:boolean}} export interface CaptureRecoveryCheckpoint {version:1;kind:"item";key:string;id:string;sessionId:string;observationId:string;eventId:string;sourceDigest:string;projection:string;phase:"checking"|"verifying"|"resolved"|"blocked";reason:string;createdAt:string;updatedAt:string;verificationAttempts:number;nextAttemptAt:number;lastVerificationFailure?:CaptureRecoveryFailure} + +/** An immutable record of a disk-verified upsert whose WAL entry is retained. */ +export interface VectorRetentionReceipt { v:1; id:string; q:number; bucket:number; digest:string } diff --git a/src/version.ts b/src/version.ts index c66ade2008..312a208f37 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.58"; +export const VERSION = "0.9.32-daniel.59"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/capture-sdk-reconciliation.test.ts b/test/capture-sdk-reconciliation.test.ts index 70a198c7b3..d4881fd14e 100644 --- a/test/capture-sdk-reconciliation.test.ts +++ b/test/capture-sdk-reconciliation.test.ts @@ -23,7 +23,7 @@ async function fixture(saved?:Map>){ } writes=0; const auditEntries:any[]=[]; - const make=()=>createSdkCaptureReconciliation(kv as never,{admitted:()=>admitted,indexEvidence:(obs:any)=>({keyword:{present:indexed,sessionId:indexed?owner:undefined},vectorSessionId:vectorOwner}),audit:async e=>{auditEntries.push(e)},now:()=>Date.parse('2026-10-29T01:00:00Z')}); + const make=(verifyCaptureVectorPending?:(id:string,sessionId:string,pending:unknown)=>Promise)=>createSdkCaptureReconciliation(kv as never,{admitted:()=>admitted,verifyCaptureVectorPending,indexEvidence:(obs:any)=>({keyword:{present:indexed,sessionId:indexed?owner:undefined},vectorSessionId:vectorOwner}),audit:async e=>{auditEntries.push(e)},now:()=>Date.parse('2026-10-29T01:00:00Z')}); return{kv,gate,get,set,helper:make(),make,writeCount:()=>writes,pause:()=>admitted=false,unindex:()=>indexed=false,keywordOwner:(v:string|undefined)=>owner=v,vectorOwner:(v:string|undefined)=>vectorOwner=v,fail:(n:number,stored=false)=>{failAt=n;after=stored},resetWrites:()=>writes=0,call(){return this.helper.reconcile({key,requestId:req,sourceDigest})}}; } it('reconciles an actually stored capture with SDK completion and preserves every original and failure/budget field',async()=>{ @@ -91,3 +91,14 @@ it('whole-review source restore mutation retains completed v2 protection',async( await f.kv.set(KV.captureInbox,key,{...rec,sdkRestoreRequestId:otherReq,sdkRestoreState:'pending',sdkRestoreAttempts:0}); await expect(assertSdkSourceLegacyProtection(f.kv as never,payload as never,key,id,eventId)).resolves.toBeUndefined(); }); + +it('requires current physical proof on each phase for a retained capture and keeps the original WAL',async()=>{ + const f=await fixture(),row={id,s:payload.sessionId,q:3,e:'AACAPw=='}; + await f.set(KV.vectorPendingLog,id,row); + await expect(f.call()).rejects.toThrow('SDK_RECONCILIATION_INDEX_PENDING'); + let checks=0; + const repaired=f.make(async(obs,session,actual)=>{checks++;return obs===id && session===payload.sessionId && JSON.stringify(actual)===JSON.stringify(row);}); + expect(await repaired.reconcile({key,requestId:req,sourceDigest})).toMatchObject({status:'reconciled',verified:false,synced:false,originalReplay:false}); + expect(checks).toBeGreaterThanOrEqual(5);expect(await f.kv.get(KV.vectorPendingLog,id)).toEqual(row); + const stale=f.make(async()=>false);await expect(stale.reconcile({key,requestId:req,sourceDigest})).rejects.toThrow('SDK_RECONCILIATION_INDEX_PENDING'); +}); diff --git a/test/manual-vector-checkpoint-recovery.test.ts b/test/manual-vector-checkpoint-recovery.test.ts new file mode 100644 index 0000000000..ee1696127f --- /dev/null +++ b/test/manual-vector-checkpoint-recovery.test.ts @@ -0,0 +1,102 @@ +import {describe,expect,it,vi} from 'vitest'; +import {IndexPersistence, vectorBucketScope} from '../src/state/index-persistence.js'; +import {receiptFor} from '../src/state/vector-checkpoint-reconciliation.js'; +import {VectorIndex} from '../src/state/vector-index.js'; + +const pending='mem:index:vec-pending',index='mem:index:bm25'; +function fixture() { + const vec=Buffer.from(new Float32Array([1,2,3]).buffer).toString('base64'); + const rows = ['obs_a','obs_b','obs_c'].map((id,i)=>({id,s:'s',q:i+1,e:vec,k:'observation'})); + const scopes = new Map>([ + [pending,new Map(rows.map(r=>[r.id,r]))], + [index,new Map([['vectors:meta',{v:3,count:3,bucketCount:1,savedAt:'2026-01-01T00:00:00.000Z'}]])], + [vectorBucketScope(0),new Map(rows.map(({id,s,e})=>[id,{id,s,e}]))], + ]); + let held=true; + const kv = { + backend:'file', + readVectorRetention: async()=>[...scopes.get('receipts')?.values()??[]], + delete: async(scope:string,key:string)=>scopes.get(scope)?.delete(key), + durability:{completion:'sdk',waitForKeys:async()=>({completed:true,synced:false})}, + get:async(scope:string,key:string)=>scopes.get(scope)?.get(key)??null, + set:async(scope:string,key:string,v:unknown)=>{if(!scopes.has(scope))scopes.set(scope,new Map());scopes.get(scope)!.set(key,v);}, + list:async(scope:string)=>[...scopes.get(scope)?.values()??[]], + reconcileVectorCheckpoint:vi.fn(async(data:{pendingRows:typeof rows},current:()=>boolean,_rev:number,authorize:boolean)=>{ + if(!current())throw Error('stale'); + const desired=data.pendingRows.map(row=>receiptFor(row as never,0)); + const stored=scopes.get('receipts')??new Map(); + if ([...stored].some(([key])=>!desired.some(row=>row.digest===key))) throw Error('original changed'); + if (!authorize && desired.some(row=>!stored.has(row.digest))) throw Error('new WAL'); + scopes.set('receipts',new Map(desired.map(row=>[row.digest,row]))); + return desired; + }), + }; + const v=new VectorIndex(); + const p=new IndexPersistence(kv as never,v,{requireRecoveryPlan:true,isStorageHeld:()=>held}); + const release=async(explicit:boolean)=>{await p.load();held=false;return p.resumeStorageRecovery(3,explicit);}; + return {scopes,rows,kv,v,p,release}; +} + +describe('operator-requested vector checkpoint recovery',()=>{ + it('certifies three exact rows before release and does not replay them',async()=>{ + const f=fixture();try{ + expect(await f.release(true)).toBe(true); + expect(f.kv.reconcileVectorCheckpoint).toHaveBeenCalledTimes(1); + expect(f.kv.reconcileVectorCheckpoint.mock.calls[0][0]).toMatchObject({pendingRows:f.rows,buckets:[{bucket:0,ids:f.rows.map(r=>r.id)}]}); + expect(f.v.size).toBe(3);expect([...f.scopes.get(pending)!.values()]).toEqual(f.rows); + expect(f.p.status()).toMatchObject({pendingLog:3,pendingLogAcknowledged:0,retainedCheckpointRows:3,pendingChanges:0}); + expect(()=>f.v.add('obs_a','s',new Float32Array([3,2,1]))).toThrow(/PAUSED/); + expect(()=>f.v.remove('obs_b')).toThrow(/PAUSED/);expect(()=>f.v.clear()).toThrow(/PAUSED/);expect(()=>f.v.markAllChanged()).toThrow(/PAUSED/); + const added=new Float32Array([4,5,6]); + f.v.add('new','s',added);await f.p.save(); + expect(f.scopes.get(vectorBucketScope(0))!.get('new')).toMatchObject({id:'new'}); + expect([...f.scopes.get(pending)!.values()]).toEqual(f.rows); + expect(f.p.status()).toMatchObject({pendingChanges:0,pendingLog:3}); + expect(await f.p.verifyCaptureVectorPending('obs_a','s',f.rows[0])).toBe(true); + expect(await f.p.verifyCaptureVectorPending('obs_a','s',null)).toBe(false); + expect(await f.p.verifyCaptureVectorPending('obs_a','other',f.rows[0])).toBe(false); + expect(await f.p.verifyCaptureVectorPending('obs_a','s',{...f.rows[0],q:9})).toBe(false); + expect(await f.p.verifyCaptureVectorPending('new','s',null)).toBe(true); + expect(await f.p.verifyCaptureVectorPending('new','s',f.rows[0])).toBe(false); + expect(f.kv.reconcileVectorCheckpoint.mock.calls.at(-1)?.[3]).toBe(false); + const next=new VectorIndex(),p2=new IndexPersistence(f.kv as never,next,{requireRecoveryPlan:true}); + try{ + const loaded=await p2.load();expect(loaded.state).toBe('buckets');await p2.prepareBackfill(loaded); + next.restoreFrom(loaded.vector!); + expect(await p2.replayPendingLog(3)).toMatchObject({entries:0,added:0}); + expect(next.size).toBe(4);expect(next.pendingChanges).toBe(0); + expect(()=>next.markRemoved('obs_a')).toThrow(/PAUSED/); + await p2.save();expect([...f.scopes.get(pending)!.values()]).toEqual(f.rows); + expect(f.kv.reconcileVectorCheckpoint.mock.calls.at(-1)?.[3]).toBe(false); + }finally{p2.stop();} + }finally{f.p.stop();} + }); + it.each(['updated q','mismatched bytes','additional row','missing row','clear'])('fails closed on subsequent boot with %s',async mode=>{ + const f=fixture();const v2=new VectorIndex(),p2=new IndexPersistence(f.kv as never,v2,{requireRecoveryPlan:true}); + try{ + expect(await f.release(true)).toBe(true);const log=f.scopes.get(pending)!; + if(mode==='updated q')log.set('obs_a',{...f.rows[0],q:12}); + if(mode==='mismatched bytes')log.set('obs_a',{...f.rows[0],e:Buffer.from(new Float32Array([8,2,3]).buffer).toString('base64')}); + if(mode==='additional row')log.set('extra',{...f.rows[0],id:'extra',q:18}); + if(mode==='missing row')log.delete('obs_a'); + if(mode==='clear')log.set('~clear',{q:19,c:1}); + const before=new Map(log); + expect((await p2.load()).state).toBe('unavailable');expect(p2.isRecoveryPaused()).toBe(true); + await p2.replayPendingLog(3);await p2.save();expect(log).toEqual(before); + expect(()=>v2.add('obs_a','s',new Float32Array(3))).toThrow(/PAUSED/); + }finally{f.p.stop();p2.stop();} + }); + it('requires an explicit request even when all checkpoints match',async()=>{ + const f=fixture();try{expect(await f.release(false)).toBe(false);expect(f.kv.reconcileVectorCheckpoint).not.toHaveBeenCalled();expect(f.scopes.get(pending)!.size).toBe(3);}finally{f.p.stop();} + }); + it.each(['clear','tombstone','duplicate ID in two buckets','checkpoint shortfall','mismatched vector'])('retains the originals on %s',async reason=>{ + const f=fixture(); + if(reason==='clear')f.scopes.get(pending)!.set('~clear',{q:20,c:1}); + if(reason==='tombstone')f.scopes.get(pending)!.set('obs_a',{q:1,id:'obs_a',t:1}); + if(reason==='duplicate ID in two buckets'){f.scopes.get(index)!.get('vectors:meta').bucketCount=2;f.scopes.set(vectorBucketScope(1),new Map(f.scopes.get(vectorBucketScope(0))));} + if(reason==='checkpoint shortfall')f.scopes.get(index)!.get('vectors:meta').count=42; + if(reason==='mismatched vector')f.scopes.get(vectorBucketScope(0))!.get('obs_a').e=Buffer.from(new Float32Array([9,2,3]).buffer).toString('base64'); + const before=new Map(f.scopes.get(pending)); + try{expect(await f.release(true)).toBe(false);expect(f.kv.reconcileVectorCheckpoint).not.toHaveBeenCalled();expect(f.scopes.get(pending)).toEqual(before);}finally{f.p.stop();} + }); +}); diff --git a/test/operations-protection-recovery.test.ts b/test/operations-protection-recovery.test.ts index c0c80592b4..8c668d5075 100644 --- a/test/operations-protection-recovery.test.ts +++ b/test/operations-protection-recovery.test.ts @@ -155,6 +155,24 @@ it('honors future backoff even when stable samples survive a clean restart and a const f=fixture({version:2,paused:true,resumePending:false,holds:['memory'],recovery:{attempts:1,nextAttemptAt:130001}});await f.control.init(f.kv);await f.normal();expect(f.control.isPaused()).toBe(true);f.time(130001);await f.guard.refresh();await f.guard.drain();expect(f.control.isPaused()).toBe(false);expect(f.control.snapshot().recovery.attempts).toBe(2); }); +it.each(['manual', 'deployment'] as const)('limits SDK vector reconciliation to a manual resume (%s)', async source => { + const f = fixture({version:2, paused:true, resumePending:false, holds:[source], recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv); + const calls: boolean[] = []; + const handlers = new Map(); + const sdk = {registerFunction:(id:string, fn:any) => handlers.set(id, fn), registerTrigger:() => {}}; + registerBackgroundControlApi(sdk as any, 'fixture', f.control, async allowReconciliation => { + calls.push(allowReconciliation); + return true; + }); + const result = await handlers.get('api::background-control-set')({ + headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'}, + body:source === 'manual' ? {action:'resume'} : {action:'resume', reason:'deployment'} + }); + expect(result.status_code).toBe(202); + expect(calls).toEqual([source === 'manual']); +}); + it('keeps action-only HTTP pauses manual and permits only an explicit deployment reason',async()=>{ const f=fixture(),handlers=new Map();await f.control.init(f.kv);registerBackgroundControlApi({registerFunction:(id:string,fn:any)=>handlers.set(id,fn),registerTrigger:()=>{}} as any,'fixture',f.control); const post=(body:any)=>handlers.get('api::background-control-set')({headers:{authorization:'Bearer fixture','x-agentmemory-background':'1','content-type':'application/json'},body}); diff --git a/test/vector-checkpoint-proof.test.ts b/test/vector-checkpoint-proof.test.ts new file mode 100644 index 0000000000..fec5eabdfc --- /dev/null +++ b/test/vector-checkpoint-proof.test.ts @@ -0,0 +1,136 @@ +import {afterEach, beforeEach, expect, it} from "vitest"; +import {mkdtemp, rename, rm, symlink, writeFile} from "node:fs/promises"; +import {tmpdir} from "node:os"; +import {join} from "node:path"; +import {verifyVectorCheckpointFiles, verifyRemainingVectorPending, verifyVectorRetentionReceipts} from "../src/ops/vector-checkpoint-proof.mjs"; + +const pending = "mem:index:vec-pending", metaScope = "mem:index:bm25", bucket = metaScope + ":vec:0000"; +const row = {id:"v1",q:1,s:"session",e:"AACAPw=="}; +const vector = {id:row.id,s:row.s,e:row.e}; +const metadata = {v:3,bucketCount:1,count:1,savedAt:"2026-11-07T00:00:00Z"}; +let storePath:string; +const file = (scope:string) => join(storePath,encodeURIComponent(scope)+".bin"); + +// rkyv 0.8 LE32 ArchivedString: short JSON is inline, long strings use an aligned length/offset. +function archive(text:string){ + const bytes=Buffer.from(text); + if(bytes.length<=8){const result=Buffer.alloc(8,0xff);bytes.copy(result);return result;} + const position=Math.ceil(bytes.length/4)*4,result=Buffer.alloc(position+8); + bytes.copy(result); + result.writeUInt32LE((bytes.length & 63) + 128 + Math.floor(bytes.length/64)*256,position); + result.writeInt32LE(-position,position+4); + return result; +} +const put = (scope:string, value:unknown) => writeFile(file(scope),archive(JSON.stringify(value))); +const input = () => ({storePath,pendingRows:[{...row}],meta:{...metadata},buckets:[{bucket:0,ids:["v1"]}],admitted:()=>true}); +beforeEach(async()=>{ + storePath=await mkdtemp(join(tmpdir(),"am-vector-proof-")); + await put(pending,{v1:row});await put(metaScope,{"vectors:meta":metadata});await put(bucket,{v1:vector}); +}); +afterEach(async()=>{await rm(storePath,{recursive:true,force:true});}); + +it("matches physical keys and SDK values under one admitted generation",async()=>{ + const check=await verifyVectorCheckpointFiles(input()); + await expect(check()).resolves.toBeUndefined(); + await expect(verifyRemainingVectorPending({...input(),pendingRows:[]})).rejects.toThrow(); + await rm(file(pending)); + await expect(verifyRemainingVectorPending({...input(),pendingRows:[]})).resolves.toBeUndefined(); + await put(pending,{}); + await expect(verifyRemainingVectorPending({...input(),pendingRows:[]})).resolves.toBeUndefined(); +}); +it.each(["alias","extra","trailer","duplicate","changed_meta","symlink","unadmitted"])("refuses %s",async kind=>{ + const opts=input(); + if(kind==="alias")await put(bucket,{other:vector}); + if(kind==="extra")await put(pending,{v1:row,stale:{...row,id:"stale",q:2}}); + if(kind==="trailer"){const buf=archive(JSON.stringify({v1:row}));buf.writeInt32LE(0,buf.length-4);await writeFile(file(pending),buf);} + if(kind==="duplicate")await writeFile(file(pending),archive('{"v1":'+JSON.stringify(row)+',"v1":'+JSON.stringify(row)+'}')); + if(kind==="changed_meta")await put(metaScope,{"vectors:meta":{...metadata,count:2}}); + if(kind==="symlink"){await rename(file(bucket),file("elsewhere"));await symlink(file("elsewhere"),file(bucket));} + if(kind==="unadmitted")opts.admitted=()=>false; + await expect(verifyVectorCheckpointFiles(opts)).rejects.toThrow(); +}); +it("rejects same-byte inode replacement or a lost writer before mutation",async()=>{ + let admitted=true; + const check=await verifyVectorCheckpointFiles({...input(),admitted:()=>admitted}); + admitted=false;await expect(check()).rejects.toThrow(); + admitted=true;await rename(file(bucket),file("old"));await put(bucket,{v1:vector}); + await expect(check()).rejects.toThrow(); +}); + +it("rejects an extra physical copy of a selected ID even under another key or selected bucket",async()=>{ + const second={...row,id:"v2",q:2},meta={...metadata,bucketCount:2,count:2}; + await put(pending,{v1:row,v2:second});await put(metaScope,{"vectors:meta":meta}); + await put(metaScope+":vec:0001",{v2:{...vector,id:"v2"},other:vector}); + await expect(verifyVectorCheckpointFiles({...input(),meta,pendingRows:[row,second], + buckets:[{bucket:0,ids:["v1"]},{bucket:1,ids:["v2"]}]})).rejects.toThrow(); +}); + +it("never treats a missing namespace as evidence for remaining work",async()=>{ + await rm(file(pending)); + await expect(verifyRemainingVectorPending(input())).rejects.toThrow(); + await expect(verifyVectorCheckpointFiles(input())).rejects.toThrow(); + await symlink(file("missing"),file(pending)); + await expect(verifyRemainingVectorPending({...input(),pendingRows:[]})).rejects.toThrow(); +}); + +it("rejects ambiguous sequence numbers and invalid float data before proof",async()=>{ + await expect(verifyRemainingVectorPending({...input(),pendingRows:[row,{...row,id:"v2"}]})).rejects.toThrow(); + const bad={...row,e:Buffer.from(new Float32Array([NaN]).buffer).toString("base64")}; + await put(pending,{v1:bad}); + await expect(verifyRemainingVectorPending({...input(),pendingRows:[bad]})).rejects.toThrow(); +}); + +const retained = "mem:index:vec-retained:v1"; +const digest = "ab".repeat(32), otherDigest = "cd".repeat(32); +const stamp = {v:1,id:"v1",q:1,bucket:0,digest}; +const retention = (receipts:Record, admitted=()=>true) => + verifyVectorRetentionReceipts({storePath,receipts,admitted}); + +it("proves exactly all receipt keys and accepts an absent namespace only for zero receipts",async()=>{ + await expect(retention({})).resolves.toBeUndefined(); + await expect(retention({[digest]:stamp})).rejects.toThrow(); + await put(retained,{[digest]:stamp}); + await expect(retention({[digest]:stamp})).resolves.toBeUndefined(); + await expect(retention({})).rejects.toThrow(); + const other={...stamp,digest:otherDigest,id:"v2",q:2}; + await put(retained,{[otherDigest]:other,[digest]:stamp}); + await expect(retention({[digest]:stamp,[otherDigest]:other})).resolves.toBeUndefined(); + await expect(retention({[digest]:stamp})).rejects.toThrow(); +}); + +it.each(["digest","key","version","extra","missing","empty_id","clear_id","id_length","sequence","bucket", + "duplicate_id","duplicate_q","too_many"])("rejects invalid retention receipt %s even on matching disk",async kind=>{ + const row:Record={...stamp}; + const receipts:Record={[digest]:row}; + if(kind==="digest")row.digest=otherDigest; + if(kind==="key"){delete receipts[digest];row.digest="X".repeat(64);receipts[String(row.digest)]=row;} + if(kind==="version")row.v=2; + if(kind==="extra")row.unsupported=true; + if(kind==="missing")delete row.bucket; + if(kind==="empty_id")row.id=""; + if(kind==="clear_id")row.id="~clear"; + if(kind==="id_length")row.id="a".repeat(513); + if(kind==="sequence")row.q=0; + if(kind==="bucket")row.bucket=-1; + if(kind==="duplicate_id")receipts[otherDigest]={...stamp,digest:otherDigest,q:2}; + if(kind==="duplicate_q")receipts[otherDigest]={...stamp,digest:otherDigest,id:"v2"}; + if(kind==="too_many")for(let i=1;i<=16;i++){ + const d=i.toString(16).padStart(64,"0");receipts[d]={...stamp,id:"v"+(i+1),q:i+1,digest:d}; + } + await put(retained,receipts); + await expect(retention(receipts)).rejects.toThrow(); +}); + +it("refuses duplicate physical receipt keys, a symlink and writer loss during recheck", async()=>{ + const receipts={[digest]:stamp}; + const kv=JSON.stringify(digest)+":"+JSON.stringify(stamp); + await writeFile(file(retained),archive("{"+kv+","+kv+"}")); + await expect(retention(receipts)).rejects.toThrow(); + await rename(file(retained),file("old-receipts")); + await symlink(file("old-receipts"),file(retained)); + await expect(retention(receipts)).rejects.toThrow(); + await rm(file(retained)); + await put(retained,receipts); + let checks=0; + await expect(retention(receipts,()=>++checks<4)).rejects.toThrow(); +}); diff --git a/test/vector-checkpoint-transaction.test.ts b/test/vector-checkpoint-transaction.test.ts new file mode 100644 index 0000000000..55b15f4d09 --- /dev/null +++ b/test/vector-checkpoint-transaction.test.ts @@ -0,0 +1,99 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {mkdtempSync,writeFileSync,rmSync,readFileSync} from 'node:fs'; +import {join} from 'node:path'; +import {tmpdir} from 'node:os'; +import {StateKV} from '../src/state/kv.js'; +import {acquireFileWriterLease} from '../src/ops/file-writer-lease.mjs'; +import {engineFixture} from './helpers/engine-evidence.js'; + +const pending='mem:index:vec-pending', index='mem:index:bm25', bucket=index+':vec:0000'; +const dirs:string[]=[]; +afterEach(()=>{vi.unstubAllEnvs();for(const d of dirs.splice(0))rmSync(d,{recursive:true,force:true});}); +function archive(value:unknown){ + const bytes=Buffer.from(JSON.stringify(value)); + if(bytes.length<=8){const inline=Buffer.alloc(8,0xff);bytes.copy(inline);return inline;} + const root=Math.ceil(bytes.length/4)*4,out=Buffer.alloc(root+8); + bytes.copy(out);out.writeUInt32LE((bytes.length&63)+128+Math.floor(bytes.length/64)*256,root);out.writeInt32LE(-root,root+4); + return out; +} +function fixture(){ + const store=mkdtempSync(join(tmpdir(),'am-vector-proof-'));dirs.push(store);vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH',store); + const {evidence}=engineFixture(store);const lease=acquireFileWriterLease(store,{evidence}); + const data=new Map>(),path=(scope:string)=>join(store,encodeURIComponent(scope)+'.bin'); + const write=(scope:string)=>writeFileSync(path(scope),archive(Object.fromEntries(data.get(scope)!))); + const rows=[1,2,3].map(q=>({id:'vec_'+q,s:'session',e:'AACAPw==',q})); + const meta={v:3,count:3,bucketCount:1,savedAt:'2026-01-01T00:00:00.000Z'}; + data.set(index,new Map([['vectors:meta',meta]]));data.set(bucket,new Map(rows.map(({id,s,e})=>[id,{id,s,e}]))); + data.set(pending,new Map(rows.map(row=>[row.id,row]))); + for(const scope of data.keys())write(scope); + const receipts='mem:index:vec-retained:v1'; + const actions:Array<{scope:string,key:string,op:string}>=[];let onSet=async(_key:string)=>{}; + const sdk={trigger:async({function_id,payload:{scope,key,value}}:any)=>{ + const scoped=data.get(scope)??new Map();data.set(scope,scoped); + if(function_id==='state::list')return [...scoped.values()]; + if(function_id==='state::get')return scoped.get(key)??null; + if(function_id==='state::delete')throw Error('unexpected destructive SDK call'); + if(function_id==='state::set'){await onSet(key);actions.push({scope,key,op:'set'});scoped.set(key,value);write(scope);return value;} + throw Error('unexpected SDK call'); + }}; + const kv=new StateKV(sdk as never,{writerLease:lease}); + const selection=(rs=rows)=>({pendingRows:rs,meta,buckets:[{bucket:0,ids:rs.map(row=>row.id)}]}); + const prove=(authorize=true)=>kv.reconcileVectorCheckpoint(selection(),()=>true,kv.vectorCheckpointRevision,authorize); + return {kv,lease,rows,disk:path,actions,data,selection,receipts,prove,write,onSet:(fn:typeof onSet)=>{onSet=fn;}}; +} +it('certifies three original rows without modifying their buckets or WAL, including retry or restart',async()=>{ + const x=fixture(),initial=readFileSync(x.disk(bucket)),wal=readFileSync(x.disk(pending)); + try{ + const result=await x.prove();expect(result).toHaveLength(3); + expect(x.actions).toEqual(result.map(s=>({scope:x.receipts,key:s.digest,op:'set'}))); + expect(await x.prove()).toEqual(result);expect(await x.prove(false)).toEqual(result); + expect(x.actions).toHaveLength(3); + expect(readFileSync(x.disk(pending))).toEqual(wal); + expect(readFileSync(x.disk(bucket))).toEqual(initial); + }finally{x.lease.close();} +}); +it.each(['changed disk checkpoint','lost authorization','no manual authority'])('performs no writes on %s',async mode=>{ + const x=fixture();try{ + if(mode==='changed disk checkpoint')writeFileSync(x.disk(bucket),archive({})); + await expect(x.kv.reconcileVectorCheckpoint(x.selection(),()=>mode!=='lost authorization',x.kv.vectorCheckpointRevision,mode!=='no manual authority')).rejects.toThrow(); + expect(x.actions).toHaveLength(0); + }finally{x.lease.close();} +}); +it('retains all source records and blocks same-epoch retry on failed receipt creation',async()=>{ + const x=fixture(),wal=readFileSync(x.disk(pending));try{ + let n=0;x.onSet(async()=>{if(++n===2)throw Error('disconnected');}); + await expect(x.prove()).rejects.toThrow();expect(x.actions).toHaveLength(1); + await expect(x.prove()).rejects.toThrow(/unverified/); + expect(readFileSync(x.disk(pending))).toEqual(wal); + }finally{x.lease.close();} +}); +it('refuses changed remote bytes even after a receipt write without deleting the changed original',async()=>{ + const x=fixture();try{ + const changed={...x.rows[0],q:17};x.onSet(async()=>{x.data.get(pending)!.set(changed.id,changed);x.write(pending);}); + await expect(x.prove()).rejects.toThrow(); + expect(x.data.get(pending)!.get(changed.id)).toEqual(changed); + expect(x.actions.every(a=>a.scope===x.receipts)).toBe(true); + await expect(x.prove()).rejects.toThrow(); + }finally{x.lease.close();} +}); +it('serializes a new local WAL key until all originals have been reverified',async()=>{ + const x=fixture();let release!:()=>void,signal!:()=>void; + const reached=new Promise(r=>signal=r);const wait=new Promise(r=>release=r); + try{ + x.onSet(async()=>{signal();await wait;}); + const repair=x.prove();await reached; + const newRow={...x.rows[0],id:'different',q:5}; + const write=x.kv.set(pending,newRow.id,newRow); + await new Promise(r=>setTimeout(r,10)); + expect(x.data.get(pending)!.has(newRow.id)).toBe(false);release();await repair;await write; + expect([...x.data.get(pending)!.keys()]).toEqual([...x.rows.map(r=>r.id),'different']); + }finally{release?.();x.lease.close();} +}); +it('rejects a checkpoint changed while the SDK was discovering its bucket map',async()=>{ + const x=fixture();try{ + const revision=x.kv.vectorCheckpointRevision; + await x.kv.set(bucket,'new-after-load',{id:'new-after-load',s:'s',e:'AACAPw=='}); + await expect(x.kv.reconcileVectorCheckpoint(x.selection(),()=>true,revision,true)).rejects.toThrow(/checkpoint_changed/); + expect(x.actions.some(a=>a.scope===x.receipts)).toBe(false); + }finally{x.lease.close();} +}); From 98c872319e60e4b535a35f6b2209e612e55cb4d6 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 7 Nov 2026 01:41:12 +0900 Subject: [PATCH 03/23] fix: preserve disk caller admission and await checkpoint metadata convergence --- CHANGELOG.md | 1 + src/ops/vector-checkpoint-proof.d.mts | 2 +- src/ops/vector-checkpoint-proof.mjs | 26 +++++++++++-- src/state/index-persistence.ts | 5 ++- src/state/kv.ts | 18 ++++++++- src/state/vector-checkpoint-reconciliation.ts | 6 ++- test/vector-checkpoint-proof.test.ts | 18 +++++++++ test/vector-checkpoint-transaction.test.ts | 38 ++++++++++++++++++- 8 files changed, 102 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 58d9d9d6ce..e3f47d5673 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ - Support explicit authenticated recovery of a bounded set of vector upserts whose pending and checkpoint records agree in the native store. Preserve the original upserts and record their verified coverage separately. Revalidate coverage on restart and distinguish retained records from pending publication in the index status. - Require the current cooperative writer, stable checkpoint, matching physical keys and vector bytes. Conflicting updates, clears or incomplete evidence leave recovery blocked. Automatic recovery and deployment resume cannot authorize new coverage. +- Preserve standalone disk-mode indexing when the approved file store has no retention records. During capture reconciliation, a lagging checkpoint timestamp can converge for up to 1.5 seconds before the full evidence check. A failed check leaves the capture and original log intact. - Record the deployment and operational acceptance separately from this source candidate in the November 7 incident report. ## [0.9.32-daniel.58] — 2026-11-06 (recovery review candidate) diff --git a/src/ops/vector-checkpoint-proof.d.mts b/src/ops/vector-checkpoint-proof.d.mts index 80bfd2739f..874f66fe26 100644 --- a/src/ops/vector-checkpoint-proof.d.mts +++ b/src/ops/vector-checkpoint-proof.d.mts @@ -1,6 +1,6 @@ type Evidence = {storePath:string; pendingRows:readonly unknown[]; admitted:()=>boolean}; export function verifyVectorCheckpointFiles(options: Evidence & { - meta:unknown; buckets:readonly {bucket:number; ids:readonly string[]}[]; + waitForCaptureMeta?:boolean; meta:unknown; buckets:readonly {bucket:number; ids:readonly string[]}[]; }):Promise<()=>Promise>; export function verifyRemainingVectorPending(options: Evidence):Promise; export function verifyVectorRetentionReceipts(options: { diff --git a/src/ops/vector-checkpoint-proof.mjs b/src/ops/vector-checkpoint-proof.mjs index 31a56d25f4..a60ef99578 100644 --- a/src/ops/vector-checkpoint-proof.mjs +++ b/src/ops/vector-checkpoint-proof.mjs @@ -110,7 +110,7 @@ async function prove(storePath, admitted, files) { const {bytesRead}=await handle.read(data,offset,Math.min(MiB,size-offset),offset); requireProof(bytesRead>0 && performance.now() {await current();await verifyNames(storePath,true);await verifyNames(storePath);await current();}; } -export async function verifyVectorCheckpointFiles({storePath,pendingRows,meta,buckets,admitted}) { +export async function verifyVectorCheckpointFiles({storePath,pendingRows,meta,buckets,admitted,waitForCaptureMeta=false}) { const byId=pendingMap(pendingRows), selected=new Map(); requireProof(byId.size>0 && meta?.v===3 && Number.isSafeInteger(meta.bucketCount) && meta.bucketCount>0 && Number.isSafeInteger(meta.count) && meta.count>=byId.size && Array.isArray(buckets) && buckets.length>0 && buckets.length<=byId.size); const expectedMeta=structuredClone(meta); - const files=[pendingFile(byId), {scope:META,limit:4*MiB,verify(rows){requireProof(isDeepStrictEqual(rows['vectors:meta'],expectedMeta));}}]; + const laggingTimestamp = Symbol('laggingCheckpointTimestamp'); + const deadline = performance.now() + 1500; + // Check metadata first. Retrying a small, older timestamp must never reread buckets. + const files=[{scope:META,limit:4*MiB,verify(rows,size){ + const current = rows['vectors:meta']; + if (isDeepStrictEqual(current,expectedMeta)) return; + if (waitForCaptureMeta && size <= 64*1024 && current && + typeof current.savedAt === 'string' && typeof expectedMeta.savedAt === 'string' && + Date.parse(current.savedAt) < Date.parse(expectedMeta.savedAt) && + isDeepStrictEqual({...current,savedAt:expectedMeta.savedAt},expectedMeta)) throw laggingTimestamp; + requireProof(false); + }}, pendingFile(byId)]; const seenBuckets=new Set(); for (const {bucket,ids} of buckets) { requireProof(Number.isSafeInteger(bucket)&&bucket>=0&&bucket0&&ids.length<=byId.size); @@ -144,7 +155,14 @@ export async function verifyVectorCheckpointFiles({storePath,pendingRows,meta,bu }}); } requireProof(selected.size===byId.size); - return prove(storePath,admitted,files); + for (;;) { + try { return await prove(storePath,admitted,files); } + catch (error) { + if (error !== laggingTimestamp) throw error; + requireProof(admitted() === true && performance.now() < deadline); + await new Promise(resolve=>setTimeout(resolve,Math.min(125,deadline-performance.now()))); + } + } } export async function verifyRemainingVectorPending({storePath,pendingRows,admitted}) { diff --git a/src/state/index-persistence.ts b/src/state/index-persistence.ts index e4c21bbd67..91124d2506 100644 --- a/src/state/index-persistence.ts +++ b/src/state/index-persistence.ts @@ -274,7 +274,8 @@ export class IndexPersistence { this.storageGeneration = options.storageGeneration ?? (() => 0); this.bootStorageGeneration = this.storageGeneration(); this.vector?.setChangeListener((id, entry) => this.logChange(id, entry)); - this.retentionReady = !this.hasRetentionStore(); + this.retentionReady = !this.hasRetentionStore() || + (!options.requireRecoveryPlan && this.kv.canUseUnloadedDiskIndex?.() === true); this.vector?.setMutationGuard(id => { if (!this.retentionReady || (id === null ? this.retainedRows.size > 0 : this.retainedRows.has(id)) || (!this.logSuppressed && (this.isStorageHeld() || this.storageBlocked || this.storageRecovering || @@ -561,7 +562,7 @@ export class IndexPersistence { const rows = [...this.retainedRows.values()]; const selected = this.checkpointSelection({state: 'buckets', vector: this.vector, savedAt: meta.savedAt, checkpointMeta: meta, expectedCount: meta.count}, rows); - await this.kv.reconcileVectorCheckpoint(selected, current, revision, false); + await this.kv.reconcileVectorCheckpoint(selected, current, revision, false, true); return current(); } catch { return false; } } diff --git a/src/state/kv.ts b/src/state/kv.ts index 116c096deb..f045e32556 100644 --- a/src/state/kv.ts +++ b/src/state/kv.ts @@ -1,3 +1,5 @@ +import { lstatSync, realpathSync } from 'node:fs' +import { join } from 'node:path' import {bucketScope, reconcileCheckpoint, readRetention, receiptFor, RETAINED_SCOPE, type RetentionReceipt, type RecoverySelection} from './vector-checkpoint-reconciliation.js' import {KV} from './schema.js' import {createRecordRecoveryGate, createRecoveryWriteGate} from './recovery-write-gate.js' @@ -173,6 +175,17 @@ export class StateKV { })) } + canUseUnloadedDiskIndex(): boolean { + // Standalone disk-fenced callers may start with an empty index. Once a receipt + // exists, only the normal load/revalidation path can admit its retained WAL. + const store = this.checkpointStorePath + if (this.durability?.completion !== 'disk' || !store) return false + try { + return realpathSync(store) === store && lstatSync(store).isDirectory() && + lstatSync(join(store, encodeURIComponent(RETAINED_SCOPE) + '.bin'), {throwIfNoEntry: false}) === undefined + } catch { return false } + } + async readVectorRetention():Promise { if (this.backend !== 'file') return [] if (!this.checkpointStorePath) throw Error('vector_retention_store_unverified') @@ -180,8 +193,9 @@ export class StateKV { (!this.writerLease || ownsFileWriterLease(this.writerLease,this.checkpointStorePath!))) } - async reconcileVectorCheckpoint(selection:RecoverySelection,current:()=>boolean,expectedRevision:number,authorize:boolean):Promise{ + async reconcileVectorCheckpoint(selection:RecoverySelection,current:()=>boolean,expectedRevision:number,authorize:boolean,waitForCaptureMeta=false):Promise{ const gate=this.recoveryWrite, storePath=this.writerStorePath + if (waitForCaptureMeta && authorize) throw Error('vector_retention_capture_is_read_only') if(!gate || !storePath || !this.recoveryMutationSafe || (authorize && this.durability?.completion!=='sdk'))throw Error('vector_recovery_writer_unverified') const keys:Array<{scope:string;key:string}>=[{scope:KV.vectorPendingLog,key:'~clear'},{scope:KV.bm25Index,key:'vectors:meta'}, ...selection.pendingRows.map(({id})=>({scope:KV.vectorPendingLog,key:id}))] @@ -194,7 +208,7 @@ export class StateKV { if (this.vectorRevision!==expectedRevision) throw Error('vector_recovery_checkpoint_changed') const admitted=()=>current() && (!authorize || gate.inExclusive()) && this.recoveryMutationSafe const existing=await readRetention(this,storePath,admitted) - return reconcileCheckpoint(this,storePath,selection,existing,authorize,admitted) + return reconcileCheckpoint(this,storePath,selection,existing,authorize,admitted,waitForCaptureMeta) }) // Read-only rechecks can run within capture's existing record gate. They never acquire another record lock. return authorize ? gate.exclusive(keys,verify) : verify() diff --git a/src/state/vector-checkpoint-reconciliation.ts b/src/state/vector-checkpoint-reconciliation.ts index 8adeedc86b..d6fc411b01 100644 --- a/src/state/vector-checkpoint-reconciliation.ts +++ b/src/state/vector-checkpoint-reconciliation.ts @@ -57,7 +57,7 @@ export async function readRetention(kv: StateKV, storePath: string, admitted: () export async function reconcileCheckpoint( kv: StateKV, storePath: string, selection: RecoverySelection, existing: RetentionReceipt[], - authorize: boolean, admitted: () => boolean, + authorize: boolean, admitted: () => boolean, waitForCaptureMeta = false, ): Promise { const { pendingRows, buckets, meta } = selection; function check() { @@ -93,7 +93,7 @@ export async function reconcileCheckpoint( throw Error('vector_retention_original_changed'); const missing = expected.filter(wanted => !existing.some(stamp => isDeepStrictEqual(stamp, wanted))); if (missing.length && !authorize) throw Error('vector_retention_manual_verification_required'); - const recheck = await verifyVectorCheckpointFiles({storePath, pendingRows, meta, buckets, admitted}); + const recheck = await verifyVectorCheckpointFiles({storePath, pendingRows, meta, buckets, admitted, waitForCaptureMeta}); await recheck(); // iii has no conditional delete. Preserve the entire WAL. Immutable receipt keys make @@ -113,6 +113,8 @@ export async function reconcileCheckpoint( if (saved.length !== expected.length || !expected.every(stamp => saved.some(actual => isDeepStrictEqual(stamp, actual)))) throw Error('vector_retention_receipts_changed'); await confirmPending(); + if (waitForCaptureMeta && !isDeepStrictEqual(await kv.get(KV.bm25Index, 'vectors:meta'), meta)) + throw Error('vector_recovery_meta_changed'); await recheck(); return saved; } diff --git a/test/vector-checkpoint-proof.test.ts b/test/vector-checkpoint-proof.test.ts index fec5eabdfc..b77ce75b0f 100644 --- a/test/vector-checkpoint-proof.test.ts +++ b/test/vector-checkpoint-proof.test.ts @@ -134,3 +134,21 @@ it("refuses duplicate physical receipt keys, a symlink and writer loss during re let checks=0; await expect(retention(receipts,()=>++checks<4)).rejects.toThrow(); }); + +it('waits for a previous savedAt to flush, then still checks the complete selected bucket',async()=>{ + const stale={...metadata,savedAt:'2026-11-06T23:59:59Z'}; + await put(metaScope,{'vectors:meta':stale});await put(bucket,{v1:{...vector,e:'AAAAAA=='}}); + const flushed=new Promise((resolve,reject)=>setTimeout(()=>{put(metaScope,{'vectors:meta':metadata}).then(resolve,reject);},175)); + await expect(verifyVectorCheckpointFiles({...input(),waitForCaptureMeta:true})).rejects.toThrow('VECTOR_CHECKPOINT_UNVERIFIED'); + await flushed; + await put(metaScope,{'vectors:meta':stale});await put(bucket,{v1:vector}); + const next=new Promise((resolve,reject)=>setTimeout(()=>{put(metaScope,{'vectors:meta':metadata}).then(resolve,reject);},175)); + const recheck=await verifyVectorCheckpointFiles({...input(),waitForCaptureMeta:true}); + await next;await recheck(); +}); +it.each(['persistent lag','revoked epoch'])('keeps the original rejection on %s during capture proof',async mode=>{ + await put(metaScope,{'vectors:meta':{...metadata,savedAt:'2026-11-06T23:59:59Z'}}); + let active=true;const timer=mode==='revoked epoch'?setTimeout(()=>{active=false},100):undefined; + try{await expect(verifyVectorCheckpointFiles({...input(),admitted:()=>active,waitForCaptureMeta:true})).rejects.toThrow('VECTOR_CHECKPOINT_UNVERIFIED');} + finally{clearTimeout(timer);} +}); diff --git a/test/vector-checkpoint-transaction.test.ts b/test/vector-checkpoint-transaction.test.ts index 55b15f4d09..e6d94e6607 100644 --- a/test/vector-checkpoint-transaction.test.ts +++ b/test/vector-checkpoint-transaction.test.ts @@ -2,6 +2,9 @@ import {afterEach,expect,it,vi} from 'vitest'; import {mkdtempSync,writeFileSync,rmSync,readFileSync} from 'node:fs'; import {join} from 'node:path'; import {tmpdir} from 'node:os'; +import {IndexPersistence} from '../src/state/index-persistence.js'; +import {VectorIndex} from '../src/state/vector-index.js'; +import {createStateDurabilityFence} from '../src/ops/state-durability.mjs'; import {StateKV} from '../src/state/kv.js'; import {acquireFileWriterLease} from '../src/ops/file-writer-lease.mjs'; import {engineFixture} from './helpers/engine-evidence.js'; @@ -39,7 +42,7 @@ function fixture(){ const kv=new StateKV(sdk as never,{writerLease:lease}); const selection=(rs=rows)=>({pendingRows:rs,meta,buckets:[{bucket:0,ids:rs.map(row=>row.id)}]}); const prove=(authorize=true)=>kv.reconcileVectorCheckpoint(selection(),()=>true,kv.vectorCheckpointRevision,authorize); - return {kv,lease,rows,disk:path,actions,data,selection,receipts,prove,write,onSet:(fn:typeof onSet)=>{onSet=fn;}}; + return {kv,sdk,store,lease,rows,disk:path,actions,data,selection,receipts,prove,write,onSet:(fn:typeof onSet)=>{onSet=fn;}}; } it('certifies three original rows without modifying their buckets or WAL, including retry or restart',async()=>{ const x=fixture(),initial=readFileSync(x.disk(bucket)),wal=readFileSync(x.disk(pending)); @@ -97,3 +100,36 @@ it('rejects a checkpoint changed while the SDK was discovering its bucket map',a expect(x.actions.some(a=>a.scope===x.receipts)).toBe(false); }finally{x.lease.close();} }); + + +it('keeps the standalone disk entry point while requiring a boot check for existing or invalid retention receipts',async()=>{ + const x=fixture();try{ + const disk=new StateKV(x.sdk as never,{durability:createStateDurabilityFence({storePath:x.store,completion:'disk'})}); + const plain=new VectorIndex(),oldCaller=new IndexPersistence(disk,plain); + expect(()=>plain.add('new','s',new Float32Array([1]))).not.toThrow(); + await oldCaller.save();oldCaller.stop(); + for(const bad of [false,true]){ + writeFileSync(x.disk(x.receipts),bad?Buffer.from('invalid'):archive({})); + const target=new VectorIndex(),fresh=new IndexPersistence(disk,target); + try{expect(()=>target.add('new','s',new Float32Array([1]))).toThrow(/VECTOR_RECOVERY_PAUSED/); + expect(target.pendingChanges).toBe(0);}finally{fresh.stop();} + } + }finally{x.lease.close();} +}); + +it('revalidates the current SDK metadata after a retained capture waited for disk, without writing',async()=>{ + const x=fixture();try{ + await x.prove(); + const selected=x.selection(), older={...selected.meta,savedAt:'2025-12-31T00:00:00.000Z'}; + const wal=readFileSync(x.disk(pending)),writes=x.actions.length; + writeFileSync(x.disk(index),archive({'vectors:meta':older})); + const repair=x.kv.reconcileVectorCheckpoint(selected,()=>true,x.kv.vectorCheckpointRevision,false,true); + const timer=setTimeout(()=>{ + writeFileSync(x.disk(index),archive({'vectors:meta':selected.meta})); + // A second publisher advanced SDK state after selection; the old disk value cannot certify that change. + x.data.get(index)!.set('vectors:meta',{...selected.meta,savedAt:'2026-01-02T00:00:00.000Z'}); + },175); + try{await expect(repair).rejects.toThrow(/meta_changed/);}finally{clearTimeout(timer);} + expect(x.actions).toHaveLength(writes);expect(readFileSync(x.disk(pending))).toEqual(wal); + }finally{x.lease.close();} +}); From 7343a8e45aba4e73cf228564290ea1ae95479068 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 7 Nov 2026 12:00:57 +0900 Subject: [PATCH 04/23] fix(capture): bound retained inbox reads and selected recovery --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 6 + docs/customizations/CAPTURE-INBOX-60.md | 37 ++ .../plans/2026-11-07-capture-inbox.md | 50 +++ integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/_capture.mjs | 18 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 4 +- src/capture/inbox-metadata.ts | 54 +++ src/capture/retry-jobs.ts | 5 +- src/capture/review.ts | 13 +- src/capture/sdk-delivery-v2.ts | 42 +++ src/capture/sdk-spool-v2.ts | 16 +- src/functions/capture.ts | 38 +- src/functions/export-import.ts | 2 +- src/mcp/in-memory-kv.ts | 5 +- src/ops/graph-file-list.d.mts | 2 +- src/ops/graph-file-list.mjs | 31 +- src/state/kv.ts | 13 +- src/types.ts | 2 +- src/version.ts | 2 +- test/capture-auto-recovery.test.ts | 2 +- test/capture-inbox-file-list.test.ts | 354 ++++++++++++++++++ test/capture-sdk-reconciliation.test.ts | 25 +- test/helpers/mocks.ts | 5 +- test/sdk-explicit-recovery-v2.test.ts | 101 +++++ tsdown.config.ts | 7 + 39 files changed, 781 insertions(+), 87 deletions(-) create mode 100644 docs/customizations/CAPTURE-INBOX-60.md create mode 100644 docs/superpowers/plans/2026-11-07-capture-inbox.md create mode 100644 src/capture/inbox-metadata.ts create mode 100644 test/capture-inbox-file-list.test.ts create mode 100644 test/sdk-explicit-recovery-v2.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 318589c7d1..c68321dc10 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index d3f7ad3c50..0c6f0ed31b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.59) +## Current Stats (v0.9.32-daniel.60) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index e3f47d5673..9313d45f48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ## [Unreleased] +## [0.9.32-daniel.60] — 2026-11-07 +- Read retained capture inboxes through the existing local streaming reader with SDK-acknowledged changes overlaid. Project status and bounded previews before retaining rows, so capture admission, review and retry no longer request an oversized shared SDK frame. Read keyed review metadata once for status instead of making one SDK call per retained original. Keep original payloads and existing per-source completion proofs. +- Add an explicitly invoked selected-source recovery entry for held SDK-v2 sources. Revalidate the retained original, claim it atomically, verify the restore reply, and preserve the original after SDK acknowledgement. Ordinary hooks do not invoke restoration; SDK acknowledgement is not a disk durability claim. +- Preserve the installed compatibility hooks in the server-only release. Source validation, package/native acceptance and operational application are recorded separately in `docs/customizations/CAPTURE-INBOX-60.md` and the November 7 incident dossier. + ## [0.9.32-daniel.59] — 2026-11-07 (held recovery candidate) - Support explicit authenticated recovery of a bounded set of vector upserts whose pending and checkpoint records agree in the native store. Preserve the original upserts and record their verified coverage separately. Revalidate coverage on restart and distinguish retained records from pending publication in the index status. @@ -574,6 +579,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.60]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.59...v0.9.32-daniel.60 [0.9.32-daniel.57]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.55...v0.9.32-daniel.57 [0.9.32-daniel.55]: https://github.com/rohitg00/agentmemory/compare/v0.9.31-daniel.54...v0.9.32-daniel.55 [0.9.31-daniel.54]: https://github.com/rohitg00/agentmemory/compare/v0.9.31-daniel.51...v0.9.31-daniel.54 diff --git a/docs/customizations/CAPTURE-INBOX-60.md b/docs/customizations/CAPTURE-INBOX-60.md new file mode 100644 index 0000000000..04b8e7b6cb --- /dev/null +++ b/docs/customizations/CAPTURE-INBOX-60.md @@ -0,0 +1,37 @@ +# Capture inbox read recovery — daniel.60 + +## Evidence and goal + +The deployed .59 inbox contains 5,074 retained SDK-acknowledged originals. Its serialized SDK list is 67,220,776 bytes, above the 67,108,864-byte SDK WebSocket maximum. `status: pending` alone does not mean these retained records need delivery; `storageCompletion: sdk` is a separate acknowledgement, not proof of disk persistence. + +The fixed .59 package and native engine reproduced the failure with synthetic data: `state::list` exceeding the limit disconnects the requesting SDK, and a normal `/status` call disconnects the worker SDK, transiently making health return 500/404. Worker and engine PIDs survive. Recovery must allow capture, status, review and retry to work as retained originals accumulate, preserve all originals and avoid treating uncertain delivery as completion. + +## Approaches and choice + +- Increasing the frame limit postpones the same failure and increases peak serialization/parse memory. Completion retains originals, so the collection keeps growing even when work succeeds. +- Native keyset pagination would avoid full namespace transfers but the installed engine exposes only `state::get` and `state::list` for this path. Changing the native engine and SDK protocol is unnecessary for this incident. +- Reuse the existing local namespace streaming reader with the existing acknowledged-write overlay. Project each disk record immediately into the metadata needed by consumers; fetch selected originals individually for processing or proof. This is the implementation choice under the user's instruction to select and implement the best solution. + +## Read boundaries + +The file backend streams fixed-size chunks and parses one record at a time. Inbox list consumers retain metadata and bounded previews, not every payload. Existing list ordering, page limits and filters remain. Capture admission's initial size scan is cached by the controller; it is not repeated for every capture. Retry and sweep select keys and use the existing `retryOne` keyed get/lock before processing. + +The shared reader overlays acknowledged changes, including deletes, until the file contains them. Reads return independent values, so a caller cannot mutate cached acknowledged state. Concurrent file replacement is detected and retried at most once; uncertain mutations fail closed. The full-list interface remains compatible for callers that explicitly need it. Redis behavior is preserved; this release does not claim native Redis pagination. + +The first packaged native trial removed disconnects and completed a new capture in 124ms, but exposed another bottleneck: status performed 5,074 individual history reads and exceeded its five-second budget. The final implementation also reads a keyed review metadata projection once. Only records with reconciliation markers require the original full history/source verification. Physical keys must match the history identity; malformed or uncertain records cannot produce a completion count. Backends without that local reader keep the original SDK lookup path. The count is an informational snapshot, never an authorization or disk-completion proof. + +This bounds retained disk payload memory to a record at a time, plus metadata for all records and acknowledged payloads not yet confirmed in the file. It does not make memory independent of item count or eliminate scan I/O. Pending acknowledged payloads must not be discarded just to lower memory use. Completion proofs still check source/hash/history consistency; proof paths that need payloads load only selected originals. + +## Explicit source recovery + +Existing pending source references use the normal delivery implementation. Selected held sources require an explicit product restore entry, exact source revalidation and an atomic owner claim. Normal hooks do not invoke restoration. Only a fully matching SDK restore response may acknowledge a reference; SDK acknowledgement remains distinct from later disk/index acceptance. A response loss leaves evidence for inspection and must not be blindly retransmitted. Original chunks remain preserved. + +## Verification and rollout + +Regression tests cover oversized inboxes, bounded metadata projections, current acknowledged update/delete overlays, caller mutation, uncertain writes, concurrent reads, existing pagination/preview behavior and valid/invalid resolution proofs. The packaged native trial must exceed 64MiB, include thousands of SDK-completed records, run actual status/list calls while health remains available, and confirm process and SDK connection continuity. Native raw `state::list` remains limited; product consumers must avoid it. + +Build and package a separate .60 server candidate. Preserve the issued .59 bundles and installed compatibility hooks. Recheck the normal SDK shutdown/COW engine deployment path and retained WAL coverage. At 11:18 KST, .59 reported a new mutation failure; its cumulative uncertainty cannot satisfy the normal shutdown certificate. That gate must remain closed. A separately reviewed recovery transaction must preserve the failed shutdown result, current disk state and process identity, and must not claim application flush verification. Do not restore an older data backup. After administrator activation, verify exact runtime identity, capture source acknowledgement, index publication, per-item physical vectors and a stable observation window. Historical memory-only writes lost before .59 and the new uncertain mutation remain unverified unless separate evidence resolves them. + +The final product bytes passed an isolated native trial with 5,074 originals (73,981,775 serialized bytes): status 790ms, 25-row list 1,377ms, review 1,248ms and new capture 70ms. All 25 concurrent health samples returned HTTP200; worker and engine identities remained unchanged, without SDK reconnects. Physical re-read verified every original against its full seed value. Peak memory was 747,687,936 bytes under a 1GiB cap with no OOM. A concurrent checkpoint replacement invalidates the whole physical read; the harness retries only that generation-change error, preserving exact equality and missing-row checks. Product and administrator acceptance remain distinct from operational collection/index acceptance. + +All 39 build configurations, SDK bundle audit, documentation and skill consistency checks passed. TypeScript reports the same 30 inherited diagnostics as .59. The full regression run exposed one fixture that populated review history behind the new local reader; routing its setup through `StateKV.set` restored all 29 tests, with 55 related tests passing. The fixture changes no product bytes. The final isolated full run passed 6,408 tests in 548 files, with 69 tests skipped and no failures. It uses the default fork pool and a temporary HOME; the normal integration suite and the inherited minimum-12GiB summary SDK boundary suite are excluded, as in .59. Frozen hashes and administrator results are recorded in the November 7 incident dossier; no production success is inferred from these isolated checks. diff --git a/docs/superpowers/plans/2026-11-07-capture-inbox.md b/docs/superpowers/plans/2026-11-07-capture-inbox.md new file mode 100644 index 0000000000..0348023f45 --- /dev/null +++ b/docs/superpowers/plans/2026-11-07-capture-inbox.md @@ -0,0 +1,50 @@ +# Capture Inbox Recovery Implementation Plan + +> **For agentic workers:** Use subagent-driven development for the disjoint inbox, explicit source recovery and deployment tasks; primary agent reviews the integrated candidate. + +**Goal:** Restore actual capture and indexing without oversized inbox SDK responses or loss of retained originals. + +**Architecture:** Reuse the file namespace reader and acknowledged-write overlay, project metadata during streaming, and load only selected originals. Keep explicit source restore on the existing product protocol and apply .60 through certified normal shutdown. + +**Tech Stack:** Existing TypeScript/Node, iii SDK/native engine, Python deployment tools, Vitest fork pool. + +**Spec:** `docs/customizations/CAPTURE-INBOX-60.md`. + +## Global Constraints + +- No production data/config for development tests; synthetic data and private network/mount namespace only. +- No raw-source loss, false disk-completion claims, data rollback, or change to issued .59 artifacts. +- Temporary real HOME and default fork pool for tests. Preserve installed compatibility hooks in the server-only artifact. + +## Review Focus + +- A projected record cannot satisfy a source-digest proof without separately loading and validating that original. +- Mutating returned values must not modify acknowledged overlay state. +- Deletes, concurrent file replacement and SDK write uncertainty cannot yield stale success. +- Thousands of already acknowledged originals must not require an oversized response or prevent health/capture progress. +- A lost restore response and delayed competing response must not acknowledge another attempt or trigger blind resends. + +## Task 1 — Inbox reads + +- [x] Reproduce original native .59 overflow and write failing capture entry regression. +- [ ] Add exact inbox scope to existing local reader; support projected reads through StateKV with unchanged full-list and backend fallback behavior. +- [ ] Use a shared metadata/preview projection in capture admission, sweep, status, retry, list, review and retry jobs. +- [ ] Reuse original completion verifier only after selected source and metadata agree; test invalid proof and changing source. +- [ ] Run focused regressions, then integrated tests/build and packaged native scale acceptance. + +Files: `src/ops/graph-file-list.*`, `src/state/kv.ts`, `src/functions/capture.ts`, `src/capture/{review,retry-jobs}.ts`, a shared capture projection helper, and focused capture/reader tests. + +## Task 2 — Selected source recovery + +- [ ] Reuse existing delivery for selected pending references. +- [ ] Implement explicit held-source claim and restore using `sdk-spool-v2.ts` and `sdk-delivery-v2.ts`; preserve source hashes, owner checks and acknowledgement semantics. +- [ ] Package a standalone operator-imported recovery entry; normal hooks do not invoke it. +- [ ] Test durable intent/response-loss/owner race handling with synthetic sources before operational use. + +## Task 3 — Deployment and acceptance + +- [ ] Update changelog, generate/check docs and skills, test and build, commit and freeze a separate .60 server-only candidate. +- [ ] Prepare normal .59→.60 deployment with exact previous receipt/code/engine bindings and physical retained-WAL coverage; use safe viewer snapshot preflight rather than .59 `/status`. +- [ ] Run actual generated guard/archive/read-back and normal transaction regressions, review and freeze the administrator enrollment command. +- [ ] After administrator activation, confirm exact .60 generation, resume through the official API, recover selected sources and verify actual SDK approval plus per-item physical indexing. +- [ ] Observe capture/embedding progress, SDK reconnects and service restarts; record implementation, deployment, limits and pending memory review separately. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 66d675a92d..7e9190f46a 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.59 +version: 0.9.32-daniel.60 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 51739bf077..2c2eb96930 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index e8673af14d..10857d0ca0 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index db771c2040..8ccce2a145 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index c4ea427bcd..ecfd8ef788 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.59 +version: 0.9.32-daniel.60 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index d30a6cedcf..d9955a049a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 7f4e6010a1..8c3767751b 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.59" + "@agentmemory/agentmemory": "0.9.32-daniel.60" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 821be7f559..6ed9b3301a 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index e74a3f5d54..35cdb86ffa 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index b4f6a59d36..9e2ff616ef 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.59" + "@agentmemory/mcp@0.9.32-daniel.60" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 364f35d4e8..616ac50ad2 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 65af56a678..9bd5ba6fe1 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/_capture.mjs b/plugin/scripts/_capture.mjs index 8ecb006c0e..d56f57eef3 100644 --- a/plugin/scripts/_capture.mjs +++ b/plugin/scripts/_capture.mjs @@ -1,6 +1,6 @@ import { performance } from "node:perf_hooks"; -import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs"; import { createHash, randomUUID } from "node:crypto"; +import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs"; import { homedir, platform } from "node:os"; import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path"; import { isDeepStrictEqual } from "node:util"; @@ -446,13 +446,17 @@ var SdkSpoolV2 = class { })); }); } - async markSending(target, sourceId) { + async markSending(target, sourceId, expectedHeldSource) { return this.locked(() => { const source = this.source(target, sourceId); if (source.manifest.conflict || source.manifest.completed) fail("SOURCE_HELD"); const ref = this.readRef(target, sourceId); - if (ref.state !== "pending") fail("SOURCE_HELD"); - if (ref.nextAttemptAt > Date.now()) fail("SOURCE_BACKOFF"); + if (expectedHeldSource) { + if (ref.state !== "held" || ref.owner || !isDeepStrictEqual(source.body, expectedHeldSource)) fail("SOURCE_HELD"); + } else { + if (ref.state !== "pending") fail("SOURCE_HELD"); + if (ref.nextAttemptAt > Date.now()) fail("SOURCE_BACKOFF"); + } const owner = ownerIdentity(); if (!owner) fail("STORE_BUSY"); ref.state = "sending"; @@ -466,7 +470,8 @@ var SdkSpoolV2 = class { const source = this.source(target, sourceId); if (source.manifest.conflict) fail("SOURCE_CONFLICT"); if (!source.manifest.completed) { - if (this.readRef(target, sourceId).state !== "sending") fail("SOURCE_HELD"); + const ref = this.readRef(target, sourceId); + if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); source.manifest.completed = true; this.atomicJson(join(this.originals, sourceId, "manifest.json"), source.manifest, "original", "ack_before_publish"); this.phase("ack_fsynced"); @@ -482,7 +487,7 @@ var SdkSpoolV2 = class { async retry(target, sourceId, _reason) { return this.locked(() => { const ref = this.readRef(target, sourceId); - if (ref.state !== "sending" || !ref.owner || !alive(ref.owner)) fail("SOURCE_HELD"); + if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); ref.attempts = Math.min(1e6, ref.attempts + 1); ref.nextAttemptAt = Date.now() + Math.min(3e5, 1e3 * 2 ** Math.min(9, ref.attempts - 1)); ref.state = "pending"; @@ -494,6 +499,7 @@ var SdkSpoolV2 = class { async hold(target, sourceId, _reason) { return this.locked(() => { const ref = this.readRef(target, sourceId); + if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); ref.state = "held"; ref.reason = "HELD"; delete ref.owner; diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 7748138cc8..ef7464b5c7 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.59"; +const VERSION = "0.9.32-daniel.60"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index e5e23b3a78..3b8bfbf85d 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.59", + "version": "0.9.32-daniel.60", "facts": { "mcpTools": [ "55" @@ -26,7 +26,7 @@ "355" ], "sourceFiles": [ - "282" + "283" ], "loc": [ "64000" diff --git a/src/capture/inbox-metadata.ts b/src/capture/inbox-metadata.ts new file mode 100644 index 0000000000..9b093089d4 --- /dev/null +++ b/src/capture/inbox-metadata.ts @@ -0,0 +1,54 @@ +import { isDeepStrictEqual } from 'node:util'; +import type { InboxRecord } from '../functions/capture.js'; +import type { CaptureReviewHistory } from '../types.js'; +import type { StateKV } from '../state/kv.js'; +import { KV } from '../state/schema.js'; +import { committedSdkResolution } from './sdk-resolution-record.js'; + +export type CaptureInboxMetadata = Omit & { + preview: string; + reviewPreview: string; +}; + +export function projectCaptureInbox(value: unknown): CaptureInboxMetadata { + const record = value as InboxRecord; + if (!record) return record; + const { payload, ...metadata } = record; + const data = payload?.data && typeof payload.data === 'object' ? payload.data as Record : {}; + const label = typeof data.tool_name === 'string' ? data.tool_name : payload?.hookType; + let text = ''; + try { text = JSON.stringify(data.tool_input ?? data.prompt ?? payload?.data ?? ''); } catch {} + const reviewLabel = typeof data.tool_name === 'string' ? data.tool_name : record.hookType; + return { + ...metadata, + preview: payload ? `${label}: ${text}`.slice(0, 160) : '', + reviewPreview: (reviewLabel + ': ' + JSON.stringify(data.tool_input ?? data.prompt ?? data.message ?? '')).slice(0, 500), + }; +} + +export function listCaptureInboxMetadata(kv: StateKV): Promise { + return kv.list(KV.captureInbox, { project: projectCaptureInbox }); +} + +export async function listLocalCaptureResolutionKeys(kv: StateKV): Promise | undefined> { + if (!kv.graphFileList?.accepts(KV.captureReview)) return undefined; + const rows = await kv.list(KV.captureReview, { project: (value, key) => { + if (!value || typeof value !== 'object' || Array.isArray(value) || typeof key !== 'string' || !key || + (value as CaptureReviewHistory).key !== key) throw Error('capture_review_key_unverified'); + return { key, hasResolution: (value as CaptureReviewHistory).sdkResolution !== undefined }; + } }); + return new Set(rows.filter(row => row.hasResolution).map(row => row.key)); +} + +export async function committedInboxMetadata( + kv: StateKV, + history: CaptureReviewHistory | null | undefined, + metadata: CaptureInboxMetadata, +): Promise { + if (history?.sdkResolution === undefined) return false; + const current = await kv.get(KV.captureInbox, metadata.key); + if (!current) return false; + const { payload, ...currentMetadata } = current; + const { preview, reviewPreview, ...expectedMetadata } = metadata; + return isDeepStrictEqual(currentMetadata, expectedMetadata) && committedSdkResolution(history, current); +} diff --git a/src/capture/retry-jobs.ts b/src/capture/retry-jobs.ts index 44699b63a9..0a81617bff 100644 --- a/src/capture/retry-jobs.ts +++ b/src/capture/retry-jobs.ts @@ -1,8 +1,9 @@ import { randomUUID } from 'node:crypto'; import { KV } from '../state/schema.js'; import type { StateKV } from '../state/kv.js'; -import { withKeyedLock } from '../state/keyed-mutex.js'; import type { InboxRecord } from '../functions/capture.js'; +import { withKeyedLock } from '../state/keyed-mutex.js'; +import { listCaptureInboxMetadata } from './inbox-metadata.js'; import { captureEventScope } from './event-record.js'; import type { CaptureReviewHistory, CaptureRetryJob as Job, CaptureRetryJobItem as Item, CaptureRetryJobItemState as ItemState } from '../types.js'; @@ -44,7 +45,7 @@ export function createCaptureRetryJobs(kv: StateKV, retry: (key: string, force: const running=await latest();if(running&&active(running)){ const now=new Date().toISOString();await save({id:input.requestId,aliasOf:running.id,all:input.all===true,...(input.eventId?{eventId:input.eventId}:{}),...(input.key?{key:input.key}:{}),createdAt:now,updatedAt:now});return view(running)!; } - const records=(await kv.list(KV.captureInbox)).filter(r=>r.status==='dead'&&(input.all||r.eventId===input.eventId&&(!input.key||r.key===input.key))); + const records=(await listCaptureInboxMetadata(kv)).filter(r=>r.status==='dead'&&(input.all||r.eventId===input.eventId&&(!input.key||r.key===input.key))); if(records.length>10000)throw Error('CAPTURE_JOB_TOO_LARGE'); const now=new Date().toISOString();const job:Job={id:input.requestId,all:input.all===true,...(input.eventId?{eventId:input.eventId}:{}),...(input.key?{key:input.key}:{}),status:records.length?'running':'completed',stopRequested:false,createdAt:now,updatedAt:now, items:records.sort((a,b)=>a.acceptedAt.localeCompare(b.acceptedAt)||a.key.localeCompare(b.key)).map(r=>({key:r.key,eventId:r.eventId,requestId:randomUUID(),status:'queued'}))}; diff --git a/src/capture/review.ts b/src/capture/review.ts index f54d7a5463..247b266e63 100644 --- a/src/capture/review.ts +++ b/src/capture/review.ts @@ -2,7 +2,8 @@ import type { CaptureReviewHistory } from '../types.js'; import type { InboxRecord } from '../functions/capture.js'; import type { StateKV } from '../state/kv.js'; import { KV } from '../state/schema.js'; -import{validSdkResolution,committedSdkResolution}from'./sdk-resolution-record.js'; +import{validSdkResolution}from'./sdk-resolution-record.js'; +import { listCaptureInboxMetadata, committedInboxMetadata } from './inbox-metadata.js'; export function captureFailureCode(error: string): string { if (error.includes('Session observation limit reached')) return 'SESSION_OBSERVATION_LIMIT'; @@ -54,18 +55,17 @@ export function reviewMetadata(history: CaptureReviewHistory) { export async function captureReviewPage(kv: StateKV, input: {status?:string;eventId?:string;key?:string;cursor?:string;limit?:number;historyOffset?:number}) { const limit=Math.min(Math.max(1,Number(input.limit)||25),50); - const inbox=await kv.list(KV.captureInbox); + const inbox=await listCaptureInboxMetadata(kv); const histories=await kv.list(KV.captureReview); const byKey=new Map(histories.map(h=>[h.key,h])); const rows=new Map(); for (const h of histories) rows.set(h.key,{key:h.key,eventId:h.eventId,sessionId:h.sessionId,project:h.project,hookType:h.hookType, observationId:h.observationId,status:h.status,attempts:h.totalAttempts,acceptedAt:h.acceptedAt,updatedAt:h.updatedAt,review:reviewMetadata(h),preview:'복구 기록 · 원문은 저장된 관측에서 확인'}); for (const rec of inbox) { - const h=byKey.get(rec.key);const d=rec.payload?.data as Record|undefined; - const text=typeof d?.tool_name==='string' ? d.tool_name : rec.hookType; + const h=byKey.get(rec.key); rows.set(rec.key,{key:rec.key,eventId:rec.eventId,sessionId:rec.sessionId,project:rec.project,hookType:rec.hookType, - observationId:rec.observationId,status:committedSdkResolution(h,rec)?'completed':rec.status,attempts:rec.attempts,acceptedAt:rec.acceptedAt,updatedAt:rec.updatedAt, - errorCode:rec.lastError ? captureFailureCode(rec.lastError) : null,preview:text, + observationId:rec.observationId,status:await committedInboxMetadata(kv,h,rec)?'completed':rec.status,attempts:rec.attempts,acceptedAt:rec.acceptedAt,updatedAt:rec.updatedAt, + errorCode:rec.lastError ? captureFailureCode(rec.lastError) : null,preview:rec.reviewPreview, review:h ? reviewMetadata(h) : {status:rec.status,totalAttempts:rec.attempts,manualRetries:0,lastFailureCode:rec.lastError?captureFailureCode(rec.lastError):null,recoveredAt:null,lastRequest:null}}); } let filtered=[...rows.values()].filter(r=>(!input.status||r.status===input.status)&&(!input.eventId||r.eventId===input.eventId)&&(!input.key||r.key===input.key)); @@ -78,7 +78,6 @@ export async function captureReviewPage(kv: StateKV, input: {status?:string;even filtered=filtered.filter(r=>r.acceptedAt>cursor[0]||r.acceptedAt===cursor[0]&&r.key>cursor[1]); } const items=filtered.slice(0,limit);const last=items.at(-1); - for(const item of items){const rec=inbox.find(r=>r.key===item.key);if(rec){const d=rec.payload?.data as Record|undefined;item.preview=(item.preview+': '+JSON.stringify(d?.tool_input??d?.prompt??d?.message??'')).slice(0,500);}} if(input.eventId)for(const item of items){const h=byKey.get(item.key);const offset=Number.isSafeInteger(input.historyOffset)&&input.historyOffset!>=0 ? input.historyOffset! : 0; item.failures=h?.failures.slice(offset,offset+50)||[];item.nextHistoryOffset=h&&h.failures.length>offset+50 ? offset+50 : null;} return {total,items,nextCursor:filtered.length>limit&&last?Buffer.from(JSON.stringify([last.acceptedAt,last.key])).toString('base64url'):null}; diff --git a/src/capture/sdk-delivery-v2.ts b/src/capture/sdk-delivery-v2.ts index 5fc3096aa2..183ed4db36 100644 --- a/src/capture/sdk-delivery-v2.ts +++ b/src/capture/sdk-delivery-v2.ts @@ -1,4 +1,5 @@ import {performance} from 'node:perf_hooks'; +import {createHash} from 'node:crypto'; import {SdkSpoolV2,type SdkSpoolV2Options} from './sdk-spool-v2.js'; export {SdkSpoolV2} from './sdk-spool-v2.js'; export const SDK_CAPTURE_V2_FLAG='--agentmemory-sdk-capture-v2'; @@ -80,6 +81,47 @@ function hasImage(value:unknown):boolean{ } return false; } +// Operator-only. Callers must durably record a one-shot intent before invoking this function. +// A lost response stays held and requires inspection, never automatic re-submission. +export async function restoreSelectedSdkCaptureV2(target:string,sourceId:string,post:V2Post,options:V2Options={}){ + const store=createStore(options); + let body:Record,observationId:string; + try{body=await store.load(target,sourceId);} + catch(error){return {sourceRetained:false,completion:'sdk' as const,durable:false,completed:false,status:'held' as const,code:safeCode(error)};} + const retained={sourceRetained:true,completion:'sdk' as const,durable:false}; + try{ + if(body.captureCompletion!=='sdk-v1'||Object.keys(body).some(key=>!['eventId','captureCompletion','hookType','sessionId','project','cwd','timestamp','data'].includes(key))|| + Buffer.byteLength(JSON.stringify(body))>256*1024||hasImage(body.data))return {...retained,completed:false,status:'held' as const,code:'SDK_SOURCE_FORMAT_UNSUPPORTED'}; + if(!['eventId','hookType','sessionId','project','cwd','timestamp'].every(key=>typeof body[key]==='string'&&(body[key] as string).length>0)|| + !/^[A-Za-z0-9_.:-]{8,128}$/.test(body.eventId as string))return {...retained,completed:false,status:'held' as const,code:'SDK_SOURCE_IDENTITY_INVALID'}; + const timestamp=Date.parse(body.timestamp as string); + if(!Number.isFinite(timestamp)||timestamp=Date.UTC(2100,0,1))return {...retained,completed:false,status:'held' as const,code:'SDK_SOURCE_IDENTITY_INVALID'}; + const key=createHash('sha256').update(body.project+'\0'+body.sessionId+'\0'+body.eventId).digest('hex'); + observationId='obs_'+timestamp.toString(36)+'_'+key.slice(0,12); + const existing=await store.retain(target,body.eventId as string,body); + if(existing.sourceId!==sourceId||existing.conflict)return {...retained,completed:false,status:'held' as const,code:'SOURCE_CONFLICT'}; + if(existing.completed)return {...retained,completed:true,status:'duplicate' as const,sdkReplyConfirmed:true}; + await store.markSending(target,sourceId,body); + }catch(error){return {...retained,completed:false,status:'held' as const,code:safeCode(error)};} + let response:V2PostResult; + try{response=await post(body);} + catch{ + try{await store.hold(target,sourceId,'SDK_RESTORE_OUTCOME_UNCERTAIN');}catch{} + return {...retained,completed:false,status:'held' as const,code:'SDK_RESTORE_OUTCOME_UNCERTAIN'}; + } + const value=response.body&&typeof response.body==='object'?response.body as Record:{}; + const confirmed=(response.status===200||response.status===201)&&value.eventId===body.eventId&&value.observationId===observationId&& + value.sourceRestore==='sdk-v1'&&value.completion==='sdk'&&value.completed===true&&value.durable===false&& + (value.status==='restored'||value.status==='duplicate'); + if(!confirmed){ + try{await store.hold(target,sourceId,'SDK_RESTORE_OUTCOME_UNCERTAIN');}catch{} + return {...retained,completed:false,status:'held' as const,code:'SDK_RESTORE_REPLY_UNVERIFIED'}; + } + try{await store.acknowledge(target,sourceId);} + catch{return {...retained,completed:false,status:'held' as const,code:'SDK_ACK_STATE_UNCONFIRMED',sdkReplyConfirmed:true};} + return {...retained,completed:true,status:value.status as 'restored'|'duplicate',sdkReplyConfirmed:true}; +} + export async function restoreSdkCaptureV2(target:string,sourceId:string,_post:V2Post,options:V2Options={}){ try{ const body=await createStore(options).load(target,sourceId); diff --git a/src/capture/sdk-spool-v2.ts b/src/capture/sdk-spool-v2.ts index e3882c5d4e..18581b91a5 100644 --- a/src/capture/sdk-spool-v2.ts +++ b/src/capture/sdk-spool-v2.ts @@ -299,13 +299,17 @@ export class SdkSpoolV2 { return result.map(({ sourceId, state, attempts, nextAttemptAt }) => ({ sourceId, state, attempts, nextAttemptAt })); }); } - async markSending(target: string, sourceId: string): Promise { + async markSending(target: string, sourceId: string, expectedHeldSource?: Record): Promise { return this.locked(() => { const source = this.source(target, sourceId); if (source.manifest.conflict || source.manifest.completed) fail('SOURCE_HELD'); const ref = this.readRef(target, sourceId); - if (ref.state !== 'pending') fail('SOURCE_HELD'); - if (ref.nextAttemptAt > Date.now()) fail('SOURCE_BACKOFF'); + if (expectedHeldSource) { + if (ref.state !== 'held' || ref.owner || !isDeepStrictEqual(source.body, expectedHeldSource)) fail('SOURCE_HELD'); + } else { + if (ref.state !== 'pending') fail('SOURCE_HELD'); + if (ref.nextAttemptAt > Date.now()) fail('SOURCE_BACKOFF'); + } const owner = ownerIdentity(); if (!owner) fail('STORE_BUSY'); ref.state = 'sending'; ref.owner = owner; this.writeRef(ref); this.phase('send_intent_fsynced'); @@ -317,7 +321,7 @@ export class SdkSpoolV2 { if (source.manifest.conflict) fail('SOURCE_CONFLICT'); if (!source.manifest.completed) { const ref = this.readRef(target, sourceId); - if (ref.state !== 'sending') fail('SOURCE_HELD'); + if (ref.state !== 'sending' || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail('SOURCE_HELD'); source.manifest.completed = true; this.atomicJson(join(this.originals, sourceId, 'manifest.json'), source.manifest, 'original', 'ack_before_publish'); this.phase('ack_fsynced'); @@ -328,13 +332,13 @@ export class SdkSpoolV2 { async retry(target: string, sourceId: string, _reason: string): Promise { return this.locked(() => { const ref = this.readRef(target, sourceId); - if (ref.state !== 'sending' || !ref.owner || !alive(ref.owner)) fail('SOURCE_HELD'); + if (ref.state !== 'sending' || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail('SOURCE_HELD'); ref.attempts = Math.min(1_000_000, ref.attempts + 1); ref.nextAttemptAt = Date.now() + Math.min(300_000, 1000 * 2 ** Math.min(9, ref.attempts - 1)); ref.state = 'pending'; ref.reason = 'RETRY'; delete ref.owner; this.writeRef(ref); }); } async hold(target: string, sourceId: string, _reason: string): Promise { - return this.locked(() => { const ref = this.readRef(target, sourceId); ref.state = 'held'; ref.reason = 'HELD'; delete ref.owner; this.writeRef(ref); }); + return this.locked(() => { const ref = this.readRef(target, sourceId); if (ref.state !== 'sending' || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail('SOURCE_HELD'); ref.state = 'held'; ref.reason = 'HELD'; delete ref.owner; this.writeRef(ref); }); } async usage(): Promise<{ originalBytes: number; queueBytes: number }> { return this.locked(() => this.rawUsage()); } } diff --git a/src/functions/capture.ts b/src/functions/capture.ts index 06ac8b5339..1d459e7bf9 100644 --- a/src/functions/capture.ts +++ b/src/functions/capture.ts @@ -1,3 +1,4 @@ +import { listCaptureInboxMetadata, listLocalCaptureResolutionKeys, committedInboxMetadata, type CaptureInboxMetadata } from '../capture/inbox-metadata.js'; import {inspectUncertainCapture,validUncertainInspection} from "../capture/uncertain-inspection.js"; import { committedSdkResolution } from '../capture/sdk-resolution-record.js'; import {recordAudit} from "./audit.js"; @@ -298,7 +299,7 @@ export function registerCaptureFunctions( else if (activeInboxKeys && pendingSince === null) pendingSince = Date.now(); } - function refreshInbox(records: InboxRecord[]): void { + function refreshInbox(records: Array): void { inboxSize = records.length; activeInboxKeys = new Set(records.filter((rec) => rec && rec.status !== "dead" && rec.storageCompletion !== "sdk").map((rec) => rec.key)); updatePendingSince(); @@ -311,7 +312,7 @@ export function registerCaptureFunctions( } async function currentInboxSize(): Promise { - if (inboxSize === null) refreshInbox(await kv.list(KV.captureInbox)); + if (inboxSize === null) refreshInbox(await listCaptureInboxMetadata(kv)); return inboxSize!; } @@ -412,10 +413,12 @@ export function registerCaptureFunctions( return { status: "accepted", state: "retrying", eventId: rec.eventId, observationId: rec.observationId, attempts: rec.attempts, nextAttemptAt, error: message }; } - async function sdkRecordCompleted(rec:InboxRecord):Promise{ + async function sdkRecordCompleted(rec:InboxRecord | CaptureInboxMetadata,resolutionKeys?:Set):Promise{ if(rec.storageCompletion!=='sdk'||rec.sdkRestoreState==='pending'||rec.sdkResolutionState==='pending')return false; + const requiresResolution=resolutionKeys?.has(rec.key)||rec.sdkResolutionId!==undefined||rec.sdkResolutionState!==undefined; + if(resolutionKeys&&!requiresResolution)return true; const history=await kv.get(KV.captureReview,rec.key); - if(rec.sdkResolutionId!==undefined||rec.sdkResolutionState!==undefined||history?.sdkResolution!==undefined)return committedSdkResolution(history,rec); + if(requiresResolution||history?.sdkResolution!==undefined)return 'payload' in rec?committedSdkResolution(history,rec):committedInboxMetadata(kv,history,rec); return true; } @@ -607,7 +610,7 @@ export function registerCaptureFunctions( async function runSweep(): Promise<{ processed: number; recovered: number; deadLettered: number }> { if (stopped || sdkCompletion) return { processed: 0, recovered: 0, deadLettered: 0 }; - const records = await kv.list(KV.captureInbox); + const records = await listCaptureInboxMetadata(kv); refreshInbox(records); let processed = 0; let recovered = 0; @@ -728,11 +731,12 @@ export function registerCaptureFunctions( await automaticRecovery.initialize().catch(()=>{}); let inbox: CaptureStatus["inbox"] = null; if (options.scanInbox !== false) try { - const records = (await kv.list(KV.captureInbox)).filter(Boolean); + const records = (await listCaptureInboxMetadata(kv)).filter(Boolean); refreshInbox(records); let sdkCompleted=0; + const resolutionKeys=sdkCompletion?await listLocalCaptureResolutionKeys(kv):undefined; if(sdkCompletion)for(let at=0;atsdkRecordCompleted(r)))).filter(Boolean).length; + sdkCompleted+=(await Promise.all(records.slice(at,at+4).map(r=>sdkRecordCompleted(r,resolutionKeys)))).filter(Boolean).length; } const live = records.filter((r) => r.status !== "dead" && r.storageCompletion !== "sdk"); const next = live @@ -791,7 +795,7 @@ export function registerCaptureFunctions( sdk.registerFunction("mem::capture-retry", async (input: { eventId?: string; key?: string; all?: boolean; requestId?: string } = {}) => { if(input.requestId && (!input.eventId || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(input.requestId))) throw new Error("INVALID_RETRY_REQUEST"); - const records = (await kv.list(KV.captureInbox)).filter(Boolean); + const records = (await listCaptureInboxMetadata(kv)).filter(Boolean); refreshInbox(records); if(input.eventId && input.requestId && !records.some(r=>input.key?r.key===input.key:r.eventId===input.eventId)){ const h=(await kv.list(KV.captureReview)).find(h=>(input.key?h.key===input.key:h.eventId===input.eventId)&&h.eventId===input.eventId&&h.requests[input.requestId!]); @@ -816,15 +820,12 @@ export function registerCaptureFunctions( sdk.registerFunction("mem::capture-list", async (input: { status?: InboxState | "completed"; limit?: number; review?: boolean; eventId?: string; key?: string; cursor?: string; historyOffset?: number } = {}) => { if(input.review) return captureReviewPage(kv,input); const limit = Math.min(Math.max(1, Number(input.limit) || 50), 500); - const records = (await kv.list(KV.captureInbox)) + const records = (await listCaptureInboxMetadata(kv)) .filter((r) => r && (!input.status || r.status === input.status)) .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)); return { total: records.length, - items: records.slice(0, limit).map(({ payload, ...rest }) => ({ - ...rest, - preview: previewPayload(payload), - })), + items: records.slice(0, limit).map(({ reviewPreview, ...rest }) => rest), }; }); @@ -885,14 +886,3 @@ function spoolPayload(body: Record): HookPayload | null { if (!hookType || !sessionId || !project || !cwd || !timestamp) return null; return { hookType: hookType as HookPayload["hookType"], sessionId, project, cwd, timestamp, data: body["data"] }; } - -function previewPayload(payload: HookPayload | undefined): string { - if (!payload) return ""; - const d = payload.data && typeof payload.data === "object" ? (payload.data as Record) : {}; - const label = typeof d["tool_name"] === "string" ? d["tool_name"] : payload.hookType; - let text = ""; - try { - text = JSON.stringify(d["tool_input"] ?? d["prompt"] ?? payload.data ?? ""); - } catch {} - return `${label}: ${text}`.slice(0, 160); -} diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 7a75aabfa0..5fcc227078 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/mcp/in-memory-kv.ts b/src/mcp/in-memory-kv.ts index e234896477..122cd8728b 100644 --- a/src/mcp/in-memory-kv.ts +++ b/src/mcp/in-memory-kv.ts @@ -37,9 +37,10 @@ export class InMemoryKV { this.store.get(scope)?.delete(key); } - async list(scope: string): Promise { + async list(scope: string, options?: { project?: (value: unknown, key?: string) => T }): Promise { const entries = this.store.get(scope); - return entries ? (Array.from(entries.values()) as T[]) : []; + const values = entries ? Array.from(entries.values()) : []; + return options?.project ? Array.from(entries ?? [], ([key, value]) => options.project!(value, key)) : values as T[]; } persist(): boolean { diff --git a/src/ops/graph-file-list.d.mts b/src/ops/graph-file-list.d.mts index f781d8497f..fe9e8a9c31 100644 --- a/src/ops/graph-file-list.d.mts +++ b/src/ops/graph-file-list.d.mts @@ -2,5 +2,5 @@ export function createGraphFileList(options:{storePath:string}):{ accepts(scope:string):boolean; record(scope:string,key:string,value:unknown):void; invalidate(scope:string):void; - list(scope:string):Promise; + list(scope:string,options?:{project?:(value:unknown,key?:string)=>T}):Promise; }; diff --git a/src/ops/graph-file-list.mjs b/src/ops/graph-file-list.mjs index d38e2aefc5..24693bad45 100644 --- a/src/ops/graph-file-list.mjs +++ b/src/ops/graph-file-list.mjs @@ -4,28 +4,43 @@ import {readNamespaceEntries} from './namespace-reader.mjs'; export function createGraphFileList({storePath}) { const pending=new Map(),uncertain=new Set(); - const accepts=scope=>/^mem:graph:(?:nodes|edges)(?::generation:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?$/.test(scope); + // Capture originals and review history can exceed one SDK frame. + const captureScope=scope=>scope==='mem:capture:inbox'||scope==='mem:capture:review'; + const accepts=scope=>captureScope(scope)||/^mem:graph:(?:nodes|edges)(?::generation:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?$/.test(scope); function record(scope,key,value) { if(!accepts(scope)||value===undefined)return; if(!pending.has(scope))pending.set(scope,new Map()); pending.get(scope).set(key,structuredClone(value)); } function invalidate(scope){if(accepts(scope))uncertain.add(scope);} - async function list(scope) { + async function list(scope,{project}={}) { if(!accepts(scope))throw Error('invalid_graph_scope'); if(uncertain.has(scope))throw Error('graph_mutation_uncertain'); - const rows=new Map(); - // shortcut: one full local scan per call; replace with native graph queries when iii provides them. + const rows=new Map(),matched=new Map(); + // Projection discards each disk row's payload before retaining the result. + // Pending SDK acknowledgements retain full values until a matching disk checkpoint. for(let attempt=0;;attempt++) { - rows.clear(); - try {await readNamespaceEntries(join(storePath,encodeURIComponent(scope)+'.bin'),{onEntry:(key,value)=>rows.set(key,value)});break;} + rows.clear();matched.clear(); + try { + await readNamespaceEntries(join(storePath,encodeURIComponent(scope)+'.bin'),{onEntry:(key,value)=>{ + const acknowledged=pending.get(scope)?.get(key); + if(acknowledged!==undefined&&isDeepStrictEqual(value,acknowledged))matched.set(key,acknowledged); + rows.set(key,project?project(value,key):value); + }}); + break; + } catch(error){if(error.code==='ENOENT')break;if(error.code==='state_namespace_changed'&&attempt<1)continue;throw error;} } if(uncertain.has(scope))throw Error('graph_mutation_uncertain'); const overlay=pending.get(scope); for(const [key,value] of overlay||[]) { - if(value===null){if(!rows.has(key))overlay.delete(key);rows.delete(key);} - else {if(isDeepStrictEqual(rows.get(key),value))overlay.delete(key);rows.set(key,value);} + // Absence cannot identify the deletion's checkpoint generation. Capture + // tombstones stay until a newer acknowledgement for that key or restart. + if(value===null){if(!captureScope(scope)&&!rows.has(key))overlay.delete(key);rows.delete(key);} + else { + if(matched.get(key)===value)overlay.delete(key); + rows.set(key,project?project(structuredClone(value),key):captureScope(scope)?structuredClone(value):value); + } } if(overlay&&!overlay.size)pending.delete(scope); return [...rows.values()]; diff --git a/src/state/kv.ts b/src/state/kv.ts index f045e32556..68fed5b307 100644 --- a/src/state/kv.ts +++ b/src/state/kv.ts @@ -370,11 +370,14 @@ export class StateKV { }) } - async list(scope: string, options?: { observationConsistency?: 'opened-generation' }): Promise { + async list(scope: string, options?: { observationConsistency?: 'opened-generation'; project?: (value: unknown, key?: string) => T }): Promise { scope = await resolveGraphScope(this, scope) await ensureGraphConsistency(this, scope) - if (this.graphFileList?.accepts(scope)) return this.graphFileList.list(scope) - if (scope.startsWith('mem:obs:') && this.observationReader) return this.observationReader.list(scope, { consistency: options?.observationConsistency }) + if (this.graphFileList?.accepts(scope)) return this.graphFileList.list(scope, options) + if (scope.startsWith('mem:obs:') && this.observationReader) { + const rows = await this.observationReader.list(scope, { consistency: options?.observationConsistency }) + return options?.project ? rows.map(value => options.project!(value)) : rows + } const read = () => this.sdk.trigger<{ scope: string }, T[]>({ function_id: 'state::list', payload: { scope }, @@ -392,8 +395,8 @@ export class StateKV { return rows }) : await read() - if (this.backend !== 'redis' || !Array.isArray(values)) return values - return orderLikeInsertion(values) + const ordered = this.backend === 'redis' && Array.isArray(values) ? orderLikeInsertion(values) : values + return options?.project && Array.isArray(ordered) ? ordered.map(value => options.project!(value)) : ordered } async listGroups(): Promise { diff --git a/src/types.ts b/src/types.ts index 62d007d1c4..e9cdb85852 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index 312a208f37..cdcd33f2d9 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.59"; +export const VERSION = "0.9.32-daniel.60"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/capture-auto-recovery.test.ts b/test/capture-auto-recovery.test.ts index d1571b621b..349d0ebe2a 100644 --- a/test/capture-auto-recovery.test.ts +++ b/test/capture-auto-recovery.test.ts @@ -17,7 +17,7 @@ async function setup(){ const fingerprint=createHash('sha256').update(obs.title+' '+obs.narrative).digest('hex'); state.set(KV.captureInbox+'|'+key,inbox);state.set(KV.captureReview+'|'+key,history);state.set(KV.observations(sessionId)+'|'+observationId,obs);state.set('mem:embedding-committed:v1|'+observationId,{kind:'observation',id:observationId,sessionId,fingerprint}); const durability={mutate:(_s:string,_k:string,fn:()=>unknown)=>fn(),waitForKeys:async(_kv:any,keys:any[],opts:any)=>{calls++;if(onProof&&keys.some(x=>x.scope===KV.observations(sessionId))){const fn=onProof;onProof=undefined;await fn();}if(failProof&&keys.some(x=>x.scope===captureEventScope(key))&&state.has(captureEventScope(key)+'|'+key))throw Error('state_durability_timeout');if(opts?.expectedValues)for(let i=0;itrue,admitted:()=>admitted,indexReady:()=>true,now:()=>clock}; return {kv,state,key,lease,evidence,storePath:d,sdk,durability,sessionId,observationId,eventId,obs,history,options,advance:()=>clock+=3600000,failProof:(v:boolean)=>failProof=v,onProof:(fn:()=>Promise)=>onProof=fn,admit:(v:boolean)=>admitted=v,calls:()=>calls}; } diff --git a/test/capture-inbox-file-list.test.ts b/test/capture-inbox-file-list.test.ts new file mode 100644 index 0000000000..081078dddd --- /dev/null +++ b/test/capture-inbox-file-list.test.ts @@ -0,0 +1,354 @@ +import { afterEach, expect, it, vi } from 'vitest'; +import { createHash } from 'node:crypto'; +import { createReadStream } from 'node:fs'; +import { mkdtemp, open, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { dirname, join } from 'node:path'; +import { StateKV, applyUpdateOps } from '../src/state/kv.js'; +import { KV } from '../src/state/schema.js'; +import { registerCaptureFunctions } from '../src/functions/capture.js'; +import { listCaptureInboxMetadata, projectCaptureInbox } from '../src/capture/inbox-metadata.js'; +import { mockSdk } from './helpers/mocks.js'; +import { capturePayloadDigest } from '../src/capture/receipt-digest.js'; +import { captureFailureHistoryDigest } from '../src/capture/sdk-resolution-record.js'; +import { createStateDurabilityFence } from '../src/ops/state-durability.mjs'; + +vi.mock('../src/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } })); +const directories: string[] = []; +const controllers: Array> = []; +afterEach(async () => { + for (const controller of controllers.splice(0)) controller.stop(); + vi.unstubAllEnvs(); + await Promise.all(directories.splice(0).map(path => rm(path, { recursive: true, force: true }))); +}); +async function fixture() { + const dir = await mkdtemp(join(tmpdir(), 'am-capture-list-')); + directories.push(dir); + vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH', dir); + return join(dir, encodeURIComponent(KV.captureInbox) + '.bin'); +} +function stateSdk(rows: Record = {}) { + const sdk = mockSdk(); + const store = new Map>([[KV.captureInbox, new Map(Object.entries(rows))]]); + const list = vi.fn(async ({ scope }: { scope: string }) => { + if (scope === KV.captureInbox) throw Error('SDK_LIST_EXCEEDS_64_MIB'); + return [...(store.get(scope)?.values() ?? [])]; + }); + sdk.registerFunction('state::list', list as never); + sdk.registerFunction('state::get', async (input: any) => store.get(input.scope)?.get(input.key) ?? null); + sdk.registerFunction('state::set', async (input: any) => { + if (!store.has(input.scope)) store.set(input.scope, new Map()); + store.get(input.scope)!.set(input.key, input.value); + return input.value; + }); + sdk.registerFunction('state::update', async (input: any) => { + const before = store.get(input.scope)?.get(input.key); + const after = applyUpdateOps(before, input.ops); + store.get(input.scope)?.set(input.key, after); + return { old_value: before, new_value: after, errors: [] }; + }); + sdk.registerFunction('state::delete', async (input: any) => { + const before = store.get(input.scope)?.get(input.key); + store.get(input.scope)?.delete(input.key); + return before ?? null; + }); + return { sdk, list, store }; +} +async function digest(path: string) { + const hash = createHash('sha256'); + for await (const block of createReadStream(path)) hash.update(block); + return hash.digest('hex'); +} + +it('preserves capture admission and status with an intact inbox beyond a 64 MiB SDK list', async () => { + const path = await fixture(); + const { sdk, list, store } = stateSdk(); + const largeText = 'x'.repeat(512 * 1024); + const handle = await open(path, 'w'); + let sdkBytes = 2; + try { + await handle.write('{'); + for (let i = 0; i < 128; i++) { + const key = 'retained-' + i; + const row = { + key, eventId: key, sessionId: 'old-session', project: 'fixture', + status: 'dead', attempts: 1, updatedAt: '2026-11-01T00:00:00.000Z', + payload: { data: { synthetic: largeText } }, + }; + store.get(KV.captureInbox)!.set(key, row); + const value = JSON.stringify(row); + sdkBytes += Buffer.byteLength(value) + Number(i > 0); + await handle.write((i ? ',' : '') + JSON.stringify(key) + ':' + value); + } + await handle.write('}'); + await handle.write(Buffer.from([0, 0, 0, 0, 255, 255, 255, 255])); + } finally { + await handle.close(); + } + expect(sdkBytes).toBeGreaterThan(64 * 1024 * 1024); + const original = await digest(path); + const kv = new StateKV(sdk as never); + const localList = vi.spyOn(kv.graphFileList!, 'list'); + sdk.registerFunction('mem::observe', async (payload: any) => ({ observationId: payload.observationId })); + sdk.registerFunction('fixture::health', async () => ({ connected: true })); + const controller = registerCaptureFunctions(sdk as never, kv); + controllers.push(controller); + const result = await sdk.trigger('mem::capture', { + eventId: 'evc_000000000099', + payload: { hookType: 'post_tool_use', sessionId: 'new-session', project: 'fixture', + cwd: '/synthetic', timestamp: '2026-11-07T00:00:00.000Z', data: { tool_name: 'Bash', tool_output: 'synthetic' } }, + }); + expect(result).toMatchObject({ status: 'accepted', state: 'sdk_completed' }); + const report = await controller.status(); + expect(report.inbox).toMatchObject({ dead: 128, pending: 0, sdkCompleted: 1 }); + expect(await sdk.trigger('fixture::health', {})).toEqual({ connected: true }); + expect(list.mock.calls.some(([input]) => input.scope === KV.captureInbox)).toBe(false); + expect(localList.mock.calls.every(([, options]) => typeof options?.project === 'function')).toBe(true); + expect(await digest(path)).toBe(original); +}, 30_000); + +it('overlays acknowledged inbox set/update/delete before disk catches up', async () => { + const path = await fixture(); + const rows = { original: { key: 'original', attempts: 0 }, removed: { key: 'removed' } }; + await writeFile(path, JSON.stringify(rows)); + const { sdk, list } = stateSdk(rows); + const kv = new StateKV(sdk as never); + await kv.update(KV.captureInbox, 'original', [{ type: 'set', path: 'attempts', value: 2 }]); + await Promise.all([ + kv.set(KV.captureInbox, 'first', { key: 'first' }), + kv.set(KV.captureInbox, 'second', { key: 'second' }), + ]); + await kv.delete(KV.captureInbox, 'removed'); + const expected = [{ key: 'original', attempts: 2 }, { key: 'first' }, { key: 'second' }]; + expect(await kv.list(KV.captureInbox)).toEqual(expected); + await writeFile(path, JSON.stringify(Object.fromEntries(expected.map(row => [row.key, row])))); + expect(await kv.list(KV.captureInbox)).toEqual(expected); + expect(list).not.toHaveBeenCalled(); +}); + +it('keeps an in-flight SDK mutation out of the overlay until acknowledged', async () => { + await fixture(); + const { sdk } = stateSdk(); + let acknowledge!: (value: unknown) => void; + let entered!: () => void; + const started = new Promise(resolve => { entered = resolve; }); + sdk.registerFunction('state::set', async () => { + entered(); + return new Promise(resolve => { acknowledge = resolve; }); + }); + const kv = new StateKV(sdk as never); + const write = kv.set(KV.captureInbox, 'new', { key: 'new' }); + await started; + expect(await kv.list(KV.captureInbox)).toEqual([]); + acknowledge({ key: 'new' }); + await write; + expect(await kv.list(KV.captureInbox)).toEqual([{ key: 'new' }]); +}); + +it('does not let a capture retry mutate the acknowledged overlay before another SDK write', async () => { + await fixture(); + const { sdk } = stateSdk(); + const kv = new StateKV(sdk as never); + await kv.set(KV.captureInbox, 'new', { key: 'new', attempts: 1, payload: { data: { text: 'original' } } }); + const first = await kv.list(KV.captureInbox); + first[0].attempts++; + first[0].payload.data.text = 'locally changed'; + expect(await kv.list(KV.captureInbox)).toEqual([ + { key: 'new', attempts: 1, payload: { data: { text: 'original' } } }, + ]); +}); + +it('retains an inbox deletion ACK when an absent checkpoint cannot prove the deletion generation', async () => { + const path = await fixture(); + await writeFile(path, '{}'); + const { sdk } = stateSdk(); + const kv = new StateKV(sdk as never); + const old = { key: 'old', attempts: 1 }; + await kv.set(KV.captureInbox, old.key, old); + await kv.delete(KV.captureInbox, old.key); + expect(await kv.list(KV.captureInbox)).toEqual([]); + // An absent key alone does not identify which SDK mutation was checkpointed. + await writeFile(path, JSON.stringify({ old })); + expect(await kv.list(KV.captureInbox)).toEqual([]); + await kv.set(KV.captureInbox, old.key, { ...old, attempts: 2 }); + expect(await kv.list(KV.captureInbox)).toEqual([{ key: 'old', attempts: 2 }]); +}); + +it('projects each inbox entry and retires the ACK overlay only after the matching checkpoint', async () => { + const path = await fixture(); + await writeFile(path, '{"old":{"key":"old","attempts":0,"payload":{"data":"large original"}}}'); + const { sdk } = stateSdk(); + const kv = new StateKV(sdk as never); + const project = (value: any) => ({ key: value.key, attempts: value.attempts }); + await kv.set(KV.captureInbox, 'old', { key: 'old', attempts: 1, payload: { data: 'uncheckpointed' } }); + expect(await kv.list(KV.captureInbox, { project })).toEqual([{ key: 'old', attempts: 1 }]); + expect(await kv.list(KV.captureInbox)).toEqual([ + { key: 'old', attempts: 1, payload: { data: 'uncheckpointed' } }, + ]); + await writeFile(path, '{"old":{"key":"old","attempts":1,"payload":{"data":"uncheckpointed"}}}'); + await kv.list(KV.captureInbox, { project }); + await writeFile(path, '{"old":{"key":"old","attempts":2,"payload":{"data":"checkpoint advanced"}}}'); + expect(await kv.list(KV.captureInbox, { project })).toEqual([{ key: 'old', attempts: 2 }]); +}); + +it('retains the exact bounded list and review previews without payloads', async () => { + const row = { key: 'preview', hookType: 'user_prompt_submit', + payload: { hookType: 'post_tool_use', data: { tool_name: 'Bash', tool_input: 'x'.repeat(800) } } }; + const metadata = projectCaptureInbox(row); + expect(metadata).not.toHaveProperty('payload'); + expect(metadata.preview).toBe(('Bash: ' + JSON.stringify(row.payload.data.tool_input)).slice(0, 160)); + expect(metadata.reviewPreview).toBe(('Bash: ' + JSON.stringify(row.payload.data.tool_input)).slice(0, 500)); + const message = projectCaptureInbox({ key: 'message', hookType: 'stop', payload: { hookType: 'stop', data: { message: 'done' } } }); + expect(message.preview).toBe('stop: {"message":"done"}'); + expect(message.reviewPreview).toBe('stop: "done"'); +}); + +it('projects a recent ACK independently of callers and projector mutation', async () => { + await fixture(); + const { sdk } = stateSdk(); + const kv = new StateKV(sdk as never); + await kv.set(KV.captureInbox, 'new', { key: 'new', attempts: 1, payload: { data: 'original' } }); + const rows = await listCaptureInboxMetadata(kv); + rows[0].attempts = 9; + await kv.list(KV.captureInbox, { project: (row: any) => { row.payload.data = 'changed'; return row.key; } }); + expect(await kv.list(KV.captureInbox)).toEqual([{ key: 'new', attempts: 1, payload: { data: 'original' } }]); +}); + +it('refuses corrupt or uncertain inbox state without an SDK list fallback', async () => { + const path = await fixture(); + const { sdk, list } = stateSdk(); + const kv = new StateKV(sdk as never); + await writeFile(path, '{"old":broken}'); + await expect(kv.list(KV.captureInbox)).rejects.toThrow(/state_namespace/); + await writeFile(path, '{"old":{"key":"old"}}'); + sdk.registerFunction('state::set', async () => { throw Error('SDK outcome unknown'); }); + await expect(kv.set(KV.captureInbox, 'new', { key: 'new' })).rejects.toThrow('SDK outcome unknown'); + await expect(kv.list(KV.captureInbox)).rejects.toThrow('graph_mutation_uncertain'); + expect(list).not.toHaveBeenCalled(); + expect(await readFile(path, 'utf8')).toBe('{"old":{"key":"old"}}'); +}); + +it.each(['redis', 'no-local-path'] as const)('preserves SDK fallback for %s', async mode => { + const { sdk, list } = stateSdk(); + if (mode === 'redis') await fixture(); + else vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH', ''); + list.mockImplementation(async () => [{ key: 'legacy' }]); + const kv = new StateKV(sdk as never, mode === 'redis' ? { backend: 'redis' } : {}); + expect(await kv.list(KV.captureInbox)).toEqual([{ key: 'legacy' }]); + expect(await kv.list(KV.captureInbox, { project: (row: any) => row.key })).toEqual(['legacy']); + expect(list).toHaveBeenCalledWith({ scope: KV.captureInbox }); +}); + +it('keeps unrelated capture namespaces on their SDK path', async () => { + await fixture(); + const { sdk, list } = stateSdk(); + const kv = new StateKV(sdk as never); + for (const scope of [KV.captureReview + ':other', KV.captureInbox + ':other', 'mem:capture:events:ab']) { + expect(await kv.list(scope)).toEqual([]); + expect(list).toHaveBeenCalledWith({ scope }); + } +}); + +function completedRow(key: string) { + return { key, eventId: key, sessionId: 'synthetic-session', project: 'synthetic', hookType: 'post_tool_use', + observationId: 'obs-' + key, status: 'pending', storageCompletion: 'sdk', attempts: 1, + acceptedAt: '2026-11-01T00:00:00.000Z', updatedAt: '2026-11-01T00:00:00.000Z', + payload: { hookType: 'post_tool_use', sessionId: 'synthetic-session', project: 'synthetic', + cwd: '/synthetic', timestamp: '2026-11-01T00:00:00.000Z', data: { synthetic: 'original' } } }; +} + +it('counts 5074 ordinary SDK completions with one keyed local review projection and no per-row history GET', async () => { + const path = await fixture(); + const rows = Object.fromEntries(Array.from({ length: 5074 }, (_, i) => { const row = completedRow('sdk-' + i); return [row.key, row]; })); + await writeFile(path, JSON.stringify(rows)); + const { sdk, list } = stateSdk(rows); + const kv = new StateKV(sdk as never); + const get = vi.spyOn(kv, 'get'); + const localList = vi.spyOn(kv.graphFileList!, 'list'); + const controller = registerCaptureFunctions(sdk as never, kv);controllers.push(controller); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 5074, pending: 0 }); + expect(get.mock.calls.filter(([scope]) => scope === KV.captureReview)).toHaveLength(0); + expect(localList.mock.calls.filter(([scope]) => scope === KV.captureReview)).toHaveLength(1); + expect(list.mock.calls.some(([input]) => input.scope === KV.captureReview)).toBe(false); +}); + +it('passes actual review storage keys through disk and acknowledged projections and retains deletion tombstones', async () => { + const path = await fixture(); + const reviewPath = join(dirname(path), encodeURIComponent(KV.captureReview) + '.bin'); + await writeFile(reviewPath, '{"disk-key":{"key":"value-alias"}}'); + const { sdk, list } = stateSdk();const kv = new StateKV(sdk as never); + const project = (value: any, key?: string) => ({ key, embeddedKey: value.key }); + expect(await kv.list(KV.captureReview, { project })).toEqual([{ key: 'disk-key', embeddedKey: 'value-alias' }]); + await kv.set(KV.captureReview, 'ack-key', { key: 'ack-alias' }); + expect(await kv.list(KV.captureReview, { project })).toContainEqual({ key: 'ack-key', embeddedKey: 'ack-alias' }); + await kv.delete(KV.captureReview, 'ack-key'); + await writeFile(reviewPath, '{}');expect(await kv.list(KV.captureReview)).toEqual([]); + await writeFile(reviewPath, '{"ack-key":{"key":"ack-alias"}}'); + expect(await kv.list(KV.captureReview)).toEqual([]); + expect(list.mock.calls.some(([input]) => input.scope === KV.captureReview)).toBe(false); +}); + +it.each([null, [], 'malformed', {}, { key: 'wrong-key' }].map(value => [value]))('does not count SDK completion from malformed or miskeyed local history %j', async history => { + const path = await fixture();const row = completedRow('selected'); + await writeFile(path, JSON.stringify({ selected: row })); + await writeFile(join(dirname(path), encodeURIComponent(KV.captureReview) + '.bin'), JSON.stringify({ selected: history })); + const { sdk } = stateSdk({ selected: row });const kv = new StateKV(sdk as never); + const controller = registerCaptureFunctions(sdk as never, kv);controllers.push(controller); + expect((await controller.status()).inbox).toBeNull(); +}); + +it('rechecks full canonical resolution and original payload only for locally marked history', async () => { + const path = await fixture();const requestId = '00000000-0000-4000-8000-000000000001'; + const row = { ...completedRow('resolved'), sdkResolutionId: requestId, sdkResolutionState: 'committed' }; + const history: any = { key: row.key, eventId: row.eventId, sessionId: row.sessionId, project: row.project, + hookType: row.hookType, observationId: row.observationId, status: 'completed', totalAttempts: 1, + cycleAttempts: 1, manualRetries: 0, failures: [], requests: {}, acceptedAt: row.acceptedAt, updatedAt: row.updatedAt }; + history.sdkResolution = { version: 1, completion: 'sdk', phase: 'committed', requestId, + sourceDigest: capturePayloadDigest(row.payload), initialProjection: 'a'.repeat(64), + priorFailureDigest: captureFailureHistoryDigest(history), priorInboxState: 'dead', + startedAt: row.acceptedAt, completedAt: row.updatedAt, verifiedProjection: 'b'.repeat(64) }; + await writeFile(path, JSON.stringify({ resolved: row })); + await writeFile(join(dirname(path), encodeURIComponent(KV.captureReview) + '.bin'), JSON.stringify({ resolved: history })); + const { sdk, store } = stateSdk({ resolved: row });store.set(KV.captureReview, new Map([[row.key, history]])); + const kv = new StateKV(sdk as never);const get = vi.spyOn(kv, 'get'); + const controller = registerCaptureFunctions(sdk as never, kv);controllers.push(controller); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 1 }); + expect(get.mock.calls.filter(([scope]) => scope === KV.captureReview)).toHaveLength(1); + expect(get.mock.calls.filter(([scope]) => scope === KV.captureInbox)).toHaveLength(1); + store.get(KV.captureInbox)!.set(row.key, { ...row, payload: { ...row.payload, data: { synthetic: 'changed' } } }); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 0 }); +}); + +it('does not turn a projected resolution that disappears from the SDK into an ordinary completion', async () => { + const path = await fixture();const row = completedRow('selected'); + await writeFile(path, JSON.stringify({ selected: row })); + await writeFile(join(dirname(path), encodeURIComponent(KV.captureReview) + '.bin'), '{"selected":{"key":"selected","sdkResolution":null}}'); + const { sdk } = stateSdk({ selected: row });const kv = new StateKV(sdk as never); + const controller = registerCaptureFunctions(sdk as never, kv);controllers.push(controller); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 0 }); +}); + +it('sees an acknowledged review resolution before its file checkpoint and refuses an uncertain review mutation', async () => { + const path = await fixture();const row = completedRow('selected'); + await writeFile(path, JSON.stringify({ selected: row })); + const { sdk } = stateSdk({ selected: row });const kv = new StateKV(sdk as never); + const controller = registerCaptureFunctions(sdk as never, kv);controllers.push(controller); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 1 }); + await kv.set(KV.captureReview, row.key, { key: row.key, sdkResolution: null }); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 0 }); + sdk.registerFunction('state::set', async () => { throw Error('synthetic unknown SDK mutation'); }); + await expect(kv.set(KV.captureReview, row.key, { key: row.key })).rejects.toThrow('synthetic unknown SDK mutation'); + expect((await controller.status()).inbox).toBeNull(); +}); + +it('keeps per-row history GET and unknown physical projection keys without a local reader', async () => { + vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH', ''); + const row = completedRow('legacy');const { sdk, list } = stateSdk({ legacy: row }); + list.mockImplementation(async () => [row]); + const kv = new StateKV(sdk as never, { durability: createStateDurabilityFence({ storePath: '/synthetic-only', completion: 'sdk' }) }); + const get = vi.spyOn(kv, 'get'); + const controller = registerCaptureFunctions(sdk as never, kv);controllers.push(controller); + expect((await controller.status()).inbox).toMatchObject({ sdkCompleted: 1 }); + expect(get.mock.calls.filter(([scope]) => scope === KV.captureReview)).toHaveLength(1); + expect(await kv.list(KV.captureInbox, { project: (_value, key) => key })).toEqual([undefined]); +}); diff --git a/test/capture-sdk-reconciliation.test.ts b/test/capture-sdk-reconciliation.test.ts index d4881fd14e..5bbe23e6d6 100644 --- a/test/capture-sdk-reconciliation.test.ts +++ b/test/capture-sdk-reconciliation.test.ts @@ -1,7 +1,10 @@ import{it,expect}from'vitest';import{createHash}from'node:crypto'; -import{mockKV}from'./helpers/mocks.js';import{KV}from'../src/state/schema.js';import{createRecordRecoveryGate}from'../src/state/recovery-write-gate.js';import{captureEventScope}from'../src/capture/event-record.js';import{createSdkCaptureReconciliation}from'../src/capture/sdk-reconciliation.js'; +import{mockKV,mockSdk}from'./helpers/mocks.js';import{KV}from'../src/state/schema.js';import{createRecordRecoveryGate}from'../src/state/recovery-write-gate.js';import{captureEventScope}from'../src/capture/event-record.js';import{createSdkCaptureReconciliation}from'../src/capture/sdk-reconciliation.js'; import{capturePayloadDigest}from'../src/capture/receipt-digest.js'; import{assertSdkSourceLegacyProtection}from'../src/capture/sdk-source-restore.js'; +import{committedInboxMetadata,projectCaptureInbox}from'../src/capture/inbox-metadata.js'; +import{captureReviewPage}from'../src/capture/review.js'; +import{registerCaptureFunctions}from'../src/functions/capture.js'; const req='00000000-0000-4000-8000-000000000001',otherReq='00000000-0000-4000-8000-000000000002'; const payload={sessionId:'synthetic',project:'synthetic',cwd:'/synthetic',hookType:'post_tool_use',timestamp:'2026-10-29T00:00:00Z',data:{tool_output:'original synthetic source'}}; const eventId='synthetic_reconcile_001',key='cap_'+createHash('sha256').update(payload.project+'\0'+payload.sessionId+'\0'+eventId).digest('hex').slice(0,40),id='obs_synthetic_reconcile'; @@ -35,6 +38,26 @@ it('reconciles an actually stored capture with SDK completion and preserves ever expect(await f.kv.get(KV.observations(payload.sessionId),id)).toEqual(obs);expect(await f.kv.get(KV.captureRecovery,'control')).toEqual(control);expect(await f.kv.get(captureEventScope(key),key)).toBeNull();expect(f.writeCount()).toBe(4); }); it('same or later request on an already reconciled key verifies without replay or new writes',async()=>{const f=await fixture();await f.call();const writes=f.writeCount();expect(await f.call()).toMatchObject({status:'already_reconciled',completed:true});expect(await f.helper.reconcile({key,requestId:otherReq,sourceDigest})).toMatchObject({status:'already_reconciled',requestId:req});expect(f.writeCount()).toBe(writes)}); +it.each([1,2])('preserves v%s completion through projected metadata while checking the current original',async version=>{ + const f=await fixture();await f.call();const h=await f.kv.get(KV.captureReview,key); + if(version===1){h.sdkResolution.version=1;delete h.sdkResolution.indexEvidence;delete h.sdkResolution.priorInboxDigest;delete h.sdkResolution.priorReviewState;await f.kv.set(KV.captureReview,key,h)} + const rec=await f.kv.get(KV.captureInbox,key),metadata=projectCaptureInbox(rec); + const controller=registerCaptureFunctions(mockSdk() as never,f.kv as never); + try{ + expect(metadata).not.toHaveProperty('payload'); + expect(await committedInboxMetadata(f.kv as never,h,metadata)).toBe(true); + expect((await controller.status()).inbox?.sdkCompleted).toBe(1); + expect((await captureReviewPage(f.kv as never,{})).items[0].status).toBe('completed'); + const changed=structuredClone(rec);changed.payload.data.tool_output='changed original';await f.kv.set(KV.captureInbox,key,changed); + expect(await committedInboxMetadata(f.kv as never,h,metadata)).toBe(false); + expect((await controller.status()).inbox?.sdkCompleted).toBe(0); + expect((await captureReviewPage(f.kv as never,{})).items[0].status).toBe('pending'); + await f.kv.set(KV.captureInbox,key,{...rec,updatedAt:'2026-11-07T00:00:00Z'}); + expect(await committedInboxMetadata(f.kv as never,h,metadata)).toBe(false); + await f.kv.delete(KV.captureInbox,key); + expect(await committedInboxMetadata(f.kv as never,h,metadata)).toBe(false); + }finally{controller.stop()} +}); it.each(['source','identity','index','deleted','queued','writer','paused','manual'])('refuses unsafe %s before any write',async mode=>{ const f=await fixture();if(mode==='source'){const obs=await f.kv.get(KV.observations(payload.sessionId),id);obs.sourceRaw.raw={tool_output:'different'};await f.kv.set(KV.observations(payload.sessionId),id,obs)} if(mode==='identity'){const obs=await f.kv.get(KV.observations(payload.sessionId),id);obs.captureKey='cap_'+'b'.repeat(40);await f.kv.set(KV.observations(payload.sessionId),id,obs)} diff --git a/test/helpers/mocks.ts b/test/helpers/mocks.ts index 7b3fd335c9..cb936c674d 100644 --- a/test/helpers/mocks.ts +++ b/test/helpers/mocks.ts @@ -33,9 +33,10 @@ export function mockKV() { delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); }, - list: async (scope: string): Promise => { + list: async (scope: string, options?: { project?: (value: unknown, key?: string) => T }): Promise => { const entries = store.get(scope); - return entries ? (Array.from(entries.values()) as T[]) : []; + const values = entries ? Array.from(entries.values()) : []; + return options?.project ? Array.from(entries ?? [], ([key, value]) => options.project!(value, key)) : values as T[]; }, }; } diff --git a/test/sdk-explicit-recovery-v2.test.ts b/test/sdk-explicit-recovery-v2.test.ts new file mode 100644 index 0000000000..43169304b4 --- /dev/null +++ b/test/sdk-explicit-recovery-v2.test.ts @@ -0,0 +1,101 @@ +import {afterEach,beforeEach,expect,it,vi} from 'vitest'; +import {mkdtempSync,readFileSync,rmSync,writeFileSync} from 'node:fs'; +import {join} from 'node:path'; +import {tmpdir} from 'node:os'; +import {createHash} from 'node:crypto'; +import * as delivery from '../src/capture/sdk-delivery-v2.js'; + +const target='http://127.0.0.1:63000'; +let dir:string; +beforeEach(()=>{dir=mkdtempSync(join(tmpdir(),'sdk-explicit-recovery-'));}); +afterEach(()=>{vi.restoreAllMocks();rmSync(dir,{recursive:true,force:true});}); +const payload=(eventId='selected-held-0001')=>({eventId,hookType:'post_tool_use',sessionId:'synthetic-session',project:'synthetic',cwd:'/synthetic',timestamp:'2026-11-02T00:00:00Z',captureCompletion:'sdk-v1',data:{text:'preserved fixture'}}); +function restored(body:ReturnType){ + const key=createHash('sha256').update(body.project+'\0'+body.sessionId+'\0'+body.eventId).digest('hex'); + return {status:201,body:{eventId:body.eventId,completion:'sdk',durable:false,sourceRestore:'sdk-v1',status:'restored',completed:true, + observationId:'obs_'+Date.parse(body.timestamp).toString(36)+'_'+key.slice(0,12)}}; +} +async function held(eventId='selected-held-0001'){ + const body=payload(eventId),store=new delivery.SdkSpoolV2({dir}); + await delivery.deliverSdkCaptureV2(target,body,async()=>({status:422,body:{}}),{dir}); + const sourceId=(await store.pending(target)).find(row=>row.sourceId===createHash('sha256').update(createHash('sha256').update(target).digest('hex')+'\0'+eventId).digest('hex'))!.sourceId; + return {store,sourceId,body}; +} +function reference(sourceId:string){return JSON.parse(readFileSync(join(dir,'queue',sourceId+'.ref'),'utf8'));} +function manifest(sourceId:string){return JSON.parse(readFileSync(join(dir,'originals',sourceId,'manifest.json'),'utf8'));} + +it('explicit restore uses the exact retained source once, requires matched SDK identity, and preserves source bytes',async()=>{ + const {store,sourceId,body}=await held();const original=manifest(sourceId); + const post=vi.fn(async(sent:any)=>{expect(sent).toEqual(body);expect(reference(sourceId)).toMatchObject({state:'sending',owner:{pid:process.pid}});return restored(body);}); + expect(await delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir})).toMatchObject({completed:true,status:'restored',sourceRetained:true,sdkReplyConfirmed:true,durable:false}); + expect(post).toHaveBeenCalledTimes(1);expect(manifest(sourceId)).toEqual({...original,completed:true}); + expect(await store.load(target,sourceId)).toEqual(body);expect(await store.pending(target)).toEqual([]); + expect(await delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir})).toMatchObject({completed:true,status:'duplicate',sourceRetained:true}); + expect(post).toHaveBeenCalledTimes(1); +}); + +it('an uncertain response remains held and cannot be retried or acknowledged by an ordinary hook',async()=>{ + const {store,sourceId,body}=await held();const post=vi.fn(async()=>{throw Error('synthetic timeout');}); + expect(await delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir})).toMatchObject({completed:false,status:'held'}); + expect(reference(sourceId)).toMatchObject({state:'held'}); + expect(manifest(sourceId).completed).toBe(false); + expect(post).toHaveBeenCalledTimes(1); + await expect(store.acknowledge(target,sourceId)).rejects.toMatchObject({code:'SOURCE_HELD'}); + await expect(store.retry(target,sourceId,'retry')).rejects.toMatchObject({code:'SOURCE_HELD'}); + await expect(store.hold(target,sourceId,'hold')).rejects.toMatchObject({code:'SOURCE_HELD'}); + expect(await delivery.deliverSdkCaptureV2(target,body,post,{dir})).toMatchObject({outcome:'held'}); + expect(post).toHaveBeenCalledTimes(1); +}); + +it('rejects a mismatching restoration response and leaves the original unacknowledged',async()=>{ + const {sourceId,body}=await held(); + const response=restored(body);response.body.observationId='obs_wrong_000000000000'; + expect(await delivery.restoreSelectedSdkCaptureV2(target,sourceId,async()=>response,{dir})).toMatchObject({completed:false,status:'held'}); + expect(manifest(sourceId).completed).toBe(false); +}); + +it('excludes a concurrent manual restore and hook for the same original',async()=>{ + const {sourceId,body}=await held();let release!:(reply:any)=>void;let entered!:()=>void; + const started=new Promise(resolve=>{entered=resolve;}); + const post=vi.fn(()=>new Promise(resolve=>{release=resolve;entered();})); + const first=delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir});await started; + expect(await delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir})).toMatchObject({completed:false,status:'held'}); + expect(await delivery.deliverSdkCaptureV2(target,body,post,{dir})).toMatchObject({outcome:'held'}); + release(restored(body));expect(await first).toMatchObject({completed:true});expect(post).toHaveBeenCalledTimes(1); +}); + +it('a crash after a durable source ACK allows local duplicate recognition without another POST',async()=>{ + const {sourceId,body,store}=await held();const post=vi.fn(async()=>restored(body)); + const first=await delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir,storeOptions:{onPhase(name){if(name==='ack_fsynced')throw Error('crash');}}}); + expect(first).toMatchObject({completed:false,sdkReplyConfirmed:true});expect(manifest(sourceId).completed).toBe(true); + expect(await delivery.restoreSelectedSdkCaptureV2(target,sourceId,post,{dir})).toMatchObject({completed:true,status:'duplicate'}); + expect(post).toHaveBeenCalledTimes(1);expect(await store.load(target,sourceId)).toEqual(body); +}); + +it('selected normal retry sends only the designated pending original and never drains a held neighbour',async()=>{ + const neighbour=await held('other-held-0002');const body=payload('selected-pending-0003'); + await delivery.deliverSdkCaptureV2(target,body,async()=>({status:0,body:null,notSent:true}),{dir}); + const pending=(await neighbour.store.pending(target)).find(row=>row.state==='pending')!; + vi.spyOn(Date,'now').mockReturnValue(pending.nextAttemptAt+1); + const post=vi.fn(async(sent:any)=>{expect(sent).toEqual(body);return {status:200,body:{eventId:body.eventId,completed:true,completion:'sdk',durable:false,status:'accepted'}};}); + expect(await delivery.deliverSdkCaptureV2(target,await neighbour.store.load(target,pending.sourceId),post,{dir})).toMatchObject({outcome:'delivered'}); + expect(post).toHaveBeenCalledTimes(1);expect(manifest(neighbour.sourceId).completed).toBe(false); + expect(await neighbour.store.pending(target)).toMatchObject([{sourceId:neighbour.sourceId,state:'held'}]); +}); + +it('the old restore stub never transmits, and a changed held payload cannot be claimed',async()=>{ + const {store,sourceId,body}=await held();const post=vi.fn(async()=>restored(body)); + expect(await delivery.restoreSdkCaptureV2(target,sourceId,post,{dir})).toMatchObject({code:'SDK_SOURCE_RESTORE_REQUIRES_REVIEW'}); + expect(post).not.toHaveBeenCalled(); + await expect(store.markSending(target,sourceId,{...body,data:{text:'changed'}})).rejects.toMatchObject({code:'SOURCE_HELD'}); + expect(reference(sourceId).state).toBe('held'); +}); +it('a stale owner cannot acknowledge, retry or hold the current sender reference',async()=>{ + const {store,sourceId,body}=await held();await store.markSending(target,sourceId,body); + const ref=reference(sourceId);ref.owner.start='mismatched-generation'; + writeFileSync(join(dir,'queue',sourceId+'.ref'),JSON.stringify(ref)); + for(const operation of [()=>store.acknowledge(target,sourceId),()=>store.retry(target,sourceId,'retry'),()=>store.hold(target,sourceId,'hold')]){ + await expect(operation()).rejects.toMatchObject({code:'SOURCE_HELD'}); + expect(reference(sourceId)).toEqual(ref);expect(manifest(sourceId).completed).toBe(false); + } +}); diff --git a/tsdown.config.ts b/tsdown.config.ts index 22daba6fee..defb2a182d 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -79,6 +79,13 @@ export default defineConfig([ clean: false, sourcemap: false, }, + { + entry: ["src/capture/sdk-delivery-v2.ts"], + outDir: "dist", + ...shared, + clean: false, + sourcemap: false, + }, { entry: ["src/mcp/standalone.ts"], outDir: "dist", From f8246e56eb666ef0f9cefa9135ccbe4df5b9deb6 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 7 Nov 2026 14:03:13 +0900 Subject: [PATCH 05/23] fix(capture): allow SDK queues to drain at capacity --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 6 + docs/customizations/CAPTURE-SDK-V2.md | 2 + docs/customizations/SDK-QUEUE-PROGRESS-61.md | 17 +++ integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/_capture.mjs | 88 ++++++++------ plugin/scripts/codex-compat/_capture.mjs | 106 ++++++++++------- plugin/scripts/codex-compat/manifest.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- scripts/plugins/package-codex.mjs | 2 +- src/capture/sdk-delivery-v2.ts | 16 +-- src/capture/sdk-spool-v2.ts | 38 +++++-- src/functions/export-import.ts | 2 +- src/types.ts | 2 +- src/version.ts | 2 +- test/sdk-spool-progress.test.ts | 114 +++++++++++++++++++ test/sdk-spool-v2.test.ts | 7 +- 30 files changed, 315 insertions(+), 125 deletions(-) create mode 100644 docs/customizations/SDK-QUEUE-PROGRESS-61.md create mode 100644 test/sdk-spool-progress.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index c68321dc10..fdf8fe96cf 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 0c6f0ed31b..acaefe8df7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.60) +## Current Stats (v0.9.32-daniel.61) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index 9313d45f48..57e4ae1f6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ## [Unreleased] +## [0.9.32-daniel.61] — 2026-11-07 +- Fix native SDK-v2 backlog progress at full admission quotas. Existing reference transitions have a bounded additional 8 KiB workspace and completion-manifest replacement 68 KiB; new originals/references cannot consume this workspace. Preserve all originals, crash files and unknown-send holds. +- Measure only the namespace being charged. Direct delivery claims its selected reference without reading the whole pending inbox; pending listings read manifests, and selected source bytes still receive complete hash verification before transmission. Keep owner fencing, known-not-sent backoff and matching SDK acknowledgement. +- Prepare a client-only .61 follow-up to the .60 server. Scoped validation passed 126 distinct tests, including 1,201 actual synthetic deliveries, a saturated 1,240-reference/3,568-original fixture, retained-original hashes, compiled native hooks and concurrent/unknown-send safety. All 39 sequential build configurations, SDK dependency audit, compatibility artifacts, skills and docs checks passed. The 30 TypeScript diagnostics exactly match a fresh .60 baseline. Actual activation remains separate; see `docs/customizations/SDK-QUEUE-PROGRESS-61.md`. Long-term memory recording remains pending manual review. + ## [0.9.32-daniel.60] — 2026-11-07 - Read retained capture inboxes through the existing local streaming reader with SDK-acknowledged changes overlaid. Project status and bounded previews before retaining rows, so capture admission, review and retry no longer request an oversized shared SDK frame. Read keyed review metadata once for status instead of making one SDK call per retained original. Keep original payloads and existing per-source completion proofs. - Add an explicitly invoked selected-source recovery entry for held SDK-v2 sources. Revalidate the retained original, claim it atomically, verify the restore reply, and preserve the original after SDK acknowledgement. Ordinary hooks do not invoke restoration; SDK acknowledgement is not a disk durability claim. @@ -579,6 +584,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.61]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.60...v0.9.32-daniel.61 [0.9.32-daniel.60]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.59...v0.9.32-daniel.60 [0.9.32-daniel.57]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.55...v0.9.32-daniel.57 [0.9.32-daniel.55]: https://github.com/rohitg00/agentmemory/compare/v0.9.31-daniel.54...v0.9.32-daniel.55 diff --git a/docs/customizations/CAPTURE-SDK-V2.md b/docs/customizations/CAPTURE-SDK-V2.md index 983662710f..233a41c71c 100644 --- a/docs/customizations/CAPTURE-SDK-V2.md +++ b/docs/customizations/CAPTURE-SDK-V2.md @@ -12,6 +12,8 @@ Store root/originals/queue are current-user0700 and actual opened source/manifes All target quotas use one existing /usr/bin/flock inherited-fd lease. Linux/flock absence fails closed; no tool is installed. Process fd closure releases the kernel lock; no stale-lock unlink or signals to other processes exist. Original/partial/conflict source allocation counts conservatively, using file/directory allocation and at least4KiB per entry; queue root/directory/lease have minimum12KiB metadata. This is logical conservative admission, not a filesystem hard quota. All target namespaces share256MiB/5MiB. Only matching target hashes drain; credential-bearing URLs are not stored. +The .61 client-only follow-up reserves bounded transition workspace beyond those unchanged admission limits:8KiB for existing reference replacement and68KiB for completed manifests. New admission cannot use it, and preserved crash files count against it. Pending listings read manifest metadata; selected sends still verify all original bytes. See [SDK queue progress](SDK-QUEUE-PROGRESS-61.md) for regression evidence and the separate activation boundary. + ## Completion and recovery The sender persists sending intent before any POST, then reloads/verifies the stored body. Only matching eventId plus completion:sdk/completed:true/durable:false acknowledges source metadata; source bytes are retained. SDK ACK is not engine disk-flush proof. Unknown sends, interrupted owner epochs, mismatched ACKs and unsupported legacy completion remain held. Known connection refusal and matching retryable admission rejection may back off; same stored reference is used. Fresh same-key completion does not create duplicate POSTs. Local queue/full/ACK-write errors cannot overwrite source or become silent success. diff --git a/docs/customizations/SDK-QUEUE-PROGRESS-61.md b/docs/customizations/SDK-QUEUE-PROGRESS-61.md new file mode 100644 index 0000000000..4428c47117 --- /dev/null +++ b/docs/customizations/SDK-QUEUE-PROGRESS-61.md @@ -0,0 +1,17 @@ +# SDK queue progress, client-only .61 preparation + +The .60 server fixes retained-inbox transport size, but the installed .55 SDK-v2 client can stop making progress once its private reference queue reaches the 5 MiB admission limit. Atomic pending-to-sending and sending-to-held/retry replacement previously demanded additional quota that admission could consume. Completed-manifest replacement had the same problem at the 256 MiB original limit. A selected delivery also loaded every pending original, and each queue budget recursively measured unrelated originals while holding the shared lease. + +This change keeps the existing 256 MiB original and 5 MiB reference admission limits. Only replacement of an existing reference may use an additional 8 KiB (one reference block and one conservative parent-directory block); completing an existing manifest may use an additional 68 KiB (the 64 KiB manifest limit and one directory block). No new source or reference can consume that transition workspace. All preserved partial/crash files still count, so exhausted workspace fails explicitly without deletion or quota bypass. These are conservative logical charges, not filesystem hard quotas. Each namespace is measured separately. + +Direct delivery reuses the existing selected-reference send path. The atomic claim preserves current/dead owner fencing, pending backoff and explicitly selected held restoration. Listing pending references validates their private manifest metadata and skips completed sources without reading all source chunks. The selected source still receives complete canonical-envelope/chunk/hash verification before claim and POST. Unselected chunk corruption is discovered when that item is selected, not by listing unrelated entries. Unknown transport/reply outcomes remain held; SDK acknowledgement remains distinct from disk durability. + +Originals retained after failed enqueue remain preserved and are not silently auto-replayed. A reviewed recovery can enumerate manifest metadata, exclude completed/conflicted or unknown-send entries, then use the existing selected public SDK path for exact target/source recovery. No direct original/ref rewrite, lease removal, global reset or deletion is part of this change. + +The isolated worktree starts at .60 commit `7343a8e45aba4e73cf228564290ea1ae95479068`. Four new regression cases first failed on the original code for the expected quota/full-read/coupling causes. Initial scoped SDK validation then passed 71 tests across five suites, including 1,201 actual synthetic deliveries with all original hashes retained; a 1,240-reference/3,568-original saturated fixture; selected read-count bounds; conflicting/current-owner protection; and unknown reply holds. + +Final preparation checks passed all 39 build configurations sequentially with a 1,536 MiB V8 heap, asset copying, server SDK dependency audit, and Codex compatibility artifact generation. The separate native/package/capture group passed 60 tests across six suites, including the updated seven-case progress suite and workspace-exhaustion refusal. One final selected-delivery regression passed separately: a malformed unrelated reference cannot prevent an otherwise valid selected send. Across these scoped runs, 126 distinct tests in ten files passed. All tests used a real temporary HOME and one default fork worker; none connected to the operational service. Skills generation/check (17 skills) and docs synchronization/check passed. `tsc --noEmit` still exits 2 with 30 diagnostics; the entire normalized output exactly matches a fresh check of the unmodified .60 baseline, and neither modified SDK source has a diagnostic. The complete server/integration suite was not rerun for this client-only change. + +Prepared shared native and compatibility capture artifacts have SHA256 `83c703972cf8fb192995a24310f7dcbdc3e54ce826fbe1d91be0fa2c9316a923`; the standalone recovery SDK artifact has SHA256 `b7b93cf1bbb177f7757b1749ddeecc6fde122a396c9873e0a9e9face7804e493`. These are preparation identities, not an operational activation receipt. + +This is a client-only preparation. The production .60 server, issued recovery kits and installed .55 clients are not modified by building or testing this tree. Administrator-reviewed client activation, failed-attempt journal preservation and live acceptance are separate. No operational API/SDK connection is used by the synthetic tests. Memory recording is pending manual review. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 7e9190f46a..5faa01cd5c 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.60 +version: 0.9.32-daniel.61 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 2c2eb96930..1937eb634a 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index 10857d0ca0..feefbe9511 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 8ccce2a145..4e85884401 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index ecfd8ef788..7c0781f448 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.60 +version: 0.9.32-daniel.61 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index d9955a049a..9fd0ba346f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 8c3767751b..f17d1b8ed5 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.60" + "@agentmemory/agentmemory": "0.9.32-daniel.61" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 6ed9b3301a..8845174707 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 35cdb86ffa..4e75738831 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index 9e2ff616ef..64679f4342 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.60" + "@agentmemory/mcp@0.9.32-daniel.61" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 616ac50ad2..8c37305878 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 9bd5ba6fe1..af77d965b4 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/_capture.mjs b/plugin/scripts/_capture.mjs index d56f57eef3..7a6cb067a7 100644 --- a/plugin/scripts/_capture.mjs +++ b/plugin/scripts/_capture.mjs @@ -11,6 +11,8 @@ const BLOCK = 4096; const INPUT_LIMIT = 8 * MiB; const ORIGINAL_LIMIT = 256 * MiB; const QUEUE_LIMIT = 5 * MiB; +const QUEUE_TRANSITION_RESERVE = 2 * BLOCK; +const ACK_TRANSITION_RESERVE = 64 * 1024 + BLOCK; const CHUNK_LIMIT = 256 * 1024; const ID = /^[a-f0-9]{64}$/; function fail(code) { @@ -142,6 +144,8 @@ function limit(value, maximum) { * rounded to 4 KiB and at least stat.blocks*512; they are not filesystem hard quotas. * The queue includes a 4 KiB lease plus queue/root directory charges (12 KiB minimum). * Writes additionally reserve a parent-directory block, and 256 bytes per new chunk-directory entry. +* Admission cannot consume transition workspace: existing refs may use an additional 8 KiB, +* and completed manifests an additional 68 KiB. Preserved crash temporaries count toward both. * /usr/bin/flock is required; no lock fallback, lease deletion, or source cleanup exists. */ var SdkSpoolV2 = class { dir; @@ -184,10 +188,11 @@ var SdkSpoolV2 = class { queueBytes: measure(this.queue) + BLOCK }; } - budget(kind, additional) { - const usage = this.rawUsage(); - if (kind === "original" && usage.originalBytes + additional > this.maxOriginalBytes) fail("ORIGINALS_FULL"); - if (kind === "queue" && usage.queueBytes + additional > this.maxQueueBytes) fail("QUEUE_FULL"); + budget(kind, additional, transition = false) { + const usage = kind === "original" ? measure(this.originals) : measure(this.queue) + BLOCK; + const maximum = kind === "original" ? this.maxOriginalBytes : this.maxQueueBytes; + const reserve = transition ? kind === "original" ? ACK_TRANSITION_RESERVE : QUEUE_TRANSITION_RESERVE : 0; + if (usage + additional > maximum + reserve) fail(kind === "original" ? "ORIGINALS_FULL" : "QUEUE_FULL"); } writeFile(path, bytes) { const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384); @@ -199,9 +204,10 @@ var SdkSpoolV2 = class { closeSync(fd); } } - atomicJson(path, value, kind, beforePublish) { + atomicJson(path, value, kind, beforePublish, transition = false) { const bytes = Buffer.from(canonical$1(value)); - if (kind) this.budget(kind, charge(bytes.length) + BLOCK); + if (kind && bytes.length > (kind === "queue" ? BLOCK : 64 * 1024)) fail("SOURCE_UNVERIFIED"); + if (kind) this.budget(kind, charge(bytes.length) + BLOCK, transition); const temp = path + "." + randomUUID() + ".tmp"; this.writeFile(temp, bytes); if (beforePublish) this.phase(beforePublish); @@ -255,13 +261,22 @@ var SdkSpoolV2 = class { conflictKey(target, eventId, body) { return digest$1(this.key(target, eventId) + "\0conflict\0" + sourceFingerprint(body)); } - source(target, sourceId) { + manifest(target, sourceId) { if (!ID.test(sourceId)) fail("SOURCE_UNVERIFIED"); try { const folder = join(this.originals, sourceId); checkDirectory(folder); const manifest = JSON.parse(regularRead(join(folder, "manifest.json"), 64 * 1024).toString()); if (!manifest || manifest.v !== 2 || manifest.sourceId !== sourceId || manifest.targetHash !== digest$1(target) || typeof manifest.eventId !== "string" || !Number.isSafeInteger(manifest.bytes) || manifest.bytes <= 0 || manifest.bytes > this.maxInputBytes || !ID.test(manifest.hash) || typeof manifest.conflict !== "boolean" || typeof manifest.completed !== "boolean" || !Array.isArray(manifest.chunks) || !manifest.chunks.length || manifest.chunks.length > this.maxInputBytes) fail("SOURCE_UNVERIFIED"); + return manifest; + } catch (error) { + if (code(error) === "STORE_UNSAFE") throw error; + fail("SOURCE_UNVERIFIED"); + } + } + source(target, sourceId) { + try { + const manifest = this.manifest(target, sourceId), folder = join(this.originals, sourceId); let bytes = 0; const chunks = manifest.chunks.map((chunk, index) => { if (chunk.name !== String(index).padStart(6, "0") + ".chunk" || !Number.isSafeInteger(chunk.bytes) || chunk.bytes <= 0 || chunk.bytes > CHUNK_LIMIT || !ID.test(chunk.hash)) fail("SOURCE_UNVERIFIED"); @@ -394,8 +409,8 @@ var SdkSpoolV2 = class { fail("SOURCE_UNVERIFIED"); } } - writeRef(ref) { - this.atomicJson(this.refPath(ref.sourceId), ref, "queue"); + writeRef(ref, transition = true) { + this.atomicJson(this.refPath(ref.sourceId), ref, "queue", void 0, transition); this.phase("reference_published"); } async enqueue(target, sourceId) { @@ -416,7 +431,7 @@ var SdkSpoolV2 = class { state: "pending", attempts: 0, nextAttemptAt: 0 - }); + }, false); }); } async pending(target) { @@ -432,7 +447,7 @@ var SdkSpoolV2 = class { this.writeRef(ref); } try { - if (this.source(target, ref.sourceId).manifest.completed) continue; + if (this.manifest(target, ref.sourceId).completed) continue; } catch { ref.state = "held"; } @@ -454,6 +469,13 @@ var SdkSpoolV2 = class { if (expectedHeldSource) { if (ref.state !== "held" || ref.owner || !isDeepStrictEqual(source.body, expectedHeldSource)) fail("SOURCE_HELD"); } else { + if (ref.state === "sending") { + if (alive(ref.owner)) fail("SOURCE_SENDING"); + ref.state = "held"; + ref.reason = "UNKNOWN_SEND"; + delete ref.owner; + this.writeRef(ref); + } if (ref.state !== "pending") fail("SOURCE_HELD"); if (ref.nextAttemptAt > Date.now()) fail("SOURCE_BACKOFF"); } @@ -473,7 +495,7 @@ var SdkSpoolV2 = class { const ref = this.readRef(target, sourceId); if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); source.manifest.completed = true; - this.atomicJson(join(this.originals, sourceId, "manifest.json"), source.manifest, "original", "ack_before_publish"); + this.atomicJson(join(this.originals, sourceId, "manifest.json"), source.manifest, "original", "ack_before_publish", true); this.phase("ack_fsynced"); } try { @@ -554,7 +576,13 @@ async function sendReference(store, target, sourceId, post, deadline) { try { await store.markSending(target, sourceId); } catch (error) { - return held(safeCode(error)); + const code = error?.code; + if (code === "SOURCE_BACKOFF") return { + outcome: "spooled", + sourceAcknowledged: true, + referenceAcknowledged: true + }; + return held(code === "SOURCE_SENDING" ? "SDK_SEND_IN_PROGRESS_OR_UNCERTAIN" : safeCode(error)); } let body; try { @@ -648,30 +676,16 @@ async function deliverSdkCaptureV2(target, body, post, options = {}) { referenceAcknowledged: false }; } - let pending; - try { - pending = (await store.pending(target)).find((record) => record.sourceId === sourceId); - } catch (error) { - return held(safeCode(error)); - } - if (!pending) { - try { - if ((await store.retain(target, storedBody.eventId, storedBody)).completed) return { - outcome: "duplicate", - sourceAcknowledged: true, - referenceAcknowledged: true, - sdkReplyConfirmed: true - }; - } catch {} - return held("QUEUE_STATE_UNCONFIRMED"); - } - if (pending.state !== "pending") return held(pending.state === "sending" ? "SDK_SEND_IN_PROGRESS_OR_UNCERTAIN" : "SOURCE_HELD"); - if (pending.nextAttemptAt > Date.now()) return { - outcome: "spooled", - sourceAcknowledged: true, - referenceAcknowledged: true - }; - return sendReference(store, target, sourceId, post); + const sent = await sendReference(store, target, sourceId, post); + if (sent.code === "SOURCE_HELD") try { + if ((await store.retain(target, storedBody.eventId, storedBody)).completed) return { + outcome: "duplicate", + sourceAcknowledged: true, + referenceAcknowledged: true, + sdkReplyConfirmed: true + }; + } catch {} + return sent; } async function drainSdkCapturesV2(target, post, options = {}) { const result = { diff --git a/plugin/scripts/codex-compat/_capture.mjs b/plugin/scripts/codex-compat/_capture.mjs index 8ecb006c0e..7a6cb067a7 100644 --- a/plugin/scripts/codex-compat/_capture.mjs +++ b/plugin/scripts/codex-compat/_capture.mjs @@ -1,6 +1,6 @@ import { performance } from "node:perf_hooks"; -import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs"; import { createHash, randomUUID } from "node:crypto"; +import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs"; import { homedir, platform } from "node:os"; import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path"; import { isDeepStrictEqual } from "node:util"; @@ -11,6 +11,8 @@ const BLOCK = 4096; const INPUT_LIMIT = 8 * MiB; const ORIGINAL_LIMIT = 256 * MiB; const QUEUE_LIMIT = 5 * MiB; +const QUEUE_TRANSITION_RESERVE = 2 * BLOCK; +const ACK_TRANSITION_RESERVE = 64 * 1024 + BLOCK; const CHUNK_LIMIT = 256 * 1024; const ID = /^[a-f0-9]{64}$/; function fail(code) { @@ -142,6 +144,8 @@ function limit(value, maximum) { * rounded to 4 KiB and at least stat.blocks*512; they are not filesystem hard quotas. * The queue includes a 4 KiB lease plus queue/root directory charges (12 KiB minimum). * Writes additionally reserve a parent-directory block, and 256 bytes per new chunk-directory entry. +* Admission cannot consume transition workspace: existing refs may use an additional 8 KiB, +* and completed manifests an additional 68 KiB. Preserved crash temporaries count toward both. * /usr/bin/flock is required; no lock fallback, lease deletion, or source cleanup exists. */ var SdkSpoolV2 = class { dir; @@ -184,10 +188,11 @@ var SdkSpoolV2 = class { queueBytes: measure(this.queue) + BLOCK }; } - budget(kind, additional) { - const usage = this.rawUsage(); - if (kind === "original" && usage.originalBytes + additional > this.maxOriginalBytes) fail("ORIGINALS_FULL"); - if (kind === "queue" && usage.queueBytes + additional > this.maxQueueBytes) fail("QUEUE_FULL"); + budget(kind, additional, transition = false) { + const usage = kind === "original" ? measure(this.originals) : measure(this.queue) + BLOCK; + const maximum = kind === "original" ? this.maxOriginalBytes : this.maxQueueBytes; + const reserve = transition ? kind === "original" ? ACK_TRANSITION_RESERVE : QUEUE_TRANSITION_RESERVE : 0; + if (usage + additional > maximum + reserve) fail(kind === "original" ? "ORIGINALS_FULL" : "QUEUE_FULL"); } writeFile(path, bytes) { const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384); @@ -199,9 +204,10 @@ var SdkSpoolV2 = class { closeSync(fd); } } - atomicJson(path, value, kind, beforePublish) { + atomicJson(path, value, kind, beforePublish, transition = false) { const bytes = Buffer.from(canonical$1(value)); - if (kind) this.budget(kind, charge(bytes.length) + BLOCK); + if (kind && bytes.length > (kind === "queue" ? BLOCK : 64 * 1024)) fail("SOURCE_UNVERIFIED"); + if (kind) this.budget(kind, charge(bytes.length) + BLOCK, transition); const temp = path + "." + randomUUID() + ".tmp"; this.writeFile(temp, bytes); if (beforePublish) this.phase(beforePublish); @@ -255,13 +261,22 @@ var SdkSpoolV2 = class { conflictKey(target, eventId, body) { return digest$1(this.key(target, eventId) + "\0conflict\0" + sourceFingerprint(body)); } - source(target, sourceId) { + manifest(target, sourceId) { if (!ID.test(sourceId)) fail("SOURCE_UNVERIFIED"); try { const folder = join(this.originals, sourceId); checkDirectory(folder); const manifest = JSON.parse(regularRead(join(folder, "manifest.json"), 64 * 1024).toString()); if (!manifest || manifest.v !== 2 || manifest.sourceId !== sourceId || manifest.targetHash !== digest$1(target) || typeof manifest.eventId !== "string" || !Number.isSafeInteger(manifest.bytes) || manifest.bytes <= 0 || manifest.bytes > this.maxInputBytes || !ID.test(manifest.hash) || typeof manifest.conflict !== "boolean" || typeof manifest.completed !== "boolean" || !Array.isArray(manifest.chunks) || !manifest.chunks.length || manifest.chunks.length > this.maxInputBytes) fail("SOURCE_UNVERIFIED"); + return manifest; + } catch (error) { + if (code(error) === "STORE_UNSAFE") throw error; + fail("SOURCE_UNVERIFIED"); + } + } + source(target, sourceId) { + try { + const manifest = this.manifest(target, sourceId), folder = join(this.originals, sourceId); let bytes = 0; const chunks = manifest.chunks.map((chunk, index) => { if (chunk.name !== String(index).padStart(6, "0") + ".chunk" || !Number.isSafeInteger(chunk.bytes) || chunk.bytes <= 0 || chunk.bytes > CHUNK_LIMIT || !ID.test(chunk.hash)) fail("SOURCE_UNVERIFIED"); @@ -394,8 +409,8 @@ var SdkSpoolV2 = class { fail("SOURCE_UNVERIFIED"); } } - writeRef(ref) { - this.atomicJson(this.refPath(ref.sourceId), ref, "queue"); + writeRef(ref, transition = true) { + this.atomicJson(this.refPath(ref.sourceId), ref, "queue", void 0, transition); this.phase("reference_published"); } async enqueue(target, sourceId) { @@ -416,7 +431,7 @@ var SdkSpoolV2 = class { state: "pending", attempts: 0, nextAttemptAt: 0 - }); + }, false); }); } async pending(target) { @@ -432,7 +447,7 @@ var SdkSpoolV2 = class { this.writeRef(ref); } try { - if (this.source(target, ref.sourceId).manifest.completed) continue; + if (this.manifest(target, ref.sourceId).completed) continue; } catch { ref.state = "held"; } @@ -446,13 +461,24 @@ var SdkSpoolV2 = class { })); }); } - async markSending(target, sourceId) { + async markSending(target, sourceId, expectedHeldSource) { return this.locked(() => { const source = this.source(target, sourceId); if (source.manifest.conflict || source.manifest.completed) fail("SOURCE_HELD"); const ref = this.readRef(target, sourceId); - if (ref.state !== "pending") fail("SOURCE_HELD"); - if (ref.nextAttemptAt > Date.now()) fail("SOURCE_BACKOFF"); + if (expectedHeldSource) { + if (ref.state !== "held" || ref.owner || !isDeepStrictEqual(source.body, expectedHeldSource)) fail("SOURCE_HELD"); + } else { + if (ref.state === "sending") { + if (alive(ref.owner)) fail("SOURCE_SENDING"); + ref.state = "held"; + ref.reason = "UNKNOWN_SEND"; + delete ref.owner; + this.writeRef(ref); + } + if (ref.state !== "pending") fail("SOURCE_HELD"); + if (ref.nextAttemptAt > Date.now()) fail("SOURCE_BACKOFF"); + } const owner = ownerIdentity(); if (!owner) fail("STORE_BUSY"); ref.state = "sending"; @@ -466,9 +492,10 @@ var SdkSpoolV2 = class { const source = this.source(target, sourceId); if (source.manifest.conflict) fail("SOURCE_CONFLICT"); if (!source.manifest.completed) { - if (this.readRef(target, sourceId).state !== "sending") fail("SOURCE_HELD"); + const ref = this.readRef(target, sourceId); + if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); source.manifest.completed = true; - this.atomicJson(join(this.originals, sourceId, "manifest.json"), source.manifest, "original", "ack_before_publish"); + this.atomicJson(join(this.originals, sourceId, "manifest.json"), source.manifest, "original", "ack_before_publish", true); this.phase("ack_fsynced"); } try { @@ -482,7 +509,7 @@ var SdkSpoolV2 = class { async retry(target, sourceId, _reason) { return this.locked(() => { const ref = this.readRef(target, sourceId); - if (ref.state !== "sending" || !ref.owner || !alive(ref.owner)) fail("SOURCE_HELD"); + if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); ref.attempts = Math.min(1e6, ref.attempts + 1); ref.nextAttemptAt = Date.now() + Math.min(3e5, 1e3 * 2 ** Math.min(9, ref.attempts - 1)); ref.state = "pending"; @@ -494,6 +521,7 @@ var SdkSpoolV2 = class { async hold(target, sourceId, _reason) { return this.locked(() => { const ref = this.readRef(target, sourceId); + if (ref.state !== "sending" || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail("SOURCE_HELD"); ref.state = "held"; ref.reason = "HELD"; delete ref.owner; @@ -548,7 +576,13 @@ async function sendReference(store, target, sourceId, post, deadline) { try { await store.markSending(target, sourceId); } catch (error) { - return held(safeCode(error)); + const code = error?.code; + if (code === "SOURCE_BACKOFF") return { + outcome: "spooled", + sourceAcknowledged: true, + referenceAcknowledged: true + }; + return held(code === "SOURCE_SENDING" ? "SDK_SEND_IN_PROGRESS_OR_UNCERTAIN" : safeCode(error)); } let body; try { @@ -642,30 +676,16 @@ async function deliverSdkCaptureV2(target, body, post, options = {}) { referenceAcknowledged: false }; } - let pending; - try { - pending = (await store.pending(target)).find((record) => record.sourceId === sourceId); - } catch (error) { - return held(safeCode(error)); - } - if (!pending) { - try { - if ((await store.retain(target, storedBody.eventId, storedBody)).completed) return { - outcome: "duplicate", - sourceAcknowledged: true, - referenceAcknowledged: true, - sdkReplyConfirmed: true - }; - } catch {} - return held("QUEUE_STATE_UNCONFIRMED"); - } - if (pending.state !== "pending") return held(pending.state === "sending" ? "SDK_SEND_IN_PROGRESS_OR_UNCERTAIN" : "SOURCE_HELD"); - if (pending.nextAttemptAt > Date.now()) return { - outcome: "spooled", - sourceAcknowledged: true, - referenceAcknowledged: true - }; - return sendReference(store, target, sourceId, post); + const sent = await sendReference(store, target, sourceId, post); + if (sent.code === "SOURCE_HELD") try { + if ((await store.retain(target, storedBody.eventId, storedBody)).completed) return { + outcome: "duplicate", + sourceAcknowledged: true, + referenceAcknowledged: true, + sdkReplyConfirmed: true + }; + } catch {} + return sent; } async function drainSdkCapturesV2(target, post, options = {}) { const result = { diff --git a/plugin/scripts/codex-compat/manifest.json b/plugin/scripts/codex-compat/manifest.json index d0cb6f8204..ae512862da 100644 --- a/plugin/scripts/codex-compat/manifest.json +++ b/plugin/scripts/codex-compat/manifest.json @@ -14,7 +14,7 @@ "subagent-start.mjs": "24a02be53008721379cbf115884a7739baa2884f8d5f3e12a967b9ae8b0c2869", "subagent-stop.mjs": "8fc6929af24afd799cbaec3a3ca210971c9f51f139f6666fe0025fdfdc62dba8", "provenance.json": "4d768394ad40a29be9d2721fccffd0a054ec97bcc6b868305a27e755eb9b1759", - "_capture.mjs": "d48e2e7d12d6790a0851127bfef80b35e0c0cae8b7664c6897b0965b38bd9838" + "_capture.mjs": "83c703972cf8fb192995a24310f7dcbdc3e54ce826fbe1d91be0fa2c9316a923" }, "deploymentMapping": { "plugin/scripts/long-session-hook-client.mjs": "plugin/scripts/codex-compat/long-session-hook-client.mjs", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index ef7464b5c7..ae9dfce22b 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.60"; +const VERSION = "0.9.32-daniel.61"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 3b8bfbf85d..45c37d2a55 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.60", + "version": "0.9.32-daniel.61", "facts": { "mcpTools": [ "55" diff --git a/scripts/plugins/package-codex.mjs b/scripts/plugins/package-codex.mjs index 5c327dfdc5..da86af56f7 100644 --- a/scripts/plugins/package-codex.mjs +++ b/scripts/plugins/package-codex.mjs @@ -63,7 +63,7 @@ for (const [flavor, { mcp, hooks }] of Object.entries(FLAVORS)) { cpSync(join(plugin, ".mcp.codex.json"), join(destination, ".mcp.json")); cpSync(join(plugin, "scripts/plugin-bridge.mjs"), join(destination, "scripts/plugin-bridge.mjs")); cpSync(join(root, "docs/plugins/codex-local.md"), join(destination, "README.md")); - if (hooks === "sdk-v2") writeFileSync(join(destination, "README.md"), `# Agent Memory native SDK capture v2 (prepared policy)\n\nThis is the full six-hook local package. Global hooks are not installed or changed. SessionStart, PreToolUse and PreCompact preserve their context/session behavior. Only UserPromptSubmit, PostToolUse and Stop receive the explicit --agentmemory-sdk-capture-v2 flag; Stop retains its nonfinal session end. The selected MCP contract is unchanged.\n\nUbuntu/Linux requires the already installed /usr/bin/flock; no fallback or new privileged helper is installed. The approved default storage is HOME/.local/share/agentmemory/capture-spool-sdk-v2. A development-only isolated-directory override is available as AGENTMEMORY_SDK_CAPTURE_V2_DIR and must be reviewed before host activation.\n\nThe privacy-scrubbed canonical envelope limit is 8 MiB, chunk limit 256 KiB, originals budget 256 MiB and reference queue budget 5 MiB. Directory/file allocation and partial/conflict data count conservatively; these are not a filesystem hard quota. There is no automatic deletion or expiry of originals. Old spools and unknown history are not read, moved, replayed or deleted. Full quota or preservation failure returns an explicit failure; this cannot promise acceptance of unlimited future input.\n\nComplete source publication and hash readback precede its reference and every POST to the same endpoint; C v2 POSTs refuse redirects. Only a matching SDK completion ACK is recorded; it is not a disk-flush receipt. Known-not-sent or explicit admission rejection may retry via the reference. Uncertain sending is held, never silently marked complete. Ordinary later prompt/tool invocations may opportunistically drain at most one eligible reference with a monotonic POST-admission/network-wait budget capped at 250ms and the remaining invocation budget. Source readback and JSON serialization consume that budget; an expired budget starts no POST and keeps a known-not-sent reference for backoff. Required synchronous state fsync and the final consistent report may finish after the deadline, so this is not a hard wall-clock guarantee for disk I/O. There is no perpetual scheduler or host retry guarantee. Stop does not perform this extra drain.\n\nLarge/image normal observe retransmission can use the verified original. The existing guarded restore API refuses images and payloads over256 KiB; this package does not bypass that restore guard. Other manual restore requires separate review.\n\nPackaging does not install, enable or trust this policy. Review exact six hook definitions, the new storage policy and the actual endpoint/environment before activation.\n`); + if (hooks === "sdk-v2") writeFileSync(join(destination, "README.md"), `# Agent Memory native SDK capture v2 (prepared policy)\n\nThis is the full six-hook local package. Global hooks are not installed or changed. SessionStart, PreToolUse and PreCompact preserve their context/session behavior. Only UserPromptSubmit, PostToolUse and Stop receive the explicit --agentmemory-sdk-capture-v2 flag; Stop retains its nonfinal session end. The selected MCP contract is unchanged.\n\nUbuntu/Linux requires the already installed /usr/bin/flock; no fallback or new privileged helper is installed. The approved default storage is HOME/.local/share/agentmemory/capture-spool-sdk-v2. A development-only isolated-directory override is available as AGENTMEMORY_SDK_CAPTURE_V2_DIR and must be reviewed before host activation.\n\nThe privacy-scrubbed canonical envelope limit is 8 MiB, chunk limit 256 KiB, originals admission budget 256 MiB and reference queue admission budget 5 MiB. Existing reference transitions have an additional bounded 8 KiB workspace; completed-manifest replacement has 68 KiB. New source/reference admission cannot consume this workspace, and preserved crash temporary files still count. Directory/file allocation and partial/conflict data count conservatively; these are not a filesystem hard quota. There is no automatic deletion or expiry of originals. Old spools and unknown history are not read, moved, replayed or deleted. Full quota or preservation failure returns an explicit failure; this cannot promise acceptance of unlimited future input.\n\nComplete source publication and hash readback precede its reference and every POST to the same endpoint; C v2 POSTs refuse redirects. Only a matching SDK completion ACK is recorded; it is not a disk-flush receipt. Known-not-sent or explicit admission rejection may retry via the reference. Uncertain sending is held, never silently marked complete. Ordinary later prompt/tool invocations may opportunistically drain at most one eligible reference with a monotonic POST-admission/network-wait budget capped at 250ms and the remaining invocation budget. Source readback and JSON serialization consume that budget; an expired budget starts no POST and keeps a known-not-sent reference for backoff. Required synchronous state fsync and the final consistent report may finish after the deadline, so this is not a hard wall-clock guarantee for disk I/O. There is no perpetual scheduler or host retry guarantee. Stop does not perform this extra drain.\n\nLarge/image normal observe retransmission can use the verified original. The existing guarded restore API refuses images and payloads over256 KiB; this package does not bypass that restore guard. Other manual restore requires separate review.\n\nPackaging does not install, enable or trust this policy. Review exact six hook definitions, the new storage policy and the actual endpoint/environment before activation.\n`); if (hooks === "pre-tool") writeFileSync(join(destination, "README.md"), `# Agent Memory companion for existing global hooks\n\nThis package preserves MCP, skills and the existing PreToolUse matcher and command. It excludes SessionStart, UserPromptSubmit, PostToolUse, PreCompact and Stop to avoid a second registration alongside separately configured global hooks.\n\nThe existing personal global compatibility artifact has 9 event registrations and 13 files including shared helpers and metadata. Those are different units. This package does not install or trust global hooks, change their event IDs or retained outbox, or verify which host dispatched an event. Select this package only after reviewing the host's active hooks. Existing PreToolUse enrichment data and destination rules remain unchanged.\n`); } else { delete manifest.mcpServers; diff --git a/src/capture/sdk-delivery-v2.ts b/src/capture/sdk-delivery-v2.ts index 183ed4db36..e797a0ab5e 100644 --- a/src/capture/sdk-delivery-v2.ts +++ b/src/capture/sdk-delivery-v2.ts @@ -14,7 +14,11 @@ function createStore(options:V2Options){return new SdkSpoolV2({...options.storeO function held(code:string,sourceAcknowledged=true,referenceAcknowledged=true):V2DeliveryResult{return {outcome:'held',code,sourceAcknowledged,referenceAcknowledged};} async function park(store:SdkSpoolV2,target:string,sourceId:string,code:string){try{await store.hold(target,sourceId,code);}catch{return held('QUEUE_STATE_UNCONFIRMED');}return held(code);} async function sendReference(store:SdkSpoolV2,target:string,sourceId:string,post:V2Post,deadline?:number):Promise{ - try{await store.markSending(target,sourceId);}catch(error){return held(safeCode(error));} + try{await store.markSending(target,sourceId);}catch(error){ + const code=(error as {code?:unknown})?.code; + if(code==='SOURCE_BACKOFF')return {outcome:'spooled',sourceAcknowledged:true,referenceAcknowledged:true}; + return held(code==='SOURCE_SENDING'?'SDK_SEND_IN_PROGRESS_OR_UNCERTAIN':safeCode(error)); + } let body:Record; try{body=await store.load(target,sourceId);}catch{return park(store,target,sourceId,'SOURCE_UNVERIFIED');} let response:V2PostResult; @@ -43,15 +47,11 @@ export async function deliverSdkCaptureV2(target:string,body:Recordrecord.sourceId===sourceId);}catch(error){return held(safeCode(error));} - if(!pending){ + const sent=await sendReference(store,target,sourceId,post); + if(sent.code==='SOURCE_HELD'){ try{if((await store.retain(target,storedBody.eventId as string,storedBody)).completed)return {outcome:'duplicate',sourceAcknowledged:true,referenceAcknowledged:true,sdkReplyConfirmed:true};}catch{} - return held('QUEUE_STATE_UNCONFIRMED'); } - if(pending.state!=='pending')return held(pending.state==='sending'?'SDK_SEND_IN_PROGRESS_OR_UNCERTAIN':'SOURCE_HELD'); - if(pending.nextAttemptAt>Date.now())return {outcome:'spooled',sourceAcknowledged:true,referenceAcknowledged:true}; - return sendReference(store,target,sourceId,post); + return sent; } export async function drainSdkCapturesV2(target:string,post:V2Post,options:V2Options&{limit?:number;budgetMs?:number;deadline?:number}={}){ const result={attempted:0,delivered:0,duplicates:0,held:0,remaining:0,error:undefined as string|undefined}; diff --git a/src/capture/sdk-spool-v2.ts b/src/capture/sdk-spool-v2.ts index 18581b91a5..171af68c1d 100644 --- a/src/capture/sdk-spool-v2.ts +++ b/src/capture/sdk-spool-v2.ts @@ -12,6 +12,8 @@ const BLOCK = 4096; const INPUT_LIMIT = 8 * MiB; const ORIGINAL_LIMIT = 256 * MiB; const QUEUE_LIMIT = 5 * MiB; +const QUEUE_TRANSITION_RESERVE = 2 * BLOCK; +const ACK_TRANSITION_RESERVE = 64 * 1024 + BLOCK; const CHUNK_LIMIT = 256 * 1024; const ID = /^[a-f0-9]{64}$/; type Owner = { pid: number; start: string; boot: string }; @@ -120,6 +122,8 @@ function limit(value: number | undefined, maximum: number): number { * rounded to 4 KiB and at least stat.blocks*512; they are not filesystem hard quotas. * The queue includes a 4 KiB lease plus queue/root directory charges (12 KiB minimum). * Writes additionally reserve a parent-directory block, and 256 bytes per new chunk-directory entry. + * Admission cannot consume transition workspace: existing refs may use an additional 8 KiB, + * and completed manifests an additional 68 KiB. Preserved crash temporaries count toward both. * /usr/bin/flock is required; no lock fallback, lease deletion, or source cleanup exists. */ export class SdkSpoolV2 { readonly dir: string; @@ -154,18 +158,20 @@ export class SdkSpoolV2 { private rawUsage(): { originalBytes: number; queueBytes: number } { return { originalBytes: measure(this.originals), queueBytes: measure(this.queue) + BLOCK }; } - private budget(kind: 'original' | 'queue', additional: number): void { - const usage = this.rawUsage(); - if (kind === 'original' && usage.originalBytes + additional > this.maxOriginalBytes) fail('ORIGINALS_FULL'); - if (kind === 'queue' && usage.queueBytes + additional > this.maxQueueBytes) fail('QUEUE_FULL'); + private budget(kind: 'original' | 'queue', additional: number, transition = false): void { + const usage = kind === 'original' ? measure(this.originals) : measure(this.queue) + BLOCK; + const maximum = kind === 'original' ? this.maxOriginalBytes : this.maxQueueBytes; + const reserve = transition ? kind === 'original' ? ACK_TRANSITION_RESERVE : QUEUE_TRANSITION_RESERVE : 0; + if (usage + additional > maximum + reserve) fail(kind === 'original' ? 'ORIGINALS_FULL' : 'QUEUE_FULL'); } private writeFile(path: string, bytes: Buffer | string): void { const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); try { privateStat(fstatSync(fd), false); writeFileSync(fd, bytes); fsyncSync(fd); } finally { closeSync(fd); } } - private atomicJson(path: string, value: unknown, kind?: 'original' | 'queue', beforePublish?: string): void { + private atomicJson(path: string, value: unknown, kind?: 'original' | 'queue', beforePublish?: string, transition = false): void { const bytes = Buffer.from(canonical(value)); - if (kind) this.budget(kind, charge(bytes.length) + BLOCK); + if (kind && bytes.length > (kind === 'queue' ? BLOCK : 64 * 1024)) fail('SOURCE_UNVERIFIED'); + if (kind) this.budget(kind, charge(bytes.length) + BLOCK, transition); const temp = path + '.' + randomUUID() + '.tmp'; this.writeFile(temp, bytes); if (beforePublish) this.phase(beforePublish); @@ -201,12 +207,18 @@ export class SdkSpoolV2 { } private key(target: string, eventId: string): string { return digest(digest(target) + '\0' + eventId); } private conflictKey(target: string, eventId: string, body: Record): string { return digest(this.key(target, eventId) + '\0conflict\0' + sourceFingerprint(body)); } - private source(target: string, sourceId: string): { manifest: Manifest; body: Record } { + private manifest(target: string, sourceId: string): Manifest { if (!ID.test(sourceId)) fail('SOURCE_UNVERIFIED'); try { const folder = join(this.originals, sourceId); checkDirectory(folder); const manifest = JSON.parse(regularRead(join(folder, 'manifest.json'), 64 * 1024).toString()) as Manifest; if (!manifest || manifest.v !== 2 || manifest.sourceId !== sourceId || manifest.targetHash !== digest(target) || typeof manifest.eventId !== 'string' || !Number.isSafeInteger(manifest.bytes) || manifest.bytes <= 0 || manifest.bytes > this.maxInputBytes || !ID.test(manifest.hash) || typeof manifest.conflict !== 'boolean' || typeof manifest.completed !== 'boolean' || !Array.isArray(manifest.chunks) || !manifest.chunks.length || manifest.chunks.length > this.maxInputBytes) fail('SOURCE_UNVERIFIED'); + return manifest; + } catch (error) { if (code(error) === 'STORE_UNSAFE') throw error; fail('SOURCE_UNVERIFIED'); } + } + private source(target: string, sourceId: string): { manifest: Manifest; body: Record } { + try { + const manifest = this.manifest(target, sourceId), folder = join(this.originals, sourceId); let bytes = 0; const chunks = manifest.chunks.map((chunk, index) => { if (chunk.name !== String(index).padStart(6, '0') + '.chunk' || !Number.isSafeInteger(chunk.bytes) || chunk.bytes <= 0 || chunk.bytes > CHUNK_LIMIT || !ID.test(chunk.hash)) fail('SOURCE_UNVERIFIED'); @@ -275,14 +287,14 @@ export class SdkSpoolV2 { return ref; } catch (error) { if (code(error) === 'ENOENT' || code(error) === 'STORE_UNSAFE') throw error; fail('SOURCE_UNVERIFIED'); } } - private writeRef(ref: Ref): void { this.atomicJson(this.refPath(ref.sourceId), ref, 'queue'); this.phase('reference_published'); } + private writeRef(ref: Ref, transition = true): void { this.atomicJson(this.refPath(ref.sourceId), ref, 'queue', undefined, transition); this.phase('reference_published'); } async enqueue(target: string, sourceId: string): Promise { return this.locked(() => { const { manifest } = this.source(target, sourceId); if (manifest.conflict) fail('SOURCE_CONFLICT'); if (manifest.completed) return; try { this.readRef(target, sourceId); return; } catch (error) { if (code(error) !== 'ENOENT') throw error; } - this.writeRef({ v: 2, targetHash: digest(target), sourceId, state: 'pending', attempts: 0, nextAttemptAt: 0 }); + this.writeRef({ v: 2, targetHash: digest(target), sourceId, state: 'pending', attempts: 0, nextAttemptAt: 0 }, false); }); } async pending(target: string): Promise> { @@ -293,7 +305,7 @@ export class SdkSpoolV2 { if (peek.targetHash !== digest(target)) continue; const ref = this.readRef(target, file.slice(0, -4)); if (ref.state === 'sending' && !alive(ref.owner!)) { ref.state = 'held'; ref.reason = 'UNKNOWN_SEND'; delete ref.owner; this.writeRef(ref); } - try { if (this.source(target, ref.sourceId).manifest.completed) continue; } catch { ref.state = 'held'; } + try { if (this.manifest(target, ref.sourceId).completed) continue; } catch { ref.state = 'held'; } result.push(ref); } return result.map(({ sourceId, state, attempts, nextAttemptAt }) => ({ sourceId, state, attempts, nextAttemptAt })); @@ -307,6 +319,10 @@ export class SdkSpoolV2 { if (expectedHeldSource) { if (ref.state !== 'held' || ref.owner || !isDeepStrictEqual(source.body, expectedHeldSource)) fail('SOURCE_HELD'); } else { + if (ref.state === 'sending') { + if (alive(ref.owner!)) fail('SOURCE_SENDING'); + ref.state = 'held'; ref.reason = 'UNKNOWN_SEND'; delete ref.owner; this.writeRef(ref); + } if (ref.state !== 'pending') fail('SOURCE_HELD'); if (ref.nextAttemptAt > Date.now()) fail('SOURCE_BACKOFF'); } @@ -323,7 +339,7 @@ export class SdkSpoolV2 { const ref = this.readRef(target, sourceId); if (ref.state !== 'sending' || !isDeepStrictEqual(ref.owner, ownerIdentity())) fail('SOURCE_HELD'); source.manifest.completed = true; - this.atomicJson(join(this.originals, sourceId, 'manifest.json'), source.manifest, 'original', 'ack_before_publish'); + this.atomicJson(join(this.originals, sourceId, 'manifest.json'), source.manifest, 'original', 'ack_before_publish', true); this.phase('ack_fsynced'); } try { unlinkSync(this.refPath(sourceId)); syncDirectory(this.queue); } catch (error) { if (code(error) !== 'ENOENT') throw error; } diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 5fcc227078..ac81245307 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/types.ts b/src/types.ts index e9cdb85852..022faddfc1 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index cdcd33f2d9..08a0a80088 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.60"; +export const VERSION = "0.9.32-daniel.61"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/sdk-spool-progress.test.ts b/test/sdk-spool-progress.test.ts new file mode 100644 index 0000000000..6e62d4c694 --- /dev/null +++ b/test/sdk-spool-progress.test.ts @@ -0,0 +1,114 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {createHash} from 'node:crypto'; +import {chmodSync,mkdirSync,mkdtempSync,readFileSync,readdirSync,rmSync,truncateSync,writeFileSync} from 'node:fs'; +import {join} from 'node:path'; +import {tmpdir} from 'node:os'; +import {performance} from 'node:perf_hooks'; +import {SdkSpoolV2} from '../src/capture/sdk-spool-v2.js'; +import {deliverSdkCaptureV2,drainSdkCapturesV2} from '../src/capture/sdk-delivery-v2.js'; + +const BLOCK=4096,MiB=1024*1024,target='https://synthetic.invalid'; +const roots:string[]=[]; +const hash=(v:string|Buffer)=>createHash('sha256').update(v).digest('hex'); +const canonical=(v:any):string=>Array.isArray(v)?'['+v.map(canonical).join(',')+']':v&&typeof v==='object'?'{'+Object.keys(v).sort().map(k=>JSON.stringify(k)+':'+canonical(v[k])).join(',')+'}':JSON.stringify(v); +const ack=(body:Record)=>({status:201,body:{eventId:body.eventId,status:'accepted',completion:'sdk',completed:true,durable:false}}); +afterEach(()=>{vi.restoreAllMocks();for(const root of roots.splice(0))rmSync(root,{recursive:true,force:true});}); +function root(){const path=mkdtempSync(join(tmpdir(),'sdk-progress-'));roots.push(path);return path;} +async function fixture(refs=1240,completed=2328,textBytes=32*1024){ + const dir=root(),store=new SdkSpoolV2({dir});await store.usage(); + const selected:Array<{sourceId:string;body:Record}>=[]; + for(let index=0;index=refs}),{mode:0o600}); + if(index{ + const {dir,store,selected}=await fixture(); + fill(join(dir,'queue','legacy-preserved.tmp'),5*MiB-(await store.usage()).queueBytes); + const before=await store.usage();expect(before.queueBytes).toBeLessThanOrEqual(5*MiB);expect(5*MiB-before.queueBytes).toBeLessThan(2*BLOCK); + const source=selected[0],chunk=join(dir,'originals',source.sourceId,'000000.chunk'),digest=hash(readFileSync(chunk)); + const extra=await store.retain(target,'new-after-full',{eventId:'new-after-full',data:'synthetic'}); + await expect(store.enqueue(target,extra.sourceId)).rejects.toMatchObject({code:'QUEUE_FULL'}); + await store.markSending(target,source.sourceId);await store.retry(target,source.sourceId,'known-not-sent'); + vi.spyOn(Date,'now').mockReturnValue(Date.now()+10000); + await store.markSending(target,source.sourceId);await store.hold(target,source.sourceId,'unknown'); + await expect(store.markSending(target,source.sourceId)).rejects.toMatchObject({code:'SOURCE_HELD'}); + await store.markSending(target,source.sourceId,source.body);await store.acknowledge(target,source.sourceId); + expect(hash(readFileSync(chunk))).toBe(digest);expect(readdirSync(join(dir,'originals'))).toHaveLength(3569); + expect(JSON.parse(readFileSync(join(dir,'originals',source.sourceId,'manifest.json'),'utf8')).completed).toBe(true); + await store.markSending(target,selected[1].sourceId);await store.acknowledge(target,selected[1].sourceId); + await expect(store.enqueue(target,extra.sourceId)).resolves.toBeUndefined(); + expect((await store.usage()).queueBytes).toBeLessThanOrEqual(5*MiB+2*BLOCK); +},30000); + +it('ACKs at the original admission limit while retaining chunks and refusing new originals',async()=>{ + const dir=root(),store=new SdkSpoolV2({dir}),body={eventId:'original-limit',data:'synthetic'}; + const source=await store.retain(target,body.eventId,body);await store.enqueue(target,source.sourceId);await store.markSending(target,source.sourceId); + const before=await store.usage(),limited=new SdkSpoolV2({dir,maxOriginalBytes:before.originalBytes}); + await expect(limited.retain(target,'new',{eventId:'new'})).rejects.toMatchObject({code:'ORIGINALS_FULL'}); + await limited.acknowledge(target,source.sourceId); + expect(await limited.load(target,source.sourceId)).toEqual(body);expect((await limited.usage()).originalBytes).toBeLessThanOrEqual(before.originalBytes+17*BLOCK); +}); + +it('counts preserved crash files against transition workspace and refuses overcommit',async()=>{ + const {dir,store,selected}=await fixture(1,0,256),before=await store.usage(); + fill(join(dir,'queue','preserved-crash.tmp'),BLOCK); + await expect(new SdkSpoolV2({dir,maxQueueBytes:before.queueBytes}).markSending(target,selected[0].sourceId)).rejects.toMatchObject({code:'QUEUE_FULL'}); + expect((await store.pending(target))[0].state).toBe('pending');expect(readFileSync(join(dir,'queue','preserved-crash.tmp'))).toHaveLength(BLOCK); + await store.markSending(target,selected[0].sourceId); + fill(join(dir,'originals','preserved-crash.tmp'),17*BLOCK); + await expect(new SdkSpoolV2({dir,maxOriginalBytes:before.originalBytes}).acknowledge(target,selected[0].sourceId)).rejects.toMatchObject({code:'ORIGINALS_FULL'}); + expect((await store.pending(target))[0].state).toBe('sending');expect(await store.load(target,selected[0].sourceId)).toEqual(selected[0].body); +}); + +it('delivers more than 1200 retained refs without deleting originals or replaying completed entries',async()=>{ + const {dir,store,selected}=await fixture(1201,0,256);let calls=0;const start=performance.now(); + for(const source of selected){const result=await deliverSdkCaptureV2(target,source.body,async body=>{calls++;return ack(body);},{dir});expect(result.outcome).toBe('delivered');} + expect(calls).toBe(1201);expect(await store.pending(target)).toEqual([]);expect(readdirSync(join(dir,'originals'))).toHaveLength(1201); + for(const source of selected){const manifest=JSON.parse(readFileSync(join(dir,'originals',source.sourceId,'manifest.json'),'utf8'));expect(manifest.completed).toBe(true);expect(hash(readFileSync(join(dir,'originals',source.sourceId,'000000.chunk')))).toBe(manifest.hash);} + const completed=await deliverSdkCaptureV2(target,selected[0].body,async body=>{calls++;return ack(body);},{dir});expect(completed.outcome).toBe('duplicate');expect(calls).toBe(1201); + console.log(JSON.stringify({syntheticSpoolDrain:true,delivered:calls,originalsPreserved:1201,elapsedMs:Math.round(performance.now()-start)})); +},120000); + +it('one sender owns delivery while concurrent attempts and unknown replies cannot replay',async()=>{ + const dir=root(),body={eventId:'concurrent',data:'synthetic'};let calls=0,release!:()=>void,started!:()=>void; + const entered=new Promise(resolve=>started=resolve),wait=new Promise(resolve=>release=resolve); + const first=deliverSdkCaptureV2(target,body,async()=>{calls++;started();await wait;throw Error('uncertain');},{dir});await entered; + const second=await deliverSdkCaptureV2(target,body,async value=>{calls++;return ack(value);},{dir});expect(second).toMatchObject({outcome:'held',code:'SDK_SEND_IN_PROGRESS_OR_UNCERTAIN'}); + release();expect(await first).toMatchObject({outcome:'held',code:'SDK_SEND_UNCERTAIN'}); + const third=await deliverSdkCaptureV2(target,body,async value=>{calls++;return ack(value);},{dir});expect(third).toMatchObject({outcome:'held',code:'SOURCE_HELD'});expect(calls).toBe(1); +}); + +it('a malformed unrelated reference cannot prevent selected delivery',async()=>{ + const {dir,selected}=await fixture(2,0,256),unrelated=join(dir,'queue',selected[1].sourceId+'.ref');writeFileSync(unrelated,'{malformed'); + let calls=0;expect(await deliverSdkCaptureV2(target,selected[0].body,async body=>{calls++;return ack(body);},{dir})).toMatchObject({outcome:'delivered'}); + expect(calls).toBe(1);expect(readFileSync(unrelated,'utf8')).toBe('{malformed'); +}); + +it('lists metadata and verifies only selected source bytes for direct delivery and bounded drain',async()=>{ + const {dir,store,selected}=await fixture();let verified=0; + const options={dir,storeOptions:{onPhase:(phase:string)=>{if(phase==='source_verified')verified++;}}}; + const start=performance.now(),records=await new SdkSpoolV2({...options.storeOptions,dir}).pending(target),listingMs=performance.now()-start; + expect(records).toHaveLength(1240);expect(verified).toBe(0); + const result=await deliverSdkCaptureV2(target,selected[0].body,async body=>ack(body),options); + expect(result.outcome).toBe('delivered');expect(verified).toBeLessThanOrEqual(5); + verified=0;const drained=await drainSdkCapturesV2(target,async body=>ack(body),{...options,limit:1,budgetMs:1500}); + expect(drained).toMatchObject({attempted:1,delivered:1,remaining:1238});expect(verified).toBeLessThanOrEqual(3); + console.log(JSON.stringify({syntheticSpoolProgress:true,refs:1240,originals:3568,listingMs:Math.round(listingMs),selectedSourceReads:verified})); + expect((await store.usage()).originalBytes).toBeGreaterThan(100*MiB); +},30000); + +it('queue transitions do not inspect unrelated original trees and corrupt selected bytes never POST',async()=>{ + const {dir,store,selected}=await fixture(2,1),unrelated=join(dir,'originals','unrelated'); + mkdirSync(unrelated,{mode:0o700});writeFileSync(join(unrelated,'private'),'',{mode:0o600});chmodSync(join(unrelated,'private'),0o644); + await store.markSending(target,selected[0].sourceId);await store.hold(target,selected[0].sourceId,'unknown'); + const chunk=join(dir,'originals',selected[1].sourceId,'000000.chunk');writeFileSync(chunk,'corrupt');let posts=0; + const result=await deliverSdkCaptureV2(target,selected[1].body,async body=>{posts++;return ack(body);},{dir}); + expect(result.outcome).toBe('dropped');expect(posts).toBe(0);expect(readFileSync(chunk,'utf8')).toBe('corrupt'); +}); diff --git a/test/sdk-spool-v2.test.ts b/test/sdk-spool-v2.test.ts index 61ca0bdc56..29a309c00b 100644 --- a/test/sdk-spool-v2.test.ts +++ b/test/sdk-spool-v2.test.ts @@ -119,11 +119,12 @@ describe('SdkSpoolV2 durable originals and references',()=>{ expect(results.filter(value=>value.status==='error').every(value=>value.code==='ORIGINALS_FULL')).toBe(true); expect((await store().usage()).originalBytes).toBeLessThanOrEqual(20480); }); - it('enforces queue quota on sending-state atomic replacement',async()=>{ + it('reserves bounded sending-state workspace beyond the queue admission quota',async()=>{ const s=store();const r=await s.retain(target,'event-1',body());await s.enqueue(target,r.sourceId); const before=(await s.usage()).queueBytes;const constrained=store({maxQueueBytes:before}); - await expect(constrained.markSending(target,r.sourceId)).rejects.toMatchObject({code:'QUEUE_FULL'}); - expect((await s.pending(target))[0].state).toBe('pending'); + await expect(constrained.markSending(target,r.sourceId)).resolves.toBeUndefined(); + expect((await s.pending(target))[0].state).toBe('sending'); + expect((await s.usage()).queueBytes).toBeLessThanOrEqual(before+8192); }); it('fails explicitly when a conflict original cannot fit',async()=>{ const s=store();const r=await s.retain(target,'event-1',body());const before=(await s.usage()).originalBytes; From 59dbc72fe7a2f87c6c6991e403896f3b3a1d7803 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 7 Nov 2026 14:38:12 +0900 Subject: [PATCH 06/23] fix(embedding): scope deferred source guards to selected keys --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 5 ++ .../EMBEDDING-SOURCE-GUARD-62.md | 17 +++++ integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- src/functions/export-import.ts | 2 +- src/functions/observe.ts | 4 +- src/ops/embedding-recovery.mjs | 17 +++-- src/ops/state-durability.d.mts | 1 + src/ops/state-durability.mjs | 15 +++- src/types.ts | 2 +- src/version.ts | 2 +- test/embedding-selected-source.test.ts | 72 +++++++++++++++++++ test/helpers/storage-unit-adapter.ts | 2 +- test/observation-certification-lock.test.ts | 32 ++++++++- test/state-durability-key-watch.test.ts | 27 +++++++ 29 files changed, 198 insertions(+), 36 deletions(-) create mode 100644 docs/customizations/EMBEDDING-SOURCE-GUARD-62.md create mode 100644 test/embedding-selected-source.test.ts create mode 100644 test/state-durability-key-watch.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index fdf8fe96cf..346db5ca1f 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index acaefe8df7..1f7a4afc8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.61) +## Current Stats (v0.9.32-daniel.62) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index 57e4ae1f6f..557f5bec84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +## [0.9.32-daniel.62] — 2026-11-07 +- Fix deferred observation embedding certification rejecting an unchanged source when another observation in the same session is written. Reuse the existing durability fence's per-key revision observers, including already pending mutations, and release each selected watch after certification, failure or worker stop. Preserve source replacement/deletion/ABA, intent-generation, missing-fence and uncertain SDK outcome refusals. +- Base the .62 server preparation on .61 commit `f8246e56eb666ef0f9cefa9135ccbe4df5b9deb6`. Keep the .61 client queue repair, server mutation fencing and batch/publication scheduling unchanged. Acquire the new-capture watch after viewer/logging side effects so failed display handling preserves the source/inbox without leaking an unstarted watch. The false rejection and lifecycle failure were reproduced before their fixes; focused mutation/fence/capture regression, all39 sequential build configurations, SDK audit, skills/docs checks and independent review passed. The30 TypeScript diagnostics exactly match .61. See `docs/customizations/EMBEDDING-SOURCE-GUARD-62.md`; operational application and manual long-term-memory review remain separate. + ## [0.9.32-daniel.61] — 2026-11-07 - Fix native SDK-v2 backlog progress at full admission quotas. Existing reference transitions have a bounded additional 8 KiB workspace and completion-manifest replacement 68 KiB; new originals/references cannot consume this workspace. Preserve all originals, crash files and unknown-send holds. - Measure only the namespace being charged. Direct delivery claims its selected reference without reading the whole pending inbox; pending listings read manifests, and selected source bytes still receive complete hash verification before transmission. Keep owner fencing, known-not-sent backoff and matching SDK acknowledgement. @@ -584,6 +588,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.62]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.61...v0.9.32-daniel.62 [0.9.32-daniel.61]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.60...v0.9.32-daniel.61 [0.9.32-daniel.60]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.59...v0.9.32-daniel.60 [0.9.32-daniel.57]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.55...v0.9.32-daniel.57 diff --git a/docs/customizations/EMBEDDING-SOURCE-GUARD-62.md b/docs/customizations/EMBEDDING-SOURCE-GUARD-62.md new file mode 100644 index 0000000000..b4940aeebc --- /dev/null +++ b/docs/customizations/EMBEDDING-SOURCE-GUARD-62.md @@ -0,0 +1,17 @@ +# Selected-source embedding certification: .62 server preparation + +An SDK capture stores its observation and embedding intent under the session lock, then releases that lock before waiting for certification. The .60/.61 deferred source check remembered the mutation revision for the entire observation namespace. A second, unrelated observation in the same session changed that revision and caused `EMBEDDING_SOURCE_CHANGED`, even though the selected observation and intent remained intact. A synthetic regression reproduced this rejection before any product edit. + +The source check now acquires a selected-key watch from the existing state durability fence. It reuses the fence's revision observers, which are notified both before and after every mutation and remain valid across dirty-key pruning. A WeakMap associates only active mutation promises with their key, so registration also rejects a target mutation that was already in progress. It introduces no permanent per-record revision history. The watch is released on successful/failed certification, prepare failure and worker stop. New capture acquires its certifier immediately before returning from the session lock, after viewer/logging side effects, so an earlier viewer exception cannot leak an unstarted watch. Raw observation/inbox preservation and same-observation retry are regression-tested. Viewer events already precede final certification and are not SDK ACKs; the HTTP result still awaits the complete certificate. A missing selected-key facility refuses deferred file certification; callers without that facility retain the existing synchronous fenced path. + +Another key may be written while the selected source is certified. Source replacement, deletion/recreation and ABA still invalidate its watch, including SDK writes that apply before returning a lost response. Source row identity, intent generation and the original source-plus-intent fence remain required. An uncertain unrelated SDK mutation still causes the existing fence refusal; this change does not reinterpret SDK acknowledgement as disk durability. The namespace-wide guards remain in observation readers and receipt inspection where full-namespace consistency is required. + +Scope: based on .61 source commit `f8246e56eb666ef0f9cefa9135ccbe4df5b9deb6`; the new server behavior is limited to `observe.ts`, `embedding-recovery.mjs`, `state-durability.mjs` and its declaration. Relative to the running .60 server, the source also inherits the already prepared .61 client spool/delivery repair and generated version metadata. No batch size, pump ordering, publication evidence retention, provider behavior, actual source/ref data or recovery authorization changes are included. The installed .61 client and .60 server are not modified by this preparation. + +Verification: the original same-session/unrelated-key case failed with `EMBEDDING_SOURCE_CHANGED`; after the patch the four initial suites passed62 tests. The real-StateKV/SDK-fence cases plus all focused state-durability suites and storage-unit adapter passed111 tests, with one existing conditional skip. The related capture/embedding pump, batch, backfill, deletion, publication and receipt tests also passed. Coverage includes unchanged selected sources with another same-session SDK write pending before/after preparation, real target ABA, applied-but-lost responses, missing guards/fences, intent replacement, pruning, source preservation and watch lifecycle cleanup. Uncertain SDK replies preserve the existing `STATE_DURABILITY_TIMEOUT`/`SDK_MUTATION_UNCERTAIN` diagnostic shape. All tests use synthetic state, a real temporary HOME and a single default fork worker. + +The independent lifecycle review additionally reproduced an unstarted watch remaining after a viewer exception; moving acquisition to the last safe point fixed it. The final five-suite observe/capture/StateKV group passed37 tests, including preserved original/inbox, successful idempotent retry and zero leaked watches. + +All39 build configurations passed sequentially with a1,536MiB V8 heap, followed by asset copy, server SDK dependency audit, compatibility artifact generation, skills generation/check17, and docs sync/check. After the final acquisition-position adjustment the affected server index and CLI bundles were rebuilt, their dependency audit passed again, and docs/type checks were repeated. TypeScript reported the same30 diagnostics as the .61 baseline, with normalized complete output equal. Independent final review and a separate three-suite run passed31 tests without another blocker. The full server/integration suite was not rerun for this scoped concurrency change. Client artifacts remained byte-identical to .61: shared native/compat capture `83c703972cf8fb192995a24310f7dcbdc3e54ce826fbe1d91be0fa2c9316a923`, standalone SDK helper `b7b93cf1bbb177f7757b1749ddeecc6fde122a396c9873e0a9e9face7804e493`. + +No service restart, operational API/SDK connection, administrative registration or deployment is performed by these tests. Long-term memory recording is pending manual review. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 5faa01cd5c..4bbec6c05d 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.61 +version: 0.9.32-daniel.62 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 1937eb634a..c5910357c2 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index feefbe9511..a88354b7ac 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 4e85884401..eb54d5a659 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index 7c0781f448..34ff0187a0 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.61 +version: 0.9.32-daniel.62 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 9fd0ba346f..26bb8fa6b9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index f17d1b8ed5..a373a1736c 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.61" + "@agentmemory/agentmemory": "0.9.32-daniel.62" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 8845174707..38632c8120 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 4e75738831..eace8e113c 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index 64679f4342..d0450e3afa 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.61" + "@agentmemory/mcp@0.9.32-daniel.62" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 8c37305878..aae38c806a 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index af77d965b4..27723338c1 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index ae9dfce22b..4f21725ef1 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.61"; +const VERSION = "0.9.32-daniel.62"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 45c37d2a55..22569ddb98 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.61", + "version": "0.9.32-daniel.62", "facts": { "mcpTools": [ "55" diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index ac81245307..87c189a371 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/functions/observe.ts b/src/functions/observe.ts index a506961011..247bfc9ac8 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -189,7 +189,7 @@ export function registerObserveFunction( const livePrompt = submittedPrompt && !backfillPrompt ? submittedPrompt : undefined; const promptRef = durable || typeof payload.eventId !== "string" ? obsId : payload.eventId; - const deferCertification = kv.backend !== "file" || (typeof kv.observationReader?.mutationRevision === "function" && typeof kv.observationReader?.pendingMutations === "function"); + const deferCertification = kv.backend !== "file" || typeof kv.durability?.watchKeys === "function"; let certify: () => Promise = async () => {}; const result = await withKeyedLock(`obs:${payload.sessionId}`, async () => { // A timed-out capture can already be stored; replay must not scan the session again. @@ -395,7 +395,6 @@ export function registerObserveFunction( synthetic = (await kv.get(KV.observations(payload.sessionId), obsId))!; getSearchIndex().add(synthetic); scheduleIndexSave(); - certify = await prepareObservationEmbedding(synthetic.id, synthetic.sessionId, deferCertification); emitLiveEvent({ id: `compressed-${obsId}`, type: "compressed_observation", data: { type: "compressed", observation: withoutObservationSource(synthetic), sessionId: payload.sessionId } }); @@ -405,6 +404,7 @@ export function registerObserveFunction( hook: payload.hookType, compress: autoCompress ? "llm" : "synthetic", }); + certify = await prepareObservationEmbedding(synthetic.id, synthetic.sessionId, deferCertification); return { observationId: obsId }; }); await certify(); diff --git a/src/ops/embedding-recovery.mjs b/src/ops/embedding-recovery.mjs index 93b48dda7f..13fd2d8299 100644 --- a/src/ops/embedding-recovery.mjs +++ b/src/ops/embedding-recovery.mjs @@ -7,7 +7,7 @@ const digest=text=>createHash('sha256').update(text).digest('hex'); export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKeyedLock=async(k,fn)=>fn(),logger,clock=Date.now,schedule=true,onIndexChanged,persistIndex}) { const state={pendingCount:0,completedCount:0,counterEpoch:randomUUID(),initialized:false,lastError:null,lastSuccessAt:null}; let pumping=false,reconciled=false,stopped=false,interval=null,initialization=null,committedRows=null,committedOffset=0; - const active=new Set(),publications=new Map(),accepted=new Map(),pendingIds=new Set(); + const active=new Set(),sourceGuards=new Set(),publications=new Map(),accepted=new Map(),pendingIds=new Set(); // Historical proof observed by this worker, never a fresh disk-verification cache. const observedPublications=new Map(); let publicationObservations=0,publicationEvidenceEvicted=0,publicationEvidenceUnavailable=0,publicationEvidenceAvailable=true; @@ -65,16 +65,18 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe })); } function prepareEnqueue(item){ - if(kv.backend==='file'&&(typeof kv.observationReader?.mutationRevision!=='function'||typeof kv.observationReader?.pendingMutations!=='function'))return Promise.reject(Object.assign(Error('embedding_source_guard_unavailable'),{code:'EMBEDDING_SOURCE_GUARD_UNAVAILABLE'})); + if(kv.backend==='file'&&typeof kv.durability?.watchKeys!=='function')return Promise.reject(Object.assign(Error('embedding_source_guard_unavailable'),{code:'EMBEDDING_SOURCE_GUARD_UNAVAILABLE'})); if(stopped)return Promise.reject(Object.assign(Error('embedding_recovery_stopped'),{code:'EMBEDDING_RECOVERY_STOPPED'})); return track(withKeyedLock(intentKey(item.id),async()=>{ await initialize(); - const scope=sourceScope(item),revision=()=>kv.observationReader?.mutationRevision?.(scope); - const sourceRevision=revision(); + if(stopped)throw Object.assign(Error('embedding_recovery_stopped'),{code:'EMBEDDING_RECOVERY_STOPPED'}); + const scope=sourceScope(item),guard=kv.backend==='file'?kv.durability.watchKeys([{scope,key:item.id}]):null; + const release=()=>{guard?.release();sourceGuards.delete(release);};sourceGuards.add(release); + try{ const sourceChanged=()=>Object.assign(Error('embedding_source_changed'),{code:'EMBEDDING_SOURCE_CHANGED'}); async function checkSource(){ const row=await kv.get(scope,item.id); - if(kv.observationReader?.pendingMutations?.(scope)||!row||row.id!==item.id||item.kind!=='memory'&&row.sessionId!==item.sessionId||revision()!==sourceRevision)throw sourceChanged(); + if(guard&&!guard.unchanged()||!row||row.id!==item.id||item.kind!=='memory'&&row.sessionId!==item.sessionId)throw sourceChanged(); } await checkSource(); const old=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id); @@ -94,11 +96,14 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe } let certification; return()=>certification??=track((async()=>{ + try{ await withKeyedLock(intentKey(item.id),check); await certifyIntent(item); await withKeyedLock(intentKey(item.id),check); return !old; + }finally{release();} })()); + }catch(error){release();throw error;} })); } function enqueueBatch(items){ @@ -299,7 +304,7 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe finally{pumping=false;} } function pump(){if(stopped)return Promise.resolve();return track(initialize().then(()=>backgroundTask(runPump)()));} - function stop(){stopped=true;if(interval){clearInterval(interval);interval=null;}} + function stop(){stopped=true;for(const release of sourceGuards)release();if(interval){clearInterval(interval);interval=null;}} async function drain(){while(active.size)await Promise.allSettled([...active]);} function start(){if(stopped||interval)return;void track(initialize()).catch(error=>{state.lastError=networkErrorCode(error);});interval=setInterval(()=>void pump().catch(error=>{state.lastError=networkErrorCode(error);logger?.warn('Embedding recovery initialization deferred',{errorCode:state.lastError});}),15000);interval.unref();} if(schedule)start(); diff --git a/src/ops/state-durability.d.mts b/src/ops/state-durability.d.mts index 3840a29edd..2bf58fe6e1 100644 --- a/src/ops/state-durability.d.mts +++ b/src/ops/state-durability.d.mts @@ -7,6 +7,7 @@ export function createStateDurabilityFence(options: { storePath: string; timeout mutate(scope: string, key: string, fn: () => Promise): Promise; keys(): DirtyKey[]; keysFor(keys: DirtyKey[]): DirtyKey[]; + watchKeys(keys: DirtyKey[]): { unchanged(): boolean; release(): void }; forgetKeys(keys: DirtyKey[]): void; stableKeys(options?: { minAgeMs?: number; limit?: number }): DirtyKey[]; wait(kv: Reader): Promise; diff --git a/src/ops/state-durability.mjs b/src/ops/state-durability.mjs index c73b806d56..0bce82c763 100644 --- a/src/ops/state-durability.mjs +++ b/src/ops/state-durability.mjs @@ -29,7 +29,7 @@ export function createStateDurabilityFence({storePath,timeoutMs=15000,pollInterv if(!['sdk','disk'].includes(completion))throw Error('state_completion_invalid'); let sdkCompleted=0,sdkFailed=0; let frozen=false,mutationFailures=0,revision=0,pruning=false,lastVerification=null,pruneSequence=0; - const active=new Set(),touched=new Map(),pruneAttempts=new Map(),revisionObservers=new Map(); + const active=new Set(),mutationKeys=new WeakMap(),touched=new Map(),pruneAttempts=new Map(),revisionObservers=new Map(); const certificates=new Set(),certificateContext=new AsyncLocalStorage(); const measurements=createDurabilityMeasurements(); const readCoordinator=createReadCoordinator({clock}); @@ -43,6 +43,15 @@ export function createStateDurabilityFence({storePath,timeoutMs=15000,pollInterv } return()=>{for(const item of items){const scope=revisionObservers.get(item.scope),keys=scope?.get(item.key);keys?.delete(item);if(!keys?.size)scope?.delete(item.key);if(!scope?.size)revisionObservers.delete(item.scope);}}; } + function watchKeys(selected){ + if(!Array.isArray(selected)||!selected.length||selected.length>200||selected.some(item=>typeof item?.scope!=='string'||typeof item?.key!=='string'))throw Error('state_mutation_selection_invalid'); + const items=selected.map(({scope,key})=>({scope,key,revision:touched.get(scope)?.get(key)?.revision})); + const release=observeRevisions(items); + const pending=[...active].some(promise=>{const pair=mutationKeys.get(promise);return items.some(item=>pair?.scope===item.scope&&pair?.key===item.key);}); + let released=false; + // Observers survive dirty-key pruning; no permanent per-record history is retained. + return {unchanged:()=>!released&&!pending&&items.every(item=>item.observedRevision===item.revision),release(){if(!released){released=true;release();}}}; + } function keys(){return [...touched].flatMap(([scope,items])=>[...items].map(([key,stamp])=>({scope,key,...stamp})));} function keysFor(selected){return selected.map(({scope,key})=>({scope,key,...touched.get(scope)?.get(key)}));} function forgetKeys(selected){for(const {scope,key,revision} of selected){const map=touched.get(scope);if(revision===undefined||map?.get(key)?.revision!==revision)continue;map.delete(key);if(!map.size){touched.delete(scope);pruneAttempts.delete(scope);}}} @@ -52,7 +61,7 @@ export function createStateDurabilityFence({storePath,timeoutMs=15000,pollInterv } function mutate(scope,key,fn){ if(frozen)return Promise.reject(Object.assign(Error('state_mutations_frozen'),{code:'STATE_FROZEN'})); - remember(scope,key);const promise=Promise.resolve().then(fn);active.add(promise); + remember(scope,key);const promise=Promise.resolve().then(fn);mutationKeys.set(promise,{scope,key});active.add(promise); promise.then(()=>{remember(scope,key);active.delete(promise);},()=>{remember(scope,key);active.delete(promise);mutationFailures++;});return promise; } async function drain(){ @@ -243,5 +252,5 @@ export function createStateDurabilityFence({storePath,timeoutMs=15000,pollInterv catch(error){return {success:false,deferred:true,errorCode:typeof error.code==='string'?error.code:'STATE_DURABILITY_UNAVAILABLE',diagnostics:error.diagnostics??null,retained:true};} finally{pruning=false;} } - return {completion,withBulkRead:(work,options)=>readCoordinator.run('bulk',work,options),mutate,keys,keysFor,forgetKeys,stableKeys,flushStable,freeze(){frozen=true;},drain,wait,waitForKeys,waitForKeyGroups,snapshot:()=>({completion,sdkCompletion:completion==='sdk'?{completed:sdkCompleted,failed:sdkFailed}:null,frozen,activeMutations:active.size,touchedScopes:touched.size,mutationFailures,pruning,lastVerification:structuredClone(lastVerification),measurements:completion==='disk'?measurements.snapshot():null,readSharing:readSharing.snapshot(),readCoordination:readCoordinator.snapshot()})}; + return {completion,withBulkRead:(work,options)=>readCoordinator.run('bulk',work,options),mutate,keys,keysFor,watchKeys,forgetKeys,stableKeys,flushStable,freeze(){frozen=true;},drain,wait,waitForKeys,waitForKeyGroups,snapshot:()=>({completion,sdkCompletion:completion==='sdk'?{completed:sdkCompleted,failed:sdkFailed}:null,frozen,activeMutations:active.size,touchedScopes:touched.size,mutationFailures,pruning,lastVerification:structuredClone(lastVerification),measurements:completion==='disk'?measurements.snapshot():null,readSharing:readSharing.snapshot(),readCoordination:readCoordinator.snapshot()})}; } diff --git a/src/types.ts b/src/types.ts index 022faddfc1..2c5f749c80 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index 08a0a80088..3a9e487d77 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.61"; +export const VERSION = "0.9.32-daniel.62"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/embedding-selected-source.test.ts b/test/embedding-selected-source.test.ts new file mode 100644 index 0000000000..8092b87bc1 --- /dev/null +++ b/test/embedding-selected-source.test.ts @@ -0,0 +1,72 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {mkdtemp,rm} from 'node:fs/promises'; +import {tmpdir} from 'node:os'; +import {join} from 'node:path'; +import {StateKV} from '../src/state/kv.js'; +import {KV} from '../src/state/schema.js'; +import {VectorIndex} from '../src/state/vector-index.js'; +import {withKeyedLock} from '../src/state/keyed-mutex.js'; +import {registerEmbeddingRecovery,EMBEDDING_RETRY_NAMESPACE as RETRY} from '../src/ops/embedding-recovery.mjs'; + +const cleanups:Array<()=>Promise>=[]; +afterEach(async()=>{vi.unstubAllEnvs();for(const cleanup of cleanups.splice(0))await cleanup();vi.restoreAllMocks();}); +async function fixture(){ + const dir=await mkdtemp(join(tmpdir(),'am-selected-source-'));vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH',dir); + const rows=new Map>();let heldKey:string|undefined,started!:()=>void,resolve!:()=>void,reject!:(error:Error)=>void; + const entered=new Promise(yes=>started=yes),gate=new Promise((yes,no)=>{resolve=yes;reject=no;});void gate.catch(()=>{}); + const sdk={trigger:async({function_id,payload:p}:any)=>{ + const table=rows.get(p.scope); + if(function_id==='state::get')return structuredClone(table?.get(p.key)??null); + if(function_id==='state::list')return structuredClone([...table?.values()??[]]); + if(function_id==='state::set'){ + if(!rows.has(p.scope))rows.set(p.scope,new Map());rows.get(p.scope)!.set(p.key,structuredClone(p.value)); + if(p.key===heldKey){started();await gate;}return p.value; + } + if(function_id==='state::delete')return table?.delete(p.key)??false; + throw Error('unexpected synthetic SDK call'); + }}; + const kv=new StateKV(sdk as never),provider={name:'synthetic',dimensions:2,embed:vi.fn(async()=>new Float32Array([1,0]))}; + const worker=registerEmbeddingRecovery({kv,KV,index:new VectorIndex(),provider,withKeyedLock,schedule:false,persistIndex:async()=>{}}); + cleanups.push(async()=>{resolve();worker.stop();await worker.drain();await kv.durability!.drain();await rm(dir,{recursive:true,force:true});}); + const item={id:'selected',sessionId:'shared-session',kind:'synthetic' as const},scope=KV.observations(item.sessionId),row={id:item.id,sessionId:item.sessionId,title:'selected original',sourceRaw:{raw:'synthetic original'}}; + await kv.set(scope,item.id,row); + return{kv,worker,provider,item,scope,row,entered,resolve,reject,hold:(key:string)=>{heldKey=key;}}; +} + +it.each([false,true])('certifies a selected source with another same-session applied SDK write starting beforePrepare=%s',async beforePrepare=>{ + const f=await fixture();f.hold('other'); + let other:Promise|undefined;if(beforePrepare){other=f.kv.set(f.scope,'other',{id:'other',sessionId:f.item.sessionId});await f.entered;} + const certify=await f.worker.prepareEnqueue(f.item); + if(!other){other=f.kv.set(f.scope,'other',{id:'other',sessionId:f.item.sessionId});await f.entered;} + let completed=false;const pending=certify().then(value=>{completed=true;return value;});void pending.catch(()=>{}); + await new Promise(resolve=>setTimeout(resolve,10));expect(completed).toBe(false); + f.resolve();await other;await expect(pending).resolves.toBe(true);expect(await f.kv.get(f.scope,f.item.id)).toEqual(f.row); + expect(await f.kv.get(RETRY,f.item.id)).toMatchObject({id:f.item.id});expect(f.provider.embed).not.toHaveBeenCalled(); +}); + +it('refuses same-key ABA even when the final SDK row equals the original',async()=>{ + const f=await fixture(),certify=await f.worker.prepareEnqueue(f.item); + await f.kv.set(f.scope,f.item.id,{...f.row,title:'replacement'});await f.kv.delete(f.scope,f.item.id);await f.kv.set(f.scope,f.item.id,f.row); + await expect(certify()).rejects.toMatchObject({code:'EMBEDDING_SOURCE_CHANGED'});expect(await f.kv.get(f.scope,f.item.id)).toEqual(f.row); +}); + +it('refuses an unrelated uncertain SDK outcome without confusing it with target mutation',async()=>{ + const f=await fixture(),certify=await f.worker.prepareEnqueue(f.item);f.hold('other'); + const other=f.kv.set(f.scope,'other',{id:'other',sessionId:f.item.sessionId});void other.catch(()=>{});await f.entered; + const pending=certify();void pending.catch(()=>{});await new Promise(resolve=>setTimeout(resolve,10));f.reject(Error('synthetic lost response')); + await expect(other).rejects.toThrow('synthetic lost response');await expect(pending).rejects.toMatchObject({code:'STATE_DURABILITY_TIMEOUT',diagnostics:{errorCode:'SDK_MUTATION_UNCERTAIN'}}); + expect(f.kv.mutationOutcomeUncertain).toBe(true);expect(await f.kv.get(f.scope,f.item.id)).toEqual(f.row);expect(await f.kv.get(RETRY,f.item.id)).not.toBeNull(); +}); + +it.each(['success','prepareFailure','fenceFailure','stopped'] as const)('releases the selected mutation watch after %s',async outcome=>{ + const f=await fixture(),fence=f.kv.durability!,original=fence.watchKeys;let live=0; + vi.spyOn(fence,'watchKeys').mockImplementation(keys=>{const watch=original(keys);live++;let released=false;return{unchanged:watch.unchanged,release(){if(!released){released=true;live--;}watch.release();}};}); + if(outcome==='prepareFailure'){await f.kv.delete(f.scope,f.item.id);await expect(f.worker.prepareEnqueue(f.item)).rejects.toMatchObject({code:'EMBEDDING_SOURCE_CHANGED'});} + else{ + const certify=await f.worker.prepareEnqueue(f.item);expect(live).toBe(1); + if(outcome==='stopped'){f.worker.stop();expect(live).toBe(0);await expect(certify()).rejects.toMatchObject({code:'EMBEDDING_RECOVERY_STOPPED'});} + else if(outcome==='fenceFailure'){vi.spyOn(fence,'waitForKeys').mockRejectedValue(Object.assign(Error('synthetic missing fence'),{code:'EMBEDDING_FENCE_UNAVAILABLE'}));await expect(certify()).rejects.toMatchObject({code:'EMBEDDING_FENCE_UNAVAILABLE'});} + else await expect(certify()).resolves.toBe(true); + } + expect(live).toBe(0); +}); diff --git a/test/helpers/storage-unit-adapter.ts b/test/helpers/storage-unit-adapter.ts index 1fc1b5740c..8789e95800 100644 --- a/test/helpers/storage-unit-adapter.ts +++ b/test/helpers/storage-unit-adapter.ts @@ -12,7 +12,7 @@ export function createStorageUnitAdapter(physical:StateKV,logicalScopes:string[] const fence=new Proxy(rawFence,{get(target,property){ if(property==='waitForKeys')return(_kv:unknown,rows:any[],...options:any[])=>target.waitForKeys(physical,selections(rows),...options); if(property==='waitForKeyGroups')return(_kv:unknown,groups:any[][],...options:any[])=>target.waitForKeyGroups(physical,groups.map(selections),...options); - if(property==='keysFor')return(rows:any[])=>target.keysFor(selections(rows)); + if(property==='keysFor'||property==='watchKeys')return(rows:any[])=>(target[property] as any)(selections(rows)); const value=Reflect.get(target,property);return typeof value==='function'?value.bind(target):value; }}); const reader=physical.observationReader; diff --git a/test/observation-certification-lock.test.ts b/test/observation-certification-lock.test.ts index d322c45ddf..ce807ac5e7 100644 --- a/test/observation-certification-lock.test.ts +++ b/test/observation-certification-lock.test.ts @@ -8,14 +8,16 @@ import {registerObserveFunction} from '../src/functions/observe.js'; import {withKeyedLock} from '../src/state/keyed-mutex.js'; import {finishLongSession} from '../src/ops/long-session.mjs'; import {registerEmbeddingRecovery,EMBEDDING_RETRY_NAMESPACE as RETRY} from '../src/ops/embedding-recovery.mjs'; +import {createStateDurabilityFence} from '../src/ops/state-durability.mjs'; vi.mock('../src/logger.js',()=>({logger:{info:vi.fn(),warn:vi.fn(),error:vi.fn()}})); const workers:ReturnType[]=[]; afterEach(async()=>{for(const w of workers.splice(0)){w.stop();await w.drain();}search.setEmbeddingRecovery(null);search.setVectorIndex(null);search.setEmbeddingProvider(null);}); function fixture(){ const kv=mockKV(),index=new VectorIndex(),provider={name:'synthetic',dimensions:2,embed:vi.fn(async()=>new Float32Array([1,0]))}; let release!:()=>void,entered=false;const gate=new Promise(resolve=>release=resolve); - let mutation=0;for(const method of ['set','delete','update'] as const){const original=kv[method];(kv as any)[method]=async(scope:string,...args:any[])=>{if(scope.startsWith('mem:obs:'))mutation++;return(original as any)(scope,...args);};} - Object.assign(kv,{observationReader:{mutationRevision:()=>mutation,pendingMutations:()=>0,captureSummary:async(scope:string,excludeId:string)=>{const rows:any[]=await kv.list(scope);const entries=rows.filter(r=>r.id!==excludeId).map(observationBudgetEntry);return{count:rows.length,summaryCount:entries.length,summaryBytes:entries.reduce((n,r)=>n+r.summaryBytes,0),sourceBytes:entries.reduce((n,r)=>n+r.sourceBytes,0)};}},backend:'file',durability:{waitForKeys:async()=>{entered=true;await gate;return{synced:true};}}}); + const mutationFence=createStateDurabilityFence({storePath:'/tmp/synthetic-certification',completion:'sdk'}); + for(const method of ['set','delete','update'] as const){const original=kv[method];(kv as any)[method]=async(scope:string,key:string,...args:any[])=>mutationFence.mutate(scope,key,()=>(original as any)(scope,key,...args));} + Object.assign(kv,{observationReader:{captureSummary:async(scope:string,excludeId:string)=>{const rows:any[]=await kv.list(scope);const entries=rows.filter(r=>r.id!==excludeId).map(observationBudgetEntry);return{count:rows.length,summaryCount:entries.length,summaryBytes:entries.reduce((n,r)=>n+r.summaryBytes,0),sourceBytes:entries.reduce((n,r)=>n+r.sourceBytes,0)};}},backend:'file',durability:{...mutationFence,waitForKeys:async()=>{entered=true;await gate;return{synced:true};}}}); const recovery=registerEmbeddingRecovery({kv:kv as never,KV,index,provider,withKeyedLock,schedule:false,persistIndex:async()=>{}});workers.push(recovery); search.setVectorIndex(index);search.setEmbeddingProvider(provider);search.setEmbeddingRecovery(recovery); const sdk=mockSdk({looseTrigger:true});registerObserveFunction(sdk as never,kv as never); @@ -159,7 +161,31 @@ for(const beginBeforePrepare of [false,true])it(`invalidates a certificate when }finally{worker.stop();await worker.drain();vi.unstubAllEnvs();await rm(dir,{recursive:true,force:true});} }); it('refuses unsafe deferred file certification without a mutation guard',async()=>{ - const f=fixture();delete(f.kv as any).observationReader; + const f=fixture();delete(f.kv as any).durability.watchKeys; const item={id:f.payload.observationId,sessionId:f.payload.sessionId,kind:'synthetic' as const};await f.kv.set(KV.observations(item.sessionId),item.id,{id:item.id,sessionId:item.sessionId,title:'canonical',facts:[],concepts:[],files:[]}); await expect(f.recovery.prepareEnqueue(item)).rejects.toMatchObject({code:'EMBEDDING_SOURCE_GUARD_UNAVAILABLE'});f.release(); }); + +it('certifies its unchanged observation while another observation in the same session is written',async()=>{ + const f=fixture(),item={id:f.payload.observationId,sessionId:f.payload.sessionId,kind:'synthetic' as const}; + await f.kv.set(KV.observations(item.sessionId),item.id,{id:item.id,sessionId:item.sessionId,title:'selected'}); + const certify=await f.recovery.prepareEnqueue(item),pending=certify();void pending.catch(()=>{});await vi.waitFor(()=>expect(f.entered()).toBe(true)); + await f.kv.set(KV.observations(item.sessionId),'obs_other',{id:'obs_other',sessionId:item.sessionId,title:'unrelated'});f.release(); + await expect(pending).resolves.toBe(true);expect(await f.kv.get(RETRY,item.id)).toMatchObject({id:item.id}); + expect(f.provider.embed).not.toHaveBeenCalled(); +}); + +it('preserves the source and inbox without leaking a watch on live-event failure, then retries',async()=>{ + const f=fixture(),fence=(f.kv as any).durability,watchKeys=fence.watchKeys;let live=0; + const watched=vi.spyOn(fence,'watchKeys').mockImplementation((keys:any)=>{const watch=watchKeys(keys);live++;let released=false;return{unchanged:watch.unchanged,release(){if(!released){released=true;live--;}watch.release();}};}); + const {liveEvents}=await import('../src/viewer/live-events.js'),original=liveEvents.emit; + const emit=vi.spyOn(liveEvents,'emit').mockImplementation(function(event){if(event.type==='compressed_observation')throw Error('synthetic live writer failed');return original.call(liveEvents,event);}); + const {registerCaptureFunctions}=await import('../src/functions/capture.js'),sdk=mockSdk({looseTrigger:true});registerObserveFunction(sdk as never,f.kv as never);const capture=registerCaptureFunctions(sdk as never,f.kv as never); + f.release(); + try{ + const failed:any=await sdk.trigger('mem::capture',{payload:f.payload,eventId:f.payload.eventId});expect(failed.state).toBe('retrying'); + expect(await f.kv.list(KV.captureInbox)).toHaveLength(1);expect(await f.kv.list(KV.observations(f.payload.sessionId))).toHaveLength(1);expect(live).toBe(0); + emit.mockRestore();expect(await sdk.trigger('mem::observe',{...f.payload,observationId:failed.observationId})).toMatchObject({existing:true,observationId:failed.observationId}); + expect(await f.kv.get(RETRY,failed.observationId)).not.toBeNull();expect(await f.kv.list(KV.observations(f.payload.sessionId))).toHaveLength(1);expect(live).toBe(0); + }finally{emit.mockRestore();watched.mockRestore();capture.stop();await capture.drain();} +}); diff --git a/test/state-durability-key-watch.test.ts b/test/state-durability-key-watch.test.ts new file mode 100644 index 0000000000..5e977fc857 --- /dev/null +++ b/test/state-durability-key-watch.test.ts @@ -0,0 +1,27 @@ +import {expect,it} from 'vitest'; +import {createStateDurabilityFence} from '../src/ops/state-durability.mjs'; + +const selected=[{scope:'mem:obs:synthetic',key:'selected'}]; +const fixture=()=>createStateDurabilityFence({storePath:'/tmp/synthetic-key-watch',completion:'sdk'}); + +it('ignores unrelated keys and dirty-key pruning while observing the selected key',async()=>{ + const fence=fixture();await fence.mutate(selected[0].scope,selected[0].key,async()=>{}); + const watch=fence.watchKeys(selected); + await fence.mutate(selected[0].scope,'other',async()=>{});fence.forgetKeys(fence.keysFor(selected)); + expect(watch.unchanged()).toBe(true);watch.release();expect(watch.unchanged()).toBe(false);watch.release(); +}); +it('rejects selected mutations that begin before or after watch registration including ABA',async()=>{ + for(const startBefore of [false,true]){ + const fence=fixture();let release!:()=>void;const gate=new Promise(resolve=>release=resolve); + const before=startBefore?fence.mutate(selected[0].scope,selected[0].key,()=>gate):null; + const watch=fence.watchKeys(selected),pending=before??fence.mutate(selected[0].scope,selected[0].key,()=>gate); + expect(watch.unchanged()).toBe(false);release();await pending; + await fence.mutate(selected[0].scope,selected[0].key,async()=>{});expect(watch.unchanged()).toBe(false);watch.release(); + } +}); +it('ignores an unrelated pending key without hiding its uncertain SDK outcome',async()=>{ + const fence=fixture();let reject!:(error:Error)=>void; + const pending=fence.mutate(selected[0].scope,'other',()=>new Promise((_,no)=>reject=no));void pending.catch(()=>{}); + const watch=fence.watchKeys(selected);expect(watch.unchanged()).toBe(true);await Promise.resolve();reject(Error('lost response'));await expect(pending).rejects.toThrow('lost response'); + expect(watch.unchanged()).toBe(true);await expect(fence.waitForKeys({get:async()=>({id:'selected'})},selected)).rejects.toMatchObject({code:'SDK_MUTATION_UNCERTAIN'});watch.release(); +}); From c8a7014d4c813173772c229599e5705d8866808a Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 7 Nov 2026 19:23:48 +0900 Subject: [PATCH 07/23] fix(capture): bound SDK handoff deadlines and advance embedding backlog --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 6 +- CHANGELOG.md | 7 + assets/tags/light/stat-tests.svg | 4 +- assets/tags/stat-tests.svg | 4 +- docs/customizations/CAPTURE-THROUGHPUT-63.md | 11 + integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/_capture.mjs | 258 +++++++++++-------- plugin/scripts/codex-compat/_capture.mjs | 258 +++++++++++-------- plugin/scripts/codex-compat/manifest.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 4 +- src/capture/sdk-delivery-v2.ts | 20 +- src/capture/sdk-spool-v2.ts | 105 +++++--- src/functions/export-import.ts | 2 +- src/hooks/_capture.ts | 8 +- src/ops/embedding-recovery.mjs | 56 +++- src/types.ts | 2 +- src/version.ts | 2 +- test/embedding-scheduling.test.ts | 117 +++++++++ test/helpers/sdk-deadline-worker.mjs | 20 ++ test/helpers/sdk-native-deadline-preload.mjs | 40 +++ test/sdk-capture-deadline.test.ts | 118 +++++++++ test/sdk-native-deadline.test.ts | 32 +++ test/sdk-v2-transport-safety.test.ts | 4 +- 36 files changed, 810 insertions(+), 302 deletions(-) create mode 100644 docs/customizations/CAPTURE-THROUGHPUT-63.md create mode 100644 test/embedding-scheduling.test.ts create mode 100644 test/helpers/sdk-deadline-worker.mjs create mode 100644 test/helpers/sdk-native-deadline-preload.mjs create mode 100644 test/sdk-capture-deadline.test.ts create mode 100644 test/sdk-native-deadline.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 346db5ca1f..72dfdbd83b 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 1f7a4afc8d..02b348127c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,20 +108,20 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Testing -- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (6,400+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests. +- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (6,500+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests. - Before any npm publish: `npm run release:gate` must pass. It installs the packed tarballs into a clean home and runs capture, recovery, restart, export/import, MCP and status checks against the installed CLI (see CONTRIBUTING.md, Release process) - Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list` - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.62) +## Current Stats (v0.9.32-daniel.63) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 17 skills - 355+ iii functions -- 6,400+ tests +- 6,500+ tests ## Personal fork verification isolation diff --git a/CHANGELOG.md b/CHANGELOG.md index 557f5bec84..191a333563 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## [Unreleased] +## [0.9.32-daniel.63] — 2026-11-07 +- Keep fresh SDK-v2 source retention and reference admission under one lease. Share the native hook's original deadline across lock acquisition and transport, reserving 750ms for final state recording. Preserve retained-source acknowledgement if reference admission fails, retain the default 150ms lock contract without an explicit deadline, and leave exhausted pending work queued before any send. Unknown transport outcomes remain held; existing held/sending records never become a successful pending result merely because time ran out. +- Claim and read the selected body under the same lease, preserving source hashing and owner fencing. No spool schema, quota, original-retention, automatic unknown-send retry or host trust changes. The source/reference publication gap under an OS crash and unbounded kernel filesystem latency are not eliminated. +- Continue successful embedding batches after a one-second yield, only after that batch's publication has settled and other due work remains. Keep batch size five, shared model serialization, existing retry/backoff and 15-second idle/error cadence; rotate attempts so failing head items cannot starve later intents. The publication bound applies to this pump, not to the existing independent add API. +- Reproduced the client lock/deadline failures and scheduler idle/starvation before changes. Client focused95 and independent22 tests, scheduler focused51 and independent13 tests passed in isolated homes. All39 sequential build configurations and SDK/skills/docs checks passed; TypeScript matches the30 existing .62 diagnostics. The ordinary suite passed6,515 with13 conditional skips; its unchanged12GiB SDK boundary fixture refused to start with8.77GB available. This environment limitation and operational rollout are recorded separately in `docs/customizations/CAPTURE-THROUGHPUT-63.md`; production remains on .62b and manual long-term-memory review is pending. + ## [0.9.32-daniel.62] — 2026-11-07 - Fix deferred observation embedding certification rejecting an unchanged source when another observation in the same session is written. Reuse the existing durability fence's per-key revision observers, including already pending mutations, and release each selected watch after certification, failure or worker stop. Preserve source replacement/deletion/ABA, intent-generation, missing-fence and uncertain SDK outcome refusals. - Base the .62 server preparation on .61 commit `f8246e56eb666ef0f9cefa9135ccbe4df5b9deb6`. Keep the .61 client queue repair, server mutation fencing and batch/publication scheduling unchanged. Acquire the new-capture watch after viewer/logging side effects so failed display handling preserves the source/inbox without leaking an unstarted watch. The false rejection and lifecycle failure were reproduced before their fixes; focused mutation/fence/capture regression, all39 sequential build configurations, SDK audit, skills/docs checks and independent review passed. The30 TypeScript diagnostics exactly match .61. See `docs/customizations/EMBEDDING-SOURCE-GUARD-62.md`; operational application and manual long-term-memory review remain separate. @@ -588,6 +594,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.63]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.62...v0.9.32-daniel.63 [0.9.32-daniel.62]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.61...v0.9.32-daniel.62 [0.9.32-daniel.61]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.60...v0.9.32-daniel.61 [0.9.32-daniel.60]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.59...v0.9.32-daniel.60 diff --git a/assets/tags/light/stat-tests.svg b/assets/tags/light/stat-tests.svg index dd258f45c7..4a61a40e77 100644 --- a/assets/tags/light/stat-tests.svg +++ b/assets/tags/light/stat-tests.svg @@ -1,5 +1,5 @@ - + - 6400+ + 6500+ TESTS PASSING diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg index 92b7fab072..4bd2297abb 100644 --- a/assets/tags/stat-tests.svg +++ b/assets/tags/stat-tests.svg @@ -1,5 +1,5 @@ - + - 6400+ + 6500+ TESTS PASSING diff --git a/docs/customizations/CAPTURE-THROUGHPUT-63.md b/docs/customizations/CAPTURE-THROUGHPUT-63.md new file mode 100644 index 0000000000..9706726671 --- /dev/null +++ b/docs/customizations/CAPTURE-THROUGHPUT-63.md @@ -0,0 +1,11 @@ +# Ubuntu collection handoff and embedding backlog progress (.63) + +Prepared from .62 commit `59dbc72fe7a2f87c6c6991e403896f3b3a1d7803`. The .62b production finalization and one official resume succeeded. Subsequent inspection found a fresh raw-only source absent on the server and a fresh unknown-send source already present there. These are different outcomes; neither is a reason for blind replay. + +The fixed .61 native SDK code reproduced both failure mechanisms in synthetic processes: source retention followed by a separately contended 150ms enqueue lock leaves no drainable reference; a 3s transport budget starting after local preparation can outlive the hook's 3.5s exit cap. Production quota scans took roughly132–138ms, but synthetic timing injections do not prove the exact historical cause of any selected original. + +Fresh delivery now reuses the source and queue primitives within one lease. Source success survives a later queue failure in the returned evidence. The native hook passes its original absolute deadline through lock acquisition and HTTP, reserves750ms for state recording, and keeps an unsent pending reference pending when the send budget expires. Source verification and the claim occur together. Default standalone lock waits remain150ms; strict SDK ACK, owner fencing, quotas, original retention, held/unknown-send refusal and explicit recovery semantics remain. No record migration or automatic replay of old holds/raw-only sources is introduced. A crash between two filesystem publications can still leave retained raw-only evidence; synchronous filesystem stalls can still overrun a time budget. + +The embedding recovery pump previously selected at most5 entries each15s even when all work finished immediately. Failed head entries could repeatedly exclude later work. The new scheduler rotates process-local pending IDs, awaits only its own round's publications, and schedules the next round after1s when the entire selection completed and more due work was observed. Failure, provider waiting, paused admission and future-only queues retain15s/backoff behavior. The existing shared model lock keeps inference serial and lets waiting chat enter between individual embeddings. External add() publication behavior is unchanged; the pump itself adds at most5 unpublished entries per round. + +Focused client95/95 and independent22/22; scheduler51/51 and independent13/13 passed. Actual synthetic native processes exercise fast/slow ACK, timeout-before-exit, two/six concurrent producers, full quota evidence, invalid deadlines and held-state preservation. All39 build configurations passed sequentially, followed by asset copying, the SDK audit, compatibility build, skill generation/check and documentation synchronization/check. TypeScript still reports30 diagnostics with output exactly equal to the .62 baseline. The ordinary suite (default forks, two workers, isolated real HOME) reported6,515 passed,13 conditional skips and one environment-precondition failure: the unchanged summary SDK boundary fixture requires12GiB available before starting, but observed8,768,102,400B. Its actual boundary scenario did not start; neither a complete-suite pass nor a fresh boundary pass is claimed. The separate service integration suite was not run. Runtime server/client code, root-owned deployment witnesses, hook trust and historical writes are separate acceptance boundaries. Windows remains deferred at the user's request. Manual long-term-memory recording is pending. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 4bbec6c05d..7e9ca07423 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.62 +version: 0.9.32-daniel.63 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index c5910357c2..36c087e0b7 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index a88354b7ac..aaef442c8e 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index eb54d5a659..822a07cb20 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index 34ff0187a0..c285c3f734 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.62 +version: 0.9.32-daniel.63 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 26bb8fa6b9..9ef12b2a57 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index a373a1736c..4e66b0db6d 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.62" + "@agentmemory/agentmemory": "0.9.32-daniel.63" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 38632c8120..783edbe3bd 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index eace8e113c..1f54bde61a 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index d0450e3afa..aab5869967 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.62" + "@agentmemory/mcp@0.9.32-daniel.63" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index aae38c806a..93a0a93dd1 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 27723338c1..11677d4082 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/_capture.mjs b/plugin/scripts/_capture.mjs index 7a6cb067a7..49fbc4a051 100644 --- a/plugin/scripts/_capture.mjs +++ b/plugin/scripts/_capture.mjs @@ -157,6 +157,7 @@ var SdkSpoolV2 = class { maxInputBytes; chunkBytes; onPhase; + deadline; constructor(options = {}) { const path = options.dir ?? process.env.AGENTMEMORY_SDK_CAPTURE_V2_DIR ?? join(homedir(), ".local", "share", "agentmemory", "capture-spool-sdk-v2"); if (!isAbsolute(path)) fail("STORE_OPTIONS_INVALID"); @@ -170,6 +171,8 @@ var SdkSpoolV2 = class { this.maxInputBytes = limit(options.maxInputBytes, INPUT_LIMIT); this.chunkBytes = limit(options.chunkBytes, CHUNK_LIMIT); this.onPhase = options.onPhase; + if (options.deadline !== void 0 && (!Number.isFinite(options.deadline) || options.deadline < 0)) fail("STORE_OPTIONS_INVALID"); + this.deadline = options.deadline; } phase(name) { this.onPhase?.(name); @@ -215,6 +218,7 @@ var SdkSpoolV2 = class { syncDirectory$1(join(path, "..")); } async locked(operation) { + const operationDeadline = this.deadline; let fd; try { if (process.platform !== "linux") fail("STORE_LOCK_UNSUPPORTED"); @@ -223,8 +227,9 @@ var SdkSpoolV2 = class { const stat = fstatSync(fd); privateStat(stat, false); if (stat.size !== 0) fail("STORE_UNSAFE"); - const deadline = performance.now() + 150; + const deadline = operationDeadline ?? performance.now() + 150; while (true) { + if (operationDeadline !== void 0 && performance.now() >= deadline) fail("STORE_BUSY"); const lock = spawnSync("/usr/bin/flock", [ "--exclusive", "--nonblock", @@ -247,6 +252,7 @@ var SdkSpoolV2 = class { } fsyncSync(fd); syncDirectory$1(this.queue); + if (operationDeadline !== void 0 && performance.now() >= deadline) fail("STORE_BUSY"); return operation(); } catch (error) { if (typeof code(error) === "string" && /^(SOURCE_|ORIGINALS_|QUEUE_|STORE_)/.test(code(error))) throw error; @@ -300,7 +306,7 @@ var SdkSpoolV2 = class { fail("SOURCE_UNVERIFIED"); } } - async retain(target, eventId, body) { + prepareSource(target, eventId, body) { let normalized; let bytes; try { @@ -311,79 +317,114 @@ var SdkSpoolV2 = class { fail("SOURCE_UNVERIFIED"); } if (bytes.length > this.maxInputBytes) fail("SOURCE_TOO_LARGE"); - return this.locked(() => { - let sourceId = this.key(target, eventId); - let conflict = false; + return { + normalized, + bytes + }; + } + retainSource(target, eventId, normalized, bytes) { + let sourceId = this.key(target, eventId); + let conflict = false; + try { + lstatSync(join(this.originals, sourceId)); + const prior = this.source(target, sourceId); + if (sameSource(prior.body, normalized)) return { + sourceId, + duplicate: true, + conflict: false, + completed: prior.manifest.completed, + body: prior.body + }; + conflict = true; + sourceId = this.conflictKey(target, eventId, normalized); try { lstatSync(join(this.originals, sourceId)); - const prior = this.source(target, sourceId); - if (sameSource(prior.body, normalized)) return { + const priorConflict = this.source(target, sourceId); + if (!priorConflict.manifest.conflict || !sameSource(priorConflict.body, normalized)) fail("SOURCE_UNVERIFIED"); + return { sourceId, duplicate: true, - conflict: false, - completed: prior.manifest.completed, - body: prior.body + conflict: true, + completed: false, + body: priorConflict.body }; - conflict = true; - sourceId = this.conflictKey(target, eventId, normalized); - try { - lstatSync(join(this.originals, sourceId)); - const priorConflict = this.source(target, sourceId); - if (!priorConflict.manifest.conflict || !sameSource(priorConflict.body, normalized)) fail("SOURCE_UNVERIFIED"); - return { - sourceId, - duplicate: true, - conflict: true, - completed: false, - body: priorConflict.body - }; - } catch (error) { - if (code(error) !== "ENOENT") throw error; - } } catch (error) { if (code(error) !== "ENOENT") throw error; } - const chunks = []; - for (let offset = 0; offset < bytes.length; offset += this.chunkBytes) chunks.push(bytes.subarray(offset, offset + this.chunkBytes)); - const manifest = { - v: 2, - sourceId, - targetHash: digest$1(target), - eventId, - bytes: bytes.length, - hash: digest$1(bytes), - chunks: chunks.map((value, index) => ({ - name: String(index).padStart(6, "0") + ".chunk", - bytes: value.length, - hash: digest$1(value) - })), - conflict, - completed: false + } catch (error) { + if (code(error) !== "ENOENT") throw error; + } + const chunks = []; + for (let offset = 0; offset < bytes.length; offset += this.chunkBytes) chunks.push(bytes.subarray(offset, offset + this.chunkBytes)); + const manifest = { + v: 2, + sourceId, + targetHash: digest$1(target), + eventId, + bytes: bytes.length, + hash: digest$1(bytes), + chunks: chunks.map((value, index) => ({ + name: String(index).padStart(6, "0") + ".chunk", + bytes: value.length, + hash: digest$1(value) + })), + conflict, + completed: false + }; + const manifestBytes = canonical$1(manifest); + if (Buffer.byteLength(manifestBytes) > 64 * 1024) fail("SOURCE_TOO_LARGE"); + this.budget("original", BLOCK + charge((chunks.length + 1) * 256) + charge(Buffer.byteLength(manifestBytes)) + chunks.reduce((sum, value) => sum + charge(value.length), 0)); + const stage = join(this.originals, ".stage-" + randomUUID()); + mkdirSync(stage, { mode: 448 }); + syncDirectory$1(this.originals); + for (let index = 0; index < chunks.length; index++) { + this.writeFile(join(stage, manifest.chunks[index].name), chunks[index]); + this.phase("chunk_fsynced"); + } + this.writeFile(join(stage, "manifest.json"), manifestBytes); + this.phase("manifest_fsynced"); + syncDirectory$1(stage); + this.phase("source_before_publish"); + renameSync(stage, join(this.originals, sourceId)); + syncDirectory$1(this.originals); + this.phase("source_published"); + const verified = this.source(target, sourceId); + return { + sourceId, + duplicate: false, + conflict, + completed: false, + body: verified.body + }; + } + async retain(target, eventId, body) { + const { normalized, bytes } = this.prepareSource(target, eventId, body); + return this.locked(() => this.retainSource(target, eventId, normalized, bytes)); + } + async retainAndEnqueue(target, eventId, body) { + const { normalized, bytes } = this.prepareSource(target, eventId, body); + return this.locked(() => { + const retained = this.retainSource(target, eventId, normalized, bytes); + if (retained.conflict) return { + retained, + referenceAcknowledged: false + }; + if (retained.completed) return { + retained, + referenceAcknowledged: true }; - const manifestBytes = canonical$1(manifest); - if (Buffer.byteLength(manifestBytes) > 64 * 1024) fail("SOURCE_TOO_LARGE"); - this.budget("original", BLOCK + charge((chunks.length + 1) * 256) + charge(Buffer.byteLength(manifestBytes)) + chunks.reduce((sum, value) => sum + charge(value.length), 0)); - const stage = join(this.originals, ".stage-" + randomUUID()); - mkdirSync(stage, { mode: 448 }); - syncDirectory$1(this.originals); - for (let index = 0; index < chunks.length; index++) { - this.writeFile(join(stage, manifest.chunks[index].name), chunks[index]); - this.phase("chunk_fsynced"); + try { + this.enqueueSource(target, retained.sourceId); + } catch (error) { + return { + retained, + referenceAcknowledged: false, + error + }; } - this.writeFile(join(stage, "manifest.json"), manifestBytes); - this.phase("manifest_fsynced"); - syncDirectory$1(stage); - this.phase("source_before_publish"); - renameSync(stage, join(this.originals, sourceId)); - syncDirectory$1(this.originals); - this.phase("source_published"); - const verified = this.source(target, sourceId); return { - sourceId, - duplicate: false, - conflict, - completed: false, - body: verified.body + retained, + referenceAcknowledged: true }; }); } @@ -413,26 +454,27 @@ var SdkSpoolV2 = class { this.atomicJson(this.refPath(ref.sourceId), ref, "queue", void 0, transition); this.phase("reference_published"); } + enqueueSource(target, sourceId) { + const { manifest } = this.source(target, sourceId); + if (manifest.conflict) fail("SOURCE_CONFLICT"); + if (manifest.completed) return; + try { + this.readRef(target, sourceId); + return; + } catch (error) { + if (code(error) !== "ENOENT") throw error; + } + this.writeRef({ + v: 2, + targetHash: digest$1(target), + sourceId, + state: "pending", + attempts: 0, + nextAttemptAt: 0 + }, false); + } async enqueue(target, sourceId) { - return this.locked(() => { - const { manifest } = this.source(target, sourceId); - if (manifest.conflict) fail("SOURCE_CONFLICT"); - if (manifest.completed) return; - try { - this.readRef(target, sourceId); - return; - } catch (error) { - if (code(error) !== "ENOENT") throw error; - } - this.writeRef({ - v: 2, - targetHash: digest$1(target), - sourceId, - state: "pending", - attempts: 0, - nextAttemptAt: 0 - }, false); - }); + return this.locked(() => this.enqueueSource(target, sourceId)); } async pending(target) { return this.locked(() => { @@ -462,6 +504,13 @@ var SdkSpoolV2 = class { }); } async markSending(target, sourceId, expectedHeldSource) { + await this.claimSource(target, sourceId, expectedHeldSource); + } + async claimForSend(target, sourceId, sendDeadline) { + return this.claimSource(target, sourceId, void 0, sendDeadline); + } + async claimSource(target, sourceId, expectedHeldSource, sendDeadline) { + if (sendDeadline !== void 0 && !Number.isFinite(sendDeadline)) fail("STORE_OPTIONS_INVALID"); return this.locked(() => { const source = this.source(target, sourceId); if (source.manifest.conflict || source.manifest.completed) fail("SOURCE_HELD"); @@ -481,10 +530,12 @@ var SdkSpoolV2 = class { } const owner = ownerIdentity(); if (!owner) fail("STORE_BUSY"); + if (sendDeadline !== void 0 && performance.now() >= sendDeadline) fail("SOURCE_SEND_BUDGET_EXHAUSTED"); ref.state = "sending"; ref.owner = owner; this.writeRef(ref); this.phase("send_intent_fsynced"); + return source.body; }); } async acknowledge(target, sourceId) { @@ -553,7 +604,8 @@ function safeCode(error) { function createStore(options) { return new SdkSpoolV2({ ...options.storeOptions, - dir: options.dir + dir: options.dir, + deadline: options.deadline }); } function held(code, sourceAcknowledged = true, referenceAcknowledged = true) { @@ -573,23 +625,18 @@ async function park(store, target, sourceId, code) { return held(code); } async function sendReference(store, target, sourceId, post, deadline) { + let body; try { - await store.markSending(target, sourceId); + body = await store.claimForSend(target, sourceId, deadline); } catch (error) { const code = error?.code; - if (code === "SOURCE_BACKOFF") return { + if (code === "SOURCE_BACKOFF" || code === "SOURCE_SEND_BUDGET_EXHAUSTED") return { outcome: "spooled", sourceAcknowledged: true, referenceAcknowledged: true }; return held(code === "SOURCE_SENDING" ? "SDK_SEND_IN_PROGRESS_OR_UNCERTAIN" : safeCode(error)); } - let body; - try { - body = await store.load(target, sourceId); - } catch { - return park(store, target, sourceId, "SOURCE_UNVERIFIED"); - } let response; const budget = deadline === void 0 ? void 0 : { deadline, @@ -648,7 +695,7 @@ async function deliverSdkCaptureV2(target, body, post, options = {}) { sourceAcknowledged: false, referenceAcknowledged: false }; - const retained = await store.retain(target, body.eventId, body); + const handoff = await store.retainAndEnqueue(target, body.eventId, body), retained = handoff.retained; sourceId = retained.sourceId; storedBody = retained.body; if (retained.conflict) return held("SOURCE_CONFLICT", true, false); @@ -658,25 +705,21 @@ async function deliverSdkCaptureV2(target, body, post, options = {}) { referenceAcknowledged: true, sdkReplyConfirmed: true }; - } catch (error) { - return { + if (!handoff.referenceAcknowledged) return { outcome: "dropped", - code: safeCode(error), - sourceAcknowledged: false, + code: safeCode(handoff.error), + sourceAcknowledged: true, referenceAcknowledged: false }; - } - try { - await store.enqueue(target, sourceId); } catch (error) { return { outcome: "dropped", code: safeCode(error), - sourceAcknowledged: true, + sourceAcknowledged: false, referenceAcknowledged: false }; } - const sent = await sendReference(store, target, sourceId, post); + const sent = await sendReference(store, target, sourceId, post, options.deadline === void 0 ? void 0 : options.deadline - 750); if (sent.code === "SOURCE_HELD") try { if ((await store.retain(target, storedBody.eventId, storedBody)).completed) return { outcome: "duplicate", @@ -697,7 +740,7 @@ async function drainSdkCapturesV2(target, post, options = {}) { error: void 0 }; const limit = Math.min(8, Math.max(0, options.limit ?? 8)), budget = Math.min(1500, Math.max(0, options.budgetMs ?? 1500)), start = performance.now(); - const deadline = Math.min(options.deadline ?? Infinity, start + budget); + const deadline = Math.min(options.deadline === void 0 ? Infinity : options.deadline - 750, start + budget); try { const store = createStore(options), records = await store.pending(target); for (const ref of records) { @@ -2144,9 +2187,12 @@ async function captureObservationV2(body, timeoutMs) { eventId, captureCompletion: "sdk-v1" })), { scrubKeys: true }); - const options = { dir: process.env["AGENTMEMORY_SDK_CAPTURE_V2_DIR"] }; - const result = await deliverSdkCaptureV2(REST_URL, payload, (b) => postRawV2(b, timeoutMs), options); - const now = performance.now(), deadline = Math.min(started + timeoutMs, now + 250), remaining = Math.floor(deadline - now); + const deadline = started + timeoutMs, options = { + dir: process.env["AGENTMEMORY_SDK_CAPTURE_V2_DIR"], + deadline + }; + const result = await deliverSdkCaptureV2(REST_URL, payload, (b, budget) => postRawV2(b, budget?.remainingMs ?? timeoutMs, budget?.deadline), options); + const now = performance.now(), remaining = Math.floor(Math.min(deadline - 750 - now, 250)); if (body.hookType !== "stop" && (result.outcome === "delivered" || result.outcome === "duplicate") && remaining >= 100) { const backlog = await drainSdkCapturesV2(REST_URL, (b, budget) => postRawV2(b, budget?.remainingMs ?? remaining, budget?.deadline ?? deadline), { ...options, diff --git a/plugin/scripts/codex-compat/_capture.mjs b/plugin/scripts/codex-compat/_capture.mjs index 7a6cb067a7..49fbc4a051 100644 --- a/plugin/scripts/codex-compat/_capture.mjs +++ b/plugin/scripts/codex-compat/_capture.mjs @@ -157,6 +157,7 @@ var SdkSpoolV2 = class { maxInputBytes; chunkBytes; onPhase; + deadline; constructor(options = {}) { const path = options.dir ?? process.env.AGENTMEMORY_SDK_CAPTURE_V2_DIR ?? join(homedir(), ".local", "share", "agentmemory", "capture-spool-sdk-v2"); if (!isAbsolute(path)) fail("STORE_OPTIONS_INVALID"); @@ -170,6 +171,8 @@ var SdkSpoolV2 = class { this.maxInputBytes = limit(options.maxInputBytes, INPUT_LIMIT); this.chunkBytes = limit(options.chunkBytes, CHUNK_LIMIT); this.onPhase = options.onPhase; + if (options.deadline !== void 0 && (!Number.isFinite(options.deadline) || options.deadline < 0)) fail("STORE_OPTIONS_INVALID"); + this.deadline = options.deadline; } phase(name) { this.onPhase?.(name); @@ -215,6 +218,7 @@ var SdkSpoolV2 = class { syncDirectory$1(join(path, "..")); } async locked(operation) { + const operationDeadline = this.deadline; let fd; try { if (process.platform !== "linux") fail("STORE_LOCK_UNSUPPORTED"); @@ -223,8 +227,9 @@ var SdkSpoolV2 = class { const stat = fstatSync(fd); privateStat(stat, false); if (stat.size !== 0) fail("STORE_UNSAFE"); - const deadline = performance.now() + 150; + const deadline = operationDeadline ?? performance.now() + 150; while (true) { + if (operationDeadline !== void 0 && performance.now() >= deadline) fail("STORE_BUSY"); const lock = spawnSync("/usr/bin/flock", [ "--exclusive", "--nonblock", @@ -247,6 +252,7 @@ var SdkSpoolV2 = class { } fsyncSync(fd); syncDirectory$1(this.queue); + if (operationDeadline !== void 0 && performance.now() >= deadline) fail("STORE_BUSY"); return operation(); } catch (error) { if (typeof code(error) === "string" && /^(SOURCE_|ORIGINALS_|QUEUE_|STORE_)/.test(code(error))) throw error; @@ -300,7 +306,7 @@ var SdkSpoolV2 = class { fail("SOURCE_UNVERIFIED"); } } - async retain(target, eventId, body) { + prepareSource(target, eventId, body) { let normalized; let bytes; try { @@ -311,79 +317,114 @@ var SdkSpoolV2 = class { fail("SOURCE_UNVERIFIED"); } if (bytes.length > this.maxInputBytes) fail("SOURCE_TOO_LARGE"); - return this.locked(() => { - let sourceId = this.key(target, eventId); - let conflict = false; + return { + normalized, + bytes + }; + } + retainSource(target, eventId, normalized, bytes) { + let sourceId = this.key(target, eventId); + let conflict = false; + try { + lstatSync(join(this.originals, sourceId)); + const prior = this.source(target, sourceId); + if (sameSource(prior.body, normalized)) return { + sourceId, + duplicate: true, + conflict: false, + completed: prior.manifest.completed, + body: prior.body + }; + conflict = true; + sourceId = this.conflictKey(target, eventId, normalized); try { lstatSync(join(this.originals, sourceId)); - const prior = this.source(target, sourceId); - if (sameSource(prior.body, normalized)) return { + const priorConflict = this.source(target, sourceId); + if (!priorConflict.manifest.conflict || !sameSource(priorConflict.body, normalized)) fail("SOURCE_UNVERIFIED"); + return { sourceId, duplicate: true, - conflict: false, - completed: prior.manifest.completed, - body: prior.body + conflict: true, + completed: false, + body: priorConflict.body }; - conflict = true; - sourceId = this.conflictKey(target, eventId, normalized); - try { - lstatSync(join(this.originals, sourceId)); - const priorConflict = this.source(target, sourceId); - if (!priorConflict.manifest.conflict || !sameSource(priorConflict.body, normalized)) fail("SOURCE_UNVERIFIED"); - return { - sourceId, - duplicate: true, - conflict: true, - completed: false, - body: priorConflict.body - }; - } catch (error) { - if (code(error) !== "ENOENT") throw error; - } } catch (error) { if (code(error) !== "ENOENT") throw error; } - const chunks = []; - for (let offset = 0; offset < bytes.length; offset += this.chunkBytes) chunks.push(bytes.subarray(offset, offset + this.chunkBytes)); - const manifest = { - v: 2, - sourceId, - targetHash: digest$1(target), - eventId, - bytes: bytes.length, - hash: digest$1(bytes), - chunks: chunks.map((value, index) => ({ - name: String(index).padStart(6, "0") + ".chunk", - bytes: value.length, - hash: digest$1(value) - })), - conflict, - completed: false + } catch (error) { + if (code(error) !== "ENOENT") throw error; + } + const chunks = []; + for (let offset = 0; offset < bytes.length; offset += this.chunkBytes) chunks.push(bytes.subarray(offset, offset + this.chunkBytes)); + const manifest = { + v: 2, + sourceId, + targetHash: digest$1(target), + eventId, + bytes: bytes.length, + hash: digest$1(bytes), + chunks: chunks.map((value, index) => ({ + name: String(index).padStart(6, "0") + ".chunk", + bytes: value.length, + hash: digest$1(value) + })), + conflict, + completed: false + }; + const manifestBytes = canonical$1(manifest); + if (Buffer.byteLength(manifestBytes) > 64 * 1024) fail("SOURCE_TOO_LARGE"); + this.budget("original", BLOCK + charge((chunks.length + 1) * 256) + charge(Buffer.byteLength(manifestBytes)) + chunks.reduce((sum, value) => sum + charge(value.length), 0)); + const stage = join(this.originals, ".stage-" + randomUUID()); + mkdirSync(stage, { mode: 448 }); + syncDirectory$1(this.originals); + for (let index = 0; index < chunks.length; index++) { + this.writeFile(join(stage, manifest.chunks[index].name), chunks[index]); + this.phase("chunk_fsynced"); + } + this.writeFile(join(stage, "manifest.json"), manifestBytes); + this.phase("manifest_fsynced"); + syncDirectory$1(stage); + this.phase("source_before_publish"); + renameSync(stage, join(this.originals, sourceId)); + syncDirectory$1(this.originals); + this.phase("source_published"); + const verified = this.source(target, sourceId); + return { + sourceId, + duplicate: false, + conflict, + completed: false, + body: verified.body + }; + } + async retain(target, eventId, body) { + const { normalized, bytes } = this.prepareSource(target, eventId, body); + return this.locked(() => this.retainSource(target, eventId, normalized, bytes)); + } + async retainAndEnqueue(target, eventId, body) { + const { normalized, bytes } = this.prepareSource(target, eventId, body); + return this.locked(() => { + const retained = this.retainSource(target, eventId, normalized, bytes); + if (retained.conflict) return { + retained, + referenceAcknowledged: false + }; + if (retained.completed) return { + retained, + referenceAcknowledged: true }; - const manifestBytes = canonical$1(manifest); - if (Buffer.byteLength(manifestBytes) > 64 * 1024) fail("SOURCE_TOO_LARGE"); - this.budget("original", BLOCK + charge((chunks.length + 1) * 256) + charge(Buffer.byteLength(manifestBytes)) + chunks.reduce((sum, value) => sum + charge(value.length), 0)); - const stage = join(this.originals, ".stage-" + randomUUID()); - mkdirSync(stage, { mode: 448 }); - syncDirectory$1(this.originals); - for (let index = 0; index < chunks.length; index++) { - this.writeFile(join(stage, manifest.chunks[index].name), chunks[index]); - this.phase("chunk_fsynced"); + try { + this.enqueueSource(target, retained.sourceId); + } catch (error) { + return { + retained, + referenceAcknowledged: false, + error + }; } - this.writeFile(join(stage, "manifest.json"), manifestBytes); - this.phase("manifest_fsynced"); - syncDirectory$1(stage); - this.phase("source_before_publish"); - renameSync(stage, join(this.originals, sourceId)); - syncDirectory$1(this.originals); - this.phase("source_published"); - const verified = this.source(target, sourceId); return { - sourceId, - duplicate: false, - conflict, - completed: false, - body: verified.body + retained, + referenceAcknowledged: true }; }); } @@ -413,26 +454,27 @@ var SdkSpoolV2 = class { this.atomicJson(this.refPath(ref.sourceId), ref, "queue", void 0, transition); this.phase("reference_published"); } + enqueueSource(target, sourceId) { + const { manifest } = this.source(target, sourceId); + if (manifest.conflict) fail("SOURCE_CONFLICT"); + if (manifest.completed) return; + try { + this.readRef(target, sourceId); + return; + } catch (error) { + if (code(error) !== "ENOENT") throw error; + } + this.writeRef({ + v: 2, + targetHash: digest$1(target), + sourceId, + state: "pending", + attempts: 0, + nextAttemptAt: 0 + }, false); + } async enqueue(target, sourceId) { - return this.locked(() => { - const { manifest } = this.source(target, sourceId); - if (manifest.conflict) fail("SOURCE_CONFLICT"); - if (manifest.completed) return; - try { - this.readRef(target, sourceId); - return; - } catch (error) { - if (code(error) !== "ENOENT") throw error; - } - this.writeRef({ - v: 2, - targetHash: digest$1(target), - sourceId, - state: "pending", - attempts: 0, - nextAttemptAt: 0 - }, false); - }); + return this.locked(() => this.enqueueSource(target, sourceId)); } async pending(target) { return this.locked(() => { @@ -462,6 +504,13 @@ var SdkSpoolV2 = class { }); } async markSending(target, sourceId, expectedHeldSource) { + await this.claimSource(target, sourceId, expectedHeldSource); + } + async claimForSend(target, sourceId, sendDeadline) { + return this.claimSource(target, sourceId, void 0, sendDeadline); + } + async claimSource(target, sourceId, expectedHeldSource, sendDeadline) { + if (sendDeadline !== void 0 && !Number.isFinite(sendDeadline)) fail("STORE_OPTIONS_INVALID"); return this.locked(() => { const source = this.source(target, sourceId); if (source.manifest.conflict || source.manifest.completed) fail("SOURCE_HELD"); @@ -481,10 +530,12 @@ var SdkSpoolV2 = class { } const owner = ownerIdentity(); if (!owner) fail("STORE_BUSY"); + if (sendDeadline !== void 0 && performance.now() >= sendDeadline) fail("SOURCE_SEND_BUDGET_EXHAUSTED"); ref.state = "sending"; ref.owner = owner; this.writeRef(ref); this.phase("send_intent_fsynced"); + return source.body; }); } async acknowledge(target, sourceId) { @@ -553,7 +604,8 @@ function safeCode(error) { function createStore(options) { return new SdkSpoolV2({ ...options.storeOptions, - dir: options.dir + dir: options.dir, + deadline: options.deadline }); } function held(code, sourceAcknowledged = true, referenceAcknowledged = true) { @@ -573,23 +625,18 @@ async function park(store, target, sourceId, code) { return held(code); } async function sendReference(store, target, sourceId, post, deadline) { + let body; try { - await store.markSending(target, sourceId); + body = await store.claimForSend(target, sourceId, deadline); } catch (error) { const code = error?.code; - if (code === "SOURCE_BACKOFF") return { + if (code === "SOURCE_BACKOFF" || code === "SOURCE_SEND_BUDGET_EXHAUSTED") return { outcome: "spooled", sourceAcknowledged: true, referenceAcknowledged: true }; return held(code === "SOURCE_SENDING" ? "SDK_SEND_IN_PROGRESS_OR_UNCERTAIN" : safeCode(error)); } - let body; - try { - body = await store.load(target, sourceId); - } catch { - return park(store, target, sourceId, "SOURCE_UNVERIFIED"); - } let response; const budget = deadline === void 0 ? void 0 : { deadline, @@ -648,7 +695,7 @@ async function deliverSdkCaptureV2(target, body, post, options = {}) { sourceAcknowledged: false, referenceAcknowledged: false }; - const retained = await store.retain(target, body.eventId, body); + const handoff = await store.retainAndEnqueue(target, body.eventId, body), retained = handoff.retained; sourceId = retained.sourceId; storedBody = retained.body; if (retained.conflict) return held("SOURCE_CONFLICT", true, false); @@ -658,25 +705,21 @@ async function deliverSdkCaptureV2(target, body, post, options = {}) { referenceAcknowledged: true, sdkReplyConfirmed: true }; - } catch (error) { - return { + if (!handoff.referenceAcknowledged) return { outcome: "dropped", - code: safeCode(error), - sourceAcknowledged: false, + code: safeCode(handoff.error), + sourceAcknowledged: true, referenceAcknowledged: false }; - } - try { - await store.enqueue(target, sourceId); } catch (error) { return { outcome: "dropped", code: safeCode(error), - sourceAcknowledged: true, + sourceAcknowledged: false, referenceAcknowledged: false }; } - const sent = await sendReference(store, target, sourceId, post); + const sent = await sendReference(store, target, sourceId, post, options.deadline === void 0 ? void 0 : options.deadline - 750); if (sent.code === "SOURCE_HELD") try { if ((await store.retain(target, storedBody.eventId, storedBody)).completed) return { outcome: "duplicate", @@ -697,7 +740,7 @@ async function drainSdkCapturesV2(target, post, options = {}) { error: void 0 }; const limit = Math.min(8, Math.max(0, options.limit ?? 8)), budget = Math.min(1500, Math.max(0, options.budgetMs ?? 1500)), start = performance.now(); - const deadline = Math.min(options.deadline ?? Infinity, start + budget); + const deadline = Math.min(options.deadline === void 0 ? Infinity : options.deadline - 750, start + budget); try { const store = createStore(options), records = await store.pending(target); for (const ref of records) { @@ -2144,9 +2187,12 @@ async function captureObservationV2(body, timeoutMs) { eventId, captureCompletion: "sdk-v1" })), { scrubKeys: true }); - const options = { dir: process.env["AGENTMEMORY_SDK_CAPTURE_V2_DIR"] }; - const result = await deliverSdkCaptureV2(REST_URL, payload, (b) => postRawV2(b, timeoutMs), options); - const now = performance.now(), deadline = Math.min(started + timeoutMs, now + 250), remaining = Math.floor(deadline - now); + const deadline = started + timeoutMs, options = { + dir: process.env["AGENTMEMORY_SDK_CAPTURE_V2_DIR"], + deadline + }; + const result = await deliverSdkCaptureV2(REST_URL, payload, (b, budget) => postRawV2(b, budget?.remainingMs ?? timeoutMs, budget?.deadline), options); + const now = performance.now(), remaining = Math.floor(Math.min(deadline - 750 - now, 250)); if (body.hookType !== "stop" && (result.outcome === "delivered" || result.outcome === "duplicate") && remaining >= 100) { const backlog = await drainSdkCapturesV2(REST_URL, (b, budget) => postRawV2(b, budget?.remainingMs ?? remaining, budget?.deadline ?? deadline), { ...options, diff --git a/plugin/scripts/codex-compat/manifest.json b/plugin/scripts/codex-compat/manifest.json index ae512862da..20e2a4ee01 100644 --- a/plugin/scripts/codex-compat/manifest.json +++ b/plugin/scripts/codex-compat/manifest.json @@ -14,7 +14,7 @@ "subagent-start.mjs": "24a02be53008721379cbf115884a7739baa2884f8d5f3e12a967b9ae8b0c2869", "subagent-stop.mjs": "8fc6929af24afd799cbaec3a3ca210971c9f51f139f6666fe0025fdfdc62dba8", "provenance.json": "4d768394ad40a29be9d2721fccffd0a054ec97bcc6b868305a27e755eb9b1759", - "_capture.mjs": "83c703972cf8fb192995a24310f7dcbdc3e54ce826fbe1d91be0fa2c9316a923" + "_capture.mjs": "62486a062c13a9200fa7c3df9ab1319aadff7f9c439be9620893728c226ce897" }, "deploymentMapping": { "plugin/scripts/long-session-hook-client.mjs": "plugin/scripts/codex-compat/long-session-hook-client.mjs", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 4f21725ef1..c410e2dcc5 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.62"; +const VERSION = "0.9.32-daniel.63"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 22569ddb98..9c60e5cca8 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.62", + "version": "0.9.32-daniel.63", "facts": { "mcpTools": [ "55" @@ -20,7 +20,7 @@ "12" ], "tests": [ - "6400+" + "6500+" ], "functions": [ "355" diff --git a/src/capture/sdk-delivery-v2.ts b/src/capture/sdk-delivery-v2.ts index e797a0ab5e..513fe0e126 100644 --- a/src/capture/sdk-delivery-v2.ts +++ b/src/capture/sdk-delivery-v2.ts @@ -6,21 +6,21 @@ export const SDK_CAPTURE_V2_FLAG='--agentmemory-sdk-capture-v2'; export type V2PostResult={status:number;body:unknown;notSent?:boolean}; export type V2PostBudget={deadline:number;remainingMs:number}; export type V2Post=(body:Record,budget?:V2PostBudget)=>Promise; -export type V2Options={dir?:string;storeOptions?:Omit}; +export type V2Options={dir?:string;deadline?:number;storeOptions?:Omit}; +export const SDK_FINALIZATION_RESERVE_MS=750; export type V2DeliveryResult={outcome:'delivered'|'duplicate'|'spooled'|'held'|'dropped';code?:string;sourceAcknowledged:boolean;referenceAcknowledged:boolean;sdkReplyConfirmed?:boolean}; const STORE_CODES=new Set(['SOURCE_TOO_LARGE','ORIGINALS_FULL','QUEUE_FULL','SOURCE_CONFLICT','SOURCE_UNVERIFIED','SOURCE_HELD','SOURCE_BACKOFF','STORE_BUSY','STORE_IO','STORE_OPTIONS_INVALID','STORE_UNSAFE','STORE_LOCK_UNSUPPORTED']); function safeCode(error:unknown){const code=(error as {code?:unknown})?.code;return typeof code==='string'&&STORE_CODES.has(code)?code:'STORE_OR_DELIVERY_UNCONFIRMED';} -function createStore(options:V2Options){return new SdkSpoolV2({...options.storeOptions,dir:options.dir});} +function createStore(options:V2Options){return new SdkSpoolV2({...options.storeOptions,dir:options.dir,deadline:options.deadline});} function held(code:string,sourceAcknowledged=true,referenceAcknowledged=true):V2DeliveryResult{return {outcome:'held',code,sourceAcknowledged,referenceAcknowledged};} async function park(store:SdkSpoolV2,target:string,sourceId:string,code:string){try{await store.hold(target,sourceId,code);}catch{return held('QUEUE_STATE_UNCONFIRMED');}return held(code);} async function sendReference(store:SdkSpoolV2,target:string,sourceId:string,post:V2Post,deadline?:number):Promise{ - try{await store.markSending(target,sourceId);}catch(error){ + let body:Record; + try{body=await store.claimForSend(target,sourceId,deadline);}catch(error){ const code=(error as {code?:unknown})?.code; - if(code==='SOURCE_BACKOFF')return {outcome:'spooled',sourceAcknowledged:true,referenceAcknowledged:true}; + if(code==='SOURCE_BACKOFF'||code==='SOURCE_SEND_BUDGET_EXHAUSTED')return {outcome:'spooled',sourceAcknowledged:true,referenceAcknowledged:true}; return held(code==='SOURCE_SENDING'?'SDK_SEND_IN_PROGRESS_OR_UNCERTAIN':safeCode(error)); } - let body:Record; - try{body=await store.load(target,sourceId);}catch{return park(store,target,sourceId,'SOURCE_UNVERIFIED');} let response:V2PostResult; const budget=deadline===undefined?undefined:{deadline,remainingMs:Math.max(0,Math.floor(deadline-performance.now()))}; try{response=budget&&budget.remainingMs<=0?{status:0,body:null,notSent:true}:await post(body,budget);}catch{return park(store,target,sourceId,'SDK_SEND_UNCERTAIN');} @@ -42,12 +42,12 @@ export async function deliverSdkCaptureV2(target:string,body:Record; conflict: boolean; completed: boolean }; -export type SdkSpoolV2Options = { dir?: string; maxOriginalBytes?: number; maxQueueBytes?: number; maxInputBytes?: number; chunkBytes?: number; onPhase?: (phase: string) => void }; +// Optional deadline uses performance.now(); omitted callers retain the 150ms lock wait. +export type SdkSpoolV2Options = { dir?: string; deadline?: number; maxOriginalBytes?: number; maxQueueBytes?: number; maxInputBytes?: number; chunkBytes?: number; onPhase?: (phase: string) => void }; export type RetainedSdkSource = { sourceId: string; duplicate: boolean; conflict: boolean; completed?: boolean; body: Record }; function fail(code: string): never { throw Object.assign(new Error(code), { code }); } @@ -135,6 +136,7 @@ export class SdkSpoolV2 { private readonly maxInputBytes: number; private readonly chunkBytes: number; private readonly onPhase?: (phase: string) => void; + private readonly deadline?: number; constructor(options: SdkSpoolV2Options = {}) { const path = options.dir ?? process.env.AGENTMEMORY_SDK_CAPTURE_V2_DIR ?? join(homedir(), '.local', 'share', 'agentmemory', 'capture-spool-sdk-v2'); if (!isAbsolute(path)) fail('STORE_OPTIONS_INVALID'); @@ -145,6 +147,8 @@ export class SdkSpoolV2 { this.maxInputBytes = limit(options.maxInputBytes, INPUT_LIMIT); this.chunkBytes = limit(options.chunkBytes, CHUNK_LIMIT); this.onPhase = options.onPhase; + if (options.deadline !== undefined && (!Number.isFinite(options.deadline) || options.deadline < 0)) fail('STORE_OPTIONS_INVALID'); + this.deadline = options.deadline; } private phase(name: string): void { this.onPhase?.(name); } private init(): void { @@ -178,6 +182,7 @@ export class SdkSpoolV2 { renameSync(temp, path); syncDirectory(join(path, '..')); } private async locked(operation: () => T): Promise { + const operationDeadline = this.deadline; let fd: number | undefined; try { if (process.platform !== 'linux') fail('STORE_LOCK_UNSUPPORTED'); @@ -186,8 +191,9 @@ export class SdkSpoolV2 { const stat = fstatSync(fd); privateStat(stat, false); if (stat.size !== 0) fail('STORE_UNSAFE'); - const deadline = performance.now() + 150; + const deadline = operationDeadline ?? performance.now() + 150; while (true) { + if (operationDeadline !== undefined && performance.now() >= deadline) fail('STORE_BUSY'); // flock inherits this open file description; its exit does not release our fd's lock. const lock = spawnSync('/usr/bin/flock', ['--exclusive', '--nonblock', '--conflict-exit-code', '73', '3'], { stdio: ['ignore', 'ignore', 'ignore', fd], timeout: 150 }); if (lock.error || lock.signal || lock.status !== 0 && lock.status !== 73) fail('STORE_LOCK_UNSUPPORTED'); @@ -196,6 +202,7 @@ export class SdkSpoolV2 { await new Promise(resolveWait => setTimeout(resolveWait, 5)); } fsyncSync(fd); syncDirectory(this.queue); + if (operationDeadline !== undefined && performance.now() >= deadline) fail('STORE_BUSY'); return operation(); } catch (error) { if (typeof code(error) === 'string' && /^(SOURCE_|ORIGINALS_|QUEUE_|STORE_)/.test(code(error)!)) throw error; @@ -237,7 +244,7 @@ export class SdkSpoolV2 { return { manifest, body }; } catch (error) { if (code(error) === 'STORE_UNSAFE') throw error; fail('SOURCE_UNVERIFIED'); } } - async retain(target: string, eventId: string, body: Record): Promise { + private prepareSource(target: string, eventId: string, body: Record): { normalized: Record; bytes: Buffer } { let normalized: Record; let bytes: Buffer; try { normalized = JSON.parse(JSON.stringify(body)); @@ -245,34 +252,51 @@ export class SdkSpoolV2 { bytes = Buffer.from(canonical(normalized)); } catch { fail('SOURCE_UNVERIFIED'); } if (bytes.length > this.maxInputBytes) fail('SOURCE_TOO_LARGE'); - return this.locked(() => { - let sourceId = this.key(target, eventId); let conflict = false; + return { normalized, bytes }; + } + private retainSource(target: string, eventId: string, normalized: Record, bytes: Buffer): RetainedSdkSource { + let sourceId = this.key(target, eventId); let conflict = false; + try { + lstatSync(join(this.originals, sourceId)); + const prior = this.source(target, sourceId); + if (sameSource(prior.body, normalized)) return { sourceId, duplicate: true, conflict: false, completed: prior.manifest.completed, body: prior.body }; + conflict = true; sourceId = this.conflictKey(target, eventId, normalized); try { lstatSync(join(this.originals, sourceId)); - const prior = this.source(target, sourceId); - if (sameSource(prior.body, normalized)) return { sourceId, duplicate: true, conflict: false, completed: prior.manifest.completed, body: prior.body }; - conflict = true; sourceId = this.conflictKey(target, eventId, normalized); - try { - lstatSync(join(this.originals, sourceId)); - const priorConflict = this.source(target, sourceId); - if (!priorConflict.manifest.conflict || !sameSource(priorConflict.body, normalized)) fail('SOURCE_UNVERIFIED'); - return { sourceId, duplicate: true, conflict: true, completed: false, body: priorConflict.body }; - } catch (error) { if (code(error) !== 'ENOENT') throw error; } + const priorConflict = this.source(target, sourceId); + if (!priorConflict.manifest.conflict || !sameSource(priorConflict.body, normalized)) fail('SOURCE_UNVERIFIED'); + return { sourceId, duplicate: true, conflict: true, completed: false, body: priorConflict.body }; } catch (error) { if (code(error) !== 'ENOENT') throw error; } - const chunks: Buffer[] = []; - for (let offset = 0; offset < bytes.length; offset += this.chunkBytes) chunks.push(bytes.subarray(offset, offset + this.chunkBytes)); - const manifest: Manifest = { v: 2, sourceId, targetHash: digest(target), eventId, bytes: bytes.length, hash: digest(bytes), chunks: chunks.map((value, index) => ({ name: String(index).padStart(6, '0') + '.chunk', bytes: value.length, hash: digest(value) })), conflict, completed: false }; - const manifestBytes = canonical(manifest); - if (Buffer.byteLength(manifestBytes) > 64 * 1024) fail('SOURCE_TOO_LARGE'); - this.budget('original', BLOCK + charge((chunks.length + 1) * 256) + charge(Buffer.byteLength(manifestBytes)) + chunks.reduce((sum, value) => sum + charge(value.length), 0)); - const stage = join(this.originals, '.stage-' + randomUUID()); - mkdirSync(stage, { mode: 0o700 }); syncDirectory(this.originals); - for (let index = 0; index < chunks.length; index++) { this.writeFile(join(stage, manifest.chunks[index].name), chunks[index]); this.phase('chunk_fsynced'); } - this.writeFile(join(stage, 'manifest.json'), manifestBytes); this.phase('manifest_fsynced'); - syncDirectory(stage); this.phase('source_before_publish'); - renameSync(stage, join(this.originals, sourceId)); syncDirectory(this.originals); this.phase('source_published'); - const verified = this.source(target, sourceId); - return { sourceId, duplicate: false, conflict, completed: false, body: verified.body }; + } catch (error) { if (code(error) !== 'ENOENT') throw error; } + const chunks: Buffer[] = []; + for (let offset = 0; offset < bytes.length; offset += this.chunkBytes) chunks.push(bytes.subarray(offset, offset + this.chunkBytes)); + const manifest: Manifest = { v: 2, sourceId, targetHash: digest(target), eventId, bytes: bytes.length, hash: digest(bytes), chunks: chunks.map((value, index) => ({ name: String(index).padStart(6, '0') + '.chunk', bytes: value.length, hash: digest(value) })), conflict, completed: false }; + const manifestBytes = canonical(manifest); + if (Buffer.byteLength(manifestBytes) > 64 * 1024) fail('SOURCE_TOO_LARGE'); + this.budget('original', BLOCK + charge((chunks.length + 1) * 256) + charge(Buffer.byteLength(manifestBytes)) + chunks.reduce((sum, value) => sum + charge(value.length), 0)); + const stage = join(this.originals, '.stage-' + randomUUID()); + mkdirSync(stage, { mode: 0o700 }); syncDirectory(this.originals); + for (let index = 0; index < chunks.length; index++) { this.writeFile(join(stage, manifest.chunks[index].name), chunks[index]); this.phase('chunk_fsynced'); } + this.writeFile(join(stage, 'manifest.json'), manifestBytes); this.phase('manifest_fsynced'); + syncDirectory(stage); this.phase('source_before_publish'); + renameSync(stage, join(this.originals, sourceId)); syncDirectory(this.originals); this.phase('source_published'); + const verified = this.source(target, sourceId); + return { sourceId, duplicate: false, conflict, completed: false, body: verified.body }; + } + async retain(target: string, eventId: string, body: Record): Promise { + const { normalized, bytes } = this.prepareSource(target, eventId, body); + return this.locked(() => this.retainSource(target, eventId, normalized, bytes)); + } + async retainAndEnqueue(target: string, eventId: string, body: Record): Promise<{ retained: RetainedSdkSource; referenceAcknowledged: boolean; error?: unknown }> { + const { normalized, bytes } = this.prepareSource(target, eventId, body); + return this.locked(() => { + const retained = this.retainSource(target, eventId, normalized, bytes); + if (retained.conflict) return { retained, referenceAcknowledged: false }; + if (retained.completed) return { retained, referenceAcknowledged: true }; + // Source publication is not rolled back if queue admission or I/O fails. + try { this.enqueueSource(target, retained.sourceId); } + catch (error) { return { retained, referenceAcknowledged: false, error }; } + return { retained, referenceAcknowledged: true }; }); } async load(target: string, sourceId: string): Promise> { @@ -288,14 +312,15 @@ export class SdkSpoolV2 { } catch (error) { if (code(error) === 'ENOENT' || code(error) === 'STORE_UNSAFE') throw error; fail('SOURCE_UNVERIFIED'); } } private writeRef(ref: Ref, transition = true): void { this.atomicJson(this.refPath(ref.sourceId), ref, 'queue', undefined, transition); this.phase('reference_published'); } + private enqueueSource(target: string, sourceId: string): void { + const { manifest } = this.source(target, sourceId); + if (manifest.conflict) fail('SOURCE_CONFLICT'); + if (manifest.completed) return; + try { this.readRef(target, sourceId); return; } catch (error) { if (code(error) !== 'ENOENT') throw error; } + this.writeRef({ v: 2, targetHash: digest(target), sourceId, state: 'pending', attempts: 0, nextAttemptAt: 0 }, false); + } async enqueue(target: string, sourceId: string): Promise { - return this.locked(() => { - const { manifest } = this.source(target, sourceId); - if (manifest.conflict) fail('SOURCE_CONFLICT'); - if (manifest.completed) return; - try { this.readRef(target, sourceId); return; } catch (error) { if (code(error) !== 'ENOENT') throw error; } - this.writeRef({ v: 2, targetHash: digest(target), sourceId, state: 'pending', attempts: 0, nextAttemptAt: 0 }, false); - }); + return this.locked(() => this.enqueueSource(target, sourceId)); } async pending(target: string): Promise> { return this.locked(() => { @@ -312,6 +337,13 @@ export class SdkSpoolV2 { }); } async markSending(target: string, sourceId: string, expectedHeldSource?: Record): Promise { + await this.claimSource(target, sourceId, expectedHeldSource); + } + async claimForSend(target: string, sourceId: string, sendDeadline?: number): Promise> { + return this.claimSource(target, sourceId, undefined, sendDeadline); + } + private async claimSource(target: string, sourceId: string, expectedHeldSource?: Record, sendDeadline?: number): Promise> { + if (sendDeadline !== undefined && !Number.isFinite(sendDeadline)) fail('STORE_OPTIONS_INVALID'); return this.locked(() => { const source = this.source(target, sourceId); if (source.manifest.conflict || source.manifest.completed) fail('SOURCE_HELD'); @@ -327,8 +359,11 @@ export class SdkSpoolV2 { if (ref.nextAttemptAt > Date.now()) fail('SOURCE_BACKOFF'); } const owner = ownerIdentity(); if (!owner) fail('STORE_BUSY'); + // Only a ref verified pending under this lease can be reported as spooled. + if (sendDeadline !== undefined && performance.now() >= sendDeadline) fail('SOURCE_SEND_BUDGET_EXHAUSTED'); ref.state = 'sending'; ref.owner = owner; this.writeRef(ref); this.phase('send_intent_fsynced'); + return source.body; }); } async acknowledge(target: string, sourceId: string): Promise { diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 87c189a371..06e481467a 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/hooks/_capture.ts b/src/hooks/_capture.ts index 02c1b11fb4..ecd255edc8 100644 --- a/src/hooks/_capture.ts +++ b/src/hooks/_capture.ts @@ -1,4 +1,4 @@ -import {deliverSdkCaptureV2,drainSdkCapturesV2,SDK_CAPTURE_V2_FLAG,type V2DeliveryResult,type V2PostResult} from "../capture/sdk-delivery-v2.js"; +import {deliverSdkCaptureV2,drainSdkCapturesV2,SDK_CAPTURE_V2_FLAG,SDK_FINALIZATION_RESERVE_MS,type V2DeliveryResult,type V2PostResult} from "../capture/sdk-delivery-v2.js"; import {scrubRecord} from "../functions/privacy.js"; import {performance} from "node:perf_hooks"; import {sendCapture,restoreSdkOriginal} from "../capture/delivery.js"; @@ -246,9 +246,9 @@ async function captureObservationV2(body:ObserveBody,timeoutMs:number):Promise; - const options={dir:process.env["AGENTMEMORY_SDK_CAPTURE_V2_DIR"]}; - const result=await deliverSdkCaptureV2(REST_URL,payload,b=>postRawV2(b,timeoutMs),options); - const now=performance.now(),deadline=Math.min(started+timeoutMs,now+250),remaining=Math.floor(deadline-now); + const deadline=started+timeoutMs,options={dir:process.env["AGENTMEMORY_SDK_CAPTURE_V2_DIR"],deadline}; + const result=await deliverSdkCaptureV2(REST_URL,payload,(b,budget)=>postRawV2(b,budget?.remainingMs??timeoutMs,budget?.deadline),options); + const now=performance.now(),remaining=Math.floor(Math.min(deadline-SDK_FINALIZATION_RESERVE_MS-now,250)); if(body.hookType!=="stop"&&(result.outcome==="delivered"||result.outcome==="duplicate")&&remaining>=100){ const backlog=await drainSdkCapturesV2(REST_URL,(b,budget)=>postRawV2(b,budget?.remainingMs??remaining,budget?.deadline??deadline),{...options,limit:1,budgetMs:remaining,deadline}); if(backlog.held||backlog.error){try{writeSync(2,JSON.stringify({code:"CAPTURE_BACKLOG_HELD",held:backlog.held,error:backlog.error})+"\n");}catch{}} diff --git a/src/ops/embedding-recovery.mjs b/src/ops/embedding-recovery.mjs index 13fd2d8299..8794e5ad61 100644 --- a/src/ops/embedding-recovery.mjs +++ b/src/ops/embedding-recovery.mjs @@ -6,7 +6,7 @@ export const EMBEDDING_COMMITTED_NAMESPACE='mem:embedding-committed:v1'; const digest=text=>createHash('sha256').update(text).digest('hex'); export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKeyedLock=async(k,fn)=>fn(),logger,clock=Date.now,schedule=true,onIndexChanged,persistIndex}) { const state={pendingCount:0,completedCount:0,counterEpoch:randomUUID(),initialized:false,lastError:null,lastSuccessAt:null}; - let pumping=false,reconciled=false,stopped=false,interval=null,initialization=null,committedRows=null,committedOffset=0; + let pumping=false,reconciled=false,stopped=false,started=false,interval=null,initialization=null,committedRows=null,committedOffset=0; const active=new Set(),sourceGuards=new Set(),publications=new Map(),accepted=new Map(),pendingIds=new Set(); // Historical proof observed by this worker, never a fresh disk-verification cache. const observedPublications=new Map(); @@ -255,12 +255,26 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe if(reconciled){committedRows=null;committedOffset=0;} } async function runPump(){ - if(stopped||backgroundPaused()||pumping)return;pumping=true; + if(stopped||backgroundPaused()||pumping)return false;pumping=true; + const roundPublications=new Set(),selected=[]; + const beforeCompleted=state.completedCount;let failed=false,more=false; try{ if(!reconciled)await reconcile(50); const rows=await kv.list(EMBEDDING_RETRY_NAMESPACE); + const byId=new Map(rows.map(item=>[item.id,item])); + for(const item of rows)if(!pendingIds.has(item.id))pending(item); + // Keep a process-local round robin independent of engine enumeration. + // New intents join the end; a failed attempt must not monopolize the head. + for(const id of pendingIds){ + const item=byId.get(id); + if(item&&!(item.retryAt>clock())&&!publications.has(id))selected.push(item); + if(selected.length===5)break; + } + for(const item of selected){pendingIds.delete(item.id);pendingIds.add(item.id);} + const selectedIds=new Set(selected.map(item=>item.id)); + more=rows.some(item=>!selectedIds.has(item.id)&&!(item.retryAt>clock())&&!publications.has(item.id)); const groups=new Map(); - for(const item of rows.filter(item=>!(item.retryAt>clock())&&!publications.has(item.id)).slice(0,5)){ + for(const item of selected){ const scope=sourceScope(item);if(!groups.has(scope))groups.set(scope,[]);groups.get(scope).push(item); } for(const items of groups.values()){ @@ -275,7 +289,7 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe try{ const queued=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id);if(!queued||queued.retryAt>clock())continue; const result=await prepare(queued,await current(queued),false);if(result)prepared.push(result); - }catch(error){state.lastError=networkErrorCode(error);} + }catch(error){failed=true;state.lastError=networkErrorCode(error);} } if(!prepared.length)return; const selections=prepared.map(({item})=>[{scope:sourceScope(item),key:item.id},{scope:EMBEDDING_RETRY_NAMESPACE,key:item.id}]); @@ -290,23 +304,45 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe if(stopped||backgroundPaused())break; const result=results?.[offset]; if(result?.status!=='fulfilled'){ + failed=true; await withKeyedLock(intentKey(entry.item.id),async()=>{ if((await kv.get(EMBEDDING_RETRY_NAMESPACE,entry.item.id))?.generation===entry.generation)await retainUnlocked(entry.item,result?.reason,true); });continue; } - try{await executePrepared(entry);}catch(error){state.lastError=networkErrorCode(error);} + try{ + if(!await executePrepared(entry))failed=true; + const publication=publications.get(entry.item.id);if(publication)roundPublications.add(publication); + }catch(error){failed=true;state.lastError=networkErrorCode(error);} if(readiness?.snapshot?.().status==='waiting')break; } }); if(readiness?.snapshot?.().status==='waiting')break; } - }catch(error){state.lastError=networkErrorCode(error);logger?.warn('Embedding recovery scan deferred',{errorCode:state.lastError});} - finally{pumping=false;} + }catch(error){failed=true;state.lastError=networkErrorCode(error);logger?.warn('Embedding recovery scan deferred',{errorCode:state.lastError});} + finally{ + // A fast provider must not grow an unbounded queue of unpublished vectors. + // Release the model locks first; publication retains its existing fences. + const outcomes=await Promise.allSettled([...roundPublications]); + if(outcomes.some(result=>result.status==='rejected'))failed=true; + pumping=false; + } + return !failed&&!stopped&&!backgroundPaused()&&readiness?.snapshot?.().status!=='waiting'&& + more&&state.completedCount>beforeCompleted&&selected.every(item=>!pendingIds.has(item.id)); } - function pump(){if(stopped)return Promise.resolve();return track(initialize().then(()=>backgroundTask(runPump)()));} - function stop(){stopped=true;for(const release of sourceGuards)release();if(interval){clearInterval(interval);interval=null;}} + function pumpWork(){if(stopped)return Promise.resolve(false);return track(initialize().then(()=>backgroundTask(runPump)()));} + function pump(){return pumpWork().then(()=>{});} + function stop(){stopped=true;for(const release of sourceGuards)release();if(interval){clearTimeout(interval);interval=null;}} async function drain(){while(active.size)await Promise.allSettled([...active]);} - function start(){if(stopped||interval)return;void track(initialize()).catch(error=>{state.lastError=networkErrorCode(error);});interval=setInterval(()=>void pump().catch(error=>{state.lastError=networkErrorCode(error);logger?.warn('Embedding recovery initialization deferred',{errorCode:state.lastError});}),15000);interval.unref();} + function scheduleNext(delay){ + if(stopped)return; + interval=setTimeout(()=>{ + interval=null; + void pumpWork().then(fast=>scheduleNext(fast===true?1000:15000),error=>{ + state.lastError=networkErrorCode(error);logger?.warn('Embedding recovery initialization deferred',{errorCode:state.lastError});scheduleNext(15000); + }); + },delay);interval.unref(); + } + function start(){if(stopped||started)return;started=true;void track(initialize()).catch(error=>{state.lastError=networkErrorCode(error);});scheduleNext(15000);} if(schedule)start(); return {add,enqueue,prepareEnqueue,enqueueBatch,pump,start,initialize:()=>track(initialize()),reconcile:()=>track(reconcile()),stop,drain, observedPublication:id=>{try{return publicationEvidenceAvailable?structuredClone(observedPublications.get(id)??null):null;}catch{evidenceFailure();return null;}}, diff --git a/src/types.ts b/src/types.ts index 2c5f749c80..96ae37f378 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index 3a9e487d77..3141a959b1 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.62"; +export const VERSION = "0.9.32-daniel.63"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/embedding-scheduling.test.ts b/test/embedding-scheduling.test.ts new file mode 100644 index 0000000000..08b7f8e016 --- /dev/null +++ b/test/embedding-scheduling.test.ts @@ -0,0 +1,117 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {mockKV} from './helpers/mocks.js'; +import {KV} from '../src/state/schema.js'; +import {VectorIndex} from '../src/state/vector-index.js'; +import {withKeyedLock} from '../src/state/keyed-mutex.js'; +import {installBackgroundControl} from '../src/ops/background-control.mjs'; +import {serializeLongSessionProvider} from '../src/ops/long-session.mjs'; +import {registerEmbeddingRecovery,EMBEDDING_RETRY_NAMESPACE as RETRY} from '../src/ops/embedding-recovery.mjs'; + +const workers:ReturnType[]=[]; +afterEach(async()=>{installBackgroundControl(null);for(const worker of workers.splice(0)){worker.stop();await worker.drain();}vi.useRealTimers();}); +async function fixture(count=12){ + vi.useFakeTimers();vi.setSystemTime(100000); + const kv=mockKV(),index=new VectorIndex();let active=0,peak=0; + const embed=vi.fn(async()=>{peak=Math.max(peak,++active);await Promise.resolve();active--;return new Float32Array([1,0]);}); + const persistIndex=vi.fn(async()=>{}); + const options={kv:kv as never,KV,index,provider:{dimensions:2,embed},withKeyedLock,schedule:false,persistIndex}; + const worker=registerEmbeddingRecovery(options);workers.push(worker); + for(let n=0;npeak}; +} +it('continues a published backlog after a one-second yield with at most five serial inferences per round',async()=>{ + const f=await fixture();f.worker.start();await vi.advanceTimersByTimeAsync(15000); + expect(f.worker.snapshot().completedCount).toBe(5);expect(f.peak()).toBe(1); + await vi.advanceTimersByTimeAsync(999);expect(f.embed).toHaveBeenCalledTimes(5); + await vi.advanceTimersByTimeAsync(1);expect(f.worker.snapshot().completedCount).toBe(10); + await vi.advanceTimersByTimeAsync(1000);expect(f.worker.snapshot().completedCount).toBe(12); + expect(await f.kv.list(RETRY)).toHaveLength(0);expect(f.peak()).toBe(1); +}); +it('rotates past unchanged failing head items without changing their attempts or source',async()=>{ + const f=await fixture(6),get=f.kv.get; + f.kv.get=async(scope,id)=>{if(scope===KV.observations('s')&&Number(id)<5)throw Error('synthetic read failure');return get(scope,id);}; + f.worker.start();await vi.advanceTimersByTimeAsync(15000);expect(f.embed).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(14999);expect(f.embed).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1);expect(f.index.has('5')).toBe(true); + for(let n=0;n<5;n++){expect(await get(RETRY,String(n))).toMatchObject({attempts:0,retryAt:0});expect(await get(KV.observations('s'),String(n))).toMatchObject({title:'synthetic '+n});} +}); +it('does not start another round while any selected publication is unresolved',async()=>{ + const f=await fixture(11);let release!:()=>void;const held=new Promise(r=>release=r); + f.persistIndex.mockImplementation(async()=>held);f.worker.start(); + try{await vi.advanceTimersByTimeAsync(15000);expect(f.embed).toHaveBeenCalledTimes(5);expect(f.worker.snapshot().completedCount).toBe(0); + await vi.advanceTimersByTimeAsync(45000);expect(f.embed).toHaveBeenCalledTimes(5); + }finally{release();await f.worker.drain();} + await vi.advanceTimersByTimeAsync(999);expect(f.embed).toHaveBeenCalledTimes(5); + await vi.advanceTimersByTimeAsync(1);expect(f.embed).toHaveBeenCalledTimes(10); +}); +it('uses the idle interval after a failed publication even when other entries complete',async()=>{ + const f=await fixture();let failed=false; + f.persistIndex.mockImplementation(async()=>{if(!failed){failed=true;throw Error('synthetic disk failure');}}); + f.worker.start();await vi.advanceTimersByTimeAsync(15000);expect(f.worker.snapshot().completedCount).toBe(4); + await vi.advanceTimersByTimeAsync(14999);expect(f.embed).toHaveBeenCalledTimes(5); + await vi.advanceTimersByTimeAsync(1);expect(f.embed).toHaveBeenCalledTimes(10); + expect(await f.kv.get(RETRY,'0')).toMatchObject({attempts:1,retryAt:145000}); +}); +it('keeps provider backoff and does not poll a future-only queue at the fast rate',async()=>{ + const f=await fixture(1);f.embed.mockRejectedValueOnce(Object.assign(Error('synthetic provider failure'),{code:'ECONNRESET'})); + const list=vi.spyOn(f.kv,'list');f.worker.start();await vi.advanceTimersByTimeAsync(15000); + expect(await f.kv.get(RETRY,'0')).toMatchObject({attempts:1,retryAt:145000});const scans=list.mock.calls.length; + await vi.advanceTimersByTimeAsync(14999);expect(list.mock.calls.length).toBe(scans); + await vi.advanceTimersByTimeAsync(1);expect(f.embed).toHaveBeenCalledTimes(1); + await vi.advanceTimersByTimeAsync(15000);expect(f.embed).toHaveBeenCalledTimes(2);expect(f.index.has('0')).toBe(true); +}); +it('does not bypass provider waiting or create multiple schedules through repeated start',async()=>{ + const f=await fixture();f.worker.stop();let ready=false; + const worker=registerEmbeddingRecovery({...f.options,readiness:{ensureReady:async()=>ready,snapshot:()=>({status:ready?'ready':'waiting'})}as never});workers.push(worker); + worker.start();worker.start();await vi.advanceTimersByTimeAsync(15000);expect(f.embed).not.toHaveBeenCalled(); + ready=true;await vi.advanceTimersByTimeAsync(14999);expect(f.embed).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1);expect(f.embed).toHaveBeenCalledTimes(5); + await vi.advanceTimersByTimeAsync(1000);expect(f.embed).toHaveBeenCalledTimes(10); +}); +it.each(['pause','stop'])('closes fast admission on %s while preserving remaining intents',async mode=>{ + const f=await fixture();let paused=false;installBackgroundControl({isPaused:()=>paused,run:async(fn:()=>unknown)=>paused?{deferred:true}:fn()}as never); + f.worker.start();await vi.advanceTimersByTimeAsync(15000);expect(f.embed).toHaveBeenCalledTimes(5); + if(mode==='pause')paused=true;else f.worker.stop(); + await vi.advanceTimersByTimeAsync(16000);expect(f.embed).toHaveBeenCalledTimes(5);expect(await f.kv.list(RETRY)).toHaveLength(7); + if(mode==='pause'){paused=false;await vi.advanceTimersByTimeAsync(15000);expect(f.embed.mock.calls.length).toBeGreaterThan(5);} +}); +it('lets an already-waiting chat run between individual embeddings',async()=>{ + const f=await fixture(5);f.worker.stop();const order:string[]=[];let release!:()=>void,entered!:()=>void; + const held=new Promise(r=>release=r),started=new Promise(r=>entered=r);let active=0,peak=0,n=0; + const provider=serializeLongSessionProvider({dimensions:2,async embed(){const id=n++;order.push('embed'+id);peak=Math.max(peak,++active);if(id===0){entered();await held;}active--;return new Float32Array([1,0]);}},withKeyedLock); + const chat=serializeLongSessionProvider({async summarize(){order.push('chat');peak=Math.max(peak,++active);active--;return 'synthetic';}},withKeyedLock); + const worker=registerEmbeddingRecovery({...f.options,provider});workers.push(worker); + try{const pump=worker.pump();await started;const chatting=chat.summarize();release();await Promise.all([pump,chatting]);await worker.drain();expect(order).toEqual(['embed0','chat','embed1','embed2','embed3','embed4']);expect(peak).toBe(1);}finally{release();} +}); +it('keeps old unattempted work ahead of new arrivals despite reversed engine enumeration',async()=>{ + const f=await fixture(6),get=f.kv.get,list=f.kv.list; + f.kv.get=async(scope,id)=>{if(scope===KV.observations('s')&&Number(id)<5)throw Error('synthetic read failure');return get(scope,id);}; + await f.worker.pump();expect(f.embed).not.toHaveBeenCalled(); + for(let n=6;n<12;n++){const id=String(n);await f.kv.set(KV.observations('s'),id,{id,sessionId:'s',title:'new '+id});await f.worker.enqueue({id,sessionId:'s',kind:'synthetic'});} + f.kv.list=async scope=>(await list(scope)).reverse(); + await f.worker.pump();expect(f.index.has('5')).toBe(true);expect(f.embed).toHaveBeenCalledTimes(1); + expect(await f.kv.list(RETRY)).toHaveLength(11); +}); +it('stops scheduling while drain still waits for already admitted publications',async()=>{ + const f=await fixture();let release!:()=>void;const held=new Promise(r=>release=r);f.persistIndex.mockImplementation(async()=>held); + f.worker.start(); + try{await vi.advanceTimersByTimeAsync(15000);f.worker.start();f.worker.stop();let drained=false;const draining=f.worker.drain().then(()=>{drained=true;}); + await vi.advanceTimersByTimeAsync(30000);expect(f.embed).toHaveBeenCalledTimes(5);expect(drained).toBe(false); + release();await draining;expect(f.worker.snapshot().completedCount).toBe(5); + await vi.advanceTimersByTimeAsync(30000);expect(f.embed).toHaveBeenCalledTimes(5);expect(await f.kv.list(RETRY)).toHaveLength(7); + }finally{release();await f.worker.drain();} +}); +it('does not schedule a fast round when readiness changes during publication',async()=>{ + const f=await fixture();f.worker.stop();let ready=true; + const worker=registerEmbeddingRecovery({...f.options,readiness:{ensureReady:async()=>ready,snapshot:()=>({status:ready?'ready':'waiting'})}as never});workers.push(worker); + f.persistIndex.mockImplementation(async()=>{ready=false;});worker.start();await vi.advanceTimersByTimeAsync(15000); + const calls=f.embed.mock.calls.length;expect(calls).toBeGreaterThan(0);ready=true; + await vi.advanceTimersByTimeAsync(14999);expect(f.embed).toHaveBeenCalledTimes(calls); + await vi.advanceTimersByTimeAsync(1);expect(f.embed.mock.calls.length).toBeGreaterThan(calls); +}); +it('returns to idle polling once the final publication finishes',async()=>{ + const f=await fixture(1),list=vi.spyOn(f.kv,'list');f.worker.start();await vi.advanceTimersByTimeAsync(15000); + expect(f.worker.snapshot().completedCount).toBe(1);const scans=list.mock.calls.length; + await vi.advanceTimersByTimeAsync(14999);expect(list.mock.calls.length).toBe(scans); + await vi.advanceTimersByTimeAsync(1);expect(list.mock.calls.length).toBe(scans+1);expect(f.embed).toHaveBeenCalledOnce(); +}); diff --git a/test/helpers/sdk-deadline-worker.mjs b/test/helpers/sdk-deadline-worker.mjs new file mode 100644 index 0000000000..0ac952f9f0 --- /dev/null +++ b/test/helpers/sdk-deadline-worker.mjs @@ -0,0 +1,20 @@ +import {openSync,closeSync} from 'node:fs'; +import {join} from 'node:path'; +import {spawnSync} from 'node:child_process'; +import {pathToFileURL} from 'node:url'; +import {performance} from 'node:perf_hooks'; +if(!process.send||process.env.FIXTURE_DIR!==join(process.env.HOME,'spool'))throw Error('FIXTURE_ISOLATION'); +if(process.env.MODE==='holder'){ + const fd=openSync(join(process.env.FIXTURE_DIR,'queue/lease.lock'),'r+'); + const lock=spawnSync('/usr/bin/flock',['--exclusive','--nonblock','3'],{stdio:['ignore','ignore','ignore',fd]}); + if(lock.status!==0)throw Error('FIXTURE_LOCK_FAILED'); + process.send({ready:true}); + process.once('message',()=>setTimeout(()=>{closeSync(fd);process.disconnect();},350)); +}else{ + const {deliverSdkCaptureV2}=await import(pathToFileURL(process.env.FIXTURE_MODULE)); + process.send({ready:true}); + process.once('message',async()=>{ + const result=await deliverSdkCaptureV2(process.env.FIXTURE_TARGET,{eventId:'multiprocess-'+process.env.FIXTURE_INDEX},async body=>({status:201,body:{eventId:body.eventId,completion:'sdk',completed:true,durable:false}}),{dir:process.env.FIXTURE_DIR,deadline:performance.now()+3000}); + process.send({result});process.disconnect(); + }); +} diff --git a/test/helpers/sdk-native-deadline-preload.mjs b/test/helpers/sdk-native-deadline-preload.mjs new file mode 100644 index 0000000000..b6f54d2be0 --- /dev/null +++ b/test/helpers/sdk-native-deadline-preload.mjs @@ -0,0 +1,40 @@ +// Fixture-only filesystem latency and mock fetch; the native hook source is unchanged by this helper. +import fs from 'node:fs'; +import { syncBuiltinESMExports } from 'node:module'; +import { performance } from 'node:perf_hooks'; +const dir = process.env.AGENTMEMORY_SDK_CAPTURE_V2_DIR; +const recordPath = process.env.FIXTURE_TRACE; +if (!dir?.startsWith(process.env.HOME + '/') || !recordPath?.startsWith(process.env.HOME + '/') || process.env.AGENTMEMORY_URL !== 'http://127.0.0.1:43111') throw Error('FIXTURE_ISOLATION'); +const trace = (event, fields = {}) => fs.appendFileSync(recordPath, JSON.stringify({ event, atMs: Math.round(performance.now()), ...fields }) + '\n', { mode: 0o600 }); +const actualTimer = globalThis.setTimeout; +let capArmed = false, delayDone = false; +globalThis.setTimeout = function(fn, ms, ...args) { + if (ms === 3500) { capArmed = true; trace('native_cap_armed', { milliseconds: ms }); } + return actualTimer(fn, ms, ...args); +}; +const actualStat = fs.lstatSync; +fs.lstatSync = function(path, ...args) { + if (capArmed && !delayDone && String(path).startsWith(dir)) { + delayDone = true; + const ms = Number(process.env.FIXTURE_LOCAL_DELAY_MS); + trace('local_delay', { milliseconds: ms }); + if (ms) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); + } + return actualStat.call(this, path, ...args); +}; +syncBuiltinESMExports(); +globalThis.fetch = async function(url, options) { + if (url !== 'http://127.0.0.1:43111/agentmemory/observe' || options?.method !== 'POST') throw Error('FIXTURE_NETWORK_REFUSED'); + const body = JSON.parse(options.body); + trace('mock_post_started'); + await new Promise((resolve, reject) => { + let timer; + const abort = () => { clearTimeout(timer); trace('mock_post_aborted'); reject(options.signal.reason); }; + if (options.signal.aborted) return abort(); + options.signal.addEventListener('abort', abort, { once: true }); + timer = actualTimer(() => { options.signal.removeEventListener('abort', abort); resolve(); }, Number(process.env.FIXTURE_REPLY_DELAY_MS)); + }); + trace('mock_ack_returned'); + return { status: 201, json: async () => ({ eventId: body.eventId, completion: 'sdk', completed: true, durable: false }) }; +}; +process.once('exit', code => trace('process_exit', { code })); diff --git a/test/sdk-capture-deadline.test.ts b/test/sdk-capture-deadline.test.ts new file mode 100644 index 0000000000..90d11d07af --- /dev/null +++ b/test/sdk-capture-deadline.test.ts @@ -0,0 +1,118 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {createHash} from 'node:crypto'; +import {existsSync,mkdirSync,mkdtempSync,readFileSync,readdirSync,rmSync,writeFileSync} from 'node:fs'; +import {join,resolve} from 'node:path'; +import {tmpdir} from 'node:os'; +import {performance} from 'node:perf_hooks'; +import {fork} from 'node:child_process'; +import {SdkSpoolV2,deliverSdkCaptureV2,drainSdkCapturesV2} from '../src/capture/sdk-delivery-v2.js'; +const target='http://127.0.0.1:43111',roots:string[]=[]; +const hash=(v:string|Buffer)=>createHash('sha256').update(v).digest('hex'); +const id=(event:string)=>hash(hash(target)+'\0'+event); +const ack=(body:Record)=>({status:201,body:{eventId:body.eventId,completion:'sdk',completed:true,durable:false}}); +const delay=(ms:number)=>Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,ms); +function root(){const value=mkdtempSync(join(tmpdir(),'sdk-deadline-'));roots.push(value);return value;} +function ref(dir:string,event:string){return JSON.parse(readFileSync(join(dir,'queue',id(event)+'.ref'),'utf8'));} +function manifest(dir:string,event:string){return JSON.parse(readFileSync(join(dir,'originals',id(event),'manifest.json'),'utf8'));} +afterEach(()=>{vi.restoreAllMocks();for(const value of roots.splice(0))rmSync(value,{recursive:true,force:true});}); + +it('publishes retained source and reference under one lease, without calling separate enqueue',async()=>{ + const dir=root();const enqueue=vi.spyOn(SdkSpoolV2.prototype,'enqueue').mockRejectedValue(Object.assign(Error('STORE_BUSY'),{code:'STORE_BUSY'})); + const result=await deliverSdkCaptureV2(target,{eventId:'composite'},async body=>ack(body),{dir}); + expect(result.outcome).toBe('delivered');expect(enqueue).not.toHaveBeenCalled();expect(manifest(dir,'composite').completed).toBe(true); +}); +it('retains original acknowledgment if reference quota rejects composite handoff',async()=>{ + const dir=root();let posts=0; + const result=await deliverSdkCaptureV2(target,{eventId:'full'},async body=>{posts++;return ack(body);},{dir,storeOptions:{maxQueueBytes:3*4096}}); + expect(result).toMatchObject({outcome:'dropped',code:'QUEUE_FULL',sourceAcknowledged:true,referenceAcknowledged:false});expect(posts).toBe(0); + expect(manifest(dir,'full').completed).toBe(false);expect(existsSync(join(dir,'queue',id('full')+'.ref'))).toBe(false); +}); +it('preserves raw published before a simulated crash and does not pretend a reference exists',async()=>{ + const dir=root();let posts=0; + const result=await deliverSdkCaptureV2(target,{eventId:'crash'},async body=>{posts++;return ack(body);},{dir,storeOptions:{onPhase:phase=>{if(phase==='source_published')throw Error('synthetic crash');}}}); + expect(result.outcome).toBe('dropped');expect(posts).toBe(0);expect(manifest(dir,'crash').completed).toBe(false); + expect(existsSync(join(dir,'queue',id('crash')+'.ref'))).toBe(false); +}); +it('reports retained source conservatively when reference publication reports an I/O fault',async()=>{ + const dir=root(),post=vi.fn(async(body:Record)=>ack(body)); + const result=await deliverSdkCaptureV2(target,{eventId:'queue-fault'},post,{dir,storeOptions:{onPhase:phase=>{if(phase==='reference_published')throw Object.assign(Error('synthetic I/O'),{code:'STORE_IO'});}}}); + expect(result).toMatchObject({outcome:'dropped',code:'STORE_IO',sourceAcknowledged:true,referenceAcknowledged:false});expect(post).not.toHaveBeenCalled();expect(manifest(dir,'queue-fault').completed).toBe(false); +}); +it('leaves pending without sending or attempts when local work consumes the transport budget',async()=>{ + const dir=root();let posts=0; + const result=await deliverSdkCaptureV2(target,{eventId:'budget'},async body=>{posts++;return ack(body);},{dir,deadline:performance.now()+900,storeOptions:{onPhase:phase=>{if(phase==='source_published')delay(200);}}}); + expect(result.outcome).toBe('spooled');expect(posts).toBe(0);expect(ref(dir,'budget')).toMatchObject({state:'pending',attempts:0,nextAttemptAt:0});expect(manifest(dir,'budget').completed).toBe(false); +}); +it('passes the same absolute transport deadline with finalization headroom to direct POST',async()=>{ + const dir=root(),deadline=performance.now()+2000;let budget:any; + const result=await deliverSdkCaptureV2(target,{eventId:'deadline'},async(body,value)=>{budget=value;return ack(body);},{dir,deadline}); + expect(result.outcome).toBe('delivered');expect(budget.deadline).toBe(deadline-750);expect(budget.remainingMs).toBeGreaterThan(0);expect(budget.remainingMs).toBeLessThanOrEqual(1250); +}); +it('never retries an uncertain POST but retains explicit not-sent retry semantics with a deadline',async()=>{ + const dir=root(),post=vi.fn(async()=>{throw Error('synthetic timeout after POST');}); + expect(await deliverSdkCaptureV2(target,{eventId:'unknown'},post,{dir,deadline:performance.now()+2000})).toMatchObject({outcome:'held',code:'SDK_SEND_UNCERTAIN'}); + expect(ref(dir,'unknown')).toMatchObject({state:'held',reason:'HELD',attempts:0}); + expect((await deliverSdkCaptureV2(target,{eventId:'unknown'},post,{dir,deadline:performance.now()+2000})).outcome).toBe('held');expect(post).toHaveBeenCalledTimes(1); + expect((await deliverSdkCaptureV2(target,{eventId:'unknown'},post,{dir,deadline:performance.now()+500})).outcome).toBe('held');expect(post).toHaveBeenCalledTimes(1); + expect((await deliverSdkCaptureV2(target,{eventId:'not-sent'},async()=>({status:0,body:null,notSent:true}),{dir,deadline:performance.now()+2000})).outcome).toBe('spooled'); + expect(ref(dir,'not-sent')).toMatchObject({state:'pending',reason:'RETRY',attempts:1}); +}); +it('does not call an existing sending reference pending when its transport budget has expired',async()=>{ + const dir=root();let entered!:()=>void,release!:()=>void,posts=0; + const started=new Promise(r=>entered=r),wait=new Promise(r=>release=r); + const first=deliverSdkCaptureV2(target,{eventId:'in-flight'},async body=>{posts++;entered();await wait;return ack(body);},{dir,deadline:performance.now()+3000});await started; + try{ + expect(await deliverSdkCaptureV2(target,{eventId:'in-flight'},async body=>{posts++;return ack(body);},{dir,deadline:performance.now()+500})).toMatchObject({outcome:'held',code:'SDK_SEND_IN_PROGRESS_OR_UNCERTAIN'}); + expect(ref(dir,'in-flight').state).toBe('sending');expect(posts).toBe(1); + }finally{release();await first;} +}); +it('does not convert a failed claim lock into evidence that a source is pending',async()=>{ + const dir=root();vi.spyOn(SdkSpoolV2.prototype,'claimForSend').mockRejectedValue(Object.assign(Error('STORE_BUSY'),{code:'STORE_BUSY'})); + const post=vi.fn(async(body:Record)=>ack(body)); + expect(await deliverSdkCaptureV2(target,{eventId:'claim-unknown'},post,{dir,deadline:performance.now()+500})).toMatchObject({outcome:'held',code:'STORE_BUSY'});expect(post).not.toHaveBeenCalled(); +}); +it('keeps SDK confirmation separate if local ACK publication fails',async()=>{ + const dir=root();const result=await deliverSdkCaptureV2(target,{eventId:'ack-fail'},async body=>ack(body),{dir,deadline:performance.now()+2000,storeOptions:{onPhase:(phase:string)=>{if(phase==='ack_before_publish')throw Error('synthetic failure');}}}); + expect(result).toMatchObject({outcome:'held',code:'SDK_ACK_STATE_UNCONFIRMED',sdkReplyConfirmed:true});expect(ref(dir,'ack-fail').state).toBe('sending');expect(manifest(dir,'ack-fail').completed).toBe(false); +}); +it('rejects non-finite public claim deadlines without creating a sending intent',async()=>{ + const dir=root(),store=new SdkSpoolV2({dir}),source=await store.retain(target,'invalid-clock',{eventId:'invalid-clock'});await store.enqueue(target,source.sourceId); + for(const deadline of [NaN,Infinity,-Infinity])await expect(store.claimForSend(target,source.sourceId,deadline)).rejects.toMatchObject({code:'STORE_OPTIONS_INVALID'}); + await expect(store.claimForSend(target,source.sourceId,-1)).rejects.toMatchObject({code:'SOURCE_SEND_BUDGET_EXHAUSTED'}); + expect(ref(dir,'invalid-clock')).toMatchObject({state:'pending',attempts:0}); +}); +it('bounded drain preserves a short shared deadline and the legacy unspecified deadline behavior',async()=>{ + const dir=root(),store=new SdkSpoolV2({dir}),source=await store.retain(target,'drain-budget',{eventId:'drain-budget'});await store.enqueue(target,source.sourceId); + let posts=0; + const short=await drainSdkCapturesV2(target,async body=>{posts++;return ack(body);},{dir,deadline:performance.now()+500,budgetMs:250}); + expect(short).toMatchObject({attempted:0,remaining:1});expect(posts).toBe(0);expect(ref(dir,'drain-budget').state).toBe('pending'); + const result=await drainSdkCapturesV2(target,async body=>{posts++;return ack(body);},{dir,budgetMs:250}); + expect(result).toMatchObject({attempted:1,delivered:1,remaining:0});expect(posts).toBe(1); +}); + +for(const processes of [2,6])it(`${processes} real processes wait beyond legacy 150ms and complete against 6000 retained originals`,async()=>{ + const home=root(),dir=join(home,'spool'),store=new SdkSpoolV2({dir});await store.usage(); + // Synthetic completed trees exercise the actual recursive quota scan. Nothing is read from the host spool. + for(let index=0;index<6000;index++){ + const folder=join(dir,'originals',hash('seed-'+index));mkdirSync(folder,{mode:0o700}); + writeFileSync(join(folder,'manifest.json'),'synthetic quota-only fixture',{mode:0o600});writeFileSync(join(folder,'000000.chunk'),'synthetic',{mode:0o600}); + } + const children:any[]=[]; + function child(mode:string,index=0){ + const worker=fork(resolve('test/helpers/sdk-deadline-worker.mjs'),[],{execArgv:['--import',resolve('node_modules/tsx/dist/loader.mjs')],env:{PATH:'/usr/bin:/bin',HOME:home,USERPROFILE:home,TMPDIR:home,MODE:mode,FIXTURE_DIR:dir,FIXTURE_TARGET:target,FIXTURE_INDEX:String(index),FIXTURE_MODULE:process.env.SDK_DEADLINE_FIXTURE_MODULE??resolve('src/capture/sdk-delivery-v2.ts')},stdio:['ignore','pipe','pipe','ipc']}); + children.push(worker);let result:any; + const ready=new Promise((done,reject)=>{worker.on('message',(m:any)=>{if(m.ready)done();if(m.result)result=m.result;});worker.once('error',reject);}); + const exited=new Promise((done,reject)=>{worker.once('exit',code=>code===0?done(result):reject(Error('FIXTURE_CHILD_FAILED')));worker.once('error',reject);}); + return {worker,ready,exited}; + } + try{ + const holder=child('holder');await holder.ready; + const senders=Array.from({length:processes},(_,i)=>child('sender',i));await Promise.all(senders.map(x=>x.ready)); + for(const sender of senders)sender.worker.send('go');holder.worker.send('release-after-350ms'); + const results=await Promise.all(senders.map(x=>x.exited));await holder.exited; + console.log(JSON.stringify({syntheticConcurrentCapture:true,processes,results})); + for(const result of results)expect(result).toMatchObject({outcome:'delivered',sourceAcknowledged:true,referenceAcknowledged:true,sdkReplyConfirmed:true}); + expect(readdirSync(join(dir,'originals'))).toHaveLength(6000+processes); + for(let i=0;i{for(const dir of roots.splice(0))rmSync(dir,{recursive:true,force:true});}); +async function run(localMs:number,replyMs:number){ + const root=mkdtempSync(join(tmpdir(),'native-sdk-deadline-'));roots.push(root);const dir=join(root,'spool-v2'),trace=join(root,'trace.jsonl'); + const env=isolatedHookEnv(root,{AGENTMEMORY_URL:'http://127.0.0.1:43111',AGENTMEMORY_SECRET:'synthetic-only',AGENTMEMORY_PROJECT_NAME:'synthetic',AGENTMEMORY_SDK_CAPTURE_V2_DIR:dir,TMPDIR:root,TMP:root,TEMP:root,FIXTURE_TRACE:trace,FIXTURE_LOCAL_DELAY_MS:String(localMs),FIXTURE_REPLY_DELAY_MS:String(replyMs)}); + const entry=process.env.SDK_NATIVE_FIXTURE_ENTRY??resolve('src/hooks/post-tool-use.ts'); + const child=spawn(process.execPath,['--import',resolve('test/helpers/sdk-native-deadline-preload.mjs'),'--import',resolve('node_modules/tsx/dist/loader.mjs'),entry,'--agentmemory-sdk-capture-v2'],{cwd:root,env,stdio:['pipe','pipe','pipe']}); + let stderr='',stdout='';child.stderr.on('data',v=>stderr+=v);child.stdout.on('data',v=>stdout+=v); + const watchdog=setTimeout(()=>child.kill(),8000); + child.stdin.end(JSON.stringify({session_id:'synthetic',tool_name:'fixture_tool',tool_input:{synthetic:true},tool_response:'synthetic',cwd:root})); + const exit=await new Promise((done,reject)=>{child.once('exit',done);child.once('error',reject);});clearTimeout(watchdog); + const ids=readdirSync(join(dir,'originals'));expect(ids).toHaveLength(1); + const manifest=JSON.parse(readFileSync(join(dir,'originals',ids[0],'manifest.json'),'utf8')); + const refs=readdirSync(join(dir,'queue')).filter(v=>v.endsWith('.ref')).map(v=>JSON.parse(readFileSync(join(dir,'queue',v),'utf8'))); + return {exit,stderr,stdout,manifest,refs,trace:readFileSync(trace,'utf8').trim().split('\n').map(v=>JSON.parse(v))}; +} +for(const [localMs,replyMs] of [[0,20],[900,1000]])it(`native shared deadline completes ACK after local ${localMs}ms and reply ${replyMs}ms`,async()=>{ + const r=await run(localMs,replyMs);expect(r.exit).toBe(0);expect(r.stderr).toBe('');expect(r.stdout).toBe('');expect(r.manifest.completed).toBe(true);expect(r.refs).toEqual([]);expect(r.trace.filter(v=>v.event==='mock_ack_returned')).toHaveLength(1); +},10000); +it('native shared deadline aborts a late POST and durably parks before the hard exit cap',async()=>{ + const r=await run(1000,2800);expect(r.exit).toBe(1);expect(r.stdout).toBe('');expect(r.stderr).toContain('SDK_SEND_UNCERTAIN');expect(r.stderr).not.toContain('CAPTURE_LOCAL_HANDOFF_UNCONFIRMED'); + expect(r.manifest.completed).toBe(false);expect(r.refs).toHaveLength(1);expect(r.refs[0]).toMatchObject({state:'held',reason:'HELD',attempts:0});expect(r.refs[0].owner).toBeUndefined(); + expect(r.trace.filter(v=>v.event==='mock_ack_returned')).toHaveLength(0);expect(r.trace.filter(v=>v.event==='mock_post_aborted')).toHaveLength(1); + const start=r.trace.find(v=>v.event==='native_cap_armed').atMs,end=r.trace.find(v=>v.event==='process_exit').atMs; + expect(end-start).toBeLessThan(3500);console.log(JSON.stringify({syntheticNativeDeadline:true,localDelayMs:1000,mockReplyMs:2800,state:r.refs[0].state,attempts:r.refs[0].attempts,elapsedAfterCapArmedMs:end-start,networkCalls:0})); +},10000); diff --git a/test/sdk-v2-transport-safety.test.ts b/test/sdk-v2-transport-safety.test.ts index 9158b0f0aa..dffceba62d 100644 --- a/test/sdk-v2-transport-safety.test.ts +++ b/test/sdk-v2-transport-safety.test.ts @@ -40,8 +40,8 @@ it('does not POST when send-intent fsync consumes the monotonic drain budget; ke it('passes the original absolute deadline and fresh remaining budget after source readback',async()=>{ await queued();let clock=1000,received:unknown; vi.spyOn(performance,'now').mockImplementation(()=>clock); - const load=SdkSpoolV2.prototype.load; - vi.spyOn(SdkSpoolV2.prototype,'load').mockImplementation(async function(this:SdkSpoolV2,t,id){const value=await load.call(this,t,id);clock+=30;return value;}); + const claim=SdkSpoolV2.prototype.claimForSend; + vi.spyOn(SdkSpoolV2.prototype,'claimForSend').mockImplementation(async function(this:SdkSpoolV2,t,id,deadline){const value=await claim.call(this,t,id,deadline);clock+=30;return value;}); const result=await drainSdkCapturesV2(target,async(b,...args:unknown[])=>{received=args[0];return ack(b);},{dir:join(root,'v2'),limit:1,budgetMs:250,storeOptions:{onPhase:phase=>{if(phase==='send_intent_fsynced')clock+=70;}}}); expect(received).toEqual({deadline:1250,remainingMs:150}); expect(result).toMatchObject({attempted:1,delivered:1,held:0,remaining:0}); From fb328957a32e60ea170fbad5071c62df11d4ee57 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 8 Nov 2026 12:38:05 +0900 Subject: [PATCH 08/23] fix(state): acknowledge large summary writes without value echo --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 9 ++++ docs/customizations/COMPACT-SUMMARY-ACK.md | 15 +++++++ integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- src/functions/export-import.ts | 2 +- src/index.ts | 3 +- src/state/kv.ts | 17 +++++++- src/state/state-readiness.ts | 9 ++++ src/types.ts | 2 +- src/version.ts | 2 +- test/state-readiness.test.ts | 13 ++++++ test/status.test.ts | 2 +- test/summary-set-ack.test.ts | 48 ++++++++++++++++++++++ 27 files changed, 134 insertions(+), 24 deletions(-) create mode 100644 docs/customizations/COMPACT-SUMMARY-ACK.md create mode 100644 test/summary-set-ack.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 72dfdbd83b..a918aa9cc6 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 02b348127c..4def5e9139 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.63) +## Current Stats (v0.9.32-daniel.64) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index 191a333563..b67502a6cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,15 @@ +## Unreleased — compact summary acknowledgement + +- Preserve summary bodies and cursors while avoiding old+new response amplification: file-backed server summary writes use the engine state::set_ack success-only response, with a pinned JSON request snapshot. Ordinary state::set/Redis and compatibility-mode StateKV remain unchanged. +- Require read-only acknowledgement capability discovery before writer acquisition and capture admission. Missing/malformed acknowledgement or actual storage failure remains an uncertain mutation; no fallback, timeout extension, message-cap increase or data migration. +- Cause: identical installed COW engine cc4ff876 + SDK0.25 synthetic overwrite of33556506-byte JSON emits67113039-byte old/new result, exceeds SDK64MiB, reconnects and TIMEOUT despite applied value. Current failure session's stored summary33555971 bytes crosses the same boundary. Operational content is not used as a fixture. +- Validation and deployment state: see workspace work/storage-timeout63/REPORT.md. Source implementation is not operating activation. Historical failures and old unknown writes remain preserved. Durable memory recording is pending manual review. + # Changelog ## [Unreleased] +## [0.9.32-daniel.64] — 2026-11-08 ## [0.9.32-daniel.63] — 2026-11-07 - Keep fresh SDK-v2 source retention and reference admission under one lease. Share the native hook's original deadline across lock acquisition and transport, reserving 750ms for final state recording. Preserve retained-source acknowledgement if reference admission fails, retain the default 150ms lock contract without an explicit deadline, and leave exhausted pending work queued before any send. Unknown transport outcomes remain held; existing held/sending records never become a successful pending result merely because time ran out. - Claim and read the selected body under the same lease, preserving source hashing and owner fencing. No spool schema, quota, original-retention, automatic unknown-send retry or host trust changes. The source/reference publication gap under an OS crash and unbounded kernel filesystem latency are not eliminated. @@ -594,6 +602,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.64]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.63...v0.9.32-daniel.64 [0.9.32-daniel.63]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.62...v0.9.32-daniel.63 [0.9.32-daniel.62]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.61...v0.9.32-daniel.62 [0.9.32-daniel.61]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.60...v0.9.32-daniel.61 diff --git a/docs/customizations/COMPACT-SUMMARY-ACK.md b/docs/customizations/COMPACT-SUMMARY-ACK.md new file mode 100644 index 0000000000..24ddb8533b --- /dev/null +++ b/docs/customizations/COMPACT-SUMMARY-ACK.md @@ -0,0 +1,15 @@ +# Compact summary state acknowledgement + +The personal file-backed server requires the native engine's `state::set_ack` function before acquiring its writer lease or admitting capture. Its engine handler delegates to the existing `state::set` implementation, returns `true` on success, and forwards failures/deferred/no-result outcomes. Existing `state::set`, validation, triggers, disk format and SDK message limits remain unchanged. + +`StateKV` enables this only for summary writes in the file-backed server. Its compatibility default and other namespaces keep the existing state API. The summary request is pinned to a JSON snapshot, a non-true ACK is an uncertain mutation, and the acknowledged snapshot updates the existing metadata/wire-byte overlay. No echoed old value is fabricated. Existing SDK completion and shutdown checks still apply; an ACK is not an fsync guarantee. + +The failure mechanism is old+new response amplification. An installed COW engine and real SDK0.25 replay of a33556506-byte value produces67113039 response bytes, exceeding the SDK64MiB message cap. The write applies, the response disconnects the SDK, and the request times out. This is why neither a longer deadline nor treating a timeout as an unapplied write is safe. + +Validation uses synthetic data only. The fixed native release engine and actual `StateKV` code must pass large overwrite, exact JSON content readback, SDK completion, no reconnect, retained bulk-response refusal, clean engine exit and cold readback. Ordinary set responses and adapter/size errors must retain their old contracts. The compiled CLI must pass capability discovery, normal shutdown receipt checks and a second fresh startup. + +This requires a coupled app/engine deployment. Never enable the new app on an old engine or apply either old published bundle again. The .63 cold-boot helper is pinned to the old release and engine: migrate its dependency and bindings as part of the same reviewed cold transaction. If the current worker already latched mutation uncertainty, use the preserved uncertain transition with a fresh PID/time-bound stop receipt, current-data backup/readback, old lifecycle preservation and no data rewind. Do not turn old unknown writes into successful history. + +A single input or get response must still fit the unchanged64MiB SDK message limit. This patch removes duplicated values from the summary write response; it does not introduce a new storage schema or solve arbitrary oversized records. Replace the custom native handler when upstream provides an equivalent acknowledged-write contract with the same validation, trigger, failure, reconnect, shutdown and preservation tests. + +Implementation and actual deployment must be recorded separately. Workspace evidence is in `work/storage-timeout63/REPORT.md`; long-term memory recording remains pending manual review. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 7e9ca07423..afc2152579 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.63 +version: 0.9.32-daniel.64 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 36c087e0b7..7280e1e44d 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index aaef442c8e..052294cb86 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 822a07cb20..1bc0bd7323 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index c285c3f734..74b12e8b79 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.63 +version: 0.9.32-daniel.64 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 9ef12b2a57..6106f480ac 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 4e66b0db6d..1caae6449c 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.63" + "@agentmemory/agentmemory": "0.9.32-daniel.64" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 783edbe3bd..0a128fb31a 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 1f54bde61a..b0a8fcd04e 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index aab5869967..9cdb0a0fac 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.63" + "@agentmemory/mcp@0.9.32-daniel.64" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 93a0a93dd1..2baddb57a7 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 11677d4082..27aa0f2da3 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index c410e2dcc5..752d04b041 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.63"; +const VERSION = "0.9.32-daniel.64"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 9c60e5cca8..bb0c676e69 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.63", + "version": "0.9.32-daniel.64", "facts": { "mcpTools": [ "55" diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 06e481467a..883d8fdf47 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/index.ts b/src/index.ts index 6f7bc2ad9f..2874a2b64b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -290,6 +290,7 @@ async function main() { stateBackend = getStateBackend(); } catch {} const stateReadiness = await waitForStateReady(sdk, { + requireSetAck: stateBackend === "file", onWaiting: (error) => bootWarn(`Waiting for the state worker to register state::get and state::list (${error})`), }); @@ -304,7 +305,7 @@ async function main() { const engineEvidence=createEngineEpochEvidence({engineUrl:config.engineUrl,enginePidPath:runtimeMetadataPath("iii.pid"),peer:()=>{const socket=(sdk as unknown as {ws?:{_socket?:{remoteAddress?:string;remotePort?:number;localAddress?:string;localPort?:number}}}).ws?._socket;return socket?{remoteAddress:socket.remoteAddress,remotePort:socket.remotePort,localAddress:socket.localAddress,localPort:socket.localPort}:null;}}); if(stateBackend==="file"&&writerStorePath&&process.platform==="linux"){const until=Date.now()+3000;while(!engineEvidence.capture()&&Date.now()setTimeout(resolve,25));} const writerLease=stateBackend==="file"&&writerStorePath&&process.platform==="linux"?acquireFileWriterLease(writerStorePath,{evidence:engineEvidence}):undefined; - const kv = new StateKV(sdk, { backend: stateBackend,writerLease }); + const kv = new StateKV(sdk, { backend: stateBackend,writerLease, compactSummaryWrites: stateBackend === 'file' }); writeWorkerPidfile(); const secret = resolveWorkerSecret(); const ingress = createShutdownIngress(); diff --git a/src/state/kv.ts b/src/state/kv.ts index 68fed5b307..6afa14c35b 100644 --- a/src/state/kv.ts +++ b/src/state/kv.ts @@ -24,6 +24,7 @@ export interface StateKVOptions { writerLease?: FileWriterLease backend?: StateBackend durability?: ReturnType + compactSummaryWrites?: boolean } type UpdateOp = { type: string; path: string; value?: unknown } @@ -141,11 +142,13 @@ export class StateKV { readonly captureReceiptPage: ReturnType | null readonly auditReader: ReturnType | null private readonly summaryCount: ReturnType | null + private readonly compactSummaryWrites: boolean constructor( private sdk: IIIClient, options: StateKVOptions = {}, ) { + this.compactSummaryWrites = options.compactSummaryWrites === true this.backend = options.backend ?? 'file' const storePath = this.backend === 'file' ? getEnvVar('AGENTMEMORY_STATE_STORE_PATH') : undefined this.checkpointStorePath = storePath @@ -265,7 +268,7 @@ export class StateKV { if(scope==='mem:summaries'&&this.summaryCount)return withKeyedLock(`summary-state:${key}`,async()=>{ const projection=knownValue&&!knownValue.deleted?this.summaryCount!.prepare(knownValue.value,{wire:false}):undefined const result=await operation(scope) - if(knownValue)this.summaryCount!.record(key,knownValue.deleted!==true,projection,result&&typeof result==='object'&&Object.hasOwn(result,'old_value')&&Object.hasOwn(result,'new_value')?Reflect.get(result,'new_value'):undefined) + if(knownValue)this.summaryCount!.record(key,knownValue.deleted!==true,projection,this.compactSummaryWrites?knownValue.value:result&&typeof result==='object'&&Object.hasOwn(result,'old_value')&&Object.hasOwn(result,'new_value')?Reflect.get(result,'new_value'):undefined) else if(result&&typeof result==='object'&&Object.hasOwn(result,'new_value'))this.summaryCount!.record(key,true,this.summaryCount!.prepare(Reflect.get(result,'new_value'))) else this.summaryCount!.invalidate() return result @@ -291,6 +294,18 @@ export class StateKV { } async set(scope: string, key: string, value: T): Promise { + if (scope === KV.summaries && this.compactSummaryWrites) { + const sent = JSON.parse(JSON.stringify(value)) as T + await this.mutate(scope, key, async (resolvedScope) => { + const acknowledged = await this.sdk.trigger({ + function_id: 'state::set_ack', + payload: { scope: resolvedScope, key, value: sent }, + }) + if (acknowledged !== true) throw Object.assign(Error('state_set_ack_unverified'), { code: 'STATE_SET_ACK_UNVERIFIED' }) + return { new_value: sent } + }, { value: sent }) + return sent + } return this.mutate(scope, key, (resolvedScope) => this.sdk.trigger<{ scope: string; key: string; value: T }, T>({ function_id: 'state::set', diff --git a/src/state/state-readiness.ts b/src/state/state-readiness.ts index c281a5ea42..46f87d3b8c 100644 --- a/src/state/state-readiness.ts +++ b/src/state/state-readiness.ts @@ -16,6 +16,7 @@ export type StateReadiness = { type TriggerClient = Pick; type WaitOptions = { + requireSetAck?: boolean; scope?: string; timeoutMs?: number; intervalMs?: number; @@ -72,6 +73,14 @@ export async function waitForStateReady( payload: { scope, key: READINESS_PROBE_KEY }, timeoutMs: probeTimeoutMs(), }); + if (options.requireSetAck) { + const info = await sdk.trigger<{ function_id: string }, { function_id?: string } | null>({ + function_id: "engine::functions::info", + payload: { function_id: "state::set_ack" }, + timeoutMs: probeTimeoutMs(), + }); + if (info?.function_id !== "state::set_ack") throw new Error("STATE_SET_ACK_REQUIRED"); + } return { ready: true, waitedMs: Math.round(now() - startedAt), attempts }; } catch (error) { lastError = errorMessage(error); diff --git a/src/types.ts b/src/types.ts index 96ae37f378..c378d04223 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index 3141a959b1..a91d10bfeb 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.63"; +export const VERSION = "0.9.32-daniel.64"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/state-readiness.test.ts b/test/state-readiness.test.ts index 038c95332d..73a9818bb6 100644 --- a/test/state-readiness.test.ts +++ b/test/state-readiness.test.ts @@ -241,3 +241,16 @@ describe("assertStateReady", () => { ).not.toThrow(); }); }); + +describe('compact state acknowledgement readiness',()=>{ + it.each([undefined,{function_id:'state::set'},null])('refuses an old/malformed engine before enabling compact writes: %j',async detail=>{ + const trigger=vi.fn(async({function_id}:any)=>function_id==='engine::functions::info'?detail:null); + const result=await waitForStateReady(asClient(trigger),{requireSetAck:true}); + expect(result.ready).toBe(false);expect(result.error).toBe('STATE_SET_ACK_REQUIRED'); + }); + it('checks registered support without writing a probe value',async()=>{ + const trigger=vi.fn(async({function_id}:any)=>function_id==='engine::functions::info'?{function_id:'state::set_ack'}:null); + expect((await waitForStateReady(asClient(trigger),{requireSetAck:true})).ready).toBe(true); + expect(trigger.mock.calls.map(([r])=>r.function_id)).toEqual(['state::list','state::get','engine::functions::info']); + }); +}); diff --git a/test/status.test.ts b/test/status.test.ts index 62fc8a03f2..2ca7c2a0bd 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -548,7 +548,7 @@ describe("status wiring", () => { it("reports the active state backend from config, not a hardcoded value", () => { expect(api).toMatch(/stateBackend: kv.backend === "redis" \? "redis" : "file"/); - expect(index).toMatch(/new StateKV\(sdk, \{ backend: stateBackend,writerLease \}\)/); + expect(index).toMatch(/new StateKV\(sdk,\s*\{\s*backend:\s*stateBackend,/); }); it("the viewer has a Health tab that reads the status report", () => { diff --git a/test/summary-set-ack.test.ts b/test/summary-set-ack.test.ts new file mode 100644 index 0000000000..f494791041 --- /dev/null +++ b/test/summary-set-ack.test.ts @@ -0,0 +1,48 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {mkdtemp,writeFile,rm} from 'node:fs/promises'; +import {tmpdir} from 'node:os'; +import {join} from 'node:path'; +import {StateKV} from '../src/state/kv.js'; +const dirs:string[]=[]; +afterEach(async()=>{vi.unstubAllEnvs();await Promise.all(dirs.splice(0).map(p=>rm(p,{recursive:true,force:true})));}); +async function fixture(trigger:ReturnType,compactSummaryWrites=true){ + const root=await mkdtemp(join(tmpdir(),'am-summary-ack-'));dirs.push(root); + vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH',root); + await writeFile(join(root,'mem%3Asummaries.bin'),'{}'); + return new StateKV({trigger}as never,{compactSummaryWrites}); +} +it('sends a pinned JSON snapshot through compact ack and retains the stored summary projection',async()=>{ + let entered!:()=>void,release!:()=>void; + const waiting=new Promise(r=>entered=r),held=new Promise(r=>release=r); + const trigger=vi.fn(async(req:any)=>{entered();await held;return true;}); + const kv=await fixture(trigger),value={sessionId:'a',title:'sent',optional:undefined}; + const saving=kv.set('mem:summaries','a',value);await waiting;value.title='changed';release(); + expect(await saving).toEqual({sessionId:'a',title:'sent'}); + expect(trigger).toHaveBeenCalledWith({function_id:'state::set_ack',payload:{scope:'mem:summaries',key:'a',value:{sessionId:'a',title:'sent'}}}); + expect(await kv.getSummaryMetadata()).toMatchObject([{sessionId:'a',title:'sent'}]); + expect(kv.mutationOutcomeUncertain).toBe(false); +}); +it.each([false,null,{}, {new_value:'unexpected'}])('rejects a malformed acknowledgement without certifying a write: %j',async ack=>{ + const kv=await fixture(vi.fn(async()=>ack)); + await expect(kv.set('mem:summaries','a',{sessionId:'a'})).rejects.toMatchObject({code:'STATE_SET_ACK_UNVERIFIED'}); + expect(kv.mutationOutcomeUncertain).toBe(true); + expect(kv.durability!.snapshot().mutationFailures).toBe(1); +}); +it('propagates failed acknowledgement and retains the storage uncertainty latch',async()=>{ + const kv=await fixture(vi.fn(async()=>{throw Object.assign(Error('adapter failed'),{code:'SET_ERROR'});})); + await expect(kv.set('mem:summaries','a',{sessionId:'a'})).rejects.toMatchObject({code:'SET_ERROR'}); + expect(kv.mutationOutcomeUncertain).toBe(true); +}); +it('keeps ordinary namespaces and compatibility-mode summary writes on the existing API',async()=>{ + const trigger=vi.fn(async(req:any)=>({old_value:null,new_value:req.payload.value})); + const kv=await fixture(trigger);await kv.set('mem:other','a',{kept:true}); + const legacy=await fixture(trigger,false);await legacy.set('mem:summaries','a',{sessionId:'a'}); + expect(trigger.mock.calls.map(([r])=>r.function_id)).toEqual(['state::set','state::set']); +}); +it('keeps byte-budgeted summary listing available after compact acknowledgement',async()=>{ + const value={sessionId:'a',title:'kept'}; + const trigger=vi.fn(async(req:any)=>req.function_id==='state::set_ack'?true:[value]); + const kv=await fixture(trigger);await kv.set('mem:summaries','a',value); + expect(await kv.list('mem:summaries')).toEqual([value]); + expect(trigger.mock.calls.map(([req])=>req.function_id)).toEqual(['state::set_ack','state::list']); +}); From 152fa918a8449b3b3eff22d5020f3d1ad6001329 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 8 Nov 2026 13:26:49 +0900 Subject: [PATCH 09/23] fix: preserve manual hold during storage and memory recovery --- CHANGELOG.md | 1 + docs/customizations/COMPACT-SUMMARY-ACK.md | 2 + src/ops/background-control.mjs | 12 +++++- src/ops/memory-pressure.mjs | 3 +- test/operations-protection-recovery.test.ts | 46 +++++++++++++++++++++ 5 files changed, 61 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b67502a6cb..cd453f127a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ - Preserve summary bodies and cursors while avoiding old+new response amplification: file-backed server summary writes use the engine state::set_ack success-only response, with a pinned JSON request snapshot. Ordinary state::set/Redis and compatibility-mode StateKV remain unchanged. - Require read-only acknowledgement capability discovery before writer acquisition and capture admission. Missing/malformed acknowledgement or actual storage failure remains an uncertain mutation; no fallback, timeout extension, message-cap increase or data migration. - Cause: identical installed COW engine cc4ff876 + SDK0.25 synthetic overwrite of33556506-byte JSON emits67113039-byte old/new result, exceeds SDK64MiB, reconnects and TIMEOUT despite applied value. Current failure session's stored summary33555971 bytes crosses the same boundary. Operational content is not used as a fixture. +- Preserve manual/storage holds when a recovered memory hold would otherwise deadlock three-way recovery. Only a fresh stable-memory check and successful storage fence may remove the memory hold; admission stays closed until explicit vector-verified resume, and automatic retries remain bounded. - Validation and deployment state: see workspace work/storage-timeout63/REPORT.md. Source implementation is not operating activation. Historical failures and old unknown writes remain preserved. Durable memory recording is pending manual review. # Changelog diff --git a/docs/customizations/COMPACT-SUMMARY-ACK.md b/docs/customizations/COMPACT-SUMMARY-ACK.md index 24ddb8533b..af12131930 100644 --- a/docs/customizations/COMPACT-SUMMARY-ACK.md +++ b/docs/customizations/COMPACT-SUMMARY-ACK.md @@ -13,3 +13,5 @@ This requires a coupled app/engine deployment. Never enable the new app on an ol A single input or get response must still fit the unchanged64MiB SDK message limit. This patch removes duplicated values from the summary write response; it does not introduce a new storage schema or solve arbitrary oversized records. Replace the custom native handler when upstream provides an equivalent acknowledged-write contract with the same validation, trigger, failure, reconnect, shutdown and preservation tests. Implementation and actual deployment must be recorded separately. Workspace evidence is in `work/storage-timeout63/REPORT.md`; long-term memory recording remains pending manual review. + +A related interrupted-pause recovery case can retain manual, memory and storage-error holds together. After sustained memory recovery, only the memory hold may be automatically released under a fresh predicate and successful storage confirmation. Manual and storage holds remain, and explicit checkpoint-verified resume is still required. Failed storage confirmation retains all holds and the existing automatic retry limit. This avoids clearing protection by editing the saved control record. diff --git a/src/ops/background-control.mjs b/src/ops/background-control.mjs index e56c19fed7..92b27a0cb4 100644 --- a/src/ops/background-control.mjs +++ b/src/ops/background-control.mjs @@ -108,9 +108,11 @@ export function createBackgroundControl({clock=Date.now}={}){ if(status==='pausing'||completion||(beforeResume&&active.size))throw Error('background_draining'); const automatic=source==='memory'; const memoryWithStorage=automatic&&holds.size===2&&holds.has('storage_error')&&holds.has('memory'); + const protectedMemoryRelease=automatic&&holds.has('storage_error')&&holds.has('memory')&&(holds.has('manual')||holds.has('deployment')); if(automatic){ - const eligible=memoryWithStorage?status==='paused'||status==='error':status==='paused'&&holds.size===1&&holds.has('memory'); + const eligible=memoryWithStorage||protectedMemoryRelease?status==='paused'||status==='error':status==='paused'&&holds.size===1&&holds.has('memory'); if(!eligible||recovery.attempts>=MEMORY_RECOVERY_MAX_ATTEMPTS||clock()=c.recovery.maxAttempts){state.recoveryStatus='attempt_limit';return;} if(now{ + const f=fixture({version:2,paused:true,resumePending:true,holds:['manual','memory','storage_error'],recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);await f.normal(115000); + expect(f.control.snapshot().holds).toEqual(['manual','memory','storage_error']); + f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain();await f.control.settled(); + expect(f.control.snapshot()).toMatchObject({holds:['manual','storage_error'],pausedRequested:true,activeOperations:0}); + expect(f.record()).toMatchObject({paused:true,resumePending:false,holds:['manual','storage_error']}); + expect(await f.control.run(async()=>42)).toMatchObject({deferred:true}); + let verified=false;await f.control.change('resume',{beforeResume:async()=>{verified=true;return true;}}); + expect(verified).toBe(true);expect(f.control.snapshot()).toMatchObject({status:'running',holds:[],pausedRequested:false}); +}); +it('requires a fresh stable-memory check before releasing one hold from a protected storage pause',async()=>{ + const f=fixture({version:2,paused:true,resumePending:true,holds:['manual','memory','storage_error'],recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);const before=structuredClone(f.record());let checked=false; + await f.control.change('resume',{source:'memory',canResume:async()=>{checked=true;return false;}}); + expect(checked).toBe(true);expect(f.record()).toEqual(before);expect(f.control.snapshot().holds).toEqual(['manual','memory','storage_error']); +}); +it('retains all protection holds on failed partial storage confirmation and bounds automatic retries',async()=>{ + const f=fixture({version:2,paused:true,resumePending:true,holds:['manual','memory','storage_error'],recovery:{attempts:2,nextAttemptAt:0}}); + await f.control.init(f.kv);const original=structuredClone(f.record());f.fail(true); + await expect(f.control.change('resume',{source:'memory',canResume:async()=>true})).rejects.toThrow('background_storage_unavailable'); + expect(f.control.snapshot()).toMatchObject({holds:['manual','memory','storage_error'],pausedRequested:true,recovery:{attempts:3}}); + expect(f.record()).toEqual(original);f.fail(false);f.time(1000000000);let retried=false; + await f.control.change('resume',{source:'memory',canResume:async()=>{retried=true;return true;}}); + expect(retried).toBe(false);expect(f.control.snapshot().holds).toEqual(['manual','memory','storage_error']); +}); +it('rechecks stable memory after the storage fence before releasing a protected memory hold',async()=>{ + const f=fixture({version:2,paused:true,resumePending:true,holds:['manual','memory','storage_error'],recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);let entered!:()=>void,release!:()=>void,stable=true; + const waiting=new Promise(r=>entered=r),held=new Promise(r=>release=r); + f.kv.durability.wait=async()=>{entered();await held;return{synced:true,mutationFailures:0};}; + const recovering=f.control.change('resume',{source:'memory',canResume:async()=>stable});await waiting;stable=false;release();await recovering; + expect(f.control.snapshot().holds).toEqual(['manual','memory','storage_error']);expect(f.record().holds).toEqual(['manual','memory','storage_error']); + expect(f.control.isPaused()).toBe(true); +}); +it('requires a new manual resume after the protected memory release completes',async()=>{ + const f=fixture({version:2,paused:true,resumePending:true,holds:['manual','memory','storage_error'],recovery:{attempts:0,nextAttemptAt:0}}); + await f.control.init(f.kv);let entered!:()=>void,release!:()=>void; + const waiting=new Promise(r=>entered=r),held=new Promise(r=>release=r); + f.kv.durability.wait=async()=>{entered();await held;return{synced:true,mutationFailures:0};}; + const recovering=f.control.change('resume',{source:'memory',canResume:async()=>true});await waiting;let callbacks=0; + const queued=f.control.change('resume',{beforeResume:async()=>{callbacks++;return true;}});release();await recovering;await queued; + expect(callbacks).toBe(0);expect(f.control.snapshot()).toMatchObject({holds:['manual','storage_error'],pausedRequested:true}); + await f.control.change('resume',{beforeResume:async()=>{callbacks++;return true;}});expect(callbacks).toBe(1);expect(f.control.isPaused()).toBe(false); +}); From 87a3d10026b5a727e059c12d6ed9416cfacf84a5 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 10 Nov 2026 22:50:48 +0900 Subject: [PATCH 10/23] fix: complete retained embeddings and tune memory protection --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 6 + docs/customizations/RETAINED-EMBEDDING-65.md | 29 ++++ integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- src/functions/export-import.ts | 2 +- src/index.ts | 1 + src/ops/embedding-recovery.d.mts | 1 + src/ops/embedding-recovery.mjs | 36 ++++- src/ops/memory-pressure.mjs | 2 +- src/state/index-persistence.ts | 18 ++- src/types.ts | 8 +- src/version.ts | 2 +- test/operations-protection-recovery.test.ts | 17 ++- test/retained-embedding-publication.test.ts | 145 +++++++++++++++++++ 28 files changed, 272 insertions(+), 31 deletions(-) create mode 100644 docs/customizations/RETAINED-EMBEDDING-65.md create mode 100644 test/retained-embedding-publication.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index a918aa9cc6..709e1db867 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 4def5e9139..b4b21799e1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.64) +## Current Stats (v0.9.32-daniel.65) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index cd453f127a..8bdef213c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,11 @@ ## [Unreleased] +## [0.9.32-daniel.65] — 2026-11-10 +- Complete a retained embedding retry only when a fresh embedding of the current canonical source exactly matches the retained WAL and loaded vector bytes and session, with current native checkpoint/receipt evidence revalidated during publication. Preserve the original WAL and vector mutation guard; changed or missing evidence remains pending. Retain bounded prior retry and commit metadata with the SDK-only completion marker. +- Apply the operator's 2026-11-10 memory tuning: pause below18% available, recover above22% available continuously for120seconds. Keep the2GiB pause floor,3GiB recovery floor,5%/512MiB critical boundary and existing storage/manual holds. +- Implementation and focused regression evidence are recorded in `docs/customizations/RETAINED-EMBEDDING-65.md`. Operating application, selected capture recovery and long-term memory review remain separate acceptance steps. + ## [0.9.32-daniel.64] — 2026-11-08 ## [0.9.32-daniel.63] — 2026-11-07 - Keep fresh SDK-v2 source retention and reference admission under one lease. Share the native hook's original deadline across lock acquisition and transport, reserving 750ms for final state recording. Preserve retained-source acknowledgement if reference admission fails, retain the default 150ms lock contract without an explicit deadline, and leave exhausted pending work queued before any send. Unknown transport outcomes remain held; existing held/sending records never become a successful pending result merely because time ran out. @@ -603,6 +608,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.65]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.64...v0.9.32-daniel.65 [0.9.32-daniel.64]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.63...v0.9.32-daniel.64 [0.9.32-daniel.63]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.62...v0.9.32-daniel.63 [0.9.32-daniel.62]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.61...v0.9.32-daniel.62 diff --git a/docs/customizations/RETAINED-EMBEDDING-65.md b/docs/customizations/RETAINED-EMBEDDING-65.md new file mode 100644 index 0000000000..346446db92 --- /dev/null +++ b/docs/customizations/RETAINED-EMBEDDING-65.md @@ -0,0 +1,29 @@ +# daniel.65 — retained embedding publication and memory calibration + +Base: operating .64 source `152fa918a8449b3b3eff22d5020f3d1ad6001329`. Status: isolated source implementation, not yet deployed. The wrapper workspace's `work/forced-shutdown-recovery-2026-11-10/` records actual validation and later activation. + +The operator approved recovery of four embedding retries and capture backlog following a forced-poweroff boot failure, then explicitly selected18% memory pause/22% recovery on2026-11-10. The separate root-owned .64 self-service crash tool has already been installed and used; it is not bundled as a silently compatible .65 tool. The next deployment must version-match its coldboot and self-service helpers. + +## Retained vectors + +The original recovery intentionally retains WAL rows and forbids mutation of their IDs. Ordinary embedding retries previously called index.add and could never finish those IDs. The worker now compares a freshly source-derived Float32Array with both retained and loaded vector bytes and session. It reuses the existing current native checkpoint/retention receipt verifier without authorizing or writing new coverage. Only exact success skips index.add. Source projection and intent generation are checked again after verification. + +Publication requires the same proof again before and after the existing SDK fence. An ID known as retained cannot fall back to ordinary publication if its WAL disappears. Add/remove/clear remain protected. There is no approximate similarity, original WAL deletion, new API, storage timeout extension or mutation-guard exception. + +The SDK committed marker preserves one bounded previous intent/commit snapshot with original attempts, error, generation and fingerprint metadata. It includes completion=sdk/verified=false/synced=false. Existing metadata is history, not source/vector provenance. Physical WAL/bucket bytes and receipts remain untouched. + +The existing embedding receipts view may still show index_pending because retained WAL remains present. Completion requires the worker's pending result and current committed/source/index proofs; WAL0 is not a target. A nondeterministic or different provider result remains pending. + +## Memory + +The pause boundary changes from max(2GiB,total×20%) to max(2GiB,total×18%). Recovery changes from max(3GiB,total×25%) to max(3GiB,total×22%) and still requires strict greater-than for120continuous seconds, fresh post-fence samples, bounded attempts and unchanged hold ownership. Critical remains max(512MiB,total×5%). Existing manual/storage/deployment holds are not waived. + +## Verification and operation + +The new four-item publication regression failed before implementation and passed after it. Refusals cover byte mismatch including negative zero, wrong owner, stale/missing receipt, changed checkpoint, source/generation races, paused admission, and loss of receipt or WAL during publication. Tests use synthetic namespace archives and the real StateKV/proof code; they are not a real native-engine process replay or operating repair. + +Focused embedding204tests and memory56tests passed before the independent review's final WAL-loss regression; the additional regression's RED/GREEN proof and combined72tests are in the wrapper logs. All39 build configurations, copied assets and SDK bundle audit passed. The built default-fork suite passed6547tests in561files, with13conditional skips in4files, inside isolated user/network/mount namespaces with temporary HOME and masked operating paths. Integration and the unchanged12GiB summary boundary fixture were excluded. Typecheck exited2 with the same30 normalized baseline diagnostics and no added diagnostics. Package/native acceptance and deployment remain pending at this source-note stage. Do not claim all backlog completion from these tests. + +The real patched a44eba0c native engine and SDK passed an additional isolated acceptance: four synthetic retained retries completed after one conservative publication retry (seven deterministic synthetic inference calls), with byte-identical original WAL, vector bucket and source files. All four receipts remained; mutation guards still rejected add/remove/clear. Two identity-checked SIGTERM stops exited0, and a fresh native process read back all four committed markers, absent retry rows and unchanged originals. Current epoch evidence used actual processes/sockets; the fixture's prior different-boot marker and provider were synthetic. This does not certify a fresh post-restart writer lease, packaged CLI or operating completion. Evidence: workspace `native-proof/result-am65-native-_ii31xyl.json`. + +Deployment must preserve patched a44eba0c engine, original client13files, all operational source/cursors/attempts/Lesson/metrics/retained WAL, and issued prior kits. Normal update admission must genuinely satisfy its storage guard. No historical write is made verified by a new SDK-only completion. Long-term memory is pending separate manual review. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index afc2152579..dc41cac63b 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.64 +version: 0.9.32-daniel.65 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 7280e1e44d..593b797030 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index 052294cb86..854a2bf384 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 1bc0bd7323..de593ea2aa 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index 74b12e8b79..d62181326c 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.64 +version: 0.9.32-daniel.65 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 6106f480ac..785b98fc4e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 1caae6449c..9b9b31e920 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.64" + "@agentmemory/agentmemory": "0.9.32-daniel.65" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 0a128fb31a..b7bf700e95 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index b0a8fcd04e..fef2447a4c 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index 9cdb0a0fac..14df0e280c 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.64" + "@agentmemory/mcp@0.9.32-daniel.65" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 2baddb57a7..4d596f354c 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 27aa0f2da3..b2707f75d3 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 752d04b041..5ce187c64c 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.64"; +const VERSION = "0.9.32-daniel.65"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index bb0c676e69..148afbacc3 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.64", + "version": "0.9.32-daniel.65", "facts": { "mcpTools": [ "55" diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 883d8fdf47..9561c01aaa 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/index.ts b/src/index.ts index 2874a2b64b..22dc98d9b4 100644 --- a/src/index.ts +++ b/src/index.ts @@ -678,6 +678,7 @@ async function main() { operationalState.embeddingRecovery = lifecycle.track(registerEmbeddingRecovery({ kv, KV, index: vectorIndex, provider: embeddingProvider, readiness, withKeyedLock, logger, schedule: false, persistIndex: (publication?: VectorPublication) => indexPersistence.saveVerified(publication), + verifyRetainedPublication: publication => indexPersistence.verifyRetainedVectorPublication(publication), })); await operationalState.embeddingRecovery.initialize(); } diff --git a/src/ops/embedding-recovery.d.mts b/src/ops/embedding-recovery.d.mts index edce6ca9cc..b313e62804 100644 --- a/src/ops/embedding-recovery.d.mts +++ b/src/ops/embedding-recovery.d.mts @@ -27,4 +27,5 @@ export function registerEmbeddingRecovery(options: { logger?: Pick; clock?: () => number; schedule?: boolean; onIndexChanged?: () => void; persistIndex?: (publication?: VectorPublication) => Promise; + verifyRetainedPublication?: (publication: VectorPublication) => Promise; }): EmbeddingRecovery; diff --git a/src/ops/embedding-recovery.mjs b/src/ops/embedding-recovery.mjs index 8794e5ad61..2e350198af 100644 --- a/src/ops/embedding-recovery.mjs +++ b/src/ops/embedding-recovery.mjs @@ -4,7 +4,7 @@ import {networkErrorCode} from './provider-readiness.mjs'; export const EMBEDDING_RETRY_NAMESPACE='mem:embedding-retry:v1'; export const EMBEDDING_COMMITTED_NAMESPACE='mem:embedding-committed:v1'; const digest=text=>createHash('sha256').update(text).digest('hex'); -export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKeyedLock=async(k,fn)=>fn(),logger,clock=Date.now,schedule=true,onIndexChanged,persistIndex}) { +export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKeyedLock=async(k,fn)=>fn(),logger,clock=Date.now,schedule=true,onIndexChanged,persistIndex,verifyRetainedPublication}) { const state={pendingCount:0,completedCount:0,counterEpoch:randomUUID(),initialized:false,lastError:null,lastSuccessAt:null}; let pumping=false,reconciled=false,stopped=false,started=false,interval=null,initialization=null,committedRows=null,committedOffset=0; const active=new Set(),sourceGuards=new Set(),publications=new Map(),accepted=new Map(),pendingIds=new Set(); @@ -162,7 +162,8 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe const canonical=await current(item); if(canonical!==null&&digest(canonical)!==fingerprint){await retainUnlocked(item,{code:'EMBEDDING_PROJECTION_CHANGED'},false);return;} if(canonical===null){await discardUnlocked(item);return;} - await kv.set(EMBEDDING_COMMITTED_NAMESPACE,item.id,{id:item.id,sessionId:item.sessionId,kind:item.kind,fingerprint,committedAt:new Date(clock()).toISOString()}); + await kv.set(EMBEDDING_COMMITTED_NAMESPACE,item.id,{id:item.id,sessionId:item.sessionId,kind:item.kind,fingerprint,committedAt:new Date(clock()).toISOString(), + ...(queued.retainedRecovery?{retainedRecovery:queued.retainedRecovery}:{})}); await fence([{scope:EMBEDDING_COMMITTED_NAMESPACE,key:item.id}]); await kv.delete(EMBEDDING_RETRY_NAMESPACE,item.id); const latest=await current(item); @@ -193,16 +194,22 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe if(!inMemory&&readiness&&!await readiness.ensureReady()){await retain(item,{code:'PROVIDER_UNAVAILABLE'},false);return false;} const generation=randomUUID(); // Durable intent precedes inference and mutation; restart always reads canonical text. + let previousIntent; await withKeyedLock(intentKey(item.id),async()=>{ forgetPublication(item.id); const queued=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id); + if(verifyRetainedPublication&&queued)previousIntent=Object.fromEntries( + ['id','sessionId','kind','attempts','retryAt','generation','fingerprint','phase','errorCode'].flatMap(key=>{ + const value=queued[key]; + return typeof value==='string'?[[key,value.slice(0,256)]]:Number.isSafeInteger(value)&&value>=0?[[key,value]]:[]; + })); await kv.set(EMBEDDING_RETRY_NAMESPACE,item.id,{...queued,id:item.id,sessionId:item.sessionId,kind:item.kind,attempts:queued?.attempts??0,retryAt:queued?.retryAt??0,generation,fingerprint,phase:inMemory?'embedded':'queued'}); pending(item); if(certify)await certifyIntent(item); }); - return {item,text,generation,fingerprint,inMemory}; + return {item,text,generation,fingerprint,inMemory,previousIntent}; } - async function executePrepared({item,text,generation,fingerprint,inMemory}) { + async function executePrepared({item,text,generation,fingerprint,inMemory,previousIntent}) { if(stopped||backgroundPaused())return false; const queued=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id); if(queued?.generation!==generation||queued.fingerprint!==fingerprint)return false; @@ -214,12 +221,29 @@ export function registerEmbeddingRecovery({kv,KV,index,provider,readiness,withKe const vector=inMemory?null:await provider.embed(text); if(!inMemory&&(!vector||vector.length!==provider.dimensions))throw Object.assign(Error('embedding_dimension_mismatch'),{code:'EMBEDDING_DIMENSION_MISMATCH'}); const ready=await withKeyedLock(intentKey(item.id),async()=>{ - const owned=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id); + let owned=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id); if(owned?.generation!==generation||owned.fingerprint!==fingerprint)return false; const canonical=await current(item); if(canonical===null){await discardUnlocked(item);return false;} if(digest(canonical)!==fingerprint){await retainUnlocked(item,{code:'EMBEDDING_PROJECTION_CHANGED'},false);return false;} - if(vector){index.add(item.id,item.sessionId,vector);accepted.set(item.id,fingerprint);onIndexChanged?.();} + if(vector){ + const reused=verifyRetainedPublication && await verifyRetainedPublication({id:item.id,entry:{sessionId:item.sessionId,embedding:vector}}); + if(!reused){index.add(item.id,item.sessionId,vector);onIndexChanged?.();} + else { + if(stopped||backgroundPaused())return false; + owned=await kv.get(EMBEDDING_RETRY_NAMESPACE,item.id); + if(owned?.generation!==generation||owned.fingerprint!==fingerprint)return false; + const currentText=await current(item); + if(currentText===null||digest(currentText)!==fingerprint)return false; + if(!owned.retainedRecovery){ + const committed=await kv.get(EMBEDDING_COMMITTED_NAMESPACE,item.id); + const previousCommit=committed?Object.fromEntries( + ['id','sessionId','kind','fingerprint','committedAt'].filter(key=>typeof committed[key]==='string').map(key=>[key,committed[key].slice(0,256)])):null; + owned={...owned,retainedRecovery:{version:1,completion:'sdk',verified:false,synced:false,previousIntent:previousIntent??null,previousCommit}}; + } + } + accepted.set(item.id,fingerprint); + } await kv.set(EMBEDDING_RETRY_NAMESPACE,item.id,{...owned,phase:'embedded'}); return true; }); diff --git a/src/ops/memory-pressure.mjs b/src/ops/memory-pressure.mjs index 7859be589d..6af2f1ba49 100644 --- a/src/ops/memory-pressure.mjs +++ b/src/ops/memory-pressure.mjs @@ -16,7 +16,7 @@ export function createMemoryPressureGuard({control,readSample=readHostMemory,sch async function readFresh(){ const sequence=++sampleSequence,before=clock(),m=await readSample(),now=clock(); if(sequence!==sampleSequence||!m||!Number.isFinite(m.total)||m.total<=0||!Number.isFinite(m.available)||m.available<0||m.available>m.total||!Number.isFinite(now)||now10000)throw Error('memory_sample_unavailable'); - const reserve=Math.max(2*GiB,m.total*.20),critical=Math.max(GiB/2,m.total*.05),recoveryBytes=Math.max(3*GiB,m.total*.25); + const reserve=Math.max(2*GiB,m.total*.18),critical=Math.max(GiB/2,m.total*.05),recoveryBytes=Math.max(3*GiB,m.total*.22); state={...state,level:m.availablerecoveryBytes}; } diff --git a/src/state/index-persistence.ts b/src/state/index-persistence.ts index 91124d2506..47134b03d0 100644 --- a/src/state/index-persistence.ts +++ b/src/state/index-persistence.ts @@ -354,7 +354,8 @@ export class IndexPersistence { const validMeta = meta === null ? expected === null && bucket === undefined : meta.v === 3 && Number.isInteger(meta.count) && meta.count >= (expected ? 1 : 0) && Number.isInteger(meta.bucketCount) && meta.bucketCount >= 0 && (bucket === undefined || bucket < meta.bucketCount); - if (!isDeepStrictEqual(row, expected) || pending !== null || clear !== null || !validMeta) throw unverified(); + if (!isDeepStrictEqual(row, expected) || clear !== null || !validMeta || + ((pending !== null || this.retainedRows.has(id)) && !await this.verifyRetainedVectorPublication(publication))) throw unverified(); }; await Promise.all([this.logChains.get(id), this.logChains.get(PENDING_CLEAR_KEY)]); await check(); @@ -567,6 +568,21 @@ export class IndexPersistence { } catch { return false; } } + async verifyRetainedVectorPublication(publication: VectorPublication): Promise { + const retained = this.retainedRows.get(publication.id), entry = publication.entry; + if (this.kv.durability?.completion !== 'sdk' || !retained || !entry || !(entry.embedding instanceof Float32Array)) return false; + const matches = () => { + const loaded = this.vector?.get(publication.id); + return entry.sessionId === retained.s && float32ToBase64(entry.embedding) === retained.e && + loaded?.sessionId === retained.s && float32ToBase64(loaded.embedding) === retained.e; + }; + try { + if (!matches()) return false; + const pending = await this.kv.get(KV.vectorPendingLog, publication.id); + return await this.verifyCaptureVectorPending(publication.id, entry.sessionId, pending) && matches(); + } catch { return false; } + } + private rememberRetained(rows: RecoveryUpsert[]): void { this.retainedRows = new Map(rows.map(row => [row.id, row])); for (const row of rows) this.seq = Math.max(this.seq, row.q); diff --git a/src/types.ts b/src/types.ts index c378d04223..9b13c4a09f 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; @@ -1132,6 +1132,7 @@ export interface EmbeddingIntent { fingerprint?: string; phase?: "queued" | "embedded"; errorCode?: string; + retainedRecovery?: EmbeddingCommit['retainedRecovery']; } export interface EmbeddingCommit { id: string; @@ -1139,6 +1140,11 @@ export interface EmbeddingCommit { kind: EmbeddingIntent["kind"]; fingerprint: string; committedAt: string; + retainedRecovery?: { + version: 1; completion: 'sdk'; verified: false; synced: false; + previousIntent: Omit | null; + previousCommit: Omit | null; + }; } export interface CaptureSdkIndexEvidence { diff --git a/src/version.ts b/src/version.ts index a91d10bfeb..f30021be59 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.64"; +export const VERSION = "0.9.32-daniel.65"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/operations-protection-recovery.test.ts b/test/operations-protection-recovery.test.ts index 11a318be62..2f4945583d 100644 --- a/test/operations-protection-recovery.test.ts +++ b/test/operations-protection-recovery.test.ts @@ -15,7 +15,7 @@ it('persists distinct overlapping holds and never automatically releases manual }); it('recovers only after strictly greater recovery threshold and sustained fresh samples',async()=>{ const f=fixture();await f.control.init(f.kv);await f.guard.refresh();await f.control.settled();expect(f.control.snapshot().holds).toEqual(['memory']); - f.memory(4*GiB);for(let i=0;i<30;i++){f.time(f.clock()+5000);await f.guard.refresh();}expect(f.control.isPaused()).toBe(true); + f.memory(16*GiB*.22);for(let i=0;i<30;i++){f.time(f.clock()+5000);await f.guard.refresh();}expect(f.control.isPaused()).toBe(true); await f.normal(115000);expect(f.control.isPaused()).toBe(true);f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain();expect(f.control.isPaused()).toBe(false); expect(f.record()).toMatchObject({version:2,paused:false,resumePending:true,recovery:{attempts:1}}); }); @@ -112,7 +112,20 @@ it('bounds automatic attempts durably and honors persisted backoff',async()=>{ const g=fixture({version:2,paused:true,resumePending:false,holds:['memory'],recovery:{attempts:1,nextAttemptAt:999999}});await g.control.init(g.kv);await g.normal();expect(g.control.isPaused()).toBe(true);expect(g.record().recovery.attempts).toBe(1); }); it('uses exact pressure boundaries and never recovers with unavailable samples',async()=>{ - const f=fixture();await f.control.init(f.kv);f.memory(16*GiB*.2);await f.guard.refresh();expect(f.guard.snapshot().level).toBe('normal');f.memory(16*GiB*.05);await f.guard.refresh();expect(f.guard.snapshot().level).toBe('high');await f.control.settled();f.memory(NaN);await f.normal(0);f.memory(NaN);f.time(f.clock()+120000);await f.guard.refresh();expect(f.control.isPaused()).toBe(true); + const f=fixture();await f.control.init(f.kv);f.memory(16*GiB*.18);await f.guard.refresh();expect(f.guard.snapshot().level).toBe('normal');f.memory(16*GiB*.05);await f.guard.refresh();expect(f.guard.snapshot().level).toBe('high');await f.control.settled();f.memory(NaN);await f.normal(0);f.memory(NaN);f.time(f.clock()+120000);await f.guard.refresh();expect(f.control.isPaused()).toBe(true); +}); + +it('uses the approved 18% reserve and recovers only above 22% for two minutes',async()=>{ + const f=fixture();await f.control.init(f.kv); + f.memory(16*GiB*.18-1);await f.guard.refresh();await f.guard.drain();await f.control.settled(); + expect(f.guard.snapshot()).toMatchObject({level:'high',reserveBytes:16*GiB*.18,recoveryBytes:16*GiB*.22,criticalBytes:16*GiB*.05}); + f.memory(16*GiB*.18);f.time(f.clock()+5000);await f.guard.refresh();expect(f.guard.snapshot().level).toBe('normal'); + f.memory(16*GiB*.22);for(let i=0;i<30;i++){f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain();} + expect(f.control.isPaused()).toBe(true); + f.memory(16*GiB*.22+1);for(let i=0;i<24;i++){f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain();} + expect(f.control.isPaused()).toBe(true); + f.time(f.clock()+5000);await f.guard.refresh();await f.guard.drain();expect(f.control.isPaused()).toBe(false); + await f.guard.stop(); }); it('retains cumulative attempts through repeated pressure and clean restart until manual acknowledgment',async()=>{ const f=fixture();await f.control.init(f.kv); diff --git a/test/retained-embedding-publication.test.ts b/test/retained-embedding-publication.test.ts new file mode 100644 index 0000000000..8d4b8d20a3 --- /dev/null +++ b/test/retained-embedding-publication.test.ts @@ -0,0 +1,145 @@ +import {afterEach,expect,it,vi} from 'vitest'; +import {createHash} from 'node:crypto'; +import {mkdtempSync,readFileSync,rmSync,writeFileSync} from 'node:fs'; +import {join} from 'node:path'; +import {tmpdir} from 'node:os'; +import {StateKV} from '../src/state/kv.js'; +import {KV} from '../src/state/schema.js'; +import {IndexPersistence,vectorBucketScope} from '../src/state/index-persistence.js'; +import {VectorIndex,float32ToBase64} from '../src/state/vector-index.js'; +import {acquireFileWriterLease} from '../src/ops/file-writer-lease.mjs'; +import {registerEmbeddingRecovery} from '../src/ops/embedding-recovery.mjs'; +import {withKeyedLock} from '../src/state/keyed-mutex.js'; +import {createBackgroundControl,installBackgroundControl} from '../src/ops/background-control.mjs'; +import {engineFixture} from './helpers/engine-evidence.js'; + +const cleanups:Array<()=>Promise>=[]; +afterEach(async()=>{for(const close of cleanups.splice(0))await close();installBackgroundControl(null as never);vi.unstubAllEnvs();vi.restoreAllMocks();}); +function archive(value:unknown){ + const bytes=Buffer.from(JSON.stringify(value)); + if(bytes.length<=8){const inline=Buffer.alloc(8,0xff);bytes.copy(inline);return inline;} + const root=Math.ceil(bytes.length/4)*4,out=Buffer.alloc(root+8); + bytes.copy(out);out.writeUInt32LE((bytes.length&63)+128+Math.floor(bytes.length/64)*256,root);out.writeInt32LE(-root,root+4);return out; +} +async function fixture(){ + const store=mkdtempSync(join(tmpdir(),'am-retained-embedding-'));vi.stubEnv('AGENTMEMORY_STATE_STORE_PATH',store); + const {evidence}=engineFixture(store),lease=acquireFileWriterLease(store,{evidence}); + const data=new Map>(),disk=(scope:string)=>join(store,encodeURIComponent(scope)+'.bin'); + const write=(scope:string)=>writeFileSync(disk(scope),archive(Object.fromEntries(data.get(scope)??[]))); + const embedding=new Float32Array([1,0]),rows=[1,2,3,4].map(q=>({id:'obs_retained_'+q,s:'session',q,e:float32ToBase64(embedding),k:'observation'})); + const oldCommit={id:rows[3].id,sessionId:'session',kind:'synthetic',fingerprint:'0'.repeat(64),committedAt:'2025-01-01T00:00:00.000Z'}; + data.set(KV.bm25Index,new Map([['vectors:meta',{v:3,count:4,bucketCount:1,savedAt:'2026-01-01T00:00:00.000Z'}]])); + data.set(vectorBucketScope(0),new Map(rows.map(({id,s,e})=>[id,{id,s,e}]))); + data.set(KV.vectorPendingLog,new Map(rows.map(row=>[row.id,row]))); + data.set(KV.observations('session'),new Map(rows.map(({id})=>[id,{id,sessionId:'session',title:'canonical '+id,narrative:'source text',sourceRaw:{original:'preserved synthetic'}}]))); + const fingerprint=(id:string)=>createHash('sha256').update('canonical '+id+' source text').digest('hex'); + const retries=rows.map(({id})=>({id,sessionId:'session',kind:'observation',attempts:3,retryAt:0,generation:'previous-'+id,fingerprint:fingerprint(id),phase:'queued',errorCode:'VECTOR_RECOVERY_PAUSED'})); + data.set(KV.embeddingRetry,new Map(retries.map(row=>[row.id,row]))); + data.set(KV.embeddingCommitted,new Map([[oldCommit.id,oldCommit]])); + for(const scope of data.keys())write(scope); + const actions:Array<{scope:string;key:string;op:string}>=[]; + const sdk={trigger:async({function_id,payload:{scope,key,value}}:any)=>{ + const table=data.get(scope)??new Map(); + if(function_id==='state::get')return structuredClone(table.get(key)??null); + if(function_id==='state::list')return structuredClone([...table.values()]); + if(function_id==='state::set'){data.set(scope,table);table.set(key,structuredClone(value));write(scope);actions.push({scope,key,op:'set'});return value;} + if(function_id==='state::delete'){table.delete(key);write(scope);actions.push({scope,key,op:'delete'});return;} + throw Error('unexpected synthetic SDK call'); + }}; + const kv=new StateKV(sdk as never,{writerLease:lease}),index=new VectorIndex();let held=true,epoch=0; + const persistence=new IndexPersistence(kv,index,{requireRecoveryPlan:true,isStorageHeld:()=>held,storageGeneration:()=>epoch}); + await persistence.load();held=false;expect(await persistence.resumeStorageRecovery(2,true)).toBe(true); + const provider={name:'synthetic',dimensions:2,embed:vi.fn(async(_text:string)=>new Float32Array(embedding)),embedBatch:async(texts:string[])=>texts.map(()=>new Float32Array(embedding))}; + const recovery=registerEmbeddingRecovery({kv,KV,index,provider,withKeyedLock,schedule:false, + verifyRetainedPublication:publication=>persistence.verifyRetainedVectorPublication(publication), + persistIndex:publication=>persistence.saveVerified(publication)}); + cleanups.push(async()=>{recovery.stop();await recovery.drain();persistence.stop();lease.close();await kv.durability?.drain();rmSync(store,{recursive:true,force:true});}); + const wal=readFileSync(disk(KV.vectorPendingLog)),buckets=readFileSync(disk(vectorBucketScope(0))); + actions.length=0; + return{kv,index,persistence,recovery,provider,rows,retries,oldCommit,data,write,disk,actions,wal,buckets, + item:(n=0)=>({id:rows[n].id,sessionId:'session',kind:'observation' as const}), + changeEpoch:()=>{epoch++;},hold:()=>{held=true;}, + assertOriginals:()=>{expect(readFileSync(disk(KV.vectorPendingLog))).toEqual(wal);expect(readFileSync(disk(vectorBucketScope(0)))).toEqual(buckets);}, + }; +} + +it('publishes all four freshly reembedded exact retained vectors without mutating WAL or vectors',async()=>{ + const f=await fixture();await f.recovery.pump();await f.recovery.drain(); + expect(f.provider.embed).toHaveBeenCalledTimes(4);expect(f.recovery.snapshot()).toMatchObject({pendingCount:0,completedCount:4,lastError:null,publicationEvidence:{completion:'sdk'}}); + for(const [n,row] of f.rows.entries()){ + expect(f.provider.embed).toHaveBeenCalledWith('canonical '+row.id+' source text'); + expect(await f.kv.get(KV.embeddingRetry,row.id)).toBeNull(); + const marker:any=await f.kv.get(KV.embeddingCommitted,row.id); + expect(marker.fingerprint).toBe(f.retries[n].fingerprint); + expect(marker.retainedRecovery).toMatchObject({version:1,completion:'sdk',verified:false,synced:false,previousIntent:f.retries[n]}); + expect(marker.retainedRecovery.previousCommit).toEqual(n===3?f.oldCommit:null); + expect(f.recovery.observedPublication(row.id)).toMatchObject({completion:'sdk',durable:false}); + } + expect(f.actions.filter(a=>a.scope===KV.vectorPendingLog||a.scope.startsWith(KV.bm25Index+':vec:')||a.scope===KV.vectorRetentionReceipts)).toEqual([]); + f.assertOriginals();expect(f.index.pendingChanges).toBe(0); + expect(f.persistence.status()).toMatchObject({pendingLog:4,retainedCheckpointRows:4,pendingLogAcknowledged:0}); + expect(()=>f.index.add(f.rows[0].id,'session',new Float32Array([1,0]))).toThrow(/VECTOR_RECOVERY_PAUSED/); + expect(()=>f.index.remove(f.rows[0].id)).toThrow(/VECTOR_RECOVERY_PAUSED/);expect(()=>f.index.clear()).toThrow(/VECTOR_RECOVERY_PAUSED/); +}); + +it.each(['different bytes','negative zero','wrong owner','epoch changed','missing receipt','stale receipt','changed checkpoint'])('retains an exact original on %s',async mode=>{ + const f=await fixture(); + if(mode==='different bytes')f.provider.embed.mockResolvedValue(new Float32Array([0,1])); + if(mode==='negative zero')f.provider.embed.mockResolvedValue(new Float32Array([1,-0])); + if(mode==='wrong owner')f.provider.embed.mockImplementation(async()=>{f.index.get(f.rows[0].id)!.sessionId='other';return new Float32Array([1,0]);}); + if(mode==='epoch changed')f.provider.embed.mockImplementation(async()=>{f.changeEpoch();return new Float32Array([1,0]);}); + if(mode==='missing receipt'||mode==='stale receipt'){ + const table=f.data.get(KV.vectorRetentionReceipts)!; + if(mode==='missing receipt')table.clear();else{const first=table.keys().next().value!;table.get(first).q++;} + f.write(KV.vectorRetentionReceipts); + } + if(mode==='changed checkpoint'){f.data.get(vectorBucketScope(0))!.get(f.rows[0].id).e=float32ToBase64(new Float32Array([0,1]));f.write(vectorBucketScope(0));} + await f.recovery.add(f.item());await f.recovery.drain(); + expect(await f.kv.get(KV.embeddingRetry,f.rows[0].id)).not.toBeNull();expect(await f.kv.get(KV.embeddingCommitted,f.rows[0].id)).toBeNull(); + expect(f.recovery.snapshot()).toMatchObject({completedCount:0});expect(f.recovery.observedPublication(f.rows[0].id)).toBeNull(); + expect(readFileSync(f.disk(KV.vectorPendingLog))).toEqual(f.wal); +}); + +it.each(['source','intent'])('rejects a changed %s during retained physical verification',async mode=>{ + const f=await fixture(),verify=f.persistence.verifyCaptureVectorPending.bind(f.persistence); + vi.spyOn(f.persistence,'verifyCaptureVectorPending').mockImplementation(async(...args)=>{ + const valid=await verify(...args); + if(mode==='source')await f.kv.set(KV.observations('session'),f.rows[0].id,{id:f.rows[0].id,sessionId:'session',title:'changed',narrative:'source text'}); + else await f.kv.set(KV.embeddingRetry,f.rows[0].id,{...await f.kv.get(KV.embeddingRetry,f.rows[0].id),generation:'new-owner'}); + return valid; + }); + await f.recovery.add(f.item());await f.recovery.drain(); + expect(await f.kv.get(KV.embeddingRetry,f.rows[0].id)).not.toBeNull();expect(await f.kv.get(KV.embeddingCommitted,f.rows[0].id)).toBeNull();f.assertOriginals(); +}); + +it.each(['receipt','WAL'])('rechecks %s evidence during publication instead of trusting earlier reuse',async evidence=>{ + const f=await fixture(),save=f.persistence.saveVerified.bind(f.persistence); + vi.spyOn(f.persistence,'saveVerified').mockImplementation(async publication=>{ + if(evidence==='receipt'){f.data.get(KV.vectorRetentionReceipts)!.clear();f.write(KV.vectorRetentionReceipts);} + else{f.data.get(KV.vectorPendingLog)!.delete(f.rows[0].id);f.write(KV.vectorPendingLog);} + return save(publication); + }); + await f.recovery.add(f.item());await f.recovery.drain(); + expect(await f.kv.get(KV.embeddingRetry,f.rows[0].id)).not.toBeNull();expect(await f.kv.get(KV.embeddingCommitted,f.rows[0].id)).toBeNull(); + if(evidence==='receipt')f.assertOriginals(); + else expect(readFileSync(f.disk(vectorBucketScope(0)))).toEqual(f.buckets); +}); + +it('does not infer or reuse retained vectors while background admission is paused',async()=>{ + const f=await fixture(),control=createBackgroundControl();await control.init(f.kv);installBackgroundControl(control);await control.change('pause');await control.settled(); + await f.recovery.add(f.item());await f.recovery.pump();await f.recovery.drain(); + expect(f.provider.embed).not.toHaveBeenCalled();expect(await f.kv.get(KV.embeddingRetry,f.rows[0].id)).not.toBeNull();f.assertOriginals(); +}); + +it('keeps completed SDK metadata and retained WAL valid after a new persistence worker loads them',async()=>{ + const f=await fixture();await f.recovery.pump();await f.recovery.drain(); + const nextIndex=new VectorIndex(),nextPersistence=new IndexPersistence(f.kv,nextIndex,{requireRecoveryPlan:true}); + try { + const loaded=await nextPersistence.load();expect(loaded.state).toBe('buckets');await nextPersistence.prepareBackfill(loaded);nextIndex.restoreFrom(loaded.vector!); + expect(await nextPersistence.replayPendingLog(2)).toMatchObject({entries:0,added:0}); + expect(nextIndex.size).toBe(4);expect(nextPersistence.status()).toMatchObject({pendingLog:4,retainedCheckpointRows:4,pendingChanges:0}); + for(const row of f.rows)expect(await nextPersistence.verifyRetainedVectorPublication({id:row.id,entry:nextIndex.get(row.id)!})).toBe(true); + expect(()=>nextIndex.remove(f.rows[0].id)).toThrow(/VECTOR_RECOVERY_PAUSED/); + f.assertOriginals(); + }finally{nextPersistence.stop();} +}); From 746a3dda6a20314ad403426809d6d66167f69326 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 11 Nov 2026 00:49:24 +0900 Subject: [PATCH 11/23] fix: expose bounded retained vector proof diagnostics --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 6 + .../RETAINED-PROOF-DIAGNOSTICS.md | 15 ++ integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- src/functions/export-import.ts | 2 +- src/state/index-persistence.ts | 128 ++++++++++++++++-- src/types.ts | 2 +- src/version.ts | 2 +- test/retained-embedding-publication.test.ts | 105 ++++++++++++++ 23 files changed, 265 insertions(+), 31 deletions(-) create mode 100644 docs/customizations/RETAINED-PROOF-DIAGNOSTICS.md diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 709e1db867..ff858abcbd 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index b4b21799e1..263b0381d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.65) +## Current Stats (v0.9.32-daniel.66) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bdef213c3..0c5c1a1212 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,11 @@ ## [Unreleased] +## [0.9.32-daniel.66] — 2026-11-10 +- Add one bounded, in-memory final retained-vector proof diagnostic to the existing persistence status. Report only a known retained ID, an enumerated result, fresh/loaded exact-byte and session matches, admission/queue/revision state, and an allowlisted physical-proof error code. Do not retain provider vector bytes, original text, arbitrary error messages or unknown requested IDs. +- Preserve retained publication/capture verification decisions, exact Float32 byte comparison (including negative zero), physical checkpoint and receipt proof, mutation guards, SDK-only completion and existing retry/backoff. This change explains later attempts; it cannot reconstruct the fresh vector or physical race from earlier .65 failures. +- Prepared separately from source `87a3d10026b5a727e059c12d6ed9416cfacf84a5`, with the parent-authorized .66 version metadata synchronized. Commit, packaging and deployment remain pending parent review. Validation and limits: `docs/customizations/RETAINED-PROOF-DIAGNOSTICS.md`. Long-term memory recording remains pending manual review. + ## [0.9.32-daniel.65] — 2026-11-10 - Complete a retained embedding retry only when a fresh embedding of the current canonical source exactly matches the retained WAL and loaded vector bytes and session, with current native checkpoint/receipt evidence revalidated during publication. Preserve the original WAL and vector mutation guard; changed or missing evidence remains pending. Retain bounded prior retry and commit metadata with the SDK-only completion marker. - Apply the operator's 2026-11-10 memory tuning: pause below18% available, recover above22% available continuously for120seconds. Keep the2GiB pause floor,3GiB recovery floor,5%/512MiB critical boundary and existing storage/manual holds. @@ -608,6 +613,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.66]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.65...v0.9.32-daniel.66 [0.9.32-daniel.65]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.64...v0.9.32-daniel.65 [0.9.32-daniel.64]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.63...v0.9.32-daniel.64 [0.9.32-daniel.63]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.62...v0.9.32-daniel.63 diff --git a/docs/customizations/RETAINED-PROOF-DIAGNOSTICS.md b/docs/customizations/RETAINED-PROOF-DIAGNOSTICS.md new file mode 100644 index 0000000000..a040eeb735 --- /dev/null +++ b/docs/customizations/RETAINED-PROOF-DIAGNOSTICS.md @@ -0,0 +1,15 @@ +# Bounded retained-proof diagnostics — preparation only + +The .65 retained retry path intentionally requires exact equality between a newly computed Float32 embedding, the retained WAL row and the loaded vector/session, followed by the existing current checkpoint/receipt proof. An ordinary `VECTOR_RECOVERY_PAUSED` retry result does not distinguish fresh-byte mismatch from physical proof rejection. Earlier fresh provider bytes were not retained, so the earlier cause remains unknown. + +This draft adds `indexPersistence.retainedProofLastCheck` to the existing status object. Existing health/status/snapshot callers already pass that object through. It is null until a known retained ID is checked or when local diagnostic sampling becomes unavailable, holds only one final result, and returns a defensive copy. Unknown IDs never replace it. The operation distinguishes capture-pending validation from retained-publication validation. A publication result includes only a newly observed same-ID inner capture proof reason/code, so an earlier verified result cannot label a later rejection. + +The fixed shape contains the known retained ID, operation and reason enum; fresh/loaded byte and session match booleans; retention readiness; stopped/storage hold/generation/recovering/blocked/paused flags; pending log/log-chain/dirty counts; revision-change flag; and an allowlisted physical proof error code. A null match/revision field means it was not observed for that path. Capture-pending has no fresh provider bytes, so `freshBytesMatch` is null; its session match refers to the supplied selected session. No vector, base64, source text, free-form exception, stack or secret is retained. Unknown errors map to `UNCLASSIFIED_PROOF_ERROR`. + +Diagnostics sample local state at the final decision, without further SDK or file reads/writes. The snapshot is observational and is not an atomic proof, a new receipt or a success override. Diagnostic collection is best effort and cannot change a verification decision. The original current/matches predicates, reconciliation arguments, exact comparisons, retained mutation guard, SDK completion and retry/backoff remain unchanged. Physical proof still retains every existing refusal. No new endpoint, background work, inference, replay, data repair or migration is introduced. + +Prepared as `0.9.32-daniel.66` on `fix/retained-proof-diagnostics` in an isolated clone based on `87a3d10026b5a727e059c12d6ed9416cfacf84a5`, after parent authorization to prepare the version bump. Official docs sync propagates the version. This draft is not a .66 activation. The issued .65 source/build/kit and operating data were not modified. + +Validation: the initial diagnostic regression had 20 expected failures with the original implementation while the original 14 retained tests passed. All 37 retained tests pass, including separate RED/GREEN error-accessor and two stale-diagnostic regressions. The new cases cover different bytes, negative zero, fresh/loaded owner mismatch, loaded byte mismatch, bounded/copy/privacy behavior, safe physical codes, stopped/hold/generation/dirty/inflight/not-ready/recovering/blocked/paused/pending mismatch and checkpoint revision changes. Synthetic original WAL and vector bucket bytes and mutation guards remain checked. Final related-suite, build and typecheck results are recorded in the adjacent workspace report. + +Actual native, packaged CLI and operating execution of this diagnostic draft are unverified. It does not diagnose prior attempts retrospectively. Parent review decides any commit, package and subsequent deployment. Long-term memory recording remains pending separate manual review. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index dc41cac63b..7db212e173 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.65 +version: 0.9.32-daniel.66 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 593b797030..b84d06f918 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index 854a2bf384..61afbff688 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index de593ea2aa..d4097219ca 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index d62181326c..3750df9f14 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.65 +version: 0.9.32-daniel.66 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 785b98fc4e..7ff12c4e53 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 9b9b31e920..5816ac32f8 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.65" + "@agentmemory/agentmemory": "0.9.32-daniel.66" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index b7bf700e95..2e7cc252be 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index fef2447a4c..8e4a5c0b74 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index 14df0e280c..7f9e8ddf89 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.65" + "@agentmemory/mcp@0.9.32-daniel.66" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 4d596f354c..9e7955146d 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index b2707f75d3..1513add63f 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 5ce187c64c..2b52d7f185 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.65"; +const VERSION = "0.9.32-daniel.66"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 148afbacc3..d038aeaf5d 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.65", + "version": "0.9.32-daniel.66", "facts": { "mcpTools": [ "55" diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 9561c01aaa..d80eac6f04 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/state/index-persistence.ts b/src/state/index-persistence.ts index 47134b03d0..af4352a252 100644 --- a/src/state/index-persistence.ts +++ b/src/state/index-persistence.ts @@ -103,6 +103,55 @@ export interface VectorCountShortfall { loaded: number; } +const RETAINED_PROOF_ERROR_CODES = [ + 'VECTOR_CHECKPOINT_UNVERIFIED', 'FILE_WRITER_EPOCH_UNVERIFIED', + 'vector_recovery_writer_unverified', 'vector_recovery_selection_invalid', 'vector_recovery_epoch_changed', + 'vector_recovery_pending_changed', 'vector_recovery_meta_changed', 'vector_recovery_checkpoint_changed', + 'vector_recovery_checkpoint_incomplete', 'vector_recovery_checkpoint_mismatch', + 'vector_retention_store_unverified', 'vector_retention_receipts_invalid', 'vector_retention_original_missing', + 'vector_retention_original_changed', 'vector_retention_manual_verification_required', + 'vector_retention_disk_sync_unconfirmed', 'vector_retention_receipts_changed', + 'ENOENT', 'EACCES', 'EPERM', 'EIO', 'ELOOP', 'UNCLASSIFIED_PROOF_ERROR', +] as const; +type RetainedProofErrorCode = typeof RETAINED_PROOF_ERROR_CODES[number]; +type RetainedProofReason = 'verified' | 'retention_not_ready' | 'recovery_not_admitted' | 'pending_row_mismatch' | + 'vector_unavailable' | 'checkpoint_meta_unverified' | 'checkpoint_selection_rejected' | 'physical_proof_rejected' | + 'postproof_not_admitted' | 'sdk_required' | 'publication_invalid' | 'publication_mismatch' | 'pending_read_rejected' | + 'capture_pending_rejected'; + +export interface RetainedProofDiagnostic { + id: string; + operation: 'capture_pending' | 'retained_publication'; + reason: RetainedProofReason; + freshBytesMatch: boolean | null; + loadedBytesMatch: boolean | null; + freshSessionMatch: boolean | null; + loadedSessionMatch: boolean | null; + retentionReady: boolean; + stopped: boolean; + storageHeld: boolean; + storageGenerationChanged: boolean; + storageRecovering: boolean; + storageBlocked: boolean; + recoveryPaused: boolean; + pendingLog: number; + logChains: number; + dirty: number; + revisionChanged: boolean | null; + physicalProofErrorCode: RetainedProofErrorCode | null; +} + +function retainedProofErrorCode(error: unknown): RetainedProofErrorCode { + try { + const value = error as {code?: unknown; message?: unknown} | null; + for (const candidate of [value?.code, value?.message]) { + if (typeof candidate === 'string' && RETAINED_PROOF_ERROR_CODES.includes(candidate as RetainedProofErrorCode)) + return candidate as RetainedProofErrorCode; + } + } catch { /* An error accessor is untrusted metadata too. */ } + return 'UNCLASSIFIED_PROOF_ERROR'; +} + export interface IndexPersistenceStatus { saveIntervalMs: number; firstCheckpointPending?: boolean; @@ -117,6 +166,7 @@ export interface IndexPersistenceStatus { retainedCheckpointRows?: number; pendingLogAcknowledged?: number; pendingLogError?: string | null; + retainedProofLastCheck?: RetainedProofDiagnostic | null; } export type VectorLoadState = "buckets" | "migrated" | "none" | "unavailable"; @@ -246,6 +296,7 @@ export class IndexPersistence { private vectorCountShortfall: VectorCountShortfall | null = null; private seq = 0; private retainedRows = new Map(); + private retainedProofLastCheck: RetainedProofDiagnostic | null = null; private retentionReady = true; private pendingLog: Map = new Map(); private acknowledgedLog: Map = new Map(); @@ -379,6 +430,7 @@ export class IndexPersistence { pendingLogKnown: this.pendingLogInspected && !this.pendingLogUnknown, pendingLogAcknowledged: this.pendingLogInspected && !this.pendingLogUnknown ? this.acknowledgedLog.size : undefined, pendingLogError: this.pendingLogError, + retainedProofLastCheck: this.retainedProofLastCheck ? {...this.retainedProofLastCheck} : null, }; } @@ -548,39 +600,95 @@ export class IndexPersistence { /** Revalidate existing WAL evidence for one explicitly selected capture, without creating receipts. */ async verifyCaptureVectorPending(id: string, sessionId: string, pending: unknown): Promise { - if (!this.retentionReady || this.storageRecovering || this.storageBlocked || this.isRecoveryPaused()) return false; + if (!this.retentionReady || this.storageRecovering || this.storageBlocked || this.isRecoveryPaused()) { + this.recordRetainedProof(id, sessionId, 'capture_pending', this.retentionReady ? 'recovery_not_admitted' : 'retention_not_ready'); + return false; + } const row = this.retainedRows.get(id); if (!row) return pending == null; - if (!this.vector || row.s !== sessionId || !isDeepStrictEqual(row, pending)) return false; + if (!this.vector || row.s !== sessionId || !isDeepStrictEqual(row, pending)) { + this.recordRetainedProof(id, sessionId, 'capture_pending', this.vector ? 'pending_row_mismatch' : 'vector_unavailable'); + return false; + } const revision = this.kv.vectorCheckpointRevision; + const finish = (result: boolean, reason: RetainedProofReason, error: RetainedProofErrorCode | null = null) => { + this.recordRetainedProof(id, sessionId, 'capture_pending', reason, undefined, revision, error); + return result; + }; const current = () => !this.stopped && !this.isStorageHeld() && this.storageGeneration() === this.bootStorageGeneration && !this.storageBlocked && !this.storageRecovering && !this.isRecoveryPaused() && !this.pendingLog.size && !this.logChains.size && !this.vector?.pendingChanges; + let stage: RetainedProofReason = 'checkpoint_meta_unverified'; try { - if (!current()) return false; + if (!current()) return finish(false, 'recovery_not_admitted'); const meta = await this.kv.get(KV.bm25Index, VECTOR_META_KEY); - if (meta?.v !== 3) return false; + if (meta?.v !== 3) return finish(false, 'checkpoint_meta_unverified'); const rows = [...this.retainedRows.values()]; + stage = 'checkpoint_selection_rejected'; const selected = this.checkpointSelection({state: 'buckets', vector: this.vector, savedAt: meta.savedAt, checkpointMeta: meta, expectedCount: meta.count}, rows); + stage = 'physical_proof_rejected'; await this.kv.reconcileVectorCheckpoint(selected, current, revision, false, true); - return current(); - } catch { return false; } + const result = current(); + return finish(result, result ? 'verified' : 'postproof_not_admitted'); + } catch (error) { return finish(false, stage, retainedProofErrorCode(error)); } } async verifyRetainedVectorPublication(publication: VectorPublication): Promise { const retained = this.retainedRows.get(publication.id), entry = publication.entry; - if (this.kv.durability?.completion !== 'sdk' || !retained || !entry || !(entry.embedding instanceof Float32Array)) return false; + if (this.kv.durability?.completion !== 'sdk' || !retained || !entry || !(entry.embedding instanceof Float32Array)) { + this.recordRetainedProof(publication.id, undefined, 'retained_publication', + this.kv.durability?.completion !== 'sdk' ? 'sdk_required' : 'publication_invalid'); + return false; + } + const finish = (result: boolean, reason: RetainedProofReason, nested?: RetainedProofDiagnostic | null) => { + this.recordRetainedProof(publication.id, entry.sessionId, 'retained_publication', reason, entry, undefined, + nested?.physicalProofErrorCode ?? null, nested?.revisionChanged ?? null); + return result; + }; const matches = () => { const loaded = this.vector?.get(publication.id); return entry.sessionId === retained.s && float32ToBase64(entry.embedding) === retained.e && loaded?.sessionId === retained.s && float32ToBase64(loaded.embedding) === retained.e; }; + let stage: RetainedProofReason = 'publication_mismatch'; try { - if (!matches()) return false; + if (!matches()) return finish(false, 'publication_mismatch'); + stage = 'pending_read_rejected'; const pending = await this.kv.get(KV.vectorPendingLog, publication.id); - return await this.verifyCaptureVectorPending(publication.id, entry.sessionId, pending) && matches(); - } catch { return false; } + stage = 'capture_pending_rejected'; + const previousDiagnostic = this.retainedProofLastCheck; + const verified = await this.verifyCaptureVectorPending(publication.id, entry.sessionId, pending); + const nested = this.retainedProofLastCheck !== previousDiagnostic && this.retainedProofLastCheck?.id === publication.id && this.retainedProofLastCheck.operation === 'capture_pending' + ? this.retainedProofLastCheck : null; + if (!verified) return finish(false, nested?.reason ?? 'capture_pending_rejected', nested); + stage = 'publication_mismatch'; + const result = matches(); + return finish(result, result ? 'verified' : 'publication_mismatch', nested); + } catch { return finish(false, stage); } + } + + private recordRetainedProof(id: string, sessionId: string | undefined, operation: RetainedProofDiagnostic['operation'], + reason: RetainedProofReason, fresh?: VectorEntry, revision?: number, physicalProofErrorCode: RetainedProofErrorCode | null = null, + revisionChanged: boolean | null = null): void { + const row = this.retainedRows.get(id); + if (!row) return; + // Diagnostic reads must never alter a verification decision or retain provider vector bytes. + try { + const loaded = this.vector?.get(id); + this.retainedProofLastCheck = { + id, operation, reason, + freshBytesMatch: fresh?.embedding instanceof Float32Array ? float32ToBase64(fresh.embedding) === row.e : null, + loadedBytesMatch: loaded?.embedding instanceof Float32Array ? float32ToBase64(loaded.embedding) === row.e : null, + freshSessionMatch: sessionId === undefined ? null : sessionId === row.s, + loadedSessionMatch: loaded ? loaded.sessionId === row.s : null, + retentionReady: this.retentionReady, stopped: this.stopped, storageHeld: this.isStorageHeld(), + storageGenerationChanged: this.storageGeneration() !== this.bootStorageGeneration, + storageRecovering: this.storageRecovering, storageBlocked: this.storageBlocked, recoveryPaused: this.isRecoveryPaused(), + pendingLog: this.pendingLog.size, logChains: this.logChains.size, dirty: this.vector?.pendingChanges ?? 0, + revisionChanged: revision === undefined ? revisionChanged : this.kv.vectorCheckpointRevision !== revision, physicalProofErrorCode, + }; + } catch { this.retainedProofLastCheck = null; } } private rememberRetained(rows: RecoveryUpsert[]): void { diff --git a/src/types.ts b/src/types.ts index 9b13c4a09f..f9c6894746 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index f30021be59..e7bebec0c4 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.65"; +export const VERSION = "0.9.32-daniel.66"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/retained-embedding-publication.test.ts b/test/retained-embedding-publication.test.ts index 8d4b8d20a3..78011e582a 100644 --- a/test/retained-embedding-publication.test.ts +++ b/test/retained-embedding-publication.test.ts @@ -143,3 +143,108 @@ it('keeps completed SDK metadata and retained WAL valid after a new persistence f.assertOriginals(); }finally{nextPersistence.stop();} }); + +it('records only one defensive-copy retained proof diagnostic and ignores unknown IDs',async()=>{ + const f=await fixture();expect(f.persistence.status().retainedProofLastCheck).toBeNull(); + expect(await f.persistence.verifyRetainedVectorPublication({id:'unknown-untrusted-id',entry:null})).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toBeNull(); + for(const row of f.rows)expect(await f.persistence.verifyRetainedVectorPublication({id:row.id,entry:f.index.get(row.id)!})).toBe(true); + const status=f.persistence.status();expect(status.retainedProofLastCheck).toMatchObject({id:f.rows[3].id,operation:'retained_publication',reason:'verified', + freshBytesMatch:true,loadedBytesMatch:true,freshSessionMatch:true,loadedSessionMatch:true,retentionReady:true, + stopped:false,storageHeld:false,storageGenerationChanged:false,storageRecovering:false,storageBlocked:false,recoveryPaused:false, + pendingLog:0,logChains:0,dirty:0,revisionChanged:false,physicalProofErrorCode:null}); + status.retainedProofLastCheck!.reason='publication_invalid';expect(f.persistence.status().retainedProofLastCheck!.reason).toBe('verified'); + expect(JSON.stringify(status)).not.toContain(f.rows[0].e);expect(JSON.stringify(status)).not.toContain('source text'); + expect(f.actions).toEqual([]);f.assertOriginals(); +}); + +it.each(['different bytes','negative zero','fresh owner','loaded owner','loaded bytes'])('diagnoses %s without relaxing exact publication rejection',async mode=>{ + const f=await fixture(),row=f.rows[0],entry={...f.index.get(row.id)!,embedding:new Float32Array([1,0])}; + if(mode==='different bytes')entry.embedding=new Float32Array([0,1]); + if(mode==='negative zero')entry.embedding=new Float32Array([1,-0]); + if(mode==='fresh owner')entry.sessionId='other'; + if(mode==='loaded owner')f.index.get(row.id)!.sessionId='other'; + if(mode==='loaded bytes')f.index.get(row.id)!.embedding[0]=0; + expect(await f.persistence.verifyRetainedVectorPublication({id:row.id,entry})).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toMatchObject({id:row.id,reason:'publication_mismatch',physicalProofErrorCode:null, + freshBytesMatch:mode!=='different bytes'&&mode!=='negative zero',loadedBytesMatch:mode!=='loaded bytes', + freshSessionMatch:mode!=='fresh owner',loadedSessionMatch:mode!=='loaded owner'}); + expect(f.actions).toEqual([]);f.assertOriginals(); + expect(()=>f.index.remove(row.id)).toThrow(/VECTOR_RECOVERY_PAUSED/); +}); + +it.each(['known','unknown'])('retains only allowlisted physical proof error codes (%s)',async mode=>{ + const f=await fixture(),row=f.rows[0]; + vi.spyOn(f.kv,'reconcileVectorCheckpoint').mockRejectedValue(Object.assign(new Error('synthetic private path and source text'),{code:mode==='known'?'VECTOR_CHECKPOINT_UNVERIFIED':'PRIVATE_UNKNOWN_SECRET'})); + expect(await f.persistence.verifyRetainedVectorPublication({id:row.id,entry:f.index.get(row.id)!})).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toMatchObject({reason:'physical_proof_rejected',freshBytesMatch:true,loadedBytesMatch:true, + physicalProofErrorCode:mode==='known'?'VECTOR_CHECKPOINT_UNVERIFIED':'UNCLASSIFIED_PROOF_ERROR'}); + expect(JSON.stringify(f.persistence.status().retainedProofLastCheck)).not.toMatch(/private|source text|PRIVATE_UNKNOWN_SECRET/); + expect(f.actions).toEqual([]);f.assertOriginals(); +}); + +it.each(['stopped','held','generation','dirty','log chain','pending log','not ready','recovering','blocked','paused','pending mismatch'])('reports %s while preserving capture pending false',async mode=>{ + const f=await fixture(),row=f.rows[0],p=f.persistence as any; + if(mode==='stopped')p.stopped=true; + if(mode==='held')f.hold(); + if(mode==='generation')f.changeEpoch(); + if(mode==='dirty')vi.spyOn(f.index,'pendingChanges','get').mockReturnValue(1); + if(mode==='log chain')p.logChains.set('synthetic',Promise.resolve()); + if(mode==='pending log')p.pendingLog.set('synthetic',1); + if(mode==='not ready')p.retentionReady=false; + if(mode==='recovering')p.storageRecovering=true; + if(mode==='blocked')p.storageBlocked=true; + if(mode==='paused')p.recoveryReady=false; + const pending=mode==='pending mismatch'?{...row,q:99}:row; + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',pending)).toBe(false); + const last=f.persistence.status().retainedProofLastCheck!; + expect(last).toMatchObject({id:row.id,operation:'capture_pending',freshBytesMatch:null,physicalProofErrorCode:null}); + if(mode==='stopped')expect(last.stopped).toBe(true); + if(mode==='held')expect(last.storageHeld).toBe(true); + if(mode==='generation')expect(last.storageGenerationChanged).toBe(true); + if(mode==='dirty')expect(last.dirty).toBe(1); + if(mode==='log chain')expect(last.logChains).toBe(1); + if(mode==='pending log')expect(last.pendingLog).toBe(1); + if(mode==='not ready')expect(last.retentionReady).toBe(false); + if(mode==='recovering')expect(last.storageRecovering).toBe(true); + if(mode==='blocked')expect(last.storageBlocked).toBe(true); + if(mode==='paused')expect(last.recoveryPaused).toBe(true); + if(mode==='pending mismatch')expect(last.reason).toBe('pending_row_mismatch'); + expect(f.actions).toEqual([]);f.assertOriginals(); +}); + +it('reports revision changes and preserves both successful and rejected capture decisions',async()=>{ + const f=await fixture(),row=f.rows[0]; + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',row)).toBe(true); + expect(f.persistence.status().retainedProofLastCheck).toMatchObject({reason:'verified',freshBytesMatch:null,loadedBytesMatch:true,revisionChanged:false}); + vi.spyOn(f.kv,'reconcileVectorCheckpoint').mockImplementation(async()=>{Object.defineProperty(f.kv,'vectorCheckpointRevision',{value:999});throw Error('vector_recovery_checkpoint_changed');}); + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',row)).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toMatchObject({reason:'physical_proof_rejected',revisionChanged:true,physicalProofErrorCode:'vector_recovery_checkpoint_changed'}); + expect(f.actions).toEqual([]);f.assertOriginals(); +}); + +it('never lets hostile physical error properties escape the original false result',async()=>{ + const f=await fixture(),row=f.rows[0]; + vi.spyOn(f.kv,'reconcileVectorCheckpoint').mockRejectedValue(Object.defineProperty({},'code',{get(){throw Error('synthetic private getter');}})); + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',row)).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toMatchObject({reason:'physical_proof_rejected',physicalProofErrorCode:'UNCLASSIFIED_PROOF_ERROR'}); + f.assertOriginals(); +}); + +it('does not label a rejected publication with an earlier verified capture diagnostic',async()=>{ + const f=await fixture(),row=f.rows[0]; + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',row)).toBe(true); + vi.spyOn(f.persistence,'verifyCaptureVectorPending').mockResolvedValue(false); + expect(await f.persistence.verifyRetainedVectorPublication({id:row.id,entry:f.index.get(row.id)!})).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toMatchObject({reason:'capture_pending_rejected'}); + f.assertOriginals(); +}); + +it('clears an earlier diagnostic if local diagnostic collection becomes unavailable',async()=>{ + const f=await fixture(),row=f.rows[0]; + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',row)).toBe(true); + (f.persistence as any).isStorageHeld=()=>{throw Error('synthetic unavailable local observation');}; + expect(await f.persistence.verifyCaptureVectorPending(row.id,'session',row)).toBe(false); + expect(f.persistence.status().retainedProofLastCheck).toBeNull(); + f.assertOriginals(); +}); From 29362ab952a93cf4122946bb3e90f0d7bd77e16a Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 11 Nov 2026 10:10:52 +0900 Subject: [PATCH 12/23] fix(health): recognize SDK reviews and legacy summary coverage --- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 11 ++ .../HEALTH-REVIEWED-STATUS-67.md | 7 + integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- src/capture/auto-recovery.ts | 30 ++++- src/functions/capture.ts | 2 +- src/functions/export-import.ts | 2 +- src/triggers/api.ts | 95 +++++++++++++- src/types.ts | 2 +- src/version.ts | 2 +- src/viewer/capture-review-viewer.js | 2 +- src/viewer/index.html | 15 ++- test/operations-throughput.test.ts | 2 +- test/sdk-capture-preservation.test.ts | 29 +++++ test/summary-coverage-api.test.ts | 120 ++++++++++++++++++ test/viewer-operations.test.ts | 21 ++- 30 files changed, 339 insertions(+), 37 deletions(-) create mode 100644 docs/customizations/HEALTH-REVIEWED-STATUS-67.md create mode 100644 test/summary-coverage-api.test.ts diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index ff858abcbd..3843125c3f 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/AGENTS.md b/AGENTS.md index 263b0381d6..6513e514d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - Test files go in `test/` with `.test.ts` extension - Follow existing patterns in `test/crystallize.test.ts` for function tests -## Current Stats (v0.9.32-daniel.66) +## Current Stats (v0.9.32-daniel.67) - 55 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials - 161 REST endpoints diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c5c1a1212..95de87d1a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## 0.9.32-daniel.67 — Health current-state display + +- Count recorded matching SDK resolutions separately from unresolved recovery checkpoints. +- Reflect exact current-source legacy summary coverage in Health through read-only metadata. +- Preserve original recovery records and stored session progress. + ## Unreleased — compact summary acknowledgement - Preserve summary bodies and cursors while avoiding old+new response amplification: file-backed server summary writes use the engine state::set_ack success-only response, with a pinned JSON request snapshot. Ordinary state::set/Redis and compatibility-mode StateKV remain unchanged. @@ -10,6 +16,10 @@ ## [Unreleased] +## [0.9.32-daniel.67] + +- Health counts matching committed SDK recovery records as reviewed history and recognizes verified legacy summary coverage without rewriting session progress. + — 2026-11-11 ## [0.9.32-daniel.66] — 2026-11-10 - Add one bounded, in-memory final retained-vector proof diagnostic to the existing persistence status. Report only a known retained ID, an enumerated result, fresh/loaded exact-byte and session matches, admission/queue/revision state, and an allowlisted physical-proof error code. Do not retain provider vector bytes, original text, arbitrary error messages or unknown requested IDs. - Preserve retained publication/capture verification decisions, exact Float32 byte comparison (including negative zero), physical checkpoint and receipt proof, mutation guards, SDK-only completion and existing retry/backoff. This change explains later attempts; it cannot reconstruct the fresh vector or physical race from earlier .65 failures. @@ -613,6 +623,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately. - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked. +[0.9.32-daniel.67]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.66...v0.9.32-daniel.67 [0.9.32-daniel.66]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.65...v0.9.32-daniel.66 [0.9.32-daniel.65]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.64...v0.9.32-daniel.65 [0.9.32-daniel.64]: https://github.com/rohitg00/agentmemory/compare/v0.9.32-daniel.63...v0.9.32-daniel.64 diff --git a/docs/customizations/HEALTH-REVIEWED-STATUS-67.md b/docs/customizations/HEALTH-REVIEWED-STATUS-67.md new file mode 100644 index 0000000000..eb3ea02a32 --- /dev/null +++ b/docs/customizations/HEALTH-REVIEWED-STATUS-67.md @@ -0,0 +1,7 @@ +# Health current-state display for existing recovery history + +The Health cleanup uses the existing SDK reconciliation and summary coverage evidence. Capture recovery checkpoints retain their original phases and attempt history. A checkpoint whose key, event, session, observation and source digest match an existing committed SDK resolution is counted separately as sdkReviewed. Disk-resolved totals retain their existing meaning. Unmatched, incomplete and unavailable records continue to contribute to the warning. The recovery dialog reports the existing SDK completion count. + +The sessions endpoint supports opt-in summary coverage metadata for Health. When summaryProgress is absent, it reads a bounded small-session source set and uses the existing summaryCovers fingerprint. Source changes, missing records, read failures and timeouts leave coverage unknown. A confirmed count is returned as response metadata. The viewer uses that count in its remaining-work and throughput views. Scheduling and persisted session records use their existing fields. + +The regression checks cover matching SDK history with unchanged storage, mismatched digest and incomplete SDK resolution, source and fingerprint changes, existing-progress precedence, and the opt-in API contract. Operation uses the normal .67 deployment procedure with version-matched boot and manual recovery helpers. Live acceptance requires the former warning to disappear, sdkReviewed to reflect the two recorded resolutions, and the Windows validation summary to appear current with zero remaining work. The original recovery rows and summaryProgress absence are rechecked after deployment. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index 7db212e173..a7b90b2f8c 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.66 +version: 0.9.32-daniel.67 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index b84d06f918..8271992e4b 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index 61afbff688..901bccf4fd 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index d4097219ca..21e9fbac62 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index 3750df9f14..1c5b2a81b5 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.66 +version: 0.9.32-daniel.67 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index 7ff12c4e53..bfd5fd2eae 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 5816ac32f8..6bba78643d 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.66" + "@agentmemory/agentmemory": "0.9.32-daniel.67" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 2e7cc252be..d46f830273 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 8e4a5c0b74..7629c4ce8d 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index 7f9e8ddf89..cb6af89783 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.66" + "@agentmemory/mcp@0.9.32-daniel.67" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 9e7955146d..4f3062a28e 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 1513add63f..4b4e9fd470 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 2b52d7f185..58ed4a1022 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.66"; +const VERSION = "0.9.32-daniel.67"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index d038aeaf5d..f85e1ffdfa 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.66", + "version": "0.9.32-daniel.67", "facts": { "mcpTools": [ "55" diff --git a/src/capture/auto-recovery.ts b/src/capture/auto-recovery.ts index 4769e43da2..36a1087c61 100644 --- a/src/capture/auto-recovery.ts +++ b/src/capture/auto-recovery.ts @@ -1,6 +1,6 @@ import {readerEvidence,validReaderEvidence} from '../ops/read-progress.mjs'; import {recordAudit} from "../functions/audit.js"; -import type {CaptureRecoveryCheckpoint,CaptureRecoveryFailure} from "../types.js"; +import type {CaptureRecoveryCheckpoint,CaptureRecoveryFailure,CaptureReviewHistory} from "../types.js"; import {createHash,randomUUID} from 'node:crypto'; import {isDeepStrictEqual} from 'node:util'; import type {StateKV} from '../state/kv.js'; @@ -8,6 +8,7 @@ import {withKeyedLock} from '../state/keyed-mutex.js'; import {KV} from '../state/schema.js'; import {captureEventScope} from './event-record.js'; import {capturePayloadDigest,captureSourceDigest} from './receipt-digest.js'; +import {committedSdkResolution} from './sdk-resolution-record.js'; const SCOPE=KV.captureRecovery; const SAFE_REASONS=new Set(['PUBLICATION_PENDING', 'PUBLICATION_WAIT_EXHAUSTED', 'ADMISSION_HELD', 'CHECK_PENDING', 'COMPLETION_PROOF_PENDING', 'VERIFIED_DURABLE', 'VERIFICATION_BUDGET_EXHAUSTED', 'VERIFICATION_PENDING', 'DELETION_RECORDED', 'IDENTITY_CONFLICT', 'SOURCE_MISSING', 'SOURCE_UNSUPPORTED', 'SOURCE_MISMATCH', 'GENERATION_CHANGED', 'INTENT_ACTIVE_OR_UNSUPPORTED', 'PUBLICATION_UNVERIFIED', 'INDEX_RESTORATION_REQUIRED', 'MANUAL_OR_ACTIVE_RETRY', 'REQUEST_REQUIRES_MANUAL_RESTORE', 'RECEIPT_CONFLICT', 'MANUAL_OR_UNKNOWN_COMPLETION', 'STATE_CHANGED', 'COMPLETION_UNVERIFIED', 'ADMISSION_CHANGED', 'FAILURE_UNCLASSIFIED']); @@ -29,7 +30,7 @@ function failureEvidence(error:any,operation:string):CaptureRecoveryFailure { function validRow(v:any):v is Row{return v?.version===1&&v.kind==='item'&&/^cap_[a-f0-9]{40}$/.test(v.key)&&typeof v.id==='string'&&['sessionId','observationId','eventId'].every(k=>typeof v[k]==='string'&&v[k])&&/^[a-f0-9]{64}$/.test(v.sourceDigest)&&/^[a-f0-9]{64}$/.test(v.projection)&&['checking','verifying','resolved','blocked'].includes(v.phase)&&Number.isSafeInteger(v.verificationAttempts)&&v.verificationAttempts>=0&&v.verificationAttempts<=MAX_PROOFS&&Number.isFinite(v.nextAttemptAt)&&v.nextAttemptAt>=0&&(v.lastVerificationFailure===undefined||validFailure(v.lastVerificationFailure));} export function createCaptureAutoRecovery(kv:StateKV,options:CaptureAutoRecoveryOptions){ const now=options.now??Date.now;let busy=false,halted=false,enabled=options.enabled,revision=0,initialized:Promise|undefined;let durableEnabled:boolean|null=null,configurationStatus='unloaded'; - let view={enabled:options.enabled,supported:false,phase:'idle',resolved:0,verifying:0,blocked:0,reasonCounts:{}as Record,breakerUntil:0,lastCheckedAt:null as string|null,lastErrorCode:null as string|null,verificationFailureCounts:{}as Record}; + let view={enabled:options.enabled,supported:false,phase:'idle',resolved:0,sdkReviewed:0,verifying:0,blocked:0,reasonCounts:{}as Record,breakerUntil:0,lastCheckedAt:null as string|null,lastErrorCode:null as string|null,verificationFailureCounts:{}as Record}; const blockReason=()=>{ if(kv.durability?.completion==='sdk')return 'SDK_COMPLETION_ONLY'; if(halted)return 'RECOVERY_STORAGE_OR_STATE_UNAVAILABLE'; @@ -67,9 +68,27 @@ export function createCaptureAutoRecovery(kv:StateKV,options:CaptureAutoRecovery const all=await kv.list(SCOPE);if(all.length>5001||all.some(r=>r?.kind==='item'&&!validRow(r)))throw fail('RECOVERY_STATE_UNSUPPORTED'); const rows=all.filter(validRow),control=all.find(r=>r?.kind==='control') as Control|undefined; if(control&&!validControl(control))throw fail('RECOVERY_STATE_UNSUPPORTED'); - const counts:Record={};for(const r of rows)if(r.phase!=='resolved'){const reason=SAFE_REASONS.has(r.reason)?r.reason:'RECOVERY_STATE_UNSUPPORTED';counts[reason]=(counts[reason]??0)+1;} - const verificationFailureCounts:Record={};for(const r of rows)if(r.phase!=='resolved'&&r.lastVerificationFailure){const f=r.lastVerificationFailure,k=f.operation+':'+f.stage+':'+f.code;verificationFailureCounts[k]=(verificationFailureCounts[k]??0)+1;} - view={...view,verificationFailureCounts,supported:kv.durability?.completion!=='sdk'&&kv.recoveryMutationSafe&&!!kv.recoveryWrite&&kv.backend==='file'&&!!kv.durability&&options.writerOwned(),resolved:rows.filter(r=>r.phase==='resolved').length,verifying:rows.filter(r=>['checking','verifying'].includes(r.phase)).length,blocked:rows.filter(r=>r.phase==='blocked').length,reasonCounts:counts,breakerUntil:control?.openUntil??0,lastCheckedAt:new Date(now()).toISOString()}; + let unresolved=rows.filter(row=>row.phase!=='resolved'); + const reviewed=new Set(); + if(kv.durability?.completion==='sdk'){ + // Bound extra SDK reads. Older checkpoints stay in storage as historical evidence. + for(const row of unresolved.slice(0,16)){ + try{ + const [history,inbox]=await Promise.all([kv.get(KV.captureReview,row.key),kv.get>(KV.captureInbox,row.key)]); + if(history?.key===row.key&&history.eventId===row.eventId&&history.sessionId===row.sessionId&&history.observationId===row.observationId&& + history.sdkResolution?.sourceDigest===row.sourceDigest&&inbox?.sdkRestoreState!=='pending'&&committedSdkResolution(history,inbox))reviewed.add(row.key); + }catch{/* Leave the item in the warning if its SDK record cannot be confirmed. */} + } + unresolved=unresolved.filter(row=>!reviewed.has(row.key)); + } + const counts:Record={}; + const verificationFailureCounts:Record={}; + for(const row of unresolved){ + const reason=SAFE_REASONS.has(row.reason)?row.reason:'RECOVERY_STATE_UNSUPPORTED'; + counts[reason]=(counts[reason]??0)+1; + if(row.lastVerificationFailure){const f=row.lastVerificationFailure,key=f.operation+':'+f.stage+':'+f.code;verificationFailureCounts[key]=(verificationFailureCounts[key]??0)+1;} + } + view={...view,verificationFailureCounts,supported:kv.durability?.completion!=='sdk'&&kv.recoveryMutationSafe&&!!kv.recoveryWrite&&kv.backend==='file'&&!!kv.durability&&options.writerOwned(),resolved:rows.filter(row=>row.phase==='resolved').length,sdkReviewed:reviewed.size,verifying:unresolved.filter(row=>row.phase!=='blocked').length,blocked:unresolved.filter(row=>row.phase==='blocked').length,reasonCounts:counts,breakerUntil:control?.openUntil??0,lastCheckedAt:new Date(now()).toISOString()}; return {rows,control:control??{version:1,kind:'control',failures:0,openUntil:0}as Control}; } function keys(row:Row){return [{scope:KV.captureReview,key:row.key},{scope:KV.captureInbox,key:row.key},{scope:KV.observations(row.sessionId),key:row.observationId},{scope:'mem:embedding-retry:v1',key:row.observationId},{scope:'mem:embedding-committed:v1',key:row.observationId},{scope:captureEventScope(row.key),key:row.key}];} @@ -139,6 +158,7 @@ export function createCaptureAutoRecovery(kv:StateKV,options:CaptureAutoRecovery } return { snapshot,initialize,setEnabled, + async refreshSdkReviews(){if(kv.durability?.completion==='sdk'){await initialize();await refresh();}}, async tick(){ if(busy)return;busy=true; try{await initialize();if(!enabled)return;await withKeyedLock('capture-auto-recovery',async()=>{ diff --git a/src/functions/capture.ts b/src/functions/capture.ts index 1d459e7bf9..488ac9838f 100644 --- a/src/functions/capture.ts +++ b/src/functions/capture.ts @@ -780,7 +780,7 @@ export function registerCaptureFunctions( return trackWork(()=>backgroundTask(async()=>{ try{ const result=await sdkReconciliation.reconcile(selection); - if(result.status==='reconciled'){counters.recovered++;updateActiveInbox(selection.key,false);} + if(result.status==='reconciled'){counters.recovered++;updateActiveInbox(selection.key,false);trackMaintenance(()=>automaticRecovery.refreshSdkReviews());} return result; }catch(error){const code=(error as {code?:unknown})?.code;return{completed:false,completion:'sdk',verified:false,synced:false,code:typeof code==='string'&&/^SDK_RECONCILIATION_[A-Z_]+$/.test(code)?code:'SDK_RECONCILIATION_UNAVAILABLE'};} })()); diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index d80eac6f04..b63f1020b1 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.32-daniel.67", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index e601db46f3..afdbd8ae76 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -7,6 +7,7 @@ import { InvocationError, TriggerAction, type IIIClient } from "iii-sdk"; import { DEDUP_WINDOW_MS, getDedupSkippedCount } from "../functions/dedup.js"; import type { HttpRequest } from "@iii-dev/helpers/http"; import { randomBytes } from "node:crypto"; +import { isDeepStrictEqual } from "node:util"; import type { Session, CompressedObservation, HookPayload, CommitLink, SessionSummary, HealthSnapshot, AuditQueryResult, AuditMigrationState, Lesson } from "../types.js"; import { AUDIT_MIGRATION_STATE_KEY } from "../functions/audit.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; @@ -68,7 +69,7 @@ import { isValidEventId } from "../capture/event-id.js"; import { getCaptureController, type CaptureResult } from "../functions/capture.js"; import { withoutObservationSource } from "../functions/observation-source.js"; import { clearSessionFinalize, scheduleSessionFinalize } from "../functions/session-finalize.js"; -import { requestSummaryRefresh } from "../functions/summary-state.js"; +import { requestSummaryRefresh, summaryCovers, summaryObservations } from "../functions/summary-state.js"; import { registerCompressionApi } from "./compression.js"; import { getFinalizeIdleMs, @@ -100,6 +101,85 @@ function parseOptionalInt(raw: unknown): number | undefined { return Number.isFinite(n) ? n : undefined; } +function createSessionSummaryCoverage(kv: StateKV) { + let busy = false; + return async (sessions: Session[]): Promise> => { + const reader = kv.observationReader; + const durability = kv.durability; + if (!reader || !durability || busy) return new Map(); + const candidates = sessions.filter(session => !("summaryProgress" in session) && + Number.isSafeInteger(session.observationCount) && session.observationCount > 0 && + session.observationCount <= 16).slice(0, 8); + if (!candidates.length) return new Map(); + + const controller = new AbortController(); + const { signal } = controller; + const expiresAt = performance.now() + 1250; + const releases: Array<() => void> = []; + busy = true; + const work = (async () => { + const verified: Array<{ session: Session; fresh: () => boolean }> = []; + for (const session of candidates) { + if (signal.aborted) break; + try { + const guard = durability.watchKeys([ + { scope: KV.sessions, key: session.id }, { scope: KV.summaries, key: session.id }, + ]); + releases.push(() => guard.release()); + if (!guard.unchanged()) continue; + const current = await kv.get(KV.sessions, session.id); + signal.throwIfAborted(); + if (!isDeepStrictEqual(current, session)) continue; + const summary = await kv.get(KV.summaries, session.id); + signal.throwIfAborted(); + if (summary?.sessionId !== session.id || !summary.coveredFingerprint || + summary.observationCount !== session.observationCount) continue; + + const scope = KV.observations(session.id); + const mutation = reader.mutationRevision(scope); + const fresh = () => !signal.aborted && performance.now() < expiresAt && guard.unchanged() && + mutation === reader.mutationRevision(scope) && !reader.pendingMutations(scope); + if (!fresh()) continue; + const revision = await reader.revision(scope); + signal.throwIfAborted(); + const view = await reader.work(scope, { kind: "summary", signal }); + if (view.rows.length !== session.observationCount) continue; + const rows: CompressedObservation[] = []; + let bytes = 0; + for (const descriptor of view.rows) { + signal.throwIfAborted(); + const row = await view.load(descriptor); + if (!row || row.sessionId !== session.id || typeof row.title !== "string") break; + bytes += Buffer.byteLength(JSON.stringify(row)); + if (bytes > 2 * 1024 * 1024) break; + rows.push(row); + } + if (rows.length !== view.rows.length) continue; + const observations = summaryObservations(rows); + if (observations.length !== rows.length || !summaryCovers(session, observations, summary)) continue; + if (revision !== await reader.revision(scope) || !fresh()) continue; + view.validate(); + verified.push({ session, fresh: () => { view.validate(); return fresh(); } }); + } catch { /* A missing or unstable source leaves coverage unknown. */ } + } + const coverage = new Map(); + for (const { session, fresh } of verified) { + try { if (fresh()) coverage.set(session.id, session.observationCount); } catch { /* Writer changed. */ } + } + return coverage; + })().finally(() => { busy = false; }); + let timer: ReturnType | undefined; + const deadline = new Promise>(resolve => { + timer = setTimeout(() => { controller.abort(); resolve(new Map()); }, 1250); + }); + try { return await Promise.race([work, deadline]); } + finally { + clearTimeout(timer); + for (const release of releases) release(); + } + }; +} + let restOriginPorts: () => Array = () => []; export function setRestOriginPorts(resolve: () => Array): void { @@ -1580,6 +1660,7 @@ export function registerApiTriggers( }, }); + const sessionSummaryCoverage = createSessionSummaryCoverage(kv); sdk.registerFunction("api::sessions", async (req: HttpRequest): Promise => { const authErr = checkAuth(req, secret); @@ -1649,9 +1730,17 @@ export function registerApiTriggers( ); summaries.push(...results); } + const metadataOnly = req.query_params?.["includeSummary"] === "false"; + const coverage = metadataOnly && req.query_params?.["includeSummaryCoverage"] === "true" + ? await sessionSummaryCoverage(filtered) : undefined; const withSummary = filtered.map((s, i) => { - if(req.query_params?.["includeSummary"]==="false") {const {summary:_,...metadata}=s;return metadata;} - return summaries[i] ? { ...s, summary: summaries[i] } : s; + const { summaryCoveredCount: _storedCount, ...session } = s as Session & { summaryCoveredCount?: unknown }; + if (metadataOnly) { + const { summary: _, ...metadata } = session; + const count = coverage?.get(s.id); + return count === undefined ? metadata : { ...metadata, summaryCoveredCount: count }; + } + return summaries[i] ? { ...session, summary: summaries[i] } : session; }); return { status_code: 200, diff --git a/src/types.ts b/src/types.ts index f9c6894746..bcd8a2a9b1 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.32-daniel.67" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; diff --git a/src/version.ts b/src/version.ts index e7bebec0c4..b95ff95da8 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.66"; +export const VERSION = "0.9.32-daniel.67"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/src/viewer/capture-review-viewer.js b/src/viewer/capture-review-viewer.js index 77515ef4ae..7528931df3 100644 --- a/src/viewer/capture-review-viewer.js +++ b/src/viewer/capture-review-viewer.js @@ -87,7 +87,7 @@ async function load(cursor){try{ var page=await api('?review=true&status='+select.value+'&limit=25'+(cursor?'&cursor='+encodeURIComponent(cursor):''));rows=page.items||[];nextCursor=page.nextCursor||null; var cap=page.capture?.inbox;deadCount=cap?cap.dead:select.value==='dead'?page.total:deadCount; - summary.textContent='선택 상태 '+page.total+'건'+(cap?' · 수집 격리 '+cap.dead+'건 · 자동 재시도 '+cap.retrying+'건':'');var auto=page.capture?.automaticRecovery;automaticState=auto||null;automaticDescription.textContent=auto?('검증 자동 복구 '+(auto.enabled?'켜짐':'꺼짐')+' · '+(auto.admitted?'조건 충족':automaticReasons[auto.blockedReason]||(auto.blockedReason?'보류':'사용 가능 · 비활성'))+(auto.configurationStatus==='pending'?' · 설정 저장 중':auto.configurationStatus==='unknown'?' · 설정 저장 결과 미확정':'')+' · 원본이 일치하고 이미 게시된 항목만 복구합니다.'):'이 서버는 검증 자동 복구 제어를 제공하지 않습니다.';if(auto)summary.textContent+=' · 검증 복구 '+auto.resolved+'건 / 확인 중 '+auto.verifying+'건 / 점검 필요 '+auto.blocked+'건'+(auto.lastErrorCode?' · 자동 변경 보류':'')+(auto.breakerUntil>Date.now()?' · 반복 실패로 대기':'');render(); + summary.textContent='선택 상태 '+page.total+'건'+(cap?' · 수집 격리 '+cap.dead+'건 · 자동 재시도 '+cap.retrying+'건':'');var auto=page.capture?.automaticRecovery;automaticState=auto||null;automaticDescription.textContent=auto?('검증 자동 복구 '+(auto.enabled?'켜짐':'꺼짐')+' · '+(auto.admitted?'조건 충족':automaticReasons[auto.blockedReason]||(auto.blockedReason?'보류':'사용 가능 · 비활성'))+(auto.configurationStatus==='pending'?' · 설정 저장 중':auto.configurationStatus==='unknown'?' · 설정 저장 결과 미확정':'')+' · 원본이 일치하고 이미 게시된 항목만 복구합니다.'):'이 서버는 검증 자동 복구 제어를 제공하지 않습니다.';if(auto)summary.textContent+=' · 검증 복구 '+auto.resolved+'건 / 확인 중 '+auto.verifying+'건 / 점검 필요 '+auto.blocked+'건'+(auto.sdkReviewed>0?' · 기존 SDK 완료 기록 '+auto.sdkReviewed+'건':'')+(auto.lastErrorCode?' · 자동 변경 보류':'')+(auto.breakerUntil>Date.now()?' · 반복 실패로 대기':'');render(); }catch{announce('수집 목록 조회 실패 · 비어 있다고 판정하지 않습니다.');}finally{controls();}} async function toggleAutomaticRecovery(){ if(busy||!automaticState)return;var desired=!automaticWantsOff();busy=true;controls(); diff --git a/src/viewer/index.html b/src/viewer/index.html index 6f7820c28a..116e3c33a2 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -2516,6 +2516,15 @@

agentmemory

return records; } + function summaryStageProgress(session) { + if (session.summaryProgress) return session.summaryProgress; + var count = session.summaryCoveredCount; + if (Number.isSafeInteger(count) && count > 0 && count === session.observationCount) { + return {status:'current',pendingCount:0,processedCount:count}; + } + return null; + } + function backgroundWorkSnapshot(sessions, health, available) { var totals = {summary:0,compress:0,graph:0,embedding:null,features:null}, knownTotals = {summary:0,compress:0,graph:0,embedding:null,features:null}; var unknownStageCounts = {summary:0,compress:0,graph:0}, unknownSessionsCount = 0, knownCounts = {summary:0,compress:0,graph:0}, rows = [], quarantined = 0; @@ -2525,7 +2534,7 @@

agentmemory

return empty ? 0 : null; } (sessions || []).forEach(function(s) { - var enrichment = s.enrichmentProgress || {}, progress = [s.summaryProgress,enrichment.compress,enrichment.graph]; + var enrichment = s.enrichmentProgress || {}, progress = [summaryStageProgress(s),enrichment.compress,enrichment.graph]; var empty = s.observationCount === 0 || s.observations === 0; var counts = {summary:pending(progress[0],empty),compress:pending(progress[1],empty),graph:pending(progress[2],empty)}; Object.keys(counts).forEach(function(k) { @@ -2646,7 +2655,7 @@

agentmemory

[['summary','요약'],['compress','압축'],['graph','그래프']].forEach(function(pair) { var counters = Object.create(null), statuses = [], complete = available, blocked = 0; (sessions || []).forEach(function(s) { - var p = pair[0] === 'summary' ? s.summaryProgress : (s.enrichmentProgress || {})[pair[0]]; + var p = pair[0] === 'summary' ? summaryStageProgress(s) : (s.enrichmentProgress || {})[pair[0]]; if (p && p.enabled === false || s.observationCount === 0 || s.observations === 0) return; if (!p || !Number.isSafeInteger(p.processedCount) || p.processedCount < 0 || typeof s.id !== 'string') { complete = false; return; } counters[s.id] = p.processedCount; statuses.push(p.status); @@ -2787,7 +2796,7 @@

agentmemory

operations.loading = true; renderOperations(); operations.request = (async function() { try { - var results = await Promise.all([apiGet('health'),apiGet('sessions?includeSummary=false'),apiGet('background/control')]); + var results = await Promise.all([apiGet('health'),apiGet('sessions?includeSummary=false&includeSummaryCoverage=true'),apiGet('background/control')]); if (generation !== operations.generation) return; var h = results[0], sessions = results[1], control = results[2]; operations.error = h ? '' : 'Health 조회 실패 · 이전 상태는 최신 상태가 아닐 수 있습니다.'; diff --git a/test/operations-throughput.test.ts b/test/operations-throughput.test.ts index 71b3c85d4f..9194297405 100644 --- a/test/operations-throughput.test.ts +++ b/test/operations-throughput.test.ts @@ -4,7 +4,7 @@ import {describe,it,expect} from 'vitest'; const html=readFileSync('src/viewer/index.html','utf8'); function setup(){ const ctx:any={operations:{progressSamples:{}},autoRefresh:{seconds:30},Number,Date}; - for(const name of ['progressDuration','operationsStages','recordOperationsProgress','stageProgress']){ + for(const name of ['progressDuration','summaryStageProgress','operationsStages','recordOperationsProgress','stageProgress']){ const start=html.indexOf('function '+name+'(');if(start<0)continue; let depth=0;for(let n=html.indexOf('{',start);n[scope,[...rows]]))).toBe(before);} finally{persistence.stop();} }); +it('reports matching SDK resolutions as historical reviews and keeps unverifiable items in the warning',async()=>{ + const {kv}=setup(); + const {createCaptureAutoRecovery}=await import('../src/capture/auto-recovery.js'); + const {capturePayloadDigest}=await import('../src/capture/receipt-digest.js'); + const {captureFailureHistoryDigest}=await import('../src/capture/sdk-resolution-record.js'); + const sourceDigest=capturePayloadDigest(payload); + const projection='a'.repeat(64); + const at='2026-11-10T00:00:00.000Z'; + const requestId='00000000-0000-4000-8000-000000000001'; + for(const [n,phase] of ['blocked','checking','blocked','checking'].entries()){ + const key='cap_'+String(n).repeat(40), eventId='synthetic-event-'+n, observationId='synthetic-obs-'+n; + const identity={key,eventId,observationId,sessionId:payload.sessionId,project:payload.project,hookType:payload.hookType}; + const row={...identity,id:'historical-'+n,version:1,kind:'item',phase,reason:phase==='blocked'?'VERIFICATION_BUDGET_EXHAUSTED':'VERIFICATION_PENDING', + sourceDigest:n===2?'b'.repeat(64):sourceDigest,projection,verificationAttempts:phase==='blocked'?3:2,nextAttemptAt:0}; + const history={...identity,status:'completed',failures:[],requests:{},totalAttempts:3,cycleAttempts:3,manualRetries:0,acceptedAt:at}; + const sdkResolution={version:1,phase:'committed',completion:'sdk',requestId,sourceDigest, + initialProjection:projection,verifiedProjection:projection,priorFailureDigest:captureFailureHistoryDigest(history as never), + priorInboxState:'dead',startedAt:at,completedAt:at}; + await kv.set(KV.captureRecovery,key,row); + await kv.set(KV.captureReview,key,{...history,sdkResolution}); + await kv.set(KV.captureInbox,key,{...identity,status:'pending',storageCompletion:'sdk',payload, + sdkResolutionId:requestId,sdkResolutionState:n===3?'pending':'committed'}); + } + const before=JSON.stringify([...kv.store].map(([scope,rows])=>[scope,[...rows]])); + const auto=createCaptureAutoRecovery(kv as never,{enabled:false,writerOwned:()=>true,admitted:()=>true,indexReady:()=>true}); + await auto.initialize(); + expect(auto.snapshot()).toMatchObject({blocked:1,verifying:1,resolved:0,sdkReviewed:2,blockedReason:'SDK_COMPLETION_ONLY'}); + expect(JSON.stringify([...kv.store].map(([scope,rows])=>[scope,[...rows]]))).toBe(before); +}); diff --git a/test/summary-coverage-api.test.ts b/test/summary-coverage-api.test.ts new file mode 100644 index 0000000000..9ef2dd0f70 --- /dev/null +++ b/test/summary-coverage-api.test.ts @@ -0,0 +1,120 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, expect, it, vi } from "vitest"; +import { summaryFingerprint } from "../src/functions/summary-state.js"; +import { createObservationReader } from "../src/ops/observation-pages.mjs"; +import { createStateDurabilityFence } from "../src/ops/state-durability.mjs"; +import { KV } from "../src/state/schema.js"; +import { registerApiTriggers } from "../src/triggers/api.js"; +import { mockKV, mockSdk } from "./helpers/mocks.js"; + +const roots: string[] = []; +const query = { includeSummary: "false", includeSummaryCoverage: "true", agentId: "*" }; +afterEach(async () => { + vi.useRealTimers(); + await Promise.all(roots.splice(0).map(path => rm(path, { recursive: true, force: true }))); +}); + +async function fixture() { + const root = await mkdtemp(join(tmpdir(), "am-summary-coverage-")); + roots.push(root); + const kv = mockKV(); + const id = "covered-legacy"; + const scope = KV.observations(id); + const session = { id, project: "synthetic", cwd: "/fixture", startedAt: "2026-01-01T00:00:00.000Z", + status: "completed" as const, observationCount: 1 }; + const row = { id: "obs_fixture", sessionId: id, timestamp: session.startedAt, + title: "Canonical title", narrative: "Canonical narrative", sourceRaw: { raw: "PRIVATE_FIXTURE_SOURCE" } }; + const summary = { sessionId: id, project: session.project, createdAt: session.startedAt, + title: "PRIVATE_FIXTURE_SUMMARY", observationCount: 1, coveredFingerprint: summaryFingerprint(session, [row as never]) }; + await kv.set(KV.sessions, id, session); + await kv.set(KV.summaries, id, summary); + await kv.set(scope, row.id, row); + await writeFile(join(root, encodeURIComponent(scope) + ".bin"), JSON.stringify({ [row.id]: row })); + const durability = createStateDurabilityFence({ storePath: root, completion: "sdk" }); + const reader = createObservationReader({ storePath: root, kv: { ...kv, durability } as never }); + const work = vi.spyOn(reader, "work"); + const get = vi.spyOn(kv, "get"); + const set = vi.spyOn(kv, "set"); + const update = vi.spyOn(kv, "update"); + const del = vi.spyOn(kv, "delete"); + const sdk = mockSdk({ looseTrigger: true }); + registerApiTriggers(sdk as never, Object.assign(kv, { observationReader: reader, durability }) as never, "fixture-secret"); + const call = (query_params = query) => sdk.fns.get("api::sessions")!({ headers: { authorization: "Bearer fixture-secret" }, query_params }) as Promise; + return { call, kv, work, get, set, update, del, session, summary, row, scope, reader, durability }; +} + +it("returns a read-only count from full canonical rows only when metadata coverage was requested", async () => { + const f = await fixture(); + expect((await f.call({ ...query, includeSummaryCoverage: "false" })).body.sessions).toEqual([f.session]); + expect(f.work).not.toHaveBeenCalled(); + expect(f.get).not.toHaveBeenCalled(); + const result = await f.call(); + expect(result.body.sessions).toEqual([{ ...f.session, summaryCoveredCount: 1 }]); + expect(f.work).toHaveBeenCalledWith(f.scope, { kind: "summary", signal: expect.any(AbortSignal) }); + expect(JSON.stringify(result)).not.toMatch(/PRIVATE_FIXTURE|summaryProgress/); + expect(f.set).not.toHaveBeenCalled(); + expect(f.update).not.toHaveBeenCalled(); + expect(f.del).not.toHaveBeenCalled(); +}); + +it("leaves coverage unknown when the legacy fingerprint is stale or explicit progress already exists", async () => { + const f = await fixture(); + await f.kv.set(KV.summaries, f.session.id, { ...f.summary, coveredFingerprint: "0".repeat(64) }); + expect((await f.call()).body.sessions[0]).not.toHaveProperty("summaryCoveredCount"); + await f.kv.set(KV.summaries, f.session.id, f.summary); + const summaryProgress = { status: "retrying", pendingCount: 1, processedCount: 0 }; + await f.kv.set(KV.sessions, f.session.id, { ...f.session, summaryProgress }); + f.work.mockClear(); + expect((await f.call()).body.sessions[0]).toEqual({ ...f.session, summaryProgress }); + expect(f.work).not.toHaveBeenCalled(); +}); + +it("strips a persisted coverage claim and requires fresh proof for each response", async () => { + const f = await fixture(); + await f.kv.set(KV.sessions, f.session.id, { ...f.session, summaryCoveredCount: 1 }); + await f.kv.set(KV.summaries, f.session.id, { ...f.summary, coveredFingerprint: "stale" }); + expect((await f.call()).body.sessions[0]).toEqual(f.session); + expect((await f.call({ ...query, includeSummaryCoverage: "false" })).body.sessions[0]).toEqual(f.session); + expect((await f.call({ ...query, includeSummary: "true" })).body.sessions[0]).not.toHaveProperty("summaryCoveredCount"); + await f.kv.set(KV.summaries, f.session.id, f.summary); + expect((await f.call()).body.sessions[0]).toEqual({ ...f.session, summaryCoveredCount: 1 }); +}); + +it.each(["observation", "summary"])("withholds matching coverage when a %s mutation races the proof", async (kind) => { + const f = await fixture(); + const work = f.reader.work.bind(f.reader); + f.work.mockImplementationOnce(async (scope, options) => { + const view = await work(scope, options); + const load = view.load.bind(view); + return { ...view, load: async row => { + const value = await load(row); + if (kind === "observation") { + f.reader.record(scope, "another-observation", { ...f.row, id: "another-observation" }); + } else { + await f.durability.mutate(KV.summaries, f.session.id, async () => {}); + } + return value; + } }; + }); + expect((await f.call()).body.sessions[0]).not.toHaveProperty("summaryCoveredCount"); +}); + +it("bounds observation work and returns metadata if a read stalls", async () => { + const f = await fixture(); + await f.kv.set(KV.sessions, f.session.id, { ...f.session, observationCount: 200 }); + expect((await f.call()).body.sessions[0]).not.toHaveProperty("summaryCoveredCount"); + expect(f.work).not.toHaveBeenCalled(); + await f.kv.set(KV.sessions, f.session.id, f.session); + vi.useFakeTimers(); + let finish!: (value: null) => void; + f.get.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; })); + const response = f.call(); + await vi.advanceTimersByTimeAsync(2000); + expect((await response).body.sessions).toEqual([f.session]); + const reads = f.get.mock.calls.length; + expect((await f.call()).body.sessions).toEqual([f.session]); + expect(f.get.mock.calls).toHaveLength(reads); + finish(null); +}); diff --git a/test/viewer-operations.test.ts b/test/viewer-operations.test.ts index b921b3d43e..b6a7242412 100644 --- a/test/viewer-operations.test.ts +++ b/test/viewer-operations.test.ts @@ -20,7 +20,7 @@ function context(names: string[], extra: Record = {}) { return ctx; } function fixtures(extra: Record = {}) { - return context(["esc", "fmtNum", "humanizeHealthFlag", "quarantineReason", "quarantineRecords", "backgroundWorkSnapshot", "memoryPressureStatus", "snapshotStatus", "storageDurabilityHtml", "inspectionErrorText", "inspectionRequest", "readinessStatusHtml", "controlDiagnosticHtml", "operationsStages", "recordOperationsProgress", "stageProgress", "progressDuration", "operationsProgressHtml", "operationsPanelHtml"], { + return context(["esc", "fmtNum", "humanizeHealthFlag", "quarantineReason", "quarantineRecords", "summaryStageProgress", "backgroundWorkSnapshot", "memoryPressureStatus", "snapshotStatus", "storageDurabilityHtml", "inspectionErrorText", "inspectionRequest", "readinessStatusHtml", "controlDiagnosticHtml", "operationsStages", "recordOperationsProgress", "stageProgress", "progressDuration", "operationsProgressHtml", "operationsPanelHtml"], { operations: { health: {}, sessions: [], control: null, job: null, available: false, loading: false, error: '', controlError: '', jobError: '', checking: false, submitting: false, controlBusy: false, detailsOpen: false }, store: {}, conn: { state: 'offline' }, autoRefresh: { enabled: true, seconds: 30 }, ...extra, }); @@ -72,6 +72,23 @@ describe("custom operations panel", () => { expect(c.backgroundWorkSnapshot([{ id:'x', status:'completed', observationCount:10 }], {}, true).totals.summary).toBeNull(); expect(c.backgroundWorkSnapshot([], {}, false).totals.graph).toBeNull(); }); + it("uses confirmed legacy coverage in both summary counts and stage progress", () => { + const c = fixtures(); + const session = { id: 'legacy', status: 'completed', observationCount: 1, summaryCoveredCount: 1, + enrichmentProgress: { compress: { enabled: false }, graph: { enabled: false } } }; + const work = c.backgroundWorkSnapshot([session], {}, true); + expect(work.totals.summary).toBe(0); + expect(work.unknownStageCounts.summary).toBe(0); + expect(work.rows).toEqual([]); + expect(c.operationsStages(work, [session], {}, true).find((stage:any) => stage.key === 'summary')) + .toMatchObject({ pending: 0, completed: 1, counters: { legacy: 1 } }); + const mismatch = { ...session, observationCount: 2 }; + const unknown = c.backgroundWorkSnapshot([mismatch], {}, true); + expect(unknown.totals.summary).toBeNull(); + expect(c.operationsStages(unknown, [mismatch], {}, true).find((stage:any) => stage.key === 'summary').completed).toBeNull(); + const retry = { ...session, summaryProgress: { status: 'retrying', pendingCount: 1, processedCount: 0 } }; + expect(c.backgroundWorkSnapshot([retry], {}, true).totals.summary).toBe(1); + }); it("shows the confirmed minimum and the unknown session/stage scope separately",()=> { const c=fixtures();c.operations.available=true; c.operations.sessions=[{id:'known',summaryProgress:{pendingCount:3,status:'running'},enrichmentProgress:{compress:{pendingCount:4,status:'waiting_provider'},graph:{pendingCount:5,status:'queued'}}},{id:'unknown',observationCount:10}]; @@ -212,7 +229,7 @@ describe("manual operations commands", () => { const c=fixtures({apiGet,renderOperations:vi.fn(),operations:{health:{},sessions:[],control:null,job,available:false,generation:0,progressSamples:{}}}); runInNewContext(source('loadOperations'),c); await c.loadOperations(); - expect(apiGet.mock.calls.map(call=>call[0])).toEqual(['health','sessions?includeSummary=false','background/control']); + expect(apiGet.mock.calls.map(call=>call[0])).toEqual(['health','sessions?includeSummary=false&includeSummaryCoverage=true','background/control']); expect(c.operations.job).toEqual(job); expect(viewer).not.toMatch(/action === ['"](?:submit-codex-inspection|copy-inspection-request)['"]/); }); From 79fdcbb1ef4a5c2cc0d945eaa30de79e7572abeb Mon Sep 17 00:00:00 2001 From: Daniel Date: Wed, 11 Nov 2026 15:54:11 +0900 Subject: [PATCH 13/23] fix(graph): shard retrieval index builds --- .cursor-plugin/plugin.json | 2 +- CHANGELOG.md | 6 ++++ docs/reliability/graph-index-migration.md | 4 ++- integrations/hermes/plugin.yaml | 2 +- integrations/omp/package.json | 2 +- integrations/openclaw/openclaw.plugin.json | 2 +- integrations/openclaw/package.json | 2 +- integrations/openclaw/plugin.yaml | 2 +- package.json | 2 +- packages/mcp/package.json | 4 +-- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/.devin-plugin/plugin.json | 4 +-- plugin/opencode/plugin.json | 2 +- plugin/plugin.json | 2 +- plugin/scripts/plugin-bridge.mjs | 2 +- scripts/docs-sync.state.json | 2 +- src/functions/export-import.ts | 2 +- src/state/graph-generation.ts | 4 +-- src/state/graph-index-migration.ts | 14 +++++--- src/state/graph-retrieval-index.ts | 30 +++++++++++----- src/types.ts | 4 +-- src/version.ts | 2 +- test/graph-index-held-boot.test.ts | 2 +- test/graph-index-migration.test.ts | 40 +++++++++++++++++++++- 25 files changed, 102 insertions(+), 40 deletions(-) diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 3843125c3f..eb42a1eba9 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.", "author": { "name": "Rohit Ghumare", diff --git a/CHANGELOG.md b/CHANGELOG.md index 95de87d1a3..c17be52dcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## 0.9.32-daniel.68 — Sharded graph retrieval index + +- Store new graph retrieval builds in per-build hash shards to stay below the native file namespace size limit. +- Explicit graph-index migration rebuilds a ready legacy index from canonical graph records and verifies inventory before publishing readiness. The old index data and canonical nodes, edges, and history are preserved. +- Continue to read legacy indexes and resume their existing journals. Newly rebuilt indexes use schema 3 and require the sharding-aware server. + ## 0.9.32-daniel.67 — Health current-state display - Count recorded matching SDK resolutions separately from unresolved recovery checkpoints. diff --git a/docs/reliability/graph-index-migration.md b/docs/reliability/graph-index-migration.md index 389e1126d3..789ffc854f 100644 --- a/docs/reliability/graph-index-migration.md +++ b/docs/reliability/graph-index-migration.md @@ -14,7 +14,7 @@ To build indexes for existing graph data, schedule a maintenance window and expl agentmemory graph-index migrate --allow-legacy-scan --json ``` -**Initial discovery is not bounded.** The pinned engine cannot paginate its state listings. Migration reads each complete legacy node, edge and history scope once, including full record values. Large stores can consume substantial memory and delay other requests during those reads. An HTTP timeout does not cancel an engine allocation already in progress. No ordinary search, status request or startup silently authorizes this scan. +Initial discovery scans each canonical node, edge and history scope. File-backed node and edge scans retain only IDs for the manifest. Other backends can still require a complete state listing. Large stores can delay other requests during discovery. An HTTP timeout does not cancel an engine allocation already in progress. No ordinary search, status request or startup silently authorizes this scan. The command returns a job ID after saving its intent. It runs in the background in an isolated index build within the current graph generation; canonical records are preserved. Capture, imports, mesh updates, temporal changes and snapshot restores maintain that build while migration runs. Status reports discovered and processed totals, readiness and partial coverage. @@ -38,6 +38,8 @@ Progress and recovery journals use the configured state backend. An acknowledged Oversized source fields remain in canonical storage. Bounded projections record partial coverage when they cannot represent a field fully, and status exposes the affected record count. A ready index with partial coverage does not claim every graph fact is searchable. Search budgets and pagination can also truncate a request; callers should check its graph diagnostics. +An explicit migration can replace a ready schema-2 index with schema 3. Schema 3 stores each build in independent shards. The previous index remains on disk. The server verifies the new inventory before declaring it ready. + Indexes add storage and write overhead. A replacement build isolates previous derived records by build ID; it does not reclaim their disk space. Repeated rebuilds and graph generations can therefore accumulate retained data. Bounded records and reads do not imply bounded total storage. The CLI honors `AGENTMEMORY_URL`, local `--port` and `--instance` selection, and the existing credential resolution. Named instances sharing a home directory share its saved API credential by default. To use separate credentials, set a different `AGENTMEMORY_SECRET` for each instance and its clients, or use separate home directories. Equivalent authenticated endpoints are `GET /agentmemory/graph/index`, `POST /agentmemory/graph/index/migrate`, and `POST /agentmemory/graph/index/resume`. Mutation bodies accept only the boolean `allowLegacyScan` flag. Repeated start requests join the running job. Use one AgentMemory graph worker per state store; the writer lock coordinates operations within that worker. diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml index a7b90b2f8c..722cb7c45d 100644 --- a/integrations/hermes/plugin.yaml +++ b/integrations/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.67 +version: 0.9.32-daniel.68 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/integrations/omp/package.json b/integrations/omp/package.json index 8271992e4b..235340a44a 100644 --- a/integrations/omp/package.json +++ b/integrations/omp/package.json @@ -2,7 +2,7 @@ "name": "agentmemory-omp-extension", "private": true, "type": "module", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "omp": { "name": "agentmemory", "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.", diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json index 901bccf4fd..2d2ad55e91 100644 --- a/integrations/openclaw/openclaw.plugin.json +++ b/integrations/openclaw/openclaw.plugin.json @@ -3,7 +3,7 @@ "kind": "memory", "name": "agentmemory", "description": "Persistent cross-session memory for OpenClaw via agentmemory.", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "configSchema": { "type": "object", "additionalProperties": false, diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json index 21e9fbac62..1f36ecffac 100644 --- a/integrations/openclaw/package.json +++ b/integrations/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "type": "module", "openclaw": { "extensions": [ diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml index 1c5b2a81b5..1991bf3ff9 100644 --- a/integrations/openclaw/plugin.yaml +++ b/integrations/openclaw/plugin.yaml @@ -1,5 +1,5 @@ name: agentmemory -version: 0.9.32-daniel.67 +version: 0.9.32-daniel.68 description: "Persistent cross-session memory for OpenClaw via agentmemory." author: "Rohit Ghumare" homepage: "https://github.com/rohitg00/agentmemory" diff --git a/package.json b/package.json index bfd5fd2eae..ce6a67f448 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives", "type": "module", "main": "dist/index.mjs", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 6bba78643d..c68d676d1d 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@agentmemory/mcp", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint", "type": "module", "bin": { @@ -28,7 +28,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "0.9.32-daniel.67" + "@agentmemory/agentmemory": "0.9.32-daniel.68" }, "publishConfig": { "access": "public", diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index d46f830273..c08d8d84cf 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 7629c4ce8d..fa0a6fb418 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json index cb6af89783..041ccec895 100644 --- a/plugin/.devin-plugin/plugin.json +++ b/plugin/.devin-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "displayName": "agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.", "logo": "assets/icon.svg", "author": { @@ -23,7 +23,7 @@ "command": "npx", "args": [ "-y", - "@agentmemory/mcp@0.9.32-daniel.67" + "@agentmemory/mcp@0.9.32-daniel.68" ], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}" diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json index 4f3062a28e..4dfd3422f8 100644 --- a/plugin/opencode/plugin.json +++ b/plugin/opencode/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory-capture", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/plugin.json b/plugin/plugin.json index 4b4e9fd470..fc58b648bf 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentmemory", - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index 58ed4a1022..db0832d908 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; //#region src/version.ts -const VERSION = "0.9.32-daniel.67"; +const VERSION = "0.9.32-daniel.68"; //#endregion //#region src/secret-store.ts const SECRET_KEY = "AGENTMEMORY_SECRET"; diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index f85e1ffdfa..f948f83952 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -1,5 +1,5 @@ { - "version": "0.9.32-daniel.67", + "version": "0.9.32-daniel.68", "facts": { "mcpTools": [ "55" diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index b63f1020b1..9b6761f5df 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -319,7 +319,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo const strategy = data.strategy || "merge"; const importData = data.exportData; - const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.32-daniel.67", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); + const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.32-daniel.67", "0.9.32-daniel.68", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]); if (!supportedVersions.has(importData.version)) { return { success: false, diff --git a/src/state/graph-generation.ts b/src/state/graph-generation.ts index cd0e172d86..832e15961a 100644 --- a/src/state/graph-generation.ts +++ b/src/state/graph-generation.ts @@ -105,7 +105,7 @@ function graphView(kv: StateKV, id: string | null): StateKV { export async function resetGraphGeneration(kv: StateKV, snapshot: unknown): Promise { const id = randomUUID(); await kv.set(physicalScope(KV.graphSnapshot, id), "current", snapshot); - await initializeGraphIndex(graphView(kv, id), { status: "ready" }); + await initializeGraphIndex(graphView(kv, id), { status: "ready", schema: 3 }); await kv.set(CONTROL_SCOPE, CONTROL_KEY, id); } @@ -114,7 +114,7 @@ export async function replaceGraphGeneration(kv: StateKV, initialize: (fresh: const { target, id: previous } = views.get(pinnedState)!; const id = randomUUID(); const fresh = graphView(target, id); - await initializeGraphIndex(fresh, { status: "ready" }); + await initializeGraphIndex(fresh, { status: "ready", schema: 3 }); const result = await initialize(fresh); // A delayed import cannot replace a reset that happened after it was pinned. if (await generation(target) === previous) { diff --git a/src/state/graph-index-migration.ts b/src/state/graph-index-migration.ts index 9e77bfec98..46d40d2ad7 100644 --- a/src/state/graph-index-migration.ts +++ b/src/state/graph-index-migration.ts @@ -206,11 +206,13 @@ export class GraphIndexMigrationController { let job = readJob(await state.get(KV.graphIndexMigration, GRAPH_INDEX_MIGRATION_KEY)); if (job?.generation !== generation) job = null; const unfinishedCheckpoint = job?.buildId === control?.buildId && (job?.state === "paused" || Boolean(job?.error)); - if (control?.status === "ready" && !control.pending && !control.batchPending && !unfinishedCheckpoint) return; + const upgradeLayout = control?.schema === 2 && control.status === "ready" && + !control.pending && !control.batchPending && !unfinishedCheckpoint && !options.resume && options.allowLegacyScan; + if (control?.status === "ready" && !control.pending && !control.batchPending && !unfinishedCheckpoint && !upgradeLayout) return; if (options.resume && !job) throw new GraphIndexMigrationError("no-job", "No graph index migration exists. Run graph-index migrate --allow-legacy-scan first."); if (options.resume && job?.sealed && !control) throw new GraphIndexMigrationError("invalid-state", "The sealed build control is missing. Start a new build with graph-index migrate --allow-legacy-scan."); if (options.resume && control?.status === "paused") throw new GraphIndexMigrationError("invalid-state", "The index requires a new build. Run graph-index migrate --allow-legacy-scan after fixing the reported data."); - if (!job || replaceCorruptControl || (!control && job.sealed) || control?.status === "paused" || (control && control.buildId !== job.buildId) || + if (!job || replaceCorruptControl || upgradeLayout || (!control && job.sealed) || control?.status === "paused" || (control && control.buildId !== job.buildId) || (!options.resume && options.allowLegacyScan && control?.batchPending)) { if (options.resume) throw new GraphIndexMigrationError("invalid-state", "The graph index build changed. Start an explicit migration again."); if (!options.allowLegacyScan) throw new GraphIndexMigrationError("consent-required", "Initial discovery requires allowLegacyScan: true; complete legacy graph scopes are read during maintenance."); @@ -218,14 +220,14 @@ export class GraphIndexMigrationController { job = { schema: 1, jobId: randomUUID(), buildId: randomUUID(), generation, state: "discovering", sealed: false, phase: "nodes", page: 0, offset: 0, processed: 0, totals: { nodes: 0, edges: 0, history: 0 }, pages: { nodes: 0, edges: 0, history: 0 }, startedAt: now, updatedAt: now }; await state.set(KV.graphIndexMigration, GRAPH_INDEX_MIGRATION_KEY, job); - await initializeGraphIndex(state, { buildId: job.buildId, status: "building" }); + await initializeGraphIndex(state, { buildId: job.buildId, status: "building", schema: 3 }); } else { if (!job.sealed && !options.allowLegacyScan) throw new GraphIndexMigrationError("consent-required", "Discovery did not finish. Resume with --allow-legacy-scan to authorize another complete legacy scan."); if (!control) { // A previous control write may have been lost after other index writes succeeded. job = { ...job, buildId: randomUUID() }; await this.save(state, job); - await initializeGraphIndex(state, { buildId: job.buildId, status: "building" }); + await initializeGraphIndex(state, { buildId: job.buildId, status: "building", schema: 3 }); } job = { ...job, state: job.sealed ? "building" : "discovering", error: undefined, updatedAt: new Date().toISOString() }; await state.set(KV.graphIndexMigration, GRAPH_INDEX_MIGRATION_KEY, job); @@ -283,7 +285,9 @@ export class GraphIndexMigrationController { job.phase = phase; await this.assertActive(state, job); await this.save(state, job); - const rows = await state.list<{ id?: unknown }>(SCOPES[phase]); + const rows = await state.list<{ id?: unknown }>(SCOPES[phase], { + project: value => ({ id: (value as { id?: unknown } | null)?.id }), + }); await this.assertActive(state, job); let ids: string[] = []; const flush = async () => { diff --git a/src/state/graph-retrieval-index.ts b/src/state/graph-retrieval-index.ts index feb71d66b7..29f8e9b164 100644 --- a/src/state/graph-retrieval-index.ts +++ b/src/state/graph-retrieval-index.ts @@ -43,9 +43,15 @@ const recordKey = (buildId: string, kind: GraphIndexRecordKind, id: string) => ` const rootKey = (buildId: string, posting: string) => `${buildId}:root:${posting}`; const entryKey = (buildId: string, posting: string, id: string) => `${buildId}:entry:${posting}:${id}`; const countKey = (kind: GraphIndexRecordKind) => kind === "node" ? "nodes" : kind === "edge" ? "edges" : "historyEdges"; +function indexDataScope(control: GraphRetrievalIndexControl, key: string): string { + if (control.schema === 2) return KV.graphRetrievalData; + // Each key ends in a SHA-256 digest. Two hex digits make 256 independent + // files per build, including for a single very large linked posting. + return `${KV.graphRetrievalData}:build:${control.buildId}:${key.slice(-64, -62)}`; +} function validateControl(value: GraphRetrievalIndexControl): void { - if (bytes(value) > MAX_CONTROL_BYTES || value.schema !== 2 || typeof value.buildId !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(value.buildId) || + if (bytes(value) > MAX_CONTROL_BYTES || (value.schema !== 2 && value.schema !== 3) || typeof value.buildId !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(value.buildId) || !["building", "ready", "paused"].includes(value.status) || ![value.revision, value.nodes, value.edges, value.historyEdges, value.incompleteRecords, value.otherTypes].every(finiteCount) || !value.nodesByType || !value.edgesByType || @@ -63,10 +69,10 @@ export async function getGraphIndexStatus(state: StateKV): Promise { +export async function initializeGraphIndex(state: StateKV, options: { status: "building" | "ready"; buildId?: string; schema?: 2 | 3 }): Promise { const kv = await pinGraphState(state); return lock(kv, async () => { - const value: GraphRetrievalIndexControl = { schema: 2, buildId: options.buildId ?? randomUUID(), status: options.status, + const value: GraphRetrievalIndexControl = { schema: options.schema ?? 2, buildId: options.buildId ?? randomUUID(), status: options.status, revision: 0, nodes: 0, edges: 0, historyEdges: 0, incompleteRecords: 0, nodesByType: {}, edgesByType: {}, otherTypes: 0, updatedAt: new Date().toISOString() }; validateControl(value); const previous = await kv.get(KV.graphRetrievalControl, CONTROL_KEY); @@ -172,7 +178,7 @@ function validateRecord(value: GraphRetrievalIndexRecord): void { async function planRecord(kv: StateKV, control: GraphRetrievalIndexControl, kind: GraphIndexRecordKind, id: string, input: unknown): Promise { const writes = new Map(); - const read = async (key: string): Promise => writes.has(key) ? writes.get(key) as T | null : kv.get(KV.graphRetrievalData, key); + const read = async (key: string): Promise => writes.has(key) ? writes.get(key) as T | null : kv.get(indexDataScope(control, key), key); const put = (key: string, value: unknown) => { if (bytes(value) > GRAPH_INDEX_MAX_RECORD_BYTES) throw new GraphIndexError("Graph retrieval index write exceeds record budget"); writes.set(key, value); }; const key = recordKey(control.buildId, kind, id); const before = await read(key); @@ -243,16 +249,18 @@ async function planRecord(kv: StateKV, control: GraphRetrievalIndexControl, kind async function applyJournal(kv: StateKV, control: GraphRetrievalIndexControl, journal: IndexJournal): Promise { if (journal.schema !== 1 || journal.buildId !== control.buildId || journal.revision !== control.revision || !Array.isArray(journal.writes) || journal.writes.length > 2048 || bytes(journal) > MAX_JOURNAL_BYTES || journal.next.buildId !== control.buildId || - journal.next.revision !== control.revision + 1 || journal.next.pending) throw new GraphIndexError("Invalid graph retrieval recovery journal"); + journal.next.schema !== control.schema || journal.next.revision !== control.revision + 1 || journal.next.pending) throw new GraphIndexError("Invalid graph retrieval recovery journal"); validateControl(journal.next); for (const write of journal.writes) { - if (!write || typeof write.key !== "string" || !write.key.startsWith(`${control.buildId}:`) || write.key.length > 512 || bytes(write.value) > GRAPH_INDEX_MAX_RECORD_BYTES) { + if (!write || typeof write.key !== "string" || !write.key.startsWith(`${control.buildId}:`) || write.key.length > 512 || + (control.schema === 3 && !/:[a-f0-9]{64}$/.test(write.key)) || bytes(write.value) > GRAPH_INDEX_MAX_RECORD_BYTES) { throw new GraphIndexError("Invalid graph retrieval recovery write"); } } for (const write of journal.writes) { - if (write.value === null) await kv.delete(KV.graphRetrievalData, write.key); - else await kv.set(KV.graphRetrievalData, write.key, write.value); + const scope = indexDataScope(control, write.key); + if (write.value === null) await kv.delete(scope, write.key); + else await kv.set(scope, write.key, write.value); } await kv.set(KV.graphRetrievalControl, CONTROL_KEY, journal.next); } @@ -325,6 +333,10 @@ export async function finishGraphIndexBuild(state: StateKV, buildId: string): Pr return lock(kv, async () => { const current = await getGraphIndexStatus(kv); if (!current || current.buildId !== buildId || current.status === "paused" || current.pending || current.batchPending) throw new GraphIndexError("Graph index build is incomplete or superseded"); + if (current.schema === 3) { + const reader = new GraphIndexReader(kv, await getGraphGeneration(kv), current, { maxReads: 16 }); + for (const kind of ["nodes", "edges", "historyEdges"] as const) await reader.posting(kind, "", { limit: 1 }); + } const next = { ...current, status: "ready" as const, revision: current.revision + 1, updatedAt: new Date().toISOString() }; await kv.set(KV.graphRetrievalControl, CONTROL_KEY, next); return next; @@ -429,7 +441,7 @@ export class GraphIndexReader { else this.active++; try { if (this.options.signal?.aborted || this.exhausted) { this.exhausted = true; return null; } - const value = await this.state.get(scope, key); + const value = await this.state.get(scope === KV.graphRetrievalData ? indexDataScope(this.status, key) : scope, key); const size = bytes(value); this.readBytes += size; if (this.readBytes > this.maxBytes || this.options.signal?.aborted) { this.exhausted = true; return null; } diff --git a/src/types.ts b/src/types.ts index bcd8a2a9b1..e377c66fac 100644 --- a/src/types.ts +++ b/src/types.ts @@ -419,7 +419,7 @@ export interface ExportCollectionPagination { } export interface ExportData { - version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.32-daniel.67" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; + version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.32-daniel.67" | "0.9.32-daniel.68" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32"; exportedAt: string; sessions: Session[]; observations: Record; @@ -568,7 +568,7 @@ export interface GraphIndexMembership { } export interface GraphRetrievalIndexControl { - schema: 2; + schema: 2 | 3; buildId: string; status: "building" | "ready" | "paused"; revision: number; diff --git a/src/version.ts b/src/version.ts index b95ff95da8..ffd54629fb 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ -export const VERSION = "0.9.32-daniel.67"; +export const VERSION = "0.9.32-daniel.68"; export const III_PINNED_VERSION = "0.25.0"; diff --git a/test/graph-index-held-boot.test.ts b/test/graph-index-held-boot.test.ts index d2567bbbfd..a871dd66b2 100644 --- a/test/graph-index-held-boot.test.ts +++ b/test/graph-index-held-boot.test.ts @@ -33,7 +33,7 @@ function fixture() { const f = fixture(); f.rows.set(KV.graphNodes, new Map([["a", node("a")], ["b", node("b")]])); const controller = new GraphIndexMigrationController(f.kv), entered = deferred(), release = deferred(); f.intercept(async (fn, p) => { - if (fn === "state::set" && p.scope === KV.graphRetrievalData) { entered.resolve(); await release.promise; } + if (fn === "state::set" && p.scope.startsWith(`${KV.graphRetrievalData}:build:`)) { entered.resolve(); await release.promise; } }); await controller.start({ allowLegacyScan: true }); await entered.promise; const stopped = controller.stop(); release.resolve(); await stopped; f.intercept(); diff --git a/test/graph-index-migration.test.ts b/test/graph-index-migration.test.ts index b1d90901da..799ec7f1d0 100644 --- a/test/graph-index-migration.test.ts +++ b/test/graph-index-migration.test.ts @@ -7,7 +7,8 @@ import { GraphIndexMigrationController, getGraphIndexMigrationStatus, graphIndexManifestKey, type GraphIndexManifestPage, type GraphIndexMigration, } from "../src/state/graph-index-migration.js"; -import { createGraphIndexReader, getGraphIndexStatus } from "../src/state/graph-retrieval-index.js"; +import { createGraphIndexReader, getGraphIndexStatus, initializeGraphIndex } from "../src/state/graph-retrieval-index.js"; +import { queryGraphIndex } from "../src/functions/graph-index-query.js"; import type { GraphNode } from "../src/types.js"; const now = "2026-10-14T00:00:00.000Z"; @@ -37,6 +38,43 @@ function setup() { } describe("explicit graph index migration", () => { + it("replaces a ready legacy index with isolated shards without changing its data or canonical rows", async () => { + const { kv, controller, rows, intercept } = setup(); + const old = await initializeGraphIndex(kv, { status: "ready" }); + for (const id of ["a", "b", "c", "d"]) await kv.set(KV.graphNodes, id, node(id)); + await kv.set(KV.graphEdges, "ab", { + id: "ab", sourceNodeId: "a", targetNodeId: "b", type: "related_to", weight: 1, + sourceObservationIds: ["observation"], createdAt: now, + }); + const protectedScopes = [KV.graphNodes, KV.graphEdges, KV.graphRetrievalData]; + const before = protectedScopes.map(scope => structuredClone(rows.get(scope))); + expect((await controller.start()).buildId).toBe(old.buildId); + let shardWrites = 0; + intercept((fn, payload) => { + if (fn === "state::set" && payload.scope.startsWith(`${KV.graphRetrievalData}:build:`) && ++shardWrites === 3) { + throw new Error("interrupted shard publication"); + } + }); + await controller.start({ allowLegacyScan: true }); + await controller.waitForIdle(); + expect(await controller.status()).toMatchObject({ state: "paused", ready: false }); + const interrupted = await getGraphIndexStatus(kv); + expect(interrupted).toMatchObject({ schema: 3, pending: { kind: "node" } }); + intercept(); + await controller.start({ resume: true }); + await controller.waitForIdle(); + const index = await getGraphIndexStatus(kv); + expect(index).toMatchObject({ schema: 3, status: "ready", nodes: 4, edges: 1 }); + expect(index!.buildId).toBe(interrupted!.buildId); + expect(index!.buildId).not.toBe(old.buildId); + expect(protectedScopes.map(scope => rows.get(scope))).toEqual(before); + expect([...rows.keys()].filter(scope => scope.startsWith(`${KV.graphRetrievalData}:build:${index!.buildId}:`)).length).toBeGreaterThan(1); + const result = await queryGraphIndex(kv, { limit: 500 }); + expect(result.nodes.map(row => row.id).sort()).toEqual(["a", "b", "c", "d"]); + expect(result.edges.map(row => row.id)).toEqual(["ab"]); + expect((await controller.start({ allowLegacyScan: true })).buildId).toBe(index!.buildId); + }); + it("keeps legacy status and boot read-only without a snapshot or graph listing", async () => { const { kv, controller, calls, rows } = setup(); rows.set(KV.graphNodes, new Map([["old", node("old")]])); From f3579e4430c737cebfc6e1c9ca434fc4b5523e18 Mon Sep 17 00:00:00 2001 From: Daniel-Hong Date: Fri, 13 Nov 2026 18:35:42 +0900 Subject: [PATCH 14/23] chore(upstream): stage exact v0.9.33 fixes on isolated review branch Import only official blobs identical to the personal v0.9.32 base and add regression tests. Keep modified engine, capture, safety and storage paths intact. Require fresh parity tests, docs generation and client bundle review before promotion. --- CHANGELOG.md | 7 + .../UPSTREAM-0.9.33-INTEGRATION.md | 39 ++ src/cli/connect/claude-code.ts | 61 ++- src/cli/doctor-diagnostics.ts | 38 +- src/config.ts | 47 +- src/hooks/_capture-filter.ts | 76 ++- src/hooks/session-end.ts | 28 ++ src/mcp/plugin-bridge.ts | 4 +- src/mcp/rest-proxy.ts | 13 +- src/providers/circuit-breaker.ts | 11 +- src/providers/embedding/clip.ts | 20 +- src/providers/index.ts | 8 +- src/providers/resilient.ts | 12 +- src/secret-store.ts | 10 +- src/state/hybrid-search.ts | 38 +- test/capture-filter.test.ts | 99 ++++ test/circuit-breaker.test.ts | 61 +++ test/claude-code-with-hooks.test.ts | 459 +++++++++++++++++- test/cli-connect.test.ts | 2 + test/clip-embedding-provider.test.ts | 152 +++++- test/hybrid-search.test.ts | 60 ++- test/mcp-standalone-proxy.test.ts | 44 +- test/plugin-bridge-secret.test.ts | 18 + test/provider-placeholder-keys.test.ts | 261 ++++++++++ test/resilient-content-filter.test.ts | 106 ++++ test/search-project-isolation.test.ts | 4 +- test/session-end-transcript.test.ts | 44 +- 27 files changed, 1618 insertions(+), 104 deletions(-) create mode 100644 docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md create mode 100644 test/provider-placeholder-keys.test.ts create mode 100644 test/resilient-content-filter.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 67a7429f84..f98b299c0b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ ## [Unreleased] +### Official v0.9.33 source-only integration review (unverified) + +- Import 25 upstream implementation/regression file blobs only where personal is unchanged from official v0.9.32; preserve all modified personal files and the modified iii engine/SDK pin. +- Candidate provider, retrieval, CLIP, MCP, Claude connector, core hook redaction and SessionEnd fixes require full tests, generated-client verification and manual parity review before merging or deploying. +- No private customization has been removed, no service/host/data has been touched. See `docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md`. + + ### Bounded capture proof pages - Limit routine authenticated capture/status checks to 32 physical-key SDK proofs per page. Keep whole retained-source counts separate and omit whole-inbox completion counts for partial pages. diff --git a/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md b/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md new file mode 100644 index 0000000000..728d0ed610 --- /dev/null +++ b/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md @@ -0,0 +1,39 @@ +# Official v0.9.33 — selective integration review + +## Reproducible source pins + +- Official v0.9.32 base: `0da38f1d5067a479a6e5c4653de342ba43ca22b2`. +- Personal original head: `658f3fdc3350a64670b28b50789defca0eef462a` (`0.9.32-daniel.55`). +- Official v0.9.33 tag: `28ffc538b81b265e2f649354ed9f88b0c12ae414` (2026-11-09). +- Staged review branch: `integration/v0.9.33-review`; upstream mirror branch: `sync/upstream-v0.9.33`. + +Exactly **25** upstream v0.9.33 implementation/test files are imported as upstream Git blobs, but only after verifying that each file in the current `personal` tree is byte-for-byte the same blob as the upstream v0.9.32 base. This deliberately does **not** merge the entire v0.9.33 tree or replace any personalized code. The locally changed `test/cli-doctor-fixes.test.ts` is intentionally not overwritten; any missing upstream regression from that file requires a manual minimal port. + +## Staged upstream source candidates — no parity certification yet + +| Change | Imported source and relevant upstream regression | Remaining check | +| --- | --- | --- | +| #1350 / #1277 | Circuit-breaker success reset and content-filter errors not counted as provider outage | Ensure real HTTP 5xx still trip breaker. | +| #1696 | Hybrid search larger fusion pool, saved-memory diversification, refill after stale hits | Personal CJK/project isolation, large-store retrieval and old-memory ordering. | +| #1250 | CLIP text tower to produce comparable image/text embeddings | Same 512-dimension projections, no automatic re-embedding. | +| #1588 | Placeholder provider keys recognized consistently by config and doctor | Preserve explicit OpenAI selection and local plain-http exception. | +| #1703 | Claude `CLAUDE_CONFIG_DIR` path selection | Actual launch environment and native hook/MCP profile equivalence. | +| #1691 | MCP long-call timeout in source REST proxy/plugin bridge | Personal generated `.mjs` and CLI shim parity, no live timeout changes. | +| #1695 / #1701 | Redact before truncation and recognize compound secret names in core filter | Native/global bundled scripts and private capture path not yet updated/verified. | +| #1692 | Give core SessionEnd hook time to finish | Generated client bundles, source-first delivery and native retained originals. | + +## Deferred / non-replaceable without a separate parity gate + +Official iii/SDK 0.25.1, state scope paging, 64 MiB transport changes, engine auto-install and registry worker changes are **not** incorporated. The personal modified iii 0.22.1, SDK 0.25.0, exact KV save-loop patch, SDK write/flush certification, source-generation and writer identity rules stay unchanged. Official features with overlapping names are not proof of equivalent crash durability. The engine upgrade requires isolated real-engine + existing-format migration/rollback-read tests before any change to engine pin. + +Retain personal sourceRaw and incremental summary/cursor, capture inbox/original/retry/quarantine/uncertainty, native six-event hooks and private source retention, embedding publication evidence, background durable holds, health/Viewer, update trust and feedback store unchanged. Official #1698 orphan facet heal, #1601 eviction cleanup, #1687 partial-vector repair, #1545/#1544 consolidation/reflection, #1527 session filters, #1693/#1220 hook pre-tool context, remaining generated hook security and large-store fixes remain **unported or partly covered**. No custom code is retired. `docs/customizations/catalog.json` retains `unverified` decisions. + +## Mandatory review before promotion to personal or a deployment candidate + +1. From this exact source tree, run `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm run docs:check` and a diff check. Commit all generated artifacts only after inspecting them. +2. Use isolated temporary HOME and Vitest default fork pool for `npm test`; run eval typecheck, compare known baseline diagnostics. Tests copied from upstream have **not been executed** while staging this source; passing test names do not constitute proof. +3. Verify bundled native/global Claude/Codex scripts reflect the reviewed source changes; preserve actual client hooks, original-first image/spool, project scope, strict secret redaction and 500/190-second timeout semantics where applicable. Never infer deployed behavior from an unchanged generated bundle. +4. Require release gate, isolated SDK/real-engine/storage cold-start/read-back/incomplete-write tests and existing data-format compatibility for any engine or persistence changes. No production store, settings, service, hook trust or backlog should be touched during this code review. +5. Remove a custom feature only in an independent follow-up after its complete parity and no-data-loss regression matrix passes. Preserve recorded history, old-format readers and uncertainty markers; no automatic old-memory replacement. + +Status: **prepared for source review only; build, tests, docs regeneration, generated-hook parity, live operating verification and deploy are not claimed.** diff --git a/src/cli/connect/claude-code.ts b/src/cli/connect/claude-code.ts index 1882be86cc..271468bf2e 100644 --- a/src/cli/connect/claude-code.ts +++ b/src/cli/connect/claude-code.ts @@ -1,7 +1,8 @@ -import { existsSync, mkdirSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs"; import { homedir } from "node:os"; -import { join } from "node:path"; +import { isAbsolute, join, normalize, resolve } from "node:path"; import * as p from "@clack/prompts"; +import { isEnvFileValue } from "../../config.js"; import type { ConnectAdapter, ConnectOptions, ConnectResult } from "./types.js"; import { AGENTMEMORY_MCP_BLOCK, @@ -18,9 +19,18 @@ import { type HookManifest, } from "./codex-hooks.js"; -const CLAUDE_DIR = join(homedir(), ".claude"); -const CLAUDE_JSON = join(homedir(), ".claude.json"); -const CLAUDE_SETTINGS = join(CLAUDE_DIR, "settings.json"); +function claudeConfigPaths() { + const rawConfigDir = process.env["CLAUDE_CONFIG_DIR"]; + const configDir = rawConfigDir?.trim() ? rawConfigDir : undefined; + const dir = configDir ? normalize(configDir) : join(homedir(), ".claude"); + return { + rawConfigDir, + configDir, + dir, + mcp: configDir ? join(dir, ".claude.json") : join(homedir(), ".claude.json"), + settings: join(dir, "settings.json"), + }; +} type ClaudeMcpEntry = typeof AGENTMEMORY_MCP_BLOCK; type ClaudeConfig = { @@ -45,10 +55,48 @@ export const adapter: ConnectAdapter = { "→ Using MCP. Hooks are also available — see https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it.", detect(): boolean { - return existsSync(CLAUDE_DIR); + const { configDir, dir } = claudeConfigPaths(); + let detected: boolean; + try { + detected = statSync(dir, { throwIfNoEntry: false })?.isDirectory() ?? false; + } catch (err) { + const code = (err as NodeJS.ErrnoException).code; + if (code !== "EACCES" && code !== "EPERM") throw err; + p.log.warn( + `Cannot inspect Claude Code configuration directory ${JSON.stringify(dir)} (${code}). Check directory permissions and retry.`, + ); + return false; + } + if (!detected && configDir) { + p.log.warn( + `Claude Code configuration path ${JSON.stringify(configDir)} is not an existing directory. Create it or correct CLAUDE_CONFIG_DIR; check for unintended leading or trailing whitespace.`, + ); + } + return detected; }, async install(opts: ConnectOptions): Promise { + const { rawConfigDir, configDir, dir: CLAUDE_DIR, mcp: CLAUDE_JSON } = claudeConfigPaths(); + const fromEnvFile = isEnvFileValue("CLAUDE_CONFIG_DIR"); + if (configDir && fromEnvFile) { + p.log.warn( + `CLAUDE_CONFIG_DIR was loaded only from agentmemory's env file. Launch Claude Code with the same CLAUDE_CONFIG_DIR value ${JSON.stringify(configDir)} so it reads the same MCP and hook configuration.`, + ); + } else if (rawConfigDir && !configDir && !fromEnvFile) { + p.log.warn( + "CLAUDE_CONFIG_DIR contains only whitespace. AgentMemory will use the default Claude Code profile. Unset CLAUDE_CONFIG_DIR before launching Claude Code so it uses the same profile.", + ); + } + if (configDir && configDir !== configDir.trim()) { + p.log.warn( + `CLAUDE_CONFIG_DIR contains leading or trailing whitespace. Using the path exactly as provided: ${JSON.stringify(configDir)}. If this is unintended, correct CLAUDE_CONFIG_DIR and rerun this command.`, + ); + } + if (configDir && !isAbsolute(configDir)) { + p.log.warn( + `CLAUDE_CONFIG_DIR is relative and resolves to ${JSON.stringify(resolve(configDir))} from this working directory. Set the same absolute path for agentmemory and Claude Code so they use the same profile.`, + ); + } const existing = readJsonSafe(CLAUDE_JSON); const next: ClaudeConfig = existing ? { ...existing } : {}; const servers: Record = { @@ -116,6 +164,7 @@ export const adapter: ConnectAdapter = { }; function installClaudeHooks(opts: ConnectOptions): ConnectResult { + const { dir: CLAUDE_DIR, settings: CLAUDE_SETTINGS } = claudeConfigPaths(); let pluginRoot: string; try { pluginRoot = findPluginRoot(); diff --git a/src/cli/doctor-diagnostics.ts b/src/cli/doctor-diagnostics.ts index 8cc84f7845..b7bea3868f 100644 --- a/src/cli/doctor-diagnostics.ts +++ b/src/cli/doctor-diagnostics.ts @@ -16,7 +16,14 @@ // agentmemory doctor --all # apply every available fix without prompting (CI) // agentmemory doctor --dry-run # show what each fix WOULD do; execute nothing -import { detectLlmProviderKind, embeddingOptInHint, LLM_PROVIDER_KEYS, llmOptInHint, parseEnvContent } from "../config.js"; +import { + detectLlmProviderKind, + embeddingOptInHint, + isRealProviderKey, + LLM_PROVIDER_KEYS, + llmOptInHint, + parseEnvContent, +} from "../config.js"; export type DiagnosticStatus = { ok: boolean; @@ -91,17 +98,6 @@ export type DiagnosticId = (typeof DIAGNOSTIC_IDS)[number]; // Pure helpers (no I/O) — exported for direct unit testing. // --------------------------------------------------------------------------- -/** Common placeholder values shipped in .env.example. */ -const PLACEHOLDER_VALUES = new Set([ - "", - "your-key-here", - "sk-ant-...", - "sk-...", - "changeme", - "todo", - "xxx", -]); - const PROVIDER_KEY_NAMES = [ "ANTHROPIC_API_KEY", "OPENAI_API_KEY", @@ -115,25 +111,12 @@ export const parseEnvFile = parseEnvContent; /** Returns the list of provider keys that look real (non-placeholder). */ export function realProviderKeys(env: Record): string[] { - return PROVIDER_KEY_NAMES.filter((k) => { - const v = (env[k] ?? "").trim(); - if (!v) return false; - if (PLACEHOLDER_VALUES.has(v.toLowerCase())) return false; - // Reject values that are just dots/placeholders like "xxxx-xxxx". - if (/^x+$/i.test(v.replace(/[-_]/g, ""))) return false; - return true; - }); + return PROVIDER_KEY_NAMES.filter((k) => isRealProviderKey(env, k)); } /** Returns the list of provider key NAMES that exist but are placeholders. */ export function placeholderProviderKeys(env: Record): string[] { - return PROVIDER_KEY_NAMES.filter((k) => { - const v = (env[k] ?? "").trim(); - if (!v) return false; - if (PLACEHOLDER_VALUES.has(v.toLowerCase())) return true; - if (/^x+$/i.test(v.replace(/[-_]/g, ""))) return true; - return false; - }); + return PROVIDER_KEY_NAMES.filter((k) => (env[k] ?? "").trim() !== "" && !isRealProviderKey(env, k)); } /** @@ -210,7 +193,6 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { for (const [k, v] of Object.entries(effects.processEnv())) { if (v !== undefined) env[k] = v; } - for (const k of placeholderProviderKeys(env)) delete env[k]; if (detectLlmProviderKind(env) !== "llm") { const hint = llmOptInHint(env); if (hint) return { ok: false, detail: hint }; diff --git a/src/config.ts b/src/config.ts index 53823f19c7..d0653bea67 100644 --- a/src/config.ts +++ b/src/config.ts @@ -41,6 +41,7 @@ function writeProviderNoticeOnce(text: string): void { // mutate the file between cases reset the module (clearing this via reload) or // call __resetEnvFileCache(). let envFileCache: Record | undefined; +const hydratedEnvValues = new Map(); function loadEnvFile(): Record { if (envFileCache) return envFileCache; @@ -86,6 +87,31 @@ function hasRealValue(v: string | undefined): v is string { return typeof v === "string" && v.trim().length > 0; } +const PLACEHOLDER_KEY_VALUES = new Set(["your-key-here", "changeme", "todo"]); + +function hasRealKey(value: string | undefined): boolean { + const v = value?.trim().toLowerCase(); + return ( + !!v && + !v.endsWith("...") && + !PLACEHOLDER_KEY_VALUES.has(v) && + !/^x+$/.test(v.replace(/[-_]/g, "")) + ); +} + +function hasRealOpenAIKey(env: Record): boolean { + return /^http:\/\//i.test(env["OPENAI_BASE_URL"]?.trim() ?? "") + ? !!env["OPENAI_API_KEY"]?.trim() + : hasRealKey(env["OPENAI_API_KEY"]); +} + +export function isRealProviderKey( + env: Record, + key: string, +): boolean { + return key === "OPENAI_API_KEY" ? hasRealOpenAIKey(env) : hasRealKey(env[key]); +} + // Hydrate ~/.agentmemory/.env into process.env at boot. loadEnvFile() is // otherwise only consumed via getMergedEnv(), which the many modules that // read raw process.env["X"] never call — so .env-only values were silently @@ -95,11 +121,19 @@ function hasRealValue(v: string | undefined): v is string { export function hydrateProcessEnvFromFile(): Record { const beforeHydration = { ...process.env }; for (const [k, v] of Object.entries(loadEnvFile())) { - if (process.env[k] === undefined) process.env[k] = v; + if (process.env[k] === undefined) { + process.env[k] = v; + hydratedEnvValues.set(k, v); + } } return beforeHydration; } +export function isEnvFileValue(key: string): boolean { + const hydrated = hydratedEnvValues.get(key); + return hydrated !== undefined && process.env[key] === hydrated; +} + // Warn once when a configured model is in the premium tier and likely to burn // money on background compression. Captured workload data shows ~$5/35h on // claude-sonnet-4 vs ~$0.46/35h on deepseek-v4-pro for the same compression @@ -152,7 +186,7 @@ function selectedLlmProviderValue(env: Record): stri } function llmProviderHasKey(env: Record, name: LlmProviderName): boolean { - return LLM_PROVIDER_KEYS[name].some((k) => hasRealValue(env[k])); + return LLM_PROVIDER_KEYS[name].some((k) => isRealProviderKey(env, k)); } export function envFileLabel(path: string = ENV_FILE): string { @@ -174,7 +208,7 @@ export function llmOptInHint(env: Record = getMerged if (env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return null; const withKey = LLM_PROVIDER_NAMES.filter((name) => llmProviderHasKey(env, name)); if (withKey.length === 0) return null; - const keys = withKey.flatMap((name) => LLM_PROVIDER_KEYS[name].filter((k) => hasRealValue(env[k]))); + const keys = withKey.flatMap((name) => LLM_PROVIDER_KEYS[name].filter((k) => isRealProviderKey(env, k))); return `Found ${keys.join(", ")}, but agentmemory sends nothing to an LLM provider until you choose one for it. To turn on LLM summaries and compression, add AGENTMEMORY_LLM_PROVIDER=${withKey[0]} to ${envFileLabel()}.`; } @@ -220,7 +254,7 @@ function detectProvider(env: Record): ProviderConfig { baseURL: env["ANTHROPIC_BASE_URL"], }; case "gemini": - if (!hasRealValue(env["GEMINI_API_KEY"])) { + if (!hasRealKey(env["GEMINI_API_KEY"])) { process.stderr.write( "[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. " + "Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n", @@ -317,6 +351,11 @@ export function getEnvVar(key: string): string | undefined { return getMergedEnv()[key]; } +export function getProviderKey(key: string): string | undefined { + const env = getMergedEnv(); + return isRealProviderKey(env, key) ? env[key] : undefined; +} + export function isSessionSweepEnabled(): boolean { return getMergedEnv()["AGENTMEMORY_SESSION_SWEEP_ENABLED"] !== "false"; } diff --git a/src/hooks/_capture-filter.ts b/src/hooks/_capture-filter.ts index 762f52420e..29c3df7fa1 100644 --- a/src/hooks/_capture-filter.ts +++ b/src/hooks/_capture-filter.ts @@ -1,3 +1,5 @@ +import { scrubRecord, stripPrivateData, stripSecrets } from "../functions/privacy.js"; + const DEFAULT_DENY_PATTERNS = [ "memory_*", "toolsearch", @@ -60,27 +62,79 @@ export function captureOutputMax(): number { return Number.isFinite(parsed) && parsed > 0 ? parsed : 8000; } -export function truncateText(value: string, max: number): string { +function cut(value: string, max: number): string { if (value.length <= max) return value; const end = /[\uD800-\uDBFF]/.test(value[max - 1] ?? "") ? max - 1 : max; return value.slice(0, end); } +export function truncateText(value: string, max: number): string { + if (value.length <= max) return value; + return cut(stripPrivateData(value), max); +} + +const JSON_WHITESPACE_ESCAPES: Record = { n: "\n", r: "\r", t: "\t" }; + +const SECRET_KEY_SUFFIXES = ["apikey", "secret", "token", "password", "passwd", "credential", "credentials"]; +const SECRET_KEY_WORDS = new Set(["auth", "authorization"]); + +function isSecretKeyName(key: string): boolean { + if (!/^[\w.-]{1,64}$/.test(key)) return false; + const words = key + .replace(/([a-z])([A-Z])/g, "$1_$2") + .replace(/([A-Za-z])(\d)/g, "$1_$2") + .toLowerCase() + .split(/[_.\-\d]+/) + .filter(Boolean); + return words.some( + (word, i) => + SECRET_KEY_WORDS.has(word) || + SECRET_KEY_SUFFIXES.some((suffix) => word.endsWith(suffix)) || + (word === "api" && words[i + 1] === "key"), + ); +} + +function redactSecretKeys(value: unknown): unknown { + if (Array.isArray(value)) return value.map(redactSecretKeys); + if (value === null || typeof value !== "object") return value; + const proto = Object.getPrototypeOf(value); + if (proto !== Object.prototype && proto !== null) return value; + return Object.fromEntries( + Object.entries(value as Record).map(([key, item]) => [ + key, + typeof item === "string" && item && isSecretKeyName(key) ? "[REDACTED_SECRET]" : redactSecretKeys(item), + ]), + ); +} + +function scrubSecrets(value: unknown): unknown { + return scrubRecord(redactSecretKeys(value), { scrubKeys: true, strip: stripSecrets }); +} + +function redactSerialized(serialized: string): string { + const unescaped = serialized.replace(/\\([\\nrt])/g, (escape, c: string) => JSON_WHITESPACE_ESCAPES[c] ?? escape); + return stripPrivateData(unescaped).replace(/[\n\r\t]/g, (c) => JSON.stringify(c).slice(1, -1)); +} + +export function truncateJson(value: unknown, max: number): string { + const str = JSON.stringify(value); + if (str.length <= max) return str; + return cut(redactSerialized(JSON.stringify(scrubSecrets(value))), max); +} + +function truncateWithSuffix(value: string, max: number, suffix: string): string { + const safe = stripPrivateData(value); + if (safe.length <= max) return safe; + return max <= suffix.length ? suffix.slice(0, max) : cut(safe, max - suffix.length) + suffix; +} + export function truncateCaptureOutput(value: unknown, max: number): unknown { if (typeof value === "string" && value.length > max) { - const suffix = "\n[...truncated]"; - return max <= suffix.length - ? suffix.slice(0, max) - : truncateText(value, max - suffix.length) + suffix; + return truncateWithSuffix(value, max, "\n[...truncated]"); } if (typeof value === "object" && value !== null) { const str = JSON.stringify(value); - if (str.length > max) { - const suffix = "...[truncated]"; - return max <= suffix.length - ? suffix.slice(0, max) - : truncateText(str, max - suffix.length) + suffix; - } + if (str.length > max) return truncateWithSuffix(redactSerialized(JSON.stringify(scrubSecrets(value))), max, "...[truncated]"); return value; } return value; diff --git a/src/hooks/session-end.ts b/src/hooks/session-end.ts index d5e682f91e..27632e1533 100644 --- a/src/hooks/session-end.ts +++ b/src/hooks/session-end.ts @@ -1,4 +1,5 @@ #!/usr/bin/env node +import { spawn } from "node:child_process"; import { readFileSync } from "node:fs"; import { truncateText } from "./_capture-filter.js"; import { resolveProject, hookCwd } from "./_project.js"; @@ -91,6 +92,32 @@ function extractTranscriptPrompts(data: Record): TranscriptProm return prompts; } +const WORKER_ENV = "AGENTMEMORY_SESSION_END_WORKER"; + +function handOff(input: string): Promise { + if (process.env[WORKER_ENV] === "1" || !process.argv[1]) return Promise.resolve(false); + return new Promise((resolve) => { + try { + const child = spawn(process.execPath, [process.argv[1]], { + detached: true, + stdio: ["pipe", "ignore", "ignore"], + windowsHide: true, + env: { ...process.env, [WORKER_ENV]: "1" }, + }); + child.on("error", () => resolve(false)); + child.stdin.on("error", () => resolve(false)); + child.once("spawn", () => { + child.stdin.end(input, () => { + child.unref(); + resolve(true); + }); + }); + } catch { + resolve(false); + } + }); +} + async function main() { if (isDrainChild()) return runDrainChild(); let input = ""; @@ -107,6 +134,7 @@ async function main() { if (!data || typeof data !== "object") return; if (isSdkChildContext(data)) return; + if (data.hook_event_name === "SessionEnd" && (await handOff(input))) return; const sessionId = ((data.session_id || data.sessionId || data.conversation_id) as string) || "unknown"; diff --git a/src/mcp/plugin-bridge.ts b/src/mcp/plugin-bridge.ts index 1ec1c56f36..593e6f9e2a 100644 --- a/src/mcp/plugin-bridge.ts +++ b/src/mcp/plugin-bridge.ts @@ -2,7 +2,7 @@ import { pathToFileURL } from "node:url"; import { realpathSync } from "node:fs"; import { VERSION } from "../version.js"; import { resolveSettingSecret } from "../hooks/_endpoint.js"; -import { resolveEnvOrEmpty } from "./rest-proxy.js"; +import { callTimeoutMs, resolveEnvOrEmpty } from "./rest-proxy.js"; import { createStdioTransport, JsonRpcError, type RequestHandler } from "./transport.js"; const PROTOCOLS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"]; @@ -37,7 +37,7 @@ export function createPluginBridge(): RequestHandler { }, body: body === undefined ? undefined : JSON.stringify(body), redirect: "error", - signal: AbortSignal.timeout(15_000), + signal: AbortSignal.timeout(callTimeoutMs()), }); } catch { throw new Error(`Agent Memory daemon is unreachable or timed out. ${SETUP} No fallback store was used; check state before retrying a write.`); diff --git a/src/mcp/rest-proxy.ts b/src/mcp/rest-proxy.ts index 9fcf752778..b2b343afb0 100644 --- a/src/mcp/rest-proxy.ts +++ b/src/mcp/rest-proxy.ts @@ -1,7 +1,9 @@ import { hookSetting, resolveSettingSecret } from "../hooks/_endpoint.js"; +import { readEnvFileValue } from "../secret-store.js"; const DEFAULT_URL = "http://localhost:3111"; const DEFAULT_HEALTH_PROBE_TIMEOUT_MS = 2_000; -const CALL_TIMEOUT_MS = 15_000; +const DEFAULT_CALL_TIMEOUT_MS = 190_000; +const MAX_TIMER_MS = 2_147_483_647; const LOCAL_MODE_TTL_MS = 30_000; function probeTimeoutMs(): number { @@ -11,6 +13,13 @@ function probeTimeoutMs(): number { return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_HEALTH_PROBE_TIMEOUT_MS; } +export function callTimeoutMs(): number { + const name = "AGENTMEMORY_CALL_TIMEOUT_MS"; + const raw = (resolveEnvOrEmpty(name) || readEnvFileValue(name)).trim(); + const n = /^\d+$/.test(raw) ? Number(raw) : 0; + return n >= 1 && n <= MAX_TIMER_MS ? n : DEFAULT_CALL_TIMEOUT_MS; +} + export function isProxyRequired(): boolean { const raw = process.env["AGENTMEMORY_FORCE_PROXY"]; return raw === "1" || raw === "true"; @@ -164,7 +173,7 @@ export async function resolveHandle(): Promise { ...authHeader(url), ...(init?.headers as Record | undefined), }, - signal: AbortSignal.timeout(CALL_TIMEOUT_MS), + signal: AbortSignal.timeout(callTimeoutMs()), redirect: "error", }); if (!res.ok) { diff --git a/src/providers/circuit-breaker.ts b/src/providers/circuit-breaker.ts index bcb27e416f..0bce44dab7 100644 --- a/src/providers/circuit-breaker.ts +++ b/src/providers/circuit-breaker.ts @@ -45,12 +45,11 @@ export class CircuitBreaker { } recordSuccess(): void { - if (this.state === "half-open") { - this.state = "closed"; - this.failures = 0; - this.lastFailureAt = null; - this.openedAt = null; - } + if (this.state === "open") return; + this.state = "closed"; + this.failures = 0; + this.lastFailureAt = null; + this.openedAt = null; } recordFailure(): void { diff --git a/src/providers/embedding/clip.ts b/src/providers/embedding/clip.ts index 4ee102bce2..984c4995a1 100644 --- a/src/providers/embedding/clip.ts +++ b/src/providers/embedding/clip.ts @@ -7,13 +7,14 @@ type ClipPipeline = ( input: string[] | RawImage | RawImage[], options?: { pooling?: string; normalize?: boolean }, ) => Promise<{ tolist: () => number[][]; data: Float32Array }>; +type ClipTextEncoder = (texts: string[]) => Promise; const DEFAULT_MODEL = "Xenova/clip-vit-base-patch32"; export class ClipEmbeddingProvider implements EmbeddingProvider { readonly name = "clip"; readonly dimensions = 512; - private textExtractor: ClipPipeline | null = null; + private textExtractor: ClipTextEncoder | null = null; private imageExtractor: ClipPipeline | null = null; private readonly modelId: string; @@ -27,9 +28,8 @@ export class ClipEmbeddingProvider implements EmbeddingProvider { } async embedBatch(texts: string[]): Promise { - const extractor = await this.getTextExtractor(); - const output = await extractor(texts, { pooling: "mean", normalize: true }); - return output.tolist().map((v) => new Float32Array(v)); + const encode = await this.getTextExtractor(); + return encode(texts); } async embedImage(src: string): Promise { @@ -41,10 +41,18 @@ export class ClipEmbeddingProvider implements EmbeddingProvider { return normalize(vec); } - private async getTextExtractor(): Promise { + private async getTextExtractor(): Promise { if (this.textExtractor) return this.textExtractor; const t = await loadTransformers(); - this.textExtractor = (await t.pipeline("feature-extraction", this.modelId, { dtype: "q8" })) as ClipPipeline; + const tokenizer = await t.AutoTokenizer.from_pretrained(this.modelId); + const model = await t.CLIPTextModelWithProjection.from_pretrained(this.modelId, { + dtype: "q8", + }); + this.textExtractor = async (texts: string[]) => { + const inputs = tokenizer(texts, { padding: true, truncation: true }); + const { text_embeds } = await model(inputs); + return text_embeds.tolist().map((v: number[]) => normalize(new Float32Array(v))); + }; return this.textExtractor; } diff --git a/src/providers/index.ts b/src/providers/index.ts index 4245e03ad1..a2c71ccbd0 100644 --- a/src/providers/index.ts +++ b/src/providers/index.ts @@ -11,12 +11,12 @@ import { OpenAIProvider } from "./openai.js"; import { OpenRouterProvider } from "./openrouter.js"; import { ResilientProvider } from "./resilient.js"; import { FallbackChainProvider } from "./fallback-chain.js"; -import { getEnvVar } from "../config.js"; +import { getEnvVar, getProviderKey } from "../config.js"; export { createEmbeddingProvider, createImageEmbeddingProvider } from "./embedding/index.js"; function requireEnvVar(key: string): string { - const value = getEnvVar(key); + const value = getProviderKey(key); if (!value) { throw new Error( `Missing required environment variable: ${key}. Set it in ~/.agentmemory/.env or as an environment variable.`, @@ -95,7 +95,7 @@ function createBaseProvider(config: ProviderConfig): MemoryProvider { ); case "gemini": { const geminiKey = - getEnvVar("GEMINI_API_KEY") || getEnvVar("GOOGLE_API_KEY"); + getProviderKey("GEMINI_API_KEY") || getProviderKey("GOOGLE_API_KEY"); if (!geminiKey) { throw new Error( "GEMINI_API_KEY (or GOOGLE_API_KEY) is required for the gemini provider", @@ -116,7 +116,7 @@ function createBaseProvider(config: ProviderConfig): MemoryProvider { "https://openrouter.ai/api/v1/chat/completions", ); case "openai": { - const openaiKey = getEnvVar("OPENAI_API_KEY"); + const openaiKey = getProviderKey("OPENAI_API_KEY"); if (!openaiKey) { throw new Error( "OPENAI_API_KEY is required for the openai provider", diff --git a/src/providers/resilient.ts b/src/providers/resilient.ts index 95ece40c96..f82e578d72 100644 --- a/src/providers/resilient.ts +++ b/src/providers/resilient.ts @@ -1,6 +1,14 @@ import type { MemoryProvider, CircuitBreakerState } from "../types.js"; import { CircuitBreaker } from "./circuit-breaker.js"; +const FILTER_CODE = /content_filter|ResponsibleAIPolicyViolation/; +const REJECTED_STATUS = /^[^{]*\(400\)/; + +export function isPayloadRejection(err: unknown): boolean { + const message = err instanceof Error ? err.message : String(err); + return REJECTED_STATUS.test(message) && FILTER_CODE.test(message); +} + export class ResilientProvider implements MemoryProvider { private breaker = new CircuitBreaker(); name: string; @@ -18,7 +26,9 @@ export class ResilientProvider implements MemoryProvider { this.breaker.recordSuccess(); return result; } catch (err) { - this.breaker.recordFailure(); + if (!isPayloadRejection(err)) { + this.breaker.recordFailure(); + } throw err; } } diff --git a/src/secret-store.ts b/src/secret-store.ts index 12dc2d9df2..915bb0b0c7 100644 --- a/src/secret-store.ts +++ b/src/secret-store.ts @@ -41,7 +41,7 @@ function unquote(value: string): string { return hash === -1 ? value : value.slice(0, hash).trim(); } -export function readEnvFileSecret(): string { +export function readEnvFileValue(name: string): string { let content: unknown; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -56,12 +56,16 @@ export function readEnvFileSecret(): string { const eq = trimmed.indexOf("="); if (eq === -1) continue; const key = trimmed.slice(0, eq).replace(/^export\s+/, "").trim(); - if (key !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (key !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +export function readEnvFileSecret(): string { + return usable(readEnvFileValue(SECRET_KEY)); +} + function readSecretFile(path: string): string { try { return usable(readFileSync(path, "utf-8")); diff --git a/src/state/hybrid-search.ts b/src/state/hybrid-search.ts index caeb8f03b8..2c7eb4e2ad 100644 --- a/src/state/hybrid-search.ts +++ b/src/state/hybrid-search.ts @@ -23,6 +23,7 @@ import { logger } from "../logger.js"; const RRF_K = 60; const GRAPH_BUDGET_MS = 500; +const MIN_FUSION_POOL = 40; export interface HybridSearchRequest { embedding?: { query: string; value: Promise }; @@ -103,7 +104,8 @@ export class HybridSearch { request?: HybridSearchRequest, ): Promise { const retrievalLimit = this.rerankEnabled ? Math.max(limit, 20) : limit; - const bm25Results = this.bm25.search(query, retrievalLimit * 2, targetLayer); + const poolLimit = Math.max(retrievalLimit * 2, MIN_FUSION_POOL); + const bm25Results = this.bm25.search(query, poolLimit, targetLayer); let vectorResults: Array<{ obsId: string; @@ -128,7 +130,7 @@ export class HybridSearch { } else { queryEmbedding = await this.embeddingProvider.embed(query); } - vectorResults = this.vector.search(queryEmbedding, retrievalLimit * 2, targetLayer, (id) => this.bm25.layerOf(id)); + vectorResults = this.vector.search(queryEmbedding, poolLimit, targetLayer, (id) => this.bm25.layerOf(id)); } catch { // fall through to BM25-only } @@ -255,7 +257,7 @@ export class HybridSearch { if (request) request.candidateCount = combined.length; const retrievalDepth = Math.max(limit, 20); - const diversified = this.diversifyBySession(combined, retrievalDepth); + const diversified = this.diversifyBySession(combined, combined.length); const enriched = await this.enrichResults(diversified, retrievalDepth); return applyReranking ? this.rerankResults(query, enriched, limit) : enriched.slice(0, limit); @@ -327,6 +329,11 @@ export class HybridSearch { const sessionCounts = new Map(); for (const r of results) { + if (r.obsId.startsWith("mem_")) { + selected.push(r); + if (selected.length >= limit) break; + continue; + } const count = sessionCounts.get(r.sessionId) || 0; if (count >= maxPerSession) continue; selected.push(r); @@ -335,9 +342,10 @@ export class HybridSearch { } if (selected.length < limit) { + const picked = new Set(selected.map((s) => s.obsId)); for (const r of results) { if (selected.length >= limit) break; - if (!selected.some(s => s.obsId === r.obsId)) { + if (!picked.has(r.obsId)) { selected.push(r); } } @@ -358,7 +366,27 @@ export class HybridSearch { }>, limit: number, ): Promise { - const sliced = results.slice(0, limit); + const enriched: HybridSearchResult[] = []; + let next = 0; + while (next < results.length && enriched.length < limit) { + const batch = results.slice(next, next + limit); + next += batch.length; + enriched.push(...(await this.enrichBatch(batch))); + } + return enriched.slice(0, limit); + } + + private async enrichBatch( + sliced: Array<{ + obsId: string; + sessionId: string; + bm25Score: number; + vectorScore: number; + graphScore: number; + combinedScore: number; + graphContext?: string; + }>, + ): Promise { const observations = await Promise.all( sliced.map(async (r) => { const obs = await this.kv diff --git a/test/capture-filter.test.ts b/test/capture-filter.test.ts index 0d576103b7..a75f5292e6 100644 --- a/test/capture-filter.test.ts +++ b/test/capture-filter.test.ts @@ -5,6 +5,7 @@ import { preCompactBudget, shouldCaptureTool, truncateCaptureOutput, + truncateJson, truncateText, } from "../src/hooks/_capture-filter.js"; @@ -116,6 +117,104 @@ describe("truncateText", () => { }); }); +describe("truncation redacts before cutting", () => { + const token = "ghp_" + "A".repeat(40); + + it("truncateText leaves text within the limit unchanged", () => { + expect(truncateText(`short ${token}`, 100)).toBe(`short ${token}`); + }); + + it("truncateText does not keep the start of a token the cut lands in", () => { + const out = truncateText("x".repeat(10) + " " + token + " tail", 20); + expect(out).not.toContain("ghp_"); + expect(out.length).toBeLessThanOrEqual(20); + }); + + it("truncateCaptureOutput redacts strings and JSON before cutting", () => { + const str = truncateCaptureOutput("x".repeat(10) + " " + token + "y".repeat(100), 40) as string; + expect(str).not.toContain("ghp_"); + expect(str.length).toBeLessThanOrEqual(40); + const json = truncateCaptureOutput({ out: "x".repeat(10) + " " + token + "y".repeat(100) }, 40) as string; + expect(json).not.toContain("ghp_"); + expect(json.length).toBeLessThanOrEqual(40); + }); +}); + +describe("truncateCaptureOutput redacts structured values before serializing", () => { + it("redacts values under secret-like keys in both helpers", () => { + const value = { password: "A".repeat(100), nested: { apiKey: "K".repeat(40) }, note: "kept" }; + for (const out of [truncateJson(value, 90), truncateCaptureOutput(value, 90) as string]) { + expect(out).not.toContain("AAAA"); + expect(out).not.toContain("KKKK"); + expect(out).toContain("[REDACTED_SECRET]"); + } + }); + + it("keeps values whose key only contains a secret word inside another word", () => { + const value = { tokenization: "words", secretary: "office", access_token: "T".repeat(40), accesstoken: "U".repeat(40), apiKey2: "V".repeat(40), pad: "y".repeat(200) }; + const out = truncateJson(value, 200); + expect(out).toContain("words"); + expect(out).toContain("office"); + expect(out).not.toContain("TTTT"); + expect(out).not.toContain("UUUU"); + expect(out).not.toContain("VVVV"); + }); + + it("leaves a short value with a secret-like key unchanged", () => { + const value = { password: "short" }; + expect(truncateJson(value, 100)).toBe(JSON.stringify(value)); + expect(truncateCaptureOutput(value, 100)).toBe(value); + }); + + it("removes a private block whose tag spans a line break", () => { + const out = truncateCaptureOutput({ log: "hidden-value" + "y".repeat(200) }, 60) as string; + expect(out).not.toContain("hidden"); + }); + + it("removes a private block that opens in one field and closes in the next", () => { + const value = { a: "start ", b: "hidden-value end", pad: "y".repeat(200) }; + expect(truncateCaptureOutput(value, 80) as string).not.toContain("hidden"); + expect(truncateJson(value, 80)).not.toContain("hidden"); + }); + + it("redacts a credential in a key that a line break separates from its scheme", () => { + const key = "Bearer\n" + "A".repeat(32); + const value = { [key]: "x", pad: "y".repeat(200) }; + expect(truncateJson(value, 100)).not.toContain("A".repeat(32)); + expect(truncateCaptureOutput(value, 100) as string).not.toContain("A".repeat(32)); + }); + + it("redacts a quoted credential whose quote JSON escapes", () => { + const value = { cmd: 'secret="' + "B".repeat(32) + '"', pad: "y".repeat(200) }; + expect(truncateJson(value, 100)).not.toContain("B".repeat(20)); + expect(truncateCaptureOutput(value, 100) as string).not.toContain("B".repeat(20)); + }); + + it("redacts a credential that a vertical tab separates from its scheme", () => { + const value = { header: "Bearer\u000b" + "C".repeat(32), pad: "y".repeat(200) }; + expect(truncateJson(value, 100)).not.toContain("C".repeat(20)); + }); + + it("keeps every field when two keys redact to the same text", () => { + const value = { ["token=" + "A".repeat(24)]: "first", ["token=" + "B".repeat(24)]: "second", pad: "y".repeat(200) }; + const out = truncateJson(value, 150); + expect(out).toContain("first"); + expect(out).toContain("second"); + }); + + it("keeps escaped backslashes and line breaks in the cut JSON", () => { + const out = truncateJson({ a: "one\ntwo\\nthree", pad: "y".repeat(200) }, 60); + expect(out.startsWith('{"a":"one\\ntwo\\\\nthree"')).toBe(true); + }); + + it("truncateJson leaves short JSON unchanged and redacts long JSON before cutting", () => { + expect(truncateJson({ a: 1 }, 100)).toBe('{"a":1}'); + const out = truncateJson({ log: "hidden-value" + "y".repeat(200) }, 60); + expect(out).not.toContain("hidden"); + expect(out.length).toBeLessThanOrEqual(60); + }); +}); + describe("truncateCaptureOutput", () => { it("leaves short strings alone", () => { expect(truncateCaptureOutput("hello", 20)).toBe("hello"); diff --git a/test/circuit-breaker.test.ts b/test/circuit-breaker.test.ts index be7489d9b7..52cd6d0e76 100644 --- a/test/circuit-breaker.test.ts +++ b/test/circuit-breaker.test.ts @@ -127,4 +127,65 @@ describe("CircuitBreaker", () => { expect(cb.getState().state).toBe("closed"); expect(cb.getState().failures).toBe(0); }); + + it("a success in closed state clears the accumulated failure count", () => { + const cb = new CircuitBreaker(); + cb.recordFailure(); + cb.recordFailure(); + expect(cb.getState().failures).toBe(2); + cb.recordSuccess(); + expect(cb.getState().failures).toBe(0); + expect(cb.getState().lastFailureAt).toBeNull(); + }); + + it("stays closed across 100 calls at a 5% failure rate", () => { + const cb = new CircuitBreaker(); + for (let i = 0; i < 100; i++) { + if (i % 20 === 0) cb.recordFailure(); + else cb.recordSuccess(); + vi.advanceTimersByTime(1_000); + expect(cb.getState().state).toBe("closed"); + } + expect(cb.isAllowed).toBe(true); + }); + + it("stays closed when failures are interleaved with successes inside the window", () => { + const cb = new CircuitBreaker(); + for (let i = 0; i < 5; i++) { + cb.recordFailure(); + cb.recordSuccess(); + } + expect(cb.getState().state).toBe("closed"); + expect(cb.getState().failures).toBe(0); + }); + + it("keeps openedAt when a success arrives while open", () => { + const cb = new CircuitBreaker(); + cb.recordFailure(); + cb.recordFailure(); + cb.recordFailure(); + expect(cb.getState().state).toBe("open"); + const openedAt = cb.getState().openedAt; + + cb.recordSuccess(); + + expect(cb.getState().state).toBe("open"); + expect(cb.getState().openedAt).toBe(openedAt); + expect(cb.isAllowed).toBe(false); + + vi.advanceTimersByTime(30_000); + expect(cb.isAllowed).toBe(true); + expect(cb.getState().state).toBe("half-open"); + }); + + it("still opens after consecutive failures with no success between them", () => { + const cb = new CircuitBreaker(); + cb.recordSuccess(); + for (let i = 0; i < 3; i++) { + cb.recordFailure(); + vi.advanceTimersByTime(1_000); + } + expect(cb.getState().state).toBe("open"); + expect(cb.isAllowed).toBe(false); + }); }); diff --git a/test/claude-code-with-hooks.test.ts b/test/claude-code-with-hooks.test.ts index e3d35af552..c79acb3cd1 100644 --- a/test/claude-code-with-hooks.test.ts +++ b/test/claude-code-with-hooks.test.ts @@ -1,5 +1,6 @@ import { afterEach, beforeEach, describe, it, expect, vi } from "vitest"; -import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { spawnSync } from "node:child_process"; +import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { @@ -41,6 +42,13 @@ describe("buildMergedHooks against plugin/hooks/hooks.json (Claude Code)", () => ).toBe(true); }); + it("gives SessionEnd more time than Claude Code's 1.5 s default so the transcript back-fill and exit timer can finish", () => { + const merged = buildMergedHooks(null, PLUGIN_ROOT, "hooks.json"); + const handler = merged.hooks["SessionEnd"]![0]!.hooks[0]!; + expect(handler.args![0]).toContain("session-end.mjs"); + expect(handler.timeout).toBeGreaterThanOrEqual(10); + }); + it("appends to existing user hooks without dropping them", () => { const existing: HookManifest = { hooks: { @@ -109,6 +117,7 @@ describe("connect claude-code --with-hooks", () => { home = mkdtempSync(join(tmpdir(), "am-claude-hooks-")); vi.stubEnv("HOME", home); vi.stubEnv("USERPROFILE", home); + vi.stubEnv("CLAUDE_CONFIG_DIR", undefined); vi.resetModules(); }); @@ -138,4 +147,452 @@ describe("connect claude-code --with-hooks", () => { ...buildMergedHooks(null, PLUGIN_ROOT, "hooks.json").hooks["Stop"]!, ]); }); + + it("detects Claude Code in CLAUDE_CONFIG_DIR without a default directory", async () => { + const configDir = join(home, "custom Claude config"); + mkdirSync(configDir); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { adapter } = await import("../src/cli/connect/claude-code.js"); + expect(adapter.detect()).toBe(true); + expect(existsSync(join(home, ".claude"))).toBe(false); + }); + + it.skipIf(process.platform === "win32")("preserves a literal trailing space instead of changing a different profile", async () => { + const configDir = join(home, "custom Claude config "); + const trimmedDir = configDir.trim(); + mkdirSync(configDir); + mkdirSync(trimmedDir); + writeFileSync(join(trimmedDir, ".claude.json"), '{"keep":"trimmed MCP"}'); + writeFileSync(join(trimmedDir, "settings.json"), '{"keep":"trimmed settings"}'); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { adapter } = await import("../src/cli/connect/claude-code.js"); + expect(adapter.detect()).toBe(true); + expect(await adapter.install({ dryRun: false, force: false, withHooks: true })).toMatchObject({ + kind: "installed", + mutatedPath: join(configDir, ".claude.json"), + }); + expect(JSON.parse(readFileSync(join(configDir, "settings.json"), "utf-8")).hooks.SessionStart).toBeDefined(); + expect(readFileSync(join(trimmedDir, ".claude.json"), "utf-8")).toBe('{"keep":"trimmed MCP"}'); + expect(readFileSync(join(trimmedDir, "settings.json"), "utf-8")).toBe('{"keep":"trimmed settings"}'); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + expect(existsSync(join(home, ".claude"))).toBe(false); + }); + + it("skips a custom profile directory that does not exist", async () => { + const configDir = join(home, "missing Claude config"); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { resolveAdapter, runAdapter } = await import("../src/cli/connect/index.js"); + expect(await runAdapter(resolveAdapter("claude-code")!, { + dryRun: false, + force: false, + withHooks: true, + guidelines: false, + })).toEqual({ kind: "skipped", reason: "not-detected" }); + expect(existsSync(configDir)).toBe(false); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + expect(existsSync(join(home, ".claude"))).toBe(false); + }); + + it.each(["custom", "default"])("skips a %s profile path that is a file", async (profile) => { + const configDir = join(home, profile === "custom" ? "Claude config" : ".claude"); + writeFileSync(configDir, "keep this file"); + if (profile === "custom") vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { resolveAdapter, runAdapter } = await import("../src/cli/connect/index.js"); + expect(await runAdapter(resolveAdapter("claude-code")!, { + dryRun: false, + force: false, + withHooks: true, + guidelines: false, + })).toEqual({ kind: "skipped", reason: "not-detected" }); + expect(readFileSync(configDir, "utf-8")).toBe("keep this file"); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + }); + + it("uses a profile override set after the adapter was imported for detection, MCP and hooks", async () => { + const { adapter } = await import("../src/cli/connect/claude-code.js"); + const configDir = join(home, "late Claude config"); + mkdirSync(configDir); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + expect(adapter.detect()).toBe(true); + expect(await adapter.install({ dryRun: false, force: false, withHooks: true })).toMatchObject({ + kind: "installed", + mutatedPath: join(configDir, ".claude.json"), + }); + expect(JSON.parse(readFileSync(join(configDir, "settings.json"), "utf-8")).hooks.SessionStart).toBeDefined(); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + expect(existsSync(join(home, ".claude"))).toBe(false); + }); + + describe.skipIf(process.platform === "win32")("CLI env-file hydration", () => { + it.each([ + { source: "default .env", customEnvFile: false, shellOverride: false, matchingShell: false, padding: "none" }, + { source: "AGENTMEMORY_ENV_FILE", customEnvFile: true, shellOverride: false, matchingShell: false, padding: "none" }, + { source: "shell overriding the env file", customEnvFile: true, shellOverride: true, matchingShell: false, padding: "none" }, + { source: "matching shell and env-file values", customEnvFile: true, shellOverride: true, matchingShell: true, padding: "none" }, + { source: "a literal env-file value with surrounding spaces", customEnvFile: true, shellOverride: false, matchingShell: false, padding: "both" }, + { source: "a literal shell value with leading spaces", customEnvFile: true, shellOverride: true, matchingShell: false, padding: "leading" }, + { source: "a literal shell value with trailing spaces", customEnvFile: true, shellOverride: true, matchingShell: false, padding: "trailing" }, + ])("installs MCP and hooks using $source", ({ customEnvFile, shellOverride, matchingShell, padding }) => { + const fileProfile = join(home, "env-file Claude config"); + const shellProfile = join(home, "shell Claude config"); + const withPadding = (value: string) => + `${padding === "leading" || padding === "both" ? " " : ""}${value}${padding === "trailing" || padding === "both" ? " " : ""}`; + const fileValue = shellOverride ? fileProfile : withPadding(fileProfile); + const selectedValue = shellOverride && !matchingShell ? withPadding(shellProfile) : fileValue; + const selected = resolve(home, selectedValue); + mkdirSync(fileProfile); + mkdirSync(shellProfile); + mkdirSync(selected, { recursive: true }); + mkdirSync(join(home, ".agentmemory")); + const envFile = customEnvFile + ? join(home, "custom.env") + : join(home, ".agentmemory", ".env"); + writeFileSync(envFile, `CLAUDE_CONFIG_DIR="${fileValue}"\n`); + + const result = spawnSync(process.execPath, [ + resolve(__dirname, "..", "dist", "cli.mjs"), + "connect", "claude-code", "--with-hooks", "--no-guidelines", + ], { + cwd: home, + env: { + ...process.env, + AGENTMEMORY_ENV_FILE: customEnvFile ? envFile : undefined, + CLAUDE_CONFIG_DIR: shellOverride ? selectedValue : undefined, + CI: "1", + NO_COLOR: "1", + }, + encoding: "utf-8", + timeout: 10000, + }); + + expect(result.status, result.stderr).toBe(0); + const output = result.stdout + result.stderr; + if (shellOverride) { + expect(output).not.toContain("CLAUDE_CONFIG_DIR was loaded only"); + } else { + expect(output).toContain("CLAUDE_CONFIG_DIR was loaded only from agentmemory's env file."); + expect(output).toContain(`Launch Claude Code with the same CLAUDE_CONFIG_DIR value ${JSON.stringify(selectedValue)}`); + expect(output.match(/CLAUDE_CONFIG_DIR was loaded only/g)).toHaveLength(1); + expect(output.indexOf("CLAUDE_CONFIG_DIR was loaded only")).toBeLessThan(output.indexOf("wired into")); + } + if (padding === "none" || padding === "trailing") { + expect(output).not.toContain("CLAUDE_CONFIG_DIR is relative"); + } + if (padding === "none") { + expect(output).not.toContain("CLAUDE_CONFIG_DIR contains leading or trailing whitespace"); + } else { + expect(output).toContain(`Using the path exactly as provided: ${JSON.stringify(selectedValue)}`); + expect(output).toContain("If this is unintended, correct CLAUDE_CONFIG_DIR and rerun this command."); + expect(output.match(/CLAUDE_CONFIG_DIR contains leading or trailing whitespace/g)).toHaveLength(1); + expect(output.indexOf("CLAUDE_CONFIG_DIR contains leading or trailing whitespace")).toBeLessThan(output.indexOf("wired into")); + } + expect(result.stdout).toContain(`wired into ${join(selectedValue, ".claude.json")}`); + expect(JSON.parse(readFileSync(join(selected, ".claude.json"), "utf-8")).mcpServers.agentmemory).toBeDefined(); + expect(JSON.parse(readFileSync(join(selected, "settings.json"), "utf-8")).hooks.SessionStart).toBeDefined(); + for (const profile of [fileProfile, shellProfile]) { + if (profile !== selected) { + expect(existsSync(join(profile, ".claude.json"))).toBe(false); + expect(existsSync(join(profile, "settings.json"))).toBe(false); + } + } + expect(existsSync(join(home, ".claude.json"))).toBe(false); + expect(existsSync(join(home, ".claude"))).toBe(false); + }, 15000); + + it.each(["env file", "shell"])("keeps legacy paths and warns only for a shell whitespace-only value from the %s", (source) => { + const fileProfile = join(home, "env-file Claude config"); + mkdirSync(fileProfile); + mkdirSync(join(home, ".claude")); + mkdirSync(join(home, ".agentmemory")); + writeFileSync(join(home, ".agentmemory", ".env"), + `CLAUDE_CONFIG_DIR="${source === "env file" ? " \t " : fileProfile}"\n`); + + const result = spawnSync(process.execPath, [ + resolve(__dirname, "..", "dist", "cli.mjs"), + "connect", "claude-code", "--with-hooks", "--no-guidelines", + ], { + cwd: home, + env: { + ...process.env, + AGENTMEMORY_ENV_FILE: undefined, + CLAUDE_CONFIG_DIR: source === "shell" ? " \t " : undefined, + CI: "1", + NO_COLOR: "1", + }, + encoding: "utf-8", + timeout: 10000, + }); + + expect(result.status, result.stderr).toBe(0); + const output = result.stdout + result.stderr; + expect(output).not.toContain("CLAUDE_CONFIG_DIR was loaded only"); + expect(output).not.toContain("CLAUDE_CONFIG_DIR contains leading or trailing whitespace"); + if (source === "shell") { + expect(output).toContain("CLAUDE_CONFIG_DIR contains only whitespace."); + expect(output).toContain("Unset CLAUDE_CONFIG_DIR before launching Claude Code"); + expect(output.match(/CLAUDE_CONFIG_DIR contains only whitespace/g)).toHaveLength(1); + } else { + expect(output).not.toContain("CLAUDE_CONFIG_DIR contains only whitespace."); + } + expect(result.stdout).toContain(`wired into ${join(home, ".claude.json")}`); + expect(JSON.parse(readFileSync(join(home, ".claude.json"), "utf-8")).mcpServers.agentmemory).toBeDefined(); + expect(JSON.parse(readFileSync(join(home, ".claude", "settings.json"), "utf-8")).hooks.SessionStart).toBeDefined(); + expect(existsSync(join(fileProfile, ".claude.json"))).toBe(false); + expect(existsSync(join(fileProfile, "settings.json"))).toBe(false); + }, 15000); + + it.each(["leading", "trailing"])("skips a missing literal profile with %s whitespace even when the trimmed directory exists", (padding) => { + const trimmedDir = join(home, "existing Claude config"); + const configDir = padding === "leading" ? ` ${trimmedDir}` : `${trimmedDir} `; + mkdirSync(trimmedDir); + + const result = spawnSync(process.execPath, [ + resolve(__dirname, "..", "dist", "cli.mjs"), + "connect", "claude-code", "--with-hooks", "--no-guidelines", + ], { + cwd: home, + env: { + ...process.env, + AGENTMEMORY_ENV_FILE: undefined, + CLAUDE_CONFIG_DIR: configDir, + CI: "1", + NO_COLOR: "1", + }, + encoding: "utf-8", + timeout: 10000, + }); + + expect(result.status, result.stderr).toBe(0); + const output = result.stdout + result.stderr; + expect(output).toContain(JSON.stringify(configDir)); + expect(output).toContain("is not an existing directory"); + expect(output).toContain("leading or trailing whitespace"); + expect(output).toContain("not detected on this machine (skipping)"); + expect(output).not.toContain("wired into"); + expect(existsSync(resolve(home, configDir))).toBe(false); + expect(existsSync(join(trimmedDir, ".claude.json"))).toBe(false); + expect(existsSync(join(trimmedDir, "settings.json"))).toBe(false); + }, 15000); + + it("warns before installing into a profile relative to the CLI working directory", () => { + const configDir = "relative Claude config"; + const selected = join(home, configDir); + mkdirSync(selected); + + const result = spawnSync(process.execPath, [ + resolve(__dirname, "..", "dist", "cli.mjs"), + "connect", "claude-code", "--with-hooks", "--no-guidelines", + ], { + cwd: home, + env: { + ...process.env, + AGENTMEMORY_ENV_FILE: undefined, + CLAUDE_CONFIG_DIR: configDir, + CI: "1", + NO_COLOR: "1", + }, + encoding: "utf-8", + timeout: 10000, + }); + + expect(result.status, result.stderr).toBe(0); + const output = result.stdout + result.stderr; + expect(output).toContain(`CLAUDE_CONFIG_DIR is relative and resolves to ${JSON.stringify(realpathSync(selected))}`); + expect(output).toContain("Set the same absolute path for agentmemory and Claude Code"); + expect(output.match(/CLAUDE_CONFIG_DIR is relative/g)).toHaveLength(1); + expect(output.indexOf("CLAUDE_CONFIG_DIR is relative")).toBeLessThan(output.indexOf("wired into")); + expect(JSON.parse(readFileSync(join(selected, ".claude.json"), "utf-8")).mcpServers.agentmemory).toBeDefined(); + expect(JSON.parse(readFileSync(join(selected, "settings.json"), "utf-8")).hooks.SessionStart).toBeDefined(); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + expect(existsSync(join(home, ".claude"))).toBe(false); + }, 15000); + + it.each(["existing", "missing"])("uses the %s normalized profile for a symlink followed by ..", (profile) => { + const alias = join(home, "alias"); + const target = join(home, "target"); + const normalizedProfile = join(alias, "profile"); + const targetProfile = join(target, "profile"); + mkdirSync(alias); + mkdirSync(join(target, "child"), { recursive: true }); + symlinkSync(join(target, "child"), join(alias, "link"), "dir"); + const configDir = `${alias}/link/../profile`; + const existingProfile = profile === "existing" ? normalizedProfile : targetProfile; + mkdirSync(existingProfile); + mkdirSync(join(home, ".claude")); + const original = '{"keep":"original configuration"}'; + for (const path of [ + join(existingProfile, ".claude.json"), + join(existingProfile, "settings.json"), + join(home, ".claude.json"), + join(home, ".claude", "settings.json"), + ]) { + writeFileSync(path, original); + } + + const result = spawnSync(process.execPath, [ + resolve(__dirname, "..", "dist", "cli.mjs"), + "connect", "claude-code", "--with-hooks", "--no-guidelines", + ], { + cwd: home, + env: { + ...process.env, + AGENTMEMORY_ENV_FILE: undefined, + CLAUDE_CONFIG_DIR: configDir, + CI: "1", + NO_COLOR: "1", + }, + encoding: "utf-8", + timeout: 10000, + }); + + expect(result.status, result.stderr).toBe(0); + const output = result.stdout + result.stderr; + if (profile === "existing") { + expect(output).toContain(`wired into ${join(normalizedProfile, ".claude.json")}`); + const config = JSON.parse(readFileSync(join(normalizedProfile, ".claude.json"), "utf-8")); + const settings = JSON.parse(readFileSync(join(normalizedProfile, "settings.json"), "utf-8")); + expect(config.mcpServers.agentmemory).toBeDefined(); + expect(settings.hooks.SessionStart).toBeDefined(); + expect(config.keep).toBe("original configuration"); + expect(settings.keep).toBe("original configuration"); + expect(existsSync(targetProfile)).toBe(false); + } else { + expect(output).toContain("not detected on this machine (skipping)"); + expect(output).not.toContain("wired into"); + expect(existsSync(normalizedProfile)).toBe(false); + expect(readFileSync(join(targetProfile, ".claude.json"), "utf-8")).toBe(original); + expect(readFileSync(join(targetProfile, "settings.json"), "utf-8")).toBe(original); + } + expect(readFileSync(join(home, ".claude.json"), "utf-8")).toBe(original); + expect(readFileSync(join(home, ".claude", "settings.json"), "utf-8")).toBe(original); + }, 15000); + + it.skipIf(process.getuid?.() === 0)("warns and skips an inaccessible profile without changing either profile", () => { + const parent = join(home, "inaccessible"); + const configDir = join(parent, "Claude config"); + const configPath = join(configDir, ".claude.json"); + const settingsPath = join(configDir, "settings.json"); + const defaultConfig = join(home, ".claude.json"); + const defaultSettings = join(home, ".claude", "settings.json"); + mkdirSync(configDir, { recursive: true }); + mkdirSync(join(home, ".claude")); + const original = '{"keep":"original configuration"}'; + for (const path of [configPath, settingsPath, defaultConfig, defaultSettings]) { + writeFileSync(path, original); + } + + chmodSync(parent, 0o000); + try { + const result = spawnSync(process.execPath, [ + resolve(__dirname, "..", "dist", "cli.mjs"), + "connect", "claude-code", "--with-hooks", "--no-guidelines", + ], { + cwd: home, + env: { + ...process.env, + AGENTMEMORY_ENV_FILE: undefined, + CLAUDE_CONFIG_DIR: configDir, + CI: "1", + NO_COLOR: "1", + }, + encoding: "utf-8", + timeout: 10000, + }); + + expect(result.status, result.stderr).toBe(0); + const output = result.stdout + result.stderr; + expect(output).toContain(`Cannot inspect Claude Code configuration directory ${JSON.stringify(configDir)} (EACCES)`); + expect(output).toContain("Check directory permissions and retry."); + expect(output).toContain("not detected on this machine (skipping)"); + expect(output).not.toContain("wired into"); + } finally { + chmodSync(parent, 0o700); + } + for (const path of [configPath, settingsPath, defaultConfig, defaultSettings]) { + expect(readFileSync(path, "utf-8")).toBe(original); + } + }, 15000); + }); + + it("merges MCP and hooks in CLAUDE_CONFIG_DIR and leaves default files untouched", async () => { + const configDir = join(home, "custom Claude config"); + const configPath = join(configDir, ".claude.json"); + const settingsPath = join(configDir, "settings.json"); + const existingServer = { command: "existing-server", args: [] }; + const userHook = { hooks: [{ type: "command", command: "echo user-hook" }] }; + mkdirSync(configDir); + mkdirSync(join(home, ".claude")); + writeFileSync(configPath, JSON.stringify({ mcpServers: { existing: existingServer }, theme: "dark" })); + writeFileSync(settingsPath, JSON.stringify({ env: { KEEP: "yes" }, hooks: { SessionStart: [userHook] } })); + writeFileSync(join(home, ".claude.json"), '{"keep":"default MCP"}'); + writeFileSync(join(home, ".claude", "settings.json"), '{"keep":"default settings"}'); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { adapter } = await import("../src/cli/connect/claude-code.js"); + const options = { dryRun: false, force: false, withHooks: true }; + const result = await adapter.install(options); + + expect(result).toMatchObject({ kind: "installed", mutatedPath: configPath }); + const config = JSON.parse(readFileSync(configPath, "utf-8")); + expect(config.theme).toBe("dark"); + expect(config.mcpServers.existing).toEqual(existingServer); + expect(config.mcpServers.agentmemory.args).toContain("@agentmemory/mcp"); + const settings = JSON.parse(readFileSync(settingsPath, "utf-8")); + expect(settings.env).toEqual({ KEEP: "yes" }); + expect(settings.hooks.SessionStart).toEqual([ + userHook, + ...buildMergedHooks(null, PLUGIN_ROOT, "hooks.json").hooks.SessionStart!, + ]); + expect(readFileSync(join(home, ".claude.json"), "utf-8")).toBe('{"keep":"default MCP"}'); + expect(readFileSync(join(home, ".claude", "settings.json"), "utf-8")).toBe('{"keep":"default settings"}'); + + const installedSettings = readFileSync(settingsPath, "utf-8"); + expect((await adapter.install(options)).kind).toBe("already-wired"); + expect(readFileSync(settingsPath, "utf-8")).toBe(installedSettings); + }); + + it("reports the custom MCP path on a dry run without writing files", async () => { + const configDir = join(home, "custom Claude config"); + mkdirSync(configDir); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { adapter } = await import("../src/cli/connect/claude-code.js"); + const result = await adapter.install({ dryRun: true, force: false, withHooks: true }); + + expect(result).toMatchObject({ kind: "installed", mutatedPath: join(configDir, ".claude.json") }); + expect(existsSync(join(configDir, ".claude.json"))).toBe(false); + expect(existsSync(join(configDir, "settings.json"))).toBe(false); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + }); + + it("puts MCP inside an explicitly configured default .claude directory", async () => { + const configDir = join(home, ".claude"); + mkdirSync(configDir); + vi.stubEnv("CLAUDE_CONFIG_DIR", configDir); + + const { adapter } = await import("../src/cli/connect/claude-code.js"); + const result = await adapter.install({ dryRun: false, force: false }); + + expect(result).toMatchObject({ kind: "installed", mutatedPath: join(configDir, ".claude.json") }); + expect(JSON.parse(readFileSync(join(configDir, ".claude.json"), "utf-8")).mcpServers.agentmemory).toBeDefined(); + expect(existsSync(join(home, ".claude.json"))).toBe(false); + }); + + it.each([undefined, "", " \t "])("keeps legacy paths when CLAUDE_CONFIG_DIR is %s", async (override) => { + vi.stubEnv("CLAUDE_CONFIG_DIR", override); + mkdirSync(join(home, ".claude")); + + const { adapter } = await import("../src/cli/connect/claude-code.js"); + expect(adapter.detect()).toBe(true); + const result = await adapter.install({ dryRun: false, force: false, withHooks: true }); + + expect(result).toMatchObject({ kind: "installed", mutatedPath: join(home, ".claude.json") }); + expect(JSON.parse(readFileSync(join(home, ".claude.json"), "utf-8")).mcpServers.agentmemory).toBeDefined(); + expect(JSON.parse(readFileSync(join(home, ".claude", "settings.json"), "utf-8")).hooks.SessionStart).toBeDefined(); + }); }); diff --git a/test/cli-connect.test.ts b/test/cli-connect.test.ts index e303fe1ab6..71548625b1 100644 --- a/test/cli-connect.test.ts +++ b/test/cli-connect.test.ts @@ -100,6 +100,7 @@ describe("agentmemory connect — claude-code adapter (mock filesystem)", () => originalUserprofile = process.env["USERPROFILE"]; process.env["HOME"] = tmpHome; process.env["USERPROFILE"] = tmpHome; + vi.stubEnv("CLAUDE_CONFIG_DIR", undefined); vi.resetModules(); }); @@ -109,6 +110,7 @@ describe("agentmemory connect — claude-code adapter (mock filesystem)", () => if (originalUserprofile !== undefined) process.env["USERPROFILE"] = originalUserprofile; else delete process.env["USERPROFILE"]; + vi.unstubAllEnvs(); rmSync(tmpHome, { recursive: true, force: true }); vi.resetModules(); }); diff --git a/test/clip-embedding-provider.test.ts b/test/clip-embedding-provider.test.ts index b605c1ef70..cfa35481b6 100644 --- a/test/clip-embedding-provider.test.ts +++ b/test/clip-embedding-provider.test.ts @@ -20,41 +20,67 @@ describe("ClipEmbeddingProvider (package unavailable)", () => { describe("ClipEmbeddingProvider (with loaded pipeline)", () => { function mockSuccessModule() { - const textExtractor = vi.fn(async (texts: string[]) => ({ - tolist: () => texts.map(() => [0.1, 0.2]), + const tokenized: unknown[] = []; + const textModel = vi.fn(async (inputs: { input_ids: number[][] }) => ({ + text_embeds: { + tolist: () => inputs.input_ids.map(() => Array.from({ length: 512 }, (_, i) => (i % 7) + 1)), + }, })); + const tokenizer = vi.fn((texts: string[]) => { + const out = { input_ids: texts.map(() => [1, 2, 3]) }; + tokenized.push(out); + return out; + }); + const fromPretrainedText = vi.fn(async () => textModel); + const fromPretrainedTokenizer = vi.fn(async () => tokenizer); + const imageVec = Array.from({ length: 512 }, (_, i) => (i % 5) + 1); const imageExtractor = vi.fn(async () => ({ - tolist: () => [[0.3, 0.4]], - data: new Float32Array([0.3, 0.4]), + tolist: () => [imageVec], + data: new Float32Array(imageVec), })); const fromBlob = vi.fn(async () => ({})); const pipeline = vi.fn((task: string) => { - if (task === "feature-extraction") return Promise.resolve(textExtractor); if (task === "image-feature-extraction") return Promise.resolve(imageExtractor); return Promise.reject(new Error(`unmocked task: ${task}`)); }); vi.doMock("@huggingface/transformers", () => ({ pipeline, + AutoTokenizer: { from_pretrained: fromPretrainedTokenizer }, + CLIPTextModelWithProjection: { from_pretrained: fromPretrainedText }, RawImage: { fromBlob }, })); vi.resetModules(); - return { pipeline, textExtractor, imageExtractor, fromBlob }; + return { + pipeline, + textModel, + tokenizer, + tokenized, + fromPretrainedText, + fromPretrainedTokenizer, + imageExtractor, + fromBlob, + }; } - it("loads text pipeline with dtype: q8 and returns mapped Float32Array", async () => { - const { pipeline } = mockSuccessModule(); + it("loads the CLIP text tower with dtype: q8 and returns a normalized Float32Array", async () => { + const { pipeline, fromPretrainedText, fromPretrainedTokenizer } = mockSuccessModule(); const { ClipEmbeddingProvider: Fresh } = await import( "../src/providers/embedding/clip.js" ); const vec = await new Fresh().embed("hello"); - expect(pipeline).toHaveBeenCalledWith( + expect(fromPretrainedTokenizer).toHaveBeenCalledWith("Xenova/clip-vit-base-patch32"); + expect(fromPretrainedText).toHaveBeenCalledWith("Xenova/clip-vit-base-patch32", { + dtype: "q8", + }); + expect(pipeline).not.toHaveBeenCalledWith( "feature-extraction", - "Xenova/clip-vit-base-patch32", - { dtype: "q8" }, + expect.anything(), + expect.anything(), ); expect(vec).toBeInstanceOf(Float32Array); - expect(vec).toEqual(new Float32Array([0.1, 0.2])); + const norm = Math.sqrt(vec.reduce((s, v) => s + v * v, 0)); + expect(norm).toBeCloseTo(1, 6); }); it("embedBatch returns one Float32Array per input", async () => { @@ -85,16 +111,110 @@ describe("ClipEmbeddingProvider (with loaded pipeline)", () => { }); it("accepts custom model ID via constructor", async () => { - const { pipeline } = mockSuccessModule(); + const { fromPretrainedText, fromPretrainedTokenizer } = mockSuccessModule(); const { ClipEmbeddingProvider: Fresh } = await import( "../src/providers/embedding/clip.js" ); await new Fresh("Xenova/clip-vit-large-patch14").embed("hello"); + expect(fromPretrainedTokenizer).toHaveBeenCalledWith("Xenova/clip-vit-large-patch14"); + expect(fromPretrainedText).toHaveBeenCalledWith("Xenova/clip-vit-large-patch14", { + dtype: "q8", + }); + }); + + it("caches the text tower across calls instead of reloading it", async () => { + const { fromPretrainedText, fromPretrainedTokenizer } = mockSuccessModule(); + const { ClipEmbeddingProvider: Fresh } = await import( + "../src/providers/embedding/clip.js" + ); + const provider = new Fresh(); + await provider.embed("hello"); + await provider.embed("world"); + await provider.embedBatch(["a", "b"]); + + expect(fromPretrainedTokenizer).toHaveBeenCalledTimes(1); + expect(fromPretrainedText).toHaveBeenCalledTimes(1); + }); + + it("tokenizes with padding so a batch of uneven texts stays one tensor", async () => { + const { tokenizer, tokenized, textModel } = mockSuccessModule(); + const { ClipEmbeddingProvider: Fresh } = await import( + "../src/providers/embedding/clip.js" + ); + await new Fresh().embedBatch(["hi", "a much longer caption"]); + + expect(tokenizer).toHaveBeenCalledWith( + ["hi", "a much longer caption"], + expect.objectContaining({ padding: true, truncation: true }), + ); + expect(tokenized).toHaveLength(1); + expect(textModel).toHaveBeenCalledWith(tokenized[0]); + }); + + it("keeps text and image vectors in the same space via the projection head", async () => { + const { fromPretrainedText, pipeline } = mockSuccessModule(); + const { ClipEmbeddingProvider: Fresh } = await import( + "../src/providers/embedding/clip.js" + ); + const provider = new Fresh(); + const text = await provider.embed("a red square"); + const image = await provider.embedImage("data:image/png;base64,AAAA"); + + expect(fromPretrainedText).toHaveBeenCalled(); expect(pipeline).toHaveBeenCalledWith( - "feature-extraction", - "Xenova/clip-vit-large-patch14", - { dtype: "q8" }, + "image-feature-extraction", + expect.anything(), + expect.anything(), + ); + expect(text).toHaveLength(512); + expect(image).toHaveLength(512); + const norm = (v: Float32Array) => Math.sqrt(v.reduce((s, x) => s + x * x, 0)); + expect(norm(text)).toBeCloseTo(1, 6); + expect(norm(image)).toBeCloseTo(1, 6); + }); + + it("propagates a non-missing-module load failure untouched", async () => { + const boom = Object.assign(new Error("wasm backend unavailable"), { + code: "ERR_DLOPEN_FAILED", + }); + vi.doMock("@huggingface/transformers", () => ({ + get pipeline() { + throw boom; + }, + get AutoTokenizer() { + throw boom; + }, + get CLIPTextModelWithProjection() { + throw boom; + }, + RawImage: { fromBlob: vi.fn() }, + })); + vi.resetModules(); + const { ClipEmbeddingProvider: Fresh } = await import( + "../src/providers/embedding/clip.js" ); + + await expect(new Fresh().embed("hello")).rejects.toThrow( + "wasm backend unavailable", + ); + }); + + it("rethrows a failed module import instead of the install hint", async () => { + const boom = Object.assign(new Error("wasm backend unavailable"), { + code: "ERR_DLOPEN_FAILED", + }); + vi.doMock("@huggingface/transformers", () => { + throw boom; + }); + vi.resetModules(); + const { ClipEmbeddingProvider: Fresh } = await import( + "../src/providers/embedding/clip.js" + ); + + const err = await new Fresh().embed("hello").catch((e: unknown) => e); + expect(err).toBeInstanceOf(Error); + expect((err as Error).message).not.toContain("Install @huggingface/transformers"); + expect(err === boom || (err as Error).cause === boom).toBe(true); }); }); diff --git a/test/hybrid-search.test.ts b/test/hybrid-search.test.ts index fde7aa2deb..2467c37359 100644 --- a/test/hybrid-search.test.ts +++ b/test/hybrid-search.test.ts @@ -3,7 +3,8 @@ import { VectorIndex } from "../src/state/vector-index.js"; import { HybridSearch } from "../src/state/hybrid-search.js"; import { KV } from "../src/state/schema.js"; import { SearchIndex } from "../src/state/search-index.js"; -import type { CompressedObservation, EmbeddingProvider } from "../src/types.js"; +import type { CompressedObservation, EmbeddingProvider, Memory } from "../src/types.js"; +import { memoryToObservation } from "../src/state/memory-utils.js"; function makeObs( overrides: Partial = {}, @@ -54,6 +55,63 @@ describe("HybridSearch", () => { kv = mockKV(); }); + it("does not cap saved memories at three by their shared synthetic session", async () => { + for (let i = 1; i <= 6; i++) { + const memory: Memory = { + id: `mem_${i}`, + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), + type: "fact", + title: `quasar policy ${i}`, + content: `quasar quasar quasar policy rule ${i}`, + concepts: [], + files: [], + sessionIds: [], + strength: 7, + version: 1, + isLatest: true, + }; + await kv.set(KV.memories, memory.id, memory); + bm25.add(memoryToObservation(memory), "memory"); + } + for (let i = 1; i <= 5; i++) { + const obs = makeObs({ id: `obs_${i}`, sessionId: `ses_${i}`, title: `quasar note ${i}`, narrative: `quasar mention ${i}`, facts: [], concepts: [], files: [] }); + bm25.add(obs); + await kv.set(KV.observations(obs.sessionId), obs.id, obs); + } + const hybrid = new HybridSearch(bm25, null, null, kv as never, 0.4, 0.6, 0, false); + const results = await hybrid.search("quasar policy", 6); + expect(results.map((r) => r.observation.id).filter((id) => id.startsWith("mem_"))).toHaveLength(6); + }); + + it("ranks a record first when it scores well in both keyword and vector search, even for a one-result search", async () => { + const keywordOnly = makeObs({ id: "obs_keyword", sessionId: "ses_k", title: "zephyr zephyr zephyr", narrative: "zephyr zephyr zephyr", facts: [], concepts: [], files: [] }); + const keywordSecond = makeObs({ id: "obs_keyword2", sessionId: "ses_k2", title: "zephyr zephyr notes", narrative: "zephyr zephyr notes", facts: [], concepts: [], files: [] }); + const both = makeObs({ id: "obs_both", sessionId: "ses_b", title: "zephyr notes notes", narrative: "zephyr notes notes", facts: [], concepts: [], files: [] }); + const vectorOnly = makeObs({ id: "obs_vector", sessionId: "ses_v", title: "unrelated", narrative: "unrelated", facts: [], concepts: [], files: [] }); + for (const obs of [keywordOnly, keywordSecond, both]) bm25.add(obs); + for (const obs of [keywordOnly, keywordSecond, both, vectorOnly]) await kv.set(KV.observations(obs.sessionId), obs.id, obs); + const vector = new VectorIndex(); + vector.add(vectorOnly.id, vectorOnly.sessionId, new Float32Array([1, 0])); + vector.add(both.id, both.sessionId, new Float32Array([0.9, 0.1])); + const provider = { name: "test", dimensions: 2, embed: vi.fn(async () => new Float32Array([1, 0])), embedBatch: vi.fn() }; + const hybrid = new HybridSearch(bm25, vector, provider, kv as never, 0.4, 0.6, 0, false); + const results = await hybrid.search("zephyr", 1); + expect(results.map((r) => r.observation.id)).toEqual(["obs_both"]); + }); + + it("returns a valid lower-ranked record when stale index entries fill the first enrichment pass", async () => { + for (let i = 0; i < 25; i++) { + bm25.add(makeObs({ id: `obs_stale_${i}`, sessionId: `ses_stale_${i}`, title: "nebula nebula nebula", narrative: "nebula nebula nebula", facts: [], concepts: [], files: [] })); + } + const valid = makeObs({ id: "obs_valid", sessionId: "ses_valid", title: "nebula notes notes", narrative: "nebula notes notes", facts: [], concepts: [], files: [] }); + bm25.add(valid); + await kv.set(KV.observations(valid.sessionId), valid.id, valid); + const hybrid = new HybridSearch(bm25, null, null, kv as never, 0.4, 0.6, 0, false); + const results = await hybrid.search("nebula", 5); + expect(results.map((r) => r.observation.id)).toEqual(["obs_valid"]); + }); + it("reuses query embeddings only within a recall request", async () => { const obs = makeObs(); bm25.add(obs); diff --git a/test/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts index 6101e9bda0..dd7b27bb39 100644 --- a/test/mcp-standalone-proxy.test.ts +++ b/test/mcp-standalone-proxy.test.ts @@ -2,6 +2,9 @@ import { describe, expect, it, beforeEach, afterEach, vi } from "vitest"; import { handleToolCall, handleToolsList } from "../src/mcp/standalone.js"; import { resetHandleForTests } from "../src/mcp/rest-proxy.js"; import { InMemoryKV } from "../src/mcp/in-memory-kv.js"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; type FetchMock = ReturnType; @@ -274,10 +277,10 @@ describe("@agentmemory/mcp standalone — server proxy", () => { let probeCount = 0; const refusal = { success: false, - error: "Response is 20.0 MiB, over the ~15 MiB engine transport frame limit; narrow the range", + error: "Response is 70.0 MiB, over the ~60 MiB engine transport message limit; narrow the range", oversized: true, - bytes: 20 * 1024 * 1024, - limitBytes: 15 * 1024 * 1024, + bytes: 70 * 1024 * 1024, + limitBytes: 60 * 1024 * 1024, }; installFetch((url) => { if (url.endsWith("/agentmemory/livez")) { @@ -516,6 +519,41 @@ describe("@agentmemory/mcp standalone — server proxy", () => { delete process.env["AGENTMEMORY_TOOLS"]; }); + it("gives proxied calls more than the worker invocation budget and honours AGENTMEMORY_CALL_TIMEOUT_MS", async () => { + installFetch((url) => { + if (url.endsWith("/agentmemory/livez")) return new Response("ok", { status: 200 }); + return new Response(JSON.stringify({ sessions: [] }), { status: 200 }); + }); + const saved = { call: process.env["AGENTMEMORY_CALL_TIMEOUT_MS"], file: process.env["AGENTMEMORY_ENV_FILE"] }; + const dir = mkdtempSync(join(tmpdir(), "am-call-timeout-")); + const envFile = join(dir, "agentmemory.env"); + delete process.env["AGENTMEMORY_CALL_TIMEOUT_MS"]; + process.env["AGENTMEMORY_ENV_FILE"] = envFile; + const timeout = vi.spyOn(AbortSignal, "timeout"); + const lastTimeout = async () => { + await handleToolCall("memory_sessions", { limit: 1 }); + return timeout.mock.lastCall?.[0]; + }; + try { + expect(await lastTimeout()).toBe(190_000); + writeFileSync(envFile, "AGENTMEMORY_CALL_TIMEOUT_MS=600000\n"); + expect(await lastTimeout()).toBe(600_000); + process.env["AGENTMEMORY_CALL_TIMEOUT_MS"] = "900000"; + expect(await lastTimeout()).toBe(900_000); + for (const bad of ["bogus", "0.5", "1e6", "600s", "2592000000"]) { + process.env["AGENTMEMORY_CALL_TIMEOUT_MS"] = bad; + expect(await lastTimeout()).toBe(190_000); + } + } finally { + timeout.mockRestore(); + rmSync(dir, { recursive: true, force: true }); + if (saved.call === undefined) delete process.env["AGENTMEMORY_CALL_TIMEOUT_MS"]; + else process.env["AGENTMEMORY_CALL_TIMEOUT_MS"] = saved.call; + if (saved.file === undefined) delete process.env["AGENTMEMORY_ENV_FILE"]; + else process.env["AGENTMEMORY_ENV_FILE"] = saved.file; + } + }); + it("AGENTMEMORY_PROBE_TIMEOUT_MS overrides the default probe timeout", async () => { process.env["AGENTMEMORY_PROBE_TIMEOUT_MS"] = "50"; let probeStarted = 0; diff --git a/test/plugin-bridge-secret.test.ts b/test/plugin-bridge-secret.test.ts index dac9679174..d398b1baec 100644 --- a/test/plugin-bridge-secret.test.ts +++ b/test/plugin-bridge-secret.test.ts @@ -131,3 +131,21 @@ describe("plugin bridge reads Claude Code plugin settings", () => { expect(authorization()).toBeUndefined(); }); }); + +describe("plugin bridge call timeout", () => { + it("uses the shared MCP call timeout instead of a fixed 15 s", async () => { + vi.stubEnv("AGENTMEMORY_CALL_TIMEOUT_MS", ""); + vi.stubEnv("CLAUDE_PLUGIN_OPTION_AGENTMEMORY_CALL_TIMEOUT_MS", ""); + vi.stubEnv("AGENTMEMORY_ENV_FILE", ""); + const timeout = vi.spyOn(AbortSignal, "timeout"); + try { + await createPluginBridge()("tools/list", {}); + expect(timeout).toHaveBeenLastCalledWith(190_000); + vi.stubEnv("AGENTMEMORY_CALL_TIMEOUT_MS", "600000"); + await createPluginBridge()("tools/list", {}); + expect(timeout).toHaveBeenLastCalledWith(600_000); + } finally { + timeout.mockRestore(); + } + }); +}); diff --git a/test/provider-placeholder-keys.test.ts b/test/provider-placeholder-keys.test.ts new file mode 100644 index 0000000000..1066fd0a24 --- /dev/null +++ b/test/provider-placeholder-keys.test.ts @@ -0,0 +1,261 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { mkdtempSync, readFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +const fakeHome = mkdtempSync(join(tmpdir(), "agentmemory-placeholder-")); + +vi.mock("node:os", async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, homedir: () => fakeHome }; +}); + +const PROVIDER_ENV = /(API_KEY|_KEY$|_TOKEN$|PROVIDER|_BASE_URL$|^AGENTMEMORY_ALLOW_AGENT_SDK$|^OLLAMA)/; + +describe("placeholder provider keys", () => { + const saved: Record = {}; + + beforeEach(() => { + vi.resetModules(); + vi.spyOn(process.stderr, "write").mockImplementation(() => true); + for (const key of Object.keys(process.env)) { + if (PROVIDER_ENV.test(key)) { + saved[key] = process.env[key]; + delete process.env[key]; + } + } + }); + + afterEach(() => { + for (const key of Object.keys(process.env)) { + if (PROVIDER_ENV.test(key)) delete process.env[key]; + } + for (const [key, value] of Object.entries(saved)) { + if (value !== undefined) process.env[key] = value; + } + vi.restoreAllMocks(); + vi.unstubAllGlobals(); + }); + + it.each([ + ["anthropic", "ANTHROPIC_API_KEY", "sk-ant-..."], + ["openai", "OPENAI_API_KEY", "sk-..."], + ["openrouter", "OPENROUTER_API_KEY", "changeme"], + ["minimax", "MINIMAX_API_KEY", "your-key-here"], + ["gemini", "GEMINI_API_KEY", "xxxx-xxxx"], + ["gemini", "GOOGLE_API_KEY", "your-key-here"], + ["openrouter", "OPENROUTER_API_KEY", "CHANGEME"], + ["anthropic", "ANTHROPIC_API_KEY", "todo"], + ["gemini", "GEMINI_API_KEY", "XXXX-XXXX"], + ["openrouter", "OPENROUTER_API_KEY", "sk-or-v1-..."], + ["anthropic", "ANTHROPIC_API_KEY", " "], + ["anthropic", "ANTHROPIC_API_KEY", "sk-ant-... "], + ])("runs zero-LLM when %s is chosen but %s=%s", async (provider, key, value) => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = provider; + process.env[key] = value; + const { loadConfig, detectLlmProviderKind, llmOptInHint } = await import("../src/config.js"); + + expect(loadConfig().provider.provider).toBe("noop"); + expect(detectLlmProviderKind()).toBe("noop"); + expect(llmOptInHint()).toContain(`AGENTMEMORY_LLM_PROVIDER=${provider} is set, but`); + }); + + it("does not offer a provider whose only key is a placeholder", async () => { + process.env["ANTHROPIC_API_KEY"] = "sk-ant-..."; + process.env["GEMINI_API_KEY"] = "your-key-here"; + process.env["GOOGLE_API_KEY"] = "AIzaRealKey123"; + const { llmOptInHint } = await import("../src/config.js"); + + const hint = llmOptInHint(); + expect(hint).toContain("Found GOOGLE_API_KEY,"); + expect(hint).toContain("AGENTMEMORY_LLM_PROVIDER=gemini"); + expect(hint).not.toContain("ANTHROPIC_API_KEY"); + expect(hint).not.toContain("GEMINI_API_KEY"); + + delete process.env["GOOGLE_API_KEY"]; + expect(llmOptInHint()).toBeNull(); + }); + + it("rejects every sample value in .env.example", async () => { + const { isRealProviderKey } = await import("../src/config.js"); + const example = readFileSync(join(import.meta.dirname, "..", ".env.example"), "utf-8"); + const samples = [...example.matchAll(/^#\s*([A-Z_]+_API_KEY)=(\S+)/gm)]; + + expect(samples.length).toBeGreaterThan(0); + for (const [, key, value] of samples) { + expect(isRealProviderKey({ [key]: value }, key), `${key}=${value}`).toBe(false); + } + }); + + it("keeps a dummy OpenAI key for a plain-http OPENAI_BASE_URL", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "openai"; + process.env["OPENAI_API_KEY"] = "xxx"; + process.env["OPENAI_BASE_URL"] = "http://localhost:11434/v1"; + const fetchMock = vi.fn(async () => + new Response(JSON.stringify({ choices: [{ message: { content: "ok" } }] }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + ); + vi.stubGlobal("fetch", fetchMock); + const { loadConfig, detectLlmProviderKind } = await import("../src/config.js"); + const { createProvider } = await import("../src/providers/index.js"); + const { realProviderKeys, placeholderProviderKeys } = await import( + "../src/cli/doctor-diagnostics.js" + ); + + const config = loadConfig(); + expect(config.provider.provider).toBe("openai"); + expect(detectLlmProviderKind()).toBe("llm"); + await createProvider(config.provider).compress("system", "user"); + const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]; + expect(String(url)).toContain("localhost:11434"); + expect((init.headers as Record)["Authorization"]).toBe("Bearer xxx"); + + const env = { OPENAI_API_KEY: "xxx", OPENAI_BASE_URL: "http://localhost:11434/v1" }; + expect(realProviderKeys(env)).toEqual(["OPENAI_API_KEY"]); + expect(placeholderProviderKeys(env)).toEqual([]); + }); + + it.each([undefined, "", " "])("does not count OPENAI_API_KEY=%j behind a plain-http OPENAI_BASE_URL", async (key) => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "openai"; + process.env["OPENAI_BASE_URL"] = "http://localhost:11434/v1"; + if (key !== undefined) process.env["OPENAI_API_KEY"] = key; + const { loadConfig, detectLlmProviderKind, llmOptInHint } = await import("../src/config.js"); + const { realProviderKeys } = await import("../src/cli/doctor-diagnostics.js"); + + expect(loadConfig().provider.provider).toBe("noop"); + expect(detectLlmProviderKind()).toBe("noop"); + expect(llmOptInHint()).toContain("OPENAI_API_KEY is not"); + expect(realProviderKeys({ OPENAI_API_KEY: key ?? "", OPENAI_BASE_URL: "http://localhost:11434/v1" })).toEqual([]); + }); + + it("keeps a dummy OpenAI key for a plain-http server on another host", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "openai"; + process.env["OPENAI_API_KEY"] = "xxx"; + process.env["OPENAI_BASE_URL"] = "http://vllm.lan:8000/v1"; + const { loadConfig, detectLlmProviderKind } = await import("../src/config.js"); + const { realProviderKeys } = await import("../src/cli/doctor-diagnostics.js"); + + expect(loadConfig().provider.provider).toBe("openai"); + expect(detectLlmProviderKind()).toBe("llm"); + expect( + realProviderKeys({ OPENAI_API_KEY: "xxx", OPENAI_BASE_URL: "http://vllm.lan:8000/v1" }), + ).toEqual(["OPENAI_API_KEY"]); + }); + + it("keeps a sample OpenAI key for a plain-http OPENAI_BASE_URL", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "openai"; + process.env["OPENAI_API_KEY"] = "sk-..."; + process.env["OPENAI_BASE_URL"] = "http://localhost:11434/v1"; + const { loadConfig, detectLlmProviderKind } = await import("../src/config.js"); + const { realProviderKeys } = await import("../src/cli/doctor-diagnostics.js"); + + expect(loadConfig().provider.provider).toBe("openai"); + expect(detectLlmProviderKind()).toBe("llm"); + expect( + realProviderKeys({ OPENAI_API_KEY: "sk-...", OPENAI_BASE_URL: "http://localhost:11434/v1" }), + ).toEqual(["OPENAI_API_KEY"]); + }); + + it("does not keep a placeholder OpenAI key for an https OPENAI_BASE_URL", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "openai"; + process.env["OPENAI_API_KEY"] = "sk-..."; + process.env["OPENAI_BASE_URL"] = "https://api.openai.com"; + const { loadConfig, detectLlmProviderKind } = await import("../src/config.js"); + const { placeholderProviderKeys } = await import("../src/cli/doctor-diagnostics.js"); + + expect(loadConfig().provider.provider).toBe("noop"); + expect(detectLlmProviderKind()).toBe("noop"); + expect( + placeholderProviderKeys({ OPENAI_API_KEY: "sk-...", OPENAI_BASE_URL: "https://api.openai.com" }), + ).toEqual(["OPENAI_API_KEY"]); + }); + + it("keeps OPENAI_BASE_URL from excusing other placeholder keys", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "anthropic"; + process.env["ANTHROPIC_API_KEY"] = "sk-ant-..."; + process.env["OPENAI_BASE_URL"] = "http://localhost:11434/v1"; + const { loadConfig, detectLlmProviderKind } = await import("../src/config.js"); + const { placeholderProviderKeys } = await import("../src/cli/doctor-diagnostics.js"); + + expect(loadConfig().provider.provider).toBe("noop"); + expect(detectLlmProviderKind()).toBe("noop"); + expect( + placeholderProviderKeys({ ANTHROPIC_API_KEY: "sk-ant-...", OPENAI_BASE_URL: "http://localhost:11434/v1" }), + ).toEqual(["ANTHROPIC_API_KEY"]); + }); + + it.each([ + ["anthropic", "ANTHROPIC_API_KEY", "sk-ant-..."], + ["minimax", "MINIMAX_API_KEY", "changeme"], + ["openrouter", "OPENROUTER_API_KEY", "sk-or-..."], + ["openai", "OPENAI_API_KEY", "sk-..."], + ] as const)("does not build the %s provider from a placeholder %s", async (provider, key, value) => { + process.env[key] = value; + const { createProvider } = await import("../src/providers/index.js"); + + expect(() => createProvider({ provider, model: "m", maxTokens: 1 })).toThrow(key); + }); + + it.each([ + ["anthropic", "ANTHROPIC_API_KEY", "sk-ant-api03-abc123"], + ["openai", "OPENAI_API_KEY", "xai-abc123def"], + ] as const)("still uses the chosen %s provider with a real %s", async (provider, key, value) => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = provider; + process.env[key] = value; + const { loadConfig } = await import("../src/config.js"); + + expect(loadConfig().provider.provider).toBe(provider); + }); + + it("sends GEMINI_API_KEY without a warning when both Gemini keys are real", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "gemini"; + process.env["GEMINI_API_KEY"] = "AIzaGeminiKey456"; + process.env["GOOGLE_API_KEY"] = "AIzaRealKey123"; + const fetchMock = vi.fn(async () => + new Response(JSON.stringify({ choices: [{ message: { content: "ok" } }] }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + ); + vi.stubGlobal("fetch", fetchMock); + const { loadConfig } = await import("../src/config.js"); + const { createProvider } = await import("../src/providers/index.js"); + + const config = loadConfig(); + expect(config.provider.provider).toBe("gemini"); + await createProvider(config.provider).compress("system", "user"); + + const init = fetchMock.mock.calls[0][1] as RequestInit; + expect((init.headers as Record)["Authorization"]).toBe("Bearer AIzaGeminiKey456"); + expect(process.stderr.write).not.toHaveBeenCalledWith( + expect.stringContaining("GOOGLE_API_KEY detected"), + ); + }); + + it("sends GOOGLE_API_KEY when GEMINI_API_KEY is a placeholder", async () => { + process.env["AGENTMEMORY_LLM_PROVIDER"] = "gemini"; + process.env["GEMINI_API_KEY"] = "your-key-here"; + process.env["GOOGLE_API_KEY"] = "AIzaRealKey123"; + const fetchMock = vi.fn(async () => + new Response(JSON.stringify({ choices: [{ message: { content: "ok" } }] }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + ); + vi.stubGlobal("fetch", fetchMock); + const { loadConfig } = await import("../src/config.js"); + const { createProvider } = await import("../src/providers/index.js"); + + const config = loadConfig(); + expect(config.provider.provider).toBe("gemini"); + await createProvider(config.provider).compress("system", "user"); + + const init = fetchMock.mock.calls[0][1] as RequestInit; + expect((init.headers as Record)["Authorization"]).toBe("Bearer AIzaRealKey123"); + expect(process.stderr.write).toHaveBeenCalledWith( + expect.stringContaining("GOOGLE_API_KEY detected"), + ); + }); +}); diff --git a/test/resilient-content-filter.test.ts b/test/resilient-content-filter.test.ts new file mode 100644 index 0000000000..0c6026a18c --- /dev/null +++ b/test/resilient-content-filter.test.ts @@ -0,0 +1,106 @@ +import { describe, expect, it } from "vitest"; +import { ResilientProvider, isPayloadRejection } from "../src/providers/resilient.js"; +import type { MemoryProvider } from "../src/types.js"; + +const CONTENT_FILTER_ERROR = new Error( + 'OpenAI API error (400): {"error":{"message":"The response was filtered due to ' + + 'the prompt triggering Azure OpenAI\'s content management policy.",' + + '"code":"content_filter","status":400,"innererror":{"code":"ResponsibleAIPolicyViolation",' + + '"content_filter_result":{"jailbreak":{"detected":true,"filtered":true}}}}}', +); + +const GATEWAY_ECHO_ERROR = new Error( + 'OpenAI API error (502): {"error":{"message":"upstream returned an error: ' + + '{\\"code\\":\\"content_filter\\",\\"innererror\\":' + + '{\\"code\\":\\"ResponsibleAIPolicyViolation\\"}}","code":"bad_gateway"}}', +); + +function providerThatFails(err: Error, okAfter = Infinity): MemoryProvider { + let calls = 0; + return { + name: "stub", + async compress() { + calls += 1; + if (calls > okAfter) return ""; + throw err; + }, + async summarize() { + return ""; + }, + } as MemoryProvider; +} + +describe("isPayloadRejection", () => { + it("recognises Azure content filter rejections", () => { + expect(isPayloadRejection(CONTENT_FILTER_ERROR)).toBe(true); + expect( + isPayloadRejection( + new Error('OpenAI API error (400): {"error":{"code":"ResponsibleAIPolicyViolation"}}'), + ), + ).toBe(true); + expect( + isPayloadRejection( + new Error('openrouter API error (400): {"error":{"code":"content_filter"}}'), + ), + ).toBe(true); + }); + + it("does not treat the filter code alone as a rejection", () => { + expect(isPayloadRejection(new Error("ResponsibleAIPolicyViolation"))).toBe(false); + }); + + it("treats genuine provider trouble as a failure", () => { + expect(isPayloadRejection(new Error("OpenAI API error (503): upstream down"))).toBe(false); + expect(isPayloadRejection(new Error("request timed out after 60000ms"))).toBe(false); + expect(isPayloadRejection("socket hang up")).toBe(false); + }); + + it("does not excuse a gateway failure that merely quotes the filter body", () => { + expect(isPayloadRejection(GATEWAY_ECHO_ERROR)).toBe(false); + }); +}); + +describe("ResilientProvider — content filter vs circuit breaker", () => { + it("keeps the breaker closed across repeated filter rejections", async () => { + const provider = new ResilientProvider(providerThatFails(CONTENT_FILTER_ERROR)); + + for (let i = 0; i < 5; i++) { + await expect(provider.compress("sys", "bad")).rejects.toThrow(/content_filter/); + } + + expect(provider.circuitState.state).toBe("closed"); + }); + + it("lets an unrelated call through after filtered ones", async () => { + const provider = new ResilientProvider(providerThatFails(CONTENT_FILTER_ERROR, 3)); + + for (let i = 0; i < 3; i++) { + await expect(provider.compress("sys", "bad")).rejects.toThrow(/content_filter/); + } + + await expect(provider.compress("sys", "harmless")).resolves.toBe(""); + }); + + it("opens the breaker when a gateway failure quotes the filter body", async () => { + const provider = new ResilientProvider(providerThatFails(GATEWAY_ECHO_ERROR)); + + for (let i = 0; i < 3; i++) { + await expect(provider.compress("sys", "x")).rejects.toThrow(/502/); + } + + expect(provider.circuitState.state).toBe("open"); + }); + + it("still opens the breaker for real provider failures", async () => { + const provider = new ResilientProvider( + providerThatFails(new Error("OpenAI API error (503): upstream down")), + ); + + for (let i = 0; i < 3; i++) { + await expect(provider.compress("sys", "x")).rejects.toThrow(/503/); + } + + expect(provider.circuitState.state).toBe("open"); + await expect(provider.compress("sys", "x")).rejects.toThrow("circuit_breaker_open"); + }); +}); diff --git a/test/search-project-isolation.test.ts b/test/search-project-isolation.test.ts index 99069dd7eb..83a4d9b413 100644 --- a/test/search-project-isolation.test.ts +++ b/test/search-project-isolation.test.ts @@ -198,7 +198,7 @@ describe.each(["keyword", "hybrid", "hybrid-fallback"] as const)( }); if (ranking === "hybrid") { - it("expands a real hybrid window shortened by a missing record", async () => { + it("fills a real hybrid window shortened by a missing record", async () => { for (let i = 0; i < 100; i++) { addMemory({ id: `mem_foreign_${i.toString().padStart(3, "0")}`, project: "project-b" }); } @@ -210,7 +210,7 @@ describe.each(["keyword", "hybrid", "hybrid-fallback"] as const)( const ranker = vi.fn(hybrid.search.bind(hybrid)); setHybridRanker(ranker); expect(await recall({ limit: 1 })).toEqual([matching.id]); - expect(ranker.mock.calls.map((call) => call[1])).toEqual([100, 200]); + expect(ranker.mock.calls.map((call) => call[1])).toEqual([100]); }); } diff --git a/test/session-end-transcript.test.ts b/test/session-end-transcript.test.ts index c9f452e8b0..4ed260733a 100644 --- a/test/session-end-transcript.test.ts +++ b/test/session-end-transcript.test.ts @@ -8,14 +8,16 @@ import { join } from "node:path"; let server: Server; let port: number; const posts: Array<{ path: string; body: Record }> = []; +let observeDelayMs = 0; function runHook( payload: Record, script = "plugin/scripts/session-end.mjs", + extraEnv: Record = {}, ): Promise { return new Promise((resolve) => { const child = spawn("node", [script], { - env: { ...process.env, AGENTMEMORY_URL: `http://127.0.0.1:${port}` }, + env: { ...process.env, AGENTMEMORY_URL: `http://127.0.0.1:${port}`, ...extraEnv }, }); child.on("exit", (code) => resolve(code ?? 1)); child.stdin.write(JSON.stringify(payload)); @@ -37,8 +39,10 @@ describe("session-end transcript prompt backfill", () => { } catch { posts.push({ path: req.url ?? "", body: {} }); } - res.writeHead(200, { "Content-Type": "application/json" }); - res.end("{}"); + setTimeout(() => { + res.writeHead(200, { "Content-Type": "application/json" }); + res.end("{}"); + }, (req.url ?? "").includes("/observe") ? observeDelayMs : 0); }); }); await new Promise((r) => server.listen(0, "127.0.0.1", r)); @@ -107,6 +111,40 @@ describe("session-end transcript prompt backfill", () => { } }); + it("hands the work to a detached worker so the hook exits inside the 1.5 s SessionEnd budget", async () => { + posts.length = 0; + const transcript = join(dir, "handoff.jsonl"); + writeFileSync(transcript, JSON.stringify({ type: "user", message: { role: "user", content: "handoff prompt" } }) + "\n"); + observeDelayMs = 2500; + const started = Date.now(); + const code = await runHook({ session_id: "ses_handoff", hook_event_name: "SessionEnd", transcript_path: transcript }); + expect(code).toBe(0); + expect(Date.now() - started).toBeLessThan(1500); + const deadline = Date.now() + 10_000; + while (!posts.some((p) => p.path.includes("/session/end")) && Date.now() < deadline) { + await new Promise((r) => setTimeout(r, 50)); + } + observeDelayMs = 0; + const prompts = posts.filter((p) => p.path.includes("/observe")).map((p) => (p.body.data as { prompt: string }).prompt); + expect(prompts).toEqual(["handoff prompt"]); + const end = posts.find((p) => p.path.includes("/session/end")); + expect(end?.body).toMatchObject({ sessionId: "ses_handoff", final: true }); + }, 20_000); + + it("runs the Claude Code SessionEnd work inline inside the detached worker", async () => { + posts.length = 0; + const transcript = join(dir, "worker.jsonl"); + writeFileSync(transcript, JSON.stringify({ type: "user", message: { role: "user", content: "worker prompt" } }) + "\n"); + const code = await runHook( + { session_id: "ses_worker", hook_event_name: "SessionEnd", transcript_path: transcript }, + undefined, + { AGENTMEMORY_SESSION_END_WORKER: "1" }, + ); + expect(code).toBe(0); + expect(posts.filter((p) => p.path.includes("/observe")).map((p) => (p.body.data as { prompt: string }).prompt)).toEqual(["worker prompt"]); + expect(posts.some((p) => p.path.includes("/session/end"))).toBe(true); + }); + it("posts prompts from a Claude Code transcript, skipping tool results", async () => { posts.length = 0; const transcript = join(dir, "t-cc.jsonl"); From 612f7d1c67cbeae618589247f9da33df6cd89855 Mon Sep 17 00:00:00 2001 From: Daniel-Hong Date: Fri, 13 Nov 2026 18:55:42 +0900 Subject: [PATCH 15/23] ci(personal): validate review PRs with unit tests and generated-client parity --- .github/workflows/personal-pr-validation.yml | 49 ++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 .github/workflows/personal-pr-validation.yml diff --git a/.github/workflows/personal-pr-validation.yml b/.github/workflows/personal-pr-validation.yml new file mode 100644 index 0000000000..25f885b090 --- /dev/null +++ b/.github/workflows/personal-pr-validation.yml @@ -0,0 +1,49 @@ +name: Personal fork PR checks + +# Source-only validation for changes proposed against personal. +# No production credentials, service control, data migration or deployment. +on: + pull_request: + branches: [personal] + types: [opened, synchronize, reopened, ready_for_review] + +permissions: + contents: read + +concurrency: + group: personal-pr-checks-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + source: + name: Source, generated hooks and unit regressions + runs-on: ubuntu-latest + timeout-minutes: 35 + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + - uses: actions/setup-node@v6 + with: + node-version: 22 + - name: Install dependencies + run: npm install --legacy-peer-deps --no-audit --no-fund + - name: Build + run: npm run build + - name: Generate explicit Codex compatibility artifacts + run: npm run build:codex-compat + - name: Reject stale checked-in hook bundles + run: git diff --exit-code -- plugin/scripts + - name: Verify skills and documented facts + run: | + npm run skills:check + npm run docs:check + - name: Eval TypeScript contract + run: npx tsc --noEmit --project tsconfig.eval.json + - name: Unit and non-integration regressions (isolated HOME) + shell: bash + run: | + test_home="$(mktemp -d "${RUNNER_TEMP}/agentmemory-pr-home.XXXXXX")" + trap 'rm -rf "$test_home"' EXIT + export HOME="$test_home" + npm test From 796c2da88804127b76a0c5efc3743962deffbcf6 Mon Sep 17 00:00:00 2001 From: Daniel-Hong Date: Fri, 13 Nov 2026 18:58:09 +0900 Subject: [PATCH 16/23] fix(upstream): preserve custom capture normalization while exposing v0.9.33 privacy helper --- src/functions/privacy.ts | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/functions/privacy.ts b/src/functions/privacy.ts index ad4d3aaaaa..002475fcff 100644 --- a/src/functions/privacy.ts +++ b/src/functions/privacy.ts @@ -51,7 +51,11 @@ const URL_CREDENTIALS_RE = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@:"'<>]*:[^\s/?#@"'<>]+@/gi; export function stripPrivateData(input: string): string { - let result = redactPrivateBlocks(input); + return stripSecrets(redactPrivateBlocks(input)); +} + +export function stripSecrets(input: string): string { + let result = input; result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); for (const source of SECRET_PATTERN_SOURCES) { @@ -61,14 +65,18 @@ export function stripPrivateData(input: string): string { return result; } -export function scrubRecord(value: T, options: { scrubKeys?: boolean } = {}): T { - if (typeof value === "string") return stripPrivateData(value) as T; +export function scrubRecord( + value: T, + options: { scrubKeys?: boolean; strip?: (input: string) => string } = {}, +): T { + const strip = options.strip ?? stripPrivateData; + if (typeof value === "string") return strip(value) as T; if (Array.isArray(value)) return value.map((item) => scrubRecord(item, options)) as T; if (value !== null && typeof value === "object") { const proto = Object.getPrototypeOf(value); if (proto !== Object.prototype && proto !== null) return value; const entries = Object.entries(value as Record).map(([key, item]) => [ - options.scrubKeys ? stripPrivateData(key) : key, + options.scrubKeys ? strip(key) : key, item, ] as const); const reserved = new Set(entries.map(([key]) => key)); From 1cc3850e1281e276744f8c4e77e099c41c16c6e6 Mon Sep 17 00:00:00 2001 From: Daniel-Hong Date: Fri, 13 Nov 2026 18:59:47 +0900 Subject: [PATCH 17/23] fix(build): pin yaml and json5 to bundled SDK audit exact versions --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 98751a2508..7a53b44984 100644 --- a/package.json +++ b/package.json @@ -96,8 +96,8 @@ "iii-sdk": "0.25.0", "picocolors": "^1.1.1", "zod": "^4.0.0", - "yaml": "^2.8.1", - "json5": "^2.2.3" + "yaml": "2.8.1", + "json5": "2.2.3" }, "optionalDependencies": { "@huggingface/transformers": "^4.2.0", From 967f4842620f722150ca583d2b9e56f9db9ba4b9 Mon Sep 17 00:00:00 2001 From: Daniel-Hong Date: Fri, 13 Nov 2026 19:05:27 +0900 Subject: [PATCH 18/23] build(upstream): synchronize generated hook bundles with imported v0.9.33 fixes Reconstruct exact generated outputs of the isolated Node22 CI build; all 12 Git blob IDs match the build's expected blob SHA prefixes. Keep SDK-v2 Codex compatibility source and manifest in sync; no deployed client or runtime data changed. --- plugin/scripts/_capture.mjs | 19 ++- plugin/scripts/codex-compat/_capture.mjs | 19 ++- plugin/scripts/codex-compat/manifest.json | 2 +- plugin/scripts/plugin-bridge.mjs | 19 ++- plugin/scripts/post-tool-failure.mjs | 62 +++++++++- plugin/scripts/post-tool-use.mjs | 134 ++++++++++++++++++++-- plugin/scripts/pre-compact.mjs | 9 +- plugin/scripts/pre-tool-use.mjs | 9 +- plugin/scripts/session-end.mjs | 96 +++++++++++++++- plugin/scripts/session-start.mjs | 9 +- plugin/scripts/subagent-stop.mjs | 62 +++++++++- plugin/scripts/task-completed.mjs | 62 +++++++++- 12 files changed, 461 insertions(+), 41 deletions(-) mode change 100755 => 100644 plugin/scripts/post-tool-failure.mjs mode change 100755 => 100644 plugin/scripts/post-tool-use.mjs mode change 100755 => 100644 plugin/scripts/pre-compact.mjs mode change 100755 => 100644 plugin/scripts/pre-tool-use.mjs mode change 100755 => 100644 plugin/scripts/session-end.mjs mode change 100755 => 100644 plugin/scripts/session-start.mjs mode change 100755 => 100644 plugin/scripts/subagent-stop.mjs mode change 100755 => 100644 plugin/scripts/task-completed.mjs diff --git a/plugin/scripts/_capture.mjs b/plugin/scripts/_capture.mjs index 8ecb006c0e..22657a0619 100644 --- a/plugin/scripts/_capture.mjs +++ b/plugin/scripts/_capture.mjs @@ -743,7 +743,10 @@ const SECRET_PATTERN_SOURCES = [ const PRIVATE_KEY_BLOCK_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|$)/g; const URL_CREDENTIALS_RE = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@:"'<>]*:[^\s/?#@"'<>]+@/gi; function stripPrivateData(input) { - let result = redactPrivateBlocks(input); + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); for (const source of SECRET_PATTERN_SOURCES) { @@ -753,12 +756,13 @@ function stripPrivateData(input) { return result; } function scrubRecord(value, options = {}) { - if (typeof value === "string") return stripPrivateData(value); + const strip = options.strip ?? stripPrivateData; + if (typeof value === "string") return strip(value); if (Array.isArray(value)) return value.map((item) => scrubRecord(item, options)); if (value !== null && typeof value === "object") { const proto = Object.getPrototypeOf(value); if (proto !== Object.prototype && proto !== null) return value; - const entries = Object.entries(value).map(([key, item]) => [options.scrubKeys ? stripPrivateData(key) : key, item]); + const entries = Object.entries(value).map(([key, item]) => [options.scrubKeys ? strip(key) : key, item]); const reserved = new Set(entries.map(([key]) => key)); const used = /* @__PURE__ */ new Set(); return Object.fromEntries(entries.map(([key, item]) => { @@ -1731,7 +1735,7 @@ function unquote(value) { const hash = value.indexOf(" #"); return hash === -1 ? value : value.slice(0, hash).trim(); } -function readEnvFileSecret() { +function readEnvFileValue(name) { let content; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -1745,11 +1749,14 @@ function readEnvFileSecret() { if (trimmed.startsWith("#")) continue; const eq = trimmed.indexOf("="); if (eq === -1) continue; - if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +function readEnvFileSecret() { + return usable(readEnvFileValue(SECRET_KEY)); +} function readSecretFile(path) { try { return usable(readFileSync(path, "utf-8")); diff --git a/plugin/scripts/codex-compat/_capture.mjs b/plugin/scripts/codex-compat/_capture.mjs index 8ecb006c0e..22657a0619 100644 --- a/plugin/scripts/codex-compat/_capture.mjs +++ b/plugin/scripts/codex-compat/_capture.mjs @@ -743,7 +743,10 @@ const SECRET_PATTERN_SOURCES = [ const PRIVATE_KEY_BLOCK_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|$)/g; const URL_CREDENTIALS_RE = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@:"'<>]*:[^\s/?#@"'<>]+@/gi; function stripPrivateData(input) { - let result = redactPrivateBlocks(input); + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); for (const source of SECRET_PATTERN_SOURCES) { @@ -753,12 +756,13 @@ function stripPrivateData(input) { return result; } function scrubRecord(value, options = {}) { - if (typeof value === "string") return stripPrivateData(value); + const strip = options.strip ?? stripPrivateData; + if (typeof value === "string") return strip(value); if (Array.isArray(value)) return value.map((item) => scrubRecord(item, options)); if (value !== null && typeof value === "object") { const proto = Object.getPrototypeOf(value); if (proto !== Object.prototype && proto !== null) return value; - const entries = Object.entries(value).map(([key, item]) => [options.scrubKeys ? stripPrivateData(key) : key, item]); + const entries = Object.entries(value).map(([key, item]) => [options.scrubKeys ? strip(key) : key, item]); const reserved = new Set(entries.map(([key]) => key)); const used = /* @__PURE__ */ new Set(); return Object.fromEntries(entries.map(([key, item]) => { @@ -1731,7 +1735,7 @@ function unquote(value) { const hash = value.indexOf(" #"); return hash === -1 ? value : value.slice(0, hash).trim(); } -function readEnvFileSecret() { +function readEnvFileValue(name) { let content; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -1745,11 +1749,14 @@ function readEnvFileSecret() { if (trimmed.startsWith("#")) continue; const eq = trimmed.indexOf("="); if (eq === -1) continue; - if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +function readEnvFileSecret() { + return usable(readEnvFileValue(SECRET_KEY)); +} function readSecretFile(path) { try { return usable(readFileSync(path, "utf-8")); diff --git a/plugin/scripts/codex-compat/manifest.json b/plugin/scripts/codex-compat/manifest.json index d0cb6f8204..e81a3e5e46 100644 --- a/plugin/scripts/codex-compat/manifest.json +++ b/plugin/scripts/codex-compat/manifest.json @@ -14,7 +14,7 @@ "subagent-start.mjs": "24a02be53008721379cbf115884a7739baa2884f8d5f3e12a967b9ae8b0c2869", "subagent-stop.mjs": "8fc6929af24afd799cbaec3a3ca210971c9f51f139f6666fe0025fdfdc62dba8", "provenance.json": "4d768394ad40a29be9d2721fccffd0a054ec97bcc6b868305a27e755eb9b1759", - "_capture.mjs": "d48e2e7d12d6790a0851127bfef80b35e0c0cae8b7664c6897b0965b38bd9838" + "_capture.mjs": "261142bc4ef6c10209e8b2735c8aec24a6bcda77c60f74675172030b186d5bab" }, "deploymentMapping": { "plugin/scripts/long-session-hook-client.mjs": "plugin/scripts/codex-compat/long-session-hook-client.mjs", diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs index de03059905..c2731290f5 100644 --- a/plugin/scripts/plugin-bridge.mjs +++ b/plugin/scripts/plugin-bridge.mjs @@ -29,7 +29,7 @@ function unquote(value) { const hash = value.indexOf(" #"); return hash === -1 ? value : value.slice(0, hash).trim(); } -function readEnvFileSecret() { +function readEnvFileValue(name) { let content; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -43,11 +43,14 @@ function readEnvFileSecret() { if (trimmed.startsWith("#")) continue; const eq = trimmed.indexOf("="); if (eq === -1) continue; - if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +function readEnvFileSecret() { + return usable(readEnvFileValue(SECRET_KEY)); +} function readSecretFile(path) { try { return usable(readFileSync(path, "utf-8")); @@ -115,6 +118,14 @@ function resolveSettingSecret(url, env = process.env) { } //#endregion //#region src/mcp/rest-proxy.ts +const DEFAULT_CALL_TIMEOUT_MS = 19e4; +const MAX_TIMER_MS = 2147483647; +function callTimeoutMs() { + const name = "AGENTMEMORY_CALL_TIMEOUT_MS"; + const raw = (resolveEnvOrEmpty(name) || readEnvFileValue(name)).trim(); + const n = /^\d+$/.test(raw) ? Number(raw) : 0; + return n >= 1 && n <= MAX_TIMER_MS ? n : DEFAULT_CALL_TIMEOUT_MS; +} function resolveEnvOrEmpty(name) { return hookSetting(name) ?? ""; } @@ -343,7 +354,7 @@ function createPluginBridge() { }, body: body === void 0 ? void 0 : JSON.stringify(body), redirect: "error", - signal: AbortSignal.timeout(15e3) + signal: AbortSignal.timeout(callTimeoutMs()) }); } catch { throw new Error(`Agent Memory daemon is unreachable or timed out. ${SETUP} No fallback store was used; check state before retrying a write.`); diff --git a/plugin/scripts/post-tool-failure.mjs b/plugin/scripts/post-tool-failure.mjs old mode 100755 new mode 100644 index 85cf906e5c..3ca165ecb5 --- a/plugin/scripts/post-tool-failure.mjs +++ b/plugin/scripts/post-tool-failure.mjs @@ -3,6 +3,62 @@ import { execSync } from "node:child_process"; import { realpathSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { captureObservation, isDrainChild, runDrainChild, withEventId } from "./_capture.mjs"; +//#region src/functions/privacy.ts +const PRIVATE_TAG_TOKEN_RE = /)[^>]*>|<\/private\s*>/gi; +function redactPrivateBlocks(input) { + const tokens = new RegExp(PRIVATE_TAG_TOKEN_RE.source, PRIVATE_TAG_TOKEN_RE.flags); + let out = ""; + let cursor = 0; + let depth = 0; + for (let match = tokens.exec(input); match; match = tokens.exec(input)) { + const closing = match[0].startsWith(" 0) return `${out}[REDACTED]`; + return out + input.slice(cursor); +} +const SECRET_PATTERN_SOURCES = [ + /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi, + /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi, + /(?]*:[^\s/?#@"'<>]+@/gi; +function stripPrivateData(input) { + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; + result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); + result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); + for (const source of SECRET_PATTERN_SOURCES) { + const pattern = new RegExp(source.source, source.flags); + result = result.replace(pattern, "[REDACTED_SECRET]"); + } + return result; +} +//#endregion //#region src/hooks/_capture-filter.ts const DEFAULT_DENY_PATTERNS = [ "memory_*", @@ -43,11 +99,15 @@ function shouldCaptureTool(toolName) { if (allow) return matchesAny(toolName, allow); return !matchesAny(toolName, [...DEFAULT_DENY_PATTERNS, ...parseEnvList(process.env["AGENTMEMORY_CAPTURE_DENY"]) ?? []]); } -function truncateText(value, max) { +function cut(value, max) { if (value.length <= max) return value; const end = /[\uD800-\uDBFF]/.test(value[max - 1] ?? "") ? max - 1 : max; return value.slice(0, end); } +function truncateText(value, max) { + if (value.length <= max) return value; + return cut(stripPrivateData(value), max); +} //#endregion //#region src/hooks/_project.ts function resolveProject(cwd) { diff --git a/plugin/scripts/post-tool-use.mjs b/plugin/scripts/post-tool-use.mjs old mode 100755 new mode 100644 index 4f77d76bdb..35ef0642d1 --- a/plugin/scripts/post-tool-use.mjs +++ b/plugin/scripts/post-tool-use.mjs @@ -3,6 +3,86 @@ import { execSync } from "node:child_process"; import { realpathSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { captureObservationForHook, isDrainChild, runDrainChild, withEventId } from "./_capture.mjs"; +//#region src/functions/privacy.ts +const PRIVATE_TAG_TOKEN_RE = /)[^>]*>|<\/private\s*>/gi; +function redactPrivateBlocks(input) { + const tokens = new RegExp(PRIVATE_TAG_TOKEN_RE.source, PRIVATE_TAG_TOKEN_RE.flags); + let out = ""; + let cursor = 0; + let depth = 0; + for (let match = tokens.exec(input); match; match = tokens.exec(input)) { + const closing = match[0].startsWith(" 0) return `${out}[REDACTED]`; + return out + input.slice(cursor); +} +const SECRET_PATTERN_SOURCES = [ + /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi, + /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi, + /(?]*:[^\s/?#@"'<>]+@/gi; +function stripPrivateData(input) { + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; + result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); + result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); + for (const source of SECRET_PATTERN_SOURCES) { + const pattern = new RegExp(source.source, source.flags); + result = result.replace(pattern, "[REDACTED_SECRET]"); + } + return result; +} +function scrubRecord(value, options = {}) { + const strip = options.strip ?? stripPrivateData; + if (typeof value === "string") return strip(value); + if (Array.isArray(value)) return value.map((item) => scrubRecord(item, options)); + if (value !== null && typeof value === "object") { + const proto = Object.getPrototypeOf(value); + if (proto !== Object.prototype && proto !== null) return value; + const entries = Object.entries(value).map(([key, item]) => [options.scrubKeys ? strip(key) : key, item]); + const reserved = new Set(entries.map(([key]) => key)); + const used = /* @__PURE__ */ new Set(); + return Object.fromEntries(entries.map(([key, item]) => { + let unique = key; + if (used.has(unique)) { + let suffix = 2; + do + unique = `${key}_${suffix++}`; + while (reserved.has(unique) || used.has(unique)); + } + used.add(unique); + return [unique, scrubRecord(item, options)]; + })); + } + return value; +} +//#endregion //#region src/hooks/_capture-filter.ts const DEFAULT_DENY_PATTERNS = [ "memory_*", @@ -49,22 +129,56 @@ function captureOutputMax() { const parsed = Number.parseInt(raw, 10); return Number.isFinite(parsed) && parsed > 0 ? parsed : 8e3; } -function truncateText(value, max) { +function cut(value, max) { if (value.length <= max) return value; const end = /[\uD800-\uDBFF]/.test(value[max - 1] ?? "") ? max - 1 : max; return value.slice(0, end); } +const JSON_WHITESPACE_ESCAPES = { + n: "\n", + r: "\r", + t: " " +}; +const SECRET_KEY_SUFFIXES = [ + "apikey", + "secret", + "token", + "password", + "passwd", + "credential", + "credentials" +]; +const SECRET_KEY_WORDS = new Set(["auth", "authorization"]); +function isSecretKeyName(key) { + if (!/^[\w.-]{1,64}$/.test(key)) return false; + const words = key.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/([A-Za-z])(\d)/g, "$1_$2").toLowerCase().split(/[_.\-\d]+/).filter(Boolean); + return words.some((word, i) => SECRET_KEY_WORDS.has(word) || SECRET_KEY_SUFFIXES.some((suffix) => word.endsWith(suffix)) || word === "api" && words[i + 1] === "key"); +} +function redactSecretKeys(value) { + if (Array.isArray(value)) return value.map(redactSecretKeys); + if (value === null || typeof value !== "object") return value; + const proto = Object.getPrototypeOf(value); + if (proto !== Object.prototype && proto !== null) return value; + return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, typeof item === "string" && item && isSecretKeyName(key) ? "[REDACTED_SECRET]" : redactSecretKeys(item)])); +} +function scrubSecrets(value) { + return scrubRecord(redactSecretKeys(value), { + scrubKeys: true, + strip: stripSecrets + }); +} +function redactSerialized(serialized) { + return stripPrivateData(serialized.replace(/\\([\\nrt])/g, (escape, c) => JSON_WHITESPACE_ESCAPES[c] ?? escape)).replace(/[\n\r\t]/g, (c) => JSON.stringify(c).slice(1, -1)); +} +function truncateWithSuffix(value, max, suffix) { + const safe = stripPrivateData(value); + if (safe.length <= max) return safe; + return max <= suffix.length ? suffix.slice(0, max) : cut(safe, max - suffix.length) + suffix; +} function truncateCaptureOutput(value, max) { - if (typeof value === "string" && value.length > max) { - const suffix = "\n[...truncated]"; - return max <= 15 ? suffix.slice(0, max) : truncateText(value, max - 15) + suffix; - } + if (typeof value === "string" && value.length > max) return truncateWithSuffix(value, max, "\n[...truncated]"); if (typeof value === "object" && value !== null) { - const str = JSON.stringify(value); - if (str.length > max) { - const suffix = "...[truncated]"; - return max <= 14 ? suffix.slice(0, max) : truncateText(str, max - 14) + suffix; - } + if (JSON.stringify(value).length > max) return truncateWithSuffix(redactSerialized(JSON.stringify(scrubSecrets(value))), max, "...[truncated]"); return value; } return value; diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs old mode 100755 new mode 100644 index 56172e63f7..489ab1d830 --- a/plugin/scripts/pre-compact.mjs +++ b/plugin/scripts/pre-compact.mjs @@ -36,7 +36,7 @@ function unquote(value) { const hash = value.indexOf(" #"); return hash === -1 ? value : value.slice(0, hash).trim(); } -function readEnvFileSecret() { +function readEnvFileValue(name) { let content; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -50,11 +50,14 @@ function readEnvFileSecret() { if (trimmed.startsWith("#")) continue; const eq = trimmed.indexOf("="); if (eq === -1) continue; - if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +function readEnvFileSecret() { + return usable(readEnvFileValue(SECRET_KEY)); +} function readSecretFile(path) { try { return usable(readFileSync(path, "utf-8")); diff --git a/plugin/scripts/pre-tool-use.mjs b/plugin/scripts/pre-tool-use.mjs old mode 100755 new mode 100644 index 4a339b8aec..c20731ecc6 --- a/plugin/scripts/pre-tool-use.mjs +++ b/plugin/scripts/pre-tool-use.mjs @@ -26,7 +26,7 @@ function unquote(value) { const hash = value.indexOf(" #"); return hash === -1 ? value : value.slice(0, hash).trim(); } -function readEnvFileSecret() { +function readEnvFileValue(name) { let content; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -40,11 +40,14 @@ function readEnvFileSecret() { if (trimmed.startsWith("#")) continue; const eq = trimmed.indexOf("="); if (eq === -1) continue; - if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +function readEnvFileSecret() { + return usable(readEnvFileValue(SECRET_KEY)); +} function readSecretFile(path) { try { return usable(readFileSync(path, "utf-8")); diff --git a/plugin/scripts/session-end.mjs b/plugin/scripts/session-end.mjs old mode 100755 new mode 100644 index d64c0b2797..d146fecf14 --- a/plugin/scripts/session-end.mjs +++ b/plugin/scripts/session-end.mjs @@ -1,14 +1,74 @@ #!/usr/bin/env node +import { execSync, spawn } from "node:child_process"; import { readFileSync, realpathSync } from "node:fs"; -import { execSync } from "node:child_process"; import { basename, dirname, resolve } from "node:path"; import { REST_URL, authHeaders, captureObservation, isDrainChild, runDrainChild, transportBlocked, withEventId } from "./_capture.mjs"; +//#region src/functions/privacy.ts +const PRIVATE_TAG_TOKEN_RE = /)[^>]*>|<\/private\s*>/gi; +function redactPrivateBlocks(input) { + const tokens = new RegExp(PRIVATE_TAG_TOKEN_RE.source, PRIVATE_TAG_TOKEN_RE.flags); + let out = ""; + let cursor = 0; + let depth = 0; + for (let match = tokens.exec(input); match; match = tokens.exec(input)) { + const closing = match[0].startsWith(" 0) return `${out}[REDACTED]`; + return out + input.slice(cursor); +} +const SECRET_PATTERN_SOURCES = [ + /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi, + /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi, + /(?]*:[^\s/?#@"'<>]+@/gi; +function stripPrivateData(input) { + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; + result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); + result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); + for (const source of SECRET_PATTERN_SOURCES) { + const pattern = new RegExp(source.source, source.flags); + result = result.replace(pattern, "[REDACTED_SECRET]"); + } + return result; +} +//#endregion //#region src/hooks/_capture-filter.ts -function truncateText(value, max) { +function cut(value, max) { if (value.length <= max) return value; const end = /[\uD800-\uDBFF]/.test(value[max - 1] ?? "") ? max - 1 : max; return value.slice(0, end); } +function truncateText(value, max) { + if (value.length <= max) return value; + return cut(stripPrivateData(value), max); +} //#endregion //#region src/hooks/_project.ts function resolveProject(cwd) { @@ -110,6 +170,37 @@ function extractTranscriptPrompts(data) { } return prompts; } +const WORKER_ENV = "AGENTMEMORY_SESSION_END_WORKER"; +function handOff(input) { + if (process.env[WORKER_ENV] === "1" || !process.argv[1]) return Promise.resolve(false); + return new Promise((resolve) => { + try { + const child = spawn(process.execPath, [process.argv[1]], { + detached: true, + stdio: [ + "pipe", + "ignore", + "ignore" + ], + windowsHide: true, + env: { + ...process.env, + [WORKER_ENV]: "1" + } + }); + child.on("error", () => resolve(false)); + child.stdin.on("error", () => resolve(false)); + child.once("spawn", () => { + child.stdin.end(input, () => { + child.unref(); + resolve(true); + }); + }); + } catch { + resolve(false); + } + }); +} async function main() { if (isDrainChild()) return runDrainChild(); let input = ""; @@ -122,6 +213,7 @@ async function main() { } if (!data || typeof data !== "object") return; if (isSdkChildContext(data)) return; + if (data.hook_event_name === "SessionEnd" && await handOff(input)) return; const sessionId = data.session_id || data.sessionId || data.conversation_id || "unknown"; const transcriptPrompts = extractTranscriptPrompts(data); if (transcriptPrompts.length > 0) { diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs old mode 100755 new mode 100644 index 73c5038b6c..045957aa23 --- a/plugin/scripts/session-start.mjs +++ b/plugin/scripts/session-start.mjs @@ -27,7 +27,7 @@ function unquote(value) { const hash = value.indexOf(" #"); return hash === -1 ? value : value.slice(0, hash).trim(); } -function readEnvFileSecret() { +function readEnvFileValue(name) { let content; try { content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8"); @@ -41,11 +41,14 @@ function readEnvFileSecret() { if (trimmed.startsWith("#")) continue; const eq = trimmed.indexOf("="); if (eq === -1) continue; - if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== SECRET_KEY) continue; - found = usable(unquote(trimmed.slice(eq + 1).trim())); + if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== name) continue; + found = unquote(trimmed.slice(eq + 1).trim()); } return found; } +function readEnvFileSecret() { + return usable(readEnvFileValue(SECRET_KEY)); +} function readSecretFile(path) { try { return usable(readFileSync(path, "utf-8")); diff --git a/plugin/scripts/subagent-stop.mjs b/plugin/scripts/subagent-stop.mjs old mode 100755 new mode 100644 index a01bff6cd0..66c330136d --- a/plugin/scripts/subagent-stop.mjs +++ b/plugin/scripts/subagent-stop.mjs @@ -3,12 +3,72 @@ import { execSync } from "node:child_process"; import { realpathSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { captureObservation, isDrainChild, runDrainChild, stripPrivateData, withEventId } from "./_capture.mjs"; +//#region src/functions/privacy.ts +const PRIVATE_TAG_TOKEN_RE = /)[^>]*>|<\/private\s*>/gi; +function redactPrivateBlocks(input) { + const tokens = new RegExp(PRIVATE_TAG_TOKEN_RE.source, PRIVATE_TAG_TOKEN_RE.flags); + let out = ""; + let cursor = 0; + let depth = 0; + for (let match = tokens.exec(input); match; match = tokens.exec(input)) { + const closing = match[0].startsWith(" 0) return `${out}[REDACTED]`; + return out + input.slice(cursor); +} +const SECRET_PATTERN_SOURCES = [ + /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi, + /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi, + /(?]*:[^\s/?#@"'<>]+@/gi; +function stripPrivateData$1(input) { + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; + result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); + result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); + for (const source of SECRET_PATTERN_SOURCES) { + const pattern = new RegExp(source.source, source.flags); + result = result.replace(pattern, "[REDACTED_SECRET]"); + } + return result; +} +//#endregion //#region src/hooks/_capture-filter.ts -function truncateText(value, max) { +function cut(value, max) { if (value.length <= max) return value; const end = /[\uD800-\uDBFF]/.test(value[max - 1] ?? "") ? max - 1 : max; return value.slice(0, end); } +function truncateText(value, max) { + if (value.length <= max) return value; + return cut(stripPrivateData$1(value), max); +} //#endregion //#region src/hooks/_project.ts function resolveProject(cwd) { diff --git a/plugin/scripts/task-completed.mjs b/plugin/scripts/task-completed.mjs old mode 100755 new mode 100644 index d92bb7240e..63bd03d239 --- a/plugin/scripts/task-completed.mjs +++ b/plugin/scripts/task-completed.mjs @@ -3,12 +3,72 @@ import { execSync } from "node:child_process"; import { realpathSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { captureObservation, isDrainChild, runDrainChild, withEventId } from "./_capture.mjs"; +//#region src/functions/privacy.ts +const PRIVATE_TAG_TOKEN_RE = /)[^>]*>|<\/private\s*>/gi; +function redactPrivateBlocks(input) { + const tokens = new RegExp(PRIVATE_TAG_TOKEN_RE.source, PRIVATE_TAG_TOKEN_RE.flags); + let out = ""; + let cursor = 0; + let depth = 0; + for (let match = tokens.exec(input); match; match = tokens.exec(input)) { + const closing = match[0].startsWith(" 0) return `${out}[REDACTED]`; + return out + input.slice(cursor); +} +const SECRET_PATTERN_SOURCES = [ + /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi, + /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi, + /(?]*:[^\s/?#@"'<>]+@/gi; +function stripPrivateData(input) { + return stripSecrets(redactPrivateBlocks(input)); +} +function stripSecrets(input) { + let result = input; + result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]"); + result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@"); + for (const source of SECRET_PATTERN_SOURCES) { + const pattern = new RegExp(source.source, source.flags); + result = result.replace(pattern, "[REDACTED_SECRET]"); + } + return result; +} +//#endregion //#region src/hooks/_capture-filter.ts -function truncateText(value, max) { +function cut(value, max) { if (value.length <= max) return value; const end = /[\uD800-\uDBFF]/.test(value[max - 1] ?? "") ? max - 1 : max; return value.slice(0, end); } +function truncateText(value, max) { + if (value.length <= max) return value; + return cut(stripPrivateData(value), max); +} //#endregion //#region src/hooks/_project.ts function resolveProject(cwd) { From 8ecd207a7fc88073f78140a167ec731f80ae68f5 Mon Sep 17 00:00:00 2001 From: Daniel-Hong Date: Fri, 13 Nov 2026 19:07:14 +0900 Subject: [PATCH 19/23] build(hooks): retain executable mode on 8 regenerated hook scripts CI Node22 rebuild identifies mode-only differences; align Git file modes with generated executable hooks. Preserve exact verified output bytes and explicit Codex compatibility manifest. --- plugin/scripts/post-tool-failure.mjs | 0 plugin/scripts/post-tool-use.mjs | 0 plugin/scripts/pre-compact.mjs | 0 plugin/scripts/pre-tool-use.mjs | 0 plugin/scripts/session-end.mjs | 0 plugin/scripts/session-start.mjs | 0 plugin/scripts/subagent-stop.mjs | 0 plugin/scripts/task-completed.mjs | 0 8 files changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 plugin/scripts/post-tool-failure.mjs mode change 100644 => 100755 plugin/scripts/post-tool-use.mjs mode change 100644 => 100755 plugin/scripts/pre-compact.mjs mode change 100644 => 100755 plugin/scripts/pre-tool-use.mjs mode change 100644 => 100755 plugin/scripts/session-end.mjs mode change 100644 => 100755 plugin/scripts/session-start.mjs mode change 100644 => 100755 plugin/scripts/subagent-stop.mjs mode change 100644 => 100755 plugin/scripts/task-completed.mjs diff --git a/plugin/scripts/post-tool-failure.mjs b/plugin/scripts/post-tool-failure.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/post-tool-use.mjs b/plugin/scripts/post-tool-use.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/pre-tool-use.mjs b/plugin/scripts/pre-tool-use.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/session-end.mjs b/plugin/scripts/session-end.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/subagent-stop.mjs b/plugin/scripts/subagent-stop.mjs old mode 100644 new mode 100755 diff --git a/plugin/scripts/task-completed.mjs b/plugin/scripts/task-completed.mjs old mode 100644 new mode 100755 From 73b86f3aa93e5e81737f0323cdfd7800f8b62c72 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 14 Nov 2026 11:34:47 +0900 Subject: [PATCH 20/23] test: make Ubuntu CI fixtures portable and deadline-aware --- CHANGELOG.md | 2 + .../UPSTREAM-0.9.33-INTEGRATION.md | 9 +++ src/ws.d.ts | 1 + test/file-writer-lease.test.ts | 2 +- test/helpers/sdk-deadline-worker.mjs | 7 +- test/hook-capture-admission.test.ts | 2 +- test/native-sdk-v2.test.ts | 2 +- test/sdk-capture-deadline.test.ts | 48 ++++++++++++-- test/sdk-v2-transport-safety.test.ts | 2 +- test/viewer-metrics-browser.test.ts | 64 ++++++++++++++++--- 10 files changed, 117 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18256ad515..cf2317589c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,8 @@ ## [Unreleased] +- Make Ubuntu CI subprocess fixtures use the active Node executable. Validate finite capture deadlines under contention without weakening exact-once ACK/original preservation checks, and wait for real browser fixture completion instead of a fixed virtual-time DOM dump. Test-only changes; no operating service changes. + ## [0.9.33-daniel.72] — 2026-11-13 - Reobserve transient State/engine socket ownership snapshot gaps at most three times without replaying RPCs or accepting a changed epoch/foreign owner. Classify remaining proven local pre-dispatch admission failures without latching uncertain writes, and retain bounded first/latest failure diagnostics without payloads. Preserve previous uncertainty and source data; see the operating follow-up in the integration note. diff --git a/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md b/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md index 2fe5c4ea39..7be29fb212 100644 --- a/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md +++ b/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md @@ -144,3 +144,12 @@ The .72 fix makes at most three complete State observations for only missing-con The owner applied .72 through the explicit sealed-not-clean recovery path. The .71 failure count of one and its uncertain outcome were preserved in the recovery receipt; no clean marker was fabricated and no original was removed. The original 10,000 retained hashes remain identical (10,001 total after the accepted synthetic event). Supported manual resume returned running with no holds. Final bounded acceptance: seven health samples from 02:01:30 to 02:04:46 UTC were healthy/running with no holds, mutation failures or SDK failures; first/latest mutation errors were null, while SDK completed work increased from 12 to 43. A new SDKv1 synthetic capture returned 201 stored, scoped search returned 200 with its exact ID in 48.993 seconds, and duplicate submission returned 200 with the same ID; independent disk inspection found exactly one record. This certifies the tested Ubuntu capture/search/dedup and bounded stability, not unlimited future stability or legacy-backlog resolution. The earlier .71 acceptance and subsequent publication hold above remain historical evidence, not overwritten success claims. Final status HTTP 200 reported 38,034 observations (38,032 original plus two accepted synthetic probes), 61 memories and 431 sessions, missing observations 0, BM25 complete, vector backfill pending 0/idle. Remaining informational codes were `audit-legacy-frozen` and `capture-check-unavailable`; these are not silently treated as completed legacy cleanup. + + +### PR CI portability and fixture timing follow-up (2026-11-14) + +- The first published candidate CI failed 26 tests: 24 subprocess fixtures assumed `/usr/bin/node`, one capture test assumed six contending processes and 6,000 retained files always finish inside three seconds, and one Chromium DOM dump lacked its fixture marker. The browser failure did not retain enough evidence to identify the missing document conclusively; it is not evidence of a production Viewer regression. +- Tests now use the active Node executable. Capture checks retain the original three-second budget, inspect conservative no-send outcomes and on-disk state, and require eventual exact ACK/completed originals with exactly one POST per event. Only proven never-sent cases retry after contention ends; uncertain or sending states still fail. A deliberate lock overrun covers the exhausted-budget path deterministically. +- Browser checks wait for the expected fixture document and its completed proof, with bounded CDP requests and preserved UI assertions, instead of assuming a fixed virtual-time dump is ready. +- These changes affect test fixtures only. Operating `.72`, data, services and configured deadlines are unchanged. Final aggregate and remote CI results are reported for their exact commit; focused results alone do not establish a green PR. +- Final local verification: full isolated-HOME fork-pool suite passed 7,045 tests (14 intentionally skipped), 590 files passed (5 skipped), no failures. Build, skill generation/check, documentation synchronization/check, Codex artifact generation with no generated drift, and eval TypeScript contract passed. Remote CI remains a separate gate. diff --git a/src/ws.d.ts b/src/ws.d.ts index a3d842ed32..420d5bd5dc 100644 --- a/src/ws.d.ts +++ b/src/ws.d.ts @@ -3,6 +3,7 @@ declare module "ws" { import type { IncomingMessage } from "node:http"; import type { Duplex } from "node:stream"; export default class WebSocket extends EventEmitter { + constructor(address:string|URL,options?:{handshakeTimeout?:number}); static readonly OPEN:number; readonly readyState:number; readonly bufferedAmount:number; diff --git a/test/file-writer-lease.test.ts b/test/file-writer-lease.test.ts index b9aa974706..7b6bcf285d 100644 --- a/test/file-writer-lease.test.ts +++ b/test/file-writer-lease.test.ts @@ -19,7 +19,7 @@ describe('native file writer ownership',()=>{ it('rejects another process and releases only when the owning process exits',async()=>{ const m=await load(),d=dir();expect(typeof m.acquireFileWriterLease).toBe('function'); const ready=join(d,'ready'); - const child=spawn('/usr/bin/node',['--input-type=module','-e',`import {acquireFileWriterLease} from ${JSON.stringify('file://'+modulePath)};import {writeFileSync} from 'node:fs';const lease=acquireFileWriterLease(${JSON.stringify(d)});writeFileSync(${JSON.stringify(ready)},'ready');setInterval(()=>{},1000);`],{stdio:'ignore',env:{PATH:'/usr/bin:/bin',HOME:d}}); + const child=spawn(process.execPath,['--input-type=module','-e',`import {acquireFileWriterLease} from ${JSON.stringify('file://'+modulePath)};import {writeFileSync} from 'node:fs';const lease=acquireFileWriterLease(${JSON.stringify(d)});writeFileSync(${JSON.stringify(ready)},'ready');setInterval(()=>{},1000);`],{stdio:'ignore',env:{PATH:'/usr/bin:/bin',HOME:d}}); try{ const until=Date.now()+1500;while(!existsSync(ready)&&child.exitCode===null&&Date.now()setTimeout(r,10)); expect(existsSync(ready)).toBe(true); diff --git a/test/helpers/sdk-deadline-worker.mjs b/test/helpers/sdk-deadline-worker.mjs index 0ac952f9f0..ffda5f4d3f 100644 --- a/test/helpers/sdk-deadline-worker.mjs +++ b/test/helpers/sdk-deadline-worker.mjs @@ -9,12 +9,13 @@ if(process.env.MODE==='holder'){ const lock=spawnSync('/usr/bin/flock',['--exclusive','--nonblock','3'],{stdio:['ignore','ignore','ignore',fd]}); if(lock.status!==0)throw Error('FIXTURE_LOCK_FAILED'); process.send({ready:true}); - process.once('message',()=>setTimeout(()=>{closeSync(fd);process.disconnect();},350)); + process.once('message',message=>setTimeout(()=>{closeSync(fd);process.disconnect();},message.holdMs)); }else{ const {deliverSdkCaptureV2}=await import(pathToFileURL(process.env.FIXTURE_MODULE)); process.send({ready:true}); process.once('message',async()=>{ - const result=await deliverSdkCaptureV2(process.env.FIXTURE_TARGET,{eventId:'multiprocess-'+process.env.FIXTURE_INDEX},async body=>({status:201,body:{eventId:body.eventId,completion:'sdk',completed:true,durable:false}}),{dir:process.env.FIXTURE_DIR,deadline:performance.now()+3000}); - process.send({result});process.disconnect(); + const started=performance.now(),phases=[];let posts=0;process.send({started:true}); + const result=await deliverSdkCaptureV2(process.env.FIXTURE_TARGET,{eventId:'multiprocess-'+process.env.FIXTURE_INDEX},async body=>{posts++;return {status:201,body:{eventId:body.eventId,completion:'sdk',completed:true,durable:false}};},{dir:process.env.FIXTURE_DIR,deadline:started+3000,storeOptions:{onPhase:phase=>phases.push({phase,elapsedMs:performance.now()-started})}}); + process.send({result:{...result,posts,elapsedMs:performance.now()-started,phases}});process.disconnect(); }); } diff --git a/test/hook-capture-admission.test.ts b/test/hook-capture-admission.test.ts index 8219ea4c71..ec3506b06e 100644 --- a/test/hook-capture-admission.test.ts +++ b/test/hook-capture-admission.test.ts @@ -11,7 +11,7 @@ async function runHook(name:string,body:Record,extra:Record{if(process.env.SYNTHETIC_FETCH_STALL==='1'){setTimeout(()=>{},10000);return new Promise(()=>{})}const b=JSON.parse(options.body||'{}');paths.push(new URL(url).pathname);return new Response(JSON.stringify({eventId:b.eventId,status:'accepted',completion:'sdk',completed:true,durable:false}),{status:201})};process.on('exit',()=>writeFileSync(process.env.SYNTHETIC_FETCH_LOG,JSON.stringify(paths)));`); const env={PATH:'/usr/bin:/bin',HOME:root,TMPDIR:root,AGENTMEMORY_URL:'http://127.0.0.1:63000',AGENTMEMORY_SECRET:'synthetic-only',AGENTMEMORY_CAPTURE_SPOOL_DIR:join(root,'spool'),SYNTHETIC_FETCH_LOG:log,...extra}; - const child=spawn('/usr/bin/node',['--max-old-space-size=192','--import',preload,resolve('dist/hooks/'+name+'.mjs')],{cwd:root,env,stdio:['pipe','pipe','pipe']}); + const child=spawn(process.execPath,['--max-old-space-size=192','--import',preload,resolve('dist/hooks/'+name+'.mjs')],{cwd:root,env,stdio:['pipe','pipe','pipe']}); let stdout='',stderr='';child.stdout.on('data',d=>stdout+=d);child.stderr.on('data',d=>stderr+=d);child.stdin.on('error',()=>{});child.stdin.end(JSON.stringify(body)); const result=await new Promise<{code:number|null,signal:NodeJS.Signals|null}>((resolve,reject)=>{let uncertain:ReturnType|undefined;const deadline=setTimeout(()=>{child.kill('SIGTERM');uncertain=setTimeout(()=>{retainRoot=true;child.unref();child.stdout.destroy();child.stderr.destroy();reject(new Error('synthetic child unreaped; inspect retained '+root));},2000);},8000);child.once('error',e=>{clearTimeout(deadline);if(uncertain)clearTimeout(uncertain);reject(e)});child.once('close',(code,signal)=>{clearTimeout(deadline);if(uncertain)clearTimeout(uncertain);resolve({code,signal})});}); return {...result,stdout,stderr,paths:existsSync(log)?JSON.parse(readFileSync(log,'utf8')) as string[]:[],startupError:existsSync(log)?'':stderr}; diff --git a/test/native-sdk-v2.test.ts b/test/native-sdk-v2.test.ts index 2707c711e6..33c00e5bc1 100644 --- a/test/native-sdk-v2.test.ts +++ b/test/native-sdk-v2.test.ts @@ -14,7 +14,7 @@ async function run(script:string,input:Record,extra:Record{const b=JSON.parse(options.body||'{}');calls.push({redirect:options.redirect,path:new URL(url).pathname,imageBytes:typeof b.data?.image_data==='string'?Buffer.byteLength(b.data.image_data):0,imageHash:typeof b.data?.image_data==='string'?createHash('sha256').update(b.data.image_data).digest('hex'):null,final:b.final});return new Response(JSON.stringify({eventId:b.eventId,status:'accepted',completion:'sdk',completed:true,durable:false}),{status:201})};process.on('exit',()=>writeFileSync(process.env.SYNTHETIC_FETCH_LOG,JSON.stringify(calls)));`); const env={PATH:'/usr/bin:/bin',HOME:root,TMPDIR:root,AGENTMEMORY_URL:target,AGENTMEMORY_SECRET:'synthetic-only',AGENTMEMORY_SDK_CAPTURE_V2_DIR:join(root,'v2'),AGENTMEMORY_CAPTURE_SPOOL_DIR:join(root,'v1'),SYNTHETIC_FETCH_LOG:log,...extra}; - const child=spawn('/usr/bin/node',['--max-old-space-size=256','--import',preload,...(sourceOnly?['--import',resolve('node_modules/tsx/dist/loader.mjs'),resolve('src/hooks/'+script+'.ts')]:[resolve('dist/hooks/'+script+'.mjs')]),'--agentmemory-sdk-capture-v2'],{cwd:root,env,stdio:['pipe','pipe','pipe']}); + const child=spawn(process.execPath,['--max-old-space-size=256','--import',preload,...(sourceOnly?['--import',resolve('node_modules/tsx/dist/loader.mjs'),resolve('src/hooks/'+script+'.ts')]:[resolve('dist/hooks/'+script+'.mjs')]),'--agentmemory-sdk-capture-v2'],{cwd:root,env,stdio:['pipe','pipe','pipe']}); let stdout='',stderr='';child.stdout.on('data',b=>stdout+=b);child.stderr.on('data',b=>stderr+=b);child.stdin.on('error',()=>{});child.stdin.end(JSON.stringify(input)); const result=await new Promise<{code:number|null,signal:NodeJS.Signals|null}>((resolve,reject)=>{let uncertain:ReturnType|undefined;const deadline=setTimeout(()=>{child.kill('SIGTERM');uncertain=setTimeout(()=>{retainRoot=true;child.unref();child.stdout.destroy();child.stderr.destroy();reject(Error('synthetic child unreaped at '+root))},2000)},10000);child.once('error',e=>{clearTimeout(deadline);if(uncertain)clearTimeout(uncertain);reject(e)});child.once('close',(code,signal)=>{clearTimeout(deadline);if(uncertain)clearTimeout(uncertain);resolve({code,signal})})}); expect(existsSync(log),stderr).toBe(true);return {...result,stdout,stderr,calls:JSON.parse(readFileSync(log,'utf8')) as Array}; diff --git a/test/sdk-capture-deadline.test.ts b/test/sdk-capture-deadline.test.ts index 90d11d07af..98cf075f71 100644 --- a/test/sdk-capture-deadline.test.ts +++ b/test/sdk-capture-deadline.test.ts @@ -90,7 +90,7 @@ it('bounded drain preserves a short shared deadline and the legacy unspecified d expect(result).toMatchObject({attempted:1,delivered:1,remaining:0});expect(posts).toBe(1); }); -for(const processes of [2,6])it(`${processes} real processes wait beyond legacy 150ms and complete against 6000 retained originals`,async()=>{ +for(const [processes,holdMs] of [[2,350],[6,350],[2,3200]])it(`${processes} real processes preserve deadline outcomes after ${holdMs}ms contention against 6000 retained originals`,async()=>{ const home=root(),dir=join(home,'spool'),store=new SdkSpoolV2({dir});await store.usage(); // Synthetic completed trees exercise the actual recursive quota scan. Nothing is read from the host spool. for(let index=0;index<6000;index++){ @@ -101,18 +101,54 @@ for(const processes of [2,6])it(`${processes} real processes wait beyond legacy function child(mode:string,index=0){ const worker=fork(resolve('test/helpers/sdk-deadline-worker.mjs'),[],{execArgv:['--import',resolve('node_modules/tsx/dist/loader.mjs')],env:{PATH:'/usr/bin:/bin',HOME:home,USERPROFILE:home,TMPDIR:home,MODE:mode,FIXTURE_DIR:dir,FIXTURE_TARGET:target,FIXTURE_INDEX:String(index),FIXTURE_MODULE:process.env.SDK_DEADLINE_FIXTURE_MODULE??resolve('src/capture/sdk-delivery-v2.ts')},stdio:['ignore','pipe','pipe','ipc']}); children.push(worker);let result:any; + const started=new Promise(done=>worker.on('message',(m:any)=>{if(m.started)done();})); const ready=new Promise((done,reject)=>{worker.on('message',(m:any)=>{if(m.ready)done();if(m.result)result=m.result;});worker.once('error',reject);}); const exited=new Promise((done,reject)=>{worker.once('exit',code=>code===0?done(result):reject(Error('FIXTURE_CHILD_FAILED')));worker.once('error',reject);}); - return {worker,ready,exited}; + return {worker,ready,started,exited}; } try{ const holder=child('holder');await holder.ready; const senders=Array.from({length:processes},(_,i)=>child('sender',i));await Promise.all(senders.map(x=>x.ready)); - for(const sender of senders)sender.worker.send('go');holder.worker.send('release-after-350ms'); + for(const sender of senders)sender.worker.send('go'); + await Promise.all(senders.map(x=>x.started));holder.worker.send({holdMs}); const results=await Promise.all(senders.map(x=>x.exited));await holder.exited; - console.log(JSON.stringify({syntheticConcurrentCapture:true,processes,results})); - for(const result of results)expect(result).toMatchObject({outcome:'delivered',sourceAcknowledged:true,referenceAcknowledged:true,sdkReplyConfirmed:true}); + console.log(JSON.stringify({syntheticConcurrentCapture:true,processes,holdMs,results})); + // A finite deadline guarantees conservative state, not CI filesystem throughput. + // The explicit overrun case makes STORE_BUSY reproducible without CPU stress. + let published=0; + for(const [index,result] of results.entries()){ + const event='multiprocess-'+index,sourceExists=existsSync(join(dir,'originals',id(event),'manifest.json')),refExists=existsSync(join(dir,'queue',id(event)+'.ref')); + expect(result.elapsedMs).toBeGreaterThan(150); + if(sourceExists)published++; + expect(result.sourceAcknowledged).toBe(sourceExists);expect(result.referenceAcknowledged).toBe(refExists||result.outcome==='delivered'); + if(result.outcome==='delivered'){ + expect(result).toMatchObject({sourceAcknowledged:true,referenceAcknowledged:true,sdkReplyConfirmed:true,posts:1}); + expect(manifest(dir,event).completed).toBe(true);expect(refExists).toBe(false); + }else{ + expect(result.posts).toBe(0);expect(result.sdkReplyConfirmed).not.toBe(true); + if(result.outcome==='spooled')expect(result).toMatchObject({sourceAcknowledged:true,referenceAcknowledged:true}); + else{expect(['held','dropped']).toContain(result.outcome);expect(result.code).toBe('STORE_BUSY');} + if(sourceExists)expect(manifest(dir,event).completed).toBe(false); + if(refExists)expect(ref(dir,event)).toMatchObject({state:'pending',attempts:0,nextAttemptAt:0}); + expect(result.elapsedMs).toBeGreaterThanOrEqual(result.outcome==='spooled'?2250:3000); + } + } + expect(readdirSync(join(dir,'originals'))).toHaveLength(6000+published); + if(holdMs>3000)for(const result of results)expect(result).toMatchObject({outcome:'dropped',code:'STORE_BUSY',posts:0,sourceAcknowledged:false,referenceAcknowledged:false}); + // Only the branches above proved conclusively not-sent may retry. Contention is + // now gone; each gets its own original 3s bound, never a larger runtime limit. + // Unknown dispatch/sending or ACK failures fail above instead of being replayed. + for(const [index,result] of results.entries()){ + if(result.outcome==='delivered')continue; + const retry=child('sender',index);await retry.ready;retry.worker.send('go'); + const resolved=await retry.exited; + expect(resolved).toMatchObject({outcome:'delivered',sourceAcknowledged:true,referenceAcknowledged:true,sdkReplyConfirmed:true,posts:1}); + expect(result.posts+resolved.posts).toBe(1); + } expect(readdirSync(join(dir,'originals'))).toHaveLength(6000+processes); - for(let i=0;ivoid){ async function readBody(req:IncomingMessage){const chunks:Buffer[]=[];for await(const chunk of req)chunks.push(Buffer.from(chunk));return JSON.parse(Buffer.concat(chunks).toString()) as Record;} async function runNative(url:string){ const image='data:image/png;base64,'+'A'.repeat(300*1024); - const child=spawn('/usr/bin/node',['--max-old-space-size=256','--import',resolve('node_modules/tsx/dist/loader.mjs'),resolve('src/hooks/post-tool-use.ts'),'--agentmemory-sdk-capture-v2'],{ + const child=spawn(process.execPath,['--max-old-space-size=256','--import',resolve('node_modules/tsx/dist/loader.mjs'),resolve('src/hooks/post-tool-use.ts'),'--agentmemory-sdk-capture-v2'],{ cwd:root,env:{PATH:'/usr/bin:/bin',HOME:root,TMPDIR:root,AGENTMEMORY_URL:url,AGENTMEMORY_SECRET:'synthetic-only',AGENTMEMORY_SDK_CAPTURE_V2_DIR:join(root,'v2'),AGENTMEMORY_CAPTURE_SPOOL_DIR:join(root,'v1')},stdio:['pipe','pipe','pipe'], }); let stdout='',stderr='';child.stdout.on('data',b=>stdout+=b);child.stderr.on('data',b=>stderr+=b);child.stdin.on('error',()=>{}); diff --git a/test/viewer-metrics-browser.test.ts b/test/viewer-metrics-browser.test.ts index 31461cd7c1..4c39ad5abb 100644 --- a/test/viewer-metrics-browser.test.ts +++ b/test/viewer-metrics-browser.test.ts @@ -1,8 +1,10 @@ -import { spawnSync } from 'node:child_process'; -import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { spawn, spawnSync } from 'node:child_process'; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'; +import { rm } from 'node:fs/promises'; import { join, resolve } from 'node:path'; import { tmpdir } from 'node:os'; import { describe, expect, it } from 'vitest'; +import WebSocket from 'ws'; const source=readFileSync(process.env.METRICS_UI_SOURCE || 'src/viewer/index.html','utf8'); const evidence=process.env.METRICS_UI_EVIDENCE; @@ -15,20 +17,64 @@ var fixtureHealth={status:'healthy',health:{connectionState:'connected'},functio var fixtureReport={status:'ok',headline:'Synthetic metrics fixture',checkedAt:new Date().toISOString(),problems:[],service:{version:'synthetic',ports:{}},provider:{llm:'openai',embeddings:'none'},functions:[fixtureMetric],flags:[],capture:{inbox:{pending:2,retrying:3,dead:4},sinceStart:{},spool:[],policy:{retryIntervalMs:30000,maxAttempts:5}}}; window.fetch=async(url,opts={})=>{requests.push({path:String(url),method:opts.method||'GET'});var path=String(url),payload={};if(path.includes('/viewer/snapshot'))payload={version:'synthetic',health:fixtureHealth.health,report:fixtureReport,functionMetrics:[fixtureMetric],counts:{sessions:1,observations:1},flags:[]};else if(path.includes('/health'))payload=fixtureHealth;else if(path.includes('/background/control'))payload={success:true,control:{status:'running',holds:[],activeOperations:0}};else if(path.includes('/sessions'))payload={sessions:[{id:'synthetic',project:'Synthetic fixture',observationCount:1,summaryProgress:{status:'blocked',pendingCount:1,blockedObservations:{one:{status:'blocked',diagnostics:{category:'output_truncated'}}}},enrichmentProgress:{compress:{status:'current',pendingCount:0},graph:{status:'current',pendingCount:0}}}]};return new Response(JSON.stringify(payload),{status:200,headers:{'Content-Type':'application/json'}});}; window.WebSocket=class{static OPEN=1;static CONNECTING=0;constructor(){this.readyState=1;setTimeout(()=>this.onopen&&this.onopen(),0);}send(){}close(){this.readyState=3;}}; -setTimeout(async()=>{var proof={};try{await loadSnapshot();await loadOperations();setAutoRefresh(false,30);operations.metrics={'mem::summary':{totalCalls:200,failureCount:190,observedAt:'2026-10-22T00:05:00.000Z'}};operations.metricPrevious='${scenario}'==='missing'?{}:{'mem::summary':{totalCalls:'${scenario}'==='reset'?250:195,failureCount:'${scenario}'==='reset'?195:190,observedAt:'2026-10-22T00:01:00.000Z'}};switchTab('${view}');await showTab('${view}');renderTab('${view}');var root=document.getElementById('view-${view}');root.querySelectorAll('details').forEach(e=>e.open=true);var fn=root.querySelector('.metric-fn'),table=fn.closest('table'),row=fn.closest('tr'),cells=Array.from(row.cells);proof.functionWidth=fn.getBoundingClientRect().width;proof.text=root.innerText;proof.metrics=table.innerText;proof.aggregate=Array.from(root.querySelectorAll('.stat-card')).find(e=>e.textContent.includes('누적 실행 시도'))?.innerText;proof.historicalCell=cells[2].innerText;proof.historicalColor=cells[2].style.color;proof.red=getComputedStyle(document.documentElement).getPropertyValue('--red').trim();proof.rateColor=cells.find(e=>e.textContent.trim()==='95%')?.style.color;proof.recentCell=cells.find(e=>e.textContent.includes('실패')&&e.textContent.includes('시도'))?.innerText;proof.attention=document.getElementById('health-attention')?.innerText;proof.errors=fixtureErrors;proof.getOnly=requests.every(r=>r.method==='GET');proof.overflow=root.scrollWidth>root.clientWidth;fn.closest('.card').scrollIntoView({block:'start'});}catch(e){proof.error=String(e.stack||e);}document.getElementById('metrics-proof').textContent=JSON.stringify(proof);},120); +addEventListener('DOMContentLoaded',async()=>{var proof={};try{await loadSnapshot();await loadOperations();setAutoRefresh(false,30);operations.metrics={'mem::summary':{totalCalls:200,failureCount:190,observedAt:'2026-10-22T00:05:00.000Z'}};operations.metricPrevious='${scenario}'==='missing'?{}:{'mem::summary':{totalCalls:'${scenario}'==='reset'?250:195,failureCount:'${scenario}'==='reset'?195:190,observedAt:'2026-10-22T00:01:00.000Z'}};switchTab('${view}');await showTab('${view}');renderTab('${view}');var root=document.getElementById('view-${view}');root.querySelectorAll('details').forEach(e=>e.open=true);var fn=root.querySelector('.metric-fn'),table=fn.closest('table'),row=fn.closest('tr'),cells=Array.from(row.cells);proof.functionWidth=fn.getBoundingClientRect().width;proof.text=root.innerText;proof.metrics=table.innerText;proof.aggregate=Array.from(root.querySelectorAll('.stat-card')).find(e=>e.textContent.includes('누적 실행 시도'))?.innerText;proof.historicalCell=cells[2].innerText;proof.historicalColor=cells[2].style.color;proof.red=getComputedStyle(document.documentElement).getPropertyValue('--red').trim();proof.rateColor=cells.find(e=>e.textContent.trim()==='95%')?.style.color;proof.recentCell=cells.find(e=>e.textContent.includes('실패')&&e.textContent.includes('시도'))?.innerText;proof.attention=document.getElementById('health-attention')?.innerText;proof.errors=fixtureErrors;proof.getOnly=requests.every(r=>r.method==='GET');proof.overflow=root.scrollWidth>root.clientWidth;fn.closest('.card').scrollIntoView({block:'start'});}catch(e){proof.error=String(e.stack||e);}document.getElementById('metrics-proof').textContent=JSON.stringify(proof);},{once:true}); `; +async function browserProof(dir:string,path:string,width:number,screenshot:string){ + const chrome=spawn('google-chrome',['--headless','--no-sandbox','--disable-gpu','--disable-background-networking','--no-first-run','--remote-debugging-port=0','--remote-debugging-address=127.0.0.1','--user-data-dir='+join(dir,'profile'),'about:blank'],{stdio:['ignore','ignore','pipe']}); + const closed=new Promise(resolve=>chrome.once('close',()=>resolve())); + const waitClosed=(ms:number)=>new Promise(resolve=>{const timer=setTimeout(()=>resolve(false),ms);void closed.then(()=>{clearTimeout(timer);resolve(true);});}); + let stderr='',socket:WebSocket|undefined; + chrome.stderr.on('data',chunk=>{stderr=(stderr+chunk).slice(-2000);}); + const deadline=Date.now()+20000; + const pause=()=>new Promise(resolve=>setTimeout(resolve,25)); + try{ + const portFile=join(dir,'profile','DevToolsActivePort'); + while(!existsSync(portFile)&&chrome.exitCode===null&&Date.now()r.json()); + socket=new WebSocket(target.webSocketDebuggerUrl,{handshakeTimeout:5000}); + await new Promise((resolve,reject)=>{const timer=setTimeout(()=>reject(Error('CDP connection timeout')),5000);socket!.once('open',()=>{clearTimeout(timer);resolve();});socket!.once('error',()=>{clearTimeout(timer);reject(Error('CDP connection failed'));});}); + let seq=0;const pending=new Mapvoid;reject:(error:Error)=>void}>(); + socket.on('close',()=>{for(const request of pending.values())request.reject(Error('CDP connection closed'));pending.clear();}); + socket.on('error',()=>{for(const request of pending.values())request.reject(Error('CDP connection error'));pending.clear();}); + socket.on('message',data=>{const message=JSON.parse(String(data)),request=pending.get(message.id);if(!request)return;pending.delete(message.id);message.error?request.reject(Error(JSON.stringify(message.error))):request.resolve(message.result);}); + const send=(method:string,params:Record={})=>new Promise((resolve,reject)=>{const id=++seq;const timer=setTimeout(()=>{pending.delete(id);reject(Error('CDP command timed out: '+method));},5000);pending.set(id,{resolve:value=>{clearTimeout(timer);resolve(value);},reject:error=>{clearTimeout(timer);reject(error);}});socket!.send(JSON.stringify({id,method,params}));}); + const evaluate=async(expression:string)=>{const result=await send('Runtime.evaluate',{expression,returnByValue:true});if(result.exceptionDetails)throw Error(JSON.stringify(result.exceptionDetails));return result.result.value;}; + await send('Page.enable'); + await send('Emulation.setDeviceMetricsOverride',{width,height:1000,deviceScaleFactor:1,mobile:false}); + const navigation=await send('Page.navigate',{url:'file://'+path});expect(navigation.errorText).toBeUndefined(); + let text=''; + while(Date.now(){ - it.each(cases.flatMap(s=>[1280,390].flatMap(w=>['health','dashboard'].map(v=>[s,w,v]))))('%s at %i/%s',(scenario,width,view)=>{ + it.each(cases.flatMap(s=>[1280,390].flatMap(w=>['health','dashboard'].map(v=>[s,w,v]))))('%s at %i/%s',async(scenario,width,view)=>{ const dir=mkdtempSync(join(tmpdir(),'am-metrics-browser-')); + let retainProfile=false; try{ if(evidence)mkdirSync(evidence,{recursive:true}); const name=`${scenario}-${width}-${view}`,path=join(dir,'fixture.html'); writeFileSync(path,source.replace('',''+fixture(String(scenario),String(view))).replace('','')); - const run=spawnSync('google-chrome',['--headless','--no-sandbox','--disable-gpu','--disable-background-networking','--no-first-run','--user-data-dir='+join(dir,'profile'),'--window-size='+width+',1000','--virtual-time-budget=1100','--screenshot='+(evidence?join(resolve(evidence),name+'.png'):join(dir,'preview.png')),'--dump-dom','file://'+path],{encoding:'utf8',timeout:25000,maxBuffer:3000000}); - expect(run.status,run.stderr.slice(-500)).toBe(0); - const match=run.stdout.match(/
]*>([\s\S]*?)<\/pre>/);expect(match).toBeTruthy();
-      const proof=JSON.parse(match![1].replaceAll('"','"').replaceAll('&','&').replaceAll('<','<').replaceAll('>','>'));
+      const proof=await browserProof(dir,path,Number(width),evidence?join(resolve(evidence),name+'.png'):join(dir,'preview.png'));
       if(evidence)writeFileSync(join(evidence,name+'.json'),JSON.stringify(proof,null,2));
       expect(proof.error).toBeUndefined();expect(proof.functionWidth).toBeGreaterThanOrEqual(120);expect(proof.errors).toEqual([]);expect(proof.getOnly).toBe(true);expect(proof.overflow).toBe(false);expect(proof.historicalCell).toBe('190');expect(proof.historicalColor).not.toBe('var(--red)');expect(proof.rateColor).not.toBe('var(--red)');expect(proof.text).toContain('집계 시작 미확인');expect(proof.metrics).toContain('실행 시도');
       if(scenario==='off'&&view==='dashboard'){expect(proof.aggregate).toContain('200');expect(proof.aggregate).toContain('190');}
@@ -39,6 +85,6 @@ describe.skipIf(spawnSync('google-chrome',['--version'],{encoding:'utf8'}).statu
       if(scenario==='reset')expect(proof.metrics).toContain('집계 기준 변경');
       if(scenario==='invalid')expect(proof.metrics).toContain('서버 관측 집계 확인 불가');
       if(view==='health'){expect(proof.attention).toContain('격리 1건');expect(proof.attention).toContain('격리 4건');expect(proof.attention).toContain('재시도 3건');expect(proof.text).toContain('현재 대기·재시도·격리');expect(proof.text).not.toContain('임베딩: 최근 실패');}
-    }finally{rmSync(dir,{recursive:true,force:true});}
+    }catch(error){retainProfile=(error as {retainProfile?:boolean})?.retainProfile===true;throw error;}finally{if(!retainProfile)await rm(dir,{recursive:true,force:true,maxRetries:10,retryDelay:100});}
   },30000);
 });

From bee90e08aa5991b1fd2f13615d30e29ddafc5df2 Mon Sep 17 00:00:00 2001
From: Codex 
Date: Sat, 14 Nov 2026 11:50:34 +0900
Subject: [PATCH 21/23] test: synchronize browser readiness and preserve
 publication deadline coverage

---
 .../UPSTREAM-0.9.33-INTEGRATION.md            |  2 ++
 test/devtools-port.test.ts                    | 13 ++++++++++
 test/embedding-scoped-publication.test.ts     | 24 +++++++++++++++++--
 test/helpers/devtools-port.ts                 | 16 +++++++++++++
 test/viewer-metrics-browser.test.ts           |  7 +++---
 5 files changed, 56 insertions(+), 6 deletions(-)
 create mode 100644 test/devtools-port.test.ts
 create mode 100644 test/helpers/devtools-port.ts

diff --git a/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md b/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md
index 7be29fb212..d93baee83d 100644
--- a/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md
+++ b/docs/customizations/UPSTREAM-0.9.33-INTEGRATION.md
@@ -153,3 +153,5 @@ Final status HTTP 200 reported 38,034 observations (38,032 original plus two acc
 - Browser checks wait for the expected fixture document and its completed proof, with bounded CDP requests and preserved UI assertions, instead of assuming a fixed virtual-time dump is ready.
 - These changes affect test fixtures only. Operating `.72`, data, services and configured deadlines are unchanged. Final aggregate and remote CI results are reported for their exact commit; focused results alone do not establish a green PR.
 - Final local verification: full isolated-HOME fork-pool suite passed 7,045 tests (14 intentionally skipped), 590 files passed (5 skipped), no failures. Build, skill generation/check, documentation synchronization/check, Codex artifact generation with no generated drift, and eval TypeScript contract passed. Remote CI remains a separate gate.
+- Second CI run passed 7,043 tests and exposed two additional fixture races: a just-created but incomplete Chrome endpoint file could become a default-port-80 request, and an 80ms synthetic filesystem fence could conservatively retain publication retry before the test assumed a committed file existed. Endpoint readiness now validates the complete port/endpoint pair (six deterministic tests). Synthetic successful I/O uses a two-second test budget, while a separate injected slow-read regression keeps the 80ms failure path and verifies retry retention, no committed publication and single inference. Runtime budgets remain unchanged.
+- After both race fixes, the final isolated full suite passed 7,052 tests (14 skipped), 591 files passed (5 skipped), no failures; all preceding build/generation/documentation/skills/eval checks passed with no generated drift.
diff --git a/test/devtools-port.test.ts b/test/devtools-port.test.ts
new file mode 100644
index 0000000000..dda14078e1
--- /dev/null
+++ b/test/devtools-port.test.ts
@@ -0,0 +1,13 @@
+import {it,expect} from 'vitest';
+import {waitForDevToolsPort} from './helpers/devtools-port.js';
+const endpoint='42093\n/devtools/browser/11111111-1111-4111-8111-111111111111';
+it('waits through absent, empty, partial port and incomplete endpoint publication',async()=>{
+ let now=0,reads=0;const rows=[null,'','42','42093','42093\n/devtools/browser/',endpoint];
+ const port=await waitForDevToolsPort('unused',100,()=>true,{clock:()=>now,pause:async()=>{now++;},read:()=>{const row=rows[reads++];if(row===null)throw Object.assign(Error('absent'),{code:'ENOENT'});return row!;}});
+ expect(port).toBe(42093);expect(reads).toBe(6);expect(now).toBe(5);
+});
+it.each(['0','65536','junk'])('rejects invalid port %s until bounded deadline',async port=>{
+ let now=0;await expect(waitForDevToolsPort('unused',3,()=>true,{clock:()=>now,pause:async()=>{now++;},read:()=>endpoint.replace('42093',port)})).rejects.toThrow('deadline');expect(now).toBe(3);
+});
+it('fails on child exit without accepting stale endpoint contents',async()=>{await expect(waitForDevToolsPort('unused',100,()=>false,{clock:()=>0,read:()=>endpoint})).rejects.toThrow('exited');});
+it('propagates read permissions failure rather than retrying it',async()=>{await expect(waitForDevToolsPort('unused',100,()=>true,{clock:()=>0,read:()=>{throw Object.assign(Error('denied'),{code:'EACCES'});}})).rejects.toThrow('denied');});
diff --git a/test/embedding-scoped-publication.test.ts b/test/embedding-scoped-publication.test.ts
index 05eec11b05..7fb80a3f40 100644
--- a/test/embedding-scoped-publication.test.ts
+++ b/test/embedding-scoped-publication.test.ts
@@ -12,7 +12,7 @@ import { registerEmbeddingRecovery, EMBEDDING_RETRY_NAMESPACE as RETRY, EMBEDDIN
 
 vi.mock('../src/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
 const fixtures: ReturnType[] = [];
-function fixture() {
+function fixture(timeoutMs = 2000) {
   const directory = mkdtempSync(join(tmpdir(), 'scoped-vector-publication-'));
   const kv = mockKV(), index = new VectorIndex();
   const blocked = new Set();
@@ -23,7 +23,9 @@ function fixture() {
   const set = kv.set, remove = kv.delete;
   kv.set = async (scope, key, value) => { const result = await set(scope, key, value); flush(scope); changed?.(scope, key); return result; };
   kv.delete = async (scope, key) => { await remove(scope, key); flush(scope); changed?.(scope, key); };
-  Object.assign(kv, { backend: 'file', durability: createStateDurabilityFence({ storePath: directory, timeoutMs: 80, pollIntervalMs: 5 }) });
+  // These tests certify real async filesystem I/O, not 80ms CI throughput.
+  // Injected mismatch tests still require the fence to expire without publishing.
+  Object.assign(kv, { backend: 'file', durability: createStateDurabilityFence({ storePath: directory, timeoutMs, pollIntervalMs: 5 }) });
   const persistence = new IndexPersistence(kv as never, index); persistence.stop();
   let clock = 0;
   const provider = { dimensions: 2, embed: vi.fn(async () => new Float32Array([1, 0])) };
@@ -116,6 +118,8 @@ it('keeps retry until the committed fingerprint is on disk and retries publicati
  const f=fixture();await f.kv.set(KV.observations('s'),item.id,{id:item.id,title:'canonical'});f.blocked.add(COMMITTED);
  await f.recovery.add(item);await f.recovery.drain();expect(await f.kv.get(RETRY,item.id)).toBeTruthy();
  f.blocked.clear();f.advance();await f.recovery.pump();await f.recovery.drain();
+ expect(await f.kv.get(RETRY,item.id)).toBeNull();
+ expect(await f.kv.get(COMMITTED,item.id)).toBeTruthy();
  expect(f.disk(COMMITTED)[item.id]).toBeTruthy();expect(f.disk(RETRY)[item.id]).toBeUndefined();expect(f.provider.embed).toHaveBeenCalledOnce();
 });
 
@@ -181,3 +185,19 @@ it('bounds observed publication history and reports evicted identities as unknow
     expect(JSON.stringify(worker.snapshot())).not.toContain('proof_');
   }finally{worker.stop();await worker.drain();}
 });
+
+
+it('retains retry without a committed file when an earlier vector read exceeds its finite budget', async () => {
+  const f = fixture(80);
+  await f.kv.set(KV.observations('s'), item.id, { id: item.id, title: 'canonical' });
+  const get = f.kv.get;
+  f.kv.get = async (scope, key) => {
+    if (scope === vectorBucketScope(0)) await new Promise(resolve => setTimeout(resolve, 120));
+    return get(scope, key);
+  };
+  await f.recovery.add(item); await f.recovery.drain();
+  expect(await get(RETRY, item.id)).toMatchObject({ attempts: 1, errorCode: 'VECTOR_PUBLICATION_UNVERIFIED' });
+  expect(await get(COMMITTED, item.id)).toBeNull();
+  expect(() => f.disk(COMMITTED)).toThrow(/ENOENT/);
+  expect(f.provider.embed).toHaveBeenCalledOnce();
+});
diff --git a/test/helpers/devtools-port.ts b/test/helpers/devtools-port.ts
new file mode 100644
index 0000000000..08523d9b11
--- /dev/null
+++ b/test/helpers/devtools-port.ts
@@ -0,0 +1,16 @@
+import {readFileSync} from 'node:fs';
+
+export async function waitForDevToolsPort(path:string,deadline:number,alive:()=>boolean,options:{read?:()=>string;clock?:()=>number;pause?:()=>Promise}={}):Promise{
+  const read=options.read??(()=>readFileSync(path,'utf8'));
+  const clock=options.clock??Date.now;
+  const pause=options.pause??(()=>new Promise(resolve=>setTimeout(resolve,25)));
+  while(clock()new Promise(resolve=>setTimeout(resolve,25));
   try{
     const portFile=join(dir,'profile','DevToolsActivePort');
-    while(!existsSync(portFile)&&chrome.exitCode===null&&Date.now()chrome.exitCode===null&&chrome.signalCode===null).catch(error=>{throw Error(String(error)+'; '+stderr);});
     const target=await fetch(`http://127.0.0.1:${port}/json/new?about:blank`,{method:'PUT',signal:AbortSignal.timeout(5000)}).then(r=>r.json());
     socket=new WebSocket(target.webSocketDebuggerUrl,{handshakeTimeout:5000});
     await new Promise((resolve,reject)=>{const timer=setTimeout(()=>reject(Error('CDP connection timeout')),5000);socket!.once('open',()=>{clearTimeout(timer);resolve();});socket!.once('error',()=>{clearTimeout(timer);reject(Error('CDP connection failed'));});});

From 01d9a551ef5ec0a3d8f584adc77adb0e8f22abc9 Mon Sep 17 00:00:00 2001
From: Codex 
Date: Sat, 14 Nov 2026 12:19:35 +0900
Subject: [PATCH 22/23] fix: preserve bounded SDK queue transitions on ext4

---
 .cursor-plugin/plugin.json                    |  2 +-
 CHANGELOG.md                                  |  3 +
 .../SDK-SPOOL-TRANSITION-WORKSPACE.md         | 13 ++++
 integrations/hermes/plugin.yaml               |  2 +-
 integrations/omp/package.json                 |  2 +-
 integrations/openclaw/openclaw.plugin.json    |  2 +-
 integrations/openclaw/package.json            |  2 +-
 integrations/openclaw/plugin.yaml             |  2 +-
 package.json                                  |  2 +-
 packages/mcp/package.json                     |  4 +-
 plugin/.claude-plugin/plugin.json             |  2 +-
 plugin/.codex-plugin/plugin.json              |  2 +-
 plugin/.devin-plugin/plugin.json              |  4 +-
 plugin/opencode/plugin.json                   |  2 +-
 plugin/plugin.json                            |  2 +-
 plugin/scripts/_capture.mjs                   | 25 ++++++-
 plugin/scripts/codex-compat/_capture.mjs      | 25 ++++++-
 plugin/scripts/codex-compat/manifest.json     |  2 +-
 scripts/docs-sync.state.json                  |  2 +-
 src/capture/sdk-spool-v2.ts                   | 25 ++++++-
 src/functions/export-import.ts                |  2 +-
 src/types.ts                                  |  2 +-
 src/version.ts                                |  2 +-
 test/diagnostics.test.ts                      | 13 +++-
 test/sdk-spool-progress.test.ts               | 74 +++++++++++++++++--
 test/sdk-spool-v2.test.ts                     |  4 +-
 26 files changed, 182 insertions(+), 40 deletions(-)
 create mode 100644 docs/customizations/SDK-SPOOL-TRANSITION-WORKSPACE.md

diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 1cca697346..b46de0240c 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs entirely on your machine.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf2317589c..27f72c74d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@
 
 ## [Unreleased]
 
+## [0.9.33-daniel.73] — 2026-11-14
+- Stage existing SDK capture queue reference replacements in a private, quota-counted queue workspace, avoiding permanent ext4 directory growth from random temporary names in large queues. Preserve the existing 5 MiB admission and 8 KiB transition budgets, crash files, source originals, and conservative refusal when legacy bootstrap cannot fit. Source fix only; installed services are unchanged. See `docs/customizations/SDK-SPOOL-TRANSITION-WORKSPACE.md`.
 - Make Ubuntu CI subprocess fixtures use the active Node executable. Validate finite capture deadlines under contention without weakening exact-once ACK/original preservation checks, and wait for real browser fixture completion instead of a fixed virtual-time DOM dump. Test-only changes; no operating service changes.
 
 ## [0.9.33-daniel.72] — 2026-11-13
@@ -688,6 +690,7 @@ Wave release closing several breaking regressions reported against v0.9.26, plus
 - `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately.
 - `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked.
 
+[0.9.33-daniel.73]: https://github.com/rohitg00/agentmemory/compare/v0.9.33-daniel.72...v0.9.33-daniel.73
 [0.9.33-daniel.72]: https://github.com/rohitg00/agentmemory/compare/v0.9.33-daniel.71...v0.9.33-daniel.72
 [0.9.33-daniel.71]: https://github.com/rohitg00/agentmemory/compare/v0.9.33-daniel.70...v0.9.33-daniel.71
 [0.9.33-daniel.70]: https://github.com/rohitg00/agentmemory/compare/v0.9.33-daniel.69...v0.9.33-daniel.70
diff --git a/docs/customizations/SDK-SPOOL-TRANSITION-WORKSPACE.md b/docs/customizations/SDK-SPOOL-TRANSITION-WORKSPACE.md
new file mode 100644
index 0000000000..62a0659a9f
--- /dev/null
+++ b/docs/customizations/SDK-SPOOL-TRANSITION-WORKSPACE.md
@@ -0,0 +1,13 @@
+# SDK queue transition workspace
+
+CI reproduced a real ext4 boundary defect: a queue initially charged at 5,242,880 bytes grew by 4,096 directory bytes after random temporary-file insertion/rename. A later hold correctly refused its reservation, stranding otherwise valid transitions. Local `/tmp` is tmpfs and did not exhibit that allocation pattern.
+
+Existing-reference replacements now stage one file inside `queue/.transitions`, then rename over the existing reference and fsync both directories. Empty stores prepare this workspace under the existing lease before admission; its directory and any contents count recursively toward queue usage. New admission remains unchanged. The 5 MiB admission limit and additional 8 KiB transition reservation are unchanged. There is no automatic cleanup, overwrite of crash evidence, source deletion, or quota increase.
+
+A legacy store bootstraps the workspace only if the directory and possible parent growth fit the same reserve, then checks the actual resulting usage before staging. Some already-full or over-limit legacy layouts cannot bootstrap safely and still return `QUEUE_FULL`. This patch does not promise progress under impossible space pressure. A nonempty workspace or unsafe/symlinked directory is preserved and rejected. Existing clients safely ignore the non-ref directory during listing and include it in recursive accounting; their own old transition algorithm is not fixed by sharing the new workspace.
+
+Tests preserve the exact byte-saturated transition→retry→hold→explicit verified resend→two ACKs→new admission sequence and retained originals. Portable successful fixtures use 1,200 references plus filler rather than assume 1,240 references fit every ext4 directory layout; a separate 1,240-reference over-limit case requires unchanged refusal and preservation. Actual staged peak, crash workspace, symlink, bootstrap pressure and tmpfs/ext4 behavior are covered. No operating service or installed hook is changed by this source patch.
+
+Upstream replacement criterion: equivalent atomic replacement, recursive accounting, crash preservation, exact byte-boundary and ext4 regressions pass. Production activation requires a separately verified package/client rollout.
+
+Candidate `0.9.33-daniel.73` is source-only. The same runtime change passed the full isolated fork-pool suite: 7,058 tests passed, 14 skipped, zero failures. Version-only generation then passed final build, skills/documentation checks, Codex artifact generation and eval TypeScript verification. Focused spool tests passed 72/72 on tmpfs and 12/12 boundary tests on ext4; prior-client accounting/listing/lease compatibility was verified. Installed operating `.72` and client hooks have not been replaced. Remote CI is a separate gate.
diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml
index 345281b25f..1b8e55890d 100644
--- a/integrations/hermes/plugin.yaml
+++ b/integrations/hermes/plugin.yaml
@@ -1,5 +1,5 @@
 name: agentmemory
-version: 0.9.33-daniel.72
+version: 0.9.33-daniel.73
 description: "Persistent memory for Hermes Agent with profile-scoped capture, recall, and native memory tools."
 author: "Rohit Ghumare"
 homepage: "https://github.com/rohitg00/agentmemory"
diff --git a/integrations/omp/package.json b/integrations/omp/package.json
index 1abc392a57..96503114a8 100644
--- a/integrations/omp/package.json
+++ b/integrations/omp/package.json
@@ -2,7 +2,7 @@
   "name": "agentmemory-omp-extension",
   "private": true,
   "type": "module",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "omp": {
     "name": "agentmemory",
     "description": "Persistent cross-session memory for omp \u2014 captures sessions, tools, approvals, and compaction; injects smart-search recall.",
diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json
index 775b95bdc4..2a725d1245 100644
--- a/integrations/openclaw/openclaw.plugin.json
+++ b/integrations/openclaw/openclaw.plugin.json
@@ -3,7 +3,7 @@
   "kind": "memory",
   "name": "agentmemory",
   "description": "Persistent cross-session memory for OpenClaw via agentmemory.",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json
index 5433c97976..c8d172bd41 100644
--- a/integrations/openclaw/package.json
+++ b/integrations/openclaw/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "type": "module",
   "openclaw": {
     "extensions": [
diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml
index 1e103c2335..b02e89e7e9 100644
--- a/integrations/openclaw/plugin.yaml
+++ b/integrations/openclaw/plugin.yaml
@@ -1,5 +1,5 @@
 name: agentmemory
-version: 0.9.33-daniel.72
+version: 0.9.33-daniel.73
 description: "Persistent cross-session memory for OpenClaw via agentmemory."
 author: "Rohit Ghumare"
 homepage: "https://github.com/rohitg00/agentmemory"
diff --git a/package.json b/package.json
index 05296d53c7..6f3406a070 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentmemory/agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives",
   "type": "module",
   "main": "dist/index.mjs",
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
index 837c62f17c..10fcad23ba 100644
--- a/packages/mcp/package.json
+++ b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentmemory/mcp",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   "homepage": "https://github.com/rohitg00/agentmemory#readme",
   "bugs": "https://github.com/rohitg00/agentmemory/issues",
   "dependencies": {
-    "@agentmemory/agentmemory": "0.9.33-daniel.72"
+    "@agentmemory/agentmemory": "0.9.33-daniel.73"
   },
   "publishConfig": {
     "access": "public",
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
index 02b5b629c1..c4c91bb45e 100644
--- a/plugin/.claude-plugin/plugin.json
+++ b/plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json
index 237743eeef..b69f03b19f 100644
--- a/plugin/.codex-plugin/plugin.json
+++ b/plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 55 MCP tools and 17 skills. Optional capture through 6 Codex hooks.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/.devin-plugin/plugin.json b/plugin/.devin-plugin/plugin.json
index 683b7dfd6a..7d25963140 100644
--- a/plugin/.devin-plugin/plugin.json
+++ b/plugin/.devin-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "agentmemory",
   "displayName": "agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Persistent memory for Devin CLI and Devin Desktop. Captures every session automatically, recalls with hybrid BM25 + vector + graph search, and exposes 55 memory tools over MCP. Keyless by default, runs on your machine. Not supported in cloud sessions.",
   "logo": "assets/icon.svg",
   "author": {
@@ -23,7 +23,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@agentmemory/mcp@0.9.33-daniel.72"
+        "@agentmemory/mcp@0.9.33-daniel.73"
       ],
       "env": {
         "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}"
diff --git a/plugin/opencode/plugin.json b/plugin/opencode/plugin.json
index 4de274ce62..6d7e6595c9 100644
--- a/plugin/opencode/plugin.json
+++ b/plugin/opencode/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory-capture",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "OpenCode plugin for agentmemory — full Claude Code hook parity: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool lifecycle (ToolPart states with timing), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline, permissions, task tracking (w/ priority), commands, config & model tracking. 22 hooks, 2 slash commands.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/plugin.json b/plugin/plugin.json
index 777a1b4f9c..2cc3e3f815 100644
--- a/plugin/plugin.json
+++ b/plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 55 MCP tools, 17 skills, real-time viewer.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/scripts/_capture.mjs b/plugin/scripts/_capture.mjs
index 6c3b3156f8..88443c9783 100644
--- a/plugin/scripts/_capture.mjs
+++ b/plugin/scripts/_capture.mjs
@@ -142,7 +142,7 @@ function limit(value, maximum) {
 /** Linux-only durable source storage. The lock covers all targets and every quota decision.
 * Source/staging files are never reclaimed. Disk charges are conservative logical bytes,
 * rounded to 4 KiB and at least stat.blocks*512; they are not filesystem hard quotas.
-* The queue includes a 4 KiB lease plus queue/root directory charges (12 KiB minimum).
+* The queue includes a 4 KiB lease plus queue/root/workspace directory charges (16 KiB for initialized stores).
 * Writes additionally reserve a parent-directory block, and 256 bytes per new chunk-directory entry.
 * Admission cannot consume transition workspace: existing refs may use an additional 8 KiB,
 * and completed manifests an additional 68 KiB. Preserved crash temporaries count toward both.
@@ -152,6 +152,7 @@ var SdkSpoolV2 = class {
 	originals;
 	queue;
 	lease;
+	queueWorkspace;
 	maxOriginalBytes;
 	maxQueueBytes;
 	maxInputBytes;
@@ -165,6 +166,7 @@ var SdkSpoolV2 = class {
 		this.originals = join(this.dir, "originals");
 		this.queue = join(this.dir, "queue");
 		this.lease = join(this.queue, "lease.lock");
+		this.queueWorkspace = join(this.queue, ".transitions");
 		this.maxOriginalBytes = limit(options.maxOriginalBytes, ORIGINAL_LIMIT);
 		this.maxQueueBytes = limit(options.maxQueueBytes, QUEUE_LIMIT);
 		if (this.maxOriginalBytes < BLOCK || this.maxQueueBytes < 3 * BLOCK) fail("STORE_OPTIONS_INVALID");
@@ -197,6 +199,17 @@ var SdkSpoolV2 = class {
 		const reserve = transition ? kind === "original" ? ACK_TRANSITION_RESERVE : QUEUE_TRANSITION_RESERVE : 0;
 		if (usage + additional > maximum + reserve) fail(kind === "original" ? "ORIGINALS_FULL" : "QUEUE_FULL");
 	}
+	prepareQueueWorkspace() {
+		try {
+			checkDirectory(this.queueWorkspace);
+			return;
+		} catch (error) {
+			if (code(error) !== "ENOENT") throw error;
+		}
+		this.budget("queue", 2 * BLOCK, true);
+		mkdirSync(this.queueWorkspace, { mode: 448 });
+		syncDirectory$1(this.queue);
+	}
 	writeFile(path, bytes) {
 		const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
 		try {
@@ -210,12 +223,19 @@ var SdkSpoolV2 = class {
 	atomicJson(path, value, kind, beforePublish, transition = false) {
 		const bytes = Buffer.from(canonical$1(value));
 		if (kind && bytes.length > (kind === "queue" ? BLOCK : 64 * 1024)) fail("SOURCE_UNVERIFIED");
+		const stagedQueue = kind === "queue" && transition;
+		if (stagedQueue) {
+			this.prepareQueueWorkspace();
+			if (readdirSync(this.queueWorkspace).length) fail("QUEUE_FULL");
+		}
 		if (kind) this.budget(kind, charge(bytes.length) + BLOCK, transition);
-		const temp = path + "." + randomUUID() + ".tmp";
+		const temp = stagedQueue ? join(this.queueWorkspace, "pending.tmp") : path + "." + randomUUID() + ".tmp";
 		this.writeFile(temp, bytes);
 		if (beforePublish) this.phase(beforePublish);
+		if (stagedQueue) this.phase("queue_transition_staged");
 		renameSync(temp, path);
 		syncDirectory$1(join(path, ".."));
+		if (stagedQueue) syncDirectory$1(this.queueWorkspace);
 	}
 	async locked(operation) {
 		const operationDeadline = this.deadline;
@@ -252,6 +272,7 @@ var SdkSpoolV2 = class {
 			}
 			fsyncSync(fd);
 			syncDirectory$1(this.queue);
+			if (readdirSync(this.queue).every((name) => name === "lease.lock")) this.prepareQueueWorkspace();
 			if (operationDeadline !== void 0 && performance.now() >= deadline) fail("STORE_BUSY");
 			return operation();
 		} catch (error) {
diff --git a/plugin/scripts/codex-compat/_capture.mjs b/plugin/scripts/codex-compat/_capture.mjs
index 6c3b3156f8..88443c9783 100644
--- a/plugin/scripts/codex-compat/_capture.mjs
+++ b/plugin/scripts/codex-compat/_capture.mjs
@@ -142,7 +142,7 @@ function limit(value, maximum) {
 /** Linux-only durable source storage. The lock covers all targets and every quota decision.
 * Source/staging files are never reclaimed. Disk charges are conservative logical bytes,
 * rounded to 4 KiB and at least stat.blocks*512; they are not filesystem hard quotas.
-* The queue includes a 4 KiB lease plus queue/root directory charges (12 KiB minimum).
+* The queue includes a 4 KiB lease plus queue/root/workspace directory charges (16 KiB for initialized stores).
 * Writes additionally reserve a parent-directory block, and 256 bytes per new chunk-directory entry.
 * Admission cannot consume transition workspace: existing refs may use an additional 8 KiB,
 * and completed manifests an additional 68 KiB. Preserved crash temporaries count toward both.
@@ -152,6 +152,7 @@ var SdkSpoolV2 = class {
 	originals;
 	queue;
 	lease;
+	queueWorkspace;
 	maxOriginalBytes;
 	maxQueueBytes;
 	maxInputBytes;
@@ -165,6 +166,7 @@ var SdkSpoolV2 = class {
 		this.originals = join(this.dir, "originals");
 		this.queue = join(this.dir, "queue");
 		this.lease = join(this.queue, "lease.lock");
+		this.queueWorkspace = join(this.queue, ".transitions");
 		this.maxOriginalBytes = limit(options.maxOriginalBytes, ORIGINAL_LIMIT);
 		this.maxQueueBytes = limit(options.maxQueueBytes, QUEUE_LIMIT);
 		if (this.maxOriginalBytes < BLOCK || this.maxQueueBytes < 3 * BLOCK) fail("STORE_OPTIONS_INVALID");
@@ -197,6 +199,17 @@ var SdkSpoolV2 = class {
 		const reserve = transition ? kind === "original" ? ACK_TRANSITION_RESERVE : QUEUE_TRANSITION_RESERVE : 0;
 		if (usage + additional > maximum + reserve) fail(kind === "original" ? "ORIGINALS_FULL" : "QUEUE_FULL");
 	}
+	prepareQueueWorkspace() {
+		try {
+			checkDirectory(this.queueWorkspace);
+			return;
+		} catch (error) {
+			if (code(error) !== "ENOENT") throw error;
+		}
+		this.budget("queue", 2 * BLOCK, true);
+		mkdirSync(this.queueWorkspace, { mode: 448 });
+		syncDirectory$1(this.queue);
+	}
 	writeFile(path, bytes) {
 		const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
 		try {
@@ -210,12 +223,19 @@ var SdkSpoolV2 = class {
 	atomicJson(path, value, kind, beforePublish, transition = false) {
 		const bytes = Buffer.from(canonical$1(value));
 		if (kind && bytes.length > (kind === "queue" ? BLOCK : 64 * 1024)) fail("SOURCE_UNVERIFIED");
+		const stagedQueue = kind === "queue" && transition;
+		if (stagedQueue) {
+			this.prepareQueueWorkspace();
+			if (readdirSync(this.queueWorkspace).length) fail("QUEUE_FULL");
+		}
 		if (kind) this.budget(kind, charge(bytes.length) + BLOCK, transition);
-		const temp = path + "." + randomUUID() + ".tmp";
+		const temp = stagedQueue ? join(this.queueWorkspace, "pending.tmp") : path + "." + randomUUID() + ".tmp";
 		this.writeFile(temp, bytes);
 		if (beforePublish) this.phase(beforePublish);
+		if (stagedQueue) this.phase("queue_transition_staged");
 		renameSync(temp, path);
 		syncDirectory$1(join(path, ".."));
+		if (stagedQueue) syncDirectory$1(this.queueWorkspace);
 	}
 	async locked(operation) {
 		const operationDeadline = this.deadline;
@@ -252,6 +272,7 @@ var SdkSpoolV2 = class {
 			}
 			fsyncSync(fd);
 			syncDirectory$1(this.queue);
+			if (readdirSync(this.queue).every((name) => name === "lease.lock")) this.prepareQueueWorkspace();
 			if (operationDeadline !== void 0 && performance.now() >= deadline) fail("STORE_BUSY");
 			return operation();
 		} catch (error) {
diff --git a/plugin/scripts/codex-compat/manifest.json b/plugin/scripts/codex-compat/manifest.json
index 89cfc02d0b..849fe33165 100644
--- a/plugin/scripts/codex-compat/manifest.json
+++ b/plugin/scripts/codex-compat/manifest.json
@@ -14,7 +14,7 @@
     "subagent-start.mjs": "24a02be53008721379cbf115884a7739baa2884f8d5f3e12a967b9ae8b0c2869",
     "subagent-stop.mjs": "8fc6929af24afd799cbaec3a3ca210971c9f51f139f6666fe0025fdfdc62dba8",
     "provenance.json": "4d768394ad40a29be9d2721fccffd0a054ec97bcc6b868305a27e755eb9b1759",
-    "_capture.mjs": "3aa31e2b33a90f9833241b0911b827c5034482ee95ea63f971828f1a72c93f48"
+    "_capture.mjs": "77c06db3bd86d2eb5595561b04060fcb9ab98c74dd2d0275704a85c835924e09"
   },
   "deploymentMapping": {
     "plugin/scripts/long-session-hook-client.mjs": "plugin/scripts/codex-compat/long-session-hook-client.mjs",
diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json
index af7303ce61..4aaa9fb0b7 100644
--- a/scripts/docs-sync.state.json
+++ b/scripts/docs-sync.state.json
@@ -1,5 +1,5 @@
 {
-  "version": "0.9.33-daniel.72",
+  "version": "0.9.33-daniel.73",
   "facts": {
     "mcpTools": [
       "55"
diff --git a/src/capture/sdk-spool-v2.ts b/src/capture/sdk-spool-v2.ts
index 81d5feadb1..f01e3e2f9e 100644
--- a/src/capture/sdk-spool-v2.ts
+++ b/src/capture/sdk-spool-v2.ts
@@ -121,7 +121,7 @@ function limit(value: number | undefined, maximum: number): number {
 /** Linux-only durable source storage. The lock covers all targets and every quota decision.
  * Source/staging files are never reclaimed. Disk charges are conservative logical bytes,
  * rounded to 4 KiB and at least stat.blocks*512; they are not filesystem hard quotas.
- * The queue includes a 4 KiB lease plus queue/root directory charges (12 KiB minimum).
+ * The queue includes a 4 KiB lease plus queue/root/workspace directory charges (16 KiB for initialized stores).
  * Writes additionally reserve a parent-directory block, and 256 bytes per new chunk-directory entry.
  * Admission cannot consume transition workspace: existing refs may use an additional 8 KiB,
  * and completed manifests an additional 68 KiB. Preserved crash temporaries count toward both.
@@ -131,6 +131,7 @@ export class SdkSpoolV2 {
   private readonly originals: string;
   private readonly queue: string;
   private readonly lease: string;
+  private readonly queueWorkspace: string;
   private readonly maxOriginalBytes: number;
   private readonly maxQueueBytes: number;
   private readonly maxInputBytes: number;
@@ -140,7 +141,7 @@ export class SdkSpoolV2 {
   constructor(options: SdkSpoolV2Options = {}) {
     const path = options.dir ?? process.env.AGENTMEMORY_SDK_CAPTURE_V2_DIR ?? join(homedir(), '.local', 'share', 'agentmemory', 'capture-spool-sdk-v2');
     if (!isAbsolute(path)) fail('STORE_OPTIONS_INVALID');
-    this.dir = resolve(path); this.originals = join(this.dir, 'originals'); this.queue = join(this.dir, 'queue'); this.lease = join(this.queue, 'lease.lock');
+    this.dir = resolve(path); this.originals = join(this.dir, 'originals'); this.queue = join(this.dir, 'queue'); this.lease = join(this.queue, 'lease.lock'); this.queueWorkspace = join(this.queue, '.transitions');
     this.maxOriginalBytes = limit(options.maxOriginalBytes, ORIGINAL_LIMIT);
     this.maxQueueBytes = limit(options.maxQueueBytes, QUEUE_LIMIT);
     if (this.maxOriginalBytes < BLOCK || this.maxQueueBytes < 3 * BLOCK) fail('STORE_OPTIONS_INVALID');
@@ -168,6 +169,14 @@ export class SdkSpoolV2 {
     const reserve = transition ? kind === 'original' ? ACK_TRANSITION_RESERVE : QUEUE_TRANSITION_RESERVE : 0;
     if (usage + additional > maximum + reserve) fail(kind === 'original' ? 'ORIGINALS_FULL' : 'QUEUE_FULL');
   }
+  private prepareQueueWorkspace(): void {
+    try { checkDirectory(this.queueWorkspace); return; }
+    catch (error) { if (code(error) !== 'ENOENT') throw error; }
+    // Bootstrap includes both the new directory and possible queue-parent growth.
+    // Legacy saturated layouts may safely refuse; never reclaim their files.
+    this.budget('queue', 2 * BLOCK, true);
+    mkdirSync(this.queueWorkspace, { mode: 0o700 }); syncDirectory(this.queue);
+  }
   private writeFile(path: string, bytes: Buffer | string): void {
     const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     try { privateStat(fstatSync(fd), false); writeFileSync(fd, bytes); fsyncSync(fd); } finally { closeSync(fd); }
@@ -175,11 +184,19 @@ export class SdkSpoolV2 {
   private atomicJson(path: string, value: unknown, kind?: 'original' | 'queue', beforePublish?: string, transition = false): void {
     const bytes = Buffer.from(canonical(value));
     if (kind && bytes.length > (kind === 'queue' ? BLOCK : 64 * 1024)) fail('SOURCE_UNVERIFIED');
+    const stagedQueue = kind === 'queue' && transition;
+    if (stagedQueue) {
+      this.prepareQueueWorkspace();
+      // A prior crash remains evidence. No overwrite, reuse, or automatic cleanup.
+      if (readdirSync(this.queueWorkspace).length) fail('QUEUE_FULL');
+    }
     if (kind) this.budget(kind, charge(bytes.length) + BLOCK, transition);
-    const temp = path + '.' + randomUUID() + '.tmp';
+    const temp = stagedQueue ? join(this.queueWorkspace, 'pending.tmp') : path + '.' + randomUUID() + '.tmp';
     this.writeFile(temp, bytes);
     if (beforePublish) this.phase(beforePublish);
+    if (stagedQueue) this.phase('queue_transition_staged');
     renameSync(temp, path); syncDirectory(join(path, '..'));
+    if (stagedQueue) syncDirectory(this.queueWorkspace);
   }
   private async locked(operation: () => T): Promise {
     const operationDeadline = this.deadline;
@@ -202,6 +219,8 @@ export class SdkSpoolV2 {
         await new Promise(resolveWait => setTimeout(resolveWait, 5));
       }
       fsyncSync(fd); syncDirectory(this.queue);
+      // Prepare empty stores before admission, so workspace is charged from day one.
+      if (readdirSync(this.queue).every(name => name === 'lease.lock')) this.prepareQueueWorkspace();
       if (operationDeadline !== undefined && performance.now() >= deadline) fail('STORE_BUSY');
       return operation();
     } catch (error) {
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index c57e470e86..42d1f9c2e5 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -315,7 +315,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
       const strategy = data.strategy || "merge";
       const importData = data.exportData;
 
-      const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.32-daniel.67", "0.9.32-daniel.68", "0.9.33-daniel.69", "0.9.33-daniel.70", "0.9.33-daniel.71", "0.9.33-daniel.72", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]);
+      const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28", "0.9.29", "0.9.30", "0.9.31", "0.9.31-daniel.1", "0.9.31-daniel.33", "0.9.31-daniel.34", "0.9.31-daniel.35", "0.9.31-daniel.36", "0.9.31-daniel.37", "0.9.31-daniel.38", "0.9.31-daniel.39", "0.9.31-daniel.40", "0.9.31-daniel.41", "0.9.31-daniel.42", "0.9.31-daniel.43", "0.9.31-daniel.44", "0.9.31-daniel.45", "0.9.31-daniel.46", "0.9.31-daniel.47", "0.9.31-daniel.48", "0.9.31-daniel.49", "0.9.31-daniel.50", "0.9.31-daniel.51", "0.9.31-daniel.52", "0.9.31-daniel.53", "0.9.31-daniel.54", "0.9.32-daniel.55", "0.9.32-daniel.57", "0.9.32-daniel.58", "0.9.32-daniel.59", "0.9.32-daniel.60", "0.9.32-daniel.61", "0.9.32-daniel.62", "0.9.32-daniel.63", "0.9.32-daniel.64", "0.9.32-daniel.65", "0.9.32-daniel.66", "0.9.32-daniel.67", "0.9.32-daniel.68", "0.9.33-daniel.69", "0.9.33-daniel.70", "0.9.33-daniel.71", "0.9.33-daniel.72", "0.9.33-daniel.73", "0.9.30-daniel.1", "0.9.30-daniel.10", "0.9.30-daniel.11", "0.9.30-daniel.15", "0.9.30-daniel.16", "0.9.30-daniel.18", "0.9.30-daniel.19", "0.9.30-daniel.2", "0.9.30-daniel.20", "0.9.30-daniel.21", "0.9.30-daniel.22", "0.9.30-daniel.23", "0.9.30-daniel.24", "0.9.30-daniel.25", "0.9.30-daniel.26", "0.9.30-daniel.27", "0.9.30-daniel.28", "0.9.30-daniel.3", "0.9.30-daniel.4", "0.9.30-daniel.5", "0.9.30-daniel.6", "0.9.30-daniel.7", "0.9.30-daniel.8", "0.9.30-daniel.9", "0.9.30-daniel.29", "0.9.30-daniel.30", "0.9.30-daniel.31", "0.9.30-daniel.32"]);
       if (!supportedVersions.has(importData.version)) {
         return {
           success: false,
diff --git a/src/types.ts b/src/types.ts
index d20279535e..f1ec9d3a88 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -421,7 +421,7 @@ export interface ExportCollectionPagination {
 }
 
 export interface ExportData {
-  version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.32-daniel.67" | "0.9.32-daniel.68" | "0.9.33-daniel.69" | "0.9.33-daniel.70" | "0.9.33-daniel.71" | "0.9.33-daniel.72" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32";
+  version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30" | "0.9.30-daniel.1" | "0.9.30-daniel.2" | "0.9.30-daniel.3" | "0.9.30-daniel.4" | "0.9.30-daniel.5" | "0.9.30-daniel.6" | "0.9.30-daniel.7" | "0.9.30-daniel.8" | "0.9.30-daniel.9" | "0.9.30-daniel.10" | "0.9.30-daniel.11" | "0.9.30-daniel.15" | "0.9.30-daniel.16" | "0.9.30-daniel.18" | "0.9.30-daniel.19" | "0.9.30-daniel.20" | "0.9.30-daniel.21" | "0.9.30-daniel.22" | "0.9.30-daniel.23" | "0.9.30-daniel.24" | "0.9.30-daniel.25" | "0.9.30-daniel.26" | "0.9.30-daniel.27" | "0.9.30-daniel.28" | "0.9.31" | "0.9.31-daniel.1" | "0.9.31-daniel.33" | "0.9.31-daniel.34" | "0.9.31-daniel.35" | "0.9.31-daniel.36" | "0.9.31-daniel.37" | "0.9.31-daniel.38" | "0.9.31-daniel.39" | "0.9.31-daniel.40" | "0.9.31-daniel.41" | "0.9.31-daniel.42" | "0.9.31-daniel.43" | "0.9.31-daniel.44" | "0.9.31-daniel.45" | "0.9.31-daniel.46" | "0.9.31-daniel.47" | "0.9.31-daniel.48" | "0.9.31-daniel.49" | "0.9.31-daniel.50" | "0.9.31-daniel.51" | "0.9.31-daniel.52" | "0.9.31-daniel.53" | "0.9.31-daniel.54" | "0.9.32-daniel.55" | "0.9.32-daniel.57" | "0.9.32-daniel.58" | "0.9.32-daniel.59" | "0.9.32-daniel.60" | "0.9.32-daniel.61" | "0.9.32-daniel.62" | "0.9.32-daniel.63" | "0.9.32-daniel.64" | "0.9.32-daniel.65" | "0.9.32-daniel.66" | "0.9.32-daniel.67" | "0.9.32-daniel.68" | "0.9.33-daniel.69" | "0.9.33-daniel.70" | "0.9.33-daniel.71" | "0.9.33-daniel.72" | "0.9.33-daniel.73" | "0.9.30-daniel.29" | "0.9.30-daniel.30" | "0.9.30-daniel.31" | "0.9.30-daniel.32";
   exportedAt: string;
   sessions: Session[];
   observations: Record;
diff --git a/src/version.ts b/src/version.ts
index 310e2a6df1..dee9c44668 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1,2 +1,2 @@
-export const VERSION = "0.9.33-daniel.72";
+export const VERSION = "0.9.33-daniel.73";
 export const III_PINNED_VERSION = "0.25.1";
diff --git a/test/diagnostics.test.ts b/test/diagnostics.test.ts
index 7a45cfa5d9..419c14becd 100644
--- a/test/diagnostics.test.ts
+++ b/test/diagnostics.test.ts
@@ -522,6 +522,12 @@ describe("Diagnostics Functions", () => {
       await kv.set(KV.facets,stale.id,{...stale,targetId:"mem_live"});
       expect(await isFacetStillOrphan(kv as never,stale)).toBe(false);
     });
+    it("rejects a replaced facet with a different creation timestamp", async()=>{
+      const stored=(await kv.get>(KV.facets,"fct_2"))!;
+      const stale={...stored,createdAt:new Date(Date.parse(stored.createdAt)-1).toISOString()};
+      expect(await isFacetStillOrphan(kv as never,stale)).toBe(false);
+      expect(await isFacetStillOrphan(kv as never,stored)).toBe(true);
+    });
     it("rechecks unindexed observations restored into a live session before delete", async()=>{
       const stale=facet("fct_restored","restored-no-prefix","observation");
       await kv.set(KV.facets,stale.id,stale);
@@ -552,7 +558,7 @@ describe("Diagnostics Functions", () => {
       await kv.set(KV.observations("migrated"), "obs_migrated", { id: "obs_migrated", sessionId: "migrated" });
       await sdk.trigger("mem::heal", { categories: ["facets"] });
       expect((await kv.list<{ id: string }>(KV.facets)).map((f) => f.id)).toContain("fct_7");
-      expect(await isFacetStillOrphan(kv as never, facet("fct_7", "obs_migrated", "observation"))).toBe(false);
+      expect(await isFacetStillOrphan(kv as never, (await kv.get>(KV.facets,"fct_7"))!)).toBe(false);
     });
 
     it("heal keeps a facet on a migrated observation whose id has no obs_ prefix", async () => {
@@ -560,11 +566,12 @@ describe("Diagnostics Functions", () => {
       await kv.set(KV.observations("migrated"), "mig_abc", { id: "mig_abc", sessionId: "migrated" });
       await sdk.trigger("mem::heal", { categories: ["facets"] });
       expect((await kv.list<{ id: string }>(KV.facets)).map((f) => f.id)).toContain("fct_8");
-      expect(await isFacetStillOrphan(kv as never, facet("fct_8", "mig_abc", "observation"))).toBe(false);
+      expect(await isFacetStillOrphan(kv as never, (await kv.get>(KV.facets,"fct_8"))!)).toBe(false);
     });
 
     it("heal keeps a facet whose target comes back before the delete", async () => {
-      const orphan = facet("fct_2", "mem_gone", "memory");
+      const orphan = (await kv.get>(KV.facets, "fct_2"))!;
+      expect(orphan).not.toBeNull();
       expect(await isFacetStillOrphan(kv as never, orphan)).toBe(true);
       await kv.set(KV.memories, "mem_gone", { id: "mem_gone" });
       expect(await isFacetStillOrphan(kv as never, orphan)).toBe(false);
diff --git a/test/sdk-spool-progress.test.ts b/test/sdk-spool-progress.test.ts
index 6e62d4c694..fd99611904 100644
--- a/test/sdk-spool-progress.test.ts
+++ b/test/sdk-spool-progress.test.ts
@@ -1,6 +1,6 @@
 import {afterEach,expect,it,vi} from 'vitest';
 import {createHash} from 'node:crypto';
-import {chmodSync,mkdirSync,mkdtempSync,readFileSync,readdirSync,rmSync,truncateSync,writeFileSync} from 'node:fs';
+import {chmodSync,mkdirSync,mkdtempSync,readFileSync,lstatSync,readdirSync,symlinkSync,rmSync,truncateSync,writeFileSync} from 'node:fs';
 import {join} from 'node:path';
 import {tmpdir} from 'node:os';
 import {performance} from 'node:perf_hooks';
@@ -28,9 +28,12 @@ async function fixture(refs=1240,completed=2328,textBytes=32*1024){
 }
 function fill(path:string,bytes:number){expect(bytes).toBeGreaterThanOrEqual(BLOCK);writeFileSync(path,'',{mode:0o600});truncateSync(path,bytes);}
 
-it('progresses a legacy 1240-ref saturated queue, preserving all originals and reserved admission',async()=>{
- const {dir,store,selected}=await fixture();
- fill(join(dir,'queue','legacy-preserved.tmp'),5*MiB-(await store.usage()).queueBytes);
+it('progresses a legacy 1200-ref byte-saturated queue, preserving all originals and reserved admission',async()=>{
+ // Keep reference count portable; exact byte saturation below still tests the same cap.
+ // ext4 directory blocks can make 1240 refs alone exceed 5MiB on some layouts.
+ const {dir,store,selected}=await fixture(1200,2368);
+ const filler=join(dir,'queue','legacy-preserved.tmp');writeFileSync(filler,'',{mode:0o600});
+ fill(filler,5*MiB-(await store.usage()).queueBytes+BLOCK);
  const before=await store.usage();expect(before.queueBytes).toBeLessThanOrEqual(5*MiB);expect(5*MiB-before.queueBytes).toBeLessThan(2*BLOCK);
  const source=selected[0],chunk=join(dir,'originals',source.sourceId,'000000.chunk'),digest=hash(readFileSync(chunk));
  const extra=await store.retain(target,'new-after-full',{eventId:'new-after-full',data:'synthetic'});
@@ -92,15 +95,15 @@ it('a malformed unrelated reference cannot prevent selected delivery',async()=>{
 });
 
 it('lists metadata and verifies only selected source bytes for direct delivery and bounded drain',async()=>{
- const {dir,store,selected}=await fixture();let verified=0;
+ const {dir,store,selected}=await fixture(1200,2368);let verified=0;
  const options={dir,storeOptions:{onPhase:(phase:string)=>{if(phase==='source_verified')verified++;}}};
  const start=performance.now(),records=await new SdkSpoolV2({...options.storeOptions,dir}).pending(target),listingMs=performance.now()-start;
- expect(records).toHaveLength(1240);expect(verified).toBe(0);
+ expect(records).toHaveLength(1200);expect(verified).toBe(0);
  const result=await deliverSdkCaptureV2(target,selected[0].body,async body=>ack(body),options);
  expect(result.outcome).toBe('delivered');expect(verified).toBeLessThanOrEqual(5);
  verified=0;const drained=await drainSdkCapturesV2(target,async body=>ack(body),{...options,limit:1,budgetMs:1500});
- expect(drained).toMatchObject({attempted:1,delivered:1,remaining:1238});expect(verified).toBeLessThanOrEqual(3);
- console.log(JSON.stringify({syntheticSpoolProgress:true,refs:1240,originals:3568,listingMs:Math.round(listingMs),selectedSourceReads:verified}));
+ expect(drained).toMatchObject({attempted:1,delivered:1,remaining:1198});expect(verified).toBeLessThanOrEqual(3);
+ console.log(JSON.stringify({syntheticSpoolProgress:true,refs:1200,originals:3568,listingMs:Math.round(listingMs),selectedSourceReads:verified}));
  expect((await store.usage()).originalBytes).toBeGreaterThan(100*MiB);
 },30000);
 
@@ -112,3 +115,58 @@ it('queue transitions do not inspect unrelated original trees and corrupt select
  const result=await deliverSdkCaptureV2(target,selected[1].body,async body=>{posts++;return ack(body);},{dir});
  expect(result.outcome).toBe('dropped');expect(posts).toBe(0);expect(readFileSync(chunk,'utf8')).toBe('corrupt');
 });
+
+
+it('preserves crashed transition workspace and refuses replacement without consuming another slot',async()=>{
+ const {dir,store,selected}=await fixture(1,0,256);
+ const slot=join(dir,'queue','.transitions','pending.tmp');writeFileSync(slot,'synthetic crash evidence',{mode:0o600});
+ const before=await store.usage();
+ await expect(store.markSending(target,selected[0].sourceId)).rejects.toMatchObject({code:'QUEUE_FULL'});
+ expect(readFileSync(slot,'utf8')).toBe('synthetic crash evidence');
+ expect(await store.usage()).toEqual(before);expect((await store.pending(target))[0].state).toBe('pending');
+});
+
+it('refuses legacy workspace bootstrap over its reserved peak without deleting preserved pressure',async()=>{
+ const {dir,store,selected}=await fixture(1,0,256);
+ rmSync(join(dir,'queue','.transitions'),{recursive:true});
+ const before=await store.usage(),pressure=join(dir,'queue','legacy-crash.tmp');
+ fill(pressure,5*MiB-before.queueBytes+BLOCK);
+ const usage=await store.usage();
+ await expect(store.markSending(target,selected[0].sourceId)).rejects.toMatchObject({code:'QUEUE_FULL'});
+ expect(await store.usage()).toEqual(usage);
+ expect(readdirSync(join(dir,'queue'))).not.toContain('.transitions');
+ expect((await store.pending(target))[0].state).toBe('pending');
+});
+
+
+it('keeps actual staged replacement peak inside the unchanged 8KiB reserve',async()=>{
+ const {dir,store,selected}=await fixture(1,0,256);
+ const before=await store.usage();let peaks=0;
+ const measure=(path:string):number=>{const stat=lstatSync(path);return Math.max(BLOCK,Math.ceil(stat.size/BLOCK)*BLOCK,stat.blocks*512)+(stat.isDirectory()?readdirSync(path).reduce((sum,name)=>sum+measure(join(path,name)),0):0);};
+ const constrained=new SdkSpoolV2({dir,maxQueueBytes:before.queueBytes,onPhase:phase=>{
+  if(phase==='queue_transition_staged'){peaks++;expect(measure(join(dir,'queue'))+BLOCK).toBeLessThanOrEqual(before.queueBytes+2*BLOCK);}
+ }});
+ await constrained.markSending(target,selected[0].sourceId);await constrained.hold(target,selected[0].sourceId,'unknown');
+ expect(peaks).toBe(2);expect(readdirSync(join(dir,'queue','.transitions'))).toEqual([]);
+ expect(await store.load(target,selected[0].sourceId)).toEqual(selected[0].body);
+});
+
+it('rejects a symlinked transition workspace without writing outside the spool',async()=>{
+ const {dir,store,selected}=await fixture(1,0,256),outside=root();
+ rmSync(join(dir,'queue','.transitions'),{recursive:true});symlinkSync(outside,join(dir,'queue','.transitions'));
+ await expect(store.markSending(target,selected[0].sourceId)).rejects.toMatchObject({code:'STORE_UNSAFE'});
+ expect(readdirSync(outside)).toEqual([]);
+});
+
+
+it('preserves a legacy 1240-ref layout that is actually over the byte quota',async()=>{
+ const {dir,store,selected}=await fixture(1240,0,256);
+ rmSync(join(dir,'queue','.transitions'),{recursive:true});
+ const usage=await store.usage();
+ if(usage.queueBytes<=5*MiB)fill(join(dir,'queue','preserved-pressure.tmp'),5*MiB-usage.queueBytes+BLOCK);
+ const before=await store.usage();expect(before.queueBytes).toBeGreaterThan(5*MiB);
+ await expect(store.markSending(target,selected[0].sourceId)).rejects.toMatchObject({code:'QUEUE_FULL'});
+ expect(await store.usage()).toEqual(before);expect(await store.pending(target)).toHaveLength(1240);
+ expect(readdirSync(join(dir,'originals'))).toHaveLength(1240);
+ expect(await store.load(target,selected[0].sourceId)).toEqual(selected[0].body);
+});
diff --git a/test/sdk-spool-v2.test.ts b/test/sdk-spool-v2.test.ts
index 29a309c00b..499d804fa2 100644
--- a/test/sdk-spool-v2.test.ts
+++ b/test/sdk-spool-v2.test.ts
@@ -148,7 +148,7 @@ describe('SdkSpoolV2 durable originals and references',()=>{
 
  it('uses one bounded lease file and no growing ticket bookkeeping',async()=>{
   const s=store();for(let index=0;index<10;index++)await s.usage();
-  expect(readdirSync(join(dir,'queue'))).toEqual(['lease.lock']);
+  expect(readdirSync(join(dir,'queue'))).toEqual(['.transitions','lease.lock']);
   expect(statSync(join(dir,'queue','lease.lock')).size).toBe(0);
  });
  it('kernel releases crashed writer lease while preserving its partial original',async()=>{
@@ -158,7 +158,7 @@ describe('SdkSpoolV2 durable originals and references',()=>{
   expect(output.trim()).toBe('synthetic-crash');
   const s=store();const r=await s.retain(target,'event-1',body());expect(await s.load(target,r.sourceId)).toEqual(body());
   expect(readdirSync(join(dir,'originals')).some(name=>name.startsWith('.stage-'))).toBe(true);
-  expect(readdirSync(join(dir,'queue'))).toEqual(['lease.lock']);
+  expect(readdirSync(join(dir,'queue'))).toEqual(['.transitions','lease.lock']);
  });
 
  it('rejects impossible fixture budgets below fixed directory and lease charges',()=>{

From 01d4f98fc4ce8109e31b4f91262be96db3b390e5 Mon Sep 17 00:00:00 2001
From: Codex 
Date: Sat, 14 Nov 2026 12:23:52 +0900
Subject: [PATCH 23/23] build: regenerate plugin bridge after candidate version
 synchronization

---
 plugin/scripts/plugin-bridge.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs
index e583e39a19..788aa540fb 100644
--- a/plugin/scripts/plugin-bridge.mjs
+++ b/plugin/scripts/plugin-bridge.mjs
@@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 //#region src/version.ts
-const VERSION = "0.9.33-daniel.72";
+const VERSION = "0.9.33-daniel.73";
 //#endregion
 //#region src/secret-store.ts
 const SECRET_KEY = "AGENTMEMORY_SECRET";