From e0aaeaf5ff3cbcb46317386cdc880d157a52cd61 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 16:32:59 +0530 Subject: [PATCH 1/7] fix(cli): explain an engine that runs without the agentmemory worker When only the iii engine runs on the REST port, the agentmemory routes return 404. Status printed version v? and Health unknown, and the viewer returned 404, with no hint about the cause. Old Docker images from the legacy CLI Docker mode ran only the engine and showed this state. Status now probes /agentmemory/livez and /agentmemory/health. When both return 404, it says that the engine runs without the worker, how to start agentmemory, and where the Docker migration guide is. Doctor has a new worker-not-connected check with the same fix text. Every failing doctor check now prints its message and a fix hint, not only its id. The iii-on-path-not-local-bin check now says which iii is used, its version, and the command to run. Signed-off-by: Rohit Ghumare --- AGENTS.md | 4 +- README.md | 4 +- READMEs/README.ar-SA.md | 4 +- READMEs/README.bn-BD.md | 4 +- READMEs/README.cs-CZ.md | 4 +- READMEs/README.da-DK.md | 4 +- READMEs/README.de-DE.md | 4 +- READMEs/README.el-GR.md | 4 +- READMEs/README.es-ES.md | 4 +- READMEs/README.fi-FI.md | 4 +- READMEs/README.fr-FR.md | 4 +- READMEs/README.he-IL.md | 4 +- READMEs/README.hi-IN.md | 4 +- READMEs/README.hu-HU.md | 4 +- READMEs/README.id-ID.md | 4 +- READMEs/README.it-IT.md | 4 +- READMEs/README.ja-JP.md | 4 +- READMEs/README.ko-KR.md | 4 +- READMEs/README.nb-NO.md | 4 +- READMEs/README.nl-NL.md | 4 +- READMEs/README.pl-PL.md | 4 +- READMEs/README.pt-BR.md | 4 +- READMEs/README.pt-PT.md | 4 +- READMEs/README.ro-RO.md | 4 +- READMEs/README.ru-RU.md | 4 +- READMEs/README.sv-SE.md | 4 +- READMEs/README.th-TH.md | 4 +- READMEs/README.tl-PH.md | 4 +- READMEs/README.tr-TR.md | 4 +- READMEs/README.uk-UA.md | 4 +- READMEs/README.ur-PK.md | 4 +- READMEs/README.vi-VN.md | 4 +- READMEs/README.zh-CN.md | 4 +- READMEs/README.zh-TW.md | 4 +- assets/tags/light/stat-tests.svg | 4 +- assets/tags/stat-tests.svg | 4 +- scripts/docs-sync.state.json | 4 +- src/cli.ts | 15 +++++-- src/cli/doctor-diagnostics.ts | 55 +++++++++++++++++++++++--- src/cli/worker-connection.ts | 52 ++++++++++++++++++++++++ test/cli-doctor-fixes.test.ts | 63 ++++++++++++++++++++++++++++++ test/cli-worker-connection.test.ts | 59 ++++++++++++++++++++++++++++ 42 files changed, 308 insertions(+), 84 deletions(-) create mode 100644 src/cli/worker-connection.ts create mode 100644 test/cli-worker-connection.test.ts diff --git a/AGENTS.md b/AGENTS.md index 3897c7910e..81b4eed6fa 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` (4,700+ 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` (4,800+ 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 - 322+ iii functions -- 4,700+ tests +- 4,800+ tests diff --git a/README.md b/README.md index cd40701a05..7590f939b8 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1313,7 +1313,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 19dfdad2f8..40b6c0699d 100644 --- a/READMEs/README.ar-SA.md +++ b/READMEs/README.ar-SA.md @@ -71,7 +71,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1244,7 +1244,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 a0881d0c27..b16b1f7bd4 100644 --- a/READMEs/README.bn-BD.md +++ b/READMEs/README.bn-BD.md @@ -69,7 +69,7 @@ 54 MCP টুল 12 অটো হুক 0 এক্সটার্নাল ডিবি - 4,700+ টেস্ট পাস + 4,800+ টেস্ট পাস

@@ -1257,7 +1257,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 3837c5eb6e..41c98ab4df 100644 --- a/READMEs/README.cs-CZ.md +++ b/READMEs/README.cs-CZ.md @@ -69,7 +69,7 @@ 54 MCP nástrojů 12 automatických hooks 0 externích databází - 4,700+ testů úspěšně proběhlo + 4,800+ testů úspěšně proběhlo

@@ -1243,7 +1243,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 209257de1f..6e96f1ad65 100644 --- a/READMEs/README.da-DK.md +++ b/READMEs/README.da-DK.md @@ -69,7 +69,7 @@ 54 MCP-værktøjer 12 automatiske hooks 0 eksterne databaser - 4,700+ beståede tests + 4,800+ beståede tests

@@ -1251,7 +1251,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 a0b4b683b8..f09b2211b6 100644 --- a/READMEs/README.de-DE.md +++ b/READMEs/README.de-DE.md @@ -69,7 +69,7 @@ 54 MCP-Tools 12 Auto-Hooks 0 externe DBs - 4,700+ bestandene Tests + 4,800+ bestandene Tests

@@ -1249,7 +1249,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 49f0fb50b2..20190d727a 100644 --- a/READMEs/README.el-GR.md +++ b/READMEs/README.el-GR.md @@ -69,7 +69,7 @@ 54 εργαλεία MCP 12 αυτόματα hooks 0 εξωτερικές βάσεις δεδομένων - 4,700+ επιτυχημένες δοκιμές + 4,800+ επιτυχημένες δοκιμές

@@ -1243,7 +1243,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 0cf25dab97..6ca88703a2 100644 --- a/READMEs/README.es-ES.md +++ b/READMEs/README.es-ES.md @@ -69,7 +69,7 @@ 54 tools MCP 12 hooks automáticos 0 bases de datos externas - 4,700+ tests superados + 4,800+ tests superados

@@ -1245,7 +1245,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 c580718e9f..c82e700071 100644 --- a/READMEs/README.fi-FI.md +++ b/READMEs/README.fi-FI.md @@ -69,7 +69,7 @@ 54 MCP-työkalua 12 automaattista hookia 0 ulkoista tietokantaa - 4,700+ testiä läpäisty + 4,800+ testiä läpäisty

@@ -1243,7 +1243,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 3f508c8454..981e72e4f9 100644 --- a/READMEs/README.fr-FR.md +++ b/READMEs/README.fr-FR.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1252,7 +1252,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 73f6e4a233..313f456302 100644 --- a/READMEs/README.he-IL.md +++ b/READMEs/README.he-IL.md @@ -71,7 +71,7 @@ 54 כלי MCP 12 hooks אוטומטיים 0 מסדי נתונים חיצוניים - 4,700+ בדיקות עוברות + 4,800+ בדיקות עוברות

@@ -1244,7 +1244,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 4c3a8d31e2..9bed3ca5eb 100644 --- a/READMEs/README.hi-IN.md +++ b/READMEs/README.hi-IN.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1258,7 +1258,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 20d0e86604..819b196d68 100644 --- a/READMEs/README.hu-HU.md +++ b/READMEs/README.hu-HU.md @@ -69,7 +69,7 @@ 54 MCP eszköz 12 automatikus hook 0 külső adatbázis - 4,700+ sikeres teszt + 4,800+ sikeres teszt

@@ -1241,7 +1241,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 855cd4dd52..a5813dcfc8 100644 --- a/READMEs/README.id-ID.md +++ b/READMEs/README.id-ID.md @@ -69,7 +69,7 @@ 54 tool MCP 12 hook otomatis 0 DB eksternal - 4,700+ pengujian lolos + 4,800+ pengujian lolos

@@ -1258,7 +1258,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 cd396e06e9..a2e6f3aa8e 100644 --- a/READMEs/README.it-IT.md +++ b/READMEs/README.it-IT.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1251,7 +1251,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 9dfe1e726c..412d9f4224 100644 --- a/READMEs/README.ja-JP.md +++ b/READMEs/README.ja-JP.md @@ -69,7 +69,7 @@ 54 MCP ツール 12 自動 hooks 外部 DB 0 個 - 4,700+ 件のテストが成功 + 4,800+ 件のテストが成功

@@ -1257,7 +1257,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 4c77e312b0..db1bee6bd2 100644 --- a/READMEs/README.ko-KR.md +++ b/READMEs/README.ko-KR.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1256,7 +1256,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 e617bec5e1..def9fa24d0 100644 --- a/READMEs/README.nb-NO.md +++ b/READMEs/README.nb-NO.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1249,7 +1249,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 ab0aa4972b..a41ab0bf2e 100644 --- a/READMEs/README.nl-NL.md +++ b/READMEs/README.nl-NL.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1245,7 +1245,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 c24834e624..be1064ea75 100644 --- a/READMEs/README.pl-PL.md +++ b/READMEs/README.pl-PL.md @@ -69,7 +69,7 @@ 54 narzędzia MCP 12 automatycznych hooków 0 zewnętrznych baz danych - 4,700+ zaliczonych testów + 4,800+ zaliczonych testów

@@ -1241,7 +1241,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 8cba9a4b83..14023e43ce 100644 --- a/READMEs/README.pt-BR.md +++ b/READMEs/README.pt-BR.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1249,7 +1249,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 c237b780d8..3f2e79bb91 100644 --- a/READMEs/README.pt-PT.md +++ b/READMEs/README.pt-PT.md @@ -69,7 +69,7 @@ 54 ferramentas MCP 12 hooks automáticos 0 bases de dados externas - 4,700+ testes aprovados + 4,800+ testes aprovados

@@ -1245,7 +1245,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 620d55913d..91d70e2ffe 100644 --- a/READMEs/README.ro-RO.md +++ b/READMEs/README.ro-RO.md @@ -69,7 +69,7 @@ 54 de instrumente MCP 12 hook-uri automate 0 baze de date externe - 4,700+ teste trecute + 4,800+ teste trecute

@@ -1237,7 +1237,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 3086998cdd..aed56590dc 100644 --- a/READMEs/README.ru-RU.md +++ b/READMEs/README.ru-RU.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1243,7 +1243,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 c29d00dbee..fc2f4d5b80 100644 --- a/READMEs/README.sv-SE.md +++ b/READMEs/README.sv-SE.md @@ -69,7 +69,7 @@ 54 MCP-verktyg 12 automatiska hooks 0 externa databaser - 4,700+ godkända tester + 4,800+ godkända tester

@@ -1251,7 +1251,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 49a0e9ce46..fa1bd6d710 100644 --- a/READMEs/README.th-TH.md +++ b/READMEs/README.th-TH.md @@ -69,7 +69,7 @@ 54 เครื่องมือ MCP 12 hook อัตโนมัติ ไม่ต้องพึ่ง external DB เลย - ผ่านการทดสอบ 4,700+ รายการ + ผ่านการทดสอบ 4,800+ รายการ

@@ -1244,7 +1244,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 9eacba7baf..27cec827c0 100644 --- a/READMEs/README.tl-PH.md +++ b/READMEs/README.tl-PH.md @@ -69,7 +69,7 @@ 54 MCP tool 12 awtomatikong hook 0 panlabas na DB - 4,700+ pumapasang test + 4,800+ pumapasang test

@@ -1253,7 +1253,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 f1aa62a40a..d26df964c2 100644 --- a/READMEs/README.tr-TR.md +++ b/READMEs/README.tr-TR.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1243,7 +1243,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 11019c61fe..08832163f6 100644 --- a/READMEs/README.uk-UA.md +++ b/READMEs/README.uk-UA.md @@ -69,7 +69,7 @@ 54 інструменти MCP 12 автоматичних хуків 0 зовнішніх БД - 4,700+ тестів пройдено + 4,800+ тестів пройдено

@@ -1244,7 +1244,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 a4a9b37b3c..c61fdbc3ef 100644 --- a/READMEs/README.ur-PK.md +++ b/READMEs/README.ur-PK.md @@ -71,7 +71,7 @@ 54 MCP ٹولز 12 خودکار ہکس 0 خارجی ڈیٹابیسز - 4,700+ ٹیسٹس پاس ہو رہے ہیں + 4,800+ ٹیسٹس پاس ہو رہے ہیں

@@ -1248,7 +1248,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 47177b4c47..6b3d54b63f 100644 --- a/READMEs/README.vi-VN.md +++ b/READMEs/README.vi-VN.md @@ -69,7 +69,7 @@ 54 MCP tools 12 auto hooks 0 external DBs - 4,700+ tests passing + 4,800+ tests passing

@@ -1253,7 +1253,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 0a5f9c2d05..e7a3f90896 100644 --- a/READMEs/README.zh-CN.md +++ b/READMEs/README.zh-CN.md @@ -69,7 +69,7 @@ 54 个 MCP 工具 12 个自动 hooks 0 个外部数据库 - 4,700+ 项测试通过 + 4,800+ 项测试通过

@@ -1254,7 +1254,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 c2e315c886..74e1eca426 100644 --- a/READMEs/README.zh-TW.md +++ b/READMEs/README.zh-TW.md @@ -69,7 +69,7 @@ 54 個 MCP 工具 12 個自動 hooks 0 個外部資料庫 - 4,700+ 測試通過 + 4,800+ 測試通過

@@ -1246,7 +1246,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: ```bash npm run dev # Hot reload npm run build # Production build -npm test # 4,700+ tests +npm test # 4,800+ 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 1b4179cfc2..743b0d095d 100644 --- a/assets/tags/light/stat-tests.svg +++ b/assets/tags/light/stat-tests.svg @@ -1,5 +1,5 @@ - + - 4700+ + 4800+ TESTS PASSING diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg index 2b679ac742..7b4a1c20eb 100644 --- a/assets/tags/stat-tests.svg +++ b/assets/tags/stat-tests.svg @@ -1,5 +1,5 @@ - + - 4700+ + 4800+ TESTS PASSING diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index ef3f2b4c6b..3829d237a6 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -20,13 +20,13 @@ "12" ], "tests": [ - "4700+" + "4800+" ], "functions": [ "323" ], "sourceFiles": [ - "259" + "260" ], "loc": [ "60000" diff --git a/src/cli.ts b/src/cli.ts index b2b89ab08d..a13a13b725 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -43,6 +43,7 @@ import { canAutoFix, doctorPromptsAllowed, dryRunPlan, + failureReport, parseEnvFile, type Diagnostic, type DiagnosticFixResult, @@ -104,6 +105,7 @@ import { bearerHeaders, resolveClientSecret } from "./secret-store.js"; import { assertComposePortsFree, composeCall, composeRegistryFailureMessage, composeStateRegistryFailure, composeWorkerFailureSummary, ownedComposeProject, readComposeLogFromOffset, startComposeDaemon, writeComposeState, type ComposeStatus } from "./cli/compose-control.js"; import { COMPOSE_WORKER_VERSIONS, composeDownTimeoutMs, composeNamespace } from "./cli/compose-project.js"; import { legacyDockerStateMessage, type LegacyDockerEngineState } from "./cli/legacy-docker-state.js"; +import { engineOnlyLines, probeWorkerConnection } from "./cli/worker-connection.js"; const __dirname = dirname(fileURLToPath(import.meta.url)); const args = process.argv.slice(2); @@ -1878,6 +1880,11 @@ async function runStatus() { process.exit(1); } + if (await probeWorkerConnection(base, bearerHeaders(base)) === "engine-only") { + p.log.error(engineOnlyLines(base).join("\n")); + process.exit(1); + } + try { const [healthRes, sessionsRes, graphRes, memoriesRes, flagsRes, followupRes] = await Promise.all([ apiFetch(base, "health"), @@ -2101,6 +2108,7 @@ function buildDoctorEffects(): DoctorEffects { const managed = state?.kind === "compose" && state.restPort === getRestPort() && !remoteTarget; return !managed && await isEngineRunning(); }, + workerConnection: () => probeWorkerConnection(getBaseUrl(), bearerHeaders(getBaseUrl())), viewerReachable: async (timeoutMs = 2000) => { try { await discoverViewerPort(); @@ -2407,16 +2415,15 @@ async function runDoctor() { continue; } failed++; - p.log.warn(`${d.id} ✗ ${status.detail ?? ""}`.trim()); + const report = failureReport(d, status); + p.log.warn(report.problem); + p.log.info(report.fix); if (!canAutoFix(d, status)) { - p.log.info(`manual fix: ${status.manualFix ?? d.fixPreview}`); skipped++; continue; } - p.log.info(`why: ${d.fixPreview}`); - if (applyAll) { const r = await applyFixWithReport(d, ctx, false); if (r.ok) fixed++; diff --git a/src/cli/doctor-diagnostics.ts b/src/cli/doctor-diagnostics.ts index b7bea3868f..7d922c3ee4 100644 --- a/src/cli/doctor-diagnostics.ts +++ b/src/cli/doctor-diagnostics.ts @@ -24,6 +24,7 @@ import { llmOptInHint, parseEnvContent, } from "../config.js"; +import { ENGINE_ONLY_DOCKER_GUIDE, ENGINE_ONLY_FIX, type WorkerConnection } from "./worker-connection.js"; export type DiagnosticStatus = { ok: boolean; @@ -73,6 +74,13 @@ export function canAutoFix(d: Diagnostic, status?: DiagnosticStatus): boolean { return !d.manualOnly && !status?.manualFix; } +export function failureReport(d: Diagnostic, status: DiagnosticStatus): { problem: string; fix: string } { + return { + problem: `${d.id} ✗ ${d.message}${status.detail ? ` (${status.detail})` : ""}`, + fix: `${canAutoFix(d, status) ? "fix" : "manual fix"}: ${status.manualFix ?? d.fixPreview}`, + }; +} + export function doctorPromptsAllowed( env: NodeJS.ProcessEnv, stdinIsTTY: boolean | undefined, @@ -87,6 +95,7 @@ export const DIAGNOSTIC_IDS = [ "no-llm-provider-key", "embedding-provider-not-chosen", "engine-version-mismatch", + "worker-not-connected", "viewer-unreachable", "stale-pidfile", "env-placeholder-keys", @@ -143,6 +152,7 @@ export type DoctorEffects = { /** Run `iii --version`; null if it fails. */ iiiBinaryVersion: (binPath: string) => string | null; externalEngineRunning: () => Promise; + workerConnection: () => Promise; /** Probe the viewer URL; true if it returns OK within timeoutMs. */ viewerReachable: (timeoutMs?: number) => Promise; /** Run init logic (copies .env.example). */ @@ -289,6 +299,27 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { return effects.runStart(); }, }, + { + id: "worker-not-connected", + message: "The iii engine is running, but the agentmemory worker is not connected to it.", + fixPreview: ENGINE_ONLY_FIX, + moreInfo: + "The REST port answers, but /agentmemory/livez and /agentmemory/health return 404. " + + "Only the agentmemory worker registers those routes, so the engine runs alone: status shows " + + "no version and no health, and the viewer is not served. Old Docker images from the legacy " + + "CLI Docker mode ran only the engine. Migration guide: " + + ENGINE_ONLY_DOCKER_GUIDE, + manualOnly: true, + check: async (ctx) => { + const connection = await effects.workerConnection(); + if (connection === "engine-only") { + return { ok: false, detail: `engine at ${ctx.baseUrl} has no agentmemory routes (404)` }; + } + if (connection === "unreachable") return { ok: true, detail: "server not reachable (see Server reachable)" }; + return { ok: true }; + }, + fix: async () => ({ ok: false, message: ENGINE_ONLY_FIX }), + }, { id: "viewer-unreachable", message: "Viewer port not reachable.", @@ -357,14 +388,16 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { { id: "iii-on-path-not-local-bin", message: - "iii is on PATH but agentmemory's private install is absent or mismatched.", + "agentmemory's own iii at ~/.agentmemory/bin/iii is missing or a different version, so an iii on your PATH is used instead.", fixPreview: - "Install the pinned version to ~/.agentmemory/bin — won't touch your PATH.", + "Run npx -y @agentmemory/agentmemory@latest. It installs the pinned iii to ~/.agentmemory/bin/iii and does not change your PATH or the other iii.", moreInfo: - "agentmemory installs its pinned engine to ~/.agentmemory/bin/iii so a " + + "agentmemory keeps its pinned engine at ~/.agentmemory/bin/iii so a " + "user-managed iii on PATH (homebrew, cargo, manual install) stays untouched. " + - "When agentmemory needs the pin and PATH doesn't have it, it falls back to the " + - "private install. If neither exists, run the installer.", + "When that copy is missing or has a different version, startup uses the iii on PATH " + + "if it matches the pin. If the PATH iii has a different version, startup installs the " + + "pinned copy into ~/.agentmemory/bin first. The engine-version-mismatch check shows " + + "which version each binary reports.", manualOnly: true, check: async (ctx) => { const bin = effects.findIiiBinary(); @@ -378,7 +411,17 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { detail: `private install pinned; PATH iii at ${bin} stays untouched`, }; } - return { ok: false, detail: `iii at: ${bin}` }; + const pathVersion = effects.iiiBinaryVersion(bin); + const detail = `PATH iii at ${bin} is ${pathVersion ?? "an unknown version"} (pinned ${ctx.pinnedVersion})`; + if (pathVersion === ctx.pinnedVersion) { + return { + ok: false, + detail, + manualFix: + "The PATH iii is the pinned version, so startup can use it and no action is needed. To give agentmemory its own copy in ~/.agentmemory/bin, run npx -y @agentmemory/agentmemory@latest upgrade and accept the iii-engine install step.", + }; + } + return { ok: false, detail }; }, fix: async () => effects.runIiiInstaller().then((r) => ({ diff --git a/src/cli/worker-connection.ts b/src/cli/worker-connection.ts new file mode 100644 index 0000000000..6e7976a25f --- /dev/null +++ b/src/cli/worker-connection.ts @@ -0,0 +1,52 @@ +export type WorkerConnection = "connected" | "engine-only" | "unreachable"; + +type FetchLike = (url: string, init: { signal: AbortSignal; headers: Record }) => Promise<{ + status: number; + body?: { cancel(): Promise } | null; +}>; + +async function routeStatus( + url: string, + headers: Record, + timeoutMs: number, + fetchImpl: FetchLike, +): Promise { + try { + const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs), headers }); + void res.body?.cancel().catch(() => {}); + return res.status; + } catch { + return null; + } +} + +export async function probeWorkerConnection( + base: string, + headers: Record = {}, + timeoutMs = 2000, + fetchImpl: FetchLike = fetch as unknown as FetchLike, +): Promise { + const [livez, health] = await Promise.all([ + routeStatus(`${base}/agentmemory/livez`, headers, timeoutMs, fetchImpl), + routeStatus(`${base}/agentmemory/health`, headers, timeoutMs, fetchImpl), + ]); + if (livez === null && health === null) return "unreachable"; + if (livez === 404 && health === 404) return "engine-only"; + return "connected"; +} + +export const ENGINE_ONLY_DOCKER_GUIDE = + "https://github.com/rohitg00/agentmemory/blob/main/deploy/README.md#migrating-from-the-legacy-cli-docker-mode"; + +export const ENGINE_ONLY_FIX = + "Stop the process that owns this port (an old Docker container or an iii you started yourself), then start agentmemory with: npx -y @agentmemory/agentmemory@latest. For Docker, run the current image instead."; + +export function engineOnlyLines(base: string): string[] { + return [ + `The iii engine is running at ${base}, but the agentmemory worker is not connected to it.`, + "The engine returns 404 for /agentmemory/livez and /agentmemory/health. Version, health and the viewer stay unavailable until the worker connects.", + "Old Docker images from the legacy CLI Docker mode ran only the engine and show this state.", + `Fix: ${ENGINE_ONLY_FIX}`, + `Docker migration: ${ENGINE_ONLY_DOCKER_GUIDE}`, + ]; +} diff --git a/test/cli-doctor-fixes.test.ts b/test/cli-doctor-fixes.test.ts index 37428eebac..c47d391058 100644 --- a/test/cli-doctor-fixes.test.ts +++ b/test/cli-doctor-fixes.test.ts @@ -13,6 +13,7 @@ import { doctorPromptsAllowed, DIAGNOSTIC_IDS, dryRunPlan, + failureReport, parseEnvFile, placeholderProviderKeys, realProviderKeys, @@ -43,6 +44,7 @@ function stubEffects(overrides: Partial = {}): DoctorEffects { localBinIiiPath: () => "/Users/test/.local/bin/iii", iiiBinaryVersion: () => III_PINNED_VERSION, externalEngineRunning: async () => false, + workerConnection: async () => "connected", viewerReachable: async () => true, runInit: async () => ({ ok: true, message: "wrote .env" }), openEditor: async () => ({ ok: true, message: "saved" }), @@ -63,6 +65,7 @@ describe("doctor v2 diagnostic catalog", () => { expect(DIAGNOSTIC_IDS).toContain("stale-pidfile"); expect(DIAGNOSTIC_IDS).toContain("env-placeholder-keys"); expect(DIAGNOSTIC_IDS).toContain("iii-on-path-not-local-bin"); + expect(DIAGNOSTIC_IDS).toContain("worker-not-connected"); }); it("every diagnostic has check, fix, message, and fixPreview", () => { @@ -483,6 +486,66 @@ describe("doctor v2 diagnostic catalog", () => { expect(lines[0]).toContain("All checks passing"); }); + it("worker-not-connected fails when the engine runs without the agentmemory worker", async () => { + const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => "engine-only" })); + const check = diagnostics.find((d) => d.id === "worker-not-connected")!; + const status = await check.check(stubCtx()); + expect(status.ok).toBe(false); + expect(status.detail).toContain("http://localhost:3111"); + expect(canAutoFix(check, status)).toBe(false); + expect(check.fixPreview).toContain("npx -y @agentmemory/agentmemory@latest"); + expect(check.moreInfo).toContain("Docker"); + }); + + it("worker-not-connected passes when the worker answers or the server is down", async () => { + for (const connection of ["connected", "unreachable"] as const) { + const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => connection })); + const check = diagnostics.find((d) => d.id === "worker-not-connected")!; + expect((await check.check(stubCtx())).ok).toBe(true); + } + }); + + it("iii-on-path-not-local-bin explains which iii is used and how to fix it", async () => { + const privatePath = "/Users/test/.agentmemory/bin/iii"; + const diagnostics = buildDiagnostics(stubEffects({ + findIiiBinary: () => "/opt/homebrew/bin/iii", + localBinIiiPath: () => privatePath, + iiiBinaryVersion: (bin) => (bin === privatePath ? null : "0.99.99"), + })); + const check = diagnostics.find((d) => d.id === "iii-on-path-not-local-bin")!; + const status = await check.check(stubCtx()); + expect(status.detail).toContain("/opt/homebrew/bin/iii"); + expect(status.detail).toContain("0.99.99"); + expect(check.message).toContain("PATH"); + expect(check.message).toContain("~/.agentmemory/bin/iii"); + const report = failureReport(check, status); + expect(report.problem).toContain(check.message); + expect(report.fix).toContain("manual fix:"); + expect(report.fix).toContain("npx -y @agentmemory/agentmemory@latest"); + }); + + it("iii-on-path-not-local-bin says no action is needed when the PATH iii is the pinned version", async () => { + const privatePath = "/Users/test/.agentmemory/bin/iii"; + const diagnostics = buildDiagnostics(stubEffects({ + findIiiBinary: () => "/opt/homebrew/bin/iii", + localBinIiiPath: () => privatePath, + iiiBinaryVersion: (bin) => (bin === privatePath ? null : III_PINNED_VERSION), + })); + const check = diagnostics.find((d) => d.id === "iii-on-path-not-local-bin")!; + const status = await check.check(stubCtx()); + expect(status.ok).toBe(false); + expect(status.manualFix).toContain("no action is needed"); + expect(failureReport(check, status).fix).toContain("upgrade"); + }); + + it("failureReport gives every failing diagnostic its message and a fix hint", () => { + for (const diagnostic of buildDiagnostics(stubEffects())) { + const report = failureReport(diagnostic, { ok: false, detail: "stub fail" }); + expect(report.problem).toBe(`${diagnostic.id} ✗ ${diagnostic.message} (stub fail)`); + expect(report.fix).toMatch(/^(manual fix|fix): \S/); + } + }); + it("dryRunPlan labels manual-only diagnostics without promising automatic fixes", () => { const diagnostic = buildDiagnostics(stubEffects()) .find((d) => d.id === "iii-on-path-not-local-bin")!; diff --git a/test/cli-worker-connection.test.ts b/test/cli-worker-connection.test.ts new file mode 100644 index 0000000000..ea7e0d465d --- /dev/null +++ b/test/cli-worker-connection.test.ts @@ -0,0 +1,59 @@ +import { describe, expect, it, vi } from "vitest"; +import { engineOnlyLines, probeWorkerConnection } from "../src/cli/worker-connection.js"; + +function fakeFetch(routes: Record) { + return vi.fn(async (url: string) => { + const path = new URL(url).pathname; + const result = routes[path]; + if (result instanceof Error || result === undefined) throw result ?? new Error("connection refused"); + return { status: result, body: null }; + }); +} + +describe("probeWorkerConnection", () => { + const base = "http://localhost:3111"; + + it("reports engine-only when the engine returns 404 for the agentmemory routes", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 404, "/agentmemory/health": 404 }); + expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("engine-only"); + }); + + it("reports connected when the worker answers", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 200, "/agentmemory/health": 200 }); + expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("connected"); + }); + + it("treats an auth rejection as a connected worker", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 401, "/agentmemory/health": 401 }); + expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("connected"); + }); + + it("does not report engine-only when only one route is missing", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 404, "/agentmemory/health": 200 }); + expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("connected"); + }); + + it("reports unreachable when nothing answers", async () => { + const fetchImpl = fakeFetch({}); + expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("unreachable"); + }); + + it("sends the given headers to both routes", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 200, "/agentmemory/health": 200 }); + await probeWorkerConnection(base, { Authorization: "Bearer x" }, 500, fetchImpl); + expect(fetchImpl).toHaveBeenCalledTimes(2); + for (const call of fetchImpl.mock.calls as unknown as Array<[string, { headers: Record }]>) { + expect(call[1].headers).toEqual({ Authorization: "Bearer x" }); + } + }); +}); + +describe("engineOnlyLines", () => { + it("explains the state, the start command and old Docker images", () => { + const text = engineOnlyLines("http://localhost:3111").join("\n"); + expect(text).toContain("iii engine is running at http://localhost:3111"); + expect(text).toContain("agentmemory worker is not connected"); + expect(text).toContain("npx -y @agentmemory/agentmemory@latest"); + expect(text).toContain("Docker"); + }); +}); From 636e7ef38f50be54a46a61f0c88550bf1c13b8c5 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 16:47:27 +0530 Subject: [PATCH 2/7] fix(cli): leave managed Compose status to the Compose failure report When a supervised worker in the managed Compose project exhausts its restarts, the agentmemory routes can return 404. The engine-only probe then exited before status printed the Compose failure. Skip the probe for managed Compose state in status and doctor; it is meant for engines agentmemory does not manage. Signed-off-by: Rohit Ghumare --- src/cli.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index a13a13b725..c00c321f8f 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1880,7 +1880,7 @@ async function runStatus() { process.exit(1); } - if (await probeWorkerConnection(base, bearerHeaders(base)) === "engine-only") { + if (savedState?.kind !== "compose" && await probeWorkerConnection(base, bearerHeaders(base)) === "engine-only") { p.log.error(engineOnlyLines(base).join("\n")); process.exit(1); } @@ -2108,7 +2108,10 @@ function buildDoctorEffects(): DoctorEffects { const managed = state?.kind === "compose" && state.restPort === getRestPort() && !remoteTarget; return !managed && await isEngineRunning(); }, - workerConnection: () => probeWorkerConnection(getBaseUrl(), bearerHeaders(getBaseUrl())), + workerConnection: async () => { + if (readEngineState()?.kind === "compose") return "connected"; + return probeWorkerConnection(getBaseUrl(), bearerHeaders(getBaseUrl())); + }, viewerReachable: async (timeoutMs = 2000) => { try { await discoverViewerPort(); From c02a4e49143b8809c21ee53a2d49f8954ba28122 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 18:21:11 +0530 Subject: [PATCH 3/7] fix(cli): confirm the iii engine and keep the target in worker probes Two 404 responses from the agentmemory routes no longer prove an iii engine. The probe now also checks the engine port. If that port does not answer, status and doctor report an unrecognized service and do not tell the user to stop it. Status and doctor now probe the selected target also when managed Compose state exists. Status prints the Compose failure report first when there is one. Doctor reports a managed Compose engine without its worker and no longer passes for a remote URL or another port. The recovery command keeps --instance, --port and --data-dir. The iii-on-path-not-local-bin message no longer says that startup uses the PATH iii. Signed-off-by: Rohit Ghumare --- src/cli.ts | 96 ++++++++++++++++++++---------- src/cli/doctor-diagnostics.ts | 34 +++++++++-- src/cli/worker-connection.ts | 61 +++++++++++++++---- test/cli-doctor-fixes.test.ts | 29 +++++++++ test/cli-worker-connection.test.ts | 75 ++++++++++++++++++++--- 5 files changed, 239 insertions(+), 56 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index c00c321f8f..d56b7ce7ed 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -105,7 +105,7 @@ import { bearerHeaders, resolveClientSecret } from "./secret-store.js"; import { assertComposePortsFree, composeCall, composeRegistryFailureMessage, composeStateRegistryFailure, composeWorkerFailureSummary, ownedComposeProject, readComposeLogFromOffset, startComposeDaemon, writeComposeState, type ComposeStatus } from "./cli/compose-control.js"; import { COMPOSE_WORKER_VERSIONS, composeDownTimeoutMs, composeNamespace } from "./cli/compose-project.js"; import { legacyDockerStateMessage, type LegacyDockerEngineState } from "./cli/legacy-docker-state.js"; -import { engineOnlyLines, probeWorkerConnection } from "./cli/worker-connection.js"; +import { DEFAULT_START_COMMAND, engineOnlyLines, probeWorkerConnection, tcpPortOpen, unrecognizedServiceLines, type WorkerConnection } from "./cli/worker-connection.js"; const __dirname = dirname(fileURLToPath(import.meta.url)); const args = process.argv.slice(2); @@ -1842,6 +1842,46 @@ async function apiFetch(base: string, path: string, timeoutMs = 500 } } +function recoveryStartCommand(): string { + const parts = [DEFAULT_START_COMMAND]; + if (hasInstanceArgument) parts.push(`--instance ${selectedInstance}`); + if (portValue || (!hasInstanceArgument && getRestPort() !== 3111)) parts.push(`--port ${getRestPort()}`); + const dataDir = cliArgValue("--data-dir"); + if (dataDir) parts.push(`--data-dir ${/\s/.test(dataDir) ? JSON.stringify(dataDir) : dataDir}`); + return parts.join(" "); +} + +function probeTargetWorker(base: string): Promise { + return probeWorkerConnection(base, { + headers: bearerHeaders(base), + engineBusReachable: async () => tcpPortOpen(new URL(base).hostname.replace(/^\[|\]$/g, ""), getEnginePort()), + }); +} + +async function savedComposeFailure(state: ComposeEngineState): Promise { + if (!state.composePid || !pidAlive(state.composePid)) return null; + try { + const composeStatus = await composeCall({ + engineUrl: state.engineUrl, + namespace: state.namespace, + functionId: "compose::status", + file: state.file, + }); + return composeWorkerFailureSummary(ownedComposeProject(composeStatus, state.file)); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + p.log.warn(`Worker Compose status unavailable: ${message}`); + return null; + } +} + +function exitWithComposeFailure(state: ComposeEngineState, failure: string, unavailable: string): never { + p.log.error(`Worker Compose failed after exhausting restart attempts; ${unavailable}.`); + p.log.error(failure); + p.log.info(`Inspect ${state.logFile}, then run agentmemory stop before retrying.`); + process.exit(1); +} + async function runStatus() { const base = getBaseUrl(); p.intro("agentmemory status"); @@ -1854,34 +1894,25 @@ async function runStatus() { const up = await isEngineRunning(); if (!up) { - if (savedState?.kind === "compose" && savedState.composePid && pidAlive(savedState.composePid)) { - try { - const composeStatus = await composeCall({ - engineUrl: savedState.engineUrl, - namespace: savedState.namespace, - functionId: "compose::status", - file: savedState.file, - }); - const project = ownedComposeProject(composeStatus, savedState.file); - const failure = composeWorkerFailureSummary(project); - if (failure) { - p.log.error(`Worker Compose failed after exhausting restart attempts; REST is unavailable at ${base}.`); - p.log.error(failure); - p.log.info(`Inspect ${savedState.logFile}, then run agentmemory stop before retrying.`); - process.exit(1); - } - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - p.log.warn(`Worker Compose status unavailable: ${message}`); - } + if (savedState?.kind === "compose") { + const failure = await savedComposeFailure(savedState); + if (failure) exitWithComposeFailure(savedState, failure, `REST is unavailable at ${base}`); } p.log.error(`Not running — no response at ${base}`); p.log.info("Start with: npx @agentmemory/agentmemory"); process.exit(1); } - if (savedState?.kind !== "compose" && await probeWorkerConnection(base, bearerHeaders(base)) === "engine-only") { - p.log.error(engineOnlyLines(base).join("\n")); + const connection = await probeTargetWorker(base); + if (connection === "engine-only" || connection === "unrecognized") { + if (savedState?.kind === "compose") { + const failure = await savedComposeFailure(savedState); + if (failure) exitWithComposeFailure(savedState, failure, `the agentmemory routes are unavailable at ${base}`); + } + const lines = connection === "engine-only" + ? engineOnlyLines(base, recoveryStartCommand()) + : unrecognizedServiceLines(base); + p.log.error(lines.join("\n")); process.exit(1); } @@ -2065,9 +2096,16 @@ function buildDoctorContext(): DoctorContext { pidfilePath: readEngineState()?.kind === "compose" ? engineStatePath() : enginePidfilePath(), enginePath: engineStatePath(), pinnedVersion: IIPINNED_VERSION, + startCommand: recoveryStartCommand(), }; } +function doctorTargetsManagedCompose(): boolean { + const state = readEngineState(); + const remoteTarget = shouldUseAgentmemoryUrl() && process.env["AGENTMEMORY_URL"]; + return state?.kind === "compose" && state.restPort === getRestPort() && !remoteTarget; +} + function buildDoctorEffects(): DoctorEffects { return { envFileExists: () => existsSync(doctorEnvPath()), @@ -2102,15 +2140,11 @@ function buildDoctorEffects(): DoctorEffects { return state?.kind === "compose" ? state.binPath : privateIiiPath(); }, iiiBinaryVersion: (binPath: string) => iiiBinVersion(binPath), - externalEngineRunning: async () => { - const state = readEngineState(); - const remoteTarget = shouldUseAgentmemoryUrl() && process.env["AGENTMEMORY_URL"]; - const managed = state?.kind === "compose" && state.restPort === getRestPort() && !remoteTarget; - return !managed && await isEngineRunning(); - }, + externalEngineRunning: async () => !doctorTargetsManagedCompose() && await isEngineRunning(), workerConnection: async () => { - if (readEngineState()?.kind === "compose") return "connected"; - return probeWorkerConnection(getBaseUrl(), bearerHeaders(getBaseUrl())); + const connection = await probeTargetWorker(getBaseUrl()); + if (connection === "connected" || connection === "unreachable") return connection; + return doctorTargetsManagedCompose() ? "managed-worker-down" : connection; }, viewerReachable: async (timeoutMs = 2000) => { try { diff --git a/src/cli/doctor-diagnostics.ts b/src/cli/doctor-diagnostics.ts index 7d922c3ee4..b6d70de879 100644 --- a/src/cli/doctor-diagnostics.ts +++ b/src/cli/doctor-diagnostics.ts @@ -24,7 +24,7 @@ import { llmOptInHint, parseEnvContent, } from "../config.js"; -import { ENGINE_ONLY_DOCKER_GUIDE, ENGINE_ONLY_FIX, type WorkerConnection } from "./worker-connection.js"; +import { DEFAULT_START_COMMAND, ENGINE_ONLY_DOCKER_GUIDE, engineOnlyFix, UNRECOGNIZED_SERVICE_FIX, type WorkerConnection } from "./worker-connection.js"; export type DiagnosticStatus = { ok: boolean; @@ -51,8 +51,11 @@ export type DoctorContext = { enginePath: string; /** Pinned engine version. */ pinnedVersion: string; + startCommand?: string; }; +export type DoctorWorkerConnection = WorkerConnection | "managed-worker-down"; + export type Diagnostic = { /** Stable id. Used in --json and tests. */ id: string; @@ -152,7 +155,7 @@ export type DoctorEffects = { /** Run `iii --version`; null if it fails. */ iiiBinaryVersion: (binPath: string) => string | null; externalEngineRunning: () => Promise; - workerConnection: () => Promise; + workerConnection: () => Promise; /** Probe the viewer URL; true if it returns OK within timeoutMs. */ viewerReachable: (timeoutMs?: number) => Promise; /** Run init logic (copies .env.example). */ @@ -302,7 +305,7 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { { id: "worker-not-connected", message: "The iii engine is running, but the agentmemory worker is not connected to it.", - fixPreview: ENGINE_ONLY_FIX, + fixPreview: engineOnlyFix(), moreInfo: "The REST port answers, but /agentmemory/livez and /agentmemory/health return 404. " + "Only the agentmemory worker registers those routes, so the engine runs alone: status shows " + @@ -312,13 +315,32 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { manualOnly: true, check: async (ctx) => { const connection = await effects.workerConnection(); + const startCommand = ctx.startCommand ?? DEFAULT_START_COMMAND; if (connection === "engine-only") { - return { ok: false, detail: `engine at ${ctx.baseUrl} has no agentmemory routes (404)` }; + return { + ok: false, + detail: `engine at ${ctx.baseUrl} has no agentmemory routes (404)`, + manualFix: engineOnlyFix(startCommand), + }; + } + if (connection === "managed-worker-down") { + return { + ok: false, + detail: `managed Worker Compose engine at ${ctx.baseUrl} has no agentmemory routes (404)`, + manualFix: `Run agentmemory status to see the Worker Compose failure report, then run agentmemory stop and start again with: ${startCommand}.`, + }; + } + if (connection === "unrecognized") { + return { + ok: false, + detail: `server at ${ctx.baseUrl} returns 404 for the agentmemory routes and the iii engine port does not answer`, + manualFix: UNRECOGNIZED_SERVICE_FIX, + }; } if (connection === "unreachable") return { ok: true, detail: "server not reachable (see Server reachable)" }; return { ok: true }; }, - fix: async () => ({ ok: false, message: ENGINE_ONLY_FIX }), + fix: async (ctx) => ({ ok: false, message: engineOnlyFix(ctx.startCommand) }), }, { id: "viewer-unreachable", @@ -388,7 +410,7 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { { id: "iii-on-path-not-local-bin", message: - "agentmemory's own iii at ~/.agentmemory/bin/iii is missing or a different version, so an iii on your PATH is used instead.", + "agentmemory's own iii at ~/.agentmemory/bin/iii is missing or a different version, and another iii is on your PATH.", fixPreview: "Run npx -y @agentmemory/agentmemory@latest. It installs the pinned iii to ~/.agentmemory/bin/iii and does not change your PATH or the other iii.", moreInfo: diff --git a/src/cli/worker-connection.ts b/src/cli/worker-connection.ts index 6e7976a25f..d587cddf91 100644 --- a/src/cli/worker-connection.ts +++ b/src/cli/worker-connection.ts @@ -1,10 +1,19 @@ -export type WorkerConnection = "connected" | "engine-only" | "unreachable"; +import { createConnection } from "node:net"; + +export type WorkerConnection = "connected" | "engine-only" | "unrecognized" | "unreachable"; type FetchLike = (url: string, init: { signal: AbortSignal; headers: Record }) => Promise<{ status: number; body?: { cancel(): Promise } | null; }>; +export type WorkerProbeOptions = { + headers?: Record; + timeoutMs?: number; + fetchImpl?: FetchLike; + engineBusReachable?: () => Promise; +}; + async function routeStatus( url: string, headers: Record, @@ -20,33 +29,65 @@ async function routeStatus( } } +export async function tcpPortOpen(host: string, port: number, timeoutMs = 1000): Promise { + return await new Promise((resolve) => { + const socket = createConnection({ host, port }); + const done = (open: boolean) => { + socket.destroy(); + resolve(open); + }; + socket.setTimeout(timeoutMs); + socket.once("connect", () => done(true)); + socket.once("timeout", () => done(false)); + socket.once("error", () => done(false)); + }); +} + export async function probeWorkerConnection( base: string, - headers: Record = {}, - timeoutMs = 2000, - fetchImpl: FetchLike = fetch as unknown as FetchLike, + options: WorkerProbeOptions = {}, ): Promise { + const headers = options.headers ?? {}; + const timeoutMs = options.timeoutMs ?? 2000; + const fetchImpl = options.fetchImpl ?? (fetch as unknown as FetchLike); const [livez, health] = await Promise.all([ routeStatus(`${base}/agentmemory/livez`, headers, timeoutMs, fetchImpl), routeStatus(`${base}/agentmemory/health`, headers, timeoutMs, fetchImpl), ]); if (livez === null && health === null) return "unreachable"; - if (livez === 404 && health === 404) return "engine-only"; - return "connected"; + if (livez !== 404 || health !== 404) return "connected"; + const busReachable = options.engineBusReachable + ? await options.engineBusReachable().catch(() => false) + : false; + return busReachable ? "engine-only" : "unrecognized"; } +export const DEFAULT_START_COMMAND = "npx -y @agentmemory/agentmemory@latest"; + export const ENGINE_ONLY_DOCKER_GUIDE = "https://github.com/rohitg00/agentmemory/blob/main/deploy/README.md#migrating-from-the-legacy-cli-docker-mode"; -export const ENGINE_ONLY_FIX = - "Stop the process that owns this port (an old Docker container or an iii you started yourself), then start agentmemory with: npx -y @agentmemory/agentmemory@latest. For Docker, run the current image instead."; +export function engineOnlyFix(startCommand = DEFAULT_START_COMMAND): string { + return `Stop the process that owns this port (an old Docker container or an iii you started yourself), then start agentmemory with: ${startCommand}. For Docker, run the current image instead.`; +} -export function engineOnlyLines(base: string): string[] { +export const UNRECOGNIZED_SERVICE_FIX = + `Check that AGENTMEMORY_URL or --port points at agentmemory. If another program owns this port, start agentmemory on a free port with: ${DEFAULT_START_COMMAND} --port .`; + +export function engineOnlyLines(base: string, startCommand = DEFAULT_START_COMMAND): string[] { return [ `The iii engine is running at ${base}, but the agentmemory worker is not connected to it.`, "The engine returns 404 for /agentmemory/livez and /agentmemory/health. Version, health and the viewer stay unavailable until the worker connects.", "Old Docker images from the legacy CLI Docker mode ran only the engine and show this state.", - `Fix: ${ENGINE_ONLY_FIX}`, + `Fix: ${engineOnlyFix(startCommand)}`, `Docker migration: ${ENGINE_ONLY_DOCKER_GUIDE}`, ]; } + +export function unrecognizedServiceLines(base: string): string[] { + return [ + `A server answers at ${base}, but agentmemory does not.`, + "It returns 404 for /agentmemory/livez and /agentmemory/health, and the iii engine port does not answer. It can be another program on this port, or a remote iii engine without the agentmemory worker.", + `Fix: ${UNRECOGNIZED_SERVICE_FIX}`, + ]; +} diff --git a/test/cli-doctor-fixes.test.ts b/test/cli-doctor-fixes.test.ts index c47d391058..b758ea3912 100644 --- a/test/cli-doctor-fixes.test.ts +++ b/test/cli-doctor-fixes.test.ts @@ -497,6 +497,35 @@ describe("doctor v2 diagnostic catalog", () => { expect(check.moreInfo).toContain("Docker"); }); + it("worker-not-connected keeps the selected port in the recovery command", async () => { + const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => "engine-only" })); + const check = diagnostics.find((d) => d.id === "worker-not-connected")!; + const startCommand = "npx -y @agentmemory/agentmemory@latest --port 4111"; + const status = await check.check({ ...stubCtx(), baseUrl: "http://localhost:4111", startCommand }); + expect(status.manualFix).toContain(`start agentmemory with: ${startCommand}.`); + expect(failureReport(check, status).fix).toContain("--port 4111"); + }); + + it("worker-not-connected points a managed Compose engine at the Compose failure report", async () => { + const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => "managed-worker-down" })); + const check = diagnostics.find((d) => d.id === "worker-not-connected")!; + const status = await check.check(stubCtx()); + expect(status.ok).toBe(false); + expect(status.detail).toContain("managed Worker Compose"); + expect(status.manualFix).toContain("agentmemory status"); + expect(status.manualFix).not.toContain("Stop the process"); + }); + + it("worker-not-connected does not call an unrecognized service an engine", async () => { + const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => "unrecognized" })); + const check = diagnostics.find((d) => d.id === "worker-not-connected")!; + const status = await check.check(stubCtx()); + expect(status.ok).toBe(false); + expect(status.detail).toContain("iii engine port does not answer"); + expect(status.manualFix).toContain("AGENTMEMORY_URL"); + expect(status.manualFix).not.toContain("Stop the process"); + }); + it("worker-not-connected passes when the worker answers or the server is down", async () => { for (const connection of ["connected", "unreachable"] as const) { const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => connection })); diff --git a/test/cli-worker-connection.test.ts b/test/cli-worker-connection.test.ts index ea7e0d465d..10ff23cd57 100644 --- a/test/cli-worker-connection.test.ts +++ b/test/cli-worker-connection.test.ts @@ -1,5 +1,11 @@ -import { describe, expect, it, vi } from "vitest"; -import { engineOnlyLines, probeWorkerConnection } from "../src/cli/worker-connection.js"; +import { createServer, type Server } from "node:net"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { + engineOnlyLines, + probeWorkerConnection, + tcpPortOpen, + unrecognizedServiceLines, +} from "../src/cli/worker-connection.js"; function fakeFetch(routes: Record) { return vi.fn(async (url: string) => { @@ -10,37 +16,54 @@ function fakeFetch(routes: Record) { }); } +const busUp = async () => true; +const busDown = async () => false; + describe("probeWorkerConnection", () => { const base = "http://localhost:3111"; - it("reports engine-only when the engine returns 404 for the agentmemory routes", async () => { + it("reports engine-only when both routes return 404 and the engine bus answers", async () => { const fetchImpl = fakeFetch({ "/agentmemory/livez": 404, "/agentmemory/health": 404 }); - expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("engine-only"); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable: busUp })).toBe("engine-only"); + }); + + it("reports an unrecognized service when both routes return 404 and no engine bus answers", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 404, "/agentmemory/health": 404 }); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable: busDown })).toBe("unrecognized"); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl })).toBe("unrecognized"); + }); + + it("reports an unrecognized service when the engine bus check throws", async () => { + const fetchImpl = fakeFetch({ "/agentmemory/livez": 404, "/agentmemory/health": 404 }); + const engineBusReachable = async () => { throw new Error("bad url"); }; + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable })).toBe("unrecognized"); }); it("reports connected when the worker answers", async () => { const fetchImpl = fakeFetch({ "/agentmemory/livez": 200, "/agentmemory/health": 200 }); - expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("connected"); + const engineBusReachable = vi.fn(busUp); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable })).toBe("connected"); + expect(engineBusReachable).not.toHaveBeenCalled(); }); it("treats an auth rejection as a connected worker", async () => { const fetchImpl = fakeFetch({ "/agentmemory/livez": 401, "/agentmemory/health": 401 }); - expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("connected"); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl })).toBe("connected"); }); it("does not report engine-only when only one route is missing", async () => { const fetchImpl = fakeFetch({ "/agentmemory/livez": 404, "/agentmemory/health": 200 }); - expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("connected"); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable: busUp })).toBe("connected"); }); it("reports unreachable when nothing answers", async () => { const fetchImpl = fakeFetch({}); - expect(await probeWorkerConnection(base, {}, 500, fetchImpl)).toBe("unreachable"); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl })).toBe("unreachable"); }); it("sends the given headers to both routes", async () => { const fetchImpl = fakeFetch({ "/agentmemory/livez": 200, "/agentmemory/health": 200 }); - await probeWorkerConnection(base, { Authorization: "Bearer x" }, 500, fetchImpl); + await probeWorkerConnection(base, { headers: { Authorization: "Bearer x" }, timeoutMs: 500, fetchImpl }); expect(fetchImpl).toHaveBeenCalledTimes(2); for (const call of fetchImpl.mock.calls as unknown as Array<[string, { headers: Record }]>) { expect(call[1].headers).toEqual({ Authorization: "Bearer x" }); @@ -48,6 +71,25 @@ describe("probeWorkerConnection", () => { }); }); +describe("tcpPortOpen", () => { + let server: Server | null = null; + + afterEach(async () => { + await new Promise((resolve) => (server ? server.close(() => resolve()) : resolve())); + server = null; + }); + + it("reports an open and a closed port", async () => { + server = createServer((socket) => socket.destroy()); + await new Promise((resolve) => server!.listen(0, "127.0.0.1", () => resolve())); + const port = (server.address() as { port: number }).port; + expect(await tcpPortOpen("127.0.0.1", port, 500)).toBe(true); + await new Promise((resolve) => server!.close(() => resolve())); + server = null; + expect(await tcpPortOpen("127.0.0.1", port, 500)).toBe(false); + }); +}); + describe("engineOnlyLines", () => { it("explains the state, the start command and old Docker images", () => { const text = engineOnlyLines("http://localhost:3111").join("\n"); @@ -56,4 +98,19 @@ describe("engineOnlyLines", () => { expect(text).toContain("npx -y @agentmemory/agentmemory@latest"); expect(text).toContain("Docker"); }); + + it("uses the given start command so recovery keeps the selected port", () => { + const text = engineOnlyLines("http://localhost:4111", "npx -y @agentmemory/agentmemory@latest --port 4111").join("\n"); + expect(text).toContain("start agentmemory with: npx -y @agentmemory/agentmemory@latest --port 4111."); + }); +}); + +describe("unrecognizedServiceLines", () => { + it("does not claim an iii engine and does not tell the user to stop the service", () => { + const text = unrecognizedServiceLines("http://localhost:3111").join("\n"); + expect(text).toContain("A server answers at http://localhost:3111, but agentmemory does not."); + expect(text).not.toContain("iii engine is running"); + expect(text).not.toContain("Stop the process"); + expect(text).toContain("--port "); + }); }); From f804af4e2a368662a7c593bf6431deb4d4b55c47 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 19:24:58 +0530 Subject: [PATCH 4/7] fix(cli): show the Compose failure report when routes are missing When a managed Compose worker exhausted its restarts, the agentmemory routes answer 404 and status exited with the engine-only message. Status now continues to the normal report, which lists the Compose failure, as it did before. Signed-off-by: Rohit Ghumare --- src/cli.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index d56b7ce7ed..47dffc4cc0 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1904,11 +1904,10 @@ async function runStatus() { } const connection = await probeTargetWorker(base); - if (connection === "engine-only" || connection === "unrecognized") { - if (savedState?.kind === "compose") { - const failure = await savedComposeFailure(savedState); - if (failure) exitWithComposeFailure(savedState, failure, `the agentmemory routes are unavailable at ${base}`); - } + const composeExplainsMissingRoutes = (connection === "engine-only" || connection === "unrecognized") + && savedState?.kind === "compose" + && (await savedComposeFailure(savedState)) !== null; + if ((connection === "engine-only" || connection === "unrecognized") && !composeExplainsMissingRoutes) { const lines = connection === "engine-only" ? engineOnlyLines(base, recoveryStartCommand()) : unrecognizedServiceLines(base); From d5fa720b1d8965379922365fe2e06a632a8c97b4 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 19:29:29 +0530 Subject: [PATCH 5/7] fix(cli): keep the target in recovery hints and tighten worker probes Status and doctor recovery commands now keep --instance, --port and a shell-quoted --data-dir for status, stop and start. A route that fails next to a 404 no longer counts as a connected worker. Status exits 1 when the worker routes do not respond. The engine bus probe honors III_URL when III_ENGINE_URL is unset. The doctor message no longer claims an engine is running, and the unrecognized-service hint points old Docker images at the migration guide. Signed-off-by: Rohit Ghumare --- src/cli.ts | 40 ++++++++++++++++++-------- src/cli/doctor-diagnostics.ts | 10 ++++--- src/cli/worker-connection.ts | 13 ++++++++- test/cli-doctor-fixes.test.ts | 12 ++++++++ test/cli-worker-connection.test.ts | 45 ++++++++++++++++++++++++++++++ 5 files changed, 104 insertions(+), 16 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index 47dffc4cc0..dfbebc8d5f 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -105,7 +105,7 @@ import { bearerHeaders, resolveClientSecret } from "./secret-store.js"; import { assertComposePortsFree, composeCall, composeRegistryFailureMessage, composeStateRegistryFailure, composeWorkerFailureSummary, ownedComposeProject, readComposeLogFromOffset, startComposeDaemon, writeComposeState, type ComposeStatus } from "./cli/compose-control.js"; import { COMPOSE_WORKER_VERSIONS, composeDownTimeoutMs, composeNamespace } from "./cli/compose-project.js"; import { legacyDockerStateMessage, type LegacyDockerEngineState } from "./cli/legacy-docker-state.js"; -import { DEFAULT_START_COMMAND, engineOnlyLines, probeWorkerConnection, tcpPortOpen, unrecognizedServiceLines, type WorkerConnection } from "./cli/worker-connection.js"; +import { DEFAULT_START_COMMAND, engineOnlyLines, probeWorkerConnection, shellArg, tcpPortOpen, unrecognizedServiceLines, type WorkerConnection } from "./cli/worker-connection.js"; const __dirname = dirname(fileURLToPath(import.meta.url)); const args = process.argv.slice(2); @@ -1842,19 +1842,34 @@ async function apiFetch(base: string, path: string, timeoutMs = 500 } } -function recoveryStartCommand(): string { - const parts = [DEFAULT_START_COMMAND]; +function recoveryTargetArgs(): string { + const parts: string[] = []; if (hasInstanceArgument) parts.push(`--instance ${selectedInstance}`); if (portValue || (!hasInstanceArgument && getRestPort() !== 3111)) parts.push(`--port ${getRestPort()}`); const dataDir = cliArgValue("--data-dir"); - if (dataDir) parts.push(`--data-dir ${/\s/.test(dataDir) ? JSON.stringify(dataDir) : dataDir}`); - return parts.join(" "); + if (dataDir) parts.push(`--data-dir ${shellArg(dataDir)}`); + return parts.map((part) => ` ${part}`).join(""); +} + +function recoveryStartCommand(): string { + return `${DEFAULT_START_COMMAND}${recoveryTargetArgs()}`; +} + +function workerEnginePort(): number { + const workerUrl = process.env["III_URL"]; + if (!process.env["III_ENGINE_URL"] && workerUrl) { + try { + const parsed = new URL(workerUrl).port; + if (parsed) return parseInt(parsed, 10); + } catch {} + } + return getEnginePort(); } function probeTargetWorker(base: string): Promise { return probeWorkerConnection(base, { headers: bearerHeaders(base), - engineBusReachable: async () => tcpPortOpen(new URL(base).hostname.replace(/^\[|\]$/g, ""), getEnginePort()), + engineBusReachable: async () => tcpPortOpen(new URL(base).hostname.replace(/^\[|\]$/g, ""), workerEnginePort()), }); } @@ -1904,13 +1919,15 @@ async function runStatus() { } const connection = await probeTargetWorker(base); - const composeExplainsMissingRoutes = (connection === "engine-only" || connection === "unrecognized") + const workerMissing = connection !== "connected"; + const composeExplainsMissingRoutes = workerMissing && savedState?.kind === "compose" && (await savedComposeFailure(savedState)) !== null; - if ((connection === "engine-only" || connection === "unrecognized") && !composeExplainsMissingRoutes) { - const lines = connection === "engine-only" - ? engineOnlyLines(base, recoveryStartCommand()) - : unrecognizedServiceLines(base); + if (workerMissing && !composeExplainsMissingRoutes) { + let lines: string[]; + if (connection === "engine-only") lines = engineOnlyLines(base, recoveryStartCommand()); + else if (connection === "unrecognized") lines = unrecognizedServiceLines(base); + else lines = [`A server answers at ${base}, but /agentmemory/livez and /agentmemory/health did not respond.`, "Check the agentmemory logs, then run status again."]; p.log.error(lines.join("\n")); process.exit(1); } @@ -2096,6 +2113,7 @@ function buildDoctorContext(): DoctorContext { enginePath: engineStatePath(), pinnedVersion: IIPINNED_VERSION, startCommand: recoveryStartCommand(), + targetArgs: recoveryTargetArgs(), }; } diff --git a/src/cli/doctor-diagnostics.ts b/src/cli/doctor-diagnostics.ts index b6d70de879..3063f49fe9 100644 --- a/src/cli/doctor-diagnostics.ts +++ b/src/cli/doctor-diagnostics.ts @@ -24,7 +24,7 @@ import { llmOptInHint, parseEnvContent, } from "../config.js"; -import { DEFAULT_START_COMMAND, ENGINE_ONLY_DOCKER_GUIDE, engineOnlyFix, UNRECOGNIZED_SERVICE_FIX, type WorkerConnection } from "./worker-connection.js"; +import { DEFAULT_START_COMMAND, ENGINE_ONLY_DOCKER_GUIDE, engineOnlyFix, UNRECOGNIZED_DOCKER_NOTE, UNRECOGNIZED_SERVICE_FIX, type WorkerConnection } from "./worker-connection.js"; export type DiagnosticStatus = { ok: boolean; @@ -52,6 +52,7 @@ export type DoctorContext = { /** Pinned engine version. */ pinnedVersion: string; startCommand?: string; + targetArgs?: string; }; export type DoctorWorkerConnection = WorkerConnection | "managed-worker-down"; @@ -304,7 +305,7 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { }, { id: "worker-not-connected", - message: "The iii engine is running, but the agentmemory worker is not connected to it.", + message: "The server answers, but the agentmemory worker routes return 404.", fixPreview: engineOnlyFix(), moreInfo: "The REST port answers, but /agentmemory/livez and /agentmemory/health return 404. " + @@ -316,6 +317,7 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { check: async (ctx) => { const connection = await effects.workerConnection(); const startCommand = ctx.startCommand ?? DEFAULT_START_COMMAND; + const targetArgs = ctx.targetArgs ?? ""; if (connection === "engine-only") { return { ok: false, @@ -327,14 +329,14 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] { return { ok: false, detail: `managed Worker Compose engine at ${ctx.baseUrl} has no agentmemory routes (404)`, - manualFix: `Run agentmemory status to see the Worker Compose failure report, then run agentmemory stop and start again with: ${startCommand}.`, + manualFix: `Run agentmemory status${targetArgs} to see the Worker Compose failure report, then run agentmemory stop${targetArgs} and start again with: ${startCommand}.`, }; } if (connection === "unrecognized") { return { ok: false, detail: `server at ${ctx.baseUrl} returns 404 for the agentmemory routes and the iii engine port does not answer`, - manualFix: UNRECOGNIZED_SERVICE_FIX, + manualFix: `${UNRECOGNIZED_SERVICE_FIX} ${UNRECOGNIZED_DOCKER_NOTE}`, }; } if (connection === "unreachable") return { ok: true, detail: "server not reachable (see Server reachable)" }; diff --git a/src/cli/worker-connection.ts b/src/cli/worker-connection.ts index d587cddf91..1cd04fbb2a 100644 --- a/src/cli/worker-connection.ts +++ b/src/cli/worker-connection.ts @@ -55,7 +55,8 @@ export async function probeWorkerConnection( routeStatus(`${base}/agentmemory/health`, headers, timeoutMs, fetchImpl), ]); if (livez === null && health === null) return "unreachable"; - if (livez !== 404 || health !== 404) return "connected"; + const answered = (status: number | null) => status !== null && status !== 404; + if (answered(livez) || answered(health)) return "connected"; const busReachable = options.engineBusReachable ? await options.engineBusReachable().catch(() => false) : false; @@ -71,6 +72,15 @@ export function engineOnlyFix(startCommand = DEFAULT_START_COMMAND): string { return `Stop the process that owns this port (an old Docker container or an iii you started yourself), then start agentmemory with: ${startCommand}. For Docker, run the current image instead.`; } +export function shellArg(value: string, platform: NodeJS.Platform = process.platform): string { + if (platform === "win32") return /^[A-Za-z0-9._:\\/-]+$/.test(value) ? value : `"${value}"`; + if (/^[A-Za-z0-9._:/@%+=,-]+$/.test(value)) return value; + return `'${value.replace(/'/g, `'"'"'`)}'`; +} + +export const UNRECOGNIZED_DOCKER_NOTE = + `Old Docker images from the legacy CLI Docker mode keep the engine port inside the container and also show this state. Docker migration: ${ENGINE_ONLY_DOCKER_GUIDE}`; + export const UNRECOGNIZED_SERVICE_FIX = `Check that AGENTMEMORY_URL or --port points at agentmemory. If another program owns this port, start agentmemory on a free port with: ${DEFAULT_START_COMMAND} --port .`; @@ -88,6 +98,7 @@ export function unrecognizedServiceLines(base: string): string[] { return [ `A server answers at ${base}, but agentmemory does not.`, "It returns 404 for /agentmemory/livez and /agentmemory/health, and the iii engine port does not answer. It can be another program on this port, or a remote iii engine without the agentmemory worker.", + UNRECOGNIZED_DOCKER_NOTE, `Fix: ${UNRECOGNIZED_SERVICE_FIX}`, ]; } diff --git a/test/cli-doctor-fixes.test.ts b/test/cli-doctor-fixes.test.ts index b758ea3912..50b09dc268 100644 --- a/test/cli-doctor-fixes.test.ts +++ b/test/cli-doctor-fixes.test.ts @@ -516,6 +516,15 @@ describe("doctor v2 diagnostic catalog", () => { expect(status.manualFix).not.toContain("Stop the process"); }); + it("worker-not-connected keeps the selected instance in the managed Compose recovery commands", async () => { + const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => "managed-worker-down" })); + const check = diagnostics.find((d) => d.id === "worker-not-connected")!; + const status = await check.check({ ...stubCtx(), targetArgs: " --instance 1", startCommand: "npx -y @agentmemory/agentmemory@latest --instance 1" }); + expect(status.manualFix).toContain("agentmemory status --instance 1 "); + expect(status.manualFix).toContain("agentmemory stop --instance 1 "); + expect(status.manualFix).toContain("start again with: npx -y @agentmemory/agentmemory@latest --instance 1."); + }); + it("worker-not-connected does not call an unrecognized service an engine", async () => { const diagnostics = buildDiagnostics(stubEffects({ workerConnection: async () => "unrecognized" })); const check = diagnostics.find((d) => d.id === "worker-not-connected")!; @@ -524,6 +533,9 @@ describe("doctor v2 diagnostic catalog", () => { expect(status.detail).toContain("iii engine port does not answer"); expect(status.manualFix).toContain("AGENTMEMORY_URL"); expect(status.manualFix).not.toContain("Stop the process"); + const report = failureReport(check, status); + expect(report.problem).not.toContain("iii engine is running"); + expect(report.fix).toContain("legacy CLI Docker mode"); }); it("worker-not-connected passes when the worker answers or the server is down", async () => { diff --git a/test/cli-worker-connection.test.ts b/test/cli-worker-connection.test.ts index 10ff23cd57..8ad42059d3 100644 --- a/test/cli-worker-connection.test.ts +++ b/test/cli-worker-connection.test.ts @@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import { engineOnlyLines, probeWorkerConnection, + shellArg, tcpPortOpen, unrecognizedServiceLines, } from "../src/cli/worker-connection.js"; @@ -56,6 +57,26 @@ describe("probeWorkerConnection", () => { expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable: busUp })).toBe("connected"); }); + it("checks the engine bus when one route returns 404 and the other request fails", async () => { + for (const routes of [ + { "/agentmemory/livez": 404 }, + { "/agentmemory/health": 404 }, + ]) { + const fetchImpl = fakeFetch(routes); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable: busUp })).toBe("engine-only"); + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl, engineBusReachable: busDown })).toBe("unrecognized"); + } + }); + + it("reports connected when one route answers and the other request fails", async () => { + for (const routes of [ + { "/agentmemory/livez": 200 }, + { "/agentmemory/health": 200 }, + ]) { + expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl: fakeFetch(routes) })).toBe("connected"); + } + }); + it("reports unreachable when nothing answers", async () => { const fetchImpl = fakeFetch({}); expect(await probeWorkerConnection(base, { timeoutMs: 500, fetchImpl })).toBe("unreachable"); @@ -113,4 +134,28 @@ describe("unrecognizedServiceLines", () => { expect(text).not.toContain("Stop the process"); expect(text).toContain("--port "); }); + + it("points old Docker images that keep the engine port internal at the migration guide", () => { + const text = unrecognizedServiceLines("http://localhost:3111").join("\n"); + expect(text).toContain("legacy CLI Docker mode"); + expect(text).toContain("#migrating-from-the-legacy-cli-docker-mode"); + }); +}); + +describe("shellArg", () => { + it("leaves plain paths unquoted", () => { + expect(shellArg("/home/alice/data", "linux")).toBe("/home/alice/data"); + expect(shellArg("C:\\Users\\alice\\data", "win32")).toBe("C:\\Users\\alice\\data"); + }); + + it("quotes apostrophes, backslashes, spaces and dollar signs for POSIX shells", () => { + expect(shellArg("/home/alice/O'Reilly", "darwin")).toBe(`'/home/alice/O'"'"'Reilly'`); + expect(shellArg("/tmp/a b", "linux")).toBe("'/tmp/a b'"); + expect(shellArg("/tmp/a\\b", "linux")).toBe("'/tmp/a\\b'"); + expect(shellArg("/tmp/$HOME", "linux")).toBe("'/tmp/$HOME'"); + }); + + it("double-quotes Windows paths with spaces or apostrophes", () => { + expect(shellArg("C:\\Users\\O'Reilly\\my data", "win32")).toBe(`"C:\\Users\\O'Reilly\\my data"`); + }); }); From 6359e2c6348171fafce968b15c32f3dce35b7c2c Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 20:22:39 +0530 Subject: [PATCH 6/7] fix(cli): quote Windows data directories for PowerShell On Windows the recovery hint now puts --data-dir in PowerShell single quotes, so dollar signs and apostrophes stay literal. Trailing path separators are dropped, so no backslash comes before a closing quote. Signed-off-by: Rohit Ghumare --- src/cli/worker-connection.ts | 5 ++++- test/cli-worker-connection.test.ts | 11 +++++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/src/cli/worker-connection.ts b/src/cli/worker-connection.ts index 1cd04fbb2a..367975a9a4 100644 --- a/src/cli/worker-connection.ts +++ b/src/cli/worker-connection.ts @@ -73,7 +73,10 @@ export function engineOnlyFix(startCommand = DEFAULT_START_COMMAND): string { } export function shellArg(value: string, platform: NodeJS.Platform = process.platform): string { - if (platform === "win32") return /^[A-Za-z0-9._:\\/-]+$/.test(value) ? value : `"${value}"`; + if (platform === "win32") { + const trimmed = /^[A-Za-z]:\\$/.test(value) ? value : value.replace(/[\\/]+$/, "") || value; + return /^[A-Za-z0-9._:\\/-]+$/.test(trimmed) ? trimmed : `'${trimmed.replace(/'/g, "''")}'`; + } if (/^[A-Za-z0-9._:/@%+=,-]+$/.test(value)) return value; return `'${value.replace(/'/g, `'"'"'`)}'`; } diff --git a/test/cli-worker-connection.test.ts b/test/cli-worker-connection.test.ts index 8ad42059d3..86738feb72 100644 --- a/test/cli-worker-connection.test.ts +++ b/test/cli-worker-connection.test.ts @@ -155,7 +155,14 @@ describe("shellArg", () => { expect(shellArg("/tmp/$HOME", "linux")).toBe("'/tmp/$HOME'"); }); - it("double-quotes Windows paths with spaces or apostrophes", () => { - expect(shellArg("C:\\Users\\O'Reilly\\my data", "win32")).toBe(`"C:\\Users\\O'Reilly\\my data"`); + it("single-quotes Windows paths for PowerShell so apostrophes and dollar signs stay literal", () => { + expect(shellArg("C:\\Users\\O'Reilly\\my data", "win32")).toBe(`'C:\\Users\\O''Reilly\\my data'`); + expect(shellArg("C:\\data\\$archive", "win32")).toBe(`'C:\\data\\$archive'`); + }); + + it("drops trailing Windows separators so no backslash precedes a closing quote", () => { + expect(shellArg("C:\\my data\\", "win32")).toBe(`'C:\\my data'`); + expect(shellArg("C:\\data\\", "win32")).toBe("C:\\data"); + expect(shellArg("C:\\", "win32")).toBe("C:\\"); }); }); From 7f497c13c2398841afdb0eaabeb9d2a739e3f643 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 11 Nov 2026 21:06:13 +0530 Subject: [PATCH 7/7] fix(cli): keep drive roots and use double quotes for Windows paths A drive root such as C:/ keeps its separator in recovery hints. Windows paths that need quoting use double quotes, which Command Prompt and PowerShell both read literally. Paths with a dollar sign keep PowerShell single quotes. Signed-off-by: Rohit Ghumare --- src/cli/worker-connection.ts | 6 ++++-- test/cli-worker-connection.test.ts | 12 +++++++++--- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/src/cli/worker-connection.ts b/src/cli/worker-connection.ts index 367975a9a4..b3f535b536 100644 --- a/src/cli/worker-connection.ts +++ b/src/cli/worker-connection.ts @@ -74,8 +74,10 @@ export function engineOnlyFix(startCommand = DEFAULT_START_COMMAND): string { export function shellArg(value: string, platform: NodeJS.Platform = process.platform): string { if (platform === "win32") { - const trimmed = /^[A-Za-z]:\\$/.test(value) ? value : value.replace(/[\\/]+$/, "") || value; - return /^[A-Za-z0-9._:\\/-]+$/.test(trimmed) ? trimmed : `'${trimmed.replace(/'/g, "''")}'`; + const trimmed = /^[A-Za-z]:[\\/]$/.test(value) ? value : value.replace(/[\\/]+$/, "") || value; + if (/^[A-Za-z0-9._:\\/-]+$/.test(trimmed)) return trimmed; + if (!/[$`%"]/.test(trimmed)) return `"${trimmed}"`; + return `'${trimmed.replace(/'/g, "''")}'`; } if (/^[A-Za-z0-9._:/@%+=,-]+$/.test(value)) return value; return `'${value.replace(/'/g, `'"'"'`)}'`; diff --git a/test/cli-worker-connection.test.ts b/test/cli-worker-connection.test.ts index 86738feb72..f71cc597c4 100644 --- a/test/cli-worker-connection.test.ts +++ b/test/cli-worker-connection.test.ts @@ -155,14 +155,20 @@ describe("shellArg", () => { expect(shellArg("/tmp/$HOME", "linux")).toBe("'/tmp/$HOME'"); }); - it("single-quotes Windows paths for PowerShell so apostrophes and dollar signs stay literal", () => { - expect(shellArg("C:\\Users\\O'Reilly\\my data", "win32")).toBe(`'C:\\Users\\O''Reilly\\my data'`); + it("double-quotes Windows paths so Command Prompt and PowerShell keep spaces and metacharacters literal", () => { + expect(shellArg("C:\\my data", "win32")).toBe(`"C:\\my data"`); + expect(shellArg("C:\\Users\\O'Reilly\\a & calc & rem", "win32")).toBe(`"C:\\Users\\O'Reilly\\a & calc & rem"`); + }); + + it("single-quotes Windows paths with dollar signs so PowerShell keeps them literal", () => { expect(shellArg("C:\\data\\$archive", "win32")).toBe(`'C:\\data\\$archive'`); + expect(shellArg("C:\\O'Reilly\\$x", "win32")).toBe(`'C:\\O''Reilly\\$x'`); }); it("drops trailing Windows separators so no backslash precedes a closing quote", () => { - expect(shellArg("C:\\my data\\", "win32")).toBe(`'C:\\my data'`); + expect(shellArg("C:\\my data\\", "win32")).toBe(`"C:\\my data"`); expect(shellArg("C:\\data\\", "win32")).toBe("C:\\data"); expect(shellArg("C:\\", "win32")).toBe("C:\\"); + expect(shellArg("C:/", "win32")).toBe("C:/"); }); });