Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix: handle slow worker startup across CLI paths (#1531)

Rohit Ghumare1c2f0ad9e236
diff --git a/.env.example b/.env.example
index ec8c26df..34dfc2ac 100644
--- a/.env.example
+++ b/.env.example
@@ -166,6 +166,16 @@
# AGENTMEMORY_DEBUG=1 # Trace MCP shim probe + standalone fallback decisions to stderr
# AGENTMEMORY_FORCE_PROXY=1 # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)
# AGENTMEMORY_PROBE_TIMEOUT_MS=2000 # MCP shim livez probe timeout
+# AGENTMEMORY_READY_TIMEOUT_MS=300000 # CLI worker readiness deadline, including state loading (5 minutes)
+# AGENTMEMORY_ENGINE_READY_TIMEOUT_MS=120000 # CLI engine readiness deadline (2 minutes)
+# Startup deadlines accept whole milliseconds from 1 to 3600000. Shell
+# environment overrides this file. Engine and worker waits have separate
+# budgets; Docker/orchestrator healthcheck grace must allow for both when
+# increasing them for a slow store.
+# AGENTMEMORY_ENGINE_MANAGES_WORKER=true # Custom engine config launches the worker through a wrapper
+# Direct AgentMemory worker commands are detected automatically. Set true
+# for custom launch wrappers so the CLI waits instead of starting a second
+# worker; set false when custom exec jobs are unrelated to AgentMemory.
# AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim
# AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status`
# Persistent iii state; same override as `--data-dir`, used by native and
diff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.yml
index d7b15088..76abbffb 100644
--- a/.github/workflows/release-gate.yml
+++ b/.github/workflows/release-gate.yml
@@ -44,10 +44,13 @@ jobs:
node-version: 22
- run: npm install --legacy-peer-deps --no-audit --no-fund
- run: npm run release:gate -- --out "${{ runner.temp }}/release-gate"
+ - run: npm run test:startup:packaged -- --skip-build --out "${{ runner.temp }}/startup-gate"
- if: always()
uses: actions/upload-artifact@v4
with:
name: release-gate-${{ matrix.os }}
- path: ${{ runner.temp }}/release-gate
+ path: |
+ ${{ runner.temp }}/release-gate
+ ${{ runner.temp }}/startup-gate
if-no-files-found: ignore
retention-days: 14
diff --git a/AGENTS.md b/AGENTS.md
index 5250056f..6a0e85ff 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ 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` (2,900+ 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` (3,000+ 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
@@ -114,4 +114,4 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 17 skills
- 312+ iii functions
-- 2,900+ tests
+- 3,000+ tests
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6e58c49d..bd876ece 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -105,6 +105,8 @@ npm run release:gate
It builds, packs `@agentmemory/agentmemory` and `@agentmemory/mcp`, installs both tarballs into a fresh prefix with a clean `HOME`, starts the installed CLI on random free ports with a deterministic local embedding server (no API keys), and checks capture through the bundled hooks, offline capture and spool recovery, replay dedup after a force kill, dead letters across a restart, vector survival before the first checkpoint, `agentmemory stop` then start, export and import into a fresh home, the MCP entrypoints, and the viewer plus `/agentmemory/status`. It prints a pass or fail line per scenario and a JSON summary, writes logs and `summary.json` to the output directory it prints, and stops only the processes it started. To gate the exact file you will publish, pass it in: `npm pack` then `npm run release:gate -- --tarball agentmemory-agentmemory-<version>.tgz`, and publish that tarball. Do not publish when a scenario fails. The `Release gate` workflow runs the same script on Ubuntu and macOS for pull requests and pushes to main.
+For startup changes, also run `npm run test:startup:packaged`. It installs the packed CLI in isolated homes and tests delayed workers, existing-engine adoption, `--no-engine`, doctor, demo, timeout failures and process cleanup. The default slow-worker case waits 48 seconds before importing the installed worker. Pass `--tarball <file.tgz>` to test an existing artifact. Run the standard release gate first to cache the pinned engine, or set `AGENTMEMORY_GATE_ENGINE` to that engine binary. Docker scenarios require a working Docker daemon; the report records unavailable Docker coverage explicitly.
+
Then: CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance (`@agentmemory/fs-watcher` versions independently from `integrations/filesystem-watcher/package.json`).
## Security issues
diff --git a/README.md b/README.md
index b9802af2..9ae959fe 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1450,7 +1450,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**227 source files · ~54,000 LOC · 2,900+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+**228 source files · ~54,000 LOC · 3,000+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
---
@@ -1882,7 +1882,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.md
index 8d993342..3cbf2965 100644
--- a/READMEs/README.ar-SA.md
+++ b/READMEs/README.ar-SA.md
@@ -73,7 +73,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية |
| أنظمة إضافات مخصصة | `iii worker add <name>` |
-**227 ملف مصدري · ~54,000 سطر برمجي · 2,900+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
+**228 ملف مصدري · ~54,000 سطر برمجي · 3,000+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
---
@@ -1863,7 +1863,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.md
index 625803cc..6e0576dd 100644
--- a/READMEs/README.bn-BD.md
+++ b/READMEs/README.bn-BD.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP টুল" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 অটো হুক" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 এক্সটার্নাল ডিবি" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ টেস্ট পাস" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ টেস্ট পাস" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + হেলথ মনিটর |
| কাস্টম প্লাগইন সিস্টেম | `iii worker add <name>` |
-**227 সোর্স ফাইল · ~54,000 LOC · 2,900+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
+**228 সোর্স ফাইল · ~54,000 LOC · 3,000+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.cs-CZ.md b/READMEs/README.cs-CZ.md
index fe64e766..c84d9b69 100644
--- a/READMEs/README.cs-CZ.md
+++ b/READMEs/README.cs-CZ.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP nástrojů" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatických hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externích databází" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testů úspěšně proběhlo" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ testů úspěšně proběhlo" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Vlastní systémy pluginů | `iii worker add <name>` |
-**227 zdrojových souborů · ~54,000 řádků kódu · 2,900+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
+**228 zdrojových souborů · ~54,000 řádků kódu · 3,000+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.da-DK.md b/READMEs/README.da-DK.md
index e95f5209..e3506395 100644
--- a/READMEs/README.da-DK.md
+++ b/READMEs/README.da-DK.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-værktøjer" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatiske hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 eksterne databaser" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ beståede tests" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ beståede tests" height="38" /></picture>
</p>
<p align="center">
@@ -1436,7 +1436,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemer | `iii worker add <name>` |
-**227 kildefiler · ~54,000 LOC · 2,900+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
+**228 kildefiler · ~54,000 LOC · 3,000+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
---
@@ -1860,7 +1860,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md
index cfa0822c..fb77b763 100644
--- a/READMEs/README.de-DE.md
+++ b/READMEs/README.de-DE.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-Tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 Auto-Hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externe DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ bestandene Tests" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ bestandene Tests" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + Health-Monitor |
| Eigene Plugin-Systeme | `iii worker add <name>` |
-**227 Quelldateien · ~54,000 LOC · 2,900+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+**228 Quelldateien · ~54,000 LOC · 3,000+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.md
index ea1d4291..28784fc0 100644
--- a/READMEs/README.el-GR.md
+++ b/READMEs/README.el-GR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 εργαλεία MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 αυτόματα hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 εξωτερικές βάσεις δεδομένων" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ επιτυχημένες δοκιμές" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ επιτυχημένες δοκιμές" height="38" /></picture>
</p>
<p align="center">
@@ -1438,7 +1438,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor υγείας |
| Προσαρμοσμένα συστήματα plugin | `iii worker add <name>` |
-**227 αρχεία πηγαίου κώδικα · ~54,000 LOC · 2,900+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
+**228 αρχεία πηγαίου κώδικα · ~54,000 LOC · 3,000+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
---
@@ -1862,7 +1862,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md
index 360b7711..3bc00ec1 100644
--- a/READMEs/README.es-ES.md
+++ b/READMEs/README.es-ES.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 tools MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks automáticos" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 bases de datos externas" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests superados" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests superados" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de salud |
| Sistemas de plugins propios | `iii worker add <name>` |
-**227 ficheros de código · ~54,000 LOC · 2,900+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+**228 ficheros de código · ~54,000 LOC · 3,000+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.md
index ac6ae128..e5fe94a3 100644
--- a/READMEs/README.fi-FI.md
+++ b/READMEs/README.fi-FI.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-työkalua" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automaattista hookia" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 ulkoista tietokantaa" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testiä läpäisty" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ testiä läpäisty" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + terveysmonitori |
| Mukautetut plugin-järjestelmät | `iii worker add <name>` |
-**227 lähdetiedostoa · ~54,000 LOC · 2,900+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
+**228 lähdetiedostoa · ~54,000 LOC · 3,000+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.md
index 8319c433..9ccb5464 100644
--- a/READMEs/README.fr-FR.md
+++ b/READMEs/README.fr-FR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1448,7 +1448,7 @@ fi
| Prometheus / Grafana | iii OTEL + moniteur de santé |
| Systèmes de plugins custom | `iii worker add <name>` |
-**227 fichiers sources · ~54,000 LOC · 2,900+ tests · 312 fonctions · 62 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
+**228 fichiers sources · ~54,000 LOC · 3,000+ tests · 312 fonctions · 62 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
---
@@ -1872,7 +1872,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.md
index 8a2e9947..c9456598 100644
--- a/READMEs/README.he-IL.md
+++ b/READMEs/README.he-IL.md
@@ -73,7 +73,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 כלי MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks אוטומטיים" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 מסדי נתונים חיצוניים" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ בדיקות עוברות" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ בדיקות עוברות" height="38" /></picture>
</p>
<p align="center">
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | iii OTEL + מוניטור health |
| מערכות plugin מותאמות אישית | `iii worker add <name>` |
-**227 קבצי מקור · ~54,000 LOC · 2,900+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
+**228 קבצי מקור · ~54,000 LOC · 3,000+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
---
@@ -1863,7 +1863,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.md
index 7a6c698c..95cb6c8b 100644
--- a/READMEs/README.hi-IN.md
+++ b/READMEs/README.hi-IN.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1449,7 +1449,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**227 source files · ~54,000 LOC · 2,900+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
+**228 source files · ~54,000 LOC · 3,000+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
---
@@ -1873,7 +1873,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.md
index 1094c112..aaabb386 100644
--- a/READMEs/README.hu-HU.md
+++ b/READMEs/README.hu-HU.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP eszköz" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatikus hook" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 külső adatbázis" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ sikeres teszt" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ sikeres teszt" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ A `/agentmemory/export` emellett elfogadja a `?maxSessions=`-t és a `?offset=`-
| Prometheus / Grafana | iii OTEL + egészségfigyelő |
| Egyéni plugin-rendszerek | `iii worker add <name>` |
-**227 forrásfájl · ~54,000 LOC · 2,900+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
+**228 forrásfájl · ~54,000 LOC · 3,000+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.id-ID.md b/READMEs/README.id-ID.md
index ff5e3cf4..c94940d9 100644
--- a/READMEs/README.id-ID.md
+++ b/READMEs/README.id-ID.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 tool MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook otomatis" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 DB eksternal" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ pengujian lolos" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ pengujian lolos" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Sistem plugin custom | `iii worker add <name>` |
-**227 file sumber · ~54,000 LOC · 2,900+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
+**228 file sumber · ~54,000 LOC · 3,000+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.it-IT.md b/READMEs/README.it-IT.md
index c85e4ac3..d3d09642 100644
--- a/READMEs/README.it-IT.md
+++ b/READMEs/README.it-IT.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor di salute |
| Sistemi di plugin personalizzati | `iii worker add <name>` |
-**227 file sorgente · ~54,000 righe di codice · 2,900+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
+**228 file sorgente · ~54,000 righe di codice · 3,000+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md
index 043adbd7..3285ed0f 100644
--- a/READMEs/README.ja-JP.md
+++ b/READMEs/README.ja-JP.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP ツール" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 自動 hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="外部 DB 0 個" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 件のテストが成功" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ 件のテストが成功" height="38" /></picture>
</p>
<p align="center">
@@ -1445,7 +1445,7 @@ fi
| Prometheus / Grafana | iii OTEL + ヘルスモニタ |
| カスタムプラグインシステム | `iii worker add <name>` |
-**227 ソースファイル · ~54,000 LOC · 2,900+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
+**228 ソースファイル · ~54,000 LOC · 3,000+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
---
@@ -1869,7 +1869,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md
index e0dadacb..32ec5cc8 100644
--- a/READMEs/README.ko-KR.md
+++ b/READMEs/README.ko-KR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health 모니터 |
| 커스텀 플러그인 시스템 | `iii worker add <name>` |
-**소스 파일 227개 · LOC ~54,000줄 · 테스트 2,900+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
+**소스 파일 228개 · LOC ~54,000줄 · 테스트 3,000+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.md
index 694280e9..878bc705 100644
--- a/READMEs/README.nb-NO.md
+++ b/READMEs/README.nb-NO.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + helseovervåker |
| Egendefinerte plugin-systemer | `iii worker add <name>` |
-**227 kildefiler · ~54,000 LOC · 2,900+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
+**228 kildefiler · ~54,000 LOC · 3,000+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.nl-NL.md b/READMEs/README.nl-NL.md
index 92ca4769..1124fb7d 100644
--- a/READMEs/README.nl-NL.md
+++ b/READMEs/README.nl-NL.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemen | `iii worker add <name>` |
-**227 bronbestanden · ~54,000 LOC · 2,900+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
+**228 bronbestanden · ~54,000 LOC · 3,000+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.pl-PL.md b/READMEs/README.pl-PL.md
index b1b98c54..f42eb503 100644
--- a/READMEs/README.pl-PL.md
+++ b/READMEs/README.pl-PL.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 narzędzia MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatycznych hooków" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 zewnętrznych baz danych" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ zaliczonych testów" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ zaliczonych testów" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor stanu |
| Niestandardowe systemy pluginów | `iii worker add <name>` |
-**227 plików źródłowych · ~54,000 LOC · 2,900+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
+**228 plików źródłowych · ~54,000 LOC · 3,000+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.md
index 852cd6fc..1dae1e6d 100644
--- a/READMEs/README.pt-BR.md
+++ b/READMEs/README.pt-BR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugin customizados | `iii worker add <name>` |
-**227 arquivos de código · ~54,000 LOC · 2,900+ testes · 312 funções · 62 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**228 arquivos de código · ~54,000 LOC · 3,000+ testes · 312 funções · 62 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.md
index 6b82ab4d..552cd50d 100644
--- a/READMEs/README.pt-PT.md
+++ b/READMEs/README.pt-PT.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 ferramentas MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks automáticos" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 bases de dados externas" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testes aprovados" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ testes aprovados" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ O `/agentmemory/export` também aceita `?maxSessions=` e `?offset=` para dividir
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugins personalizados | `iii worker add <name>` |
-**227 ficheiros de código-fonte · ~54,000 LOC · 2,900+ testes · 312 funções · 62 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**228 ficheiros de código-fonte · ~54,000 LOC · 3,000+ testes · 312 funções · 62 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ro-RO.md b/READMEs/README.ro-RO.md
index 6f73b5ee..2a8a0d08 100644
--- a/READMEs/README.ro-RO.md
+++ b/READMEs/README.ro-RO.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 de instrumente MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook-uri automate" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 baze de date externe" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ teste trecute" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ teste trecute" height="38" /></picture>
</p>
<p align="center">
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de sănătate |
| Sisteme de plugin-uri personalizate | `iii worker add <name>` |
-**227 fișiere sursă · ~54,000 LOC · 2,900+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
+**228 fișiere sursă · ~54,000 LOC · 3,000+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
---
@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md
index d04a8ada..a7300af9 100644
--- a/READMEs/README.ru-RU.md
+++ b/READMEs/README.ru-RU.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + монитор состояния |
| Самописные плагинные системы | `iii worker add <name>` |
-**227 исходных файлов · ~54,000 LOC · 2,900+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
+**228 исходных файлов · ~54,000 LOC · 3,000+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.md
index 895aa777..787e74bf 100644
--- a/READMEs/README.sv-SE.md
+++ b/READMEs/README.sv-SE.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-verktyg" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatiska hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externa databaser" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ godkända tester" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ godkända tester" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + hälsoövervakare |
| Anpassade pluginsystem | `iii worker add <name>` |
-**227 källkodsfiler · ~54,000 LOC · 2,900+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
+**228 källkodsfiler · ~54,000 LOC · 3,000+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.th-TH.md b/READMEs/README.th-TH.md
index 3a1ac15d..c70f7a9b 100644
--- a/READMEs/README.th-TH.md
+++ b/READMEs/README.th-TH.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 เครื่องมือ MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook อัตโนมัติ" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="ไม่ต้องพึ่ง external DB เลย" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="ผ่านการทดสอบ 2,900+ รายการ" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="ผ่านการทดสอบ 3,000+ รายการ" height="38" /></picture>
</p>
<p align="center">
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**227 source file · ~54,000 LOC · 2,900+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
+**228 source file · ~54,000 LOC · 3,000+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
---
@@ -1868,7 +1868,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.tl-PH.md b/READMEs/README.tl-PH.md
index 884e3ebb..ff12dbf8 100644
--- a/READMEs/README.tl-PH.md
+++ b/READMEs/README.tl-PH.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tool" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 awtomatikong hook" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 panlabas na DB" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ pumapasang test" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ pumapasang test" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ Tinatanggap din ng `/agentmemory/export` ang `?maxSessions=` at `?offset=` para
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom na plugin system | `iii worker add <name>` |
-**227 na source file · ~54,000 LOC · 2,900+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
+**228 na source file · ~54,000 LOC · 3,000+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md
index e44fe39b..aae81337 100644
--- a/READMEs/README.tr-TR.md
+++ b/READMEs/README.tr-TR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom eklenti sistemleri | `iii worker add <name>` |
-**227 kaynak dosya · ~54,000 LOC · 2,900+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
+**228 kaynak dosya · ~54,000 LOC · 3,000+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.md
index 23ed1f21..ef124feb 100644
--- a/READMEs/README.uk-UA.md
+++ b/READMEs/README.uk-UA.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 інструменти MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 автоматичних хуків" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 зовнішніх БД" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ тестів пройдено" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ тестів пройдено" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + монітор стану здоров'я |
| Власні системи плагінів | `iii worker add <name>` |
-**227 вихідних файлів · ~54,000 LOC · 2,900+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
+**228 вихідних файлів · ~54,000 LOC · 3,000+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ur-PK.md b/READMEs/README.ur-PK.md
index 19cf115c..42fb1c0d 100644
--- a/READMEs/README.ur-PK.md
+++ b/READMEs/README.ur-PK.md
@@ -73,7 +73,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP ٹولز" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 خودکار ہکس" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 خارجی ڈیٹابیسز" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture>
</p>
<p align="center">
@@ -1432,7 +1432,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| کسٹم plugin سسٹمز | `iii worker add <name>` |
-**227 سورس فائلز · ~54,000 لائنز کوڈ · 2,900+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
+**228 سورس فائلز · ~54,000 لائنز کوڈ · 3,000+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
---
@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.md
index 43c1b769..c754c365 100644
--- a/READMEs/README.vi-VN.md
+++ b/READMEs/README.vi-VN.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Hệ thống plugin tùy chỉnh | `iii worker add <name>` |
-**227 file source · ~54,000 LOC · 2,900+ test · 312 function · 62 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
+**228 file source · ~54,000 LOC · 3,000+ test · 312 function · 62 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md
index 94d4a82d..4b9dee4b 100644
--- a/READMEs/README.zh-CN.md
+++ b/READMEs/README.zh-CN.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 个 MCP 工具" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 个自动 hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 个外部数据库" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 项测试通过" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ 项测试通过" height="38" /></picture>
</p>
<p align="center">
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康监控 |
| Custom plugin systems | `iii worker add <name>` |
-**227 个源文件 · ~54,000 行代码 · 2,900+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
+**228 个源文件 · ~54,000 行代码 · 3,000+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
---
@@ -1868,7 +1868,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md
index 83605600..d4b90bca 100644
--- a/READMEs/README.zh-TW.md
+++ b/READMEs/README.zh-TW.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 個 MCP 工具" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 個自動 hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 個外部資料庫" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 測試通過" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ 測試通過" height="38" /></picture>
</p>
<p align="center">
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康監控 |
| 自訂外掛系統 | `iii worker add <name>` |
-**227 個原始檔 · ~54,000 行程式碼 · 2,900+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
+**228 個原始檔 · ~54,000 行程式碼 · 3,000+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
---
@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,900+ tests
+npm test # 3,000+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/assets/tags/light/stat-tests.svg b/assets/tags/light/stat-tests.svg
index 955556fb..45fd4a82 100644
--- a/assets/tags/light/stat-tests.svg
+++ b/assets/tags/light/stat-tests.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2900+">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 3000+">
<rect x="0" y="0" width="140" height="48" rx="10" fill="#FFFFFF" stroke="#E5E7EB" stroke-width="1"/>
- <text x="70" y="24" fill="#16A34A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2900+</text>
+ <text x="70" y="24" fill="#16A34A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">3000+</text>
<text x="70" y="38" fill="#64748B" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="9" font-weight="600" text-anchor="middle" letter-spacing="1.5">TESTS PASSING</text>
</svg>
diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg
index 8e120b66..67853cf6 100644
--- a/assets/tags/stat-tests.svg
+++ b/assets/tags/stat-tests.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2900+">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 3000+">
<rect x="0" y="0" width="140" height="48" rx="10" fill="#1A1A1A" stroke="#2A2A2A" stroke-width="1"/>
- <text x="70" y="24" fill="#00D26A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2900+</text>
+ <text x="70" y="24" fill="#00D26A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">3000+</text>
<text x="70" y="38" fill="#9CA3AF" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="9" font-weight="600" text-anchor="middle" letter-spacing="1.5">TESTS PASSING</text>
</svg>
diff --git a/package.json b/package.json
index 0893be3a..1a9893db 100644
--- a/package.json
+++ b/package.json
@@ -25,6 +25,7 @@
"test:watch": "vitest --exclude test/integration.test.ts",
"test:integration": "vitest run test/integration.test.ts",
"test:all": "vitest run",
+ "test:startup:packaged": "node scripts/release-gate/startup.mjs",
"release:gate": "node scripts/release-gate/run.mjs",
"skills:gen": "tsx scripts/skills/generate.ts",
"engine:hashes": "node scripts/engine-hashes.mjs",
diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md
index e2ab6379..f2a09783 100644
--- a/plugin/skills/agentmemory-config/REFERENCE.md
+++ b/plugin/skills/agentmemory-config/REFERENCE.md
@@ -3,7 +3,7 @@
Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.
<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->
-Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 73 recognized variables:
+Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 76 recognized variables:
- `AGENTMEMORY_AGENT_SCOPE`
- `AGENTMEMORY_ALLOW_AGENT_SDK`
@@ -35,6 +35,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_DOCKER_SKIP_CHOWN`
- `AGENTMEMORY_DOCKER_UID`
- `AGENTMEMORY_DROP_STALE_INDEX`
+- `AGENTMEMORY_ENGINE_MANAGES_WORKER`
+- `AGENTMEMORY_ENGINE_READY_TIMEOUT_MS`
- `AGENTMEMORY_EXPORT_ROOT`
- `AGENTMEMORY_FINALIZE_IDLE_MS`
- `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS`
@@ -56,6 +58,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_PROBE_TIMEOUT_MS`
- `AGENTMEMORY_PROJECT_NAME`
- `AGENTMEMORY_PROVIDER`
+- `AGENTMEMORY_READY_TIMEOUT_MS`
- `AGENTMEMORY_REDIS_URL`
- `AGENTMEMORY_REFLECT`
- `AGENTMEMORY_RUNTIME_DIR`
diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json
index 7ba2ceb9..fad86a8d 100644
--- a/scripts/docs-sync.state.json
+++ b/scripts/docs-sync.state.json
@@ -20,13 +20,13 @@
"12"
],
"tests": [
- "2900+"
+ "3000+"
],
"functions": [
"312"
],
"sourceFiles": [
- "227"
+ "228"
],
"loc": [
"54000"
diff --git a/scripts/release-gate/startup.mjs b/scripts/release-gate/startup.mjs
new file mode 100644
index 00000000..1dc75a03
--- /dev/null
+++ b/scripts/release-gate/startup.mjs
@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { spawn, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import http from "node:http";
+import net from "node:net";
+import { arch, homedir, platform, tmpdir } from "node:os";
+import { dirname, join, resolve, delimiter } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const options = { tarball: null, out: null, only: null, keep: false, delayMs: 48_000, skipBuild: false };
+for (let i = 2; i < process.argv.length; i++) {
+ const arg = process.argv[i];
+ if (arg === "--tarball") options.tarball = resolve(process.argv[++i]);
+ else if (arg === "--out") options.out = resolve(process.argv[++i]);
+ else if (arg === "--only") options.only = new Set(process.argv[++i].split(","));
+ else if (arg === "--delay-ms") options.delayMs = Number(process.argv[++i]);
+ else if (arg === "--keep") options.keep = true;
+ else if (arg === "--skip-build") options.skipBuild = true;
+ else if (arg === "--help") {
+ console.log("Usage: node scripts/release-gate/startup.mjs [--tarball file.tgz] [--out dir] [--only names] [--delay-ms 48000] [--skip-build] [--keep]");
+ process.exit(0);
+ } else throw new Error(`Unknown argument ${arg}`);
+}
+assert(Number.isSafeInteger(options.delayMs) && options.delayMs > 0 && options.delayMs <= 300_000, "--delay-ms must be 1..300000");
+const root = mkdtempSync(join(tmpdir(), "am-startup-"));
+const out = options.out ?? mkdtempSync(join(tmpdir(), "agentmemory-startup-gate-"));
+mkdirSync(out, { recursive: true });
+const prefix = join(root, "prefix");
+const pkg = join(prefix, "node_modules/@agentmemory/agentmemory");
+const cli = join(pkg, "dist/cli.mjs");
+const nodeDir = dirname(process.execPath);
+const cache = process.env.AGENTMEMORY_GATE_CACHE ?? join(homedir(), ".cache/agentmemory-release-gate");
+const children = new Set();
+const instances = new Set();
+const results = [];
+const started = Date.now();
+const log = (message) => {
+ const line = `[${((Date.now() - started) / 1000).toFixed(1)}s] ${message}`;
+ console.log(line);
+ appendFileSync(join(out, "gate.log"), `${line}\n`);
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sha = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
+function packageDigest() {
+ const files = [];
+ const walk = (dir, relative = "") => { for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const name = relative ? `${relative}/${entry.name}` : entry.name;
+ if (entry.isDirectory()) walk(join(dir, entry.name), name);
+ else if (entry.isFile()) files.push([name, sha(join(dir, entry.name))]);
+ } };
+ walk(pkg); files.sort(([a], [b]) => a.localeCompare(b));
+ return createHash("sha256").update(JSON.stringify(files)).digest("hex");
+}
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+function kill(pid, signal = "SIGKILL") {
+ if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) return;
+ try { process.kill(-pid, signal); } catch {}
+ try { process.kill(pid, signal); } catch {}
+}
+function launch(command, args, env, cwd, logFile) {
+ const child = spawn(command, args, { env, cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+ children.add(child);
+ child.text = "";
+ child.result = null;
+ const record = (chunk) => { child.text += chunk; if (logFile) appendFileSync(logFile, chunk); };
+ child.stdout.on("data", record);
+ child.stderr.on("data", record);
+ child.on("error", (err) => record(String(err)));
+ child.on("close", (code, signal) => { child.result = { code, signal }; children.delete(child); });
+ return child;
+}
+async function exited(child, timeoutMs = 30_000) {
+ const deadline = Date.now() + timeoutMs;
+ while (!child.result && Date.now() < deadline) await sleep(25);
+ if (!child.result) { kill(child.pid); throw new Error(`process exceeded ${timeoutMs}ms: ${child.text.slice(-1000)}`); }
+ return child.result;
+}
+async function command(bin, args, env = process.env, cwd = repo, timeout = 120_000, logFile) {
+ const child = launch(bin, args, env, cwd, logFile);
+ const result = await exited(child, timeout);
+ assert.equal(result.code, 0, `${bin} ${args.join(" ")}: ${child.text.slice(-1200)}`);
+ return child.text;
+}
+async function poll(label, probe, timeoutMs = 90_000) {
+ const deadline = Date.now() + timeoutMs;
+ let last;
+ do {
+ try { const value = await probe(); if (value) return value; } catch (err) { last = err; if (err.fatal) throw err; }
+ await sleep(100);
+ } while (Date.now() < deadline);
+ throw new Error(`${label} timed out: ${last?.message ?? "not ready"}`);
+}
+async function unusedPort() {
+ const server = net.createServer();
+ await new Promise((r, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", r); });
+ const port = server.address().port;
+ await new Promise((r) => server.close(r));
+ return port;
+}
+async function free(port) {
+ const server = net.createServer();
+ return new Promise((r) => { server.once("error", () => r(false)); server.listen(port, "127.0.0.1", () => server.close(() => r(true))); });
+}
+async function portBlock() {
+ for (let i = 0; i < 200; i++) {
+ const port = 12000 + Math.floor(Math.random() * 7000);
+ if ((await Promise.all([0, 1, 2, 3, 6353, 46023].map((d) => free(port + d)))).every(Boolean)) return port;
+ }
+ throw new Error("No free port block");
+}
+let installed;
+let tarball;
+let artifactSha;
+let cliSha;
+let pkgSha;
+let engine;
+function baseEnv(home) {
+ return { HOME: home, PATH: [join(prefix, "node_modules/.bin"), nodeDir, "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(delimiter), TMPDIR: tmpdir(), CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", EMBEDDING_PROVIDER: "none", LLM_PROVIDER: "none", III_TELEMETRY_ENABLED: "false" };
+}
+async function install() {
+ tarball = options.tarball;
+ if (!tarball) {
+ if (!options.skipBuild) await command("npm", ["run", "build"], process.env, repo, 600_000, join(out, "build.log"));
+ const packDir = join(root, "pack"); mkdirSync(packDir);
+ const packed = await command("npm", ["pack", "--json", "--pack-destination", packDir]);
+ tarball = join(packDir, JSON.parse(packed)[0].filename);
+ }
+ artifactSha = sha(tarball);
+ mkdirSync(prefix, { recursive: true });
+ writeFileSync(join(prefix, "package.json"), '{"name":"startup-gate-prefix","private":true}\n');
+ const installHome = join(root, "install-home"); mkdirSync(installHome);
+ const npmCache = execFileSync("npm", ["config", "get", "cache"], { encoding: "utf8" }).trim();
+ log(`installing exact tarball ${tarball}`);
+ await command("npm", ["install", "--no-audit", "--no-fund", "--no-package-lock", tarball], { ...baseEnv(installHome), npm_config_cache: npmCache }, prefix, 600_000, join(out, "install.log"));
+ installed = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
+ engine = process.env.AGENTMEMORY_GATE_ENGINE ?? join(cache, `iii-${installed.dependencies["iii-sdk"]}-${platform()}-${arch()}`);
+ assert(existsSync(engine), `Pinned engine missing: ${engine}. Run the standard release gate once, or set AGENTMEMORY_GATE_ENGINE.`);
+ const version = await command(engine, ["--version"]);
+ assert(version.includes(installed.dependencies["iii-sdk"]), `Engine version mismatch: ${version}`);
+ cliSha = sha(cli); pkgSha = packageDigest();
+ const cliVersion = await command(process.execPath, [cli, "--version"], baseEnv(installHome));
+ assert.equal(cliVersion.trim(), installed.version);
+}
+class Instance {
+ constructor(name) {
+ this.name = name; this.dir = join(root, name); this.home = join(this.dir, "home"); this.data = join(this.dir, "data"); this.runtime = join(this.home, ".agentmemory");
+ for (const dir of [this.home, this.data, this.runtime]) mkdirSync(dir, { recursive: true });
+ this.logFile = join(out, `${name}.log`); this.envExtra = {}; this.handles = []; this.ownedPids = new Set(); this.dockerProject = null;
+ instances.add(this);
+ }
+ async init() {
+ this.port = await portBlock();
+ const binDir = join(this.runtime, "bin"); mkdirSync(binDir, { recursive: true }); copyFileSync(engine, join(binDir, "iii")); chmodSync(join(binDir, "iii"), 0o755);
+ return this;
+ }
+ env(extra = {}) { return { ...baseEnv(this.home), AGENTMEMORY_DATA_DIR: this.data, AGENTMEMORY_RUNTIME_DIR: this.runtime, III_REST_PORT: String(this.port), III_STREAM_PORT: String(this.port + 1), III_VIEWER_PORT: String(this.port + 2), III_ENGINE_PORT: String(this.port + 46023), AGENTMEMORY_METRICS_PORT: String(this.port + 6353), ...this.envExtra, ...extra }; }
+ get url() { return `http://127.0.0.1:${this.port}`; }
+ pid(name) { try { return Number(readFileSync(join(this.runtime, `${name}.pid`), "utf8").trim()); } catch { return null; } }
+ config({ delayMs = 0, earlyPid = false, worker = true } = {}) {
+ let raw = readFileSync(join(pkg, "iii-config.yaml"), "utf8").split(" - name: iii-exec")[0];
+ raw = raw.replaceAll("3111", String(this.port)).replaceAll("3112", String(this.port + 1)).replaceAll("3113", String(this.port + 2)).replaceAll("./data/", `${this.data}/`);
+ raw += ` - name: iii-worker-manager\n config:\n port: ${this.port + 46023}\n host: 127.0.0.1\n`;
+ if (worker) {
+ const wrapper = join(this.dir, "delayed-worker.mjs");
+ writeFileSync(wrapper, `import { appendFileSync, writeFileSync } from 'node:fs';\nappendFileSync(${JSON.stringify(join(this.dir, "worker-starts.jsonl"))}, JSON.stringify({pid:process.pid,at:Date.now()})+'\\n');\n${earlyPid ? `writeFileSync(${JSON.stringify(join(this.runtime, "worker.pid"))}, String(process.pid));` : ""}\nawait new Promise(r=>setTimeout(r,${delayMs}));\nawait import(${JSON.stringify(pathToFileURL(join(pkg, "dist/index.mjs")).href)});\n`);
+ raw += ` - name: iii-exec\n config:\n exec:\n - ${process.execPath} ${wrapper}\n`;
+ }
+ const file = join(this.dir, "iii-config.yaml"); writeFileSync(file, raw); this.envExtra.AGENTMEMORY_III_CONFIG = file; if (worker) this.envExtra.AGENTMEMORY_ENGINE_MANAGES_WORKER = "true"; return file;
+ }
+ start(args = [], env = {}) {
+ this.cli = launch(process.execPath, [cli, ...args, "--port", String(this.port)], this.env(env), this.dir, this.logFile);
+ this.ownedPids.add(this.cli.pid); return this.cli;
+ }
+ async startEngine(config) {
+ this.engine = launch(engine, ["--config", config, "--no-update-check"], this.env(), this.dir, this.logFile);
+ this.ownedPids.add(this.engine.pid);
+ await poll("external engine", async () => (await fetch(`${this.url}/`, { signal: AbortSignal.timeout(500) })).status > 0, 20_000);
+ writeFileSync(join(this.runtime, "engine-state.json"), JSON.stringify({ kind: "native", configPath: config, binPath: engine, restPort: this.port, attached: true }));
+ writeFileSync(join(this.runtime, "iii.pid"), String(this.engine.pid));
+ }
+ async ready(timeout = 90_000, requireHint = true, allowDoctorDiagnosticsFailure = false) {
+ await poll(this.name, async () => {
+ if (!allowDoctorDiagnosticsFailure && this.cli.result?.code && this.cli.result.code !== 0) { const err = new Error(`CLI exited ${this.cli.result.code}: ${this.cli.text.slice(-1100)}`); err.fatal = true; throw err; }
+ if (requireHint && !this.cli.text.includes("REST API")) return false;
+ const response = await fetch(`${this.url}/agentmemory/livez`, { signal: AbortSignal.timeout(1000) });
+ if (!response.ok) return false;
+ const body = await response.json(); return body.viewerPort || body.viewerSkipped;
+ }, timeout);
+ }
+ wrapperStarts() { try { return readFileSync(join(this.dir, "worker-starts.jsonl"), "utf8").trim().split("\n").map(JSON.parse); } catch { return []; } }
+ async close() {
+ if (this.closed) return; this.closed = true;
+ for (const handle of this.handles) { handle.closeAllConnections?.(); handle.close(); }
+ if (this.dockerProject) await command(this.dockerBin, ["compose", "-p", this.dockerProject, "-f", join(pkg, "docker-compose.yml"), "down", "--volumes"], this.env(), this.dir, 30_000, this.logFile).catch((err) => log(`${this.name} Docker cleanup: ${err.message}`));
+ for (const name of ["worker", "iii"]) { const pid = this.pid(name); if (pid) this.ownedPids.add(pid); }
+ for (const row of this.wrapperStarts()) this.ownedPids.add(row.pid);
+ for (const pid of this.ownedPids) kill(pid);
+ await sleep(100);
+ }
+}
+async function scenario(name, fn) {
+ if (options.only && !options.only.has(name)) return;
+ log(`RUN ${name}`); const at = Date.now(); const details = {}; let instance;
+ try { instance = await new Instance(name).init(); await fn(instance, details); const status = details.skipped ? "skipped" : "pass"; results.push({ name, status, ms: Date.now() - at, details }); log(`${status.toUpperCase()} ${name}${details.skipped ? `: ${details.skipped}` : ""}`); }
+ catch (err) { results.push({ name, status: "fail", ms: Date.now() - at, error: err.stack, details }); log(`FAIL ${name}: ${err.message}`); }
+ finally { if (instance) await instance.close(); }
+}
+async function delayedConfigured(instance, details, { delayMs, earlyPid = false, adopt = false, args = [] } = {}) {
+ const config = instance.config({ delayMs, earlyPid });
+ if (adopt) await instance.startEngine(config);
+ const at = Date.now(); instance.start(args); await instance.ready(delayMs + 25_000);
+ details.readyMs = Date.now() - at; details.delayMs = delayMs; details.transport = "real pinned native engine and installed worker via custom delayed-import config";
+ assert(details.readyMs >= delayMs - 1000, `Ready before configured worker delay: ${details.readyMs}`);
+ const starts = instance.wrapperStarts(); assert.equal(starts.length, 1, "Configured worker launched more than once");
+ assert.equal(instance.pid("worker"), starts[0].pid, "CLI imported a second worker instead of waiting for the configured worker");
+ details.workerPid = starts[0].pid; details.enginePid = instance.pid("iii");
+}
+async function delayedSocket(instance, backendPort, delayMs) {
+ const connections = new Set();
+ let accepted = 0;
+ const server = net.createServer((socket) => {
+ accepted++; connections.add(socket); socket.pause();
+ const timer = setTimeout(() => {
+ if (socket.destroyed) return;
+ const upstream = net.connect(backendPort, "127.0.0.1"); connections.add(upstream);
+ upstream.on("connect", () => { socket.pipe(upstream); upstream.pipe(socket); socket.resume(); });
+ upstream.on("error", () => socket.destroy()); socket.on("error", () => upstream.destroy());
+ socket.on("close", () => upstream.destroy()); upstream.on("close", () => connections.delete(upstream));
+ }, delayMs);
+ socket.on("close", () => { clearTimeout(timer); connections.delete(socket); });
+ socket.on("error", () => {});
+ });
+ server.closeAllConnections = () => { for (const socket of connections) socket.destroy(); };
+ await new Promise((r) => server.listen(0, "127.0.0.1", r)); instance.handles.push(server);
+ return { port: server.address().port, accepted: () => accepted };
+}
+async function fixtureServer(instance, livez) {
+ let probes = 0;
+ const server = http.createServer((req, res) => {
+ if (req.url === "/agentmemory/livez") {
+ probes++;
+ if (probes === 1) { res.writeHead(404); res.end(); return; }
+ livez(req, res, probes - 1); return;
+ }
+ res.writeHead(200, { "content-type": "application/json" }); res.end("{}");
+ });
+ await new Promise((r) => server.listen(instance.port, "127.0.0.1", r)); instance.handles.push(server);
+ const sleeper = launch(process.execPath, ["-e", "setInterval(()=>{},1000)"], instance.env(), instance.dir);
+ instance.ownedPids.add(sleeper.pid); writeFileSync(join(instance.runtime, "worker.pid"), String(sleeper.pid));
+ instance.config({ worker: false });
+ writeFileSync(join(instance.runtime, "engine-state.json"), JSON.stringify({ kind: "native", configPath: instance.envExtra.AGENTMEMORY_III_CONFIG, binPath: engine, restPort: instance.port, attached: true }));
+ return { worker: sleeper, probes: () => probes };
+}
+async function expectFailure(instance, args, env, { budgetMs = 5000, message } = {}) {
+ const at = Date.now(); const child = instance.start(args, env); const result = await exited(child, budgetMs);
+ assert.notEqual(result.code, 0, `CLI incorrectly succeeded: ${child.text}`);
+ if (message) assert(child.text.includes(message), `Missing ${message}: ${child.text.slice(-1500)}`);
+ return { elapsedMs: Date.now() - at, exitCode: result.code };
+}
+function dockerFixture(instance, mode) {
+ const fixtureBin = join(instance.dir, "fixture-bin"); mkdirSync(fixtureBin);
+ const project = `agentmemory-${instance.port}`; const containerId = "startup-fixture-owned-container";
+ const record = { Id: containerId, State: { Running: false }, Config: { Image: `iiidev/iii:${installed.dependencies["iii-sdk"]}`, Labels: { "com.docker.compose.project": project, "com.docker.compose.service": "iii-engine" } }, HostConfig: { PortBindings: { [`${instance.port}/tcp`]: [{ HostPort: String(instance.port) }] } }, Mounts: [{ Type: "bind", Source: instance.data, Destination: "/data" }] };
+ const pidFile = join(instance.dir, "docker-stub.pid");
+ const file = join(fixtureBin, "docker");
+ writeFileSync(file, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nconst args=process.argv.slice(2);\nif(args[0]===${JSON.stringify(mode)}) { writeFileSync(${JSON.stringify(pidFile)},String(process.pid)); process.on('SIGTERM',()=>{}); setInterval(()=>{},1000); }\nelse if(args[0]==='inspect') console.log(${JSON.stringify(JSON.stringify([record]))});\nelse if(args.includes('ps')) console.log(${JSON.stringify(containerId)});\n`); chmodSync(file, 0o755);
+ instance.envExtra.PATH = [fixtureBin, instance.env().PATH].join(delimiter);
+ writeFileSync(join(instance.runtime, "engine-state.json"), JSON.stringify({ kind: "docker", schemaVersion: 2, composeFile: join(pkg, "docker-compose.yml"), projectName: project, engineVersion: installed.dependencies["iii-sdk"], restPort: instance.port, dataDir: instance.data, containerId, dataMountType: "bind", dataMountSource: instance.data, preserveContainer: mode === "inspect" }));
+ return pidFile;
+}
+async function main() {
+ await install();
+ await scenario("slow-native", (i, d) => delayedConfigured(i, d, { delayMs: options.delayMs, earlyPid: true }));
+ await scenario("configured-adoption", (i, d) => delayedConfigured(i, d, { delayMs: 8_000, adopt: true }));
+ await scenario("unrelated-exec", async (i, d) => {
+ const config = i.config({ worker: false });
+ const other = join(i.dir, "unrelated-worker.mjs"); writeFileSync(other, "setInterval(()=>{},1000);\n");
+ appendFileSync(config, ` - name: iii-exec\n config:\n exec:\n - ${process.execPath} ${other}\n`);
+ const at = Date.now(); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }); await i.ready(8_000);
+ d.readyMs = Date.now() - at; assert.equal(i.pid("worker"), i.cli.pid, "Unrelated exec prevented the CLI-owned worker from starting");
+ d.transport = "real engine with unrelated iii-exec command plus installed CLI-owned worker";
+ });
+ await scenario("native-engine-timeout", async (i, d) => {
+ i.config({ worker: false });
+ const binary = join(i.runtime, "bin/iii"); const launchPid = join(i.dir, "launched-engine.pid");
+ writeFileSync(binary, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nif(process.argv.includes('--version')) { console.log('iii ${installed.dependencies["iii-sdk"]}'); process.exit(0); }\nwriteFileSync(${JSON.stringify(launchPid)},String(process.pid));\nsetInterval(()=>{},1000);\n`); chmodSync(binary, 0o755);
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
+ const pid = Number(readFileSync(launchPid, "utf8")); i.ownedPids.add(pid); await poll("owned engine timeout cleanup", () => !alive(pid), 5_000);
+ assert(!existsSync(join(i.runtime, "iii.pid"))); assert(!existsSync(join(i.runtime, "engine-state.json")));
+ d.transport = "version-compatible engine executable fixture that stays alive without opening HTTP; actual installed CLI";
+ });
+ await scenario("untracked-native-adoption", async (i, d) => {
+ const config = i.config({ worker: false }); const externalConfig = join(i.dir, "external-config.yaml");
+ copyFileSync(config, externalConfig); rmSync(config); await i.startEngine(externalConfig);
+ delete i.envExtra.AGENTMEMORY_III_CONFIG;
+ rmSync(join(i.runtime, "engine-state.json")); rmSync(join(i.runtime, "iii.pid"));
+ i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }); await i.ready(6_000);
+ assert.equal(i.pid("worker"), i.cli.pid, "Untracked engine was assumed to own a configured worker");
+ assert(alive(i.engine.pid)); d.transport = "real native engine without lifecycle metadata or AgentMemory exec config";
+ });
+ await scenario("cancel-owned-startup", async (i, d) => {
+ i.config({ delayMs: 10_000, earlyPid: true }); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
+ await poll("owned engine ready before cancellation", async () => i.pid("worker") && (await fetch(i.url, { signal: AbortSignal.timeout(500) })).status > 0, 5_000);
+ const enginePid = i.pid("iii"); const workerPid = i.pid("worker");
+ i.cli.kill("SIGINT"); const result = await exited(i.cli, 6_000); assert.equal(result.code, 130, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);
+ await poll("cancelled owned process cleanup", () => !alive(enginePid) && !alive(workerPid), 5_000);
+ d.exitCode = result.code; d.ownedEngineStopped = true;
+ });
+ await scenario("cancel-external-startup", async (i, d) => {
+ await i.startEngine(i.config({ worker: false })); const proxy = await delayedSocket(i, i.port + 46023, 10_000);
+ i.start(["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${proxy.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
+ await poll("worker connecting before cancellation", () => proxy.accepted() > 0, 5_000);
+ i.cli.kill("SIGTERM"); const result = await exited(i.cli, 6_000); assert.equal(result.code, 143, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);
+ assert(alive(i.engine.pid), "Cancellation stopped an external engine"); d.exitCode = result.code; d.externalEnginePreserved = true;
+ });
+ await scenario("no-engine", async (i, d) => {
+ await i.startEngine(i.config({ worker: false }));
+ const socket = await delayedSocket(i, i.port + 46023, 3_000);
+ const at = Date.now(); i.start(["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${socket.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "10000" });
+ await i.ready(15_000); d.readyMs = Date.now() - at; d.delayedConnections = socket.accepted();
+ assert(d.readyMs >= 3000); assert(d.delayedConnections > 0); assert(alive(i.engine.pid), "External engine stopped during no-engine startup");
+ const worker = i.pid("worker");
+ const duplicate = launch(process.execPath, [cli, "--no-engine", "--port", String(i.port)], i.env(), i.dir, i.logFile);
+ const result = await exited(duplicate, 5_000); assert.notEqual(result.code, 0); assert(duplicate.text.includes("already running"));
+ assert.equal(i.pid("worker"), worker); assert(alive(worker)); assert(alive(i.engine.pid));
+ d.duplicateExitCode = result.code; d.transport = "real native engine and installed worker over delayed TCP proxy";
+ });
+ await scenario("no-engine-timeout", async (i, d) => {
+ await i.startEngine(i.config({ worker: false }));
+ const socket = await delayedSocket(i, i.port + 46023, 5_000);
+ Object.assign(d, await expectFailure(i, ["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${socket.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
+ assert(alive(i.engine.pid), "Timeout stopped an externally owned engine");
+ assert(!i.pid("worker") || !alive(i.pid("worker")), "Failed in-process worker left a live stale PID");
+ d.externalEnginePreserved = true;
+ });
+ await scenario("inline-worker-fatal", async (i, d) => {
+ i.config({ worker: false }); mkdirSync(join(i.runtime, "secret"));
+ const child = i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "10000" });
+ const enginePid = await poll("owned engine PID before worker initialization", () => i.pid("iii"), 3_000); i.ownedPids.add(enginePid);
+ const result = await exited(child, 6_000); assert.equal(result.code, 1); assert(child.text.includes("[agentmemory] Fatal:"), "Fixture did not exercise the worker's fatal initialization path");
+ await poll("fatal initialization engine cleanup", () => !alive(enginePid), 4_000);
+ assert(!i.pid("iii")); assert(!i.pid("worker") || !alive(i.pid("worker")));
+ d.exitCode = result.code; d.ownedEngineStopped = true; d.transport = "real engine and inline installed worker; secret path occupied by a directory causes initialization failure";
+ });
+ await scenario("native-worker-timeout", async (i, d) => {
+ i.config({ delayMs: 5_000, earlyPid: true });
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
+ await poll("owned engine cleanup", () => (!i.pid("iii") || !alive(i.pid("iii"))) && (!i.pid("worker") || !alive(i.pid("worker"))), 5_000);
+ assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Failed owned engine still serves REST");
+ d.ownedEngineStopped = true;
+ });
+ await scenario("hung-livez-body", async (i, d) => {
+ const f = await fixtureServer(i, (_req, res) => { res.writeHead(200, { "content-type": "application/json" }); res.write('{"viewerPort":'); });
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 2_000, message: "0.3s" }));
+ assert(alive(f.worker.pid)); d.externalWorkerPreserved = true; d.probes = f.probes(); d.transport = "controlled HTTP headers with a stalled response body; external worker PID fixture";
+ });
+ await scenario("malformed-livez", async (i, d) => {
+ const invalid = ["not json", JSON.stringify({ viewerPort: -1 }), JSON.stringify({ viewerPort: 0 }), JSON.stringify({ viewerPort: 65536 }), JSON.stringify({ viewerPort: 3000.5 }), JSON.stringify({ viewerSkipped: "true" }), JSON.stringify({ viewerPort: null, viewerSkipped: false })];
+ const f = await fixtureServer(i, (_req, res, n) => { res.writeHead(200, { "content-type": "application/json" }); res.end(invalid[n - 1] ?? JSON.stringify({ viewerSkipped: true })); });
+ i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "6000" });
+ await poll("CLI readiness hint", () => i.cli.text.includes("REST API"), 7_000);
+ assert(f.probes() >= invalid.length + 2, `Malformed readiness accepted after ${f.probes()} probes`); await i.ready(1_000); d.probes = f.probes(); d.invalidResponses = invalid.length; d.transport = "controlled readiness response fixture";
+ });
+ await scenario("env-file-and-precedence", async (i, d) => {
+ const f = await fixtureServer(i, (_req, res) => { res.writeHead(503); res.end(); });
+ writeFileSync(join(i.runtime, ".env"), "AGENTMEMORY_READY_TIMEOUT_MS=350\nAGENTMEMORY_ENGINE_READY_TIMEOUT_MS=1000\n");
+ d.fromFile = await expectFailure(i, [], {}, { budgetMs: 2500, message: "0.35s" });
+ d.shellOverride = await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "150" }, { budgetMs: 2000, message: "0.15s" });
+ assert(alive(f.worker.pid)); d.transport = "controlled unready external worker fixture";
+ });
+ await scenario("invalid-timeouts", async (i, d) => {
+ d.rejected = [];
+ for (const key of ["AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", "AGENTMEMORY_READY_TIMEOUT_MS"]) {
+ for (const value of ["", "0", "-1", "1.5", "NaN", "Infinity", "500ms", "3600001"]) {
+ const result = await expectFailure(i, ["--no-engine"], { [key]: value }, { budgetMs: 2500, message: key });
+ d.rejected.push({ key, value, ...result });
+ assert(!existsSync(join(i.runtime, "worker.pid")), "Invalid timeout imported the worker");
+ }
+ }
+ const ownership = await expectFailure(i, ["--no-engine"], { AGENTMEMORY_ENGINE_MANAGES_WORKER: "yes" }, { budgetMs: 2500, message: "AGENTMEMORY_ENGINE_MANAGES_WORKER" });
+ d.invalidOwnership = ownership;
+ const help = await command(process.execPath, [cli, "--help"], i.env({ AGENTMEMORY_READY_TIMEOUT_MS: "invalid" }), i.dir);
+ assert(help.includes("Usage:"));
+ });
+ await scenario("doctor", async (i, d) => {
+ i.config({ delayMs: 2_000, earlyPid: true });
+ writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=15000\n");
+ const at = Date.now();
+ const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) });
+ await poll("doctor worker ready", () => child.text.includes("Engine and agentmemory worker ready"), 30_000);
+ const result = await exited(child, 10_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`); d.doctorExitCode = result.code;
+ await i.ready(10_000, false, true); assert(alive(i.pid("worker")), "Doctor-owned worker stopped when doctor exited"); d.readyMs = Date.now() - at; d.transport = "real native engine, configured delayed worker, installed doctor --all";
+ assert(d.readyMs >= 2000); assert.equal(i.wrapperStarts().length, 1);
+ });
+ await scenario("doctor-invalid-timeout", async (i, d) => {
+ await i.startEngine(i.config({ worker: false }));
+ writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=invalid\n");
+ Object.assign(d, await expectFailure(i, ["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) }, { budgetMs: 10_000, message: "AGENTMEMORY_READY_TIMEOUT_MS" }));
+ assert(alive(i.engine.pid), "Invalid doctor startup configuration stopped an existing engine");
+ assert.equal(i.pid("iii"), i.engine.pid, "Invalid doctor configuration changed the external engine PID"); d.externalEnginePreserved = true;
+ });
+ await scenario("doctor-cli-worker", async (i, d) => {
+ i.config({ worker: false });
+ writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=15000\n");
+ const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) });
+ await poll("doctor detached worker ready", () => child.text.includes("Engine and agentmemory worker ready"), 30_000);
+ const result = await exited(child, 10_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`);
+ await i.ready(10_000, false, true); assert(alive(i.pid("worker")), "Doctor-owned worker stopped when doctor exited");
+ assert.notEqual(i.pid("worker"), child.pid, "Doctor did not detach the CLI-owned worker");
+ d.doctorExitCode = result.code; d.workerPid = i.pid("worker"); d.transport = "real native engine and installed detached worker created by doctor --all";
+ });
+ await scenario("hung-docker-start", async (i, d) => {
+ const pidFile = dockerFixture(i, "start");
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { budgetMs: 3000 }));
+ const pid = Number(readFileSync(pidFile, "utf8")); i.ownedPids.add(pid); assert(!alive(pid), "Timed-out Docker start subprocess survived");
+ assert(existsSync(join(i.runtime, "engine-state.json")), "Docker command timeout discarded owned lifecycle metadata");
+ d.transport = "Docker command fixture whose start subprocess ignores SIGTERM; actual installed CLI";
+ });
+ await scenario("hung-docker-inspect", async (i, d) => {
+ const pidFile = dockerFixture(i, "inspect");
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { budgetMs: 8_000, message: "cannot be verified" }));
+ const pid = Number(readFileSync(pidFile, "utf8")); i.ownedPids.add(pid); assert(!alive(pid), "Timed-out Docker inspect subprocess survived");
+ assert(existsSync(join(i.runtime, "engine-state.json"))); d.transport = "Docker inspect subprocess fixture ignoring SIGTERM; actual installed CLI";
+ });
+ await scenario("docker", async (i, d) => {
+ let dockerBin;
+ try { dockerBin = execFileSync("which", ["docker"], { encoding: "utf8" }).trim(); } catch { d.skipped = "Docker executable unavailable"; return; }
+ let host;
+ try { host = process.env.DOCKER_HOST ?? execFileSync(dockerBin, ["context", "inspect", "--format", '{{(index .Endpoints "docker").Host}}'], { encoding: "utf8" }).trim(); } catch { d.skipped = "Docker context unavailable"; return; }
+ i.dockerBin = dockerBin;
+ i.envExtra = { AGENTMEMORY_USE_DOCKER: "1", DOCKER_HOST: host, DOCKER_CONFIG: process.env.DOCKER_CONFIG ?? join(homedir(), ".docker"), PATH: [dirname(dockerBin), i.env().PATH].join(delimiter) };
+ try { d.serverVersion = (await command(dockerBin, ["info", "--format", "{{.ServerVersion}}"], i.env(), i.dir, 10_000)).trim(); } catch { d.skipped = "Docker daemon unavailable"; return; }
+ let project;
+ for (let attempt = 0; attempt < 20; attempt++) {
+ const candidate = `agentmemory-${i.port}`;
+ const filter = `label=com.docker.compose.project=${candidate}`;
+ const existing = await Promise.all([
+ command(dockerBin, ["ps", "-aq", "--filter", filter], i.env(), i.dir),
+ command(dockerBin, ["network", "ls", "-q", "--filter", filter], i.env(), i.dir),
+ command(dockerBin, ["volume", "ls", "-q", "--filter", filter], i.env(), i.dir),
+ ]);
+ if (existing.every((value) => !value.trim())) { project = candidate; break; }
+ i.port = await portBlock();
+ }
+ assert(project, "Could not reserve an unused Docker project");
+ i.dockerProject = project;
+ const at = Date.now(); i.start([], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
+ await i.ready(90_000); d.freshReadyMs = Date.now() - at;
+ const state = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); assert.equal(state.kind, "docker");
+ const containerId = (await command(dockerBin, ["compose", "-p", i.dockerProject, "-f", join(pkg, "docker-compose.yml"), "ps", "-q", "iii-engine"], i.env(), i.dir)).trim(); assert(containerId);
+ d.containerId = containerId;
+ kill(i.cli.pid); await exited(i.cli, 3_000);
+ await command(dockerBin, ["stop", "--time", "3", containerId], i.env(), i.dir, 15_000);
+ const failedProxy = await delayedSocket(i, i.port + 46023, 10_000);
+ d.stoppedRecoveryTimeout = await expectFailure(i, [], { III_ENGINE_URL: `ws://127.0.0.1:${failedProxy.port}`, AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 20_000, message: "0.3s" });
+ const stopped = await command(dockerBin, ["inspect", "--format", "{{.State.Running}}", containerId], i.env(), i.dir); assert.equal(stopped.trim(), "false", "Failed recovery did not stop the container it restarted");
+ assert.equal(JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")).containerId, containerId, "Failed Docker recovery lost lifecycle ownership");
+ const proxy = await delayedSocket(i, i.port + 46023, 3_000);
+ const restartAt = Date.now(); i.start([], { III_ENGINE_URL: `ws://127.0.0.1:${proxy.port}`, AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
+ await i.ready(30_000); d.recoveryReadyMs = Date.now() - restartAt;
+ assert(d.recoveryReadyMs >= 3000); assert(proxy.accepted() > 0);
+ const restored = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); assert.equal(restored.containerId, containerId);
+ kill(i.cli.pid); await exited(i.cli, 3_000);
+ const externalProxy = await delayedSocket(i, i.port + 46023, 10_000);
+ d.runningEngineTimeout = await expectFailure(i, [], { III_ENGINE_URL: `ws://127.0.0.1:${externalProxy.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 5_000, message: "0.3s" });
+ const running = await command(dockerBin, ["inspect", "--format", "{{.State.Running}}", containerId], i.env(), i.dir); assert.equal(running.trim(), "true", "Failed attach stopped a preexisting running Docker engine");
+ d.transport = "real Docker Compose pinned iii image; same owned container restarted; installed host worker over delayed TCP proxy";
+ });
+ await scenario("demo", async (i, d) => {
+ i.config({ delayMs: 2_000, earlyPid: true }); const at = Date.now();
+ const child = i.start(["demo", "--serve"], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
+ const result = await exited(child, 35_000); assert.equal(result.code, 0, child.text.slice(-1200)); assert(child.text.includes("demo complete"));
+ d.completedMs = Date.now() - at; d.transport = "real native engine and installed demo command";
+ assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Demo-owned engine survived teardown");
+ });
+}
+
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(signal, () => {
+ for (const i of instances) {
+ for (const name of ["iii", "worker"]) kill(i.pid(name));
+ for (const row of i.wrapperStarts()) kill(row.pid);
+ for (const pid of i.ownedPids) kill(pid);
+ if (i.dockerProject && !i.closed) {
+ try { execFileSync(i.dockerBin, ["compose", "-p", i.dockerProject, "-f", join(pkg, "docker-compose.yml"), "down", "--volumes"], { env: i.env(), timeout: 30_000, stdio: "ignore" }); } catch {}
+ }
+ }
+ for (const child of children) kill(child.pid);
+ process.exit(130);
+});
+let fatal;
+try { await main(); } catch (err) { fatal = err.stack; log(fatal); }
+finally { for (const i of instances) await i.close(); for (const child of children) kill(child.pid); }
+const unchanged = cliSha ? cliSha === sha(cli) && pkgSha === packageDigest() && artifactSha === sha(tarball) : false;
+const summary = { ok: !fatal && unchanged && results.some((r) => r.status === "pass") && results.every((r) => r.status !== "fail"), version: installed?.version, enginePin: installed?.dependencies["iii-sdk"], tarball, tarballSha256: artifactSha, installedCliSha256: cliSha, installedPackageSha256: pkgSha, installedArtifactUnmodified: unchanged, node: process.version, platform: `${platform()}-${arch()}`, durationMs: Date.now() - started, root: options.keep ? root : undefined, scenarios: results, fatal };
+writeFileSync(join(out, "summary.json"), JSON.stringify(summary, null, 2) + "\n");
+log(`Summary: ${results.filter((r) => r.status === "pass").length}/${results.length} passed; ${join(out, "summary.json")}`);
+if (!options.keep && !out.startsWith(`${root}/`)) rmSync(root, { recursive: true, force: true });
+process.exit(summary.ok ? 0 : 1);
diff --git a/src/cli.ts b/src/cli.ts
index d626a8c6..34e2c79e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -71,13 +71,25 @@ import {
} from "./cli/engine-launch.js";
import { runtimeMetadataPath } from "./runtime-paths.js";
import { createStartupStderrCapture } from "./cli/startup-stderr.js";
+import {
+ configStartsAgentmemoryWorker,
+ probeEngine,
+ probeWorker,
+ startWorkerAndWait,
+ startupDeadline,
+ startupTimeoutMessage,
+ startupTimeouts,
+ waitForReadiness,
+ withinStartupDeadline,
+ type StartupDeadline,
+} from "./cli/readiness.js";
import {
clearPersistedBuiltinConfig,
engineFlushWaitMs,
engineStateConfigPaths,
renderEngineConfig,
} from "./cli/engine-config.js";
-import { SHUTDOWN_HARD_EXIT_MS } from "./shutdown.js";
+import { SHUTDOWN_HARD_EXIT_MS, registerStartupCleanup, runStartupCleanup } from "./shutdown.js";
import { consoleArgs, defaultConsolePort, parseConsoleArgs } from "./cli/console.js";
import { processStatIsRunning } from "./cli/process-state.js";
import { renderSplash } from "./cli/splash.js";
@@ -255,6 +267,14 @@ Environment:
AGENTMEMORY_III_CONFIG Engine config to start from (default: ./iii-config.yaml,
then ~/.agentmemory/iii-config.yaml, then the bundled
loopback-only config).
+ AGENTMEMORY_ENGINE_READY_TIMEOUT_MS
+ Engine readiness deadline in milliseconds (default 120000).
+ AGENTMEMORY_READY_TIMEOUT_MS
+ Worker readiness deadline in milliseconds (default 300000).
+ Both deadlines accept integers from 1 through 3600000.
+ AGENTMEMORY_ENGINE_MANAGES_WORKER
+ true for custom engine-managed worker wrappers; false
+ for CLI-managed workers. Unset detects direct worker commands.
AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS
Window (seconds) for the smart-search follow-up diagnostic
(default 30). Long values overcount, short values undercount.
@@ -459,36 +479,17 @@ function getEnginePort(): number {
}
async function isEngineRunning(): Promise<boolean> {
- try {
- await fetch(`${getBaseUrl()}/`, {
- signal: AbortSignal.timeout(2000),
- });
- return true;
- } catch {
- return false;
- }
+ const result = await withinStartupDeadline(startupDeadline(2000), (signal) => probeEngine(getBaseUrl(), signal)).catch(() => null);
+ return result?.completed === true && result.value;
}
async function isAgentmemoryReady(): Promise<boolean> {
- try {
- const res = await fetch(`${getBaseUrl()}/agentmemory/livez`, {
- signal: AbortSignal.timeout(2000),
- });
- if (!res.ok) return false;
- try {
- const data = await res.json() as { viewerPort?: number | null; viewerSkipped?: boolean };
- if (typeof data.viewerPort === "number") {
- discoveredViewerPort = data.viewerPort;
- return true;
- }
- if (data.viewerSkipped) return true;
- return false;
- } catch {
- return false;
- }
- } catch {
- return false;
- }
+ const result = await withinStartupDeadline(startupDeadline(2000), workerReadinessProbe).catch(() => null);
+ return result?.completed === true && result.value;
+}
+
+function workerReadinessProbe(signal: AbortSignal): Promise<boolean> {
+ return probeWorker(getBaseUrl(), signal, (port) => { discoveredViewerPort = port; });
}
function findIiiConfig(): string {
@@ -767,36 +768,65 @@ function engineStateRestPort(state: EngineState): number {
return 3111;
}
-async function startWorkerForEngineState(): Promise<void> {
- const workerPid = readWorkerPidfile();
- if (workerPid && pidAlive(workerPid)) return;
- if (configuredEngineMayStartWorker() && await waitForConfiguredWorker(5000)) {
- return;
+async function startWorkerForEngineState(background = false): Promise<void> {
+ const timeoutMs = startupTimeouts().workerMs;
+ startupWorkerFailure = null;
+ const ready = await startWorkerAndWait({
+ timeoutMs,
+ hasLiveWorker: () => {
+ const workerPid = readWorkerPidfile();
+ return Boolean(workerPid && pidAlive(workerPid));
+ },
+ engineStartsWorker: configuredEngineMayStartWorker,
+ startWorker: async () => {
+ if (background) {
+ const builtEntry = join(__dirname, "index.mjs");
+ const workerArgs = existsSync(builtEntry)
+ ? [builtEntry]
+ : ["--import", "tsx", join(__dirname, "index.ts")];
+ const child = spawn(process.execPath, workerArgs, {
+ detached: true,
+ stdio: "ignore",
+ windowsHide: true,
+ env: { ...process.env },
+ });
+ spawnedStartupWorker = child;
+ child.on("error", (error) => {
+ if (spawnedStartupWorker === child) startupWorkerFailure = error;
+ });
+ child.on("exit", (code, signal) => {
+ if (spawnedStartupWorker === child) startupWorkerFailure = new Error(`agentmemory worker exited during startup (${signal ?? code}).`);
+ });
+ child.unref();
+ } else {
+ importedStartupWorker = true;
+ await import("./index.js");
+ }
+ },
+ probe: workerReadinessProbe,
+ stopped: () => startupInterrupted || engineStartupFailed() || startupWorkerFailure !== null,
+ });
+ if (!ready) {
+ if (startupWorkerFailure) throw startupWorkerFailure;
+ if (engineStartupFailed()) throw new Error("iii-engine exited before the agentmemory worker became ready.");
+ throw new Error(startupTimeoutMessage("worker", timeoutMs));
}
- await import("./index.js");
+ finishStartup();
}
function configuredEngineMayStartWorker(): boolean {
+ const explicit = startupTimeouts().engineManagesWorker;
+ if (explicit !== undefined) return explicit;
const state = readEngineState();
- if (state?.kind !== "native") return false;
+ if (state?.kind !== "native" || state.attached) return false;
try {
const raw = readFileSync(state.configPath, "utf-8");
- return raw.includes("- name: iii-exec");
+ return configStartsAgentmemoryWorker(raw, join(__dirname, "index.mjs"));
} catch {
return false;
}
}
-async function waitForConfiguredWorker(timeoutMs: number): Promise<boolean> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- const workerPid = readWorkerPidfile();
- if (workerPid && pidAlive(workerPid)) return true;
- if (await isAgentmemoryReady()) return true;
- await new Promise((resolve) => setTimeout(resolve, 100));
- }
- return false;
-}
function discoverComposeFile(): string | null {
const candidates = [
@@ -856,6 +886,8 @@ function inspectDockerContainer(
encoding: "utf-8",
stdio: ["ignore", "pipe", "ignore"],
maxBuffer: 1024 * 1024,
+ timeout: 5000,
+ killSignal: "SIGKILL",
});
if (result.status !== 0) {
return { status: "unavailable", reason: `docker inspect failed for ${containerId}` };
@@ -1025,7 +1057,7 @@ function inspectOwnedDockerEngine(state: EngineState): DockerEngineInspection {
"--all",
"iii-engine",
]),
- { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+ { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, killSignal: "SIGKILL" },
);
if (psResult.status === 0) {
for (const id of (psResult.stdout ?? "").trim().split(/\s+/)) {
@@ -1052,7 +1084,7 @@ function inspectOwnedDockerEngine(state: EngineState): DockerEngineInspection {
const scanResult = spawnSync(
dockerBin,
scanArgs,
- { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+ { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, killSignal: "SIGKILL" },
);
if (scanResult.status === 0) {
for (const id of (scanResult.stdout ?? "").trim().split(/\s+/)) {
@@ -1383,6 +1415,92 @@ type StartupFailure = {
let startupFailure: StartupFailure | null = null;
let activeStartupStderr = createStartupStderrCapture();
+let spawnedNativeEngine: ChildProcess | null = null;
+let importedStartupWorker = false;
+let spawnedStartupWorker: ChildProcess | null = null;
+let startupWorkerFailure: Error | null = null;
+let spawnedDockerCommand: ChildProcess | null = null;
+let startedDockerEngine: DockerEngineState | null = null;
+let engineReadinessDeadline: StartupDeadline | null = null;
+let startupInterrupted = false;
+let finishStartup = (): void => {};
+
+function beginStartup(): void {
+ finishStartup();
+ startupInterrupted = false;
+ const unregister = registerStartupCleanup(cleanupFailedStartup);
+ const interrupt = async (exitCode: number): Promise<void> => {
+ startupInterrupted = true;
+ process.exit(await runStartupCleanup(exitCode).catch(() => exitCode));
+ };
+ const onInterrupt = () => { void interrupt(130); };
+ const onTerminate = () => { void interrupt(143); };
+ process.on("SIGINT", onInterrupt);
+ process.on("SIGTERM", onTerminate);
+ finishStartup = () => {
+ process.off("SIGINT", onInterrupt);
+ process.off("SIGTERM", onTerminate);
+ unregister();
+ finishStartup = () => {};
+ };
+}
+
+function engineStartupFailed(): boolean {
+ return startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed";
+}
+
+async function cleanupFailedStartup(): Promise<void> {
+ engineReadinessDeadline = null;
+ if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();
+ const worker = spawnedStartupWorker;
+ spawnedStartupWorker = null;
+ if (worker && typeof worker.pid === "number") {
+ if (worker.exitCode === null && worker.signalCode === null && !(await signalAndWait(worker.pid, "SIGTERM", 3000))) {
+ p.log.warn(`Started worker pid ${worker.pid} survived shutdown; lifecycle state was preserved.`);
+ return;
+ }
+ if (readWorkerPidfile() === worker.pid) clearWorkerPidfile();
+ }
+ const dockerCommand = spawnedDockerCommand;
+ spawnedDockerCommand = null;
+ if (dockerCommand && typeof dockerCommand.pid === "number" && dockerCommand.exitCode === null && dockerCommand.signalCode === null) {
+ await signalAndWait(dockerCommand.pid, "SIGTERM", 1000);
+ }
+ const dockerState = startedDockerEngine;
+ startedDockerEngine = null;
+ if (dockerState) {
+ const inspection = inspectOwnedDockerEngine(dockerState);
+ if (inspection.status === "running" || inspection.status === "stopped") {
+ persistDockerInspection(dockerState, inspection);
+ const dockerBin = whichBinary("docker");
+ if (inspection.status === "running" && dockerBin) {
+ runCommand(dockerBin, ["stop", "--time", "10", inspection.containerId], {
+ label: "Stopping the Docker container started by this invocation",
+ timeoutMs: 15_000,
+ });
+ }
+ } else {
+ p.log.warn("Docker startup ownership could not be verified for cleanup; project state was preserved for `agentmemory stop`.");
+ }
+ }
+ const child = spawnedNativeEngine;
+ spawnedNativeEngine = null;
+ if (!child || typeof child.pid !== "number") return;
+ if (!IS_WINDOWS) {
+ try { process.kill(-child.pid, "SIGTERM"); } catch {}
+ }
+ if (child.exitCode === null && child.signalCode === null) {
+ const stopped = await signalAndWait(child.pid, "SIGTERM", 3000);
+ if (!stopped) {
+ p.log.warn(`Started engine pid ${child.pid} survived shutdown; lifecycle state was preserved.`);
+ return;
+ }
+ }
+ if (readEnginePidfile() === child.pid) {
+ clearEnginePidfile();
+ clearEngineState();
+ }
+}
function printCapturedStartupStderr(): void {
const stderr = redactCredentialUrls(activeStartupStderr.text().trim());
@@ -1410,6 +1528,7 @@ function printDockerStartupLogs(): void {
encoding: "utf-8",
stdio: ["ignore", "pipe", "pipe"],
timeout: 5000,
+ killSignal: "SIGKILL",
maxBuffer: 64 * 1024,
},
);
@@ -1429,6 +1548,8 @@ function spawnEngineBackground(
): ChildProcess {
vlog(`spawn: ${bin} ${spawnArgs.join(" ")}${cwd ? ` (cwd: ${cwd})` : ""}`);
activeStartupStderr = createStartupStderrCapture();
+ startupFailure = null;
+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
const child = spawn(bin, spawnArgs, {
detached: true,
stdio: ["ignore", "ignore", "pipe"],
@@ -1437,15 +1558,31 @@ function spawnEngineBackground(
...(cwd ? { cwd } : {}),
});
const isDocker = label.includes("Docker");
- if (!isDocker && typeof child.pid === "number") {
- writeEnginePidfile(child.pid);
- }
+ if (isDocker) spawnedDockerCommand = child;
+ if (!isDocker) {
+ spawnedNativeEngine = child;
+ if (typeof child.pid === "number") writeEnginePidfile(child.pid);
+ }
+ child.on("error", (error) => {
+ if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;
+ startupFailure = {
+ kind: isDocker ? "docker-crashed" : "engine-crashed",
+ stderr: redactCredentialUrls(error.message),
+ binary: bin,
+ };
+ if (!isDocker && spawnedNativeEngine === child) {
+ clearEnginePidfile();
+ clearEngineState();
+ }
+ });
child.stderr?.on("data", (chunk: Buffer) => {
+ if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;
activeStartupStderr.append(chunk);
});
+ (child.stderr as { unref?: () => void } | null)?.unref?.();
child.on("exit", (code, signal) => {
- const abnormal =
- (code !== null && code !== 0) || (code === null && signal !== null);
+ if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;
+ const abnormal = !isDocker || (code !== null && code !== 0) || (code === null && signal !== null);
if (abnormal) {
const stderr = redactCredentialUrls(activeStartupStderr.text());
startupFailure = {
@@ -1461,7 +1598,7 @@ function spawnEngineBackground(
if (IS_VERBOSE && stderr.trim()) {
p.log.error(`engine stderr:\n${stderr}`);
}
- if (!isDocker) {
+ if (!isDocker && readEnginePidfile() === child.pid) {
clearEnginePidfile();
clearEngineState();
}
@@ -1607,6 +1744,8 @@ function warnIfDockerIgnoresStateBackend(stateBackendKind: "file" | "redis"): vo
}
async function startEngine(): Promise<boolean> {
+ startupFailure = null;
+ engineReadinessDeadline = null;
let stateBackendKind: "file" | "redis";
try {
stateBackendKind = getStateBackend();
@@ -1638,12 +1777,13 @@ async function startEngine(): Promise<boolean> {
persistDockerInspection(persistedState, inspection);
if (inspection.status === "running") return true;
const dockerBin = whichBinary("docker");
- return Boolean(
- dockerBin &&
- runCommand(dockerBin, ["start", inspection.containerId], {
- label: `Restarting owned Docker container ${inspection.containerId}`,
- }),
- );
+ if (!dockerBin) return false;
+ startedDockerEngine = persistDockerInspection(persistedState, inspection);
+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
+ return runCommand(dockerBin, ["start", inspection.containerId], {
+ label: `Restarting owned Docker container ${inspection.containerId}`,
+ timeoutMs: startupTimeouts().engineMs,
+ });
}
const configPath = findIiiConfig();
warnIfRelocatedDataDir();
@@ -1775,7 +1915,7 @@ async function startEngine(): Promise<boolean> {
s.start("Starting iii-engine via Docker...");
configureDockerHostUser();
const projectName = dockerProjectName(getRestPort());
- writeEngineState({
+ const dockerState: DockerEngineState = {
kind: "docker",
schemaVersion: 2,
composeFile,
@@ -1784,7 +1924,14 @@ async function startEngine(): Promise<boolean> {
dataMountType: "bind",
dataMountSource: dataDirResolution.dataDir,
preserveContainer: false,
- });
+ };
+ const previous = inspectOwnedDockerEngine(dockerState);
+ if (previous.status === "missing" || previous.status === "stopped") {
+ startedDockerEngine = previous.status === "stopped"
+ ? persistDockerInspection(dockerState, previous)
+ : dockerState;
+ }
+ writeEngineState(dockerState);
spawnEngineBackground(
dockerBin,
dockerComposeArgs(composeFile, projectName, ["up", "-d"]),
@@ -1802,13 +1949,19 @@ async function startEngine(): Promise<boolean> {
return false;
}
-async function waitForEngine(timeoutMs: number): Promise<boolean> {
- const start = Date.now();
- while (Date.now() - start < timeoutMs) {
- if (await isEngineRunning()) return true;
- await new Promise((r) => setTimeout(r, 500));
- }
- return false;
+async function waitForEngine(timeoutMs = startupTimeouts().engineMs): Promise<boolean> {
+ return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), (signal) => probeEngine(getBaseUrl(), signal), {
+ intervalMs: 500,
+ stopped: () => startupInterrupted || engineStartupFailed(),
+ });
+}
+
+async function waitForPersistedNativeEngine(): Promise<boolean> {
+ const state = readEngineState();
+ const pid = readEnginePidfile();
+ if (state?.kind !== "native" || !pid || !pidAlive(pid) || isForeignPortHolder(pidCommand(pid))) return false;
+ if (!(await waitForEngine())) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
+ return true;
}
async function reconcilePersistedDockerEngine(): Promise<boolean> {
@@ -1829,29 +1982,24 @@ async function reconcilePersistedDockerEngine(): Promise<boolean> {
}
persistDockerInspection(state, inspection);
if (inspection.status === "stopped") {
+ startedDockerEngine = persistDockerInspection(state, inspection);
+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
const dockerBin = whichBinary("docker");
if (
!dockerBin ||
!runCommand(dockerBin, ["start", inspection.containerId], {
label: `Restarting owned Docker container ${inspection.containerId}`,
+ timeoutMs: startupTimeouts().engineMs,
})
) {
- p.log.error("The owned Docker container could not be restarted; lifecycle state was preserved.");
- process.exit(1);
+ throw new Error("The owned Docker container could not be restarted; lifecycle state was preserved.");
}
}
- if (!(await waitForEngine(5000))) {
+ if (!(await waitForEngine())) {
printDockerStartupLogs();
- p.log.error(
- `The owned Docker container is running, but its REST API on port ${getRestPort()} is unhealthy. The saved project was preserved; inspect the Docker logs above or run \`agentmemory stop\`.`,
- );
- process.exit(1);
+ throw new Error(`${startupTimeoutMessage("engine", startupTimeouts().engineMs)} Docker ownership state was preserved.`);
}
await startWorkerForEngineState();
- if (!(await waitForAgentmemoryReady(15000))) {
- p.log.error("agentmemory worker did not become ready within 15s.");
- process.exit(1);
- }
await maybeOfferGlobalInstall();
printReadyHint();
return true;
@@ -1907,14 +2055,6 @@ function portInUseDiagnostic(port: number): string {
: ` lsof -i :${port} # or: ss -tlnp | grep :${port}`;
}
-async function waitForAgentmemoryReady(timeoutMs: number): Promise<boolean> {
- const start = Date.now();
- while (Date.now() - start < timeoutMs) {
- if (await isAgentmemoryReady()) return true;
- await new Promise((r) => setTimeout(r, 250));
- }
- return false;
-}
// Derive a host string for the streams/engine WebSocket lines from
// the configured engine URL (`III_ENGINE_URL`) or REST base
@@ -1970,6 +2110,7 @@ function printReadyHint(): void {
}
async function main() {
+ startupTimeouts();
await assertRuntimePortOwnership();
// Booting a second instance next to a live daemon registers a duplicate
// worker on the running engine, and before iii 0.19.2 the second instance's
@@ -2011,19 +2152,19 @@ async function main() {
await runOnboarding();
}
+ beginStartup();
+
if (skipEngine) {
if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
- await import("./index.js");
- if (await waitForAgentmemoryReady(15000)) {
- await maybeOfferGlobalInstall();
- printReadyHint();
- }
+ await startWorkerForEngineState();
+ await maybeOfferGlobalInstall();
+ printReadyHint();
return;
}
if (await reconcilePersistedDockerEngine()) return;
- if (await isEngineRunning()) {
+ if (await isEngineRunning() || await waitForPersistedNativeEngine()) {
if (IS_VERBOSE) p.log.success("iii-engine is running");
// Prefer the binary path persisted at launch time over whatever's on
// PATH now. PATH lookups misfire when a global iii install gets added
@@ -2050,10 +2191,6 @@ async function main() {
if (detected === IIPINNED_VERSION) {
adoptRunningEngine();
await startWorkerForEngineState();
- if (!(await waitForAgentmemoryReady(15000))) {
- p.log.error("agentmemory worker did not become ready within 15s.");
- process.exit(1);
- }
await maybeOfferGlobalInstall();
printReadyHint();
return;
@@ -2106,16 +2243,16 @@ async function main() {
);
}
p.note(lines.join("\n"), "Setup required");
- process.exit(1);
+ throw new Error("iii-engine could not be started.");
}
const s = p.spinner();
s.start("Waiting for iii-engine to be ready...");
- const ready = await waitForEngine(15000);
+ const ready = await waitForEngine();
if (!ready) {
const port = getRestPort();
- s.stop("iii-engine did not become ready within 15s");
+ s.stop(startupTimeoutMessage("engine", startupTimeouts().engineMs));
printDockerStartupLogs();
if (startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed") {
@@ -2156,15 +2293,11 @@ async function main() {
"Troubleshooting",
);
}
- process.exit(1);
+ throw new Error(engineStartupFailed() ? "iii-engine failed during startup." : startupTimeoutMessage("engine", startupTimeouts().engineMs));
}
s.stop(c.ok("iii-engine is ready"));
await startWorkerForEngineState();
- if (!(await waitForAgentmemoryReady(15000))) {
- p.log.error("agentmemory worker did not become ready within 15s.");
- process.exit(1);
- }
await maybeOfferGlobalInstall();
printReadyHint();
// Mark splash as something to skip on subsequent runs. This is a
@@ -2440,6 +2573,7 @@ function buildDoctorEffects(): DoctorEffects {
},
runStop: async () => {
try {
+ startupTimeouts();
// runStop calls process.exit on its own — guard against that here
// by short-circuiting when there's nothing to stop.
const port = getRestPort();
@@ -2473,14 +2607,16 @@ function buildDoctorEffects(): DoctorEffects {
},
runStart: async () => {
try {
+ startupTimeouts();
+ beginStartup();
const started = await startEngine();
- if (!started) return { ok: false, message: "startEngine() returned false" };
- const ready = await waitForEngine(15000);
- return {
- ok: ready,
- message: ready ? "Engine ready" : "Engine did not become ready within 15s",
- };
+ if (!started) throw new Error("iii-engine could not be started.");
+ if (!(await waitForEngine())) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
+ await startWorkerForEngineState(true);
+ return { ok: true, message: "Engine and agentmemory worker ready" };
} catch (err) {
+ await runStartupCleanup(1);
+ finishStartup();
return {
ok: false,
message: err instanceof Error ? err.message : String(err),
@@ -2978,50 +3114,34 @@ async function runInit() {
}
async function startServerForDemo(): Promise<() => Promise<void>> {
+ startupTimeouts();
await assertRuntimePortOwnership();
if (await isAgentmemoryReady()) {
return async () => {};
}
- const startedEngine = !(await isEngineRunning());
+ beginStartup();
+
+ const startedEngine = !skipEngine && !(await isEngineRunning() || await waitForPersistedNativeEngine());
if (startedEngine) {
const ok = await startEngine();
if (!ok) {
p.log.error("Could not start iii-engine for the demo.");
p.note(installInstructions().join("\n"), "Setup required");
- process.exit(1);
+ throw new Error("iii-engine could not be started for the demo.");
}
- if (!(await waitForEngine(15000))) {
+ if (!(await waitForEngine())) {
printCapturedStartupStderr();
printDockerStartupLogs();
- p.log.error("iii-engine did not become ready within 15s.");
- process.exit(1);
+ throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
}
}
await startWorkerForEngineState();
- if (!(await waitForAgentmemoryReady(15000))) {
- p.log.error("agentmemory worker did not become ready within 15s.");
- process.exit(1);
- }
return async () => {
- if (!startedEngine) return;
- const port = getRestPort();
- const state = readEngineState();
- if (state?.kind === "docker") {
- await stopDockerEngine(state, port).catch(() => {});
- return;
- }
- const pids = new Set<number>(findEnginePidsByPort(port));
- const pidfilePid = readEnginePidfile();
- if (pidfilePid) pids.add(pidfilePid);
- for (const pid of pids) {
- await signalAndWait(pid, "SIGTERM", 3000).catch(() => {});
- }
- clearEnginePidfile();
- clearEngineState();
- clearWorkerPidfile();
+ if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();
+ if (startedEngine) await cleanupFailedStartup();
};
}
@@ -3123,7 +3243,7 @@ async function runDemoBody(base: string) {
function runCommand(
command: string,
commandArgs: string[],
- options: { cwd?: string; label: string; optional?: boolean } = { label: "command" },
+ options: { cwd?: string; label: string; optional?: boolean; timeoutMs?: number } = { label: "command" },
): boolean {
const spinner = p.spinner();
spinner.start(options.label);
@@ -3131,6 +3251,7 @@ function runCommand(
cwd: options.cwd || process.cwd(),
stdio: "pipe",
encoding: "utf-8",
+ ...(options.timeoutMs !== undefined ? { timeout: options.timeoutMs, killSignal: "SIGKILL" as const } : {}),
});
if (result.status === 0) {
@@ -4136,7 +4257,8 @@ async function unknownCommand(): Promise<void> {
// `agentmemory consolidate`) fell through to the full server boot and could
// break a running daemon.
const handler = commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main);
-handler().catch((err) => {
+handler().catch(async (err) => {
p.log.error(err instanceof Error ? err.message : String(err));
- process.exit(1);
+ const exitCode = await runStartupCleanup(1).catch(() => 1);
+ process.exit(exitCode);
});
diff --git a/src/cli/readiness.ts b/src/cli/readiness.ts
new file mode 100644
index 00000000..e7ca0fb9
--- /dev/null
+++ b/src/cli/readiness.ts
@@ -0,0 +1,173 @@
+export const DEFAULT_ENGINE_TIMEOUT_MS = 120_000;
+export const DEFAULT_WORKER_TIMEOUT_MS = 300_000;
+export const MAX_STARTUP_TIMEOUT_MS = 3_600_000;
+
+export function startupTimeouts(env: NodeJS.ProcessEnv = process.env): {
+ engineMs: number;
+ workerMs: number;
+ engineManagesWorker: boolean | undefined;
+} {
+ const parse = (key: string, fallback: number): number => {
+ const raw = env[key];
+ if (raw === undefined) return fallback;
+ const value = Number(raw);
+ if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1 || value > MAX_STARTUP_TIMEOUT_MS) {
+ throw new Error(`${key} must be an integer between 1 and ${MAX_STARTUP_TIMEOUT_MS} milliseconds.`);
+ }
+ return value;
+ };
+ const ownership = env.AGENTMEMORY_ENGINE_MANAGES_WORKER;
+ if (ownership !== undefined && ownership !== "true" && ownership !== "false") {
+ throw new Error("AGENTMEMORY_ENGINE_MANAGES_WORKER must be true or false.");
+ }
+ return {
+ engineMs: parse("AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", DEFAULT_ENGINE_TIMEOUT_MS),
+ workerMs: parse("AGENTMEMORY_READY_TIMEOUT_MS", DEFAULT_WORKER_TIMEOUT_MS),
+ engineManagesWorker: ownership === undefined ? undefined : ownership === "true",
+ };
+}
+
+export function configStartsAgentmemoryWorker(raw: string, workerEntry: string): boolean {
+ const lines = raw.split(/\r?\n/);
+ let workerIndent: number | undefined;
+ let execIndent: number | undefined;
+ for (const line of lines) {
+ if (!line.trim() || line.trimStart().startsWith("#")) continue;
+ const indent = line.length - line.trimStart().length;
+ if (workerIndent !== undefined && indent <= workerIndent) {
+ workerIndent = undefined;
+ execIndent = undefined;
+ }
+ if (/^\s*-\s+name:\s*(?:iii-exec|"iii-exec"|'iii-exec')(?:\s+#.*)?\s*$/.test(line)) {
+ workerIndent = indent;
+ continue;
+ }
+ if (workerIndent === undefined) continue;
+ if (execIndent !== undefined && indent <= execIndent) execIndent = undefined;
+ if (/^\s*exec:\s*(?:#.*)?$/.test(line)) {
+ execIndent = indent;
+ continue;
+ }
+ if (execIndent === undefined) continue;
+ const scalar = line.match(/^\s*-\s+(.+)$/)?.[1]?.trim();
+ if (!scalar) continue;
+ const quoted = scalar.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+ const command = quoted ? quoted[2]! : scalar;
+ const tokens = command.match(/"[^"]*"|'[^']*'|[^\s]+/g)?.map((token) => token.replace(/^("|')(.*)\1$/, "$2").replaceAll("\\", "/"));
+ if (!tokens) continue;
+ const comment = tokens.findIndex((token) => token.startsWith("#"));
+ if (comment !== -1) tokens.splice(comment);
+ const runtime = tokens[0]?.split("/").at(-1);
+ if (runtime !== "node" && runtime !== "node.exe" && runtime !== "tsx") continue;
+ if (runtime !== "tsx") {
+ while (tokens[1] && /^(?:--max[-_]old[-_]space[-_]size=\d+|--enable-source-maps|--no-warnings)$/.test(tokens[1])) tokens.splice(1, 1);
+ }
+ const entry = tokens.length === 2
+ ? tokens[1]
+ : tokens.length === 4 && tokens[1] === "--import" && tokens[2] === "tsx" ? tokens[3] : undefined;
+ if (entry === workerEntry.replaceAll("\\", "/") || entry === "dist/index.mjs" || entry === "./dist/index.mjs" || entry === "src/index.ts" || entry === "./src/index.ts") return true;
+ }
+ return false;
+}
+
+export function startupTimeoutMessage(kind: "engine" | "worker", timeoutMs: number): string {
+ const name = kind === "engine" ? "iii-engine" : "agentmemory worker";
+ const variable = kind === "engine" ? "AGENTMEMORY_ENGINE_READY_TIMEOUT_MS" : "AGENTMEMORY_READY_TIMEOUT_MS";
+ return `${name} did not become ready within ${timeoutMs / 1000}s. Set ${variable} to allow more startup time.`;
+}
+
+export interface StartupDeadline {
+ remaining(): number;
+}
+
+export function startupDeadline(timeoutMs: number): StartupDeadline {
+ const deadline = performance.now() + timeoutMs;
+ return { remaining: () => Math.max(0, deadline - performance.now()) };
+}
+
+export async function withinStartupDeadline<T>(
+ deadline: StartupDeadline,
+ work: (signal: AbortSignal) => Promise<T>,
+ maximumMs = Infinity,
+): Promise<{ completed: true; value: T } | { completed: false }> {
+ const remaining = Math.min(deadline.remaining(), maximumMs);
+ if (remaining <= 0) return { completed: false };
+ const controller = new AbortController();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const expired = new Promise<{ completed: false }>((resolve) => {
+ timer = setTimeout(() => {
+ controller.abort();
+ resolve({ completed: false });
+ }, Math.ceil(remaining));
+ });
+ try {
+ const result = await Promise.race([
+ Promise.resolve().then(() => work(controller.signal)).then((value) => ({ completed: true as const, value })),
+ expired,
+ ]);
+ return deadline.remaining() > 0 ? result : { completed: false };
+ } finally {
+ clearTimeout(timer);
+ controller.abort();
+ }
+}
+
+export async function waitForReadiness(
+ deadline: StartupDeadline,
+ probe: (signal: AbortSignal) => Promise<boolean>,
+ options: { intervalMs?: number; stopped?: () => boolean } = {},
+): Promise<boolean> {
+ while (deadline.remaining() > 0 && !options.stopped?.()) {
+ const result = await withinStartupDeadline(deadline, probe, 2000).catch(() => ({ completed: false as const }));
+ if (options.stopped?.()) return false;
+ if (result.completed && result.value) return true;
+ const remaining = deadline.remaining();
+ if (remaining <= 0) break;
+ await new Promise((resolve) => setTimeout(resolve, Math.min(options.intervalMs ?? 250, remaining)));
+ }
+ return false;
+}
+
+export async function probeEngine(base: string, signal: AbortSignal): Promise<boolean> {
+ const response = await fetch(`${base}/`, { signal });
+ void response.body?.cancel().catch(() => {});
+ // The engine's root path is normally 404 until the worker registers routes.
+ return true;
+}
+
+export async function probeWorker(
+ base: string,
+ signal: AbortSignal,
+ onViewerPort?: (port: number) => void,
+): Promise<boolean> {
+ const response = await fetch(`${base}/agentmemory/livez`, { signal });
+ if (!response.ok) {
+ void response.body?.cancel().catch(() => {});
+ return false;
+ }
+ const data: unknown = await response.json();
+ if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+ const { viewerPort, viewerSkipped } = data as { viewerPort?: unknown; viewerSkipped?: unknown };
+ if (typeof viewerPort === "number" && Number.isInteger(viewerPort) && viewerPort > 0 && viewerPort <= 65535) {
+ onViewerPort?.(viewerPort);
+ return true;
+ }
+ return viewerSkipped === true;
+}
+
+export async function startWorkerAndWait(options: {
+ timeoutMs: number;
+ hasLiveWorker: () => boolean;
+ engineStartsWorker: () => boolean;
+ startWorker: () => Promise<unknown>;
+ probe: (signal: AbortSignal) => Promise<boolean>;
+ stopped?: () => boolean;
+}): Promise<boolean> {
+ const deadline = startupDeadline(options.timeoutMs);
+ if (options.stopped?.()) return false;
+ if (!options.hasLiveWorker() && !options.engineStartsWorker()) {
+ const started = await withinStartupDeadline(deadline, () => options.startWorker());
+ if (!started.completed) return false;
+ }
+ return waitForReadiness(deadline, options.probe, { stopped: options.stopped });
+}
diff --git a/src/index.ts b/src/index.ts
index 08dbb3a0..eca1b13c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -33,7 +33,7 @@ import { VectorIndex } from "./state/vector-index.js";
import type { SearchLayer } from "./state/search-layer.js";
import { HybridSearch } from "./state/hybrid-search.js";
import { IndexPersistence } from "./state/index-persistence.js";
-import { SHUTDOWN_FLUSH_TIMEOUT_MS, SHUTDOWN_HARD_EXIT_MS, settleWithin } from "./shutdown.js";
+import { SHUTDOWN_FLUSH_TIMEOUT_MS, SHUTDOWN_HARD_EXIT_MS, runStartupCleanup, settleWithin } from "./shutdown.js";
import { registerPrivacyFunction, withWriteScrubbing } from "./functions/privacy.js";
import { registerObserveFunction } from "./functions/observe.js";
import { registerCaptureFunctions } from "./functions/capture.js";
@@ -749,12 +749,12 @@ async function main() {
const shutdown = async () => {
console.log(`\n[agentmemory] Shutting down...`);
- const hardExit = setTimeout(() => {
+ const hardExit = setTimeout(async () => {
console.warn(
`[agentmemory] Shutdown still blocked after ${SHUTDOWN_HARD_EXIT_MS}ms; exiting now.`,
);
clearWorkerPidfile();
- process.exit(1);
+ process.exit(await runStartupCleanup(1).catch(() => 1));
}, SHUTDOWN_HARD_EXIT_MS);
hardExit.unref();
healthMonitor.stop();
@@ -779,13 +779,13 @@ async function main() {
console.warn(`[agentmemory] SDK shutdown failed:`, err);
});
clearWorkerPidfile();
- process.exit(0);
+ process.exit(await runStartupCleanup(0).catch(() => 1));
};
process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);
}
-main().catch((err) => {
+main().catch(async (err) => {
console.error(`[agentmemory] Fatal:`, err);
- process.exit(1);
+ process.exit(await runStartupCleanup(1).catch(() => 1));
});
diff --git a/src/shutdown.ts b/src/shutdown.ts
index 512d5a58..461c4b9c 100644
--- a/src/shutdown.ts
+++ b/src/shutdown.ts
@@ -1,6 +1,33 @@
export const SHUTDOWN_FLUSH_TIMEOUT_MS = 4000;
export const SHUTDOWN_HARD_EXIT_MS = 8000;
+interface StartupCleanup {
+ cleanup: () => Promise<void>;
+ pending?: Promise<void>;
+ exitCode?: number;
+}
+
+// The CLI and worker are built separately, but share startup ownership in one process.
+const STARTUP_CLEANUP = Symbol.for("@agentmemory/startup-cleanup");
+const startupGlobal = globalThis as typeof globalThis & { [STARTUP_CLEANUP]?: StartupCleanup };
+
+export function registerStartupCleanup(cleanup: () => Promise<void>): () => void {
+ const state: StartupCleanup = { cleanup };
+ startupGlobal[STARTUP_CLEANUP] = state;
+ return () => {
+ if (startupGlobal[STARTUP_CLEANUP] === state) delete startupGlobal[STARTUP_CLEANUP];
+ };
+}
+
+export async function runStartupCleanup(exitCode: number): Promise<number> {
+ const state = startupGlobal[STARTUP_CLEANUP];
+ if (!state) return exitCode;
+ state.exitCode ??= exitCode;
+ state.pending ??= Promise.resolve().then(state.cleanup);
+ await state.pending;
+ return state.exitCode;
+}
+
export async function settleWithin(
work: Promise<unknown>,
ms: number,
diff --git a/test/cli-engine-startup.test.ts b/test/cli-engine-startup.test.ts
index cdade606..b091484d 100644
--- a/test/cli-engine-startup.test.ts
+++ b/test/cli-engine-startup.test.ts
@@ -30,13 +30,13 @@ describe("fresh native engine startup", () => {
);
expect(spawnBody).toContain("activeStartupStderr.append(chunk)");
- const timeoutStart = source.indexOf("const ready = await waitForEngine(15000)");
+ const timeoutStart = source.indexOf("const ready = await waitForEngine()");
const timeoutEnd = source.indexOf('s.stop(c.ok("iii-engine is ready"))', timeoutStart);
expect(source.slice(timeoutStart, timeoutEnd)).toContain(
"printCapturedStartupStderr()",
);
- const demoTimeoutStart = source.indexOf("await waitForEngine(15000)", timeoutEnd);
+ const demoTimeoutStart = source.indexOf("await waitForEngine()", timeoutEnd);
const demoTimeoutEnd = source.indexOf("await import(\"./index.js\")", demoTimeoutStart);
expect(source.slice(demoTimeoutStart, demoTimeoutEnd)).toContain(
"printCapturedStartupStderr()",
@@ -88,11 +88,13 @@ describe("fresh native engine startup", () => {
const workerBody = source.slice(workerStart, workerEnd);
expect(workerBody).toContain("readWorkerPidfile()");
expect(workerBody).toContain("pidAlive(workerPid)");
- expect(workerBody).toContain("waitForConfiguredWorker");
+ expect(workerBody).toContain("startWorkerAndWait");
+ expect(workerBody).toContain("engineStartsWorker: configuredEngineMayStartWorker");
expect(workerBody).toContain('await import("./index.js")');
- expect(source.match(/await startWorkerForEngineState\(\)/g)).toHaveLength(4);
- expect(source).toContain("agentmemory worker did not become ready within 15s");
+ expect(source.match(/await startWorkerForEngineState\(\)/g)).toHaveLength(5);
+ expect(source).toContain('startupTimeoutMessage("worker", timeoutMs)');
+ expect(source).not.toContain("waitForAgentmemoryReady(15000)");
});
it("stores lifecycle metadata per resolved instance and scopes Docker", () => {
@@ -125,7 +127,7 @@ describe("fresh native engine startup", () => {
const mainBody = source.slice(mainStart, mainEnd);
expect(mainBody).toContain("reconcilePersistedDockerEngine()");
expect(mainBody.indexOf("reconcilePersistedDockerEngine()"))
- .toBeLessThan(mainBody.indexOf("if (await isEngineRunning())"));
+ .toBeLessThan(mainBody.indexOf("if (await isEngineRunning() ||"));
});
it("keeps canonical compatibility and rejects Docker ownership on another port", () => {
diff --git a/test/cli-readiness.test.ts b/test/cli-readiness.test.ts
new file mode 100644
index 00000000..13f7c578
--- /dev/null
+++ b/test/cli-readiness.test.ts
@@ -0,0 +1,250 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ configStartsAgentmemoryWorker,
+ probeEngine,
+ probeWorker,
+ startWorkerAndWait,
+ startupDeadline,
+ startupTimeoutMessage,
+ startupTimeouts,
+ waitForReadiness,
+ withinStartupDeadline,
+} from "../src/cli/readiness.js";
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+});
+
+function fakeTime(): void {
+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "performance", "Date"] });
+}
+
+async function advance<T>(promise: Promise<T>, ms: number): Promise<T> {
+ await vi.advanceTimersByTimeAsync(ms);
+ return promise;
+}
+
+const forever = <T>(): Promise<T> => new Promise(() => {});
+
+function workerOptions(overrides: Partial<Parameters<typeof startWorkerAndWait>[0]> = {}) {
+ return {
+ timeoutMs: 1000,
+ hasLiveWorker: () => false,
+ engineStartsWorker: () => false,
+ startWorker: vi.fn(async () => {}),
+ probe: vi.fn(async () => true),
+ ...overrides,
+ };
+}
+
+describe("startup configuration", () => {
+ it("uses separate bounded engine and worker defaults", () => {
+ expect(startupTimeouts({})).toEqual({ engineMs: 120_000, workerMs: 300_000, engineManagesWorker: undefined });
+ });
+
+ it("reads runtime values on each call, including both boundaries", () => {
+ const env = { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "1", AGENTMEMORY_READY_TIMEOUT_MS: "3600000" };
+ expect(startupTimeouts(env)).toMatchObject({ engineMs: 1, workerMs: 3_600_000 });
+ env.AGENTMEMORY_ENGINE_READY_TIMEOUT_MS = "48000";
+ expect(startupTimeouts(env).engineMs).toBe(48_000);
+ });
+
+ it.each(["", " ", "0", "-1", "1.5", "15s", "12abc", "1e3", "NaN", "Infinity", "3600001", "9007199254740993"])("rejects invalid timeout %j for either phase", (value) => {
+ for (const key of ["AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", "AGENTMEMORY_READY_TIMEOUT_MS"]) {
+ expect(() => startupTimeouts({ [key]: value })).toThrow(`${key} must be an integer`);
+ }
+ });
+
+ it("accepts explicit worker ownership and rejects ambiguous boolean values", () => {
+ expect(startupTimeouts({ AGENTMEMORY_ENGINE_MANAGES_WORKER: "true" }).engineManagesWorker).toBe(true);
+ expect(startupTimeouts({ AGENTMEMORY_ENGINE_MANAGES_WORKER: "false" }).engineManagesWorker).toBe(false);
+ for (const value of ["", "1", "yes", "TRUE"]) {
+ expect(() => startupTimeouts({ AGENTMEMORY_ENGINE_MANAGES_WORKER: value })).toThrow("must be true or false");
+ }
+ });
+
+ it("reports the configured duration and correct setting in failures", () => {
+ expect(startupTimeoutMessage("worker", 48_050)).toContain("48.05s. Set AGENTMEMORY_READY_TIMEOUT_MS");
+ expect(startupTimeoutMessage("engine", 120_000)).toContain("120s. Set AGENTMEMORY_ENGINE_READY_TIMEOUT_MS");
+ });
+});
+
+describe("configured worker ownership", () => {
+ const config = (command: string) => `workers:\n - name: iii-exec\n config:\n exec:\n - ${command}\n - name: iii-http\n config:\n port: 3111\n`;
+ it.each(["node dist/index.mjs", "node ./dist/index.mjs", "node --import tsx src/index.ts", "tsx ./src/index.ts", '"node dist/index.mjs"', "node dist/index.mjs # worker", '"node dist/index.mjs" # worker', "node --max-old-space-size=8192 dist/index.mjs", '\'/opt/node /package/dist/index.mjs\''])("recognizes a direct worker command: %s", (command) => {
+ expect(configStartsAgentmemoryWorker(config(command), "/package/dist/index.mjs")).toBe(true);
+ });
+ it.each(["node other.mjs", "node delayed-wrapper.mjs", "echo node dist/index.mjs", "sh -c 'node dist/index.mjs'", "node dist/index.mjs && something", "node dist/index.mjs.fake"])("does not claim unrelated or wrapped command: %s", (command) => {
+ expect(configStartsAgentmemoryWorker(config(command), "/package/dist/index.mjs")).toBe(false);
+ });
+ it("ignores comments, other workers and sibling configuration lists", () => {
+ const raw = `# - name: iii-exec\n# exec:\n# - node dist/index.mjs\n - name: iii-state\n config:\n exec:\n - node dist/index.mjs\n - name: iii-exec\n config:\n exec:\n - node other.mjs\n watch:\n - node dist/index.mjs\n`;
+ expect(configStartsAgentmemoryWorker(raw, "/package/dist/index.mjs")).toBe(false);
+ });
+});
+
+describe("readiness deadlines", () => {
+ it("aborts a hung probe at the remaining budget, without a trailing retry sleep", async () => {
+ fakeTime();
+ let signal: AbortSignal | undefined;
+ const probe = vi.fn(async (value: AbortSignal) => { signal = value; return forever<boolean>(); });
+ const pending = waitForReadiness(startupDeadline(25), probe);
+ expect(await advance(pending, 25)).toBe(false);
+ expect(performance.now()).toBe(25);
+ expect(signal?.aborted).toBe(true);
+ expect(probe).toHaveBeenCalledTimes(1);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("caps individual probes and keeps retries within the total budget", async () => {
+ fakeTime();
+ const probe = vi.fn(() => forever<boolean>());
+ expect(await advance(waitForReadiness(startupDeadline(3000), probe), 3000)).toBe(false);
+ expect(probe).toHaveBeenCalledTimes(2);
+ expect(performance.now()).toBe(3000);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("includes response body consumption in the probe budget", async () => {
+ fakeTime();
+ vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true, json: () => forever() })));
+ const pending = waitForReadiness(startupDeadline(25), (signal) => probeWorker("http://local", signal));
+ expect(await advance(pending, 25)).toBe(false);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("retries errors and malformed responses before accepting viewerSkipped", async () => {
+ fakeTime();
+ const fetchMock = vi.fn()
+ .mockRejectedValueOnce(new Error("ECONNREFUSED"))
+ .mockResolvedValueOnce(new Response("not json"))
+ .mockResolvedValueOnce(Response.json({ viewerSkipped: true }));
+ vi.stubGlobal("fetch", fetchMock);
+ expect(await advance(waitForReadiness(startupDeadline(1000), (signal) => probeWorker("http://local", signal)), 500)).toBe(true);
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("accepts readiness just before the deadline", async () => {
+ fakeTime();
+ const pending = waitForReadiness(startupDeadline(100), async () => new Promise((resolve) => setTimeout(() => resolve(true), 99)));
+ expect(await advance(pending, 99)).toBe(true);
+ });
+
+ it("rejects readiness at or after the deadline even when the probe ignores abort", async () => {
+ fakeTime();
+ const pending = waitForReadiness(startupDeadline(100), async () => new Promise((resolve) => setTimeout(() => resolve(true), 100)));
+ expect(await advance(pending, 100)).toBe(false);
+ });
+
+ it("rejects late success after synchronous work exhausts the deadline", async () => {
+ const remaining = vi.fn().mockReturnValueOnce(5).mockReturnValue(0);
+ const result = await withinStartupDeadline({ remaining }, async () => true);
+ expect(result.completed).toBe(false);
+ });
+
+ it("does not let wall-clock changes extend startup", async () => {
+ fakeTime();
+ const pending = waitForReadiness(startupDeadline(25), () => forever<boolean>());
+ vi.setSystemTime(new Date("1999-01-01"));
+ expect(await advance(pending, 25)).toBe(false);
+ });
+
+ it("stops retrying after a known engine exit, including during a successful probe", async () => {
+ let stopped = false;
+ const probe = vi.fn(async () => { stopped = true; return true; });
+ expect(await waitForReadiness(startupDeadline(1000), probe, { stopped: () => stopped })).toBe(false);
+ expect(probe).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not start a probe after expiry or a known failure", async () => {
+ const probe = vi.fn(async () => true);
+ expect(await waitForReadiness(startupDeadline(0), probe)).toBe(false);
+ expect(await waitForReadiness(startupDeadline(100), probe, { stopped: () => true })).toBe(false);
+ expect(probe).not.toHaveBeenCalled();
+ });
+});
+
+describe("probe contracts", () => {
+ it("accepts the engine's root404 while discarding its response body", async () => {
+ const cancel = vi.fn(async () => {});
+ vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, body: { cancel } })));
+ expect(await probeEngine("http://local", new AbortController().signal)).toBe(true);
+ expect(cancel).toHaveBeenCalledOnce();
+ });
+
+ it.each([null, [], {}, { viewerPort: null }, { viewerPort: 0 }, { viewerPort: -1 }, { viewerPort: 1.5 }, { viewerPort: 65536 }, { viewerPort: "3113" }, { viewerSkipped: "true" }])("rejects malformed readiness body %j", async (body) => {
+ vi.stubGlobal("fetch", vi.fn(async () => Response.json(body)));
+ expect(await probeWorker("http://local", new AbortController().signal)).toBe(false);
+ });
+
+ it("publishes a valid discovered viewer port", async () => {
+ const found = vi.fn();
+ vi.stubGlobal("fetch", vi.fn(async () => Response.json({ viewerPort: 65535 })));
+ expect(await probeWorker("http://local", new AbortController().signal, found)).toBe(true);
+ expect(found).toHaveBeenCalledWith(65535);
+ });
+
+ it("requires a successful HTTP response even with a ready-shaped body", async () => {
+ vi.stubGlobal("fetch", vi.fn(async () => Response.json({ viewerSkipped: true }, { status: 503 })));
+ expect(await probeWorker("http://local", new AbortController().signal)).toBe(false);
+ });
+});
+
+describe("worker startup ownership", () => {
+ it("does not import a worker after the owned engine has already failed", async () => {
+ const options = workerOptions({ stopped: () => true });
+ expect(await startWorkerAndWait(options)).toBe(false);
+ expect(options.startWorker).not.toHaveBeenCalled();
+ expect(options.probe).not.toHaveBeenCalled();
+ });
+
+ it("starts exactly one CLI-owned worker", async () => {
+ const options = workerOptions();
+ expect(await startWorkerAndWait(options)).toBe(true);
+ expect(options.startWorker).toHaveBeenCalledOnce();
+ });
+
+ it.each(["live pid", "engine-managed"])("waits for %s without importing a duplicate", async (ownership) => {
+ fakeTime();
+ const options = workerOptions({
+ timeoutMs: 10_000,
+ hasLiveWorker: () => ownership === "live pid",
+ engineStartsWorker: () => ownership === "engine-managed",
+ probe: vi.fn(async () => performance.now() >= 8000),
+ });
+ expect(await advance(startWorkerAndWait(options), 8000)).toBe(true);
+ expect(options.startWorker).not.toHaveBeenCalled();
+ });
+
+ it("never falls back to a duplicate after an engine-managed worker times out", async () => {
+ fakeTime();
+ const options = workerOptions({ engineStartsWorker: () => true, probe: vi.fn(async () => false) });
+ expect(await advance(startWorkerAndWait(options), 1000)).toBe(false);
+ expect(options.startWorker).not.toHaveBeenCalled();
+ });
+
+ it("includes async import in the same readiness deadline", async () => {
+ fakeTime();
+ const options = workerOptions({ startWorker: vi.fn(() => forever<void>()) });
+ expect(await advance(startWorkerAndWait(options), 1000)).toBe(false);
+ expect(options.probe).not.toHaveBeenCalled();
+ });
+
+ it("does not reset the budget after a slow import", async () => {
+ fakeTime();
+ const options = workerOptions({
+ startWorker: vi.fn(() => new Promise<void>((resolve) => setTimeout(resolve, 900))),
+ probe: vi.fn(async () => false),
+ });
+ expect(await advance(startWorkerAndWait(options), 1000)).toBe(false);
+ expect(options.probe).toHaveBeenCalledTimes(1);
+ });
+
+ it("propagates import failures and removes its deadline timer", async () => {
+ fakeTime();
+ await expect(startWorkerAndWait(workerOptions({ startWorker: async () => { throw new Error("bad import"); } }))).rejects.toThrow("bad import");
+ expect(vi.getTimerCount()).toBe(0);
+ });
+});
diff --git a/test/startup-cleanup.test.ts b/test/startup-cleanup.test.ts
new file mode 100644
index 00000000..3c8584c8
--- /dev/null
+++ b/test/startup-cleanup.test.ts
@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { registerStartupCleanup, runStartupCleanup } from "../src/shutdown.js";
+
+let unregister: (() => void) | undefined;
+afterEach(() => { unregister?.(); unregister = undefined; });
+
+describe("startup-owned process cleanup", () => {
+ it("leaves normal runtime shutdown unchanged after readiness", async () => {
+ const cleanup = vi.fn(async () => {});
+ unregister = registerStartupCleanup(cleanup);
+ unregister();
+ expect(await runStartupCleanup(0)).toBe(0);
+ expect(await runStartupCleanup(1)).toBe(1);
+ expect(cleanup).not.toHaveBeenCalled();
+ });
+
+ it("coalesces fatal, signal and worker shutdown exits until the same cleanup finishes", async () => {
+ let finish!: () => void;
+ const cleanup = vi.fn(() => new Promise<void>((resolve) => { finish = resolve; }));
+ unregister = registerStartupCleanup(cleanup);
+ const interrupt = runStartupCleanup(130);
+ const fatal = runStartupCleanup(1);
+ const workerExit = runStartupCleanup(0);
+ let settled = false;
+ void workerExit.then(() => { settled = true; });
+ await Promise.resolve();
+ expect(cleanup).toHaveBeenCalledOnce();
+ expect(settled).toBe(false);
+ finish();
+ expect(await Promise.all([interrupt, fatal, workerExit])).toEqual([130, 130, 130]);
+ });
+
+ it("shares startup ownership across separately loaded module instances", async () => {
+ const cleanup = vi.fn(async () => {});
+ unregister = registerStartupCleanup(cleanup);
+ vi.resetModules();
+ const workerModule = await import("../src/shutdown.js");
+ expect(await workerModule.runStartupCleanup(1)).toBe(1);
+ expect(cleanup).toHaveBeenCalledOnce();
+ });
+
+ it("does not let an older completed attempt unregister the next attempt", async () => {
+ const clearOld = registerStartupCleanup(async () => {});
+ await runStartupCleanup(1);
+ const cleanup = vi.fn(async () => {});
+ unregister = registerStartupCleanup(cleanup);
+ clearOld();
+ expect(await runStartupCleanup(143)).toBe(143);
+ expect(cleanup).toHaveBeenCalledOnce();
+ });
+
+ it("keeps the original failure code when a later signal races with cleanup", async () => {
+ unregister = registerStartupCleanup(async () => {});
+ expect(await Promise.all([runStartupCleanup(1), runStartupCleanup(143)])).toEqual([1, 1]);
+ });
+
+ it("shares cleanup failure without running a second destructive cleanup", async () => {
+ const cleanup = vi.fn(async () => { throw new Error("cleanup failed"); });
+ unregister = registerStartupCleanup(cleanup);
+ const results = await Promise.allSettled([runStartupCleanup(1), runStartupCleanup(143)]);
+ expect(results.every((result) => result.status === "rejected")).toBe(true);
+ expect(cleanup).toHaveBeenCalledOnce();
+ });
+});