@elvatis_com/openclaw-cli-bridge-elvatis 0.2.6 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/.ai/handoff/CONVENTIONS.md +34 -3
  2. package/.ai/handoff/DASHBOARD.md +27 -65
  3. package/.ai/handoff/LOG.md +40 -24
  4. package/.ai/handoff/NEXT_ACTIONS.md +29 -25
  5. package/.ai/handoff/STATUS.md +24 -26
  6. package/.clawhubignore +6 -5
  7. package/README.md +1 -1
  8. package/index.ts +29 -12
  9. package/openclaw.plugin.json +1 -1
  10. package/package.json +1 -1
package/.ai/handoff/CONVENTIONS.md CHANGED
@@ -26,6 +26,37 @@ package.json / tsconfig.json
26
26
  - Error messages must include actionable fix hint (e.g. "Run 'codex login' and retry")
27
27
 
28
28
  ## Release Checklist (mandatory for every publish)
29
- 1. GitHub tag + release (elvatis org)
30
- 2. `npm publish --access public`
31
- 3. `clawhub publish`
29
+
30
+ ### Before release
31
+ 1. `npm run typecheck` — must pass
32
+ 2. `npm test` — all tests must pass
33
+ 3. Bump version in `package.json` AND `openclaw.plugin.json`
34
+
35
+ ### Publish (all three platforms, no exceptions)
36
+ 4. `git tag vX.Y.Z && git push origin main && git push origin vX.Y.Z`
37
+ 5. `gh release create vX.Y.Z --title "..." --notes "..."`
38
+ 6. `npm publish --access public`
39
+ 7. ClawHub (use rsync workaround — `.clawhubignore` is NOT respected by `clawhub publish`):
40
+ ```bash
41
+ TMP=$(mktemp -d)
42
+ rsync -a --exclude='node_modules' --exclude='.git' --exclude='dist' \
43
+ --exclude='package-lock.json' ./ "$TMP/"
44
+ clawhub publish "$TMP" --slug openclaw-cli-bridge-elvatis \
45
+ --name "OpenClaw CLI Bridge" --version X.Y.Z --changelog "..." --no-input
46
+ rm -rf "$TMP"
47
+ ```
48
+
49
+ ### After release
50
+ 8. Update ALL docs in this repo: STATUS.md, DASHBOARD.md, LOG.md, NEXT_ACTIONS.md, README.md, SKILL.md
51
+ 9. Update MEMORY.md on server if architecture decisions changed
52
+
53
+ ## Documentation Rule (MANDATORY)
54
+ **Every release MUST update the following files before committing:**
55
+ - `.ai/handoff/STATUS.md` — current version, state, open risks
56
+ - `.ai/handoff/DASHBOARD.md` — task table
57
+ - `.ai/handoff/LOG.md` — append entry for this session
58
+ - `.ai/handoff/NEXT_ACTIONS.md` — move done tasks, add new ones
59
+ - `README.md` — version number + any changed behavior
60
+ - `SKILL.md` — if commands or config changed
61
+
62
+ Skipping documentation = incomplete release. No exceptions.
package/.ai/handoff/DASHBOARD.md CHANGED
@@ -1,74 +1,36 @@
1
- # [PROJECT]: Build Dashboard
1
+ # DASHBOARD.md — openclaw-cli-bridge-elvatis
2
2
 
3
- > Single source of truth for build health, test coverage, and pipeline state.
4
- > Updated by agents at the end of every completed task.
3
+ _Last updated: 2026-03-07_
5
4
 
6
- ---
5
+ ## 🏗️ Plugin Status
7
6
 
8
- ## 🏗️ Services / Components
7
+ | Component | Version | Build | Tests | Status |
8
+ |-----------|---------|-------|-------|--------|
9
+ | openclaw-cli-bridge-elvatis | 0.2.6 | ✅ | 5/5 ✅ | ✅ Stable |
9
10
 
10
- | Name | Version | Build | Tests | Status | Notes |
11
- |------|---------|-------|-------|--------|-------|
12
- | service-a | - | ✅ | - | ✅ | |
13
- | service-b | - | ✅ | 42/42 ✅ | ✅ | |
14
- | service-c | - | ❌ | - | 🔴 Broken | See LOG.md |
11
+ ## 🚀 Release State
15
12
 
16
- **Legend:** ✅ passing · ❌ failing · 🔵 stub/mock · ⏳ pending · 🔴 blocked
13
+ | Platform | Version | Status |
14
+ |----------|---------|--------|
15
+ | GitHub | v0.2.6 | ✅ Tagged + Release |
16
+ | npm | 0.2.6 | ✅ Published |
17
+ | ClawHub | 0.2.6 | ✅ Published |
17
18
 
18
- ---
19
+ ## 📋 Open Tasks
19
20
 
20
- ## 🧪 Test Coverage
21
+ | ID | Task | Priority | Status |
22
+ |----|------|----------|--------|
23
+ | T-101 | Unit tests for prompt formatter + model router | 🟡 MEDIUM | Ready |
24
+ | T-102 | Proxy auth key rotation via config | 🟢 LOW | Ready |
25
+ | T-103 | Explicit model allowlist for CLI execution | 🟢 LOW | Ready |
21
26
 
22
- | Suite | Tests | Status | Last Run |
23
- |-------|-------|--------|----------|
24
- | unit | - | - | - |
25
- | integration | - | - | - |
26
- | e2e | - | - | - |
27
+ ## ✅ Completed Tasks
27
28
 
28
- ---
29
-
30
- ## 🚀 Infrastructure / Deployment
31
-
32
- | Component | Status | Blocker |
33
- |-----------|--------|---------|
34
- | Local dev stack | ✅ | - |
35
- | Staging | ⏳ Not deployed | Needs credentials |
36
- | Production | ⏳ Not deployed | Needs credentials |
37
-
38
- ---
39
-
40
- ## 🤖 Pipeline State
41
-
42
- | Field | Value |
43
- |-------|-------|
44
- | Current task | - |
45
- | Phase | idle |
46
- | Last completed | - |
47
- | Rate limit | None |
48
-
49
- ---
50
-
51
- ## 📋 Open Tasks (strategic priority)
52
-
53
- | ID | Task | Priority | Blocked by | Ready? |
54
- |----|------|----------|-----------|--------|
55
- | T-001 | Describe task here | 🔴 HIGH | - | ✅ Ready |
56
- | T-002 | Another task | 🟠 MEDIUM | Waiting for X | 🔴 Blocked |
57
-
58
- ---
59
-
60
- ## 🔄 Update Instructions (for agents)
61
-
62
- After completing any task:
63
-
64
- 1. Update the relevant row to ✅ with current date
65
- 2. Update test counts
66
- 3. Update "Pipeline State"
67
- 4. Move completed task out of "Open Tasks"
68
- 5. Add newly discovered tasks with correct priority
69
-
70
- **Pipeline rules:**
71
- - Blocked task → skip, take next unblocked
72
- - All tasks blocked → notify the project owner
73
- - Notify project owner only on **fully completed tasks**, not phase transitions
74
- - On test failures: attempt 1–2 self-fixes before escalating
29
+ | Task | Title | Version |
30
+ |------|-------|---------|
31
+ | T-006 | Fix port leak: registerService stop() hook for proxy server | 0.2.6 |
32
+ | T-005 | Add openclaw.extensions to package.json | 0.2.6 |
33
+ | T-004 | /cli-codex + /cli-codex-mini slash commands | 0.2.5 |
34
+ | T-003 | /cli-back restore + /cli-test health check | 0.2.3 |
35
+ | T-002 | /cli-* model switch slash commands (Phase 3) | 0.2.2 |
36
+ | T-001 | Phase 1+2: auth bridge + local proxy + config patcher | 0.2.0 |
package/.ai/handoff/LOG.md CHANGED
@@ -1,28 +1,44 @@
1
1
  # LOG.md — openclaw-cli-bridge-elvatis
2
2
 
3
+ ## 2026-03-07 — Session 2 (Akido / claude-sonnet-4-6)
4
+
5
+ **Bug: Port leak on gateway hot-reload (fixed in v0.2.6)**
6
+
7
+ Root cause: HTTP proxy server on port 31337 had no cleanup handler. On hot-reloads
8
+ or gateway restarts, the old server instance kept the port bound. New plugin instance
9
+ couldn't bind → EADDRINUSE → proxy failed silently.
10
+
11
+ Fix: added `api.registerService({ id: "cli-bridge-proxy", stop: async () => server.close() })`
12
+ so OpenClaw calls `stop()` on plugin teardown.
13
+
14
+ Also added missing `openclaw.extensions` field to `package.json` (required for `openclaw plugins install --link`).
15
+ Added `.clawhubignore` and documented rsync workaround in CONVENTIONS.md (clawhub publish ignores .clawhubignore).
16
+
17
+ **Root conflict with openclaw-self-healing-elvatis:**
18
+ The infinite restart loop was caused by self-healing's `lastRestartAt` being saved after
19
+ `openclaw gateway restart` (which kills the process). Fixed in self-healing v0.2.8.
20
+ Both plugins now stable together.
21
+
22
+ **Release pipeline:**
23
+ - v0.2.6 committed, tagged, pushed to GitHub
24
+ - GitHub release: https://github.com/elvatis/openclaw-cli-bridge-elvatis/releases/tag/v0.2.6
25
+ - npm published: `@elvatis_com/openclaw-cli-bridge-elvatis@0.2.6`
26
+ - ClawHub published: `openclaw-cli-bridge-elvatis@0.2.6`
27
+
28
+ ---
29
+
3
30
  ## 2026-03-07 — Session 1 (gpt-5.3-codex / sonnet)
4
31
 
5
- **Major progress**
6
- - Implemented and verified Codex auth bridge for provider `openai-codex`.
7
- - Resolved "Unknown provider openai-codex" by registering provider in plugin.
8
- - Added `.gitignore` for build artifacts + secrets.
9
- - Created GitHub repo under `elvatis`: https://github.com/elvatis/openclaw-cli-bridge-elvatis
10
- - Pushed initial release code and follow-up fix for AAHP version label.
11
-
12
- **Architecture upgrade**
13
- - Added full request-bridge components:
14
- - `src/cli-runner.ts`
15
- - `src/proxy-server.ts`
16
- - `src/config-patcher.ts`
17
- - Updated plugin to `0.2.0` conceptually (manifest), with phase split:
18
- - Phase 1: auth bridge (`openai-codex`)
19
- - Phase 2: HTTP proxy + vllm mapping (`cli-gemini/*`, `cli-claude/*`)
20
-
21
- **Operational notes**
22
- - `openai-codex/gpt-5.4` returns 401 missing scope `model.request`.
23
- - `openai-codex/gpt-5.3-codex` selected as current dev model.
24
- - Self-heal startup warning investigated; startup cleanup delay increased in `openclaw-self-healing-elvatis`.
25
-
26
- **Next**
27
- - Validate proxy endpoints + live vllm model calls end-to-end.
28
- - Then release pipeline (GitHub tag, npm, ClawHub).
32
+ **Architecture: Phase 1 + 2 + 3 implemented**
33
+
34
+ - Phase 1: `openai-codex` auth bridge via `~/.codex/auth.json`
35
+ - Phase 2: local OpenAI-compatible proxy (`src/proxy-server.ts`, `src/cli-runner.ts`, `src/config-patcher.ts`)
36
+ - Gemini CLI → `cli-gemini/*` models
37
+ - Claude Code CLI → `cli-claude/*` models
38
+ - Prompt delivery via stdin (avoids E2BIG + Gemini agentic mode)
39
+ - Phase 3: `/cli-sonnet`, `/cli-opus`, `/cli-haiku`, `/cli-gemini`, `/cli-gemini-flash`, `/cli-gemini3`, `/cli-codex`, `/cli-codex-mini`, `/cli-back`, `/cli-test`
40
+
41
+ - Published to GitHub, npm, ClawHub at v0.2.5
42
+
43
+ **Known issue at time of session:**
44
+ - `openai-codex/gpt-5.4` → 401 missing scope `model.request` (external, OpenAI account limitation)
package/.ai/handoff/NEXT_ACTIONS.md CHANGED
@@ -2,36 +2,40 @@
2
2
 
3
3
  _Last updated: 2026-03-07_
4
4
 
5
- ## Immediate
5
+ ## Status Summary
6
6
 
7
- 1. **Validate proxy runtime**
8
- - Confirm local proxy listens on `127.0.0.1:31337`
9
- - Test:
10
- - `GET /v1/models`
11
- - `POST /v1/chat/completions` (non-stream + stream)
7
+ | Status | Count |
8
+ |--------|-------|
9
+ | Done | 6 |
10
+ | Ready | 3 |
11
+ | Blocked | 0 |
12
12
 
13
- 2. **Validate OpenClaw vllm integration**
14
- - Ensure `models.providers.vllm` contains `cli-gemini/*` + `cli-claude/*`
15
- - Send live test prompts with:
16
- - `vllm/cli-gemini/gemini-2.5-pro`
17
- - `vllm/cli-claude/claude-sonnet-4-6`
13
+ ---
18
14
 
19
- 3. **Stability pass**
20
- - Confirm timeout behavior and error mapping (CLI exits, malformed output)
21
- - Confirm no secret leakage in logs
15
+ ## Ready — Work These Next
22
16
 
23
- ## Next
17
+ ### T-101: [medium] — Unit tests for prompt formatter + model router
18
+ - **Goal:** Cover `src/cli-runner.ts` message formatting and model routing logic with vitest tests.
19
+ - **Files:** `test/cli-runner.test.ts`, `src/cli-runner.ts`
20
+ - **Definition of done:** Prompt truncation, stdin format, and model→CLI mapping covered by tests.
24
21
 
25
- 4. **Self-heal integration**
26
- - Update `openclaw-self-healing-elvatis` model order for dev-safe default fallback chain.
22
+ ### T-102: [low] — Proxy auth key rotation via config
23
+ - **Goal:** Allow `proxyApiKey` to be rotated without code change via config reload.
24
+ - **Files:** `index.ts`, `src/proxy-server.ts`
27
25
 
28
- 5. **Release pipeline**
29
- - GitHub release tag
30
- - npm publish (`@elvatis_com/openclaw-cli-bridge-elvatis`)
31
- - ClawHub publish
26
+ ### T-103: [low] — Explicit model allowlist for CLI execution
27
+ - **Goal:** Config-driven allowlist of which model IDs are permitted to spawn CLI subprocesses.
28
+ - **Files:** `index.ts`, `src/cli-runner.ts`
32
29
 
33
- ## Optional hardening
30
+ ---
34
31
 
35
- - Add unit tests for prompt formatter + model router
36
- - Add proxy auth key rotation via config
37
- - Add explicit model allowlist for CLI execution
32
+ ## Recently Completed
33
+
34
+ | Task | Title | Date |
35
+ |------|-------|------|
36
+ | T-006 | Fix port leak: registerService stop() hook | 2026-03-07 |
37
+ | T-005 | Add openclaw.extensions to package.json | 2026-03-07 |
38
+ | T-004 | /cli-codex + /cli-codex-mini | 2026-03-07 |
39
+ | T-003 | /cli-back + /cli-test | 2026-03-07 |
40
+ | T-002 | /cli-* model switch commands | 2026-03-07 |
41
+ | T-001 | Phase 1+2: auth + proxy + config patcher | 2026-03-07 |
package/.ai/handoff/STATUS.md CHANGED
@@ -1,32 +1,30 @@
1
1
  # STATUS.md — openclaw-cli-bridge-elvatis
2
2
 
3
- _Last updated: 2026-03-07 by gpt-5.3-codex_
3
+ _Last updated: 2026-03-07 by Akido (claude-sonnet-4-6)_
4
4
 
5
- ## Phase: Integration & validation
5
+ ## Current Version: 0.2.6 — STABLE
6
6
 
7
7
  ## What is done
8
8
 
9
- - ✅ Repo created: `https://github.com/elvatis/openclaw-cli-bridge-elvatis`
10
- - ✅ AAHP handoff in `.ai/handoff/` (v3)
11
- - ✅ Phase 1 implemented: `openai-codex` auth bridge via `~/.codex/auth.json`
12
- - ✅ Auth flow verified with `openclaw models auth login --provider openai-codex`
13
- - ✅ Session model switching verified (`gpt-5.3-codex` works)
14
- - ✅ Phase 2 implemented: local OpenAI-compatible proxy server (`src/proxy-server.ts`)
15
- - ✅ CLI routing implemented (`src/cli-runner.ts`):
16
- - `cli-gemini/*` → `gemini`
17
- - `cli-claude/*` → `claude`
18
- - ✅ Config patcher implemented (`src/config-patcher.ts`) for `models.providers.vllm`
19
-
20
- ## Current state
21
-
22
- - Development model pinned to: `openai-codex/gpt-5.3-codex`
23
- - `openai-codex/gpt-5.4` still fails with OpenAI scope error (`model.request`)
24
- - Plugin should now support both:
25
- - direct Codex OAuth auth bridge
26
- - vllm-based CLI request bridge (Gemini + Claude)
27
-
28
- ## Open risks
29
-
30
- - Need explicit runtime validation of proxy endpoints and vllm model calls.
31
- - Config patcher writes `openclaw.json`; keep backup/doctor discipline before release.
32
- - `gpt-5.4` scope limitation is external (OpenAI account/role/scope), not plugin code.
9
+ - ✅ Repo: `https://github.com/elvatis/openclaw-cli-bridge-elvatis`
10
+ - ✅ npm: `@elvatis_com/openclaw-cli-bridge-elvatis@0.2.6`
11
+ - ✅ ClawHub: `openclaw-cli-bridge-elvatis@0.2.6`
12
+ - ✅ Phase 1: `openai-codex` provider via `~/.codex/auth.json` (no re-login)
13
+ - ✅ Phase 2: Local OpenAI-compatible proxy on `127.0.0.1:31337` (Gemini + Claude CLI)
14
+ - ✅ Phase 3: 10 slash commands (`/cli-sonnet`, `/cli-opus`, `/cli-haiku`, `/cli-gemini`, `/cli-gemini-flash`, `/cli-gemini3`, `/cli-codex`, `/cli-codex-mini`, `/cli-back`, `/cli-test`)
15
+ - ✅ Config patcher: auto-adds vllm provider to `openclaw.json` on first startup
16
+ - ✅ Prompt delivery via stdin (no E2BIG, no Gemini agentic mode)
17
+ - ✅ `registerService` stop() hook: closes proxy server on plugin teardown (fixes EADDRINUSE on hot-reload)
18
+ - ✅ `openclaw.extensions` added to `package.json` (required for `openclaw plugins install`)
19
+
20
+ ## Bug Fixed (v0.2.6)
21
+
22
+ **Port leak on gateway hot-reload** — HTTP proxy server on port 31337 had no cleanup
23
+ handler. On hot-reloads the old server kept the port bound, causing EADDRINUSE.
24
+ Fixed with `registerService` stop() callback.
25
+
26
+ ## Open Risks
27
+
28
+ - `openai-codex/gpt-5.4` returns 401 missing scope `model.request` — external (OpenAI account scope), not plugin code
29
+ - Config patcher writes `openclaw.json` directly → triggers one gateway restart on first install (expected, one-time only)
30
+ - ClawHub publish ignores `.clawhubignore` — use rsync workaround (see CONVENTIONS.md)
package/.clawhubignore CHANGED
@@ -1,7 +1,8 @@
1
- node_modules/
2
- .git/
3
- dist/
1
+ node_modules
2
+ .git
3
+ dist
4
4
  *.tgz
5
5
  npm-debug.log*
6
- .vscode/
7
- .idea/
6
+ .vscode
7
+ .idea
8
+ package-lock.json
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  > OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers — with slash commands for instant model switching, restore, and health testing.
4
4
 
5
- **Current version:** `0.2.5`
5
+ **Current version:** `0.2.6`
6
6
 
7
7
  ---
8
8
 
package/index.ts CHANGED
@@ -354,14 +354,17 @@ const plugin = {
354
354
  let proxyServer: import("node:http").Server | null = null;
355
355
 
356
356
  if (enableProxy) {
357
- startProxyServer({
358
- port,
359
- apiKey,
360
- timeoutMs,
361
- log: (msg) => api.logger.info(msg),
362
- warn: (msg) => api.logger.warn(msg),
363
- })
364
- .then((server) => {
357
+ // Retry up to 3 times with 600ms delay to handle the race condition where
358
+ // a previous plugin instance's server.close() hasn't released the port yet.
359
+ const startWithRetry = async (attemptsLeft: number): Promise<void> => {
360
+ try {
361
+ const server = await startProxyServer({
362
+ port,
363
+ apiKey,
364
+ timeoutMs,
365
+ log: (msg) => api.logger.info(msg),
366
+ warn: (msg) => api.logger.warn(msg),
367
+ });
365
368
  proxyServer = server;
366
369
  api.logger.info(
367
370
  `[cli-bridge] proxy ready on :${port} — vllm/cli-gemini/* and vllm/cli-claude/* available`
@@ -372,10 +375,17 @@ const plugin = {
372
375
  `[cli-bridge] openclaw.json patched with vllm provider. Restart gateway to activate.`
373
376
  );
374
377
  }
375
- })
376
- .catch((err: Error) => {
377
- api.logger.warn(`[cli-bridge] proxy failed to start on port ${port}: ${err.message}`);
378
- });
378
+ } catch (err: unknown) {
379
+ const msg = (err as Error).message ?? String(err);
380
+ if (attemptsLeft > 1 && msg.includes("EADDRINUSE")) {
381
+ api.logger.warn(`[cli-bridge] port ${port} busy, retrying in 600ms (${attemptsLeft - 1} left)…`);
382
+ await new Promise((r) => setTimeout(r, 600));
383
+ return startWithRetry(attemptsLeft - 1);
384
+ }
385
+ api.logger.warn(`[cli-bridge] proxy failed to start on port ${port}: ${msg}`);
386
+ }
387
+ };
388
+ startWithRetry(3).catch(() => {});
379
389
  }
380
390
 
381
391
  // ── Cleanup: close proxy server on plugin stop (hot-reload / gateway restart) ──
@@ -385,6 +395,13 @@ const plugin = {
385
395
  start: async () => { /* proxy already started above */ },
386
396
  stop: async () => {
387
397
  if (proxyServer) {
398
+ // closeAllConnections() forcefully terminates keep-alive connections
399
+ // so that server.close() releases the port immediately rather than
400
+ // waiting for them to drain. Without this, the port stays bound
401
+ // during hot-reloads and the next start() call gets EADDRINUSE.
402
+ if (typeof (proxyServer as any).closeAllConnections === "function") {
403
+ (proxyServer as any).closeAllConnections();
404
+ }
388
405
  await new Promise<void>((resolve) => {
389
406
  proxyServer!.close((err) => {
390
407
  if (err) api.logger.warn(`[cli-bridge] proxy close error: ${err.message}`);
package/openclaw.plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "openclaw-cli-bridge-elvatis",
3
3
  "name": "OpenClaw CLI Bridge",
4
- "version": "0.2.6",
4
+ "version": "0.2.7",
5
5
  "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
6
6
  "providers": [
7
7
  "openai-codex"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
3
- "version": "0.2.6",
3
+ "version": "0.2.7",
4
4
  "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
5
5
  "type": "module",
6
6
  "openclaw": {