v0.7.0

# v0.7.0 — Craft CLI, Headless Server & Architecture Overhaul

---

## Craft CLI

A new terminal client for running agent sessions from the command line — no GUI required.

- **`craft-cli run`** — launch agent sessions directly from your terminal with prompt input and streaming output
- **Multi-provider support** — select between multiple LLM connections and models from the CLI
- **CI workspace support** — create and manage workspaces programmatically for automated workflows
- **`--validate-server`** — verify server configuration with prettified diagnostic output
- **Redesigned spinner** — stays visible during agent thinking for better terminal UX

### Why it's cool
This is the first step toward full programmatic control of Craft Agents. Script your agent workflows, integrate into CI/CD pipelines, or run sessions headlessly on remote machines. Partially addresses [#343](#343).

## Headless Server

Run Craft Agents as a standalone server without the Electron desktop app — deploy on any machine, connect from any client.

- **Standalone Bun server** — headless entry point that runs without Electron, with sharp eliminated from the bundle
- **TLS support** — secure remote connections with automatic certificate handling
- **Multi-platform build script** — distribution packaging for Linux, macOS, and Windows
- **Remote mode via env vars** — configure headless operation through environment variables
- **Thin-client connection state** — WebSocket connection status and failure banners in the client

### Why it's cool
Deploy Craft Agents on a remote server and connect from anywhere. Run it on your home lab, a cloud VM, or a CI runner. The thin-client mode means the browser UI stays lightweight while all the heavy lifting happens server-side. Partially addresses [#291](#291).

## Transport & Architecture

The entire inter-process communication layer has been rebuilt from the ground up.

- **WebSocket-only RPC** — replaced Electron IPC with WebSocket RPC for all communication, enabling remote operation
- **Bidirectional RPC** — typed push events, server-owned OAuth token management
- **Server-core extraction** — 14 core handlers, session management, services, and domain utilities extracted into `@craft-agent/server-core` for reuse across Electron and headless
- **Protocol formalization** — channels, DTOs, and event maps extracted to `@craft-agent/shared/protocol` with wire-format stability tests
- **Split-brain cleanup** — removed dead handler/session copies, added `IWindowManager` and channel advertisement

### Why it's cool
This is the foundation that makes CLI, headless server, and future remote/mobile clients possible. The architecture is now cleanly split between reusable server-core logic and platform-specific shells (Electron, Bun server, CLI).

## Editor & UI

- **Rich block interactions** — tiptap image support, slash menu for inserting content blocks, and theme fallback
- **Model fallback chain** — automatic fallback between models when one is unavailable, with improved playground theming
- **Browser tooling** — better lifecycle management, metadata badge components, and safe-mode boundaries

## Security

- **Block unencrypted WebSocket** — remote connections now require `wss://` (TLS); plaintext `ws://` is rejected
- **Certificate generation** — fixed curve name in cert generation script

## Bug Fixes

- **Pi 3-tier model persistence** — fixed model save/hydration for Best/Balanced/Fast tiers. Fixes [#336](#336)
- **Multi-panel input focus** — fixed focus scoping and race handling that caused keystrokes to jump between panels. Fixes [#339](#339)
- **Pi Azure base URL** — propagate Azure base URL to Pi subprocess
- **Deep-link routing** — corrected deep-link client targeting with regression tests
- **Split-turn expansion** — fixed TurnCard expansion key collisions
- **Explore mode false positive** — no longer flags node arrow syntax (`=>`) as a write operation
- **Onboarding loop** — fixed onboarding always showing + silent connection save failures
- **Copilot model listing** — use GitHub OAuth token for CopilotClient model listing
- **Label badge overlap** — prevent premature label badge overlap in UI
- **Transport hardening** — hardened WebSocket startup routing, codec, and session watcher isolation
- **OAuth fixes** — open OAuth browser locally via `shell.openExternal`, accept `/oauth/callback` path
- **Event payloads** — consistent `sources:changed` and `skills:changed` payload shapes
- **Global config guard** — ensure `config.json` exists before handler registration

Author: github-actions[bot]

.github/workflows/validate-server.yml

@@ -0,0 +1,26 @@
+name: Validate Server (Integration)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  validate-server:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run --validate-server
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.CRAFT_ANTHROPIC_API_KEY }}
+        run: bun run apps/cli/src/index.ts --validate-server --no-spinner

.github/workflows/validate.yml

@@ -0,0 +1,34 @@
+name: Validate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: validate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run validation suite
+        run: bun run validate:ci

.gitignore

@@ -62,3 +62,7 @@ id_ed25519*
 # Credentials files
 credentials.enc
 *.credentials
+
+# act (local GitHub Actions runner)
+.secrets
+.actrc

README.md

@@ -147,11 +147,205 @@ Use **SHIFT+TAB** to cycle through modes in the chat interface.
 | `Enter` | Send message |
 | `Shift+Enter` | New line |
 
+## Remote Server (Headless)
+
+Craft Agents can run as a headless server on a remote machine (e.g., a Linux VPS), with the desktop app connecting as a thin client. This lets you keep long-running sessions alive, access them from multiple machines, and run compute-heavy tasks on a powerful server.
+
+### Quick Start
+
+From the monorepo root:
+
+```bash
+# Generate a token and start the server
+CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts
+```
+
+The server prints the connection details on startup:
+
+```
+CRAFT_SERVER_URL=ws://203.0.113.5:9100
+CRAFT_SERVER_TOKEN=<generated-token>
+```
+
+Copy these values and use them to connect the desktop app.
+
+### Connecting the Desktop App
+
+Launch the Electron app in thin-client mode by passing the server URL and token:
+
+```bash
+CRAFT_SERVER_URL=wss://203.0.113.5:9100 CRAFT_SERVER_TOKEN=<token> bun run electron:start
+```
+
+In thin-client mode, the desktop app renders the UI but all session logic, tool execution, and LLM calls run on the remote server.
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CRAFT_SERVER_TOKEN` | Yes | — | Bearer token for client authentication |
+| `CRAFT_RPC_HOST` | No | `127.0.0.1` | Bind address (`0.0.0.0` for remote access) |
+| `CRAFT_RPC_PORT` | No | `9100` | Bind port |
+| `CRAFT_RPC_TLS_CERT` | No | — | Path to PEM certificate file (enables `wss://`) |
+| `CRAFT_RPC_TLS_KEY` | No | — | Path to PEM private key file (required with cert) |
+| `CRAFT_RPC_TLS_CA` | No | — | Path to PEM CA chain file (optional, for client cert verification) |
+| `CRAFT_DEBUG` | No | `false` | Enable debug logging |
+
+### TLS (Recommended for Remote Access)
+
+When exposing the server over the network, TLS encrypts the WebSocket connection (`wss://` instead of `ws://`).
+
+**Generate a self-signed certificate (development/testing):**
+
+```bash
+./scripts/generate-dev-cert.sh
+# Creates certs/cert.pem and certs/key.pem (valid 365 days)
+```
+
+**Start the server with TLS:**
+
+```bash
+CRAFT_SERVER_TOKEN=<token> \
+CRAFT_RPC_HOST=0.0.0.0 \
+CRAFT_RPC_TLS_CERT=certs/cert.pem \
+CRAFT_RPC_TLS_KEY=certs/key.pem \
+bun run packages/server/src/index.ts
+```
+
+The server will print `CRAFT_SERVER_URL=wss://<your-public-ip>:9100`.
+
+**For production**, use certificates from a trusted CA (e.g., Let's Encrypt) or place the server behind a reverse proxy (nginx, Caddy) that terminates TLS.
+
+### Docker
+
+```bash
+docker run -d \
+  -p 9100:9100 \
+  -e CRAFT_SERVER_TOKEN=<token> \
+  -e CRAFT_RPC_HOST=0.0.0.0 \
+  -v craft-data:/root/.craft-agent \
+  craft-agents-server
+```
+
+To enable TLS in Docker, mount your certificates and set the env vars:
+
+```bash
+docker run -d \
+  -p 9100:9100 \
+  -e CRAFT_SERVER_TOKEN=<token> \
+  -e CRAFT_RPC_HOST=0.0.0.0 \
+  -e CRAFT_RPC_TLS_CERT=/certs/cert.pem \
+  -e CRAFT_RPC_TLS_KEY=/certs/key.pem \
+  -v ./certs:/certs:ro \
+  -v craft-data:/root/.craft-agent \
+  craft-agents-server
+```
+
+## CLI Client
+
+A terminal client that connects to a running Craft Agent server over WebSocket (`ws://` or `wss://`). Use it for scripting, CI/CD pipelines, server validation, or when you prefer the command line.
+
+### Installation
+
+```bash
+# From the monorepo (requires Bun)
+bun run apps/cli/src/index.ts --help
+
+# Or add to your PATH
+alias craft-cli="bun run $(pwd)/apps/cli/src/index.ts"
+```
+
+### Connection
+
+The CLI reads connection details from flags or environment variables:
+
+```bash
+# Via environment (set once)
+export CRAFT_SERVER_URL=ws://127.0.0.1:9100
+export CRAFT_SERVER_TOKEN=<your-token>
+
+# Or via flags
+craft-cli --url ws://127.0.0.1:9100 --token <token> ping
+```
+
+For TLS connections (`wss://`), use `--tls-ca <path>` for self-signed certificates.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `ping` | Verify connectivity (clientId + latency) |
+| `health` | Check credential store health |
+| `versions` | Show server runtime versions |
+| `workspaces` | List workspaces |
+| `sessions` | List sessions in workspace |
+| `connections` | List LLM connections |
+| `sources` | List configured sources |
+| `session create` | Create a session (`--name`, `--mode`) |
+| `session messages <id>` | Print session message history |
+| `session delete <id>` | Delete a session |
+| `send <id> <message>` | Send message and stream AI response |
+| `cancel <id>` | Cancel in-progress processing |
+| `invoke <channel> [args]` | Raw RPC call with JSON args |
+| `listen <channel>` | Subscribe to push events (Ctrl+C to stop) |
+| `run <prompt>` | Self-contained: spawn server, run prompt, stream response, exit |
+| `--validate-server` | 21-step integration test (auto-spawns server if no `--url`) |
+
+#### Run Command Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--workspace-dir <path>` | — | Register a workspace directory before running |
+| `--source <slug>` | — | Enable a source (repeatable) |
+| `--output-format <fmt>` | `text` | Output format: `text` or `stream-json` |
+| `--mode <mode>` | `allow-all` | Permission mode for the session |
+| `--no-cleanup` | `false` | Skip session deletion on exit |
+| `--server-entry <path>` | — | Custom server entry point |
+| `--provider <name>` | `anthropic` | LLM provider (`anthropic`, `openai`, `google`, `openrouter`, `groq`, `mistral`, `xai`, etc.) |
+| `--model <id>` | (provider default) | Model ID (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`, `gemini-2.0-flash`) |
+| `--api-key <key>` | — | API key (or `$LLM_API_KEY`, or provider-specific env var) |
+| `--base-url <url>` | — | Custom API endpoint for proxies or self-hosted models |
+
+The `run` command is fully self-contained — it spawns a headless server, creates a session, sends the prompt, streams the response, and exits. No separate server setup needed. An API key is resolved from `--api-key`, `$LLM_API_KEY`, or a provider-specific env var (e.g., `$ANTHROPIC_API_KEY`, `$OPENAI_API_KEY`).
+
+### Examples
+
+```bash
+# Quick connectivity check
+craft-cli ping
+
+# List sessions (human-readable)
+craft-cli sessions
+
+# Send a message and stream the AI response
+craft-cli send abc-123 "What files are in the current directory?"
+
+# Pipe input
+echo "Summarize this" | craft-cli send abc-123
+
+# JSON output for scripting
+craft-cli --json workspaces | jq '.[].name'
+
+# Self-contained run (spawns its own server)
+craft-cli run "Summarize the README"
+craft-cli run --workspace-dir ./my-project --source github "List open PRs"
+
+# Multi-provider support
+craft-cli run --provider openai --model gpt-4o "Summarize this repo"
+GOOGLE_API_KEY=... craft-cli run --provider google --model gemini-2.0-flash "Hello"
+craft-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"
+
+# Validate the server (auto-spawns if no --url)
+craft-cli --validate-server
+craft-cli --validate-server --url ws://127.0.0.1:9100 --token <token>
+```
+
 ## Architecture
 
 ```
 craft-agent/
 ├── apps/
+│   ├── cli/                   # Terminal client (CLI)
 │   └── electron/              # Desktop GUI (primary)
 │       └── src/
 │           ├── main/          # Electron main process

apps/cli/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@craft-agent/cli",
+  "version": "0.7.0",
+  "description": "Terminal client for Craft Agent server",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "craft-cli": "src/index.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "@craft-agent/shared": "workspace:*",
+    "@craft-agent/server-core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "@types/node": "^22.0.0",
+    "@types/bun": "latest"
+  }
+}