@elvatis_com/openclaw-cli-bridge-elvatis 0.2.18 → 0.2.20

package/.ai/handoff/STATUS.md

@@ -2,13 +2,13 @@
 
 _Last updated: 2026-03-08 by Akido (claude-sonnet-4-6)_
 
-## Current Version: 0.2.18 — STABLE
+## Current Version: 0.2.19 — STABLE
 
 ## What is done
 
 - ✅ Repo: `https://github.com/elvatis/openclaw-cli-bridge-elvatis`
-- ✅ npm: `@@@elvatis_com/openclaw-cli-bridge-elvatis@0.2.18`
-- ✅ ClawHub: `openclaw-cli-bridge-elvatis@0.2.18`
+- ✅ npm: `@@@@elvatis_com/openclaw-cli-bridge-elvatis@0.2.19`
+- ✅ ClawHub: `openclaw-cli-bridge-elvatis@0.2.19`
 - ✅ Phase 1: `openai-codex` provider via `~/.codex/auth.json` (no re-login)
 - ✅ Phase 2: Local OpenAI-compatible proxy on `127.0.0.1:31337` (Gemini + Claude CLI)
 - ✅ 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`)

package/README.md

@@ -1,8 +1,8 @@
 # openclaw-cli-bridge-elvatis
 
-> 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.
+> OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers — with slash commands for instant model switching, restore, health testing, and model listing.
 
-**Current version:** `0.2.18`
+**Current version:** `0.2.20`
 
 ---
 
@@ -20,13 +20,15 @@ Starts a local OpenAI-compatible HTTP proxy on `127.0.0.1:31337` and configures
 |---|---|---|
 | `vllm/cli-gemini/gemini-2.5-pro` | `gemini -m gemini-2.5-pro -p ""` (stdin, cwd=/tmp) | ~8–10s |
 | `vllm/cli-gemini/gemini-2.5-flash` | `gemini -m gemini-2.5-flash -p ""` (stdin, cwd=/tmp) | ~4–6s |
-| `vllm/cli-gemini/gemini-3-pro` | `gemini -m gemini-3-pro -p ""` (stdin, cwd=/tmp) | ~8–10s |
+| `vllm/cli-gemini/gemini-3-pro-preview` | `gemini -m gemini-3-pro-preview -p ""` (stdin, cwd=/tmp) | ~8–10s |
+| `vllm/cli-gemini/gemini-3-flash-preview` | `gemini -m gemini-3-flash-preview -p ""` (stdin, cwd=/tmp) | ~4–6s |
 | `vllm/cli-claude/claude-sonnet-4-6` | `claude -p --output-format text --model claude-sonnet-4-6` (stdin) | ~2–4s |
 | `vllm/cli-claude/claude-opus-4-6` | `claude -p --output-format text --model claude-opus-4-6` (stdin) | ~3–5s |
 | `vllm/cli-claude/claude-haiku-4-5` | `claude -p --output-format text --model claude-haiku-4-5` (stdin) | ~1–3s |
 
 ### Phase 3 — Slash commands
-Ten plugin-registered commands (all `requireAuth: true`):
+
+All commands use gateway-level `commands.allowFrom` for authorization (`requireAuth: false` at plugin level).
 
 **Claude Code CLI** (routed via local proxy on `:31337`):
 
@@ -42,14 +44,18 @@ Ten plugin-registered commands (all `requireAuth: true`):
 |---|---|
 | `/cli-gemini` | `vllm/cli-gemini/gemini-2.5-pro` |
 | `/cli-gemini-flash` | `vllm/cli-gemini/gemini-2.5-flash` |
-| `/cli-gemini3` | `vllm/cli-gemini/gemini-3-pro` |
+| `/cli-gemini3` | `vllm/cli-gemini/gemini-3-pro-preview` |
+| `/cli-gemini3-flash` | `vllm/cli-gemini/gemini-3-flash-preview` |
 
-**Codex CLI** (via `openai-codex` provider — Codex CLI OAuth auth, calls OpenAI API directly, **not** through the local proxy):
+**Codex CLI** (via `openai-codex` provider — OAuth auth, calls OpenAI API directly, **not** through the local proxy):
 
-| Command | Model |
-|---|---|
-| `/cli-codex` | `openai-codex/gpt-5.3-codex` |
-| `/cli-codex-mini` | `openai-codex/gpt-5.1-codex-mini` |
+| Command | Model | Notes |
+|---|---|---|
+| `/cli-codex` | `openai-codex/gpt-5.3-codex` | ✅ Tested |
+| `/cli-codex-spark` | `openai-codex/gpt-5.3-codex-spark` | |
+| `/cli-codex52` | `openai-codex/gpt-5.2-codex` | |
+| `/cli-codex54` | `openai-codex/gpt-5.4` | May require upgraded OAuth scope |
+| `/cli-codex-mini` | `openai-codex/gpt-5.1-codex-mini` | ✅ Tested |
 
 **Utility:**
 
@@ -57,6 +63,7 @@ Ten plugin-registered commands (all `requireAuth: true`):
 |---|---|
 | `/cli-back` | Restore the model active **before** the last `/cli-*` switch |
 | `/cli-test [model]` | One-shot proxy health check — **does NOT switch your active model** |
+| `/cli-list` | Show all registered CLI bridge models with commands |
 
 **`/cli-back` details:**
 - Before every `/cli-*` switch the current model is saved to `~/.openclaw/cli-bridge-state.json`
@@ -68,6 +75,10 @@ Ten plugin-registered commands (all `requireAuth: true`):
 - Default when no arg given: `cli-claude/claude-sonnet-4-6`
 - Reports response content, latency, and confirms your active model is unchanged
 
+**`/cli-list` details:**
+- Lists all registered models grouped by provider (Claude CLI, Gemini CLI, Codex)
+- No arguments required
+
 ---
 
 ## Requirements
@@ -111,8 +122,10 @@ openclaw gateway restart
 
 ```
 [cli-bridge] proxy ready on :31337
-[cli-bridge] registered 8 commands: /cli-sonnet, /cli-opus, /cli-haiku,
-             /cli-gemini, /cli-gemini-flash, /cli-gemini3, /cli-back, /cli-test
+[cli-bridge] registered 14 commands: /cli-sonnet, /cli-opus, /cli-haiku,
+             /cli-gemini, /cli-gemini-flash, /cli-gemini3, /cli-gemini3-flash,
+             /cli-codex, /cli-codex-spark, /cli-codex52, /cli-codex54, /cli-codex-mini,
+             /cli-back, /cli-test, /cli-list
 ```
 
 ### 3. Register Codex auth (optional — Phase 1 only)
@@ -122,7 +135,39 @@ openclaw models auth login --provider openai-codex
 # Select: "Codex CLI (existing login)"
 ```
 
-### 4. Test without switching your model
+### 4. List available models
+
+```
+/cli-list
+→ 🤖 CLI Bridge Models
+
+  Claude Code CLI
+    /cli-sonnet          claude-sonnet-4-6
+    /cli-opus            claude-opus-4-6
+    /cli-haiku           claude-haiku-4-5
+
+  Gemini CLI
+    /cli-gemini          gemini-2.5-pro
+    /cli-gemini-flash    gemini-2.5-flash
+    /cli-gemini3         gemini-3-pro-preview
+    /cli-gemini3-flash   gemini-3-flash-preview
+
+  Codex (OAuth)
+    /cli-codex           gpt-5.3-codex
+    /cli-codex-spark     gpt-5.3-codex-spark
+    /cli-codex52         gpt-5.2-codex
+    /cli-codex54         gpt-5.4
+    /cli-codex-mini      gpt-5.1-codex-mini
+
+  Utility
+    /cli-back            Restore previous model
+    /cli-test [model]    Health check (no model switch)
+    /cli-list            This overview
+
+  Proxy: 127.0.0.1:31337
+```
+
+### 5. Test without switching your model
 
 ```
 /cli-test
@@ -140,7 +185,7 @@ openclaw models auth login --provider openai-codex
   Active model unchanged: anthropic/claude-sonnet-4-6
 ```
 
-### 5. Switch and restore
+### 6. Switch and restore
 
 ```
 /cli-sonnet
@@ -173,15 +218,22 @@ In `~/.openclaw/openclaw.json` → `plugins.entries.openclaw-cli-bridge-elvatis.
 
 ---
 
+## Model Allowlist
+
+`routeToCliRunner` enforces `DEFAULT_ALLOWED_CLI_MODELS` — only models registered in the plugin are accepted by the proxy. Unregistered models receive a clear error listing allowed options.
+
+To disable the check (e.g. for custom vllm routing): pass `allowedModels: null` in `RouteOptions`.
+
+---
+
 ## Architecture
 
 ```
 OpenClaw agent
   │
   ├─ openai-codex/*  ──────────────────────────► OpenAI API (direct)
-  │    auth: ~/.codex/auth.json OAuth tokens        ▲
-  │                                                 │
-  │    /cli-codex, /cli-codex-mini ─────────────────┘  (switch to this provider)
+  │    auth: ~/.codex/auth.json OAuth tokens
+  │    /cli-codex, /cli-codex-spark, /cli-codex52, /cli-codex54, /cli-codex-mini
   │
   └─ vllm/cli-gemini/*  ─┐
      vllm/cli-claude/*   ─┤─► localhost:31337  (openclaw-cli-bridge proxy)
@@ -190,21 +242,16 @@ OpenClaw agent
                           │       │                 (neutral cwd prevents agentic mode)
                           │       └─ cli-claude/* → claude -p --model <model>
                           │                         stdin=prompt
-                          └───────────────────────────────────────────────────
 
-Slash commands (bypass agent, requireAuth=true):
-  /cli-sonnet|opus|haiku|gemini|gemini-flash|gemini3|codex|codex-mini
+Slash commands (requireAuth=false, gateway commands.allowFrom is the auth layer):
+  /cli-sonnet|opus|haiku|gemini|gemini-flash|gemini3|gemini3-flash
+  /cli-codex|codex-spark|codex52|codex54|codex-mini
      └─► saves current model → ~/.openclaw/cli-bridge-state.json
-     └─► openclaw models set <model>  (~1s, atomic)
+     └─► openclaw models set <model>
 
-  /cli-back
-     └─► reads ~/.openclaw/cli-bridge-state.json
-     └─► openclaw models set <previous>
-
-  /cli-test [model]
-     └─► HTTP POST → localhost:31337  (no global model change)
-     └─► reports response + latency
-     └─► NOTE: only tests the proxy — Codex models bypass the proxy
+  /cli-back   → reads state file, restores previous model, clears state
+  /cli-test   → HTTP POST → localhost:31337, no global model change
+  /cli-list   → formatted table of all registered models
 ```
 
 ---
@@ -218,8 +265,8 @@ Slash commands (bypass agent, requireAuth=true):
 
 ### Gemini agentic mode / hangs (fixed in v0.2.4)
 **Symptom:** Gemini hangs, returns wrong answers, or says "directory does not exist".
-**Cause:** `@file` syntax (`gemini -p @/tmp/xxx.txt`) triggers agentic mode — Gemini scans the working directory for project context and treats prompts as task instructions. Running from the workspace root makes this worse.
-**Fix:** Stdin delivery (`gemini -p ""` with prompt via stdin) + `cwd=/tmp`. Same pattern as Claude.
+**Cause:** `@file` syntax (`gemini -p @/tmp/xxx.txt`) triggers agentic mode — Gemini scans the working directory for project context and treats prompts as task instructions.
+**Fix:** Stdin delivery (`gemini -p ""` with prompt via stdin) + `cwd=/tmp`.
 
 ---
 
@@ -227,87 +274,71 @@ Slash commands (bypass agent, requireAuth=true):
 
 ```bash
 npm run typecheck   # tsc --noEmit
-npm test            # vitest run (5 unit tests for formatPrompt)
+npm test            # vitest run (45 tests)
 ```
 
 ---
 
 ## Changelog
 
+### v0.2.20
+- **fix:** `formatPrompt` now defensively coerces `content` to string via `contentToString()` — prevents `[object Object]` reaching the CLI when WhatsApp group messages contain structured content objects instead of plain strings
+- **feat:** `ChatMessage.content` now accepts `string | ContentPart[] | unknown` (OpenAI multimodal content arrays supported)
+- **feat:** New `contentToString()` helper: handles string, OpenAI ContentPart arrays, arbitrary objects (JSON.stringify), null/undefined
+
+### v0.2.19
+- **feat:** `/cli-list` command — formatted overview of all registered models grouped by provider
+- **docs:** Rewrite README to reflect current state (correct model names, command count, requireAuth, test count, /cli-list docs)
+
 ### v0.2.18
 - **feat:** Add `/cli-gemini3-flash` → `gemini-3-flash-preview`
 - **feat:** Add `/cli-codex-spark` → `gpt-5.3-codex-spark`, `/cli-codex52` → `gpt-5.2-codex`, `/cli-codex54` → `gpt-5.4`
 - **fix:** Update `DEFAULT_ALLOWED_CLI_MODELS` with `gemini-3-flash-preview`
 
 ### v0.2.17
-- **fix:** `/cli-gemini3` model corrected to `gemini-3-pro-preview` (was `gemini-3-pro`, which returns 404 from Gemini API)
+- **fix:** `/cli-gemini3` model corrected to `gemini-3-pro-preview` (was `gemini-3-pro`, returns 404 from Gemini API)
 
 ### v0.2.16
 - **feat(T-101):** Expand test suite to 45 tests — new cases for `formatPrompt` (mixed roles, boundary values, system messages) and `routeToCliRunner` (gemini paths, edge cases)
 - **feat(T-103):** Add `DEFAULT_ALLOWED_CLI_MODELS` allowlist; `routeToCliRunner` now rejects unregistered models by default; pass `allowedModels: null` to opt out
 
 ### v0.2.15
-- **docs:** Rewrite changelog (entries for v0.2.12–v0.2.14 were corrupted by repeated sed version bumps); all providers verified working (Claude, Gemini, Codex)
-- **docs:** Update STATUS.md with end-to-end test results
+- **docs:** Rewrite changelog (entries for v0.2.12–v0.2.14 were corrupted); all providers verified working end-to-end
 
 ### v0.2.14
-- **fix:** Strip `vllm/` prefix in `routeToCliRunner` — OpenClaw sends full provider path (`vllm/cli-claude/...`) but proxy router expected bare `cli-claude/...`; caused "Unknown CLI bridge model" on all requests
-- **test:** Add 4 routing tests covering both prefixed and non-prefixed model paths (9 tests total)
+- **fix:** Strip `vllm/` prefix in `routeToCliRunner` — OpenClaw sends full provider path (`vllm/cli-claude/...`) but proxy router expected bare `cli-claude/...`
+- **test:** Add 4 routing tests (9 total)
 
 ### v0.2.13
-- **fix:** Set `requireAuth: false` on all `/cli-*` commands — webchat senders were always blocked because plugin-level auth uses a different resolution path than `commands.allowFrom` config; gateway-level allowlist is the correct security layer
-- **fix:** Hardcoded `version: "0.2.5"` in plugin object (`index.ts`) — now tracks `package.json`
-
-### v0.2.12
-- **docs:** Fix changelog continuity — v0.2.10 entry was lost, v0.2.11 description was wrong; all entries now accurate
-
-### v0.2.11
-- **docs:** Fix README `Current version:** `0.2.18`
-
-### v0.2.10
-- **docs:** Fix version labels — SKILL.md was showing 0.2.2, README changelog ended at v0.2.5; add entries for v0.2.6–v0.2.9
+- **fix:** Set `requireAuth: false` on all `/cli-*` commands — plugin-level auth uses different resolution path than `commands.allowFrom`; gateway allowlist is the correct security layer
+- **fix:** Hardcoded `version: "0.2.5"` in plugin object now tracks `package.json`
 
 ### v0.2.9
-- **fix:** Critical — replace `fuser -k 31337/tcp` with safe health probe (`GET /v1/models`)
-- Prevents gateway SIGKILL on in-process hot-reloads (systemd `status=9/KILL` was caused by `fuser` finding gateway itself holding the port)
-- If proxy responds → reuse it; if EADDRINUSE but no response → wait 1s, retry once
-
-### v0.2.8
-- **fix:** EADDRINUSE on every gateway restart — `closeAllConnections()` + `registerService` stop() hook (partially; superseded by v0.2.9 health-probe approach)
+- **fix:** Critical — replace `fuser -k 31337/tcp` with safe health probe to prevent gateway SIGKILL on hot-reloads
 
-### v0.2.7
-- **fix:** Port leak on gateway hot-reload — added `registerService` stop() callback to close proxy server on plugin teardown
+### v0.2.7–v0.2.8
+- **fix:** Port leak on hot-reload — `registerService` stop() hook + `closeAllConnections()`
 
 ### v0.2.6
-- **fix:** `openclaw.extensions` added to `package.json` (required for `openclaw plugins install`)
-- Config patcher: auto-adds vllm provider to `openclaw.json` on first startup
+- **fix:** `openclaw.extensions` added to `package.json`; config patcher auto-adds vllm provider
 
 ### v0.2.5
-- **feat:** `/cli-codex` → `openai-codex/gpt-5.3-codex`
-- **feat:** `/cli-codex-mini` → `openai-codex/gpt-5.1-codex-mini`
-- Codex commands use the `openai-codex` provider (Codex CLI OAuth auth, direct OpenAI API — not the local proxy)
+- **feat:** `/cli-codex` + `/cli-codex-mini` (Codex OAuth provider, direct API)
 
 ### v0.2.4
-- **fix:** Gemini agentic mode — replaced `@file` with stdin delivery (`-p ""`) + `cwd=/tmp`
-- **fix:** Filter `[WARN]` and `Loaded cached credentials` noise from Gemini stderr
-- Added `RunCliOptions` interface with optional `cwd` field
+- **fix:** Gemini agentic mode — stdin delivery + `cwd=/tmp`
 
 ### v0.2.3
-- **feat:** `/cli-back` — restore previous model (state persisted in `~/.openclaw/cli-bridge-state.json`)
-- **feat:** `/cli-test [model]` — one-shot proxy health check without changing active model
+- **feat:** `/cli-back` + `/cli-test`
 
 ### v0.2.2
-- **feat:** Phase 3 — `/cli-*` slash commands for instant model switching
-- All 6 model commands via `api.registerCommand` with `requireAuth: true`
+- **feat:** Phase 3 — `/cli-*` slash commands
 
 ### v0.2.1
-- **fix:** `spawn E2BIG` — `buildMinimalEnv()` instead of spreading full `process.env`
-- **feat:** Unit tests (`test/cli-runner.test.ts`)
+- **fix:** `spawn E2BIG` + unit tests
 
 ### v0.2.0
-- **feat:** Phase 2 — local OpenAI-compatible proxy server
-- Stdin prompt delivery, `MAX_MESSAGES=20` + `MAX_MSG_CHARS=4000` truncation
-- Auto-patch of `openclaw.json` vllm provider config
+- **feat:** Phase 2 — local OpenAI-compatible proxy, stdin delivery, prompt truncation
 
 ### v0.1.x
 - Phase 1: Codex CLI OAuth auth bridge

package/SKILL.md

@@ -53,4 +53,4 @@ Each command runs `openclaw models set <model>` atomically and replies with a co
 
 See `README.md` for full configuration reference and architecture diagram.
 
-**Version:** 0.2.18
+**Version:** 0.2.20

package/index.ts

@@ -20,6 +20,7 @@
  *   /cli-codex-mini   → openai-codex/gpt-5.1-codex-mini        (Codex CLI OAuth, direct API)
  *   /cli-back         → restore model that was active before last /cli-* switch
  *   /cli-test [model] → one-shot proxy health check (does NOT switch global model)
+ *   /cli-list         → list all registered CLI bridge models with commands
  *
  * Provider / model naming:
  *   vllm/cli-gemini/gemini-2.5-pro  → `gemini -m gemini-2.5-pro @<tmpfile>`
@@ -575,10 +576,51 @@ const plugin = {
       },
     } satisfies OpenClawPluginCommandDefinition);
 
+    // ── Phase 3d: /cli-list — formatted model overview ────────────────────────
+    api.registerCommand({
+      name: "cli-list",
+      description: "List all registered CLI bridge models and their commands.",
+      requireAuth: false,
+      handler: async (): Promise<PluginCommandResult> => {
+        const groups: Record<string, { cmd: string; model: string }[]> = {
+          "Claude Code CLI": [],
+          "Gemini CLI": [],
+          "Codex (OAuth)": [],
+        };
+
+        for (const c of CLI_MODEL_COMMANDS) {
+          const entry = { cmd: `/${c.name}`, model: c.model };
+          if (c.model.startsWith("vllm/cli-claude/")) groups["Claude Code CLI"].push(entry);
+          else if (c.model.startsWith("vllm/cli-gemini/")) groups["Gemini CLI"].push(entry);
+          else groups["Codex (OAuth)"].push(entry);
+        }
+
+        const lines: string[] = ["🤖 *CLI Bridge Models*", ""];
+        for (const [group, entries] of Object.entries(groups)) {
+          if (entries.length === 0) continue;
+          lines.push(`*${group}*`);
+          for (const { cmd, model } of entries) {
+            const modelId = model.replace(/^vllm\/cli-(claude|gemini)\//, "").replace(/^openai-codex\//, "");
+            lines.push(`  ${cmd.padEnd(20)} ${modelId}`);
+          }
+          lines.push("");
+        }
+        lines.push("*Utility*");
+        lines.push("  /cli-back            Restore previous model");
+        lines.push("  /cli-test [model]    Health check (no model switch)");
+        lines.push("  /cli-list            This overview");
+        lines.push("");
+        lines.push(`Proxy: \`127.0.0.1:${port}\``);
+
+        return { text: lines.join("\n") };
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
     const allCommands = [
       ...CLI_MODEL_COMMANDS.map((c) => `/${c.name}`),
       "/cli-back",
       "/cli-test",
+      "/cli-list",
     ];
     api.logger.info(`[cli-bridge] registered ${allCommands.length} commands: ${allCommands.join(", ")}`);
   },

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-cli-bridge-elvatis",
   "name": "OpenClaw CLI Bridge",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
   "providers": [
     "openai-codex"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "openclaw": {

package/src/cli-runner.ts

@@ -24,9 +24,15 @@ const MAX_MSG_CHARS = 4000;
 // Message formatting
 // ──────────────────────────────────────────────────────────────────────────────
 
+export interface ContentPart {
+  type: string;
+  text?: string;
+}
+
 export interface ChatMessage {
   role: "system" | "user" | "assistant";
-  content: string;
+  /** Plain string or OpenAI-style content array (multimodal / structured). */
+  content: string | ContentPart[] | unknown;
 }
 
 /**
@@ -61,7 +67,30 @@ export function formatPrompt(messages: ChatMessage[]): string {
     .join("\n\n");
 }
 
-function truncateContent(s: string): string {
+/**
+ * Coerce any message content value to a plain string.
+ *
+ * Handles:
+ *  - string          → as-is
+ *  - ContentPart[]   → join text parts (OpenAI multimodal format)
+ *  - other object    → JSON.stringify (prevents "[object Object]" from reaching the CLI)
+ *  - null/undefined  → ""
+ */
+function contentToString(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (content === null || content === undefined) return "";
+  if (Array.isArray(content)) {
+    return (content as ContentPart[])
+      .filter((c) => c?.type === "text" && typeof c.text === "string")
+      .map((c) => c.text!)
+      .join("\n");
+  }
+  if (typeof content === "object") return JSON.stringify(content);
+  return String(content);
+}
+
+function truncateContent(raw: unknown): string {
+  const s = contentToString(raw);
   if (s.length <= MAX_MSG_CHARS) return s;
   return s.slice(0, MAX_MSG_CHARS) + `\n...[truncated ${s.length - MAX_MSG_CHARS} chars]`;
 }

package/test/cli-runner.test.ts

@@ -99,6 +99,60 @@ describe("formatPrompt", () => {
     expect(result).toContain("[System]");
     expect(result).toContain("[User]");
   });
+
+  // contentToString coercion tests (fix: [object Object] in WhatsApp group messages)
+  it("coerces ContentPart array to plain text", () => {
+    const result = formatPrompt([
+      { role: "user", content: [{ type: "text", text: "Hello from WA group" }] },
+    ]);
+    expect(result).toBe("Hello from WA group");
+    expect(result).not.toContain("[object Object]");
+  });
+
+  it("joins multiple text ContentParts with newline", () => {
+    const result = formatPrompt([
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "Part one" },
+          { type: "text", text: "Part two" },
+        ],
+      },
+    ]);
+    expect(result).toContain("Part one");
+    expect(result).toContain("Part two");
+  });
+
+  it("ignores non-text ContentParts (e.g. image)", () => {
+    const result = formatPrompt([
+      {
+        role: "user",
+        content: [
+          { type: "image_url", url: "https://example.com/img.png" },
+          { type: "text", text: "describe this" },
+        ],
+      },
+    ]);
+    expect(result).toBe("describe this");
+  });
+
+  it("coerces plain object content to JSON string (not [object Object])", () => {
+    const result = formatPrompt([
+      { role: "user", content: { text: "structured", extra: 42 } as any },
+    ]);
+    expect(result).not.toBe("[object Object]");
+    expect(result).toContain("structured");
+  });
+
+  it("handles null content gracefully", () => {
+    const result = formatPrompt([{ role: "user", content: null as any }]);
+    expect(result).toBe("");
+  });
+
+  it("handles undefined content gracefully", () => {
+    const result = formatPrompt([{ role: "user", content: undefined as any }]);
+    expect(result).toBe("");
+  });
 });
 
 // ──────────────────────────────────────────────────────────────────────────────