kenaz 0.0.0-stage → 0.3.2

package/core/dev/specs/agent-connect/history/FLOWPIX_bridge_CONTRACT.md

@@ -0,0 +1,642 @@
+# bridge HTTP contract v1 (TASK_96)
+
+Field names here are the wire contract -- backend/image_generation.py and
+backend/text_generation.py (the bridge's only clients, over stdlib
+`urllib.request`) and this document must never drift apart. Base URL
+defaults to `http://127.0.0.1:8790`, overridable via `GAMEASSET_BRIDGE_URL`
+on the backend side and `GAMEASSET_BRIDGE_HOST` / `GAMEASSET_BRIDGE_PORT` on
+the bridge side.
+
+## `GET /health`
+
+```json
+{
+  "ok": true,
+  "bridge_version": "1.0.0",
+  "default_provider": "codex",
+  "providers": [
+    {"id": "codex", "available": true, "detail": "codex 0.153.4, Logged in using ChatGPT; transport=appserver; usage 34% of 10080min window, resets 2026-09-14T08:33:13+00:00"},
+    {"id": "openai", "available": false, "detail": "OPENAI_API_KEY environment variable is not set"}
+  ]
+}
+```
+
+- `codex`'s `available` = `codex --version` exits 0 AND `codex login status`
+  reports `Logged in` -- independent of which transport is configured (both
+  need the same logged-in CLI).
+- `openai`'s `available` = `OPENAI_API_KEY` has a non-empty value.
+- `codex`'s `detail` (TASK_98 R5) always appends `; transport=<appserver|exec>`
+  (`GAMEASSET_BRIDGE_CODEX_TRANSPORT`, default `appserver`); once at least
+  one `appserver`-transport call has completed and cached an
+  `account/rateLimits/updated` notification, it further appends `; usage
+  <usedPercent>% of <windowDurationMins>min window, resets <ISO time>`. The
+  usage suffix is absent before any such call, and never appears for the
+  `exec` transport (which has no persistent connection to receive the
+  notification on).
+
+## `POST /v1/image`
+
+Request:
+
+```json
+{
+  "provider": "codex",
+  "prompt": "a three-quarter view of the attached garment",
+  "size": "1024x1024",
+  "quality": "medium",
+  "reference_images": ["<base64 PNG>", "..."]
+}
+```
+
+`provider` is optional -- omit it (or send `null`) to let the bridge decide
+(see "Provider selection" below).
+
+Response (200):
+
+```json
+{
+  "image_png_b64": "<base64 PNG>",
+  "width": 1024,
+  "height": 1024,
+  "provider": "codex",
+  "elapsed_ms": 48213,
+  "meta": {"thread_id": "01a07574-...", "transport": "appserver", "rate_limits": {"...": "..."}}
+}
+```
+
+`meta` is provider-specific and best-effort -- callers must not depend on
+any particular key being present. For the `codex` provider (TASK_98 R1/R5):
+
+- `thread_id` -- the (ephemeral) codex thread this call ran in, both
+  transports.
+- `transport` -- `"appserver"` or `"exec"`, whichever transport actually
+  ran this call. When `GAMEASSET_BRIDGE_CODEX_TRANSPORT=appserver` (the
+  default) but the app-server subprocess could not be spawned or never
+  became healthy within 10s, THIS SINGLE CALL falls back to `exec`
+  automatically (R6) -- `transport` reads `"exec"` and an additional
+  `fallback_reason` key explains why. This is a same-provider transport
+  fallback, not the silent `codex`-to-`openai` provider substitution R3
+  forbids elsewhere in this document.
+- `rate_limits` -- present only for the `appserver` transport, only once at
+  least one `account/rateLimits/updated` notification has been received
+  (the same object surfaced in `GET /health`'s usage summary, see above).
+
+## `POST /v1/text`
+
+Request:
+
+```json
+{
+  "provider": null,
+  "prompt": "describe this garment in under 60 words",
+  "system": "",
+  "model": "gpt-5.6-sol",
+  "max_output_tokens": 4096,
+  "reasoning_effort": "auto",
+  "reference_images": ["<base64 PNG>"]
+}
+```
+
+Response (200):
+
+```json
+{
+  "text": "...",
+  "provider": "openai",
+  "elapsed_ms": 3120,
+  "meta": {"model": "gpt-5.6-sol"}
+}
+```
+
+## Provider selection (R3)
+
+1. `request.provider`, if given explicitly.
+2. `GAMEASSET_BRIDGE_DEFAULT_PROVIDER` environment variable, if set.
+3. `'codex'`.
+
+If the selected provider is not registered, or registered but its `probe()`
+reports `available: false`, the bridge answers `422 provider_unavailable`.
+**It never silently substitutes a different provider** -- a user who asked
+for (or defaulted to) their ChatGPT subscription and got a silent fallback
+to the API-key provider would be burning paid API credits without knowing
+it.
+
+## Errors
+
+Every non-2xx response is:
+
+```json
+{"error": {"code": "provider_unavailable" | "provider_failed" | "provider_timeout" | "invalid_request", "message": "..."}}
+```
+
+| HTTP status | `code`                | Meaning |
+|---|---|---|
+| 422 | `provider_unavailable` | Unknown provider id, or the selected provider's `probe()` failed. |
+| 422 | `invalid_request`      | Malformed request body (e.g. a `reference_images` entry that isn't valid base64). |
+| 502 | `provider_failed`      | The provider ran but the generation itself failed (process error, empty response, moderation refusal, ...). |
+| 504 | `provider_timeout`     | The provider exceeded its own timeout ceiling (image: 300s, text: 180s for the codex provider; the openai provider's SDK client is configured with a 180s timeout for both). |
+
+`message` never contains `OPENAI_API_KEY` or any other secret/token value.
+
+## CORS (R10)
+
+Allowed origins: `GAMEASSET_BRIDGE_ALLOWED_ORIGINS` (comma-separated),
+default `http://localhost:5173,http://127.0.0.1:5173`. Every preflight
+(`OPTIONS`) response additionally carries
+`Access-Control-Allow-Private-Network: true` (Chrome's Private Network
+Access check) -- header only, no relay/queueing logic; a future
+cloud-hosted page proxying through this bridge is a separate card.
+
+---
+
+# Agent hub v1 (TASK_99)
+
+Turns the bridge into a local relay between a CLI agent (Codex / Claude
+Code) and the FlowPix canvas tab(s) the user has open in their browser. The
+bridge never touches the backend's saved-workflow API for any of this --
+every tool call below acts on a tab's LIVE, possibly-unsaved, in-page graph
+(the page-side executor is a separate card; this document is its contract).
+
+Implementation: `bridge/agent_hub/hub.py` (session registry + addressing +
+request/response relay), `bridge/agent_hub/auth.py` (token + `/mcp` guard),
+`bridge/agent_hub/tools.py` (the MCP tool set below), wired into
+`bridge/main.py`.
+
+## `/mcp` -- CLI agent entry point
+
+A streamable-HTTP MCP server (python `mcp>=2.1`, `MCPServer`), mounted into
+this same FastAPI app on the same port (8790 by default). Every request
+must carry `Authorization: Bearer <token>`, or the guard middleware answers
+before the request reaches MCP:
+
+| Condition | Response |
+|---|---|
+| `Origin` header present at all | `403 {"error":{"code":"forbidden","message":"..."}}` -- this path is for local non-browser programs only; a real browser page always sends `Origin` cross-origin. |
+| Missing/invalid `Authorization: Bearer <token>` | `401 {"error":{"code":"unauthorized","message":"..."}}` |
+
+**Token** resolution (`bridge/agent_hub/auth.get_agent_token`): env var
+`GAMEASSET_BRIDGE_AGENT_TOKEN`, else `storage/bridge/agent_token.txt`
+(created with a fresh 32-hex-char token on first read if neither exists).
+Never logged, never included in any error message.
+
+At real ASGI startup the bridge prints three ready-to-paste setup steps
+(TASK_102 -- a two-line banner that never told the user to set
+`FLOWPIX_MCP_TOKEN` produced codex's own "Environment variable
+FLOWPIX_MCP_TOKEN ... is not set" error the moment the user tried step 2):
+
+```
+1) 設定 token 環境變數
+   PowerShell: setx FLOWPIX_MCP_TOKEN "<token>"
+   bash:       export FLOWPIX_MCP_TOKEN="<token>"
+2) 接上 Codex CLI
+   PowerShell: codex mcp add flowpix --url http://127.0.0.1:<port>/mcp --bearer-token-env-var FLOWPIX_MCP_TOKEN
+   bash:       codex mcp add flowpix --url http://127.0.0.1:<port>/mcp --bearer-token-env-var FLOWPIX_MCP_TOKEN
+3) 接上 Claude Code
+   PowerShell: claude mcp add --transport http flowpix http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"
+   bash:       claude mcp add --transport http flowpix http://127.0.0.1:<port>/mcp --header 'Authorization: Bearer <token>'
+```
+
+Shell correctness (TASK_102 R4): single quotes are NOT shell quoting in
+cmd.exe or PowerShell -- pasting the old single-quoted `claude mcp add`
+line there sent claude a literal `Bearer` argument with the quotes and
+token stripped off, and claude answered `Invalid header format: "Bearer".
+Expected format: "Header-Name: value"`. Double quotes ARE valid quoting in
+cmd.exe, PowerShell **and** bash/zsh/sh, so every `powershell` variant
+above uses double quotes (safe to paste into cmd.exe too); only the `bash`
+variant still uses single quotes.
+
+**Do not use `--dangerously-bypass-approvals-and-sandbox` for normal use.**
+It exists only so this card's own automated test (AC5) can drive `codex
+exec` non-interactively against a throwaway fake canvas and an empty
+directory; a real CLI agent session should let its OWN approval mechanism
+gate `run_workflow` (see below) -- the bridge does not gate it a second
+time.
+
+**Client timeout trap (TASK_106)**: a python `mcp` client built by wrapping
+its own `httpx2.AsyncClient(headers={"Authorization": ...})` for the Bearer
+header -- instead of `mcp.shared._httpx_utils.create_mcp_http_client()`,
+which sets an SSE-friendly `read=300s` -- silently inherits `httpx2`'s bare
+default `Timeout(5.0)`. Any tool call whose SSE response takes longer than
+5s to arrive (e.g. `get_output`, whose own server-side timeout is 60s --
+see the `canvas_timeout` row in the Errors table below) then gets its
+connection torn down by the CLIENT itself, surfacing as `mcp`'s own
+"SSE stream ended without a response" -- indistinguishable, from the
+agent's side, from the bridge actually dropping the response. Any client
+constructed here (or in a script driving this bridge) that adds its own
+`headers=` MUST also pass an explicit `timeout=httpx2.Timeout(30.0,
+read=900.0)` (or otherwise route through `create_mcp_http_client`) so a
+long-running tool's own timeout error (`canvas_timeout`) has a chance to
+reach the client before the client's own read timeout does. (TASK_107:
+`run_workflow` itself no longer runs long enough to hit this trap -- it now
+answers as soon as the job is accepted, same shape as a quick edit -- but
+the trap still applies to any tool whose SSE response can legitimately take
+more than 5s, `get_output` included.)
+
+## `GET /agent/setup`
+
+CORS-scoped like every other non-`/mcp` route (`GAMEASSET_BRIDGE_ALLOWED_ORIGINS`).
+Feeds the editor's connection panel:
+
+```json
+{
+  "mcp_url": "http://127.0.0.1:8790/mcp",
+  "token": "<32 hex chars>",
+  "steps": [
+    {
+      "id": "set_token",
+      "title": "設定 token 環境變數",
+      "powershell": "setx FLOWPIX_MCP_TOKEN \"<token>\"",
+      "bash": "export FLOWPIX_MCP_TOKEN=\"<token>\"",
+      "note": "PowerShell（setx）：設定後只對之後開啟的新終端機生效，本視窗要重開；Bash（export）：只在目前這個 shell session 有效，要寫進 ~/.bashrc（或 ~/.zshrc）才能持久。"
+    },
+    {
+      "id": "codex_add",
+      "title": "接上 Codex CLI",
+      "powershell": "codex mcp add flowpix --url http://127.0.0.1:8790/mcp --bearer-token-env-var FLOWPIX_MCP_TOKEN",
+      "bash": "codex mcp add flowpix --url http://127.0.0.1:8790/mcp --bearer-token-env-var FLOWPIX_MCP_TOKEN"
+    },
+    {
+      "id": "claude_add",
+      "title": "接上 Claude Code",
+      "powershell": "claude mcp add --transport http flowpix http://127.0.0.1:8790/mcp --header \"Authorization: Bearer <token>\"",
+      "bash": "claude mcp add --transport http flowpix http://127.0.0.1:8790/mcp --header 'Authorization: Bearer <token>'"
+    }
+  ],
+  "commands": {
+    "codex": "codex mcp add flowpix --url http://127.0.0.1:8790/mcp --bearer-token-env-var FLOWPIX_MCP_TOKEN",
+    "claude_code": "claude mcp add --transport http flowpix http://127.0.0.1:8790/mcp --header \"Authorization: Bearer <token>\""
+  },
+  "connected_canvases": [
+    {"session_id": "...", "tab_id": "...", "workflow_name": "...", "workflow_id": null, "dirty": false, "running": false}
+  ]
+}
+```
+
+`steps` (TASK_102) is the panel's actual data source -- an ordered array,
+`set_token` first, with the token already substituted into every command
+(nothing left for the user to fill in themselves). `commands` is a legacy
+field kept for backward compatibility (TASK_100); `claude_code` there was
+switched to the same double-quoted form as `steps.claude_add.powershell`
+(TASK_102 R4) since double quotes work in every shell this field might be
+pasted into.
+
+## `/ws/canvas` -- FlowPix tab entry point
+
+A WebSocket endpoint. One connection per browser tab; the page connects,
+not the bridge. Origin is checked BEFORE `accept()`:
+
+- Origin missing, or not in `GAMEASSET_BRIDGE_ALLOWED_ORIGINS` -> the
+  connection is accepted then immediately closed with code `1008` (policy
+  violation) -- no `welcome` is ever sent. (An equivalent pre-accept HTTP
+  403 denial is also acceptable to a client; the bridge currently always
+  uses accept-then-close because it does not depend on the ASGI server
+  advertising the websocket-denial-response extension.)
+- Origin allowed -> accepted, and the tab must send `hello` as its first
+  message.
+
+**Handshake:**
+
+```
+tab -> bridge: {"type": "hello", "tab_id": "<string>", "workflow_name": "<string>", "workflow_id": "<string>|null", "client_version": "<string>", "page_id": "<string>|null"}
+bridge -> tab: {"type": "welcome", "session_id": "<string>"}
+```
+
+`page_id` (TASK_103, optional) identifies which BROWSER PAGE this tab
+belongs to -- every tab a single page opens (see `create_canvas` below)
+sends the SAME `page_id` in its own hello (AgentBridgeClient.ts computes it
+once, module-level, and every AgentBridgeClient instance on that page reads
+it). Omitted/`null` is accepted (an older client, or a test fixture) and
+simply never groups with anything.
+
+Anything other than `{"type": "hello", ...}` as the first message closes
+the connection (code `1008`) without a `welcome`.
+
+**Re-addressing** (the tab changed which workflow it shows, without
+reconnecting):
+
+```
+tab -> bridge: {"type": "state", "workflow_name": "<string>", "workflow_id": "<string>|null", "dirty": <bool>, "running": <bool>}
+```
+
+Each field is optional and merged into the session (omitted fields keep
+their previous value).
+
+One session per connection; a session is removed the instant its
+connection closes (any tool call still in flight for it fails immediately
+with `canvas_disconnected` instead of waiting out its timeout).
+
+## Tool-call relay protocol (R4)
+
+```
+bridge -> tab: {"type": "call", "request_id": "<string>", "tool": "<string>", "args": {...}}
+tab -> bridge: {"type": "result", "request_id": "<string>", "ok": true, "result": <any>}
+             | {"type": "result", "request_id": "<string>", "ok": false, "error": {"code": "<string>", "message": "<string>"}}
+```
+
+- `request_id` is a fresh random id per call (never reused), so multiple
+  calls to the same tab may be in flight concurrently; the bridge matches
+  each `result` back to its own caller by `request_id` alone (never "the
+  most recent call").
+- Timeout: 30s for every tool except `get_output` (60s). On timeout the
+  bridge answers the MCP caller with `canvas_timeout` (see Errors below);
+  it does NOT resend the call, and a result that arrives after the timeout
+  is silently dropped.
+- `args` never includes `workflow` -- that field only selects WHICH tab
+  the call is delivered to (see Addressing below); the tab already knows
+  its own identity.
+
+## MCP tool set v1
+
+Every tool's first argument is `workflow: str` (a `workflow_name` or a
+`session_id` -- see Addressing) EXCEPT `list_canvases` (takes none) and
+`create_canvas` (takes `name: str` instead -- there is no canvas yet to
+address).
+`args` sent to the tab is exactly the tool's OTHER arguments, as shown per
+tool below.
+
+| Tool | Args to tab | Result (from tab, via MCP) |
+|---|---|---|
+| `list_canvases()` | -- (not forwarded; answered by the bridge itself) | `[{"session_id", "tab_id", "workflow_name", "workflow_id", "dirty", "running", "page_id"}, ...]` |
+| `create_canvas(name)` | `{"name"}` -- forwarded to the MOST RECENTLY CONNECTED session (see below), not to an addressed `workflow` | `{"session_id", "tab_id", "workflow_name"}` for the BRAND-NEW tab |
+| `focus_canvas(workflow)` | `{}` | `{"tab_id", "workflow_name"}` |
+| `get_canvas(workflow)` | `{}` | `{"nodes": [{"id","type","params","position","status","error"}, ...], "edges": [...]}` |
+| `list_node_types(workflow)` | `{}` | `[{"type_id","display_name","inputs","outputs","params": [{"name","type","default","options"?,"min"?,"max"?}]}]` |
+| `add_node(workflow, type_id, params=None, position=None)` | `{"type_id","params","position"}` | `{"node_id": "<string>"}` |
+| `connect_nodes(workflow, source_node, source_port, target_node, target_port)` | `{"source_node","source_port","target_node","target_port"}` | `{}` (or any tab-defined ack) |
+| `set_params(workflow, node_id, params)` | `{"node_id","params"}` | `{}` |
+| `delete_node(workflow, node_id)` | `{"node_id"}` | `{}` |
+| `save_workflow(workflow)` | `{}` | `{"workflow_id": "<string>"}` |
+| `run_workflow(workflow, ignore_cache=False)` (TASK_107: returns as soon as the job is ACCEPTED, not when it finishes -- poll `get_job` for the rest) | `{"ignore_cache"}` | `{"job_id": "<string>"}` |
+| `get_job(workflow, job_id)` | `{"job_id"}` | `{"status": "<string>", "nodes": {"<node_id>": {"status","error"}}}` |
+| `get_output(workflow, node_id, port=None)` | `{"node_id","port"}` | see below |
+
+**`get_output`'s result shape from the tab** (TN5 -- the ONLY tool whose
+tab-side result is itself typed, because the bridge must convert it into
+real MCP content, not just relay JSON):
+
+```json
+{"kind": "image", "mime_type": "image/png", "data_b64": "<base64 PNG>"}
+```
+or
+```json
+{"kind": "text", "text": "<string>"}
+```
+
+The bridge turns `kind:"image"` into MCP `ImageContent(type="image",
+mimeType, data=<the same base64>)` -- the agent sees a real image, never a
+base64 string dressed up as text. `kind:"text"` becomes the tool's plain
+text result.
+
+## `create_canvas` protocol (TASK_103 R1/TN2)
+
+`create_canvas` has no `workflow` to address by -- there is no canvas yet.
+Instead:
+
+1. The bridge picks the single MOST RECENTLY CONNECTED `/ws/canvas` session
+   (regardless of `workflow_name`/`page_id`) and forwards `{"tool":
+   "create_canvas", "args": {"name": name}}` to it, exactly like any other
+   tool call. Zero sessions connected at all -> `no_canvas` (the bridge
+   cannot open a browser tab on its own).
+2. That tab opens a brand-new, empty tab named `name` and switches its own
+   UI to it, then answers the call with `{"tab_id": "<the new tab's id>"}`.
+   A tab named `name` already open -> the tab answers `{"ok": false,
+   "error": {"code": "canvas_exists", "message": "..."}}` instead (passed
+   through to the agent like any other tab-reported error -- see Errors).
+3. The NEW tab's own `AgentBridgeClient` connects and sends its own `hello`
+   (`tab_id` = the id from step 2, `page_id` = the SAME page_id as every
+   other tab on that page) like any ordinary tab open.
+4. The bridge waits (`GAMEASSET_BRIDGE_CREATE_CANVAS_HELLO_TIMEOUT_S`,
+   default 5s) for that exact `tab_id` to register a session, then answers
+   the MCP call with `{"session_id", "tab_id", "workflow_name"}` for the
+   NEW session. No hello within the window -> `canvas_timeout`.
+
+## Addressing (R6)
+
+Applies to every tool that takes a `workflow` argument -- i.e. every tool
+except `list_canvases` and `create_canvas` (see above, its own protocol
+section). `focus_canvas` uses this SAME resolution, unlike `create_canvas`.
+
+`workflow` is resolved against every currently-connected `/ws/canvas`
+session, in this order:
+
+1. **Zero canvases connected at all** -> `no_canvas`, regardless of what
+   `workflow` was. The agent must ask the human to open FlowPix and this
+   workflow in their browser -- it must NEVER fall back to editing the
+   backend's saved workflow file.
+2. `workflow` equals a connected session's `session_id` exactly -> that
+   session (no name lookup needed).
+3. Otherwise, exact match against every connected session's
+   `workflow_name`:
+   - 0 matches -> `canvas_not_found`, message lists the `workflow_name`s
+     that ARE currently connected.
+   - 1 match -> that session.
+   - >1 matches (two tabs share a workflow name) -> `ambiguous_canvas`,
+     message lists the matching sessions' `session_id`s -- retry with one
+     of those as `workflow` (case 2).
+
+## Errors
+
+Every failure raised by a tool is an MCP tool error (`is_error: true`)
+whose text content IS `json.dumps({"code": "<code>", "message": "<string>"})`
+-- but **what the calling agent actually receives is not that raw JSON
+string**. The `mcp` python SDK (and, empirically, every client built on it)
+prefixes a tool error's text with `Error executing tool <name>: ` before the
+JSON object, e.g.:
+
+```
+Error executing tool set_params: {"code": "invalid_params", "message": "unknown param 'sizee' for text_prompt"}
+```
+
+**A reader (TASK_100's frontend executor included, and any agent-side code
+parsing this) must locate and parse the `{...}` object embedded in the
+text, never `json.loads()` the whole string** -- the exact wording of the
+`Error executing tool <name>: ` prefix is the MCP SDK's own, not this
+bridge's, and is not part of this contract (do not depend on its exact
+text, only on there being a JSON object with `code`/`message` keys
+somewhere in the string). `bridge/agent_hub/tools.py`'s tests locate it
+with a substring check (`'"code": "<code>"' in text`), not a full parse.
+
+| `code` | Meaning |
+|---|---|
+| `no_canvas` | No `/ws/canvas` session is connected at all. |
+| `canvas_not_found` | `workflow` matched no connected `session_id` or `workflow_name`. |
+| `ambiguous_canvas` | `workflow` matched more than one connected `workflow_name`. |
+| `canvas_timeout` | The addressed tab did not send a `result` within the call's timeout (30s; 60s for `get_output`; 30s for `run_workflow` too, TASK_107 -- its page-side handler now answers as soon as the job is ACCEPTED, the same shape/duration as a quick edit, so it shares the plain default value even though it keeps its own override knob; overridable in tests via `GAMEASSET_BRIDGE_CALL_TIMEOUT_S` / `GAMEASSET_BRIDGE_GET_OUTPUT_TIMEOUT_S` / `GAMEASSET_BRIDGE_RUN_WORKFLOW_TIMEOUT_S`). |
+| `canvas_disconnected` | The tab's connection closed (or a send to it failed) while a call was in flight. |
+| `no_output` | (tab-reported) the node has not produced output yet. |
+| `tool_failed` | Generic fallback ONLY if a tab's `{"ok": false, "error": {...}}` result is missing `code`/`message` entirely. |
+| *(tab-defined)* | Any other `code`/`message` a tab's `{"ok": false, "error": {...}}` result reports (e.g. `invalid_params`, `invalid_connection`) is passed through UNCHANGED -- this is how the agent learns WHY an edit was rejected, not just that it was. Covered by `test_tab_reported_error_passes_through` and mutation arm M7 (cutting this passthrough is caught). |
+
+Never falls back to the backend's saved-workflow API for any of these --
+that would silently act on stale data instead of surfacing the error to
+the agent (R6).
+
+---
+
+# Relay v1 (TASK_105)
+
+**This section is the wire contract Kenaz's Rust implementation targets** --
+see `FEATURE_REQUEST_kenaz-agent-hub_2026-09-07.md` (K1-K8) in the kenaz-core
+repo for the product-level feature list this protocol serves. Field names
+below MUST NOT drift between the three spike implementations
+(`spikes/relay_spike/relay.mjs`, `bridge/agent_relay_client.py`,
+`backend/jobs.py`'s `RelaySiteClient`) without updating this document first
+-- `test_relay_contract.py` asserts all three agree with the JSON examples
+here (AC6).
+
+## Why this exists (R4/K2)
+
+The cloud website/backend never holds the user's AI credentials. Instead a
+website's "連接 Kenaz" button opens a `kenaz://connect?...` deep link that
+wakes the user's own local Kenaz; Kenaz then dials OUT to a relay server
+(firewall-friendly -- the user's machine never needs an inbound port), and
+every AI generation the website asks for is forwarded through that relay to
+Kenaz, which runs it against the user's own ChatGPT/Codex subscription and
+asks the user to approve it. Web3 "connect wallet" UX: connect once, approve
+per action (or "always allow this site").
+
+## Transport
+
+One WS/WSS endpoint per relay process (this spike: `ws://127.0.0.1:<port>/ws`;
+a real deployment would put this behind TLS). Every frame is UTF-8 JSON, one
+JSON object per frame, with at least a `"type"` string field. Most also carry
+`"request_id"` (string) that pairs a request with its response(s); a handful
+of unsolicited pushes carry `"request_id": null`.
+
+**Size cap (R2)**: any single frame whose UTF-8 byte length exceeds
+**262144 bytes (256 KiB)** is rejected by the relay without being forwarded
+-- this is why images and other large payloads travel as object-storage URLs
+(`reference_images` entries, a `result.payload.url`), never inline base64. If
+the oversized frame carried a `request_id`, the relay answers the SENDER
+(not the intended recipient) with `{"type":"error","request_id":<id>,
+"error":{"code":"payload_too_large","message":"<n> bytes exceeds the 256KB
+relay limit"}}`; a `request_id`-less oversized frame is simply dropped and
+logged. The relay logs every frame's direction/type/byte length (JSONL) so a
+run can prove after the fact that nothing crossed the cap (AC1).
+
+## Roles
+
+- **site** -- the cloud backend acting on behalf of one website/session
+  (`backend/jobs.py`'s `RelaySiteClient` in this spike; a real deployment
+  would run this inside FlowPix's own backend process).
+- **agent** -- Kenaz (or, in this spike, `bridge/agent_relay_client.py`
+  standing in as a "fake Kenaz").
+
+A connection's role is fixed by its FIRST message: `site.hello` makes it a
+site connection; `pair.begin` makes it an agent connection (an agent has no
+separate hello step -- `pair.begin` serves both purposes).
+
+## 1. Site handshake
+
+```json
+site -> relay: {"type": "site.hello", "request_id": "<id>", "origin": "<site origin, e.g. https://flowpix.app>"}
+relay -> site: {"type": "site.ready", "request_id": "<id>", "site_session_id": "<string>"}
+```
+
+## 2. Pairing token (one-time, 60s TTL, origin-bound)
+
+```json
+site -> relay: {"type": "token.mint", "request_id": "<id>", "agent": "claude" | "codex" | null}
+relay -> site: {"type": "token.minted", "request_id": "<id>", "token": "<32 hex chars>", "ttl_s": 60}
+```
+
+The token is bound to `(site_session_id, origin, agent)` at mint time and is
+**consumed the instant a `pair.begin` referencing it is processed** --
+regardless of whether that attempt succeeds -- so a token can only ever be
+tried once, full stop (AC3: a stolen token cannot be retried against a
+different origin after a first failed guess). The site backend builds the
+deep link from this response:
+
+```
+kenaz://connect?site=<url-encoded origin>&token=<token>&relay=<url-encoded relay ws url>&agent=<claude|codex>
+```
+
+## 3. Agent pairing
+
+```json
+agent -> relay: {"type": "pair.begin", "request_id": "<id>", "token": "<token>", "site_origin": "<origin>"}
+relay -> agent: {"type": "pair.ok", "request_id": "<id>", "session_credential": "<string>", "site_origin": "<origin>"}
+             | {"type": "pair.denied", "request_id": "<id>", "error": {"code": "token_invalid" | "token_expired" | "token_already_used" | "origin_mismatch" | "relay_unavailable", "message": "<string>"}}
+relay -> site (pair.ok only): {"type": "agent.connected", "request_id": null, "agent_session_id": "<string>"}
+```
+
+`origin_mismatch`: `site_origin` in `pair.begin` does not equal the origin the
+token was minted against. `relay_unavailable`: the token's site session
+already disconnected.
+
+## 4. Status push (agent -> site, unsolicited, forwarded verbatim)
+
+```json
+{"type": "agent.status", "request_id": null, "codex_logged_in": true, "rate_limits": null, "approval_mode": "allow_all" | "ask_once" | "deny"}
+```
+
+## 5. Generation requests (site -> agent, forwarded)
+
+```json
+{"type": "generate_image", "request_id": "<id>", "prompt": "<string>", "size": "<string>", "quality": "<string>", "reference_images": ["<url>", "..."]}
+{"type": "generate_text", "request_id": "<id>", "prompt": "<string>", "system": "<string>", "model": "<string>", "max_output_tokens": <int>, "reasoning_effort": "<string>", "reference_images": ["<url>", "..."]}
+```
+
+`reference_images` are object-storage URLs (this spike: `blobstore.mjs`'s
+fake presigned URLs), never inline base64 -- exactly why the 256KB cap above
+is workable at all. FlowPix's canvas tool set (`list_canvases`...
+`focus_canvas`, "Agent hub v1" above) is a SEPARATE path for a local CLI
+agent and never travels over the relay.
+
+## 6. Approval (agent -> site, forwarded, same `request_id` as the generate_* call)
+
+```json
+{"type": "approval.pending", "request_id": "<id>", "summary": "<string>"}
+{"type": "approval.resolved", "request_id": "<id>", "decision": "allow" | "deny"}
+```
+
+The site shows "等待你在 Kenaz 允許" for `request_id`s between `.pending` and
+`.resolved`/`result` (AC2).
+
+## 7. Result (agent -> site, forwarded, same `request_id`)
+
+```json
+{"type": "result", "request_id": "<id>", "ok": true, "payload": {...}}
+{"type": "result", "request_id": "<id>", "ok": false, "error": {"code": "<code>", "message": "<string>"}}
+```
+
+`payload` for `generate_image`: `{"url": "<blobstore url>", "width": <int>,
+"height": <int>, "provider": "codex", "elapsed_ms": <int>, "meta": {...}}`.
+`payload` for `generate_text`: `{"text": "<string>", "provider": "codex",
+"elapsed_ms": <int>, "meta": {...}}`.
+
+Error codes (`error.code`): `not_logged_in`, `usage_limit_exceeded` (carries
+an additional `resetsAt` field), `denied`, `timeout`, `relay_unavailable`,
+`payload_too_large`, `token_invalid`, `token_expired`, `token_already_used`,
+`origin_mismatch`.
+
+## 8. Agent launch (agent -> site, forwarded -- R7/K8)
+
+Announces that Kenaz, having just paired via a deep link carrying
+`agent=claude|codex`, is starting that CLI headless with FlowPix's `/mcp`
+endpoint (this same bridge's Agent hub v1, above) pre-configured so the CLI
+can `list_canvases` / `add_node` on the canvas the deep link named, without
+the relay itself being involved in that traffic at all.
+
+```json
+{"type": "agent.launch", "request_id": null, "agent": "claude" | "codex", "mode": "headless" | "interactive", "prompt": "<string>" | null}
+{"type": "agent.launched", "request_id": null, "agent": "claude" | "codex", "pid": <int> | null}
+{"type": "agent_unavailable", "request_id": null, "agent": "claude" | "codex", "reason": "<string>"}
+```
+
+## 9. Disconnect
+
+```json
+relay -> site: {"type": "agent.disconnected", "request_id": null}
+```
+Sent when the paired agent's connection closes. The site's `GET`-style status
+read (`backend/jobs.py`'s `get_kenaz_status()`) then reports `connected: false`
+again.
+
+## Security notes (R1/K2)
+
+Kenaz only ever makes an OUTBOUND connection to the relay -- no inbound port
+on the user's machine. Credentials (Codex/ChatGPT login) never leave the
+user's machine; only the generated image/text and metadata cross the relay.
+Each website origin gets its own pairing; nothing here lets one origin's
+pairing be reused by another.