@openclaw/gateway-protocol 0.0.0 → 2026.7.2-beta.5

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog — @openclaw/gateway-protocol
+
+Wire-protocol and schema contracts for the OpenClaw Gateway (WebSocket JSON-RPC-style
+frames, handshake, and method/event payload schemas). Protocol version is negotiated
+per connection via `minProtocol`/`maxProtocol`. This log covers the wire protocol
+version and the additive schema surface. Dates are authoring dates (2026).
+
+## Unreleased
+
+- Add semantic `agent` / `system` roster kinds negotiated through the `agent-kind` client capability.
+- Rename structured-question item `id` to `questionId` and flatten keyed answer arrays.
+- Slim worker and session-catalog payloads to the active wire contract.
+- Remove dead protocol surfaces and add since-vintage metadata to retained schemas and methods.
+
+## Protocol v4 (current)
+
+Introduced 2026-05-07 (commit `330ba1f`). The stable, current wire version.
+
+Wire contract:
+- Frame envelopes: `req` / `res` / `event`, discriminated on `type`.
+- Handshake: client sends `ConnectParams` (advertises `minProtocol`/`maxProtocol`,
+  client identity, `caps`, `commands`, `permissions`, `role`/`scopes`, optional signed
+  `device` identity, and an `auth` bag: token / bootstrapToken / deviceToken / password /
+  approvalRuntimeToken / agentRuntimeIdentityToken).
+- Server replies `hello-ok` with the negotiated `protocol`, server identity, the live
+  `features` map (`methods`, `events`, `capabilities`), initial `snapshot`, minted `auth`
+  device tokens, and connection `policy` (maxPayload / maxBufferedBytes / tickIntervalMs).
+- Server events: `tick` heartbeat and `shutdown` notice; event frames may carry `seq`
+  and `stateVersion` for ordered state sync.
+
+Changed vs v3:
+- `hello-ok` handshake replaced the single `canvasHostUrl` string with a
+  `pluginSurfaceUrls` map (canvas generalized into arbitrary plugin surfaces). This
+  field change is the breaking bump behind v4.
+- Later additively extended (no bump) with `controlUiTabs` (plugin-declared Control UI
+  tabs) and multi-`deviceTokens` in the handshake auth block.
+
+Compatibility window (`version.ts`):
+- `MIN_CLIENT_PROTOCOL_VERSION = 4` — general clients must speak v4.
+- `MIN_NODE_PROTOCOL_VERSION = 3` and `MIN_PROBE_PROTOCOL_VERSION = 3` — authenticated
+  nodes and lightweight probes are accepted at N-1 (v3) to stay manageable during
+  rolling upgrades. Added 2026-07-06 (#101109).
+- A transient v5 (2026-05-16, `07f05e9`) renamed `inboundTurnKind` -> `inboundEventKind`;
+  it was reverted the next day (2026-05-17, `ad155fb`, "restore v4 message action
+  protocol"). v5 never shipped as a stable ceiling; v4 remains current.
+
+## Protocol v3
+
+Baseline wire version. Present since repo genesis (2026-04-21) as an inline literal in
+`protocol-schemas.ts`; extracted into `version.ts` unchanged on 2026-05-04 (`2949171`).
+The first externally-relevant version — there is no 2->3 bump in tracked history.
+
+Established the still-current shape: `req`/`res`/`event` frame envelopes, the
+`ConnectParams` -> `hello-ok` handshake with protocol negotiation, `snapshot` state sync,
+and the founding method/event families: sessions, agent chat, cron, devices, nodes,
+channels, config, commands, logs-chat, exec-approvals, plugin-approvals, secrets, push,
+wizard. (v3 `hello-ok` carried `canvasHostUrl`; v4 replaced it — see above.)
+
+## Schema surface history
+
+Additive method/event/schema families added over time. Pure refactors, test-only, and
+docs commits are omitted. The package was extracted from `src/gateway/protocol` to
+`packages/gateway-protocol` on 2026-05-29 (#87797); paths before that date lived under
+the old tree.
+
+### 2026-04 (v3 baseline era)
+
+- Ship baseline families: frames/handshake, sessions, agent chat, cron, devices, nodes,
+  channels, config, commands, logs-chat, exec-approvals, plugin-approvals, secrets, push,
+  wizard, snapshot, primitives, agents-models-skills.
+- Add WhatsApp `replyToMode` quoting (#62305).
+- Add browser realtime Talk and transports — origin of the talk/voice families.
+- Add Control UI PWA web push support (#44590).
+- Add plugins and artifacts schema modules.
+- Add OpenClaw SDK package and authenticated iOS background presence beacon (#73330).
+
+### 2026-05
+
+- Add environments discovery RPCs (#74867) and task-ledger RPCs (#74847) — tasks family.
+- Add unified Talk gateway sessions, realtime active-run control, and typed `sessionKey`
+  on the wake protocol.
+- Add SDK `tools.invoke` RPC; extend cron with agentId filtering (#77602), run
+  diagnostics (#75928), and direct job lookup.
+- Add Skill Workshop gateway methods: proposal files, revision requests, persisted origin.
+- Add core session goals (#87469).
+- Add heartbeat flag on agent event broadcast (#80610), warm-MCP effective inventory, and
+  plugin approval action metadata.
+- Harden auth/device identity: bind approval access to requester metadata (#81380);
+  require approval for setup-code device pairing (#81292); scope Talk session to resolver.
+- Introduce and revert transient protocol v5 (`07f05e9` / `ad155fb`).
+
+### 2026-06
+
+Enhancement-only month (no new schema modules):
+- Extend cron with command jobs, compact list responses (#93395), and an on-exit
+  schedule kind that fires when a watched command exits.
+- Forward-port fast-Talks auto mode (#85104); add session workspace rail (#92856).
+
+### 2026-07 (largest expansion)
+
+- Add terminal family: `terminal.*` RPC methods/events, detach/reattach with output
+  replay, `terminal.list`/`terminal.text`, and file uploads into terminals (#107364).
+- Add managed git worktrees: lifecycle create/provision/snapshot/restore/GC (#100535),
+  new-session-in-worktree (#100788), session worktree targeting and branch listing
+  (#103432); add read-only `agents.workspace` browsing RPCs (#100738).
+- Add audit family: metadata-only message audit events (#103903), native-search audit
+  correlation (#98704), and audit-activity schema.
+- Add `tts.speak` returning synthesized audio inline (#100770).
+- Add cooperative host suspension / gateway-suspend prepare/status/resume RPCs (#103618).
+- Add durable approvals: persisted operator approvals (#103579), typed cross-surface
+  approval actions (#103679), approval-id, and the durable-approvals stack (#104837).
+- Add cloud-workers stack: durable environments + lifecycle RPCs (#104401), worker bundle
+  + SSH bootstrap + admission handshake (#104532), authenticated worker protocol with
+  minted credentials (#104688), durable transcript commit (#104809), live-event streaming
+  (#105275), inference proxy (#105719), and session placement/dispatch (#106332).
+- Add session catalog: sessions-catalog + sessions-create with external-session
+  pagination unification (#104717).
+- Add fs family: `sessions.files.set` hash-CAS writes (#104757) and gateway/node folder
+  browsing (#105114).
+- Add node-hosted plugins — dynamic tools, MCP servers, skills (#90431) — plus node
+  invoke/presence protocol schemas.
+- Add migrations family: log-migration protocol schemas and Codex/Claude memory import
+  (#106406).
+- Add durable device rename for human-friendly device names (#94517).
+- Add follow-up task suggestions (#102422) and task-suggestions schema.
+- Add cron event triggers via polled condition-watcher scripts (#101195) and native
+  mobile Automations parity (#106355).
+- Add system-agent conversational onboarding (#99935); rename `crestodian.*` methods to
+  `openclaw.chat` / `openclaw.setup.*` (2026-07-14, `a6a0716`).
+- Add typed structured questions / `ask_user` with live option cards (#109922, #110242)
+  and the questions schema module.
+- Add ui-command / screen-tool Control UI layout control and capability-gated
+  `show_widget` inline web chat widgets (#101840).
+- Add direct watch/watchOS node connect to Gateway (#102893); widen node/probe protocol
+  acceptance to N-1 (#101109).
+
+## Notes for external versioning
+
+- Post-v4 changes are additive except: the transient v5 rename (reverted, net-zero) and
+  the 2026-07-14 `crestodian.*` -> `openclaw.*` method rename. The renamed feature was
+  introduced only 9 days earlier (2026-07-05, #99935), never left the v4 window, and
+  predates public publish, so no released method name changed under v4.
+- `schema/types.ts` was removed 2026-07-11 (#103679); it re-exported compile-time type
+  aliases only and has no wire impact.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# OpenClaw Gateway Protocol
+# `@openclaw/gateway-protocol`
 
-Reserved package name. Release artifacts are published by OpenClaw release automation.
+Typed schemas, inferred TypeScript types, and runtime validators for the OpenClaw
+Gateway WebSocket protocol.
+
+The current wire protocol is version 4. General clients must use v4; authenticated
+node clients and lightweight probes may use the N-1 window during rolling upgrades.
+See the [Gateway protocol specification](https://docs.openclaw.ai/gateway/protocol)
+for transport, authentication, roles, scopes, and complete frame examples.
+
+## Versioning
+
+Package versions follow the OpenClaw calendar release train:
+`YYYY.M.PATCH`, with the same prerelease suffix when applicable. A package version
+therefore identifies the OpenClaw source release that produced the schemas; it is
+not the wire protocol number.
+
+The wire protocol integer is versioned separately. Its current value is exported
+as `PROTOCOL_VERSION` from `@openclaw/gateway-protocol/version`. Gateway protocol
+changes are additive first. An incompatible wire change requires an explicit
+protocol-version decision and coordinated client follow-through. See
+[`CHANGELOG.md`](./CHANGELOG.md) for the wire and schema history.
+
+## Install
+
+```bash
+npm install @openclaw/gateway-protocol
+```
+
+## Entry points
+
+- `@openclaw/gateway-protocol` exports runtime validators, selected schemas, error
+  formatting, and their TypeScript types. This is the main TypeBox-backed entry.
+- `@openclaw/gateway-protocol/schema` exports the TypeBox schema graph, including
+  the `ProtocolSchemas` registry used by generators.
+- `@openclaw/gateway-protocol/frame-guards` exports dependency-free structural
+  guards for gateway event and response envelopes.
+- `@openclaw/gateway-protocol/client-info` exports client ID, mode, and capability
+  registries plus normalization helpers.
+- `@openclaw/gateway-protocol/connect-error-details` exports structured connect
+  error readers and recovery metadata.
+- `@openclaw/gateway-protocol/gateway-error-details` exports helpers for reading
+  structured details from general gateway errors.
+- `@openclaw/gateway-protocol/startup-unavailable` exports startup retry constants
+  and helpers.
+- `@openclaw/gateway-protocol/version` exports the current and minimum accepted
+  protocol versions.
+
+The `frame-guards`, `client-info`, `connect-error-details`, `gateway-error-details`,
+`startup-unavailable`, and `version` entry points are TypeBox-free. Prefer them when
+a browser bundle only needs envelope dispatch, handshake constants, or reconnect
+policy. This also avoids runtime compilation in CSP-sensitive consumers. The root
+and `schema` entry points provide the full validation surface and depend on TypeBox.
+
+## Validate an inbound frame
+
+The compiled validators are callable type guards. Their `errors` property contains
+the most recent validation errors.
+
+```ts
+import { formatValidationErrors, validateRequestFrame } from "@openclaw/gateway-protocol";
+
+const frame: unknown = JSON.parse(inboundText);
+
+if (!validateRequestFrame(frame)) {
+  throw new Error(formatValidationErrors(validateRequestFrame.errors));
+}
+
+console.log(frame.id, frame.method);
+```
+
+`validateRequestFrame` validates the request envelope. Dispatch code must also use
+the validator for the selected method's `params`; the root entry point exports those
+validators as `validate*Params` functions.
+
+## Guard an event without TypeBox
+
+Use the lightweight guards when code only needs safe frame discrimination. They
+check dispatch-critical envelope fields and intentionally allow additive payload
+fields.
+
+```ts
+import { isGatewayEventFrame } from "@openclaw/gateway-protocol/frame-guards";
+
+const frame: unknown = JSON.parse(inboundText);
+
+if (isGatewayEventFrame(frame)) {
+  console.log(frame.event, frame.seq);
+}
+```
+
+## Build handshake version and capability fields
+
+Protocol levels and client capabilities live in TypeBox-free entry points.
+
+```ts
+import { GATEWAY_CLIENT_CAPS } from "@openclaw/gateway-protocol/client-info";
+import { MIN_CLIENT_PROTOCOL_VERSION, PROTOCOL_VERSION } from "@openclaw/gateway-protocol/version";
+
+const handshake = {
+  minProtocol: MIN_CLIENT_PROTOCOL_VERSION,
+  maxProtocol: PROTOCOL_VERSION,
+  caps: [GATEWAY_CLIENT_CAPS.TOOL_EVENTS],
+};
+```
+
+Nodes and probes use `MIN_NODE_PROTOCOL_VERSION` and
+`MIN_PROBE_PROTOCOL_VERSION`, respectively. A capability advertises client support;
+it does not grant authorization.
+
+## Contract notes
+
+### Session identifiers
+
+Several identifier names coexist because they identify different things:
+
+- `key` is the established logical session selector used by most `sessions.*`
+  CRUD, send, subscription, patch, reset, delete, compaction, and usage methods.
+  A key can be canonicalized or resolved within an agent's session store.
+- `sessionKey` names the same logical routing identity where the contract needs to
+  make that meaning explicit. `chat.*`, session file and diff APIs, transcript
+  branch/rewind/fork APIs, agent events, and channel delivery payloads use this
+  spelling.
+- `sessionId` is the opaque stored transcript or runtime instance ID. Session
+  results may return it beside a key. Talk, terminal, worker, and selected channel
+  protocols also use `sessionId` for their own concrete session instances; do not
+  substitute a logical session key there.
+
+Follow each method schema rather than converting fields based on their spelling.
+`sessions.resolve` is the explicit bridge when a caller has a key, raw session ID,
+label, or parent/agent scope.
+
+### Intentionally open fields
+
+The schema graph is strict by default, but roughly 60 fields intentionally use
+`Type.Unknown()` passthroughs. The main clusters are transport-owned channel
+payloads, logs-chat message and attachment passthrough, worker and node tool
+arguments/results, and the dynamic `config.schema` response. Frame `params`,
+`payload`, and error `details` are also open at the envelope layer because the
+selected method, event, or error code owns their concrete shape.
+
+Do not treat these fields as validated domain objects. Narrow them at their owner
+boundary before reading nested values.
+
+### Machine-readable schema
+
+`protocol.schema.json` ships in the npm tarball as the generated machine-readable
+contract. It contains the frame union, named schema definitions, and core method
+metadata. It is generated during `prepack` and is not committed to the repository.
+
+### Method discovery
+
+The `hello-ok.features.methods` list is conservative discovery, not a complete
+enumeration of every callable method. It reflects the methods the connected
+Gateway intentionally advertises. Core-internal, role-specific, plugin-provided,
+or otherwise non-advertised methods can have valid schemas without appearing in
+that list. Clients should use discovery to enable optional UI, not to reject an
+otherwise documented method contract.

package/dist/client-info.d.mts

@@ -0,0 +1,94 @@
+//#region src/client-info.d.ts
+/** Canonical client ids accepted in gateway hello/connect payloads. */
+declare const GATEWAY_CLIENT_IDS: {
+  readonly WEBCHAT_UI: "webchat-ui";
+  readonly CONTROL_UI: "openclaw-control-ui";
+  readonly BROWSER_COPILOT: "openclaw-browser-copilot";
+  readonly TUI: "openclaw-tui";
+  readonly WEBCHAT: "webchat";
+  readonly CLI: "cli";
+  readonly GATEWAY_CLIENT: "gateway-client";
+  readonly MACOS_APP: "openclaw-macos";
+  readonly LINUX_APP: "openclaw-linux";
+  readonly IOS_APP: "openclaw-ios";
+  readonly WATCHOS_APP: "openclaw-watchos";
+  readonly ANDROID_APP: "openclaw-android";
+  readonly NODE_HOST: "node-host";
+  readonly WORKER: "openclaw-worker";
+  readonly TEST: "test";
+  readonly FINGERPRINT: "fingerprint";
+  readonly PROBE: "openclaw-probe";
+};
+/** Stable gateway client ids used on the wire during hello/connect handshakes. */
+type GatewayClientId = (typeof GATEWAY_CLIENT_IDS)[keyof typeof GATEWAY_CLIENT_IDS];
+declare const GATEWAY_CLIENT_NAMES: {
+  readonly WEBCHAT_UI: "webchat-ui";
+  readonly CONTROL_UI: "openclaw-control-ui";
+  readonly BROWSER_COPILOT: "openclaw-browser-copilot";
+  readonly TUI: "openclaw-tui";
+  readonly WEBCHAT: "webchat";
+  readonly CLI: "cli";
+  readonly GATEWAY_CLIENT: "gateway-client";
+  readonly MACOS_APP: "openclaw-macos";
+  readonly LINUX_APP: "openclaw-linux";
+  readonly IOS_APP: "openclaw-ios";
+  readonly WATCHOS_APP: "openclaw-watchos";
+  readonly ANDROID_APP: "openclaw-android";
+  readonly NODE_HOST: "node-host";
+  readonly WORKER: "openclaw-worker";
+  readonly TEST: "test";
+  readonly FINGERPRINT: "fingerprint";
+  readonly PROBE: "openclaw-probe";
+};
+/** Compatibility alias for internal callers that still use "name" terminology. */
+type GatewayClientName = GatewayClientId;
+/** Coarse modes let policy group clients without matching every product id. */
+declare const GATEWAY_CLIENT_MODES: {
+  readonly WEBCHAT: "webchat";
+  readonly CLI: "cli";
+  readonly UI: "ui";
+  readonly BACKEND: "backend";
+  readonly NODE: "node";
+  readonly WORKER: "worker";
+  readonly PROBE: "probe";
+  readonly TEST: "test";
+};
+/** Coarse client category used for gateway policy and diagnostics. */
+type GatewayClientMode = (typeof GATEWAY_CLIENT_MODES)[keyof typeof GATEWAY_CLIENT_MODES];
+/** Client metadata sent during gateway connection setup. */
+type GatewayClientInfo = {
+  /** Stable product/client identifier from `GATEWAY_CLIENT_IDS`. */id: GatewayClientId; /** Human-readable label for diagnostics; not used for policy decisions. */
+  displayName?: string; /** Client app or package version reported by the connecting process. */
+  version: string; /** Runtime platform string, such as `darwin`, `ios`, `android`, or `web`. */
+  platform: string; /** Optional device family used by native clients for display and routing hints. */
+  deviceFamily?: string; /** Native hardware/model identifier when available. */
+  modelIdentifier?: string; /** Coarse category from `GATEWAY_CLIENT_MODES` for policy and diagnostics. */
+  mode: GatewayClientMode; /** Per-installation or per-process id used to distinguish same-product clients. */
+  instanceId?: string;
+};
+/** Capability flags a client may advertise during the gateway handshake. */
+declare const GATEWAY_CLIENT_CAPS: {
+  readonly AGENT_KIND: "agent-kind";
+  readonly APPROVALS: "approvals";
+  readonly EXEC_APPROVALS: "exec-approvals";
+  readonly INLINE_WIDGETS: "inline-widgets";
+  readonly RUN_TOOL_BINDINGS: "run-tool-bindings";
+  readonly SESSION_SCOPED_EVENTS: "session-scoped-events";
+  readonly PLUGIN_APPROVALS: "plugin-approvals";
+  readonly TASK_SUGGESTIONS: "task-suggestions";
+  readonly TERMINAL_OFFSET_SEQ: "terminal-offset-seq";
+  readonly TOOL_EVENTS: "tool-events";
+  readonly UI_COMMANDS: "ui-commands";
+};
+/** Optional capability advertised by clients during gateway handshake. */
+type GatewayClientCap = (typeof GATEWAY_CLIENT_CAPS)[keyof typeof GATEWAY_CLIENT_CAPS];
+/** Normalizes untrusted client ids and rejects unknown values. */
+declare function normalizeGatewayClientId(raw?: string | null): GatewayClientId | undefined;
+/** Normalizes legacy client-name fields through the canonical client-id registry. */
+declare function normalizeGatewayClientName(raw?: string | null): GatewayClientName | undefined;
+/** Normalizes untrusted client modes and rejects unknown values. */
+declare function normalizeGatewayClientMode(raw?: string | null): GatewayClientMode | undefined;
+/** Checks a client-advertised capability list without treating missing caps as errors. */
+declare function hasGatewayClientCap(caps: string[] | null | undefined, cap: GatewayClientCap): boolean;
+//#endregion
+export { GATEWAY_CLIENT_CAPS, GATEWAY_CLIENT_IDS, GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, GatewayClientCap, GatewayClientId, GatewayClientInfo, GatewayClientMode, GatewayClientName, hasGatewayClientCap, normalizeGatewayClientId, normalizeGatewayClientMode, normalizeGatewayClientName };

package/dist/client-info.mjs

@@ -0,0 +1,82 @@
+//#region src/client-info.ts
+/**
+* Shared gateway client identity contract.
+*
+* These values cross the WebSocket handshake boundary, so additions must stay
+* aligned with protocol schemas and server policy checks.
+*/
+function normalizeOptionalLowercaseString(raw) {
+	if (typeof raw !== "string") return;
+	return raw.trim().toLowerCase() || void 0;
+}
+/** Canonical client ids accepted in gateway hello/connect payloads. */
+const GATEWAY_CLIENT_IDS = {
+	WEBCHAT_UI: "webchat-ui",
+	CONTROL_UI: "openclaw-control-ui",
+	BROWSER_COPILOT: "openclaw-browser-copilot",
+	TUI: "openclaw-tui",
+	WEBCHAT: "webchat",
+	CLI: "cli",
+	GATEWAY_CLIENT: "gateway-client",
+	MACOS_APP: "openclaw-macos",
+	LINUX_APP: "openclaw-linux",
+	IOS_APP: "openclaw-ios",
+	WATCHOS_APP: "openclaw-watchos",
+	ANDROID_APP: "openclaw-android",
+	NODE_HOST: "node-host",
+	WORKER: "openclaw-worker",
+	TEST: "test",
+	FINGERPRINT: "fingerprint",
+	PROBE: "openclaw-probe"
+};
+const GATEWAY_CLIENT_NAMES = GATEWAY_CLIENT_IDS;
+/** Coarse modes let policy group clients without matching every product id. */
+const GATEWAY_CLIENT_MODES = {
+	WEBCHAT: "webchat",
+	CLI: "cli",
+	UI: "ui",
+	BACKEND: "backend",
+	NODE: "node",
+	WORKER: "worker",
+	PROBE: "probe",
+	TEST: "test"
+};
+/** Capability flags a client may advertise during the gateway handshake. */
+const GATEWAY_CLIENT_CAPS = {
+	AGENT_KIND: "agent-kind",
+	APPROVALS: "approvals",
+	EXEC_APPROVALS: "exec-approvals",
+	INLINE_WIDGETS: "inline-widgets",
+	RUN_TOOL_BINDINGS: "run-tool-bindings",
+	SESSION_SCOPED_EVENTS: "session-scoped-events",
+	PLUGIN_APPROVALS: "plugin-approvals",
+	TASK_SUGGESTIONS: "task-suggestions",
+	TERMINAL_OFFSET_SEQ: "terminal-offset-seq",
+	TOOL_EVENTS: "tool-events",
+	UI_COMMANDS: "ui-commands"
+};
+const GATEWAY_CLIENT_ID_SET = new Set(Object.values(GATEWAY_CLIENT_IDS));
+const GATEWAY_CLIENT_MODE_SET = new Set(Object.values(GATEWAY_CLIENT_MODES));
+/** Normalizes untrusted client ids and rejects unknown values. */
+function normalizeGatewayClientId(raw) {
+	const normalized = normalizeOptionalLowercaseString(raw);
+	if (!normalized) return;
+	return GATEWAY_CLIENT_ID_SET.has(normalized) ? normalized : void 0;
+}
+/** Normalizes legacy client-name fields through the canonical client-id registry. */
+function normalizeGatewayClientName(raw) {
+	return normalizeGatewayClientId(raw);
+}
+/** Normalizes untrusted client modes and rejects unknown values. */
+function normalizeGatewayClientMode(raw) {
+	const normalized = normalizeOptionalLowercaseString(raw);
+	if (!normalized) return;
+	return GATEWAY_CLIENT_MODE_SET.has(normalized) ? normalized : void 0;
+}
+/** Checks a client-advertised capability list without treating missing caps as errors. */
+function hasGatewayClientCap(caps, cap) {
+	if (!Array.isArray(caps)) return false;
+	return caps.includes(cap);
+}
+//#endregion
+export { GATEWAY_CLIENT_CAPS, GATEWAY_CLIENT_IDS, GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, hasGatewayClientCap, normalizeGatewayClientId, normalizeGatewayClientMode, normalizeGatewayClientName };

package/dist/connect-error-details.d.mts

@@ -0,0 +1,114 @@
+//#region src/connect-error-details.d.ts
+/** Structured connect-error codes carried in gateway error `details.code`. */
+declare const ConnectErrorDetailCodes: {
+  readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+  readonly AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED";
+  readonly AUTH_TOKEN_MISSING: "AUTH_TOKEN_MISSING";
+  readonly AUTH_TOKEN_MISMATCH: "AUTH_TOKEN_MISMATCH";
+  readonly AUTH_TOKEN_NOT_CONFIGURED: "AUTH_TOKEN_NOT_CONFIGURED";
+  readonly AUTH_PASSWORD_MISSING: "AUTH_PASSWORD_MISSING";
+  readonly AUTH_PASSWORD_MISMATCH: "AUTH_PASSWORD_MISMATCH";
+  readonly AUTH_PASSWORD_NOT_CONFIGURED: "AUTH_PASSWORD_NOT_CONFIGURED";
+  readonly AUTH_BOOTSTRAP_TOKEN_INVALID: "AUTH_BOOTSTRAP_TOKEN_INVALID";
+  readonly AUTH_DEVICE_TOKEN_MISMATCH: "AUTH_DEVICE_TOKEN_MISMATCH";
+  readonly AUTH_SCOPE_MISMATCH: "AUTH_SCOPE_MISMATCH";
+  readonly AUTH_RATE_LIMITED: "AUTH_RATE_LIMITED";
+  readonly AUTH_TAILSCALE_IDENTITY_MISSING: "AUTH_TAILSCALE_IDENTITY_MISSING";
+  readonly AUTH_TAILSCALE_PROXY_MISSING: "AUTH_TAILSCALE_PROXY_MISSING";
+  readonly AUTH_TAILSCALE_WHOIS_FAILED: "AUTH_TAILSCALE_WHOIS_FAILED";
+  readonly AUTH_TAILSCALE_IDENTITY_MISMATCH: "AUTH_TAILSCALE_IDENTITY_MISMATCH";
+  readonly CONTROL_UI_ORIGIN_NOT_ALLOWED: "CONTROL_UI_ORIGIN_NOT_ALLOWED";
+  readonly PROTOCOL_MISMATCH: "PROTOCOL_MISMATCH";
+  readonly CONTROL_UI_DEVICE_IDENTITY_REQUIRED: "CONTROL_UI_DEVICE_IDENTITY_REQUIRED";
+  readonly DEVICE_IDENTITY_REQUIRED: "DEVICE_IDENTITY_REQUIRED";
+  readonly DEVICE_AUTH_INVALID: "DEVICE_AUTH_INVALID";
+  readonly DEVICE_AUTH_DEVICE_ID_MISMATCH: "DEVICE_AUTH_DEVICE_ID_MISMATCH";
+  readonly DEVICE_AUTH_SIGNATURE_EXPIRED: "DEVICE_AUTH_SIGNATURE_EXPIRED";
+  readonly DEVICE_AUTH_NONCE_REQUIRED: "DEVICE_AUTH_NONCE_REQUIRED";
+  readonly DEVICE_AUTH_NONCE_MISMATCH: "DEVICE_AUTH_NONCE_MISMATCH";
+  readonly DEVICE_AUTH_SIGNATURE_INVALID: "DEVICE_AUTH_SIGNATURE_INVALID";
+  readonly DEVICE_AUTH_PUBLIC_KEY_INVALID: "DEVICE_AUTH_PUBLIC_KEY_INVALID";
+  readonly PAIRING_REQUIRED: "PAIRING_REQUIRED";
+  readonly CLIENT_VERSION_MISMATCH: "CLIENT_VERSION_MISMATCH";
+};
+type ConnectErrorDetailCode = (typeof ConnectErrorDetailCodes)[keyof typeof ConnectErrorDetailCodes];
+/** Pairing-specific reasons clients can display and use for reconnect policy. */
+declare const ConnectPairingRequiredReasons: {
+  readonly NOT_PAIRED: "not-paired";
+  readonly ROLE_UPGRADE: "role-upgrade";
+  readonly SCOPE_UPGRADE: "scope-upgrade";
+  readonly METADATA_UPGRADE: "metadata-upgrade";
+};
+type ConnectPairingRequiredReason = (typeof ConnectPairingRequiredReasons)[keyof typeof ConnectPairingRequiredReasons];
+/** Suggested client-side recovery action for structured connect errors. */
+type ConnectRecoveryNextStep = "retry_with_device_token" | "update_auth_configuration" | "update_auth_credentials" | "wait_then_retry" | "review_auth_configuration";
+/** Optional retry guidance extracted from gateway connect-error details. */
+type ConnectErrorRecoveryAdvice = {
+  canRetryWithDeviceToken?: boolean;
+  recommendedNextStep?: ConnectRecoveryNextStep;
+};
+/** Full structured details for pairing-required connect failures. */
+type PairingConnectErrorDetails = {
+  code: typeof ConnectErrorDetailCodes.PAIRING_REQUIRED;
+  reason?: ConnectPairingRequiredReason;
+  requestId?: string;
+  remediationHint?: string;
+  recommendedNextStep?: ConnectRecoveryNextStep;
+  retryable?: boolean;
+  pauseReconnect?: boolean;
+  deviceId?: string;
+  requestedRole?: string;
+  requestedScopes?: string[];
+  approvedRoles?: string[];
+  approvedScopes?: string[];
+};
+/** Compact pairing-required subset used by reconnect/status surfaces. */
+type ConnectPairingRequiredDetails = Pick<PairingConnectErrorDetails, "reason" | "requestId">;
+/** Maps internal auth failure reasons to public connect-error detail codes. */
+declare function resolveAuthConnectErrorDetailCode(reason: string | undefined): ConnectErrorDetailCode;
+/** Maps device-auth verifier reasons to public connect-error detail codes. */
+declare function resolveDeviceAuthConnectErrorDetailCode(reason: string | undefined): ConnectErrorDetailCode;
+/** Reads a non-empty detail code from an untrusted error details payload. */
+declare function readConnectErrorDetailCode(details: unknown): string | null;
+/** Extracts normalized retry advice from untrusted connect-error details. */
+declare function readConnectErrorRecoveryAdvice(details: unknown): ConnectErrorRecoveryAdvice;
+/** Normalizes pairing request ids before echoing them in close reasons or UI text. */
+declare function normalizePairingConnectRequestId(value: unknown): string | undefined;
+/** Human-readable requirement summary for a pairing-required reason. */
+declare function describePairingConnectRequirement(reason: ConnectPairingRequiredReason | undefined): string;
+/** Builds the gateway close/error message for a pairing-required connect failure. */
+declare function buildPairingConnectErrorMessage(reason: ConnectPairingRequiredReason | undefined): string;
+/** Short user-facing recovery title for pairing-required connect failures. */
+declare function buildPairingConnectRecoveryTitle(reason: ConnectPairingRequiredReason | undefined): string;
+/** Builds sanitized structured details for a pairing-required connect failure. */
+declare function buildPairingConnectErrorDetails(params: {
+  reason: ConnectPairingRequiredReason | undefined;
+  requestId?: string;
+  remediationHint?: string;
+  recommendedNextStep?: ConnectRecoveryNextStep;
+  retryable?: boolean;
+  pauseReconnect?: boolean;
+  deviceId?: string;
+  requestedRole?: string;
+  requestedScopes?: string[];
+  approvedRoles?: string[];
+  approvedScopes?: string[];
+}): PairingConnectErrorDetails;
+/** Builds a sanitized close reason string for WebSocket pairing rejections. */
+declare function buildPairingConnectCloseReason(params: {
+  reason: ConnectPairingRequiredReason | undefined;
+  requestId?: string;
+}): string;
+/** Reads and backfills pairing-required details from an untrusted details object. */
+declare function readPairingConnectErrorDetails(details: unknown): PairingConnectErrorDetails | null;
+/** Parses legacy/string-only pairing-required messages into structured details. */
+declare function readConnectPairingRequiredMessage(message: string | null | undefined): ConnectPairingRequiredDetails | null;
+/** Formats pairing-required details into the canonical user-facing message. */
+declare function formatConnectPairingRequiredMessage(details: unknown): string;
+/** Formats connect errors using structured details before falling back to raw messages. */
+declare function formatConnectErrorMessage(params: {
+  message?: string;
+  details?: unknown;
+}): string;
+//#endregion
+export { ConnectErrorDetailCodes, ConnectPairingRequiredDetails, ConnectPairingRequiredReason, buildPairingConnectCloseReason, buildPairingConnectErrorDetails, buildPairingConnectErrorMessage, buildPairingConnectRecoveryTitle, describePairingConnectRequirement, formatConnectErrorMessage, formatConnectPairingRequiredMessage, normalizePairingConnectRequestId, readConnectErrorDetailCode, readConnectErrorRecoveryAdvice, readConnectPairingRequiredMessage, readPairingConnectErrorDetails, resolveAuthConnectErrorDetailCode, resolveDeviceAuthConnectErrorDetailCode };