@elvatis_com/openclaw-cli-bridge-elvatis 0.2.0

package/.ai/handoff/CONVENTIONS.md

@@ -0,0 +1,31 @@
+# CONVENTIONS.md — openclaw-cli-bridge-elvatis
+
+## Language & Runtime
+- TypeScript strict mode, ESM (`"type": "module"`)
+- Node 16 module resolution (`"moduleResolution": "Node16"`)
+- Target: ES2022
+
+## Package
+- Scope: `@elvatis_com/openclaw-cli-bridge-elvatis`
+- Plugin ID: `openclaw-cli-bridge-elvatis`
+- Providers declared: `["openai-codex"]`
+
+## File Layout
+```
+.ai/handoff/         ← AAHP protocol files (this folder)
+src/                 ← per-CLI auth modules (codex-auth.ts, gemini-auth.ts, ...)
+index.ts             ← plugin entry point (registerProvider calls)
+openclaw.plugin.json ← manifest
+package.json / tsconfig.json
+```
+
+## Code Style
+- Named exports from `src/`, default export from `index.ts`
+- No secrets printed to logs — redact tokens with `[REDACTED]`
+- Auth files accessed read-only
+- Error messages must include actionable fix hint (e.g. "Run 'codex login' and retry")
+
+## Release Checklist (mandatory for every publish)
+1. GitHub tag + release (elvatis org)
+2. `npm publish --access public`
+3. `clawhub publish`

package/.ai/handoff/DASHBOARD.md

@@ -0,0 +1,74 @@
+# [PROJECT]: Build Dashboard
+
+> Single source of truth for build health, test coverage, and pipeline state.
+> Updated by agents at the end of every completed task.
+
+---
+
+## 🏗️ Services / Components
+
+| Name | Version | Build | Tests | Status | Notes |
+|------|---------|-------|-------|--------|-------|
+| service-a | - | ✅ | - | ✅ | |
+| service-b | - | ✅ | 42/42 ✅ | ✅ | |
+| service-c | - | ❌ | - | 🔴 Broken | See LOG.md |
+
+**Legend:** ✅ passing · ❌ failing · 🔵 stub/mock · ⏳ pending · 🔴 blocked
+
+---
+
+## 🧪 Test Coverage
+
+| Suite | Tests | Status | Last Run |
+|-------|-------|--------|----------|
+| unit | - | - | - |
+| integration | - | - | - |
+| e2e | - | - | - |
+
+---
+
+## 🚀 Infrastructure / Deployment
+
+| Component | Status | Blocker |
+|-----------|--------|---------|
+| Local dev stack | ✅ | - |
+| Staging | ⏳ Not deployed | Needs credentials |
+| Production | ⏳ Not deployed | Needs credentials |
+
+---
+
+## 🤖 Pipeline State
+
+| Field | Value |
+|-------|-------|
+| Current task | - |
+| Phase | idle |
+| Last completed | - |
+| Rate limit | None |
+
+---
+
+## 📋 Open Tasks (strategic priority)
+
+| ID | Task | Priority | Blocked by | Ready? |
+|----|------|----------|-----------|--------|
+| T-001 | Describe task here | 🔴 HIGH | - | ✅ Ready |
+| T-002 | Another task | 🟠 MEDIUM | Waiting for X | 🔴 Blocked |
+
+---
+
+## 🔄 Update Instructions (for agents)
+
+After completing any task:
+
+1. Update the relevant row to ✅ with current date
+2. Update test counts
+3. Update "Pipeline State"
+4. Move completed task out of "Open Tasks"
+5. Add newly discovered tasks with correct priority
+
+**Pipeline rules:**
+- Blocked task → skip, take next unblocked
+- All tasks blocked → notify the project owner
+- Notify project owner only on **fully completed tasks**, not phase transitions
+- On test failures: attempt 1–2 self-fixes before escalating

package/.ai/handoff/LOG-ARCHIVE.md

@@ -0,0 +1,10 @@
+# [PROJECT]: Agent Journal -Archive
+
+> **Archived entries from LOG.md.**
+> When LOG.md exceeds 10 entries, older entries are moved here.
+> This file is for human review and forensics, not routine agent consumption.
+> Agents should only read this file when investigating historical decisions.
+
+---
+
+<!-- Archived entries are prepended below this line -->

package/.ai/handoff/LOG.md

@@ -0,0 +1,28 @@
+# LOG.md — openclaw-cli-bridge-elvatis
+
+## 2026-03-07 — Session 1 (gpt-5.3-codex / sonnet)
+
+**Major progress**
+- Implemented and verified Codex auth bridge for provider `openai-codex`.
+- Resolved "Unknown provider openai-codex" by registering provider in plugin.
+- Added `.gitignore` for build artifacts + secrets.
+- Created GitHub repo under `elvatis`: https://github.com/elvatis/openclaw-cli-bridge-elvatis
+- Pushed initial release code and follow-up fix for AAHP version label.
+
+**Architecture upgrade**
+- Added full request-bridge components:
+  - `src/cli-runner.ts`
+  - `src/proxy-server.ts`
+  - `src/config-patcher.ts`
+- Updated plugin to `0.2.0` conceptually (manifest), with phase split:
+  - Phase 1: auth bridge (`openai-codex`)
+  - Phase 2: HTTP proxy + vllm mapping (`cli-gemini/*`, `cli-claude/*`)
+
+**Operational notes**
+- `openai-codex/gpt-5.4` returns 401 missing scope `model.request`.
+- `openai-codex/gpt-5.3-codex` selected as current dev model.
+- Self-heal startup warning investigated; startup cleanup delay increased in `openclaw-self-healing-elvatis`.
+
+**Next**
+- Validate proxy endpoints + live vllm model calls end-to-end.
+- Then release pipeline (GitHub tag, npm, ClawHub).

package/.ai/handoff/MANIFEST.json

@@ -0,0 +1,35 @@
+{
+  "aahp_version": "3.0",
+  "project": "openclaw-cli-bridge-elvatis",
+  "last_session": {
+    "agent": "openai-codex/gpt-5.3-codex",
+    "session_id": "main",
+    "timestamp": "2026-03-07T21:29:00Z",
+    "commit": "16fca7c",
+    "phase": "integration",
+    "duration_minutes": 60
+  },
+  "files": {
+    "STATUS.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "Auth bridge done; request bridge implemented; pending runtime validation." },
+    "NEXT_ACTIONS.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "Top priority: validate proxy + vllm model calls, then release pipeline." },
+    "LOG.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "Repo created, provider fixed, proxy architecture added." },
+    "DASHBOARD.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "2 bridge phases implemented; validation pending." },
+    "TRUST.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "No secret output, local-only proxy, explicit scope constraints." },
+    "CONVENTIONS.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "TypeScript strict + AAHP v3 + multi-platform release discipline." },
+    "WORKFLOW.md": { "checksum": "sha256:tbd", "updated": "2026-03-07T21:29:00Z", "lines": 0, "summary": "Validate → harden → publish (GitHub, npm, ClawHub)." }
+  },
+  "quick_context": "Codex auth bridge is working and repo is live. gpt-5.4 fails due to OpenAI scope limitations, so development is on gpt-5.3-codex. Request-bridge code for Gemini/Claude via vllm-compatible proxy exists; next is end-to-end validation.",
+  "token_budget": { "manifest_only": 90, "manifest_plus_core": 350, "full_read": 700 },
+  "next_task_id": 9,
+  "tasks": {
+    "T-001": { "title": "Scaffold plugin structure + AAHP handoff", "status": "done", "priority": "high", "depends_on": [], "created": "2026-03-07T20:40:00Z", "completed": "2026-03-07T20:56:00Z" },
+    "T-002": { "title": "Implement openai-codex provider (Codex CLI auth bridge)", "status": "done", "priority": "high", "depends_on": ["T-001"], "created": "2026-03-07T20:40:00Z", "completed": "2026-03-07T20:56:00Z" },
+    "T-003": { "title": "Test auth flow: openclaw models auth login --provider openai-codex", "status": "done", "priority": "high", "depends_on": ["T-002"], "created": "2026-03-07T20:56:00Z", "completed": "2026-03-07T21:01:00Z" },
+    "T-004": { "title": "Verify model call: test gpt-5.2 or gpt-5.3-codex responds", "status": "done", "priority": "high", "depends_on": ["T-003"], "created": "2026-03-07T20:56:00Z", "completed": "2026-03-07T21:27:00Z" },
+    "T-005": { "title": "Implement Gemini CLI request bridge", "status": "done", "priority": "medium", "depends_on": ["T-003"], "created": "2026-03-07T20:56:00Z", "completed": "2026-03-07T21:23:00Z" },
+    "T-006": { "title": "Implement Claude Code CLI request bridge", "status": "done", "priority": "medium", "depends_on": ["T-003"], "created": "2026-03-07T20:56:00Z", "completed": "2026-03-07T21:23:00Z" },
+    "T-007": { "title": "Create GitHub repo and push initial code", "status": "done", "priority": "high", "depends_on": ["T-004"], "created": "2026-03-07T21:20:00Z", "completed": "2026-03-07T21:24:00Z" },
+    "T-008": { "title": "Validate proxy endpoints + vllm model calls end-to-end", "status": "ready", "priority": "high", "depends_on": ["T-005", "T-006"], "created": "2026-03-07T21:29:00Z" },
+    "T-009": { "title": "Publish to npm + ClawHub", "status": "blocked", "priority": "medium", "depends_on": ["T-008"], "created": "2026-03-07T21:29:00Z" }
+  }
+}

package/.ai/handoff/NEXT_ACTIONS.md

@@ -0,0 +1,37 @@
+# NEXT_ACTIONS.md — openclaw-cli-bridge-elvatis
+
+_Last updated: 2026-03-07_
+
+## Immediate
+
+1. **Validate proxy runtime**
+   - Confirm local proxy listens on `127.0.0.1:31337`
+   - Test:
+     - `GET /v1/models`
+     - `POST /v1/chat/completions` (non-stream + stream)
+
+2. **Validate OpenClaw vllm integration**
+   - Ensure `models.providers.vllm` contains `cli-gemini/*` + `cli-claude/*`
+   - Send live test prompts with:
+     - `vllm/cli-gemini/gemini-2.5-pro`
+     - `vllm/cli-claude/claude-sonnet-4-6`
+
+3. **Stability pass**
+   - Confirm timeout behavior and error mapping (CLI exits, malformed output)
+   - Confirm no secret leakage in logs
+
+## Next
+
+4. **Self-heal integration**
+   - Update `openclaw-self-healing-elvatis` model order for dev-safe default fallback chain.
+
+5. **Release pipeline**
+   - GitHub release tag
+   - npm publish (`@elvatis_com/openclaw-cli-bridge-elvatis`)
+   - ClawHub publish
+
+## Optional hardening
+
+- Add unit tests for prompt formatter + model router
+- Add proxy auth key rotation via config
+- Add explicit model allowlist for CLI execution

package/.ai/handoff/STATUS.md

@@ -0,0 +1,32 @@
+# STATUS.md — openclaw-cli-bridge-elvatis
+
+_Last updated: 2026-03-07 by gpt-5.3-codex_
+
+## Phase: Integration & validation
+
+## What is done
+
+- ✅ Repo created: `https://github.com/elvatis/openclaw-cli-bridge-elvatis`
+- ✅ AAHP handoff in `.ai/handoff/` (v3)
+- ✅ Phase 1 implemented: `openai-codex` auth bridge via `~/.codex/auth.json`
+- ✅ Auth flow verified with `openclaw models auth login --provider openai-codex`
+- ✅ Session model switching verified (`gpt-5.3-codex` works)
+- ✅ Phase 2 implemented: local OpenAI-compatible proxy server (`src/proxy-server.ts`)
+- ✅ CLI routing implemented (`src/cli-runner.ts`):
+  - `cli-gemini/*` → `gemini`
+  - `cli-claude/*` → `claude`
+- ✅ Config patcher implemented (`src/config-patcher.ts`) for `models.providers.vllm`
+
+## Current state
+
+- Development model pinned to: `openai-codex/gpt-5.3-codex`
+- `openai-codex/gpt-5.4` still fails with OpenAI scope error (`model.request`)
+- Plugin should now support both:
+  - direct Codex OAuth auth bridge
+  - vllm-based CLI request bridge (Gemini + Claude)
+
+## Open risks
+
+- Need explicit runtime validation of proxy endpoints and vllm model calls.
+- Config patcher writes `openclaw.json`; keep backup/doctor discipline before release.
+- `gpt-5.4` scope limitation is external (OpenAI account/role/scope), not plugin code.

package/.ai/handoff/TRUST.md

@@ -0,0 +1,69 @@
+# [PROJECT]: Trust Register
+
+> Tracks verification status of critical system properties.
+> In multi-agent pipelines, hallucinations and drift are real risks.
+> Every claim here has a confidence level tied to how it was verified.
+
+---
+
+## Confidence Levels
+
+| Level | Meaning |
+|-------|---------|
+| **verified** | An agent executed code, ran tests, or observed output to confirm this |
+| **assumed** | Derived from docs, config files, or chat, not directly tested |
+| **untested** | Status unknown; needs verification |
+
+---
+
+## Build System
+
+| Property | Status | Last Verified | Agent | Notes |
+|----------|--------|---------------|-------|-------|
+| `build` passes | untested | - | - | |
+| `test` passes | untested | - | - | |
+| `lint` passes | untested | - | - | |
+| `type-check` passes | untested | - | - | |
+
+---
+
+## Infrastructure
+
+| Property | Status | Last Verified | Agent | Notes |
+|----------|--------|---------------|-------|-------|
+| Local dev stack boots | untested | - | - | |
+| All health endpoints respond | untested | - | - | |
+| Database connection works | untested | - | - | |
+| Auth flow completes | untested | - | - | |
+
+---
+
+## Integrations
+
+| Property | Status | Last Verified | Agent | Notes |
+|----------|--------|---------------|-------|-------|
+| External API A reachable | untested | - | - | |
+| Webhook delivery confirmed | untested | - | - | |
+
+---
+
+## Security
+
+| Property | Status | Last Verified | Agent | Notes |
+|----------|--------|---------------|-------|-------|
+| No secrets in source | assumed | - | - | Pre-commit hooks configured |
+| Auth tokens expire correctly | untested | - | - | |
+| PII not logged | untested | - | - | |
+
+---
+
+## Update Rules (for agents)
+
+- Change `untested` → `verified` only after **running actual code/tests**
+- Change `assumed` → `verified` after direct confirmation
+- Never downgrade `verified` without explaining why in `LOG.md`
+- Add new rows when new system properties become critical
+
+---
+
+*Trust degrades over time. Re-verify periodically, especially after major refactors.*

package/.ai/handoff/WORKFLOW.md

@@ -0,0 +1,152 @@
+# [PROJECT]: Autonomous Multi-Agent Workflow
+
+> Based on the [AAHP Protocol](https://github.com/homeofe/AAHP).
+> No manual triggers. Agents read `handoff/DASHBOARD.md` and work autonomously.
+
+---
+
+## Agent Roles
+
+| Agent | Model | Role | Responsibility |
+|-------|-------|------|---------------|
+| 🔭 Researcher | e.g. perplexity/sonar-pro | Researcher | OSS research, compliance checks, doc review |
+| 🏛️ Architect | e.g. claude-opus | Architect | System design, ADRs, interface definitions |
+| ⚙️ Implementer | e.g. claude-sonnet | Implementer | Code, tests, refactoring, commits |
+| 💬 Reviewer | e.g. gpt-4 / second model | Reviewer | Second opinion, edge cases, security review |
+
+> Adapt roles and models to your team's tooling.
+
+---
+
+## The Pipeline
+
+### Phase 1: Research & Context
+
+```
+Reads:   handoff/NEXT_ACTIONS.md or DASHBOARD.md (top unblocked task)
+         handoff/STATUS.md (current project state)
+
+Does:    Researches relevant OSS libraries / APIs / compliance requirements
+         Checks whether similar solutions already exist in the project
+         Clarifies ambiguities in the task
+
+Writes:  handoff/LOG.md -research findings + sources + recommendation
+```
+
+### Phase 2: Architecture Decision
+
+```
+Reads:   Research output from LOG.md
+         handoff/STATUS.md
+         Relevant source files, config, docs
+
+Does:    Decides architecture and interface design
+         Chooses branch name
+         Defines exactly what the Implementer should build
+
+Writes:  handoff/LOG.md -ADR (Architecture Decision Record)
+
+ADR format:
+  ## [DATE] ADR: [Feature Name]
+  **Decision:** ...
+  **Rationale:** ...
+  **Consequences:** ...
+  **Branch:** feat/...
+  **Instructions for Implementer:** [numbered steps]
+```
+
+### Phase 3: Implementation
+
+```
+Reads:   ADR from LOG.md
+         CONTRIBUTING.md / CONVENTIONS.md (MANDATORY before first commit)
+
+Does:    Creates feature branch: git checkout -b feat/<scope>-<name>
+         Writes code + unit tests
+         Runs tests and type-check
+         Commits and pushes branch
+
+Branch convention:
+  feat/<scope>-<short-name>    → new feature
+  fix/<scope>-<short-name>     → bug fix
+  docs/<scope>-<name>          → documentation only
+
+Commit format:
+  feat(scope): description [AAHP-auto]
+  fix(scope): description [AAHP-fix]
+```
+
+### Phase 4: Discussion Round
+
+```
+All agents review the completed code on the feature branch.
+
+Architect  → "Does the implementation match the ADR?"
+Reviewer   → "What could be more robust, simpler, or more secure?"
+Researcher → "Were all task items fulfilled? Any compliance concerns?"
+
+Outcome:
+  - Minor fixes → Implementer fixes in the same branch
+  - Larger issues → New tasks added to NEXT_ACTIONS.md / DASHBOARD.md
+  - Everything documented in LOG.md
+```
+
+### Phase 5: Completion & Handoff
+
+```
+DASHBOARD.md:    Update build status, test counts, pipeline state
+STATUS.md:       Update changed system state (Verified / Assumed / Unknown)
+LOG.md:          Append session summary
+NEXT_ACTIONS.md: Check off completed task, add newly discovered tasks
+
+Git:     Branch pushed, PR-ready
+Notify:  Project owner -only on fully completed tasks, not phase transitions
+         Format: "✅ [Feature] done -Branch: feat/... -Tests: X/X"
+```
+
+---
+
+## Autonomy Boundaries
+
+| Allowed ✅ | Not allowed ❌ |
+|-----------|--------------|
+| Write & commit code | Push directly to `main` |
+| Write & run tests | Install new dependencies without documenting |
+| Push feature branches | Write secrets or PII into source |
+| Research & propose OSS libraries | Call external APIs without credentials |
+| Make architecture decisions | Perform production deployments |
+| Break tests (when fixing identified bugs) | Delete tests without replacement |
+
+---
+
+## Task Selection Rules
+
+1. Read `DASHBOARD.md`, take the top task where `Ready? = ✅`
+2. If a task is **blocked** → skip it, take the next unblocked one
+3. If **all tasks are blocked** → notify the project owner, pause
+4. Never start a task without reading `STATUS.md` first
+5. After completing a task → always update `DASHBOARD.md` before stopping
+
+---
+
+## Error Handling
+
+If an agent fails or is uncertain:
+- Mark task as `(Unknown)` in `STATUS.md`
+- Document the specific blocker in `LOG.md`
+- Notify the project owner
+- **Never proceed on assumptions when certainty is missing**
+
+---
+
+## Open Source First
+
+Before any custom implementation:
+1. Researcher searches for existing OSS solutions
+2. Architect evaluates: build vs. OSS vs. fork
+3. Decision is documented in the ADR
+4. Custom builds must be: clean abstraction, testable, documented
+
+---
+
+*This document lives in the repo and is continuously refined by the agents themselves.*

package/README.md

@@ -0,0 +1,84 @@
+# openclaw-cli-bridge-elvatis
+
+> OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers.
+
+## What it does
+
+**Phase 1 — Auth bridge:** Registers the `openai-codex` provider using OAuth tokens already stored by the Codex CLI (`~/.codex/auth.json`). No re-login needed.
+
+**Phase 2 — Request bridge:** Starts a local OpenAI-compatible HTTP proxy server (default port `31337`) and configures OpenClaw's `vllm` provider to route model calls through `gemini` and `claude` CLI subprocesses.
+
+| Model reference | CLI invoked |
+|---|---|
+| `vllm/cli-gemini/gemini-2.5-pro` | `gemini -m gemini-2.5-pro -p "<prompt>"` |
+| `vllm/cli-gemini/gemini-2.5-flash` | `gemini -m gemini-2.5-flash -p "<prompt>"` |
+| `vllm/cli-claude/claude-opus-4-6` | `claude -p -m claude-opus-4-6 --output-format text "<prompt>"` |
+| `vllm/cli-claude/claude-sonnet-4-6` | `claude -p -m claude-sonnet-4-6 --output-format text "<prompt>"` |
+
+## Requirements
+
+- [OpenClaw](https://openclaw.ai) gateway running
+- One or more of:
+  - [`@openai/codex`](https://github.com/openai/codex) — `npm i -g @openai/codex` + `codex login`
+  - [`@google/gemini-cli`](https://github.com/google-gemini/gemini-cli) — `npm i -g @google/gemini-cli` + `gemini auth`
+  - [`@anthropic-ai/claude-code`](https://github.com/anthropic-ai/claude-code) — `npm i -g @anthropic-ai/claude-code` + `claude auth`
+
+## Installation
+
+```bash
+# Install from ClawHub (once published)
+clawhub install openclaw-cli-bridge-elvatis
+
+# Or load directly from this repo (development)
+# Add to ~/.openclaw/openclaw.json:
+# plugins.load.paths: ["<path-to-this-repo>"]
+# plugins.allow: ["openclaw-cli-bridge-elvatis"]
+# plugins.entries.openclaw-cli-bridge-elvatis: { "enabled": true }
+```
+
+## Auth setup (Phase 1 — Codex)
+
+After enabling the plugin, register the Codex auth profile:
+
+```bash
+openclaw models auth login --provider openai-codex
+# Select: "Codex CLI (existing login)"
+```
+
+The proxy server (Phase 2) starts automatically and patches `openclaw.json` with the `vllm` provider config. Restart the gateway to activate the new models.
+
+## Configuration
+
+Add to your `plugins.entries.openclaw-cli-bridge-elvatis.config` in `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  "enableCodex": true,       // register openai-codex from Codex CLI auth
+  "enableProxy": true,       // start the local CLI proxy server
+  "proxyPort": 31337,        // port for the proxy (default: 31337)
+  "proxyApiKey": "cli-bridge", // key used between OpenClaw and the proxy
+  "proxyTimeoutMs": 120000   // CLI timeout in ms (default: 2 min)
+}
+```
+
+## Architecture
+
+```
+OpenClaw agent
+  │
+  ├─ openai-codex/* ──► OpenAI API (auth via Codex CLI OAuth tokens)
+  │
+  └─ vllm/cli-gemini/*  ─┐
+     vllm/cli-claude/*   ─┤─► openclaw-cli-bridge-elvatis proxy (127.0.0.1:31337)
+                          │       ├─ cli-gemini/* → gemini -m <model> -p "<prompt>"
+                          │       └─ cli-claude/* → claude -p -m <model> "<prompt>"
+                          └──────────────────────────────────────────────────────
+```
+
+## AAHP handoff
+
+Project tracking lives in `.ai/handoff/` (AAHP v3 protocol).
+
+## License
+
+MIT