swarph-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{swarph_cli-0.2.0/src/swarph_cli.egg-info → swarph_cli-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.2.0
-Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13).
+Version: 0.4.0
+Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.4.0 ships Phase 5.5 `swarph onboard` + `swarph ratify` on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL (PLAN.md §13 / §15).
 Author: Pierre Samson, Claude Opus
 License: MIT
 Project-URL: Homepage, https://github.com/darw007d/swarph-cli
@@ -24,7 +24,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: swarph-mesh>=0.1.0
+Requires-Dist: swarph-mesh>=0.5.0
 Requires-Dist: swarph-shared>=0.2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
@@ -49,12 +49,84 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.2.0 — Phase 2 one-shot + Phase 2.5 import.** Two verbs ship:
+**v0.4.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify.** Five verbs ship:
 
-1. `swarph "prompt"` — Phase 2 one-shot mode (against `--provider gemini`)
-2. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
+1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
+2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
+3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
+4. `swarph onboard <peer-name>` — **NEW** Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+5. `swarph ratify <peer-name>` — **NEW** Phase 5.5 witness ratification (PLAN.md §15.4a)
 
-Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, additional source formats).
+Subsequent phases extend the CLI surface (`--ask <peer>`, daemon).
+
+### `swarph onboard` + `swarph ratify` (Phase 5.5)
+
+Per PLAN.md §15, onboarding splits into a **mechanics phase** (`swarph onboard`) that automates the boring parts (registry POST, scaffolding, token resolution) and a **manual contract phase** (the new peer composes the handshake DM in their own words). A witness peer judges the handshake and runs `swarph ratify <peer>` to flip `ratified=true`, gating `task_claim` server-side.
+
+```bash
+# New peer self-onboards
+$ swarph onboard razorpeter
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] prepare peer-registry row                 ok
+[3/6] resolve MESH_GATEWAY_TOKEN                ok
+[4/6] POST .../peers/register                   ok (registered_unratified=true)
+[5/6] verify_subscription_setup()               ok
+[6/6] scaffold ~/swarph_state/razorpeter/       ok
+
+[manual] handshake template at /tmp/razorpeter-handshake.md
+  Edit each section in your own words, then send to your witness peer.
+
+# After peer composes + sends handshake, witness ratifies
+$ SWARPH_WITNESS=lab-ovh swarph ratify razorpeter \
+    --reason "handshake covers all four invariants in own words"
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] verify witness 'lab-ovh' is ratified      ok
+[3/6] verify 'razorpeter' is registered_unratified  ok
+[4/6] PATCH .../peers/razorpeter                ok
+[5/6] verify peer_ratifications audit row       ok (id=N reason='...')
+[6/6] invalidate local TTL cache                ok
+```
+
+Server-side gating (mesh-gateway PR A): unratified peers can read inbox + send DMs (so the handshake itself works) but `task_claim` returns 403. Witness must itself be ratified — no self-ratification, no unratified-witnesses-ratifying-others. Audit log (`peer_ratifications`) is append-only.
+
+### `swarph chat`
+
+Interactive REPL against any of the five swarph-mesh adapters (`gemini` / `deepseek` / `claude` / `openai` / `grok`). Multi-turn conversation history accumulates in-memory; cumulative session cost + token totals tracked.
+
+```bash
+$ swarph chat --provider claude
+swarph chat — Phase 5 REPL
+provider=claude model=(adapter default) caller=cli.repl.ubuntu
+
+Type a message and press Enter to send. Slash commands:
+  /help  /clear  /system  /provider  /model  /history  /cost  /quit
+Ctrl-D to exit.
+
+> hello
+Hi! How can I help...
+# 8+12t  $0  0.34s
+
+> /provider gemini
+[switched to provider=gemini; model reset to adapter default; history cleared]
+
+> /cost
+[turns=1  in=8  out=12  cost=$0]
+
+> /quit
+[swarph-chat] bye.
+```
+
+**Slash commands:**
+- `/help` — print available commands
+- `/quit`, `/exit` (or Ctrl-D) — exit
+- `/clear`, `/reset` — clear history (keeps system prompt)
+- `/system [prompt]` — set or clear system prompt
+- `/provider <name>` — switch provider (resets history)
+- `/model <name>` — switch model
+- `/history` — print running message list
+- `/cost` — cumulative session cost + tokens
+
+**Out of scope until Phase 5.6** (`swarph daemon`): inbox drain coroutine, `/inbox` and `/reply` slash commands. Streaming output ships alongside the cross-adapter `stream()` work in v0.5+ of swarph-mesh.
 
 ### `swarph import`
 
@@ -115,13 +187,14 @@ Pong!
 
 | Phase | What lands |
 |---|---|
-| **0** (this) | Scaffold — entry-point + status banner |
-| **2** | One-shot mode: `swarph "hello" --provider gemini` |
+| **0** | Scaffold — entry-point + status banner |
+| **2** (v0.1.0) | One-shot mode: `swarph "hello" --provider gemini` |
+| **2.5** (v0.2.0) | `swarph import` — Claude JSONL → swarph-native session format |
+| **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
+| **5.5** (v0.4.0 — this release) | **`swarph onboard <peer-name>` + `swarph ratify <peer-name>`** — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
 | **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
-| **5** | Interactive REPL — `/inbox`, `/reply`, `/dm`, `/watch` |
-| **5.5** | `swarph onboard <peer-name>` + `swarph ratify <peer-name>` (PLAN.md §15) |
-| **5.7** | `swarph daemon` foreground drain loop + `swarph chat` REPL with drain coroutine (PLAN.md §16) |
-| **6** | PyPI publish |
+| **5.6** | `swarph daemon` foreground drain loop + REPL drain coroutine + `/inbox`, `/reply` (PLAN.md §16) |
+| **6** | (already done) PyPI publish |
 
 ## Why split CLI from substrate
 

swarph_cli-0.4.0/README.md

@@ -0,0 +1,184 @@
+# swarph-cli
+
+The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Thin client over the [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) substrate.
+
+```bash
+pip install swarph-cli
+swarph --version
+```
+
+This is one of three repos in the v0.3.x architecture:
+
+| Repo | Role |
+|---|---|
+| [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) | Substrate Python package — Protocol + adapters + SwarphCall + MeshClient. Pure library, no CLI |
+| [`swarph-cli`](https://github.com/darw007d/swarph-cli) | This repo — the `swarph` binary |
+| [`swarph-meshlm`](https://github.com/darw007d/swarph-meshlm) | Simon Willison `llm` plugin |
+
+## Status
+
+**v0.4.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify.** Five verbs ship:
+
+1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
+2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
+3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
+4. `swarph onboard <peer-name>` — **NEW** Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+5. `swarph ratify <peer-name>` — **NEW** Phase 5.5 witness ratification (PLAN.md §15.4a)
+
+Subsequent phases extend the CLI surface (`--ask <peer>`, daemon).
+
+### `swarph onboard` + `swarph ratify` (Phase 5.5)
+
+Per PLAN.md §15, onboarding splits into a **mechanics phase** (`swarph onboard`) that automates the boring parts (registry POST, scaffolding, token resolution) and a **manual contract phase** (the new peer composes the handshake DM in their own words). A witness peer judges the handshake and runs `swarph ratify <peer>` to flip `ratified=true`, gating `task_claim` server-side.
+
+```bash
+# New peer self-onboards
+$ swarph onboard razorpeter
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] prepare peer-registry row                 ok
+[3/6] resolve MESH_GATEWAY_TOKEN                ok
+[4/6] POST .../peers/register                   ok (registered_unratified=true)
+[5/6] verify_subscription_setup()               ok
+[6/6] scaffold ~/swarph_state/razorpeter/       ok
+
+[manual] handshake template at /tmp/razorpeter-handshake.md
+  Edit each section in your own words, then send to your witness peer.
+
+# After peer composes + sends handshake, witness ratifies
+$ SWARPH_WITNESS=lab-ovh swarph ratify razorpeter \
+    --reason "handshake covers all four invariants in own words"
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] verify witness 'lab-ovh' is ratified      ok
+[3/6] verify 'razorpeter' is registered_unratified  ok
+[4/6] PATCH .../peers/razorpeter                ok
+[5/6] verify peer_ratifications audit row       ok (id=N reason='...')
+[6/6] invalidate local TTL cache                ok
+```
+
+Server-side gating (mesh-gateway PR A): unratified peers can read inbox + send DMs (so the handshake itself works) but `task_claim` returns 403. Witness must itself be ratified — no self-ratification, no unratified-witnesses-ratifying-others. Audit log (`peer_ratifications`) is append-only.
+
+### `swarph chat`
+
+Interactive REPL against any of the five swarph-mesh adapters (`gemini` / `deepseek` / `claude` / `openai` / `grok`). Multi-turn conversation history accumulates in-memory; cumulative session cost + token totals tracked.
+
+```bash
+$ swarph chat --provider claude
+swarph chat — Phase 5 REPL
+provider=claude model=(adapter default) caller=cli.repl.ubuntu
+
+Type a message and press Enter to send. Slash commands:
+  /help  /clear  /system  /provider  /model  /history  /cost  /quit
+Ctrl-D to exit.
+
+> hello
+Hi! How can I help...
+# 8+12t  $0  0.34s
+
+> /provider gemini
+[switched to provider=gemini; model reset to adapter default; history cleared]
+
+> /cost
+[turns=1  in=8  out=12  cost=$0]
+
+> /quit
+[swarph-chat] bye.
+```
+
+**Slash commands:**
+- `/help` — print available commands
+- `/quit`, `/exit` (or Ctrl-D) — exit
+- `/clear`, `/reset` — clear history (keeps system prompt)
+- `/system [prompt]` — set or clear system prompt
+- `/provider <name>` — switch provider (resets history)
+- `/model <name>` — switch model
+- `/history` — print running message list
+- `/cost` — cumulative session cost + tokens
+
+**Out of scope until Phase 5.6** (`swarph daemon`): inbox drain coroutine, `/inbox` and `/reply` slash commands. Streaming output ships alongside the cross-adapter `stream()` work in v0.5+ of swarph-mesh.
+
+### `swarph import`
+
+Per PLAN.md §17, session import is the **knowledge half of onboarding** — gives a memory-carrying peer (or human migrating CLIs) the substantive context they're bringing into the swarph, paired with §15's contract half (handshake DM acknowledging the four invariants).
+
+```bash
+# Inspect what would be imported (lossy → honest framing)
+$ swarph import ~/.claude/projects/.../X.jsonl --report-only
+
+# Commit — writes ~/.swarph/sessions/<session-id>.jsonl
+$ swarph import ~/.claude/projects/.../X.jsonl
+
+# Refuse-with-error if target exists (protects continuation turns)
+$ swarph import same-source.jsonl
+swarph import: target /home/.../X.jsonl already exists (...)
+To proceed:
+  --force                  overwrite (destroys continuation turns)
+  --target-session NAME    write to a different file
+```
+
+**What ports cleanly:** plain user/assistant/system text, role tags, conversation order.
+
+**What's lossy** (counted in report, kept as visible text where possible):
+- `thinking` blocks (Anthropic-specific reasoning trace)
+- `tool_use` blocks (call shape doesn't port across providers)
+- `tool_result` blocks (companion drop with `tool_use`)
+
+**What's dropped:** attachments (would need re-upload), provider-side KV cache, conversation IDs, `cache_control` annotations.
+
+Honest framing per PLAN.md §17.3: **teleport is "import + continue", not "freeze and resume"** — the first turn after import on a new provider pays cold-cache cost. Phase 5+ adds `--continue` for live REPL integration.
+
+```bash
+$ swarph "say pong" --provider gemini
+Pong!
+# 3+26t  $0.0000  0.73s  caller=cli.oneshot.ubuntu  provider=gemini
+```
+
+### `--json` mode semantics
+
+`--json` is a **harness trigger**, not a strict-validation gate. When set, swarph routes the response through the swarph-mesh JSON harness:
+
+- A permissive `{"type": "object"}` schema is synthesised when `--schema` is absent (Phase 5+ adds Pydantic validation).
+- The harness retries once with `[USER]`-turn feedback on parse failure.
+- **Malformed-JSON exits with code 1** + raw text on stdout for caller recovery. Useful for shell scripts:
+  ```bash
+  if swarph "give me a trade" --json; then
+    # parsed dict was on stdout
+    ...
+  fi
+  ```
+- Pretty-printed parsed dict on stdout when parse succeeds; `error_class=malformed_json` shows up in the stderr attribution footer when it doesn't.
+
+## Spec
+
+→ [hedge-fund-mcp / research/swarph_cli/PLAN.md](https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md)
+
+## Phase rollout
+
+| Phase | What lands |
+|---|---|
+| **0** | Scaffold — entry-point + status banner |
+| **2** (v0.1.0) | One-shot mode: `swarph "hello" --provider gemini` |
+| **2.5** (v0.2.0) | `swarph import` — Claude JSONL → swarph-native session format |
+| **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
+| **5.5** (v0.4.0 — this release) | **`swarph onboard <peer-name>` + `swarph ratify <peer-name>`** — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
+| **5.6** | `swarph daemon` foreground drain loop + REPL drain coroutine + `/inbox`, `/reply` (PLAN.md §16) |
+| **6** | (already done) PyPI publish |
+
+## Why split CLI from substrate
+
+`swarph-mesh` (the library) is imported by `omega-boss`, Council judges, `lab-orchestrator`, and any future swarph peer that wants to write programs against the Protocol. Those callers don't need the CLI surface or the console-script entry point. Keeping the CLI in a separate repo means library users `pip install swarph-mesh` without pulling argparse + REPL plumbing they'll never run.
+
+## Install (dev)
+
+```bash
+git clone https://github.com/darw007d/swarph-cli
+cd swarph-cli
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+swarph --version
+```
+
+## License
+
+MIT. Pierre Samson + Claude Opus, 2026.

{swarph_cli-0.2.0 → swarph_cli-0.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.2.0"
-description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13)."
+version = "0.4.0"
+description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.4.0 ships Phase 5.5 `swarph onboard` + `swarph ratify` on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL (PLAN.md §13 / §15)."
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
@@ -29,7 +29,9 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "swarph-mesh>=0.1.0",
+    # Phase 5 REPL exercises all five adapters; bumped to 0.5.0 for
+    # OpenAI + Grok availability in /provider switch.
+    "swarph-mesh>=0.5.0",
     "swarph-shared>=0.2.0",
 ]
 

{swarph_cli-0.2.0 → swarph_cli-0.4.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = ["__version__"]

swarph_cli-0.4.0/src/swarph_cli/commands/chat.py

@@ -0,0 +1,348 @@
+"""``swarph chat`` — interactive REPL.
+
+Phase 5 per PLAN.md §13. Multi-turn conversation against any of the
+five swarph-mesh adapters (gemini / deepseek / claude / openai / grok).
+Stdlib-only — uses ``readline`` for line editing + in-process history,
+no third-party REPL framework.
+
+Slash commands (typed as the entire input):
+
+  /help                  — print this list
+  /quit | /exit          — exit (Ctrl-D also works)
+  /clear | /reset        — clear conversation history (keeps system prompt)
+  /system [prompt]       — show or set the system prompt; ``/system`` alone clears it
+  /provider <name>       — switch provider (resets the conversation)
+  /model <name>          — switch model
+  /history               — print the running message list
+  /cost                  — print cumulative session cost + token totals
+
+Out of scope per PLAN.md §13 (lands in 5.6):
+  /inbox /reply          — require the inbox-drain coroutine
+  background drain       — Phase 5.6 ``swarph daemon``
+
+Streaming output is not wired here — every swarph-mesh adapter raises
+``NotImplementedError`` on ``stream()`` as of v0.5.0; the REPL awaits
+the full response and prints in one block. Token-by-token streaming
+lands alongside the cross-adapter ``stream()`` work in v0.5+.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+from swarph_cli.caller import default_caller
+
+
+_BANNER = """\
+swarph chat — Phase 5 REPL
+provider={provider} model={model} caller={caller}{system}
+
+Type a message and press Enter to send. Slash commands:
+  /help  /clear  /system  /provider  /model  /history  /cost  /quit
+Ctrl-D to exit.
+"""
+
+_HELP = """\
+Slash commands:
+  /help                 — show this list
+  /quit, /exit          — exit (Ctrl-D works too)
+  /clear, /reset        — clear conversation history (keeps system prompt)
+  /system [prompt]      — show or set system prompt; bare /system clears it
+  /provider <name>      — switch provider (clears history; rebinds adapter)
+  /model <name>         — switch model
+  /history              — print the running message list
+  /cost                 — print cumulative cost + token totals
+"""
+
+
+@dataclass
+class ReplState:
+    """In-memory REPL state. Lives for the duration of a single
+    ``swarph chat`` process."""
+
+    provider: str
+    model: Optional[str]
+    caller: str
+    system_prompt: Optional[str]
+    temperature: float = 0.7
+    max_tokens: Optional[int] = None
+    messages: list = field(default_factory=list)
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    total_cost_usd: float = 0.0
+    turn_count: int = 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="swarph chat",
+        description=(
+            "Interactive REPL against any swarph-mesh adapter. "
+            "Phase 5 per PLAN.md §13."
+        ),
+    )
+    p.add_argument(
+        "--provider",
+        default="gemini",
+        help='LLM provider (gemini / deepseek / claude / openai / grok).',
+    )
+    p.add_argument(
+        "--model",
+        default=None,
+        help="Provider-specific model id. Defaults to the adapter's default_model.",
+    )
+    p.add_argument(
+        "--caller",
+        default=None,
+        help='Caller-convention slug. Defaults to "cli.repl.<user>".',
+    )
+    p.add_argument(
+        "--system",
+        default=None,
+        help="System prompt prepended to every turn.",
+    )
+    p.add_argument(
+        "--temperature",
+        type=float,
+        default=0.7,
+    )
+    p.add_argument(
+        "--max-tokens",
+        type=int,
+        default=None,
+    )
+    return p
+
+
+def _default_repl_caller() -> str:
+    """``cli.repl.<user>`` — distinct from ``cli.oneshot.<user>`` so
+    attribution rows distinguish REPL turns from one-shot calls.
+
+    Falls back to the caller-convention default if env-derived user
+    extraction fails."""
+    user = os.environ.get("USER") or os.environ.get("LOGNAME")
+    if not user:
+        return default_caller()
+    user_slug = "".join(c if c.isalnum() else "_" for c in user.lower())
+    return f"cli.repl.{user_slug}"
+
+
+def _print(msg: str = "", *, file=None) -> None:
+    """Centralized print helper — tests monkeypatch this so they can
+    capture REPL output without poking sys.stdout."""
+    print(msg, file=file or sys.stdout, flush=True)
+
+
+def _read_line(prompt: str) -> str:
+    """Single-line input. Tests monkeypatch this to inject scripted
+    input. Production uses stdlib ``input()`` — readline is auto-loaded
+    by import-time on POSIX, giving line editing + history for free."""
+    try:
+        import readline  # noqa: F401 — side-effect-only on POSIX
+    except ImportError:
+        pass  # Windows / minimal builds; raw input still works
+    return input(prompt)
+
+
+def _format_attribution(
+    *, input_tokens: int, output_tokens: int, cost_usd: float, duration_s: float, cached: bool
+) -> str:
+    cost_str = f"${cost_usd:.4f}" if cost_usd > 0 else "$0"
+    line = (
+        f"# {input_tokens}+{output_tokens}t  "
+        f"{cost_str}  {duration_s:.2f}s"
+    )
+    if cached:
+        line += "  (cached)"
+    return line
+
+
+def _handle_slash(state: ReplState, line: str) -> str:
+    """Apply a slash command to ``state``. Return one of:
+
+    - ``"continue"`` — keep the REPL running
+    - ``"quit"``     — exit the REPL with code 0
+    - ``"unknown"``  — unrecognized command (caller prints + continues)
+    """
+    parts = line.split(maxsplit=1)
+    cmd = parts[0].lower()
+    arg = parts[1] if len(parts) > 1 else ""
+
+    if cmd in ("/quit", "/exit"):
+        return "quit"
+
+    if cmd == "/help":
+        _print(_HELP)
+        return "continue"
+
+    if cmd in ("/clear", "/reset"):
+        state.messages = []
+        _print("[cleared conversation history]")
+        return "continue"
+
+    if cmd == "/system":
+        if not arg:
+            if state.system_prompt:
+                _print(f"[system prompt cleared (was: {state.system_prompt!r})]")
+                state.system_prompt = None
+            else:
+                _print("[no system prompt set]")
+        else:
+            state.system_prompt = arg
+            _print(f"[system prompt set: {arg!r}]")
+        return "continue"
+
+    if cmd == "/provider":
+        if not arg:
+            _print(f"[current provider: {state.provider}]")
+            return "continue"
+        state.provider = arg
+        state.model = None  # adapter's default_model picks up
+        state.messages = []
+        _print(
+            f"[switched to provider={arg}; model reset to adapter default; "
+            f"history cleared]"
+        )
+        return "continue"
+
+    if cmd == "/model":
+        if not arg:
+            _print(f"[current model: {state.model or '(adapter default)'}]")
+            return "continue"
+        state.model = arg
+        _print(f"[switched to model={arg}]")
+        return "continue"
+
+    if cmd == "/history":
+        if not state.messages:
+            _print("[no messages yet]")
+            return "continue"
+        for i, m in enumerate(state.messages):
+            _print(f"  [{i}] {m.role}: {m.content[:200]}")
+        return "continue"
+
+    if cmd == "/cost":
+        cost_str = f"${state.total_cost_usd:.6f}" if state.total_cost_usd > 0 else "$0"
+        _print(
+            f"[turns={state.turn_count}  "
+            f"in={state.total_input_tokens}  out={state.total_output_tokens}  "
+            f"cost={cost_str}]"
+        )
+        return "continue"
+
+    return "unknown"
+
+
+async def _send_turn(state: ReplState, user_text: str) -> int:
+    """Send one user turn, append assistant reply on success. Returns
+    0 on success, non-zero on adapter error (REPL keeps running either
+    way; the return is for tests).
+
+    On adapter error the user turn is *not* appended to state.messages
+    so the user can retry the same input without doubling it up."""
+    # Local import — keeps the chat module importable in test contexts
+    # that don't have all five adapters installed.
+    from swarph_mesh import ChatMessage, SwarphCall
+
+    state.messages.append(ChatMessage(role="user", content=user_text))
+
+    try:
+        sc = SwarphCall(
+            provider=state.provider,
+            caller=state.caller,
+            model=state.model,
+        )
+        resp = await sc.chat(
+            messages=state.messages,
+            system_prompt=state.system_prompt,
+            temperature=state.temperature,
+            max_tokens=state.max_tokens,
+        )
+    except Exception as exc:
+        # Pop the failed user turn so retry doesn't compound it.
+        state.messages.pop()
+        _print(f"[error] {exc}", file=sys.stderr)
+        return 1
+
+    state.messages.append(ChatMessage(role="assistant", content=resp.text))
+    state.total_input_tokens += resp.input_tokens
+    state.total_output_tokens += resp.output_tokens
+    state.total_cost_usd += resp.cost_usd
+    state.turn_count += 1
+
+    _print(resp.text)
+    _print(
+        _format_attribution(
+            input_tokens=resp.input_tokens,
+            output_tokens=resp.output_tokens,
+            cost_usd=resp.cost_usd,
+            duration_s=resp.duration_s,
+            cached=resp.cached,
+        ),
+        file=sys.stderr,
+    )
+    return 0
+
+
+async def _repl_loop(state: ReplState) -> int:
+    """Main REPL loop. Returns process exit code."""
+    sys_line = f" system={state.system_prompt!r}" if state.system_prompt else ""
+    _print(
+        _BANNER.format(
+            provider=state.provider,
+            model=state.model or "(adapter default)",
+            caller=state.caller,
+            system=sys_line,
+        )
+    )
+
+    while True:
+        try:
+            line = _read_line("> ")
+        except EOFError:
+            _print()
+            _print("[swarph-chat] bye.")
+            return 0
+        except KeyboardInterrupt:
+            _print()
+            _print("[interrupted — type /quit to exit]")
+            continue
+
+        line = line.rstrip()
+        if not line:
+            continue
+
+        if line.startswith("/"):
+            result = _handle_slash(state, line)
+            if result == "quit":
+                _print("[swarph-chat] bye.")
+                return 0
+            if result == "unknown":
+                _print(f"[unknown command: {line.split()[0]!r} — try /help]")
+            continue
+
+        await _send_turn(state, line)
+
+
+def run_chat(argv: list[str]) -> int:
+    """Entry point invoked by ``swarph_cli.main`` verb dispatch.
+
+    Returns process exit code."""
+    args = _build_parser().parse_args(argv)
+    caller = args.caller or _default_repl_caller()
+
+    state = ReplState(
+        provider=args.provider,
+        model=args.model,
+        caller=caller,
+        system_prompt=args.system,
+        temperature=args.temperature,
+        max_tokens=args.max_tokens,
+    )
+
+    return asyncio.run(_repl_loop(state))