@abot-ai/socket 0.0.0-stage → 0.2.0

package/docs/INSTALLATION.md

@@ -0,0 +1,177 @@
+# Installation and first connection
+
+ABot Socket is MIT-licensed and distributed as `@abot-ai/socket` on npm.
+This guide covers package installation, server preparation and the first
+runtime/app connection.
+
+## Install the command
+
+Use Node.js 24 or later and a persistent npm installation owned by an unprivileged
+account. Linux with systemd is the server deployment target; macOS can run the
+foreground service and local development checks. The authentication store uses
+POSIX ownership/permissions and does not support Windows server installation.
+
+Install the command from the official npm registry:
+
+```sh
+npm install --global @abot-ai/socket@0.2.0
+abot-socket --version
+abot-socket setup
+```
+
+Prefer an explicit version for server upgrades. An installed package uses the
+`abot-socket` command; it does not require a Git checkout or `npm ci`.
+For an existing installation, retain its configuration and follow the
+[state backup and schema upgrade guide](MIGRATION.md#durable-request-ownership-schema-upgrade)
+before replacing the package. `setup` prepares a new configuration; it does not
+migrate or overwrite an existing one.
+
+Alternatively, prepare a tarball from the public source:
+
+```sh
+git clone https://github.com/Dorshitrit/abot-socket.git
+cd abot-socket
+npm ci --omit=optional --ignore-scripts
+npm pack --ignore-scripts --json > /tmp/abot-socket-pack.json
+npm run check-package -- /tmp/abot-socket-pack.json
+```
+
+Then install that tarball (or a verified local tarball you already have):
+
+```sh
+npm install --global ./abot-ai-socket-0.2.0.tgz
+abot-socket --version
+abot-socket setup
+```
+
+Contributor commands are separate in [Self-hosting](SELF-HOSTING.md#source-checkout-development).
+
+Do not use an ephemeral npx installation for a persistent system service. npm
+installation has no lifecycle install hooks and does not run the setup wizard,
+request certificates, contact your runtime or change OS service settings.
+
+## Follow setup
+
+The interactive wizard asks for:
+
+1. A new private installation directory; the default is `~/.abot-socket`.
+2. Your canonical HTTPS origin, for example `https://socket.example.net`.
+3. The runtime identity and a private loopback listener port (default 8788).
+4. On Linux as a non-root user: nginx, Apache or an existing HTTPS setup. Proxy
+   templates require paths to an existing full-chain certificate and private key.
+5. Confirmation before writing any installation files.
+
+Setup creates a new directory with mode `0700` and private files with mode `0600`:
+
+| Output | Purpose |
+| --- | --- |
+| `config.json` | HTTPS origin, listener port, state location and runtime grants containing token hashes. |
+| `runtime-connection.json` | Bridge URL, runtime identity and secret; transfer only to the runtime computer. |
+| `state/auth.sqlite3` | Pairing state, device credentials, notification metadata and pending delivery state. |
+| `deployment/` | Reviewable Linux service/proxy plan, when selected in the interactive wizard. |
+
+Setup defaults to Ask permission and port `8788`. Keep the installation outside
+the package/source directory so package updates cannot replace its state.
+No services are installed/started and certificate contents are never read.
+Pairing details are displayed in the terminal, not stored as a plaintext file.
+They expire after five minutes, so request a fresh bundle when HTTPS is ready.
+
+The optional endpoint check at the end makes one bounded public HTTPS request only
+if you explicitly choose it. A successful check proves relay health, not a working
+runtime or model. Cancellation before file creation leaves no installation behind.
+
+For unattended local file preparation, use explicit arguments instead of prompts:
+
+```sh
+abot-socket setup --output /srv/abot-private \
+  --origin https://socket.example.net --runtime-id workstation --port 8788
+```
+
+The parent directory must exist, and the output directory must not exist. Run as
+the same unprivileged account that will operate the relay. The unattended command
+creates the configuration/state only; use `deployment` separately for service files.
+If state initialization fails after files were written, preserve the installation,
+correct the private-state path/permissions and use `pair` to retry. Setup never
+overwrites existing configuration or state.
+
+## Configure HTTPS and start the relay
+
+Follow [Deployment](DEPLOYMENT.md) to review and explicitly apply the generated
+systemd and proxy files. Supply DNS, a valid certificate and the required proxy
+software yourself; neither npm nor setup obtains or installs them. Existing
+services must be checked before applying the plan.
+
+For foreground operation instead of a system service:
+
+```sh
+abot-socket start
+```
+
+Commands use `~/.abot-socket/config.json` by default. For a custom location:
+
+```sh
+abot-socket start --config /srv/abot-private/config.json
+abot-socket check-config --config /srv/abot-private/config.json
+```
+
+`--config` overrides environment settings. Otherwise `ABOT_SOCKET_CONFIG` and its
+legacy `SOCKET_V2_CONFIG` alias retain their existing precedence/conflict checks.
+`setup` takes `--output` instead; it never overwrites an existing configuration.
+
+## Connect runtime, then pair the app
+
+Privately transfer `runtime-connection.json` to the intended runtime computer.
+Configure its existing bridge with the generated `agentBridgeUrl`, `runtimeId`
+and `runtimeToken`, using that runtime version's documented configuration names.
+The file is a credential handoff, not a replacement runtime configuration or a
+second bridge process. This is separate from app pairing; the runtime secret
+must never go into the app.
+No runtime source changes are required by this installer.
+
+Recoverable approvals and continuation of computer-created requests require a
+compatible app and a runtime advertising `request_approvals_v1`. SPARK companion
+chat requires `spark_chat_v1` and a configured SPARK model. The app must check
+the selected runtime's capabilities and readiness, not just the Socket's global
+flags. Earlier clients and runtimes retain their supported legacy chat path;
+upgrading the Socket alone does not enable these runtime features.
+
+```sh
+abot-socket doctor
+abot-socket pair
+```
+
+For custom configuration locations, add `--config` to those commands as above.
+Doctor verifies TLS and the `/health` response, refuses redirects and has a five-second
+total timeout. Its output always includes `runtimeVerified: false`. It never sends
+credentials or generates a device session. The app must confirm that the selected
+runtime is online and can complete a chat request.
+
+In a normal terminal, `abot-socket pair` also displays a private QR for a scanner-capable
+ABot App. Scan inside the app, check the displayed server address, and confirm.
+The QR contains the same HTTPS URL, temporary pairing key and six-digit code; it
+expires after five minutes and can be used once. Anyone with the QR can use that
+pending pairing, so do not publish it or send it to a public QR service.
+
+Generate a fresh QR **after** the service and HTTPS are ready; setup does not start
+the server, and its initial pairing may expire while deployment is being completed.
+The QR is printed locally, not saved to disk or served at a public endpoint.
+Piped output keeps the existing text/JSON format. `TERM=dumb` or a narrow terminal
+uses manual details instead; widen the terminal and run `pair` again if needed.
+When running a remote command through SSH, allocate a terminal to display the QR.
+
+Manual entry remains available for app versions without a scanner or when camera
+access is unavailable: enter the new code, HTTPS URL and temporary pairing key. Afterwards,
+`abot-socket devices` lists devices and `abot-socket revoke <device-id>` revokes one.
+Both operate on the local private state without restarting the service.
+
+Push delivery is optional and off by default. Ordinary chat and the notification
+inbox work without it. See [push delivery configuration](SELF-HOSTING.md#optional-push-delivery)
+for the difference between the Store application's gateway and a self-built app's
+own Firebase sender.
+
+## Updates
+
+Keep private configuration/state outside the npm package directory. Updating the
+package must not replace that state. Regenerate the service plan if Node or the
+package path changes, and restart the service explicitly during the approved update.
+No automatic update, live migration or service restart is implemented here.

package/docs/MIGRATION.md

@@ -0,0 +1,84 @@
+# Moving to pairing
+
+Installing the package does not change existing services or applications. Use a
+separately approved cutover after real-device verification.
+
+The chat envelopes, runtime bridge and runtime credential grants remain compatible.
+Authentication changes: the new client uses local-operator pairing instead of
+email. Old in-memory sessions cannot be imported. Existing devices must pair to
+the new service, receiving separate credentials bound to its HTTPS origin.
+
+1. Back up the current private configuration and deployed version.
+2. Prepare a separate candidate endpoint and private state with a unique test
+   runtime identity. Do not attach two active runtimes using the same ID.
+3. Issue pairing locally; verify pairing, restart persistence, runtime discovery,
+   history, chat, steering, approvals and revocation through the actual app.
+4. Perform the approved service/client cutover while retaining a rollback path.
+
+The new configuration has `publicOrigin`, `port`, `stateDirectory`, and
+`runtimeGrants`. Remove old `allowedEmail` and `mail` settings; they are rejected.
+`ABOT_SOCKET_CONFIG` accepts `SOCKET_V2_CONFIG` as a path alias. No mail-token
+variable is used. The existing runtime adapter needs configuration only, not
+source changes. Setup generates new runtime credentials rather than rotating or
+migrating an existing installation automatically.
+
+After cutover, retain the private state directory through upgrades. Device
+sessions persist there. Socket connections and transient subscriptions still
+disappear on restart; durable request ownership is described below. Interrupted
+requests must be reconciled against runtime state before retry.
+
+## Durable request ownership schema upgrade
+
+Schema v4 adds a routing-ownership table to the existing private database.
+Schemas v1, v2 and v3 upgrade transactionally, preserving owner identity, paired
+devices, pending pairing, notification metadata, preview keys and delivery queues.
+No new dependency or additional state file is required.
+
+New durable requests record their runtime, session, request, owner and
+initiating device identifiers, plus routing status and timestamps. A paired owner
+device can also recover an unowned computer-created request: after a fresh
+response from the authorized runtime verifies the exact session and request, the
+Socket records that ownership with the adopting device. Existing ownership is
+never reassigned to a different owner or session. There is no bulk import, and
+historical events cannot establish ownership.
+
+This table contains no conversation content, approval presentation, decision or
+continuation. The runtime remains authoritative for pending approvals and decision
+receipts. Recovery requires a compatible client and `request_approvals_v1` on the
+selected runtime; legacy requests are not automatically converted during upgrade.
+
+Ownership is persisted before forwarding a new request. Open or uncertain records
+do not expire or get evicted; a full 512-record ledger rejects new admissions.
+Only confirmed terminal records expire after 12 hours. Confirmed whole-session
+deletion retires that session's records. Revoking the originating
+device does not erase ownership: another paired device of the same owner can
+still recover the request, but revoked credentials cannot connect or receive push.
+An interrupted send is never automatically resent from this ledger.
+
+Stop the service and preserve the private state directory and matching code before
+upgrading. Older binaries reject schema v4. Rollback requires restoring the
+matching pre-upgrade database snapshot and code while stopped; do not delete state
+to make an old binary start. Reconcile device revocations and deliveries made
+since that snapshot before resuming service. This source change alone does not
+upgrade or restart a deployed service.
+
+
+## Notification preview schema upgrade
+
+Schema v3 adds a device-scoped preview-key table and nullable encrypted-preview
+column on the existing outbox. Both schema v1 and v2 upgrade transactionally;
+paired-device tokens, pending pairing, owner identity, notification metadata and
+generic delivery queues are preserved. Preview remains off until that device
+explicitly provisions a key after push registration. No runtime changes are needed.
+
+Stop the service and back up the private state directory and matching deployed
+code before upgrading. Older binaries reject schema v3. Rollback requires restoring
+the matching pre-upgrade database snapshot together with old code while stopped;
+do not point an old binary at the migrated state or delete the database to make it
+start. Restoring a snapshot also restores its older device/revocation/delivery state,
+so reconcile changes made since that snapshot before resuming service.
+
+For gateway delivery, upgrade the publisher gateway before clients enable previews.
+Keep previews off until compatible client support is installed. Old clients and
+opted-out devices retain the original generic push behavior. This source change
+alone does not deploy or enable preview delivery on an existing installation.

package/docs/PROTOCOL.md

@@ -0,0 +1,371 @@
+# Protocol and compatibility
+
+This candidate retains the Socket v2 chat transport contract and replaces email
+authentication with operator-issued pairing. It does not change
+runtime source or expose the complete runtime Web UI API. The `/health` value
+`version: 2` identifies the protocol family, not a package release number.
+
+## HTTP
+
+Use the configured HTTPS origin. JSON body limits depend on the route:
+
+| Route | Maximum JSON request body |
+| --- | --- |
+| `POST /v2/pairing/redeem`, `POST /v2/notifications/read`, `POST /v2/notifications/presence` | 4 KiB (4096 bytes). |
+| `PUT /v2/notifications/push` | 8 KiB (8192 bytes). |
+| `PUT /v2/notifications/push/preview` | 512 bytes. |
+
+These are application limits; a reverse proxy can impose a smaller limit. The
+generated direct-proxy plans currently cap request bodies at 4 KiB. The separate
+notification gateway accepts JSON bodies up to 8 KiB and needs its own proxy
+configuration. Field validation still applies within each body limit.
+
+Responses are `no-store`. Host must match the configured origin, and a supplied
+browser Origin must match it exactly. The local proxy requirements apply to all
+routes, including `/health`.
+
+| Method and path | Request / response |
+| --- | --- |
+| `GET /health` | `{ok:true, version:2}`; no account or runtime details. |
+| `POST /v2/pairing/redeem` | `{pairingId, code, deviceName}` → `{token, expiresAt, session:{id,subject,deviceName}}`. |
+| `GET /v2/auth/sessions` | Bearer session token → `{sessions:[{id,deviceName,createdAt,expiresAt,current}]}`. |
+| `DELETE /v2/auth/sessions/:id` | Bearer session token → `{revoked}`. |
+| `POST /v2/auth/logout` | Bearer session token → `{ok:true}`. |
+| `GET /v2/runtimes` | Bearer session token → `{runtimes:[...]}` with IDs, online state, model catalog, allowed modes, and capabilities. |
+
+`pairingId` is a random 32-character base64url temporary key; `code` is exactly
+six decimal digits, including leading zeros. Both are required. A bundle is
+valid for five minutes and five failed attempts; consume and device issuance
+share a database transaction. A retry after a lost success response cannot reuse
+it: the operator must create a fresh bundle. Neither secret belongs in a URL.
+The ordinary Socket API has no HTTP endpoint for generating pairing bundles.
+The optional, separately enabled [app-review portal](APP-REVIEW.md) exposes an
+authenticated `POST /review/pair` on its own listener/origin, bound to a dedicated
+review installation. It is not part of the ordinary Socket API. Legacy email
+endpoints are no longer supported.
+
+### Pairing QR, version 1
+
+The operator CLI can encode the existing bundle as raw UTF-8 JSON in a QR:
+
+```json
+{"type":"abot-pairing","version":1,"serverUrl":"https://socket.example.test","pairingId":"0123456789abcdefghijklmnopqrstuv","code":"000123","expiresAt":1800000300000}
+```
+
+This example is illustrative, not a usable pairing. `expiresAt` is Unix time in
+milliseconds; the server remains authoritative for validity. The code is a string
+to preserve leading zeros. The QR contains only these six fields, never a runtime
+token, permanent device token, configuration file, or secret-bearing URL/deep link.
+
+Clients validate the type/version and field shapes, accept only a canonical HTTPS
+origin, display the destination for confirmation, and then use the existing
+`POST /v2/pairing/redeem`. Scanning alone must not contact the destination. Suppress
+duplicate camera detections while confirmation or redemption is in progress.
+The existing expiry, attempt limits and one-use transaction apply unchanged;
+creating a new bundle replaces only the pending pairing, not existing devices.
+The QR is a bearer enrollment secret, so it must not be retained in logs or sent
+to external QR-generation services.
+
+An expired, unknown, consumed or wrong pairing returns `invalid_code` / 401.
+General HTTP limits and source/global code-verification limits return `rate_limited` / 429.
+Verification quotas apply only after matching an unexpired, unlocked pending pairing
+key; malformed, unknown, expired or already-locked pairing requests do not spend them.
+A full device list
+returns `device_limit` / 429; free a slot locally. Malformed device names return
+`invalid_request` / 400 without consuming an otherwise valid pairing.
+
+## Native client WebSocket
+
+Connect to `/v2/realtime` using `Authorization: Bearer <device-session-token>` in
+the HTTP upgrade. Credentials are not accepted in URL query parameters. Native
+clients should store the token in the platform's secure credential store.
+Browser WebSocket APIs cannot set this header; browser support needs its own
+designed authentication path.
+
+On connection, the relay sends `authenticated` with the session expiry and
+capability flags. Client commands use `{id, runtimeId, body}`. IDs must be unique
+per connection. Supported body types are:
+
+- `run_request`, `steer_request`, `tool_approval_response`;
+- `request.approvals.request`, `request.approval.decide.request` for an owned request on a capable runtime;
+- `session.list.request`, `session.snapshot.request`, `request.events.request`;
+- `spark.chat.open.request` on a SPARK-capable runtime;
+- `session.delete.request`, `session.messages.clear.request`, `session.message.delete.request`;
+- `attachment.upload.request`, `attachment.fetch.request`;
+- relay-local `subscribe_request` for a known request belonging to this owner.
+
+The relay returns `relay.ack`, `relay.error`, `relay.response`, or `relay.event`
+with the appropriate command ID, runtime ID, and body. An acknowledgement means
+dispatched or queued, not completed. Runtime correlations belong to the relay;
+the client cannot choose them. Unknown command fields and unsupported operations
+are rejected rather than forwarded as a generic admin API.
+
+Tool permission values are `ask`, `full_access`, and `full_plus`, constrained by
+the runtime grant. Setup grants only `ask`. The model catalog and supported
+reasoning controls come from the connected runtime, not a hardcoded model list.
+
+### SPARK companion chat
+
+The Socket advertises `authenticated.capabilities.sparkChat`. Each runtime in
+`/v2/runtimes` reports this capability only when online and advertising
+`spark_chat_v1`. Clients must check the per-runtime capability; a runtime feature
+alone does not establish support in an older Socket.
+
+Send `{type:'spark.chat.open.request'}` inside the usual authenticated command
+envelope. The client supplies no session, model, permission or correlation fields.
+The correlated `spark.chat.open.response` contains `ok`, the canonical
+`sessionId:'spark-companion'`, `modelProfileId` (or null), `toolPermissionMode` and
+`readiness` (`ready`, `model_required`, or `model_unavailable`). Failure responses
+contain a bounded public error code. Other runtime fields are not forwarded.
+
+Opening creates or reuses the marked companion without starting a model request.
+Load history and recover waiting approvals through the existing APIs. Send chat
+through `run_request` with the returned session and permission mode; the runtime
+selects its configured SPARK model. Opening can report a mode above the relay's
+grant, but does not authorize it: the existing grant check rejects that send.
+The runtime also rejects a mode changed since open with
+`spark_chat_permission_mismatch`; refresh state and let the user retry, never
+silently increase permissions or automatically resubmit an uncertain request.
+
+Unsupported runtimes reject SPARK open/run with `spark_chat_unsupported`.
+Correlations remain bound to the requesting client and exact runtime connection,
+are consumed once, and expire after 30 seconds. This contract does not expose
+SPARK settings writes, collection, jobs or autonomous activity.
+
+### Session mutations
+
+Each runtime in `/v2/runtimes` and the WebSocket `authenticated` frame includes
+`capabilities.sessionMutation: true` for these three relay operations. Clients must treat an
+absent/false flag as unsupported and require explicit user confirmation.
+
+| Request body | Response body (inside `relay.response`) |
+| --- | --- |
+| `{type:'session.delete.request', sessionId}` | `{type:'session.delete.response', ok, sessionId, deleted, deletedMessages, deletedRequests}` |
+| `{type:'session.messages.clear.request', sessionId}` | `{type:'session.messages.clear.response', ok, sessionId, cleared, deletedMessages, deletedRequests, updatedAt}` |
+| `{type:'session.message.delete.request', sessionId, messageId}` | `{type:'session.message.delete.response', ok, sessionId, messageId, deleted, updatedAt, deletedRequestId?, deletedRequestEvents?}` |
+
+Use canonical message IDs from a fresh runtime snapshot, not local UI IDs.
+Numeric message IDs are normalized to strings. Only `ok:true` together with
+`deleted:true` / `cleared:true` confirms a change; reload canonical history after
+the result. The runtime's single-message delete removes only that message row,
+plus its associated request replay/context and memory checkpoints; sibling
+message rows remain. Session deletion/clearing follows the existing runtime's
+history and attachment cleanup semantics.
+
+The relay rejects observed active/uncertain requests and in-flight uploads with
+`session_busy`. Before forwarding a mutation it reads a complete snapshot with
+`includeRequests:true`; active requests prevent deletion, and an incomplete or
+unrecognized snapshot returns `session_state_unavailable`. No snapshot contents
+are added to the mutation response. A pending mutation blocks another mutation,
+new run or upload in that session (`session_mutation_pending`). It retains this
+guard after client disconnect until the outcome or the shared 30-second timeout.
+A client disconnected during the read check cannot begin deletion.
+
+This check is not an atomic lock over independent Web UI clients. A request
+started directly at the runtime after the check can race with deletion; the
+runtime fences deleted generations and that request may be cancelled. Wait for
+work on all clients to finish. `outcome_unknown` never authorizes an automatic
+retry: reload authoritative history first. Missing sessions report
+`session_not_found`; runtime failures remain failures.
+
+## Runtime bridge
+
+Connect to `/agent-bridge` with the separate runtime Bearer token, then send the
+existing `{type:'register', agentId, features?, modelCatalog?}` message. The
+registered ID must match the credential's grant. A second connection cannot
+replace an already connected runtime with the same ID. Client device credentials
+cannot authenticate this role.
+
+## Recovery and capability limits
+
+- A timeout or disconnect can return `outcome_unknown`; do not retry commands
+  automatically. Read canonical runtime history/replay to reconcile the result;
+  the durable decision retry rules below apply only to that decision, never a run.
+- Live `eventSequence` and replay `seqNo` are separate counters. `afterSeq` uses
+  the persisted replay counter only.
+- Legacy `tool_approval_response` requires a live observed pending approval for
+  the correct owner, runtime and request. Positive approval expires after five
+  minutes; an explicit decline can remain possible once on that same active
+  runtime connection and request. Historical replay never creates authority.
+- `cancel` remains false. Restart, cron, configuration, and generic administration
+  are not exposed.
+- The relay keeps bounded routing state and persistent durable-request ownership
+  metadata. It is not an offline queue, conversation store, or exactly-once
+  execution service.
+
+### Durable approval recovery
+
+The WebSocket `authenticated.capabilities.durableApprovals` flag describes
+whether the Socket has the persistent ownership store required by this API.
+Each `/v2/runtimes` entry reports the flag separately: it is true only while that
+runtime is online and advertises `request_approvals_v1`. Clients must check the
+chosen runtime, not infer its support from the global flag. Older runtimes remain
+usable through the legacy path.
+
+To opt in, a new `run_request` includes `approvalMode:'durable_v1'`. Omitting it
+retains legacy behavior. The relay persists its owner, originating device,
+runtime, session and request identity before forwarding the run. It does not
+persist the prompt, approval payload, decision or runtime continuation. An
+unavailable capability rejects the opt-in instead of silently downgrading it.
+
+| Request body | Response body inside `relay.response` |
+| --- | --- |
+| `{type:'request.approvals.request', sessionId, requestId}` | `{type:'request.approvals.response', correlationId, sessionId, requestId, ok:true, approvals:[{request,wait?}], lifecycle, finalState}` |
+| `{type:'request.approval.decide.request', sessionId, requestId, approvalId, approved, reason?, generation?, waitId?, revision?, commandId?}` | `{type:'request.approval.decide.response', correlationId, sessionId, requestId, ok:true, result:{accepted,duplicate?,reason?}}` |
+
+Runtime failures use `ok:false,error` with the same scope. The relay assigns the
+private correlation; clients correlate the outer command `id`. Only a response
+from the current runtime connection with matching request, session and correlation
+is accepted. One approval query/decision per request may be in flight at a time.
+
+Recovery requires a durable ownership record admitted by this Socket. When an
+authorized paired device queries approvals for a request created directly on
+its runtime, the relay can establish that record after a fresh, privately
+correlated snapshot from the current runtime connection confirms the exact
+session and request. Client-provided history or a replayed
+`tool.approval.required` event cannot establish ownership. An existing record
+for another owner or session is never reassigned. A decision alone cannot
+establish ownership; query the current approvals first.
+After a Socket or runtime restart, an authenticated device belonging to the same
+installation owner may recover the request; revoking the originating device does
+not transfer its credential or notification inbox. Recovery also restores live
+delivery for that request. It does not rerun it or reconstruct missed events.
+
+The runtime remains authoritative for pending approvals and their lifecycle.
+Durable waits do not inherit the relay's legacy five-minute approval timeout.
+For a returned `wait`, send its exact `generation`, `waitId` and `revision` together
+with a stable client-generated `commandId`. All four fields are required together;
+omit all four only for a legacy approval returned by the runtime. Do not substitute
+new wait identities when retrying an uncertain decision. Reuse the original
+decision and `commandId` so the runtime can recognize its durable receipt, then
+reload canonical state. Accepted duplicate decisions must not execute the action
+again. A declined or stale decision remains a refusal, not an invitation to retry
+against a newer approval.
+
+Ownership storage is capped at 512 records. Open records are not age-evicted;
+confirmed terminal records are retained for 12 hours, or removed after confirmed
+deletion of their complete session. Capacity exhaustion rejects new admission.
+
+Use the new pairing-capable client. Email-only personal builds cannot enroll
+through this authentication contract. Clients and runtime adapters that omit the
+durable approval opt-in retain legacy behavior.
+
+## Notifications
+
+`capabilities.notifications: true` advertises the authenticated notification API.
+Notifications are owned by the **paired device that initiated the request**, or
+by the **device that first adopts an unowned computer-created request** through
+the verified recovery flow above. Ownership does not follow the current
+WebSocket connection: later recovery by another paired device does not transfer
+the notification inbox. Other paired devices cannot list or mark that device's
+records. There are no new unsolicited WebSocket frame types; clients poll the
+inbox while foregrounded and reconcile on resume or push tap.
+
+| Method and path | Request / response |
+| --- | --- |
+| `GET /v2/notifications?limit=50&before=<cursor>` | Device inbox, descending time; limit 1–100; opaque optional cursor. |
+| `POST /v2/notifications/read` | `{ids:[...]}` (maximum 100) → `{ok:true}`. Unknown or foreign IDs have no effect. |
+| `POST /v2/notifications/presence` | `{foreground:boolean,runtimeId?,sessionId?}` → `{ok:true}`; a session requires its runtime. |
+| `PUT /v2/notifications/push` | `{provider:'fcm',token}` or `{provider:'gateway',endpointId,sendToken}` → `{ok:true}`. |
+| `DELETE /v2/notifications/push` | Remove this device's push registration, preview key and queued deliveries → `{ok:true}`. |
+| `PUT /v2/notifications/push/preview` | Exact `{keyId,key}` → `{ok:true}`; opt in after registering push. Replaces the device's key. |
+| `DELETE /v2/notifications/push/preview` | Remove this device's preview key and queued ciphertext, retaining generic deliveries → `{ok:true}`. |
+
+The inbox response is `{version:1,items,nextCursor,unreadCount,unreadByRuntime,
+unreadBySession,delivery,registration,preview}`. Each item is
+`{id,runtimeId,sessionId,requestId,kind,createdAt,readAt,expiresAt}`; timestamps
+are epoch milliseconds, and `readAt` is null until read. `kind` is `completed`,
+`failed` or `approval_required`. `unreadByRuntime` maps runtime IDs to counts;
+`unreadBySession` maps runtime IDs to session-ID/count maps. `delivery` is
+`{mode:'disabled'|'fcm'|'gateway',configured:boolean}`, and `registration` is
+`{enabled:boolean}`. `preview` is `{supported:true,enabled:boolean,keyId:string|null}`.
+Older servers omit `preview`; clients treat that as unsupported and off. Keys
+and registration credentials are never returned by this API.
+
+Foreground presence lasts 45 seconds. Renew while active; `foreground:false`
+clears it. Presence is advisory: the phone may be suspended before its background
+update arrives, so presence alone never marks records read or suppresses delivery.
+Only an explicit authenticated read acknowledgement consumes records and cancels
+queued deliveries. Clients acknowledge fetched IDs after showing the conversation.
+Counts share the same ledger; they are not runtime transcript read receipts.
+Push taps resolve the notification ID through this authenticated inbox
+before opening a conversation; a push payload grants no execution or approval authority.
+
+Only validated live `completed`, `failed` and `tool.approval.required` frames for
+known relay requests create records. Streaming/progress events and replay do not.
+Granted/rejected/terminal events cancel pending approval deliveries. Approval
+notifications expire after five minutes; other records after at most seven days
+or device credential expiry. Storage is capped at 500 records per device.
+Expiration, logout and revocation remove registrations and pending deliveries.
+The outbox retries at most five times, with bounded backoff. Duplicate source
+events are deduplicated, but provider delivery is not an exactly-once guarantee.
+
+The inbox and queued deliveries survive relay restarts. Live subscriptions must
+be restored explicitly; durable ownership permits the scoped recovery described
+above. This is not a complete runtime-wide event subscription or an offline
+execution queue. Work started outside the relay has no automatic notification
+subscription. After an existing computer request is verified and adopted, later
+validated live events for that request can create notifications for its adopting
+device; recovery does not backfill missed notifications. Never interpret a missing
+notification as a failed request or auto-retry it.
+
+Push is disabled unless private operator configuration includes
+`notifications.delivery`. A self-built client uses
+`{type:'fcm',serviceAccountFile:'./private-sender.json'}`; the path is resolved
+relative to the private socket configuration, and sender credentials stay on
+that operator's server. The client must belong to the same configured Firebase
+project. Official builds can use `{type:'gateway',gatewayOrigin:'https://<trusted-host>'}`
+with a separately enrolled endpoint. Clients cannot choose a gateway URL or send
+provider credentials through the registration API. A missing or mismatched
+configured transport returns `409 push_unavailable`; ordinary chat and the inbox
+continue to work with delivery disabled.
+
+
+### Optional encrypted answer previews
+
+Previews are off by default and enabled per paired device, only after an active
+push registration exists. The app generates a random 32-byte AES-256-GCM key and
+16-byte key ID, sends both over authenticated HTTPS to its own Socket, and enables
+local display only after acknowledgement. Both fields use canonical unpadded
+base64url. No email, additional identity provider, or runtime change is involved.
+Provider-token rotation preserves the preview setting. Key replacement clears
+pending ciphertext. Disabling previews clears the key and ciphertext while leaving
+the generic queue intact; unregistering push removes the entire delivery queue.
+In-flight sends are aborted where possible, but provider-accepted notifications
+cannot be recalled. The client must discard its key immediately on disable/logout.
+
+Only a nonempty final `completed.output` is eligible. The Socket takes a bounded
+prefix, removes unsafe controls and bidi override characters, and truncates on a
+Unicode scalar boundary to at most 1024 UTF-8 bytes, including an ellipsis when
+needed. It is an excerpt, not secret redaction. Approval, failure and progress
+content is never included. No plaintext preview is stored in the inbox or outbox.
+The inbox remains metadata-only; encrypted content exists only in the pending
+outbox and is removed on delivery, read acknowledgement, revocation or expiry.
+
+The exact encrypted envelope is `{v:1,keyId,nonce,ciphertext,expiresAt}`. Nonce is
+12 random bytes. Ciphertext contains encrypted UTF-8 followed by the 16-byte GCM
+authentication tag (at most 1040 bytes), using canonical unpadded base64url.
+Authenticated additional data is UTF-8, with literal newline separators:
+
+```text
+ABot push preview v1
+<keyId>
+<notificationId>
+<expiresAt decimal epoch milliseconds>
+```
+
+The expiry equals notification expiry, capped by the device credential and seven
+days. The device rejects an unknown key, altered ID/expiry/content, expired data
+or malformed envelope and retains a generic alert. The gateway receives neither
+the key nor plaintext. Its `/v1/deliver` accepts an optional strictly validated
+`preview` field alongside the existing fixed delivery fields. Upgrade the gateway
+before enabling previews; older gateways do not accept this field.
+
+Encrypted FCM sends have no top-level `notification` or `android.notification`.
+Their string-valued data is `notificationId`, `abotPreview` (envelope JSON),
+`abotKind` (`completed`), `abotExpiresAt` and `abotBadge`. Android renders the
+notification locally. APNs retains a generic alert and sets `mutable-content:1`
+for the app's notification-service extension. Generic sends keep their existing
+payload. Serialized provider envelopes are bounded to 4096 UTF-8 bytes. Foreground
+display and navigation continue to use the authenticated inbox; push cannot grant
+access or approval authority.