@symerian/symi 3.0.21 → 3.0.22

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

@@ -1,333 +0,0 @@
----
-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)
-
-Symi’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
-`symi agent`), so routing/permissions/config match your Gateway.
-
-## Authentication
-
-Uses the Gateway auth configuration. Send a bearer token:
-
-- `Authorization: Bearer <token>`
-
-Notes:
-
-- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `SYMI_GATEWAY_TOKEN`).
-- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `SYMI_GATEWAY_PASSWORD`).
-- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
-
-## Choosing an agent
-
-No custom headers required: encode the agent id in the OpenResponses `model` field:
-
-- `model: "symi:<agentId>"` (example: `"symi:main"`, `"symi:beta"`)
-- `model: "agent:<agentId>"` (alias)
-
-Or target a specific Symi agent by header:
-
-- `x-symi-agent-id: <agentId>` (default: `main`)
-
-Advanced:
-
-- `x-symi-session-key: <sessionKey>` to fully control session routing.
-
-## Enabling the endpoint
-
-Set `gateway.http.endpoints.responses.enabled` to `true`:
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: { enabled: true },
-      },
-    },
-  },
-}
-```
-
-## Disabling the endpoint
-
-Set `gateway.http.endpoints.responses.enabled` to `false`:
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: { enabled: false },
-      },
-    },
-  },
-}
-```
-
-## 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`.
-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)
-
-## 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"],
-            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
-
-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-symi-agent-id: main' \
-  -d '{
-    "model": "symi",
-    "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-symi-agent-id: main' \
-  -d '{
-    "model": "symi",
-    "stream": true,
-    "input": "hi"
-  }'
-```

package/docs/gateway/pairing.md

@@ -1,99 +0,0 @@
----
-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
-symi nodes pending
-symi nodes approve <requestId>
-symi nodes reject <requestId>
-symi nodes status
-symi 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 `~/.symi`):
-
-- `~/.symi/nodes/paired.json`
-- `~/.symi/nodes/pending.json`
-
-If you override `SYMI_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.

package/docs/gateway/protocol.md

@@ -1,221 +0,0 @@
----
-summary: "Gateway WebSocket protocol: handshake, frames, versioning"
-read_when:
-  - Implementing or updating gateway WS clients
-  - Debugging protocol mismatches or connect failures
-  - Regenerating protocol schema/models
-title: "Gateway Protocol"
----
-
-# Gateway protocol (WebSocket)
-
-The Gateway WS protocol is the **single control plane + node transport** for
-Symi. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
-nodes) connect over WebSocket and declare their **role** + **scope** at
-handshake time.
-
-## Transport
-
-- WebSocket, text frames with JSON payloads.
-- First frame **must** be a `connect` request.
-
-## Handshake (connect)
-
-Gateway → Client (pre-connect challenge):
-
-```json
-{
-  "type": "event",
-  "event": "connect.challenge",
-  "payload": { "nonce": "…", "ts": 1737264000000 }
-}
-```
-
-Client → Gateway:
-
-```json
-{
-  "type": "req",
-  "id": "…",
-  "method": "connect",
-  "params": {
-    "minProtocol": 3,
-    "maxProtocol": 3,
-    "client": {
-      "id": "cli",
-      "version": "1.2.3",
-      "platform": "macos",
-      "mode": "operator"
-    },
-    "role": "operator",
-    "scopes": ["operator.read", "operator.write"],
-    "caps": [],
-    "commands": [],
-    "permissions": {},
-    "auth": { "token": "…" },
-    "locale": "en-US",
-    "userAgent": "symi-cli/1.2.3",
-    "device": {
-      "id": "device_fingerprint",
-      "publicKey": "…",
-      "signature": "…",
-      "signedAt": 1737264000000,
-      "nonce": "…"
-    }
-  }
-}
-```
-
-Gateway → Client:
-
-```json
-{
-  "type": "res",
-  "id": "…",
-  "ok": true,
-  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
-}
-```
-
-When a device token is issued, `hello-ok` also includes:
-
-```json
-{
-  "auth": {
-    "deviceToken": "…",
-    "role": "operator",
-    "scopes": ["operator.read", "operator.write"]
-  }
-}
-```
-
-### Node example
-
-```json
-{
-  "type": "req",
-  "id": "…",
-  "method": "connect",
-  "params": {
-    "minProtocol": 3,
-    "maxProtocol": 3,
-    "client": {
-      "id": "ios-node",
-      "version": "1.2.3",
-      "platform": "ios",
-      "mode": "node"
-    },
-    "role": "node",
-    "scopes": [],
-    "caps": ["camera", "canvas", "screen", "location", "voice"],
-    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
-    "permissions": { "camera.capture": true, "screen.record": false },
-    "auth": { "token": "…" },
-    "locale": "en-US",
-    "userAgent": "symi-ios/1.2.3",
-    "device": {
-      "id": "device_fingerprint",
-      "publicKey": "…",
-      "signature": "…",
-      "signedAt": 1737264000000,
-      "nonce": "…"
-    }
-  }
-}
-```
-
-## Framing
-
-- **Request**: `{type:"req", id, method, params}`
-- **Response**: `{type:"res", id, ok, payload|error}`
-- **Event**: `{type:"event", event, payload, seq?, stateVersion?}`
-
-Side-effecting methods require **idempotency keys** (see schema).
-
-## Roles + scopes
-
-### Roles
-
-- `operator` = control plane client (CLI/UI/automation).
-- `node` = capability host (camera/screen/canvas/system.run).
-
-### Scopes (operator)
-
-Common scopes:
-
-- `operator.read`
-- `operator.write`
-- `operator.admin`
-- `operator.approvals`
-- `operator.pairing`
-
-### Caps/commands/permissions (node)
-
-Nodes declare capability claims at connect time:
-
-- `caps`: high-level capability categories.
-- `commands`: command allowlist for invoke.
-- `permissions`: granular toggles (e.g. `screen.record`, `camera.capture`).
-
-The Gateway treats these as **claims** and enforces server-side allowlists.
-
-## Presence
-
-- `system-presence` returns entries keyed by device identity.
-- Presence entries include `deviceId`, `roles`, and `scopes` so UIs can show a single row per device
-  even when it connects as both **operator** and **node**.
-
-### Node helper methods
-
-- Nodes may call `skills.bins` to fetch the current list of skill executables
-  for auto-allow checks.
-
-## Exec approvals
-
-- When an exec request needs approval, the gateway broadcasts `exec.approval.requested`.
-- Operator clients resolve by calling `exec.approval.resolve` (requires `operator.approvals` scope).
-
-## Versioning
-
-- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.
-- Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches.
-- Schemas + models are generated from TypeBox definitions:
-  - `pnpm protocol:gen`
-  - `pnpm protocol:gen:swift`
-  - `pnpm protocol:check`
-
-## Auth
-
-- If `SYMI_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
-  must match or the socket is closed.
-- After pairing, the Gateway issues a **device token** scoped to the connection
-  role + scopes. It is returned in `hello-ok.auth.deviceToken` and should be
-  persisted by the client for future connects.
-- Device tokens can be rotated/revoked via `device.token.rotate` and
-  `device.token.revoke` (requires `operator.pairing` scope).
-
-## Device identity + pairing
-
-- Nodes should include a stable device identity (`device.id`) derived from a
-  keypair fingerprint.
-- Gateways issue tokens per device + role.
-- Pairing approvals are required for new device IDs unless local auto-approval
-  is enabled.
-- **Local** connects include loopback and the gateway host’s own tailnet address
-  (so same‑host tailnet binds can still auto‑approve).
-- All WS clients must include `device` identity during `connect` (operator + node).
-  Control UI can omit it **only** when `gateway.controlUi.dangerouslyDisableDeviceAuth`
-  is enabled for break-glass use.
-- Non-local connections must sign the server-provided `connect.challenge` nonce.
-
-## TLS + pinning
-
-- TLS is supported for WS connections.
-- Clients may optionally pin the gateway cert fingerprint (see `gateway.tls`
-  config plus `gateway.remote.tlsFingerprint` or CLI `--tls-fingerprint`).
-
-## Scope
-
-This protocol exposes the **full gateway API** (status, channels, models, chat,
-agent, sessions, nodes, approvals, etc.). The exact surface is defined by the
-TypeBox schemas in `src/gateway/protocol/schema.ts`.