kenaz 0.3.21 → 0.3.23

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

@@ -1,642 +0,0 @@
-# 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.