pipane 0.1.6 → 0.1.7

package/dist/server/shared/ws-protocol.js

@@ -1 +1,473 @@
-export {};
+/** Increment when a breaking WebSocket wire change is introduced. */
+export const WS_PROTOCOL_VERSION = 1;
+class ValidationFailure extends Error {
+    code;
+    constructor(code, path, message) {
+        super(`${path}: ${message}`);
+        this.code = code;
+    }
+}
+function fail(path, message, code = "invalid_message") {
+    throw new ValidationFailure(code, path, message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function record(value, path) {
+    if (!isRecord(value))
+        fail(path, "expected an object");
+    return value;
+}
+function string(value, path, allowEmpty = true) {
+    if (typeof value !== "string" || (!allowEmpty && value.length === 0)) {
+        fail(path, allowEmpty ? "expected a string" : "expected a non-empty string");
+    }
+    return value;
+}
+function optionalString(value, path) {
+    return value === undefined ? undefined : string(value, path);
+}
+function boolean(value, path) {
+    if (typeof value !== "boolean")
+        fail(path, "expected a boolean");
+    return value;
+}
+function integer(value, path) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        fail(path, "expected a non-negative safe integer");
+    }
+    return value;
+}
+function finiteNumber(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        fail(path, "expected a finite number");
+    return value;
+}
+function array(value, path) {
+    if (!Array.isArray(value))
+        fail(path, "expected an array");
+    return value;
+}
+function stringArray(value, path) {
+    return array(value, path).map((item, index) => string(item, `${path}[${index}]`));
+}
+function stringRecord(value, path) {
+    const source = record(value, path);
+    for (const [key, item] of Object.entries(source))
+        string(item, `${path}.${key}`);
+    return source;
+}
+function statusRecord(value, path) {
+    const source = record(value, path);
+    for (const [key, item] of Object.entries(source)) {
+        if (item !== "running" && item !== "done")
+            fail(`${path}.${key}`, "expected 'running' or 'done'");
+    }
+    return source;
+}
+function queuesRecord(value, path) {
+    const source = record(value, path);
+    for (const [key, item] of Object.entries(source))
+        stringArray(item, `${path}.${key}`);
+    return source;
+}
+function thinkingLevel(value, path) {
+    if (!["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(value))) {
+        fail(path, "expected a supported thinking level");
+    }
+    return value;
+}
+function compactModel(value, path) {
+    const model = record(value, path);
+    string(model.provider, `${path}.provider`, false);
+    string(model.modelId, `${path}.modelId`, false);
+    return model;
+}
+function wireModel(value, path) {
+    const model = record(value, path);
+    string(model.provider, `${path}.provider`, false);
+    const id = optionalString(model.id, `${path}.id`);
+    const modelId = optionalString(model.modelId, `${path}.modelId`);
+    if (!id && !modelId)
+        fail(path, "expected id or modelId");
+    return model;
+}
+function images(value, path) {
+    return array(value, path).map((item, index) => {
+        const image = record(item, `${path}[${index}]`);
+        if (image.type !== "image")
+            fail(`${path}[${index}].type`, "expected 'image'");
+        string(image.data, `${path}[${index}].data`);
+        string(image.mimeType, `${path}[${index}].mimeType`, false);
+        return image;
+    });
+}
+function optionalCommandFields(command, path) {
+    if (command.thinkingLevel !== undefined)
+        thinkingLevel(command.thinkingLevel, `${path}.thinkingLevel`);
+    if (command.controlRevision !== undefined)
+        integer(command.controlRevision, `${path}.controlRevision`);
+    if (command.images !== undefined)
+        images(command.images, `${path}.images`);
+}
+function validateVersion(message, path) {
+    if (message.protocolVersion !== WS_PROTOCOL_VERSION) {
+        const actual = message.protocolVersion === undefined ? "missing" : JSON.stringify(message.protocolVersion);
+        fail(`${path}.protocolVersion`, `unsupported protocol version ${actual}; expected ${WS_PROTOCOL_VERSION}`, "unsupported_version");
+    }
+}
+function decodeJson(raw) {
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: {
+                code: "invalid_json",
+                message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+                requestId: null,
+                command: "parse",
+            },
+        };
+    }
+}
+function decodeFailure(value, failure, fallbackCommand) {
+    const source = isRecord(value) ? value : undefined;
+    const requestId = typeof source?.id === "string" ? source.id : null;
+    const command = typeof source?.type === "string" ? source.type : fallbackCommand;
+    const validation = failure instanceof ValidationFailure
+        ? failure
+        : new ValidationFailure("invalid_message", "$", failure instanceof Error ? failure.message : String(failure));
+    return {
+        ok: false,
+        error: {
+            code: validation.code,
+            message: validation.message,
+            requestId,
+            command,
+        },
+    };
+}
+export function decodeClientCommand(raw) {
+    const parsed = decodeJson(raw);
+    if (!parsed.ok)
+        return parsed;
+    const value = parsed.value;
+    try {
+        const command = record(value, "$command");
+        validateVersion(command, "$command");
+        string(command.id, "$command.id", false);
+        const type = string(command.type, "$command.type", false);
+        const sessionPath = () => string(command.sessionPath, "$command.sessionPath");
+        switch (type) {
+            case "install_pi":
+            case "get_available_models":
+            case "get_default_model":
+            case "get_session_statuses":
+            case "reload_processes":
+                break;
+            case "get_commands":
+                optionalString(command.sessionPath, "$command.sessionPath");
+                optionalString(command.cwd, "$command.cwd");
+                break;
+            case "subscribe_session":
+            case "abort":
+            case "hard_kill":
+            case "get_session_stats":
+                sessionPath();
+                break;
+            case "prompt":
+                sessionPath();
+                string(command.message, "$command.message");
+                optionalString(command.cwd, "$command.cwd");
+                compactModel(command.model, "$command.model");
+                optionalCommandFields(command, "$command");
+                break;
+            case "steer":
+                sessionPath();
+                string(command.message, "$command.message");
+                break;
+            case "remove_steering":
+                sessionPath();
+                integer(command.index, "$command.index");
+                break;
+            case "compact":
+                sessionPath();
+                optionalString(command.customInstructions, "$command.customInstructions");
+                break;
+            case "fork":
+                sessionPath();
+                string(command.entryId, "$command.entryId", false);
+                break;
+            case "fork_prompt":
+                sessionPath();
+                string(command.message, "$command.message");
+                compactModel(command.model, "$command.model");
+                optionalCommandFields(command, "$command");
+                break;
+            case "set_session_name":
+                sessionPath();
+                string(command.name, "$command.name");
+                break;
+            default:
+                fail("$command.type", `unknown command '${type}'`, "unknown_command");
+        }
+        return { ok: true, value: command };
+    }
+    catch (error) {
+        return decodeFailure(value, error, "unknown");
+    }
+}
+function validateSlashCommands(value, path) {
+    array(value, path).forEach((item, index) => {
+        const command = record(item, `${path}[${index}]`);
+        string(command.name, `${path}[${index}].name`, false);
+        optionalString(command.description, `${path}[${index}].description`);
+        if (!["extension", "prompt", "skill"].includes(String(command.source))) {
+            fail(`${path}[${index}].source`, "expected extension, prompt, or skill");
+        }
+        if (command.sourceInfo !== undefined)
+            record(command.sourceInfo, `${path}[${index}].sourceInfo`);
+        optionalString(command.location, `${path}[${index}].location`);
+        optionalString(command.path, `${path}[${index}].path`);
+    });
+}
+function validateSessionStats(value, path) {
+    const stats = record(value, path);
+    string(stats.sessionFile, `${path}.sessionFile`, false);
+    string(stats.sessionId, `${path}.sessionId`, false);
+    for (const field of ["userMessages", "assistantMessages", "toolCalls", "toolResults", "totalMessages"]) {
+        integer(stats[field], `${path}.${field}`);
+    }
+    const tokens = record(stats.tokens, `${path}.tokens`);
+    for (const field of ["input", "output", "cacheRead", "cacheWrite", "total"]) {
+        integer(tokens[field], `${path}.tokens.${field}`);
+    }
+    if (finiteNumber(stats.cost, `${path}.cost`) < 0)
+        fail(`${path}.cost`, "expected a non-negative number");
+    if (stats.contextUsage !== undefined) {
+        const context = record(stats.contextUsage, `${path}.contextUsage`);
+        if (context.tokens !== null)
+            integer(context.tokens, `${path}.contextUsage.tokens`);
+        integer(context.contextWindow, `${path}.contextUsage.contextWindow`);
+        if (context.percent !== null && finiteNumber(context.percent, `${path}.contextUsage.percent`) < 0) {
+            fail(`${path}.contextUsage.percent`, "expected a non-negative number or null");
+        }
+    }
+}
+function validateSuccessData(command, value, path) {
+    const data = record(value, path);
+    switch (command) {
+        case "install_pi":
+        case "subscribe_session":
+        case "steer":
+        case "remove_steering":
+        case "abort":
+        case "set_session_name":
+            break;
+        case "prompt":
+        case "fork_prompt":
+            string(data.newSessionPath, `${path}.newSessionPath`, false);
+            break;
+        case "hard_kill":
+            boolean(data.killed, `${path}.killed`);
+            if (data.reason !== undefined && data.reason !== "signal_failed" && data.reason !== "not_attached") {
+                fail(`${path}.reason`, "expected signal_failed or not_attached");
+            }
+            break;
+        case "compact":
+            break;
+        case "get_available_models":
+            array(data.models, `${path}.models`).forEach((model, index) => wireModel(model, `${path}.models[${index}]`));
+            break;
+        case "get_default_model":
+            if (data.model !== null)
+                wireModel(data.model, `${path}.model`);
+            thinkingLevel(data.thinkingLevel, `${path}.thinkingLevel`);
+            break;
+        case "get_session_statuses":
+            statusRecord(data.statuses, `${path}.statuses`);
+            break;
+        case "get_session_stats":
+            validateSessionStats(data, path);
+            break;
+        case "fork":
+            string(data.text, `${path}.text`);
+            boolean(data.cancelled, `${path}.cancelled`);
+            if (data.newSessionPath !== null)
+                string(data.newSessionPath, `${path}.newSessionPath`, false);
+            break;
+        case "get_commands":
+            validateSlashCommands(data.commands, `${path}.commands`);
+            break;
+        case "reload_processes":
+            integer(data.killed, `${path}.killed`);
+            integer(data.draining, `${path}.draining`);
+            break;
+    }
+}
+const CLIENT_COMMAND_TYPES = new Set([
+    "install_pi",
+    "subscribe_session",
+    "prompt",
+    "steer",
+    "remove_steering",
+    "abort",
+    "hard_kill",
+    "compact",
+    "get_available_models",
+    "get_default_model",
+    "get_session_statuses",
+    "get_session_stats",
+    "fork",
+    "fork_prompt",
+    "set_session_name",
+    "get_commands",
+    "reload_processes",
+]);
+function clientCommandType(value, path) {
+    const type = string(value, path, false);
+    if (!CLIENT_COMMAND_TYPES.has(type))
+        fail(path, `unknown response command '${type}'`, "unknown_message");
+    return type;
+}
+function validatePatches(value, path) {
+    array(value, path).forEach((item, index) => {
+        const patch = record(item, `${path}[${index}]`);
+        integer(patch.offset, `${path}[${index}].offset`);
+        integer(patch.deleteCount, `${path}[${index}].deleteCount`);
+        string(patch.insert, `${path}[${index}].insert`);
+    });
+}
+export function decodeServerMessage(raw) {
+    const parsed = decodeJson(raw);
+    if (!parsed.ok)
+        return parsed;
+    const value = parsed.value;
+    try {
+        const message = record(value, "$message");
+        validateVersion(message, "$message");
+        const type = string(message.type, "$message.type", false);
+        switch (type) {
+            case "response": {
+                const success = boolean(message.success, "$message.success");
+                if (success) {
+                    string(message.id, "$message.id", false);
+                    const command = clientCommandType(message.command, "$message.command");
+                    validateSuccessData(command, message.data, "$message.data");
+                }
+                else {
+                    if (message.id !== null)
+                        string(message.id, "$message.id", false);
+                    string(message.command, "$message.command", false);
+                    string(message.error, "$message.error", false);
+                    if (!["invalid_json", "invalid_message", "unsupported_version", "unknown_command", "unknown_message", "command_failed"].includes(String(message.code))) {
+                        fail("$message.code", "expected a protocol error code");
+                    }
+                }
+                break;
+            }
+            case "init":
+                statusRecord(message.sessionStatuses, "$message.sessionStatuses");
+                queuesRecord(message.steeringQueues, "$message.steeringQueues");
+                stringRecord(message.providerUsageStatuses, "$message.providerUsageStatuses");
+                break;
+            case "pi_install_required":
+                string(message.command, "$message.command", false);
+                boolean(message.installable, "$message.installable");
+                boolean(message.installing, "$message.installing");
+                string(message.message, "$message.message", false);
+                break;
+            case "session_status_change":
+                string(message.sessionPath, "$message.sessionPath", false);
+                if (message.status !== "running" && message.status !== "done")
+                    fail("$message.status", "expected running or done");
+                break;
+            case "provider_usage":
+                stringRecord(message.statuses, "$message.statuses");
+                break;
+            case "extension_status":
+                string(message.sessionPath, "$message.sessionPath", false);
+                stringRecord(message.statuses, "$message.statuses");
+                break;
+            case "session_sync":
+                string(message.sessionPath, "$message.sessionPath", false);
+                integer(message.revision, "$message.revision");
+                string(message.hash, "$message.hash", false);
+                if (message.op === "full") {
+                    string(message.data, "$message.data");
+                }
+                else if (message.op === "delta") {
+                    string(message.baseHash, "$message.baseHash", false);
+                    validatePatches(message.patches, "$message.patches");
+                }
+                else {
+                    fail("$message.op", "expected full or delta");
+                }
+                break;
+            case "control_state":
+                string(message.sessionPath, "$message.sessionPath", false);
+                if (message.controlRevision !== undefined)
+                    integer(message.controlRevision, "$message.controlRevision");
+                wireModel(message.model, "$message.model");
+                thinkingLevel(message.thinkingLevel, "$message.thinkingLevel");
+                break;
+            case "session_attached":
+                string(message.sessionPath, "$message.sessionPath", false);
+                optionalString(message.cwd, "$message.cwd");
+                optionalString(message.firstMessage, "$message.firstMessage");
+                break;
+            case "sessions_changed":
+                string(message.file, "$message.file");
+                break;
+            default:
+                fail("$message.type", `unknown server message '${type}'`, "unknown_message");
+        }
+        return { ok: true, value: message };
+    }
+    catch (error) {
+        return decodeFailure(value, error, "unknown");
+    }
+}
+export function decodeSessionStateJson(raw) {
+    const parsed = decodeJson(raw);
+    if (!parsed.ok)
+        return parsed;
+    const value = parsed.value;
+    try {
+        const state = record(value, "$session");
+        array(state.messages, "$session.messages").forEach((item, index) => {
+            const message = record(item, `$session.messages[${index}]`);
+            string(message.role, `$session.messages[${index}].role`, false);
+        });
+        boolean(state.isStreaming, "$session.isStreaming");
+        stringArray(state.pendingToolCalls, "$session.pendingToolCalls");
+        const timings = record(state.toolCallTimings, "$session.toolCallTimings");
+        for (const [toolCallId, value] of Object.entries(timings)) {
+            const timing = record(value, `$session.toolCallTimings.${toolCallId}`);
+            finiteNumber(timing.startedAt, `$session.toolCallTimings.${toolCallId}.startedAt`);
+            if (timing.completedAt !== undefined) {
+                finiteNumber(timing.completedAt, `$session.toolCallTimings.${toolCallId}.completedAt`);
+            }
+        }
+        if (state.model !== null)
+            compactModel(state.model, "$session.model");
+        thinkingLevel(state.thinkingLevel, "$session.thinkingLevel");
+        stringArray(state.steeringQueue, "$session.steeringQueue");
+        optionalString(state.error, "$session.error");
+        return { ok: true, value: state };
+    }
+    catch (error) {
+        return decodeFailure(value, error, "session_sync");
+    }
+}
+export function encodeClientCommand(payload, id) {
+    return JSON.stringify({ protocolVersion: WS_PROTOCOL_VERSION, id, ...payload });
+}
+export function encodeServerMessage(payload) {
+    return JSON.stringify({ protocolVersion: WS_PROTOCOL_VERSION, ...payload });
+}
+export function assertNever(value) {
+    throw new Error(`Unhandled protocol variant: ${JSON.stringify(value)}`);
+}

package/docs/protocol.md

@@ -0,0 +1,127 @@
+# pipane Protocol Contracts
+
+## Browser WebSocket protocol
+
+The shared contract lives in `src/shared/ws-protocol.ts`. Every browser/server message is a JSON object containing:
+
+- `protocolVersion`: currently `1`
+- `type`: a discriminant for exhaustive dispatch
+- `id`: required on client commands and correlated command responses
+
+The server rejects invalid JSON, unsupported versions, unknown commands, and invalid fields before command dispatch. Failures use a `response` envelope with a stable error `code`, a useful `error` message, and the request id when one could be recovered.
+
+### Client commands
+
+The v1 command union covers installation, session subscription, prompting and steering, steering removal, abort and hard kill, compaction, model and command discovery, session statuses and authoritative session statistics, fork and fork/prompt, session naming, and process reload.
+
+`WsAgentAdapter.send()` is generic over this union. Its result type is selected from `CommandResponseDataMap`, so a response for one command cannot be consumed as another command's data. The browser also checks that the response command matches the pending request before resolving it. Command discovery may include an active `sessionPath` or virtual-session `cwd`; the server uses that context so Pi returns the correct project-scoped prompts and skills.
+
+### Server messages
+
+The v1 server union covers:
+
+- command success and failure responses
+- initialization and Pi-install status
+- global session status changes
+- account and session extension statuses
+- session synchronization
+- effective model/thinking controls
+- newly attached sessions
+- session-directory change notifications
+
+All outbound production messages use `encodeServerMessage()`, which attaches the current protocol version. The browser validates the complete envelope before mutating client state and uses exhaustive dispatch.
+
+### Session revisions
+
+Every `session_sync` message includes a non-negative `revision`. Revisions increase when the authoritative serialized state changes. A full snapshot establishes a revision; each following delta must be the next revision. A gap causes the browser to discard its sync base and request a fresh authoritative snapshot.
+
+The existing hash and patch fields remain in v1. Revisions make ordering and recovery explicit without pre-empting the future semantic-update protocol.
+
+## Rendezvous, pairing, and connection trust
+
+The control-plane contract lives in `src/shared/rendezvous-protocol.ts` and is independently versioned by `RENDEZVOUS_PROTOCOL_VERSION`, currently `2`. The standalone rendezvous process exposes:
+
+- `/v2/rendezvous/backend` for persistent outbound backend registration, pairing control, and signaling
+- `/v2/rendezvous/browser` for one ticket-authorized browser/backend signaling route
+
+Every frame is validated JSON containing `protocolVersion` and a `type` discriminant. Rendezvous forwards trust metadata plus ICE descriptions/candidates only; application frames never pass through it.
+
+### Backend registration and ICE
+
+The server sends a fresh random `challenge`. A backend responds with `register_backend`, containing its P-256 public key, metadata, and an ES256 signature over the domain-separated challenge. Rendezvous derives `backendId` from the SHA-256 fingerprint of canonical SPKI bytes and replies with `registered`, its ticket-verification public key, and short-lived ICE server credentials. Backend identity and trust files are mode `0600` and survive restarts.
+
+The backend client reconnects its outbound WebSocket with bounded exponential backoff and repeats challenge authentication. STUN servers may be static. TURN credentials use coturn's REST convention: an expiring `timestamp:subject` username and HMAC-SHA1 credential; fresh backend credentials accompany each `connection_request` rather than expiring in a long-running peer manager. Browser and backend support relay-only ICE policy; deterministic E2E forces both peers through a local UDP TURN relay.
+
+Backend registration uses `PIPANE_RENDEZVOUS_URL` and optional `PIPANE_APP_URL`/`PIPANE_BACKEND_NAME`. The rendezvous executable reads comma-separated `PIPANE_STUN_URLS` and `PIPANE_TURN_URLS`, plus `PIPANE_TURN_SECRET`; durable central identity/account state defaults to `~/.config/pipane-rendezvous` or `PIPANE_RENDEZVOUS_DATA_DIR`.
+
+### Device identity and anonymous accounts
+
+The browser creates a non-exportable P-256 private key and stores the `CryptoKey` in IndexedDB. `deviceId` is the SHA-256 fingerprint of its canonical public SPKI. Central trust endpoints issue one-use challenges for pairing, normal connection tickets, authorized-backend discovery, device revocation, and backend-grant revocation. The device signs every challenge; no permanent bearer credential is stored in the browser.
+
+- `POST /v1/auth/challenges`
+- `POST /v1/pairings/:pairId/tickets`
+- `POST /v1/connections/tickets`
+- `POST /v1/accounts/backends`
+- `POST /v1/revocations/devices`
+- `POST /v1/revocations/backends`
+
+The first backend-confirmed pairing creates an anonymous account. Later terminal pairings can add another browser device to the backend's owner account, or an authenticated device can add an unowned backend to its account. A signed `discover` challenge returns only that account's backend grants, with registration metadata and current reachability. A backend has one owning account in this protocol version.
+
+### Pairing capabilities
+
+The backend creates a 256-bit secret, stores only its hash, and publishes the opaque pair id and expiry with `open_pairing`. The QR URL has this shape:
+
+```text
+https://app.example/pair/pair_id#backend=b_id&secret=secret
+```
+
+The secret remains in the URL fragment and never reaches HTTP access logs. Capabilities expire within fifteen minutes and are single-use at both rendezvous and backend. `pipane pair` asks the running local backend for a fresh QR link. The backend validates the secret over the end-to-end DataChannel before sending `confirm_pairing`; only then does rendezvous create or extend the anonymous account and backend grant.
+
+### Connection tickets and signaling
+
+A browser first signs a purpose- and route-scoped central challenge. Rendezvous then signs a short-lived ticket containing ticket id, kind, account (after pairing), device id and public key, backend id, browser-generated connection id, issue time, expiry, and optional pair id. `connect_backend` requires this ticket. Rendezvous and backend each reject ticket replay, expiry, route mismatch, revoked devices, and revoked backend grants.
+
+The browser may send only an SDP offer and the registered backend only an answer. The backend signs a `connection_binding` over the connection id, SHA-256 hashes of both exact SDP descriptions, the answer's DTLS certificate fingerprint, and ticket expiry. Rendezvous validates it against the observed signaling transcript; the browser validates the signature and pins the public key fingerprint to `backendId` before applying the answer.
+
+### Authenticated DataChannel
+
+The answer-side implementation accepts only a reliable ordered DataChannel with label `pipane` and subprotocol `pipane.v1`. Its first frame must contain the exact connection ticket, backend-binding signature, a device signature over both, and the pairing secret when applicable. The backend exposes the channel to `WsHandler` only after all central-ticket, local-owner, replay, revocation, device-proof, and optional pairing-secret checks pass.
+
+Authenticated DataChannels carry the existing versioned v1 application frames through the same server connection boundary as local WebSockets. A frame router keeps those application frames isolated from semantic v2 responses on the same ordered channel. Revocation closes active rendezvous routes and matching backend peers, prevents new ticket issuance, and is retained centrally so an offline backend clears stale local ownership when it next registers.
+
+### Semantic backend protocol v2
+
+`src/shared/backend-protocol.ts` defines the carrier-neutral request protocol independently from application v1:
+
+```text
+{ v: 2, kind: "request", id, method, params }
+{ v: 2, kind: "response", id, method, success, result | error }
+{ v: 2, kind: "event", cursor, type, data }
+```
+
+The currently implemented semantic methods are:
+
+- `backend.capabilities`
+- `sessions.list`, `sessions.delete`, `sessions.forkMessages`, `sessions.raw`
+- `files.read`, `files.upload.create`, `files.upload.append`, `files.upload.complete`
+- `host.browse`, `host.mkdir`
+- `settings.get`, `settings.validate`, `settings.patch`, `settings.save`
+- `updates.get`, `updates.run`
+
+Every method has runtime-validated parameters, correlated responses, stable error codes, bounded concurrency, and a bounded device-scoped completed-request cache. File uploads use bounded, offset-addressed base64 chunks so arbitrary non-image attachments can cross either local HTTP or the authenticated DataChannel, land in a private temporary backend path, and be referenced in the agent prompt. Pending browser requests retain their id across a carrier reconnect, so an in-flight mutation is resumed or answered from the cache instead of being executed twice. The backend uses one `LocalBackendApi` implementation for both the legacy local HTTP facade and semantic DataChannel requests. Remote session results are scoped to a structured `{ backendId, path }` identity; paths remain backend-local identifiers rather than authorization.
+
+The browser's `RemoteBackendManager` maintains one client/store per active backend id, requests a fresh ticket whenever a WebRTC carrier reconnects, and never treats an arbitrary URL backend id as authorized until signed account discovery includes it. The product UI exposes reachable authorized backends and uses on-demand pairwise connections rather than a full mesh. Terminal `pipane pair` remains the no-email recovery path when browser storage is lost.
+
+Application streaming, turn control, and session snapshots remain on validated v1 frames during parity migration. Semantic v2 is deployed beside v1 rather than changing v1's renderer-state contract in place.
+
+## Pi subprocess RPC protocol
+
+`src/server/pi-rpc-protocol.ts` defines the typed subset of Pi RPC commands used by pipane and validates all corresponding responses, agent/session events, and extension UI requests before they reach session state. Pi's built-in TUI commands are not forwarded by RPC `prompt`; browser equivalents such as `/session` map to explicit typed RPC operations (`get_session_stats`) instead.
+
+`ProcessPool.sendRpc()` is generic over Pi's exported `RpcCommand`/`RpcResponse` types. Pending requests retain their expected command, and a mismatched response is rejected rather than resolving the wrong operation.
+
+Pi RPC uses strict JSONL framing. Records are split only on LF; Unicode line separators inside JSON strings are preserved. Invalid JSON, unknown event types, malformed event payloads, and malformed command responses are logged and ignored before event dispatch.
+
+## Compatibility policy
+
+A breaking browser/backend application-frame change must increment `WS_PROTOCOL_VERSION`; a breaking semantic method-envelope change must increment `BACKEND_PROTOCOL_VERSION`; a breaking rendezvous control-plane change must increment `RENDEZVOUS_PROTOCOL_VERSION`. Update the corresponding decoders and contract tests. Additive fields may be introduced without a version increment when old peers can safely ignore them. New discriminants require explicit validation and exhaustive handling on both sides.