@abot-ai/socket 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.2.0 - 2026-11-14
+
+### Added
+
+- Recover pending tool approvals after client reconnects and Socket or runtime
+  restarts, using persistent request ownership and runtime-authoritative waits.
+- Continue and approve requests started on the computer from a paired client,
+  after the current runtime confirms the exact session and request. Existing
+  ownership is never reassigned to another owner or session.
+- Open and chat with the runtime's SPARK companion through compatible clients,
+  using its configured model and permissions. This does not expose SPARK
+  management, settings writes or proactive activity.
+
+### Fixed
+
+- Restore scoped live request delivery when recovering an owned request, without
+  rerunning it or reconstructing events missed during disconnection.
+
+### Upgrade notes
+
+- New features require a compatible client and the selected runtime's
+  `request_approvals_v1` or `spark_chat_v1` capability. Legacy chat and live-only
+  approval behavior remain available when the new capabilities are not used.
+- Private SQLite state upgrades transactionally from schema v1, v2 or v3 to v4.
+  Existing pairing, device credentials, notification metadata, preview keys and
+  delivery queues are preserved. Stop the service and back up its private state
+  and matching code before upgrading; rollback requires both the pre-upgrade
+  state and old code. See [Migration](docs/MIGRATION.md).
+- Node.js 24 or later remains required. Dependencies and the HTTP/WebSocket
+  protocol envelope are unchanged.
+
+## 0.1.0 - 2026-11-11
+
+- Initial MIT-licensed npm release with authenticated runtime relay, QR/manual
+  pairing, device revocation, notification delivery and optional encrypted
+  previews, and CLI setup/deployment guidance.

package/README.md

@@ -6,6 +6,7 @@ computers. The relay does not require an ABot-hosted account or backend.
 
 The source is available under the [MIT license](LICENSE). Install the versioned
 `@abot-ai/socket` package from npm, or build a local tarball from source.
+See the [changelog](CHANGELOG.md) for release notes and upgrade requirements.
 
 ## Install and prepare
 
@@ -14,7 +15,7 @@ guide for installing the command, preparing a server, connecting a runtime and
 pairing the app by QR or manual entry.
 
 ```sh
-npm install --global @abot-ai/socket@0.1.0
+npm install --global @abot-ai/socket@0.2.0
 abot-socket setup
 ```
 
@@ -49,27 +50,39 @@ ABot App scans the private pairing QR and asks you to confirm its server address
 Manual code, HTTPS URL and temporary-key entry remains available. The app receives
 its own device credential; never copy the runtime credential into the app.
 
-The relay supports chat, steering, observed tool approvals, runtime history,
-model selection and attachments through the existing bridge. It does not execute
-models or store conversation history. Runtime configuration uses the existing
-bridge adapter; runtime source changes are not part of this project.
+The relay supports chat, steering, tool approvals, runtime history, model selection
+and attachments through the runtime Bridge. Compatible clients can recover pending
+approvals across reconnects and restarts, continue requests created on their
+computer, and open the runtime's SPARK companion chat. SPARK model settings and
+permissions remain runtime-owned; management and proactive activity are not exposed.
+These features require the selected runtime to advertise `request_approvals_v1`
+or `spark_chat_v1` respectively; older runtimes retain the legacy chat path.
+The relay does not execute models or store conversation history. Configure the
+runtime's existing Bridge; this installer does not modify runtime source.
 
 Device sessions last up to 30 days without sliding renewal and survive restarts
 in a private SQLite database. Operators can list and revoke devices locally.
 The device-scoped notification inbox records completion, failure and observed
-approval requests initiated through this relay. Push delivery is off by default;
+approval events for routed requests. Notifications belong to the initiating device
+or the device that first recovers a computer-created request through the verified
+ownership flow; later recovery by another device does not transfer that inbox.
+Push delivery is off by default;
 operators may configure their own FCM sender or an explicitly trusted ABot push
 gateway. Notifications are generic by default. An optional per-device encrypted
 preview can show a bounded final-answer excerpt; the gateway/provider never gets
 the preview key or plaintext. The app remains usable without push.
-Cancellation, durable approval restoration and recovery of events missed while
-the relay/runtime is disconnected are not implemented. The relay host is trusted and can read routed content;
-transport encryption is not end-to-end encryption.
-
-Notification metadata and pending deliveries share the private SQLite state.
-Upgrading migrates schema v1 or v2 to v3 without replacing paired devices. Back up the
-private state before deploying: an older binary cannot open the new schema.
-See [notification protocol and delivery](docs/PROTOCOL.md#notifications).
+Cancellation and reconstruction of events missed while disconnected are not
+implemented. Approval recovery queries current runtime state and restores scoped
+live delivery; it never automatically resends an interrupted request. The relay
+host is trusted and can read routed content; transport encryption is not end-to-end
+encryption.
+
+Notification metadata, pending deliveries and durable request ownership share the
+private SQLite state. Upgrading migrates schema v1, v2 or v3 to v4 without replacing
+paired devices. Back up the private state and matching code while stopped before
+upgrading. Older binaries cannot open v4; rollback requires the matching state
+backup and old code together. See [migration](docs/MIGRATION.md#durable-request-ownership-schema-upgrade)
+and [notification protocol and delivery](docs/PROTOCOL.md#notifications).
 
 ## Source layout
 

package/docs/INSTALLATION.md

@@ -14,13 +14,17 @@ 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.1.0
+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:
 
@@ -35,7 +39,7 @@ 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.1.0.tgz
+npm install --global ./abot-ai-socket-0.2.0.tgz
 abot-socket --version
 abot-socket setup
 ```
@@ -124,6 +128,13 @@ 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

package/docs/MIGRATION.md

@@ -23,8 +23,44 @@ 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; transient relay routes still disappear on restart.
-Interrupted requests must be reconciled against runtime history before retry.
+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

package/docs/PROTOCOL.md

@@ -87,7 +87,9 @@ capability flags. Client commands use `{id, runtimeId, body}`. IDs must be uniqu
 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.
@@ -102,6 +104,34 @@ 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
@@ -149,28 +179,87 @@ 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.
+  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.
-- Approval authority requires an observed pending approval for the correct
-  runtime and request. Historical replay alone does not restore that authority.
-  Positive approval expires after five minutes; an explicit decline can remain
-  possible once on that same active runtime connection and request.
-- `cancel` and `durableApprovals` are advertised as false. Restart, cron,
-  configuration, and generic administration are not exposed.
-- The relay keeps bounded temporary routing state. It is not an offline queue,
-  durable conversation store, or exactly-once execution service.
+- 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. Existing runtime adapters are unchanged.
+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**, not
-by its current WebSocket connection. 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.
+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 |
 | --- | --- |
@@ -211,10 +300,14 @@ 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. In-flight request routing
-does not: this is not a complete runtime-wide event subscription or an offline
-execution queue. Web UI, schedules and autonomous SPARK events are outside this
-phase. Never interpret a missing notification as a failed request or auto-retry it.
+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

package/docs/SECURITY.md

@@ -60,10 +60,28 @@ and rejects unsupported operations. These controls do not make a compromised
 authorized device harmless: it can act within its owner's configured grants.
 Revoking that device session removes its relay access.
 
+Paired owner devices can continue requests started directly on an authorized
+runtime. Before admitting an unowned request for approval recovery, the relay
+verifies its exact session/request identity through a fresh response from that
+runtime connection. It never replaces an existing ownership binding for a
+different owner or session. The runtime still validates every approval decision
+against its current wait; a session snapshot is not approval authority.
+
 The relay does not automatically retry uncertain operations, restore approval
 authority from historical events, or provide exactly-once execution. After a
 disconnect, reconcile against runtime history before resubmission.
 
+## SPARK chat boundary
+
+SPARK chat uses the same paired-device runtime access and tool-permission ceiling
+as ordinary chat. Opening it exposes only the canonical session, selected model,
+permission mode and model readiness, never the full preferences or internal
+diagnostics. Runtime support is required before dispatch. The runtime remains
+responsible for its marked companion and rereads its policy at every new send;
+the relay never caches that policy as permission to execute. Existing approval
+ownership and recovery checks remain in force. SPARK configuration and autonomous
+activity are outside this API.
+
 ## Push preview boundary
 
 Answer previews are opt-in per paired device and off by default. The already

package/docs/SELF-HOSTING.md

@@ -131,8 +131,15 @@ Back up the private configuration, runtime credential and state directory using
 a consistent filesystem/database snapshot or with the service stopped. Losing
 state requires pairing devices again. Restoring an old backup may restore old
 revocation state; reapply necessary revocations. Conversation history remains in
-each runtime. Temporary relay routes do not survive restart, so reconcile
-interrupted requests with runtime history rather than automatically resending.
+each runtime. Temporary relay routes do not survive restart. Durable request
+ownership does: a compatible app can query current approvals on a runtime
+advertising `request_approvals_v1` and restore live delivery for that request.
+This does not reconstruct missed events or resend interrupted work; reconcile
+against current runtime state before retrying.
+
+Version 0.2.0 uses state schema v4. See the
+[upgrade and rollback procedure](MIGRATION.md#durable-request-ownership-schema-upgrade)
+before upgrading; older binaries require the matching pre-upgrade state backup.
 
 The package does not provision a public TLS endpoint or install a service.
 Real-device, proxy and runtime verification remains separate from automated tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abot-ai/socket",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -50,6 +50,7 @@
     "src/setup/*.mjs",
     "src/transport/*.mjs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "config.example.json",
     "docs/SELF-HOSTING.md",

package/src/auth/auth-database.mjs

@@ -3,9 +3,10 @@ import { DatabaseSync } from 'node:sqlite';
 import { assertSameDatabaseFile, prepareAuthenticationDatabase } from './auth-storage-path.mjs';
 import { NOTIFICATION_SCHEMA } from '../notifications/notification-schema.mjs';
 import { NOTIFICATION_PREVIEW_SCHEMA } from '../notifications/notification-preview-schema.mjs';
+import { REQUEST_OWNERSHIP_SCHEMA } from '../relay/request-ownership-schema.mjs';
 
 const APPLICATION_ID = 0x41425341;
-const SCHEMA_VERSION = 3;
+const SCHEMA_VERSION = 4;
 
 const SCHEMA = `
   CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT;
@@ -81,9 +82,10 @@ export class AuthDatabase {
     const applicationId = this.prepare('PRAGMA application_id').get().application_id;
     const version = this.prepare('PRAGMA user_version').get().user_version;
     if (applicationId === APPLICATION_ID && version === SCHEMA_VERSION) return;
-    if (applicationId === APPLICATION_ID && [1, 2].includes(version)) {
+    if (applicationId === APPLICATION_ID && [1, 2, 3].includes(version)) {
       if (version === 1) this.#connection.exec(NOTIFICATION_SCHEMA);
-      this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+      if (version <= 2) this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+      this.#connection.exec(REQUEST_OWNERSHIP_SCHEMA);
       this.#connection.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
       return;
     }
@@ -94,6 +96,7 @@ export class AuthDatabase {
     this.#connection.exec(SCHEMA);
     this.#connection.exec(NOTIFICATION_SCHEMA);
     this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+    this.#connection.exec(REQUEST_OWNERSHIP_SCHEMA);
     const insert = this.prepare('INSERT INTO metadata(key, value) VALUES (?, ?)');
     insert.run('owner_id', randomUUID());
     insert.run('token_salt', randomBytes(32).toString('hex'));

package/src/cli/client-capabilities.mjs

@@ -1,4 +1,14 @@
+import { supportsSparkChat } from '../protocol/spark-chat-protocol.mjs';
+
 /** Socket-owned API support; runtime identity/features remain separately scoped. */
-export function clientCapabilities() {
-  return { cancel: false, durableApprovals: false, sessionMutation: true, notifications: true };
+export function clientCapabilities({ ownership, runtime } = {}) {
+  return { cancel: false, durableApprovals: supportsDurableApprovals(ownership, runtime),
+    sessionMutation: true, notifications: true, sparkChat: supportsSparkChat(runtime) };
+}
+
+function supportsDurableApprovals(ownership, runtime) {
+  if (!ownership) return false;
+  if (runtime === undefined) return true;
+  if (runtime.online !== true) return false;
+  return Array.isArray(runtime.features) && runtime.features.includes('request_approvals_v1');
 }

package/src/protocol/approval-protocol.mjs

@@ -0,0 +1,39 @@
+import { MAX_TEXT_BYTES, approvalId, boolean, fail, id, integer, optional, string } from './protocol-validation.mjs';
+
+export const APPROVAL_FIELDS = Object.freeze({
+  'request.approvals.request': ['sessionId', 'requestId'],
+  'request.approval.decide.request': ['sessionId', 'requestId', 'approvalId', 'approved', 'reason',
+    'generation', 'waitId', 'revision', 'commandId'],
+});
+
+export const APPROVAL_RESPONSES = Object.freeze({
+  'request.approvals.request': 'request.approvals.response',
+  'request.approval.decide.request': 'request.approval.decide.response',
+});
+
+const WAIT_FIELDS = ['generation', 'waitId', 'revision', 'commandId'];
+
+export function isApprovalCommand(type) {
+  return typeof type === 'string' && Object.hasOwn(APPROVAL_FIELDS, type);
+}
+
+export function durableApprovalMode(value) {
+  if (value !== 'durable_v1') fail();
+  return value;
+}
+
+/** Validate transport input only; current approval state and decisions belong to the runtime. */
+export function normalizeApprovalCommand(value) {
+  const result = { type: value.type, sessionId: id(value.sessionId), requestId: id(value.requestId) };
+  if (value.type === 'request.approvals.request') return result;
+  result.approvalId = approvalId(value.approvalId);
+  result.approved = boolean(value.approved);
+  optional(value, result, 'reason', reason => string(reason, MAX_TEXT_BYTES, { controls: true }));
+  if (!WAIT_FIELDS.some(key => Object.hasOwn(value, key))) return result;
+  if (!WAIT_FIELDS.every(key => Object.hasOwn(value, key))) fail();
+  result.generation = id(value.generation);
+  result.waitId = id(value.waitId);
+  result.revision = integer(value.revision);
+  result.commandId = id(value.commandId);
+  return result;
+}

package/src/protocol/protocol.mjs

@@ -3,11 +3,16 @@ import {
   MAX_MESSAGE_BYTES, MAX_TEXT_BYTES, fail, record, string, id, approvalId, integer,
   boolean, optional, attachment, attachments, modelPreference, reasoningPreference, upload,
 } from './protocol-validation.mjs';
+import { APPROVAL_FIELDS, APPROVAL_RESPONSES, durableApprovalMode,
+  isApprovalCommand, normalizeApprovalCommand } from './approval-protocol.mjs';
+import { SPARK_OPEN_REQUEST, SPARK_OPEN_RESPONSE } from './spark-chat-protocol.mjs';
 
 export { MAX_MESSAGE_BYTES, MAX_ATTACHMENT_BYTES, MAX_TEXT_BYTES } from './protocol-validation.mjs';
 
 const FIELDS = Object.freeze({
-  run_request: ['requestId', 'sessionId', 'input', 'text', 'agentMode', 'modelPreference', 'reasoningPreference', 'toolPermissionMode', 'attachments'],
+  [SPARK_OPEN_REQUEST]: [],
+  run_request: ['requestId', 'sessionId', 'input', 'text', 'agentMode', 'modelPreference', 'reasoningPreference', 'toolPermissionMode', 'attachments', 'approvalMode'],
+  ...APPROVAL_FIELDS,
   steer_request: ['requestId', 'steerId', 'text'],
   tool_approval_response: ['approvalId', 'approved', 'reason'],
   'request.events.request': ['requestId', 'afterSeq'],
@@ -21,6 +26,8 @@ const FIELDS = Object.freeze({
   subscribe_request: ['requestId'],
 });
 const RESPONSES = Object.freeze({
+  [SPARK_OPEN_REQUEST]: SPARK_OPEN_RESPONSE,
+  ...APPROVAL_RESPONSES,
   'request.events.request': 'request.events.response',
   'session.list.request': 'session.list.response',
   'session.snapshot.request': 'session.snapshot.response',
@@ -48,6 +55,7 @@ function run(value, allowedModes) {
   });
   optional(value, result, 'modelPreference', modelPreference);
   optional(value, result, 'reasoningPreference', reasoningPreference);
+  optional(value, result, 'approvalMode', durableApprovalMode);
   const mode = Object.hasOwn(value, 'toolPermissionMode') ? value.toolPermissionMode : 'ask';
   if (!MODES.includes(mode)) fail();
   if (!Array.isArray(allowedModes) || !allowedModes.includes(mode)) fail('forbidden');
@@ -57,8 +65,10 @@ function run(value, allowedModes) {
 }
 
 function normalize(value, allowedModes) {
+  if (isApprovalCommand(value.type)) return normalizeApprovalCommand(value);
   const result = { type: value.type };
   switch (value.type) {
+    case SPARK_OPEN_REQUEST: return result;
     case 'run_request': return run(value, allowedModes);
     case 'subscribe_request': return { ...result, requestId: id(value.requestId) };
     case 'steer_request': return { ...result, requestId: id(value.requestId), steerId: id(value.steerId), text: text(value.text) };

package/src/protocol/spark-chat-protocol.mjs

@@ -0,0 +1,51 @@
+import { id, string, fail } from './protocol-validation.mjs';
+
+export const SPARK_SESSION_ID = 'spark-companion';
+export const SPARK_CHAT_FEATURE = 'spark_chat_v1';
+export const SPARK_OPEN_REQUEST = 'spark.chat.open.request';
+export const SPARK_OPEN_RESPONSE = 'spark.chat.open.response';
+
+const MODES = new Set(['ask', 'full_access', 'full_plus']);
+const READINESS = new Set(['ready', 'model_required', 'model_unavailable']);
+const ERRORS = new Set(['invalid_spark_chat_request', 'spark_chat_session_unavailable',
+  'spark_chat_model_required', 'spark_chat_model_unavailable', 'spark_chat_permission_mismatch',
+  'spark_chat_unsupported', 'spark_chat_unavailable']);
+
+export function supportsSparkChat(runtime) {
+  if (runtime === undefined) return true;
+  if (runtime.online !== true) return false;
+  return Array.isArray(runtime.features) && runtime.features.includes(SPARK_CHAT_FEATURE);
+}
+
+function isSparkChatCommand(command) {
+  if (command.type === SPARK_OPEN_REQUEST) return true;
+  return command.type === 'run_request' && command.sessionId === SPARK_SESSION_ID;
+}
+
+/** The existing authenticated runtime grant remains the authority ceiling. */
+export function assertSparkChatSupported(command, runtime) {
+  if (!isSparkChatCommand(command)) return;
+  if (!runtime.features.includes(SPARK_CHAT_FEATURE)) fail('spark_chat_unsupported');
+}
+
+function projectSparkChatState(body) {
+  if (body.sessionId !== SPARK_SESSION_ID) fail();
+  if (!MODES.has(body.toolPermissionMode) || !READINESS.has(body.readiness)) fail();
+  const modelProfileId = body.modelProfileId === null ? null : string(body.modelProfileId, 256);
+  if ((modelProfileId === null) !== (body.readiness === 'model_required')) fail();
+  return { sessionId: SPARK_SESSION_ID, modelProfileId,
+    toolPermissionMode: body.toolPermissionMode, readiness: body.readiness };
+}
+
+/** Only chat state crosses the relay; preferences and private diagnostics never do. */
+export function projectSparkOpenResponse(body) {
+  try {
+    if (!body || body.type !== SPARK_OPEN_RESPONSE || typeof body.ok !== 'boolean') return null;
+    const result = { type: SPARK_OPEN_RESPONSE, correlationId: id(body.correlationId), ok: body.ok };
+    if (body.ok) return { ...result, ...projectSparkChatState(body) };
+    if (!ERRORS.has(body.error)) return null;
+    return { ...result, error: body.error };
+  } catch {
+    return null;
+  }
+}