diff --git a/.env.example b/.env.example index ec8c26df3a..34dfc2ac3b 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 d7b150883e..76abbffb4a 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 5250056fa8..6a0e85ff13 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 6e58c49d0c..bd876ece28 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-.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 ` 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 b9802af2f8..9ae959fe84 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1450,7 +1450,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Custom plugin systems | `iii worker add ` | -**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 8d99334276..3cbf2965c3 100644 --- a/READMEs/README.ar-SA.md +++ b/READMEs/README.ar-SA.md @@ -73,7 +73,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1439,7 +1439,7 @@ fi | Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية | | أنظمة إضافات مخصصة | `iii worker add ` | -**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 625803cc43..6e0576ddb3 100644 --- a/READMEs/README.bn-BD.md +++ b/READMEs/README.bn-BD.md @@ -71,7 +71,7 @@ 54 MCP টুল 12 অটো হুক 0 এক্সটার্নাল ডিবি - 2,900+ টেস্ট পাস + 3,000+ টেস্ট পাস

@@ -1437,7 +1437,7 @@ fi | Prometheus / Grafana | iii OTEL + হেলথ মনিটর | | কাস্টম প্লাগইন সিস্টেম | `iii worker add ` | -**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 fe64e76606..c84d9b6972 100644 --- a/READMEs/README.cs-CZ.md +++ b/READMEs/README.cs-CZ.md @@ -71,7 +71,7 @@ 54 MCP nástrojů 12 automatických hooks 0 externích databází - 2,900+ testů úspěšně proběhlo + 3,000+ testů úspěšně proběhlo

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Vlastní systémy pluginů | `iii worker add ` | -**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 e95f52093b..e350639533 100644 --- a/READMEs/README.da-DK.md +++ b/READMEs/README.da-DK.md @@ -71,7 +71,7 @@ 54 MCP-værktøjer 12 automatiske hooks 0 eksterne databaser - 2,900+ beståede tests + 3,000+ beståede tests

@@ -1436,7 +1436,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Custom plugin-systemer | `iii worker add ` | -**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 cfa0822c3a..fb77b7636b 100644 --- a/READMEs/README.de-DE.md +++ b/READMEs/README.de-DE.md @@ -71,7 +71,7 @@ 54 MCP-Tools 12 Auto-Hooks 0 externe DBs - 2,900+ bestandene Tests + 3,000+ bestandene Tests

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + Health-Monitor | | Eigene Plugin-Systeme | `iii worker add ` | -**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 ea1d429177..28784fc04e 100644 --- a/READMEs/README.el-GR.md +++ b/READMEs/README.el-GR.md @@ -71,7 +71,7 @@ 54 εργαλεία MCP 12 αυτόματα hooks 0 εξωτερικές βάσεις δεδομένων - 2,900+ επιτυχημένες δοκιμές + 3,000+ επιτυχημένες δοκιμές

@@ -1438,7 +1438,7 @@ fi | Prometheus / Grafana | iii OTEL + monitor υγείας | | Προσαρμοσμένα συστήματα plugin | `iii worker add ` | -**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 360b77113d..3bc00ec100 100644 --- a/READMEs/README.es-ES.md +++ b/READMEs/README.es-ES.md @@ -71,7 +71,7 @@ 54 tools MCP 12 hooks automáticos 0 bases de datos externas - 2,900+ tests superados + 3,000+ tests superados

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + monitor de salud | | Sistemas de plugins propios | `iii worker add ` | -**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 ac6ae128aa..e5fe94a3c8 100644 --- a/READMEs/README.fi-FI.md +++ b/READMEs/README.fi-FI.md @@ -71,7 +71,7 @@ 54 MCP-työkalua 12 automaattista hookia 0 ulkoista tietokantaa - 2,900+ testiä läpäisty + 3,000+ testiä läpäisty

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + terveysmonitori | | Mukautetut plugin-järjestelmät | `iii worker add ` | -**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 8319c43395..9ccb54644f 100644 --- a/READMEs/README.fr-FR.md +++ b/READMEs/README.fr-FR.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1448,7 +1448,7 @@ fi | Prometheus / Grafana | iii OTEL + moniteur de santé | | Systèmes de plugins custom | `iii worker add ` | -**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 8a2e994768..c9456598f5 100644 --- a/READMEs/README.he-IL.md +++ b/READMEs/README.he-IL.md @@ -73,7 +73,7 @@ 54 כלי MCP 12 hooks אוטומטיים 0 מסדי נתונים חיצוניים - 2,900+ בדיקות עוברות + 3,000+ בדיקות עוברות

@@ -1439,7 +1439,7 @@ fi | Prometheus / Grafana | iii OTEL + מוניטור health | | מערכות plugin מותאמות אישית | `iii worker add ` | -**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 7a6c698c4b..95cb6c8bdb 100644 --- a/READMEs/README.hi-IN.md +++ b/READMEs/README.hi-IN.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1449,7 +1449,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Custom plugin systems | `iii worker add ` | -**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 1094c112cc..aaabb3866c 100644 --- a/READMEs/README.hu-HU.md +++ b/READMEs/README.hu-HU.md @@ -71,7 +71,7 @@ 54 MCP eszköz 12 automatikus hook 0 külső adatbázis - 2,900+ sikeres teszt + 3,000+ sikeres teszt

@@ -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 ` | -**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 ff5e3cf455..c94940d953 100644 --- a/READMEs/README.id-ID.md +++ b/READMEs/README.id-ID.md @@ -71,7 +71,7 @@ 54 tool MCP 12 hook otomatis 0 DB eksternal - 2,900+ pengujian lolos + 3,000+ pengujian lolos

@@ -1447,7 +1447,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Sistem plugin custom | `iii worker add ` | -**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 c85e4ac3e8..d3d09642b4 100644 --- a/READMEs/README.it-IT.md +++ b/READMEs/README.it-IT.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + monitor di salute | | Sistemi di plugin personalizzati | `iii worker add ` | -**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 043adbd7b3..3285ed0ff8 100644 --- a/READMEs/README.ja-JP.md +++ b/READMEs/README.ja-JP.md @@ -71,7 +71,7 @@ 54 MCP ツール 12 自動 hooks 外部 DB 0 個 - 2,900+ 件のテストが成功 + 3,000+ 件のテストが成功

@@ -1445,7 +1445,7 @@ fi | Prometheus / Grafana | iii OTEL + ヘルスモニタ | | カスタムプラグインシステム | `iii worker add ` | -**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 e0dadacb9d..32ec5cc84d 100644 --- a/READMEs/README.ko-KR.md +++ b/READMEs/README.ko-KR.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + health 모니터 | | 커스텀 플러그인 시스템 | `iii worker add ` | -**소스 파일 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 694280e978..878bc7055c 100644 --- a/READMEs/README.nb-NO.md +++ b/READMEs/README.nb-NO.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1447,7 +1447,7 @@ fi | Prometheus / Grafana | iii OTEL + helseovervåker | | Egendefinerte plugin-systemer | `iii worker add ` | -**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 92ca476973..1124fb7d6e 100644 --- a/READMEs/README.nl-NL.md +++ b/READMEs/README.nl-NL.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Custom plugin-systemen | `iii worker add ` | -**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 b1b98c54c9..f42eb5038f 100644 --- a/READMEs/README.pl-PL.md +++ b/READMEs/README.pl-PL.md @@ -71,7 +71,7 @@ 54 narzędzia MCP 12 automatycznych hooków 0 zewnętrznych baz danych - 2,900+ zaliczonych testów + 3,000+ zaliczonych testów

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + monitor stanu | | Niestandardowe systemy pluginów | `iii worker add ` | -**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 852cd6fc06..1dae1e6d80 100644 --- a/READMEs/README.pt-BR.md +++ b/READMEs/README.pt-BR.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1447,7 +1447,7 @@ fi | Prometheus / Grafana | iii OTEL + monitor de saúde | | Sistemas de plugin customizados | `iii worker add ` | -**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 6b82ab4de7..552cd50d80 100644 --- a/READMEs/README.pt-PT.md +++ b/READMEs/README.pt-PT.md @@ -71,7 +71,7 @@ 54 ferramentas MCP 12 hooks automáticos 0 bases de dados externas - 2,900+ testes aprovados + 3,000+ testes aprovados

@@ -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 ` | -**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 6f73b5eeb8..2a8a0d08df 100644 --- a/READMEs/README.ro-RO.md +++ b/READMEs/README.ro-RO.md @@ -71,7 +71,7 @@ 54 de instrumente MCP 12 hook-uri automate 0 baze de date externe - 2,900+ teste trecute + 3,000+ teste trecute

@@ -1430,7 +1430,7 @@ fi | Prometheus / Grafana | iii OTEL + monitor de sănătate | | Sisteme de plugin-uri personalizate | `iii worker add ` | -**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 d04a8adab7..a7300af944 100644 --- a/READMEs/README.ru-RU.md +++ b/READMEs/README.ru-RU.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1446,7 +1446,7 @@ fi | Prometheus / Grafana | iii OTEL + монитор состояния | | Самописные плагинные системы | `iii worker add ` | -**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 895aa777dc..787e74bf05 100644 --- a/READMEs/README.sv-SE.md +++ b/READMEs/README.sv-SE.md @@ -71,7 +71,7 @@ 54 MCP-verktyg 12 automatiska hooks 0 externa databaser - 2,900+ godkända tester + 3,000+ godkända tester

@@ -1437,7 +1437,7 @@ fi | Prometheus / Grafana | iii OTEL + hälsoövervakare | | Anpassade pluginsystem | `iii worker add ` | -**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 3a1ac15d2c..c70f7a9b11 100644 --- a/READMEs/README.th-TH.md +++ b/READMEs/README.th-TH.md @@ -71,7 +71,7 @@ 54 เครื่องมือ MCP 12 hook อัตโนมัติ ไม่ต้องพึ่ง external DB เลย - ผ่านการทดสอบ 2,900+ รายการ + ผ่านการทดสอบ 3,000+ รายการ

@@ -1444,7 +1444,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Custom plugin systems | `iii worker add ` | -**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 884e3ebb5f..ff12dbf842 100644 --- a/READMEs/README.tl-PH.md +++ b/READMEs/README.tl-PH.md @@ -71,7 +71,7 @@ 54 MCP tool 12 awtomatikong hook 0 panlabas na DB - 2,900+ pumapasang test + 3,000+ pumapasang test

@@ -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 ` | -**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 e44fe39b03..aae81337c8 100644 --- a/READMEs/README.tr-TR.md +++ b/READMEs/README.tr-TR.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1437,7 +1437,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Custom eklenti sistemleri | `iii worker add ` | -**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 23ed1f21ca..ef124feb5c 100644 --- a/READMEs/README.uk-UA.md +++ b/READMEs/README.uk-UA.md @@ -71,7 +71,7 @@ 54 інструменти MCP 12 автоматичних хуків 0 зовнішніх БД - 2,900+ тестів пройдено + 3,000+ тестів пройдено

@@ -1447,7 +1447,7 @@ fi | Prometheus / Grafana | iii OTEL + монітор стану здоров'я | | Власні системи плагінів | `iii worker add ` | -**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 19cf115ce3..42fb1c0d7b 100644 --- a/READMEs/README.ur-PK.md +++ b/READMEs/README.ur-PK.md @@ -73,7 +73,7 @@ 54 MCP ٹولز 12 خودکار ہکس 0 خارجی ڈیٹابیسز - 2,900+ ٹیسٹس پاس ہو رہے ہیں + 3,000+ ٹیسٹس پاس ہو رہے ہیں

@@ -1432,7 +1432,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | کسٹم plugin سسٹمز | `iii worker add ` | -**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 43c1b7691e..c754c3654b 100644 --- a/READMEs/README.vi-VN.md +++ b/READMEs/README.vi-VN.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 2,900+ tests passing + 3,000+ tests passing

@@ -1437,7 +1437,7 @@ fi | Prometheus / Grafana | iii OTEL + health monitor | | Hệ thống plugin tùy chỉnh | `iii worker add ` | -**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 94d4a82d8b..4b9dee4bed 100644 --- a/READMEs/README.zh-CN.md +++ b/READMEs/README.zh-CN.md @@ -71,7 +71,7 @@ 54 个 MCP 工具 12 个自动 hooks 0 个外部数据库 - 2,900+ 项测试通过 + 3,000+ 项测试通过

@@ -1444,7 +1444,7 @@ fi | Prometheus / Grafana | iii OTEL + 健康监控 | | Custom plugin systems | `iii worker add ` | -**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 836056007e..d4b90bcaac 100644 --- a/READMEs/README.zh-TW.md +++ b/READMEs/README.zh-TW.md @@ -71,7 +71,7 @@ 54 個 MCP 工具 12 個自動 hooks 0 個外部資料庫 - 2,900+ 測試通過 + 3,000+ 測試通過

@@ -1430,7 +1430,7 @@ fi | Prometheus / Grafana | iii OTEL + 健康監控 | | 自訂外掛系統 | `iii worker add ` | -**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 955556fbee..45fd4a824c 100644 --- a/assets/tags/light/stat-tests.svg +++ b/assets/tags/light/stat-tests.svg @@ -1,5 +1,5 @@ - + - 2900+ + 3000+ TESTS PASSING diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg index 8e120b6661..67853cf67d 100644 --- a/assets/tags/stat-tests.svg +++ b/assets/tags/stat-tests.svg @@ -1,5 +1,5 @@ - + - 2900+ + 3000+ TESTS PASSING diff --git a/package.json b/package.json index 0893be3a9a..1a9893dbcf 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 e2ab637956..f2a097836b 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. -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 7ba2ceb9a9..fad86a8df8 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 0000000000..1dc75a035d --- /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 d626a8c609..34e2c79eda 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 { - 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 { - 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 { + 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 { - const workerPid = readWorkerPidfile(); - if (workerPid && pidAlive(workerPid)) return; - if (configuredEngineMayStartWorker() && await waitForConfiguredWorker(5000)) { - return; +async function startWorkerForEngineState(background = false): Promise { + 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 { - 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 => { + 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 { + 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 { + startupFailure = null; + engineReadinessDeadline = null; let stateBackendKind: "file" | "redis"; try { stateBackendKind = getStateBackend(); @@ -1638,12 +1777,13 @@ async function startEngine(): Promise { 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 { 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 { 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 { return false; } -async function waitForEngine(timeoutMs: number): Promise { - 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 { + return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), (signal) => probeEngine(getBaseUrl(), signal), { + intervalMs: 500, + stopped: () => startupInterrupted || engineStartupFailed(), + }); +} + +async function waitForPersistedNativeEngine(): Promise { + 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 { @@ -1829,29 +1982,24 @@ async function reconcilePersistedDockerEngine(): Promise { } 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 { - 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> { + 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(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 { // `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 0000000000..e7ca0fb9bc --- /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( + deadline: StartupDeadline, + work: (signal: AbortSignal) => Promise, + 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 | 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, + options: { intervalMs?: number; stopped?: () => boolean } = {}, +): Promise { + 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 { + 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 { + 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; + probe: (signal: AbortSignal) => Promise; + stopped?: () => boolean; +}): Promise { + 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 08dbb3a02b..eca1b13ce6 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 512d5a588d..461c4b9c7a 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; + pending?: Promise; + 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 { + 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 { + 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, ms: number, diff --git a/test/cli-engine-startup.test.ts b/test/cli-engine-startup.test.ts index cdade606b2..b091484de7 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 0000000000..13f7c578c1 --- /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(promise: Promise, ms: number): Promise { + await vi.advanceTimersByTimeAsync(ms); + return promise; +} + +const forever = (): Promise => new Promise(() => {}); + +function workerOptions(overrides: Partial[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(); }); + 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()); + 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()); + 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()) }); + 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((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 0000000000..3c8584c8a9 --- /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((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(); + }); +});