@quantumclaw/quantumclaw 2026.3.22

package/docs/gateway/openresponses-http-api.md

@@ -0,0 +1,295 @@
+---
+summary: "Expose an OpenResponses-compatible /v1/responses HTTP endpoint from the Gateway"
+read_when:
+  - Integrating clients that speak the OpenResponses API
+  - You want item-based inputs, client tool calls, or SSE events
+title: "OpenResponses API"
+---
+
+# OpenResponses API (HTTP)
+
+QuantumClaw’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
+
+This endpoint is **disabled by default**. Enable it in config first.
+
+- `POST /v1/responses`
+- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/responses`
+
+Under the hood, requests are executed as a normal Gateway agent run (same codepath as
+`quantumclaw agent`), so routing/permissions/config match your Gateway.
+
+## Authentication, security, and routing
+
+Operational behavior matches [OpenAI Chat Completions](/gateway/openai-http-api):
+
+- use `Authorization: Bearer <token>` with the normal Gateway auth config
+- treat the endpoint as full operator access for the gateway instance
+- select agents with `model: "quantumclaw:<agentId>"`, `model: "agent:<agentId>"`, or `x-quantumclaw-agent-id`
+- use `x-quantumclaw-session-key` for explicit session routing
+
+Enable or disable this endpoint with `gateway.http.endpoints.responses.enabled`.
+
+## Session behavior
+
+By default the endpoint is **stateless per request** (a new session key is generated each call).
+
+If the request includes an OpenResponses `user` string, the Gateway derives a stable session key
+from it, so repeated calls can share an agent session.
+
+## Request shape (supported)
+
+The request follows the OpenResponses API with item-based input. Current support:
+
+- `input`: string or array of item objects.
+- `instructions`: merged into the system prompt.
+- `tools`: client tool definitions (function tools).
+- `tool_choice`: filter or require client tools.
+- `stream`: enables SSE streaming.
+- `max_output_tokens`: best-effort output limit (provider dependent).
+- `user`: stable session routing.
+
+Accepted but **currently ignored**:
+
+- `max_tool_calls`
+- `reasoning`
+- `metadata`
+- `store`
+- `previous_response_id`
+- `truncation`
+
+## Items (input)
+
+### `message`
+
+Roles: `system`, `developer`, `user`, `assistant`.
+
+- `system` and `developer` are appended to the system prompt.
+- The most recent `user` or `function_call_output` item becomes the “current message.”
+- Earlier user/assistant messages are included as history for context.
+
+### `function_call_output` (turn-based tools)
+
+Send tool results back to the model:
+
+```json
+{
+  "type": "function_call_output",
+  "call_id": "call_123",
+  "output": "{\"temperature\": \"72F\"}"
+}
+```
+
+### `reasoning` and `item_reference`
+
+Accepted for schema compatibility but ignored when building the prompt.
+
+## Tools (client-side function tools)
+
+Provide tools with `tools: [{ type: "function", function: { name, description?, parameters? } }]`.
+
+If the agent decides to call a tool, the response returns a `function_call` output item.
+You then send a follow-up request with `function_call_output` to continue the turn.
+
+## Images (`input_image`)
+
+Supports base64 or URL sources:
+
+```json
+{
+  "type": "input_image",
+  "source": { "type": "url", "url": "https://example.com/image.png" }
+}
+```
+
+Allowed MIME types (current): `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/heic`, `image/heif`.
+Max size (current): 10MB.
+
+## Files (`input_file`)
+
+Supports base64 or URL sources:
+
+```json
+{
+  "type": "input_file",
+  "source": {
+    "type": "base64",
+    "media_type": "text/plain",
+    "data": "SGVsbG8gV29ybGQh",
+    "filename": "hello.txt"
+  }
+}
+```
+
+Allowed MIME types (current): `text/plain`, `text/markdown`, `text/html`, `text/csv`,
+`application/json`, `application/pdf`.
+
+Max size (current): 5MB.
+
+Current behavior:
+
+- File content is decoded and added to the **system prompt**, not the user message,
+  so it stays ephemeral (not persisted in session history).
+- PDFs are parsed for text. If little text is found, the first pages are rasterized
+  into images and passed to the model.
+
+PDF parsing uses the Node-friendly `pdfjs-dist` legacy build (no worker). The modern
+PDF.js build expects browser workers/DOM globals, so it is not used in the Gateway.
+
+URL fetch defaults:
+
+- `files.allowUrl`: `true`
+- `images.allowUrl`: `true`
+- `maxUrlParts`: `8` (total URL-based `input_file` + `input_image` parts per request)
+- Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts).
+- Optional hostname allowlists are supported per input type (`files.urlAllowlist`, `images.urlAllowlist`).
+  - Exact host: `"cdn.example.com"`
+  - Wildcard subdomains: `"*.assets.example.com"` (does not match apex)
+  - Empty or omitted allowlists mean no hostname allowlist restriction.
+- To disable URL-based fetches entirely, set `files.allowUrl: false` and/or `images.allowUrl: false`.
+
+## File + image limits (config)
+
+Defaults can be tuned under `gateway.http.endpoints.responses`:
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: {
+          enabled: true,
+          maxBodyBytes: 20000000,
+          maxUrlParts: 8,
+          files: {
+            allowUrl: true,
+            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
+            allowedMimes: [
+              "text/plain",
+              "text/markdown",
+              "text/html",
+              "text/csv",
+              "application/json",
+              "application/pdf",
+            ],
+            maxBytes: 5242880,
+            maxChars: 200000,
+            maxRedirects: 3,
+            timeoutMs: 10000,
+            pdf: {
+              maxPages: 4,
+              maxPixels: 4000000,
+              minTextChars: 200,
+            },
+          },
+          images: {
+            allowUrl: true,
+            urlAllowlist: ["images.example.com"],
+            allowedMimes: [
+              "image/jpeg",
+              "image/png",
+              "image/gif",
+              "image/webp",
+              "image/heic",
+              "image/heif",
+            ],
+            maxBytes: 10485760,
+            maxRedirects: 3,
+            timeoutMs: 10000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Defaults when omitted:
+
+- `maxBodyBytes`: 20MB
+- `maxUrlParts`: 8
+- `files.maxBytes`: 5MB
+- `files.maxChars`: 200k
+- `files.maxRedirects`: 3
+- `files.timeoutMs`: 10s
+- `files.pdf.maxPages`: 4
+- `files.pdf.maxPixels`: 4,000,000
+- `files.pdf.minTextChars`: 200
+- `images.maxBytes`: 10MB
+- `images.maxRedirects`: 3
+- `images.timeoutMs`: 10s
+- HEIC/HEIF `input_image` sources are accepted and normalized to JPEG before provider delivery.
+
+Security note:
+
+- URL allowlists are enforced before fetch and on redirect hops.
+- Allowlisting a hostname does not bypass private/internal IP blocking.
+- For internet-exposed gateways, apply network egress controls in addition to app-level guards.
+  See [Security](/gateway/security).
+
+## Streaming (SSE)
+
+Set `stream: true` to receive Server-Sent Events (SSE):
+
+- `Content-Type: text/event-stream`
+- Each event line is `event: <type>` and `data: <json>`
+- Stream ends with `data: [DONE]`
+
+Event types currently emitted:
+
+- `response.created`
+- `response.in_progress`
+- `response.output_item.added`
+- `response.content_part.added`
+- `response.output_text.delta`
+- `response.output_text.done`
+- `response.content_part.done`
+- `response.output_item.done`
+- `response.completed`
+- `response.failed` (on error)
+
+## Usage
+
+`usage` is populated when the underlying provider reports token counts.
+
+## Errors
+
+Errors use a JSON object like:
+
+```json
+{ "error": { "message": "...", "type": "invalid_request_error" } }
+```
+
+Common cases:
+
+- `401` missing/invalid auth
+- `400` invalid request body
+- `405` wrong method
+
+## Examples
+
+Non-streaming:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/responses \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-quantumclaw-agent-id: main' \
+  -d '{
+    "model": "quantumclaw",
+    "input": "hi"
+  }'
+```
+
+Streaming:
+
+```bash
+curl -N http://127.0.0.1:18789/v1/responses \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-quantumclaw-agent-id: main' \
+  -d '{
+    "model": "quantumclaw",
+    "stream": true,
+    "input": "hi"
+  }'
+```

package/docs/gateway/openshell.md

@@ -0,0 +1,307 @@
+---
+title: OpenShell
+summary: "Use OpenShell as a managed sandbox backend for QuantumClaw agents"
+read_when:
+  - You want cloud-managed sandboxes instead of local Docker
+  - You are setting up the OpenShell plugin
+  - You need to choose between mirror and remote workspace modes
+---
+
+# OpenShell
+
+OpenShell is a managed sandbox backend for QuantumClaw. Instead of running Docker
+containers locally, QuantumClaw delegates sandbox lifecycle to the `openshell` CLI,
+which provisions remote environments with SSH-based command execution.
+
+The OpenShell plugin reuses the same core SSH transport and remote filesystem
+bridge as the generic [SSH backend](/gateway/sandboxing#ssh-backend). It adds
+OpenShell-specific lifecycle (`sandbox create/get/delete`, `sandbox ssh-config`)
+and an optional `mirror` workspace mode.
+
+## Prerequisites
+
+- The `openshell` CLI installed and on `PATH` (or set a custom path via
+  `plugins.entries.openshell.config.command`)
+- An OpenShell account with sandbox access
+- QuantumClaw Gateway running on the host
+
+## Quick start
+
+1. Enable the plugin and set the sandbox backend:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "all",
+        backend: "openshell",
+        scope: "session",
+        workspaceAccess: "rw",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      openshell: {
+        enabled: true,
+        config: {
+          from: "quantumclaw",
+          mode: "remote",
+        },
+      },
+    },
+  },
+}
+```
+
+2. Restart the Gateway. On the next agent turn, QuantumClaw creates an OpenShell
+   sandbox and routes tool execution through it.
+
+3. Verify:
+
+```bash
+quantumclaw sandbox list
+quantumclaw sandbox explain
+```
+
+## Workspace modes
+
+This is the most important decision when using OpenShell.
+
+### `mirror`
+
+Use `plugins.entries.openshell.config.mode: "mirror"` when you want the **local
+workspace to stay canonical**.
+
+Behavior:
+
+- Before `exec`, QuantumClaw syncs the local workspace into the OpenShell sandbox.
+- After `exec`, QuantumClaw syncs the remote workspace back to the local workspace.
+- File tools still operate through the sandbox bridge, but the local workspace
+  remains the source of truth between turns.
+
+Best for:
+
+- You edit files locally outside QuantumClaw and want those changes visible in the
+  sandbox automatically.
+- You want the OpenShell sandbox to behave as much like the Docker backend as
+  possible.
+- You want the host workspace to reflect sandbox writes after each exec turn.
+
+Tradeoff: extra sync cost before and after each exec.
+
+### `remote`
+
+Use `plugins.entries.openshell.config.mode: "remote"` when you want the
+**OpenShell workspace to become canonical**.
+
+Behavior:
+
+- When the sandbox is first created, QuantumClaw seeds the remote workspace from
+  the local workspace once.
+- After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate
+  directly against the remote OpenShell workspace.
+- QuantumClaw does **not** sync remote changes back into the local workspace.
+- Prompt-time media reads still work because file and media tools read through
+  the sandbox bridge.
+
+Best for:
+
+- The sandbox should live primarily on the remote side.
+- You want lower per-turn sync overhead.
+- You do not want host-local edits to silently overwrite remote sandbox state.
+
+Important: if you edit files on the host outside QuantumClaw after the initial seed,
+the remote sandbox does **not** see those changes. Use
+`quantumclaw sandbox recreate` to re-seed.
+
+### Choosing a mode
+
+|                          | `mirror`                   | `remote`                  |
+| ------------------------ | -------------------------- | ------------------------- |
+| **Canonical workspace**  | Local host                 | Remote OpenShell          |
+| **Sync direction**       | Bidirectional (each exec)  | One-time seed             |
+| **Per-turn overhead**    | Higher (upload + download) | Lower (direct remote ops) |
+| **Local edits visible?** | Yes, on next exec          | No, until recreate        |
+| **Best for**             | Development workflows      | Long-running agents, CI   |
+
+## Configuration reference
+
+All OpenShell config lives under `plugins.entries.openshell.config`:
+
+| Key                       | Type                     | Default       | Description                                           |
+| ------------------------- | ------------------------ | ------------- | ----------------------------------------------------- |
+| `mode`                    | `"mirror"` or `"remote"` | `"mirror"`    | Workspace sync mode                                   |
+| `command`                 | `string`                 | `"openshell"` | Path or name of the `openshell` CLI                   |
+| `from`                    | `string`                 | `"quantumclaw"`  | Sandbox source for first-time create                  |
+| `gateway`                 | `string`                 | —             | OpenShell gateway name (`--gateway`)                  |
+| `gatewayEndpoint`         | `string`                 | —             | OpenShell gateway endpoint URL (`--gateway-endpoint`) |
+| `policy`                  | `string`                 | —             | OpenShell policy ID for sandbox creation              |
+| `providers`               | `string[]`               | `[]`          | Provider names to attach when sandbox is created      |
+| `gpu`                     | `boolean`                | `false`       | Request GPU resources                                 |
+| `autoProviders`           | `boolean`                | `true`        | Pass `--auto-providers` during sandbox create         |
+| `remoteWorkspaceDir`      | `string`                 | `"/sandbox"`  | Primary writable workspace inside the sandbox         |
+| `remoteAgentWorkspaceDir` | `string`                 | `"/agent"`    | Agent workspace mount path (for read-only access)     |
+| `timeoutSeconds`          | `number`                 | `120`         | Timeout for `openshell` CLI operations                |
+
+Sandbox-level settings (`mode`, `scope`, `workspaceAccess`) are configured under
+`agents.defaults.sandbox` as with any backend. See
+[Sandboxing](/gateway/sandboxing) for the full matrix.
+
+## Examples
+
+### Minimal remote setup
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "all",
+        backend: "openshell",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      openshell: {
+        enabled: true,
+        config: {
+          from: "quantumclaw",
+          mode: "remote",
+        },
+      },
+    },
+  },
+}
+```
+
+### Mirror mode with GPU
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "all",
+        backend: "openshell",
+        scope: "agent",
+        workspaceAccess: "rw",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      openshell: {
+        enabled: true,
+        config: {
+          from: "quantumclaw",
+          mode: "mirror",
+          gpu: true,
+          providers: ["openai"],
+          timeoutSeconds: 180,
+        },
+      },
+    },
+  },
+}
+```
+
+### Per-agent OpenShell with custom gateway
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: { mode: "off" },
+    },
+    list: [
+      {
+        id: "researcher",
+        sandbox: {
+          mode: "all",
+          backend: "openshell",
+          scope: "agent",
+          workspaceAccess: "rw",
+        },
+      },
+    ],
+  },
+  plugins: {
+    entries: {
+      openshell: {
+        enabled: true,
+        config: {
+          from: "quantumclaw",
+          mode: "remote",
+          gateway: "lab",
+          gatewayEndpoint: "https://lab.example",
+          policy: "strict",
+        },
+      },
+    },
+  },
+}
+```
+
+## Lifecycle management
+
+OpenShell sandboxes are managed through the normal sandbox CLI:
+
+```bash
+# List all sandbox runtimes (Docker + OpenShell)
+quantumclaw sandbox list
+
+# Inspect effective policy
+quantumclaw sandbox explain
+
+# Recreate (deletes remote workspace, re-seeds on next use)
+quantumclaw sandbox recreate --all
+```
+
+For `remote` mode, **recreate is especially important**: it deletes the canonical
+remote workspace for that scope. The next use seeds a fresh remote workspace from
+the local workspace.
+
+For `mirror` mode, recreate mainly resets the remote execution environment because
+the local workspace remains canonical.
+
+### When to recreate
+
+Recreate after changing any of these:
+
+- `agents.defaults.sandbox.backend`
+- `plugins.entries.openshell.config.from`
+- `plugins.entries.openshell.config.mode`
+- `plugins.entries.openshell.config.policy`
+
+```bash
+quantumclaw sandbox recreate --all
+```
+
+## Current limitations
+
+- Sandbox browser is not supported on the OpenShell backend.
+- `sandbox.docker.binds` does not apply to OpenShell.
+- Docker-specific runtime knobs under `sandbox.docker.*` apply only to the Docker
+  backend.
+
+## How it works
+
+1. QuantumClaw calls `openshell sandbox create` (with `--from`, `--gateway`,
+   `--policy`, `--providers`, `--gpu` flags as configured).
+2. QuantumClaw calls `openshell sandbox ssh-config <name>` to get SSH connection
+   details for the sandbox.
+3. Core writes the SSH config to a temp file and opens an SSH session using the
+   same remote filesystem bridge as the generic SSH backend.
+4. In `mirror` mode: sync local to remote before exec, run, sync back after exec.
+5. In `remote` mode: seed once on create, then operate directly on the remote
+   workspace.
+
+## See also
+
+- [Sandboxing](/gateway/sandboxing) -- modes, scopes, and backend comparison
+- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging blocked tools
+- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides
+- [Sandbox CLI](/cli/sandbox) -- `quantumclaw sandbox` commands

package/docs/gateway/pairing.md

@@ -0,0 +1,99 @@
+---
+summary: "Gateway-owned node pairing (Option B) for iOS and other remote nodes"
+read_when:
+  - Implementing node pairing approvals without macOS UI
+  - Adding CLI flows for approving remote nodes
+  - Extending gateway protocol with node management
+title: "Gateway-Owned Pairing"
+---
+
+# Gateway-owned pairing (Option B)
+
+In Gateway-owned pairing, the **Gateway** is the source of truth for which nodes
+are allowed to join. UIs (macOS app, future clients) are just frontends that
+approve or reject pending requests.
+
+**Important:** WS nodes use **device pairing** (role `node`) during `connect`.
+`node.pair.*` is a separate pairing store and does **not** gate the WS handshake.
+Only clients that explicitly call `node.pair.*` use this flow.
+
+## Concepts
+
+- **Pending request**: a node asked to join; requires approval.
+- **Paired node**: approved node with an issued auth token.
+- **Transport**: the Gateway WS endpoint forwards requests but does not decide
+  membership. (Legacy TCP bridge support is deprecated/removed.)
+
+## How pairing works
+
+1. A node connects to the Gateway WS and requests pairing.
+2. The Gateway stores a **pending request** and emits `node.pair.requested`.
+3. You approve or reject the request (CLI or UI).
+4. On approval, the Gateway issues a **new token** (tokens are rotated on re‑pair).
+5. The node reconnects using the token and is now “paired”.
+
+Pending requests expire automatically after **5 minutes**.
+
+## CLI workflow (headless friendly)
+
+```bash
+quantumclaw nodes pending
+quantumclaw nodes approve <requestId>
+quantumclaw nodes reject <requestId>
+quantumclaw nodes status
+quantumclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
+```
+
+`nodes status` shows paired/connected nodes and their capabilities.
+
+## API surface (gateway protocol)
+
+Events:
+
+- `node.pair.requested` — emitted when a new pending request is created.
+- `node.pair.resolved` — emitted when a request is approved/rejected/expired.
+
+Methods:
+
+- `node.pair.request` — create or reuse a pending request.
+- `node.pair.list` — list pending + paired nodes.
+- `node.pair.approve` — approve a pending request (issues token).
+- `node.pair.reject` — reject a pending request.
+- `node.pair.verify` — verify `{ nodeId, token }`.
+
+Notes:
+
+- `node.pair.request` is idempotent per node: repeated calls return the same
+  pending request.
+- Approval **always** generates a fresh token; no token is ever returned from
+  `node.pair.request`.
+- Requests may include `silent: true` as a hint for auto-approval flows.
+
+## Auto-approval (macOS app)
+
+The macOS app can optionally attempt a **silent approval** when:
+
+- the request is marked `silent`, and
+- the app can verify an SSH connection to the gateway host using the same user.
+
+If silent approval fails, it falls back to the normal “Approve/Reject” prompt.
+
+## Storage (local, private)
+
+Pairing state is stored under the Gateway state directory (default `~/.quantumclaw`):
+
+- `~/.quantumclaw/nodes/paired.json`
+- `~/.quantumclaw/nodes/pending.json`
+
+If you override `QUANTUMCLAW_STATE_DIR`, the `nodes/` folder moves with it.
+
+Security notes:
+
+- Tokens are secrets; treat `paired.json` as sensitive.
+- Rotating a token requires re-approval (or deleting the node entry).
+
+## Transport behavior
+
+- The transport is **stateless**; it does not store membership.
+- If the Gateway is offline or pairing is disabled, nodes cannot pair.
+- If the Gateway is in remote mode, pairing still happens against the remote Gateway’s store.