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

package/dist/connect-error-details.mjs

@@ -0,0 +1,296 @@
+//#region src/connect-error-details.ts
+/**
+* Shared gateway connect-error detail helpers.
+*
+* These details cross client/server boundaries, so readers normalize untrusted
+* payloads before using them in reconnect decisions or user-facing messages.
+*/
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function normalizeArrayBackedTrimmedStringList(value) {
+	if (!Array.isArray(value)) return;
+	const values = value.map((entry) => normalizeOptionalString(entry)).filter((entry) => Boolean(entry));
+	return values.length > 0 ? values : void 0;
+}
+/** Structured connect-error codes carried in gateway error `details.code`. */
+const ConnectErrorDetailCodes = {
+	AUTH_REQUIRED: "AUTH_REQUIRED",
+	AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+	AUTH_TOKEN_MISSING: "AUTH_TOKEN_MISSING",
+	AUTH_TOKEN_MISMATCH: "AUTH_TOKEN_MISMATCH",
+	AUTH_TOKEN_NOT_CONFIGURED: "AUTH_TOKEN_NOT_CONFIGURED",
+	AUTH_PASSWORD_MISSING: "AUTH_PASSWORD_MISSING",
+	AUTH_PASSWORD_MISMATCH: "AUTH_PASSWORD_MISMATCH",
+	AUTH_PASSWORD_NOT_CONFIGURED: "AUTH_PASSWORD_NOT_CONFIGURED",
+	AUTH_BOOTSTRAP_TOKEN_INVALID: "AUTH_BOOTSTRAP_TOKEN_INVALID",
+	AUTH_DEVICE_TOKEN_MISMATCH: "AUTH_DEVICE_TOKEN_MISMATCH",
+	AUTH_SCOPE_MISMATCH: "AUTH_SCOPE_MISMATCH",
+	AUTH_RATE_LIMITED: "AUTH_RATE_LIMITED",
+	AUTH_TAILSCALE_IDENTITY_MISSING: "AUTH_TAILSCALE_IDENTITY_MISSING",
+	AUTH_TAILSCALE_PROXY_MISSING: "AUTH_TAILSCALE_PROXY_MISSING",
+	AUTH_TAILSCALE_WHOIS_FAILED: "AUTH_TAILSCALE_WHOIS_FAILED",
+	AUTH_TAILSCALE_IDENTITY_MISMATCH: "AUTH_TAILSCALE_IDENTITY_MISMATCH",
+	CONTROL_UI_ORIGIN_NOT_ALLOWED: "CONTROL_UI_ORIGIN_NOT_ALLOWED",
+	PROTOCOL_MISMATCH: "PROTOCOL_MISMATCH",
+	CONTROL_UI_DEVICE_IDENTITY_REQUIRED: "CONTROL_UI_DEVICE_IDENTITY_REQUIRED",
+	DEVICE_IDENTITY_REQUIRED: "DEVICE_IDENTITY_REQUIRED",
+	DEVICE_AUTH_INVALID: "DEVICE_AUTH_INVALID",
+	DEVICE_AUTH_DEVICE_ID_MISMATCH: "DEVICE_AUTH_DEVICE_ID_MISMATCH",
+	DEVICE_AUTH_SIGNATURE_EXPIRED: "DEVICE_AUTH_SIGNATURE_EXPIRED",
+	DEVICE_AUTH_NONCE_REQUIRED: "DEVICE_AUTH_NONCE_REQUIRED",
+	DEVICE_AUTH_NONCE_MISMATCH: "DEVICE_AUTH_NONCE_MISMATCH",
+	DEVICE_AUTH_SIGNATURE_INVALID: "DEVICE_AUTH_SIGNATURE_INVALID",
+	DEVICE_AUTH_PUBLIC_KEY_INVALID: "DEVICE_AUTH_PUBLIC_KEY_INVALID",
+	PAIRING_REQUIRED: "PAIRING_REQUIRED",
+	CLIENT_VERSION_MISMATCH: "CLIENT_VERSION_MISMATCH"
+};
+/** Pairing-specific reasons clients can display and use for reconnect policy. */
+const ConnectPairingRequiredReasons = {
+	NOT_PAIRED: "not-paired",
+	ROLE_UPGRADE: "role-upgrade",
+	SCOPE_UPGRADE: "scope-upgrade",
+	METADATA_UPGRADE: "metadata-upgrade"
+};
+const CONNECT_RECOVERY_NEXT_STEP_VALUES = /* @__PURE__ */ new Set([
+	"retry_with_device_token",
+	"update_auth_configuration",
+	"update_auth_credentials",
+	"wait_then_retry",
+	"review_auth_configuration"
+]);
+const CONNECT_PAIRING_REQUIRED_REASON_VALUES = /* @__PURE__ */ new Set([
+	"not-paired",
+	"role-upgrade",
+	"scope-upgrade",
+	"metadata-upgrade"
+]);
+const PAIRING_CONNECT_REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const PAIRING_CONNECT_REASON_METADATA = {
+	"not-paired": {
+		requirement: "device is not approved yet",
+		remediationHint: "Approve this device from the pending pairing requests.",
+		recoveryTitle: "Gateway pairing approval required."
+	},
+	"role-upgrade": {
+		requirement: "device is asking for a higher role than currently approved",
+		remediationHint: "Review the requested role upgrade, then approve the pending request.",
+		recoveryTitle: "Gateway role upgrade approval required."
+	},
+	"scope-upgrade": {
+		requirement: "device is asking for more scopes than currently approved",
+		remediationHint: "Review the requested scopes, then approve the pending upgrade.",
+		recoveryTitle: "Gateway scope upgrade approval required."
+	},
+	"metadata-upgrade": {
+		requirement: "device identity changed and must be re-approved",
+		remediationHint: "Review the refreshed device details, then approve the pending request.",
+		recoveryTitle: "Gateway device refresh approval required."
+	}
+};
+const CONNECT_PAIRING_REQUIRED_MESSAGE_BY_REASON = {
+	"not-paired": "device pairing required",
+	"role-upgrade": "role upgrade pending approval",
+	"scope-upgrade": "scope upgrade pending approval",
+	"metadata-upgrade": "device metadata change pending approval"
+};
+/** Maps internal auth failure reasons to public connect-error detail codes. */
+function resolveAuthConnectErrorDetailCode(reason) {
+	switch (reason) {
+		case "token_missing": return ConnectErrorDetailCodes.AUTH_TOKEN_MISSING;
+		case "token_mismatch": return ConnectErrorDetailCodes.AUTH_TOKEN_MISMATCH;
+		case "token_missing_config": return ConnectErrorDetailCodes.AUTH_TOKEN_NOT_CONFIGURED;
+		case "password_missing": return ConnectErrorDetailCodes.AUTH_PASSWORD_MISSING;
+		case "password_mismatch": return ConnectErrorDetailCodes.AUTH_PASSWORD_MISMATCH;
+		case "password_missing_config": return ConnectErrorDetailCodes.AUTH_PASSWORD_NOT_CONFIGURED;
+		case "bootstrap_token_invalid": return ConnectErrorDetailCodes.AUTH_BOOTSTRAP_TOKEN_INVALID;
+		case "tailscale_user_missing": return ConnectErrorDetailCodes.AUTH_TAILSCALE_IDENTITY_MISSING;
+		case "tailscale_proxy_missing": return ConnectErrorDetailCodes.AUTH_TAILSCALE_PROXY_MISSING;
+		case "tailscale_whois_failed": return ConnectErrorDetailCodes.AUTH_TAILSCALE_WHOIS_FAILED;
+		case "tailscale_user_mismatch": return ConnectErrorDetailCodes.AUTH_TAILSCALE_IDENTITY_MISMATCH;
+		case "rate_limited": return ConnectErrorDetailCodes.AUTH_RATE_LIMITED;
+		case "device_token_mismatch": return ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH;
+		case "scope_mismatch": return ConnectErrorDetailCodes.AUTH_SCOPE_MISMATCH;
+		case void 0: return ConnectErrorDetailCodes.AUTH_REQUIRED;
+		default: return ConnectErrorDetailCodes.AUTH_UNAUTHORIZED;
+	}
+}
+/** Maps device-auth verifier reasons to public connect-error detail codes. */
+function resolveDeviceAuthConnectErrorDetailCode(reason) {
+	switch (reason) {
+		case "device-id-mismatch": return ConnectErrorDetailCodes.DEVICE_AUTH_DEVICE_ID_MISMATCH;
+		case "device-signature-stale": return ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_EXPIRED;
+		case "device-nonce-missing": return ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_REQUIRED;
+		case "device-nonce-mismatch": return ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_MISMATCH;
+		case "device-signature": return ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_INVALID;
+		case "device-public-key": return ConnectErrorDetailCodes.DEVICE_AUTH_PUBLIC_KEY_INVALID;
+		default: return ConnectErrorDetailCodes.DEVICE_AUTH_INVALID;
+	}
+}
+/** Reads a non-empty detail code from an untrusted error details payload. */
+function readConnectErrorDetailCode(details) {
+	if (!details || typeof details !== "object" || Array.isArray(details)) return null;
+	const code = details.code;
+	return typeof code === "string" && code.trim().length > 0 ? code.trim() : null;
+}
+/** Extracts normalized retry advice from untrusted connect-error details. */
+function readConnectErrorRecoveryAdvice(details) {
+	if (!details || typeof details !== "object" || Array.isArray(details)) return {};
+	const raw = details;
+	const canRetryWithDeviceToken = typeof raw.canRetryWithDeviceToken === "boolean" ? raw.canRetryWithDeviceToken : void 0;
+	const normalizedNextStep = normalizeOptionalString(raw.recommendedNextStep) ?? "";
+	return {
+		canRetryWithDeviceToken,
+		recommendedNextStep: CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0
+	};
+}
+function normalizePairingConnectReason(value) {
+	const normalized = normalizeOptionalString(value) ?? "";
+	return CONNECT_PAIRING_REQUIRED_REASON_VALUES.has(normalized) ? normalized : void 0;
+}
+/** Normalizes pairing request ids before echoing them in close reasons or UI text. */
+function normalizePairingConnectRequestId(value) {
+	const normalized = normalizeOptionalString(value);
+	return normalized && PAIRING_CONNECT_REQUEST_ID_PATTERN.test(normalized) ? normalized : void 0;
+}
+function normalizeStringArray(value) {
+	return normalizeArrayBackedTrimmedStringList(value);
+}
+function createPairingConnectErrorDetails(params) {
+	return {
+		code: ConnectErrorDetailCodes.PAIRING_REQUIRED,
+		...params.reason ? { reason: params.reason } : {},
+		...params.requestId ? { requestId: params.requestId } : {},
+		...params.remediationHint ? { remediationHint: params.remediationHint } : {},
+		...params.recommendedNextStep ? { recommendedNextStep: params.recommendedNextStep } : {},
+		...params.retryable !== void 0 ? { retryable: params.retryable } : {},
+		...params.pauseReconnect !== void 0 ? { pauseReconnect: params.pauseReconnect } : {},
+		...params.deviceId ? { deviceId: params.deviceId } : {},
+		...params.requestedRole ? { requestedRole: params.requestedRole } : {},
+		...params.requestedScopes ? { requestedScopes: params.requestedScopes } : {},
+		...params.approvedRoles ? { approvedRoles: params.approvedRoles } : {},
+		...params.approvedScopes ? { approvedScopes: params.approvedScopes } : {}
+	};
+}
+/** Human-readable requirement summary for a pairing-required reason. */
+function describePairingConnectRequirement(reason) {
+	return reason ? PAIRING_CONNECT_REASON_METADATA[reason].requirement : "device approval is required";
+}
+/** Builds the gateway close/error message for a pairing-required connect failure. */
+function buildPairingConnectErrorMessage(reason) {
+	return reason ? `pairing required: ${describePairingConnectRequirement(reason)}` : "pairing required";
+}
+function buildPairingConnectRemediationHint(reason) {
+	return reason ? PAIRING_CONNECT_REASON_METADATA[reason].remediationHint : "Approve the pending device request before retrying.";
+}
+/** Short user-facing recovery title for pairing-required connect failures. */
+function buildPairingConnectRecoveryTitle(reason) {
+	return reason ? PAIRING_CONNECT_REASON_METADATA[reason].recoveryTitle : "Gateway pairing approval required.";
+}
+/** Builds sanitized structured details for a pairing-required connect failure. */
+function buildPairingConnectErrorDetails(params) {
+	const requestId = normalizePairingConnectRequestId(params.requestId);
+	const remediationHint = normalizeOptionalString(params.remediationHint) ?? buildPairingConnectRemediationHint(params.reason);
+	const deviceId = normalizeOptionalString(params.deviceId);
+	const requestedRole = normalizeOptionalString(params.requestedRole);
+	const requestedScopes = normalizeStringArray(params.requestedScopes);
+	const approvedRoles = normalizeStringArray(params.approvedRoles);
+	const approvedScopes = normalizeStringArray(params.approvedScopes);
+	return createPairingConnectErrorDetails({
+		reason: params.reason,
+		requestId,
+		remediationHint,
+		recommendedNextStep: params.recommendedNextStep,
+		retryable: params.retryable,
+		pauseReconnect: params.pauseReconnect,
+		deviceId,
+		requestedRole,
+		requestedScopes,
+		approvedRoles,
+		approvedScopes
+	});
+}
+/** Builds a sanitized close reason string for WebSocket pairing rejections. */
+function buildPairingConnectCloseReason(params) {
+	const requestId = normalizePairingConnectRequestId(params.requestId);
+	const message = buildPairingConnectErrorMessage(params.reason);
+	return requestId ? `${message} (requestId: ${requestId})` : message;
+}
+/** Reads and backfills pairing-required details from an untrusted details object. */
+function readPairingConnectErrorDetails(details) {
+	if (readConnectErrorDetailCode(details) !== ConnectErrorDetailCodes.PAIRING_REQUIRED) return null;
+	if (!details || typeof details !== "object" || Array.isArray(details)) return null;
+	const raw = details;
+	const reason = normalizePairingConnectReason(raw.reason);
+	const requestId = normalizePairingConnectRequestId(raw.requestId);
+	const remediationHint = normalizeOptionalString(raw.remediationHint) ?? buildPairingConnectRemediationHint(reason);
+	const normalizedNextStep = normalizeOptionalString(raw.recommendedNextStep) ?? "";
+	const recommendedNextStep = CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0;
+	const deviceId = normalizeOptionalString(raw.deviceId);
+	const requestedRole = normalizeOptionalString(raw.requestedRole);
+	const requestedScopes = normalizeStringArray(raw.requestedScopes);
+	const approvedRoles = normalizeStringArray(raw.approvedRoles);
+	const approvedScopes = normalizeStringArray(raw.approvedScopes);
+	return createPairingConnectErrorDetails({
+		reason,
+		requestId,
+		remediationHint,
+		recommendedNextStep,
+		retryable: typeof raw.retryable === "boolean" ? raw.retryable : void 0,
+		pauseReconnect: typeof raw.pauseReconnect === "boolean" ? raw.pauseReconnect : void 0,
+		deviceId,
+		requestedRole,
+		requestedScopes,
+		approvedRoles,
+		approvedScopes
+	});
+}
+/** Parses legacy/string-only pairing-required messages into structured details. */
+function readConnectPairingRequiredMessage(message) {
+	const normalizedMessage = normalizeOptionalString(message);
+	if (!normalizedMessage) return null;
+	const normalized = normalizedMessage.trim().toLowerCase();
+	let reason;
+	for (const [candidate, prefix] of Object.entries(CONNECT_PAIRING_REQUIRED_MESSAGE_BY_REASON)) if (normalized.includes(prefix)) {
+		reason = candidate;
+		break;
+	}
+	if (!reason && normalized.includes("pairing required")) reason = ConnectPairingRequiredReasons.NOT_PAIRED;
+	if (!reason) return null;
+	const requestId = normalizePairingConnectRequestId(normalizedMessage.match(/\(requestId:\s*([^\s)]+)\)/i)?.[1]);
+	return {
+		...requestId ? { requestId } : {},
+		reason
+	};
+}
+/** Formats pairing-required details into the canonical user-facing message. */
+function formatConnectPairingRequiredMessage(details) {
+	const pairing = readPairingConnectErrorDetails(details);
+	const base = CONNECT_PAIRING_REQUIRED_MESSAGE_BY_REASON[pairing?.reason ?? ConnectPairingRequiredReasons.NOT_PAIRED];
+	return pairing?.requestId ? `${base} (requestId: ${pairing.requestId})` : base;
+}
+/** Formats connect errors using structured details before falling back to raw messages. */
+function formatConnectErrorMessage(params) {
+	if (readConnectErrorDetailCode(params.details) === ConnectErrorDetailCodes.PAIRING_REQUIRED) return formatConnectPairingRequiredMessage(params.details);
+	if (readConnectErrorDetailCode(params.details) === ConnectErrorDetailCodes.PROTOCOL_MISMATCH) return formatProtocolMismatchMessage(params.message, params.details);
+	return normalizeOptionalString(params.message) ?? "gateway request failed";
+}
+function formatProtocolMismatchMessage(message, details) {
+	const raw = details;
+	const clientMin = normalizeProtocolNumber(raw.clientMinProtocol);
+	const clientMax = normalizeProtocolNumber(raw.clientMaxProtocol);
+	const expected = normalizeProtocolNumber(raw.expectedProtocol);
+	const probeMin = normalizeProtocolNumber(raw.minimumProbeProtocol);
+	const parts = [];
+	if (clientMin !== void 0 && clientMax !== void 0) parts.push(clientMin === clientMax ? `Control UI v${clientMin}` : `Control UI v${clientMin}-v${clientMax}`);
+	if (expected !== void 0) parts.push(`Gateway v${expected}`);
+	if (probeMin !== void 0) parts.push(`probe min v${probeMin}`);
+	const normalized = normalizeOptionalString(message) ?? "protocol mismatch";
+	return parts.length > 0 ? `${normalized}: ${parts.join(", ")}` : normalized;
+}
+function normalizeProtocolNumber(value) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+//#endregion
+export { ConnectErrorDetailCodes, buildPairingConnectCloseReason, buildPairingConnectErrorDetails, buildPairingConnectErrorMessage, buildPairingConnectRecoveryTitle, describePairingConnectRequirement, formatConnectErrorMessage, formatConnectPairingRequiredMessage, normalizePairingConnectRequestId, readConnectErrorDetailCode, readConnectErrorRecoveryAdvice, readConnectPairingRequiredMessage, readPairingConnectErrorDetails, resolveAuthConnectErrorDetailCode, resolveDeviceAuthConnectErrorDetailCode };

package/dist/frame-guards.d.mts

@@ -0,0 +1,7 @@
+import { a as EventFrame, c as GatewayFrame, f as RequestFrame, m as ResponseFrame, r as ErrorShape, t as ConnectParams, u as HelloOk } from "./frames-DEn_IEne.mjs";
+
+//#region src/frame-guards.d.ts
+declare function isGatewayEventFrame(value: unknown): value is EventFrame;
+declare function isGatewayResponseFrame(value: unknown): value is ResponseFrame;
+//#endregion
+export { type ConnectParams, type ErrorShape, type EventFrame, type GatewayFrame, type HelloOk, type RequestFrame, type ResponseFrame, isGatewayEventFrame, isGatewayResponseFrame };

package/dist/frame-guards.mjs

@@ -0,0 +1,26 @@
+//#region src/frame-guards.ts
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function isNonNegativeInteger(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isGatewayErrorShape(value) {
+	if (!isRecord(value)) return false;
+	if (!isNonEmptyString(value.code) || !isNonEmptyString(value.message)) return false;
+	if (value.retryable !== void 0 && typeof value.retryable !== "boolean") return false;
+	return value.retryAfterMs === void 0 || isNonNegativeInteger(value.retryAfterMs);
+}
+function isGatewayEventFrame(value) {
+	if (!isRecord(value) || value.type !== "event" || !isNonEmptyString(value.event)) return false;
+	return value.seq === void 0 || isNonNegativeInteger(value.seq);
+}
+function isGatewayResponseFrame(value) {
+	if (!isRecord(value) || value.type !== "res" || !isNonEmptyString(value.id) || typeof value.ok !== "boolean") return false;
+	return value.error === void 0 || isGatewayErrorShape(value.error);
+}
+//#endregion
+export { isGatewayEventFrame, isGatewayResponseFrame };

package/dist/frames-DEn_IEne.d.mts

@@ -0,0 +1,341 @@
+import { Static, Type } from "typebox";
+
+//#region src/schema/frames.d.ts
+declare const GATEWAY_SERVER_CAPS: {
+  readonly BOARD_WIDGET_PUT_CANVAS_DOC: "board-widget-put-canvas-doc";
+  readonly CHAT_SEND_ROUTING_CONTRACT: "chat-send-routing-contract";
+  readonly SYSTEM_AGENT_SETUP_MODEL_REF: "openclaw-setup-model-ref";
+};
+/**
+ * Top-level gateway frame schemas.
+ *
+ * These are the WebSocket envelope contracts; method/event payload schemas live
+ * in feature-specific modules and are referenced by runtime validators.
+ */
+/** Periodic server heartbeat event payload. */
+declare const TickEventSchema: Type.TObject<{
+  ts: Type.TInteger;
+}>;
+/** Server shutdown notice event payload. */
+declare const ShutdownEventSchema: Type.TObject<{
+  reason: Type.TString;
+  restartExpectedMs: Type.TOptional<Type.TInteger>;
+}>;
+/** Initial client hello/connect payload sent before the gateway accepts frames. */
+declare const ConnectParamsSchema: Type.TObject<{
+  minProtocol: Type.TInteger;
+  maxProtocol: Type.TInteger;
+  client: Type.TObject<{
+    id: Type.TEnum<["webchat-ui", "openclaw-control-ui", "openclaw-browser-copilot", "openclaw-tui", "webchat", "cli", "gateway-client", "openclaw-macos", "openclaw-linux", "openclaw-ios", "openclaw-watchos", "openclaw-android", "node-host", "openclaw-worker", "test", "fingerprint", "openclaw-probe"]>;
+    displayName: Type.TOptional<Type.TString>;
+    version: Type.TString;
+    platform: Type.TString;
+    deviceFamily: Type.TOptional<Type.TString>;
+    modelIdentifier: Type.TOptional<Type.TString>;
+    mode: Type.TEnum<["webchat", "cli", "worker", "test", "probe", "ui", "backend", "node"]>;
+    instanceId: Type.TOptional<Type.TString>;
+  }>;
+  caps: Type.TOptional<Type.TArray<Type.TString>>;
+  commands: Type.TOptional<Type.TArray<Type.TString>>;
+  permissions: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
+  pathEnv: Type.TOptional<Type.TString>;
+  role: Type.TOptional<Type.TString>;
+  scopes: Type.TOptional<Type.TArray<Type.TString>>;
+  device: Type.TOptional<Type.TObject<{
+    id: Type.TString;
+    publicKey: Type.TString;
+    signature: Type.TString;
+    signedAt: Type.TInteger;
+    nonce: Type.TString;
+  }>>;
+  auth: Type.TOptional<Type.TObject<{
+    token: Type.TOptional<Type.TString>;
+    bootstrapToken: Type.TOptional<Type.TString>;
+    deviceToken: Type.TOptional<Type.TString>;
+    password: Type.TOptional<Type.TString>;
+    approvalRuntimeToken: Type.TOptional<Type.TString>;
+    agentRuntimeIdentityToken: Type.TOptional<Type.TString>;
+  }>>;
+  locale: Type.TOptional<Type.TString>;
+  userAgent: Type.TOptional<Type.TString>;
+}>;
+/** Successful gateway hello response with negotiated protocol and initial state. */
+declare const HelloOkSchema: Type.TObject<{
+  type: Type.TLiteral<"hello-ok">;
+  protocol: Type.TInteger;
+  server: Type.TObject<{
+    version: Type.TString;
+    connId: Type.TString;
+  }>;
+  features: Type.TObject<{
+    methods: Type.TArray<Type.TString>;
+    events: Type.TArray<Type.TString>;
+    capabilities: Type.TOptional<Type.TArray<Type.TString>>;
+  }>;
+  snapshot: Type.TObject<{
+    presence: Type.TArray<Type.TObject<{
+      host: Type.TOptional<Type.TString>;
+      ip: Type.TOptional<Type.TString>;
+      version: Type.TOptional<Type.TString>;
+      platform: Type.TOptional<Type.TString>;
+      deviceFamily: Type.TOptional<Type.TString>;
+      modelIdentifier: Type.TOptional<Type.TString>;
+      mode: Type.TOptional<Type.TString>;
+      lastInputSeconds: Type.TOptional<Type.TInteger>;
+      reason: Type.TOptional<Type.TString>;
+      tags: Type.TOptional<Type.TArray<Type.TString>>;
+      text: Type.TOptional<Type.TString>;
+      ts: Type.TInteger;
+      deviceId: Type.TOptional<Type.TString>;
+      roles: Type.TOptional<Type.TArray<Type.TString>>;
+      scopes: Type.TOptional<Type.TArray<Type.TString>>;
+      instanceId: Type.TOptional<Type.TString>;
+      user: Type.TOptional<Type.TObject<{
+        id: Type.TString;
+        email: Type.TOptional<Type.TString>;
+        name: Type.TOptional<Type.TString>;
+        avatarUrl: Type.TOptional<Type.TString>;
+      }>>;
+      watchedSessions: Type.TOptional<Type.TArray<Type.TString>>;
+    }>>;
+    health: Type.TObject<{
+      ok: Type.TOptional<Type.TLiteral<true>>;
+      ts: Type.TOptional<Type.TInteger>;
+      durationMs: Type.TOptional<Type.TInteger>;
+      eventLoop: Type.TOptional<Type.TObject<{
+        degraded: Type.TBoolean;
+        reasons: Type.TArray<Type.TUnion<[Type.TLiteral<"event_loop_delay">, Type.TLiteral<"event_loop_utilization">, Type.TLiteral<"cpu">]>>;
+        intervalMs: Type.TNumber;
+        delayP99Ms: Type.TNumber;
+        delayMaxMs: Type.TNumber;
+        utilization: Type.TNumber;
+        cpuCoreRatio: Type.TNumber;
+      }>>;
+      plugins: Type.TOptional<Type.TObject<{
+        loaded: Type.TArray<Type.TString>;
+        errors: Type.TArray<Type.TObject<{
+          id: Type.TString;
+          origin: Type.TString;
+          activated: Type.TBoolean;
+          activationSource: Type.TOptional<Type.TString>;
+          activationReason: Type.TOptional<Type.TString>;
+          failurePhase: Type.TOptional<Type.TString>;
+          error: Type.TString;
+        }>>;
+        unavailable: Type.TOptional<Type.TArray<Type.TObject<{
+          id: Type.TString;
+          state: Type.TLiteral<"configured-unavailable">;
+          diagnostic: Type.TObject<{
+            kind: Type.TLiteral<"plugin-verification">;
+            reason: Type.TString;
+            detail: Type.TString;
+          }>;
+        }>>>;
+      }>>;
+      contextEngines: Type.TOptional<Type.TObject<{
+        quarantined: Type.TArray<Type.TObject<{
+          engineId: Type.TString;
+          owner: Type.TOptional<Type.TString>;
+          operation: Type.TString;
+          reason: Type.TString;
+          failedAt: Type.TInteger;
+        }>>;
+      }>>;
+      deliveryQueues: Type.TOptional<Type.TObject<{
+        failed: Type.TArray<Type.TObject<{
+          queueName: Type.TString;
+          count: Type.TInteger;
+          oldestFailedAt: Type.TOptional<Type.TInteger>;
+        }>>;
+      }>>;
+      modelPricing: Type.TOptional<Type.TObject<{
+        state: Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"degraded">, Type.TLiteral<"disabled">]>;
+        sources: Type.TArray<Type.TObject<{
+          source: Type.TUnion<[Type.TLiteral<"openrouter">, Type.TLiteral<"litellm">, Type.TLiteral<"bootstrap">, Type.TLiteral<"refresh">]>;
+          state: Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"degraded">]>;
+          lastFailureAt: Type.TOptional<Type.TInteger>;
+          detail: Type.TOptional<Type.TString>;
+        }>>;
+        lastFailureAt: Type.TOptional<Type.TInteger>;
+        detail: Type.TOptional<Type.TString>;
+      }>>;
+      configReload: Type.TOptional<Type.TObject<{
+        hotReloadStatus: Type.TUnion<[Type.TLiteral<"active">, Type.TLiteral<"disabled">]>;
+      }>>;
+      channels: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+      channelOrder: Type.TOptional<Type.TArray<Type.TString>>;
+      channelLabels: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+      heartbeatSeconds: Type.TOptional<Type.TInteger>;
+      defaultAgentId: Type.TOptional<Type.TString>;
+      agents: Type.TOptional<Type.TArray<Type.TObject<{
+        agentId: Type.TString;
+        name: Type.TOptional<Type.TString>;
+        isDefault: Type.TBoolean;
+        heartbeat: Type.TObject<{
+          enabled: Type.TBoolean;
+          every: Type.TString;
+          everyMs: Type.TUnion<[Type.TInteger, Type.TNull]>;
+          prompt: Type.TString;
+          target: Type.TString;
+          model: Type.TOptional<Type.TString>;
+          ackMaxChars: Type.TInteger;
+        }>;
+        sessions: Type.TObject<{
+          path: Type.TString;
+          count: Type.TInteger;
+          recent: Type.TArray<Type.TObject<{
+            key: Type.TString;
+            updatedAt: Type.TUnion<[Type.TInteger, Type.TNull]>;
+            age: Type.TUnion<[Type.TInteger, Type.TNull]>;
+          }>>;
+        }>;
+      }>>>;
+      sessions: Type.TOptional<Type.TObject<{
+        path: Type.TString;
+        count: Type.TInteger;
+        recent: Type.TArray<Type.TObject<{
+          key: Type.TString;
+          updatedAt: Type.TUnion<[Type.TInteger, Type.TNull]>;
+          age: Type.TUnion<[Type.TInteger, Type.TNull]>;
+        }>>;
+      }>>;
+    }>;
+    stateVersion: Type.TObject<{
+      presence: Type.TInteger;
+      health: Type.TInteger;
+    }>;
+    uptimeMs: Type.TInteger;
+    appliedConfigHash: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    configPath: Type.TOptional<Type.TString>;
+    stateDir: Type.TOptional<Type.TString>;
+    sessionDefaults: Type.TOptional<Type.TObject<{
+      defaultAgentId: Type.TString;
+      mainKey: Type.TString;
+      mainSessionKey: Type.TString;
+      scope: Type.TOptional<Type.TString>;
+    }>>;
+    authMode: Type.TOptional<Type.TUnion<[Type.TLiteral<"none">, Type.TLiteral<"token">, Type.TLiteral<"password">, Type.TLiteral<"trusted-proxy">]>>;
+    updateAvailable: Type.TOptional<Type.TObject<{
+      currentVersion: Type.TString;
+      latestVersion: Type.TString;
+      channel: Type.TString;
+    }>>;
+  }>;
+  controlUiTabs: Type.TOptional<Type.TArray<Type.TObject<{
+    pluginId: Type.TString;
+    id: Type.TString;
+    label: Type.TString;
+    description: Type.TOptional<Type.TString>;
+    icon: Type.TOptional<Type.TString>;
+    path: Type.TOptional<Type.TString>;
+    requiresGatewayAuth: Type.TOptional<Type.TBoolean>;
+    group: Type.TOptional<Type.TUnion<[Type.TLiteral<"control">, Type.TLiteral<"agent">]>>;
+    order: Type.TOptional<Type.TNumber>;
+  }>>>;
+  controlUiWidgetKinds: Type.TOptional<Type.TArray<Type.TObject<{
+    pluginId: Type.TString;
+    kind: Type.TString;
+    label: Type.TString;
+  }>>>;
+  pluginSurfaceUrls: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+  deviceAuthMigration: Type.TOptional<Type.TObject<{
+    pending: Type.TLiteral<true>;
+  }>>;
+  auth: Type.TObject<{
+    deviceToken: Type.TOptional<Type.TString>;
+    role: Type.TString;
+    scopes: Type.TArray<Type.TString>;
+    issuedAtMs: Type.TOptional<Type.TInteger>;
+    deviceTokens: Type.TOptional<Type.TArray<Type.TObject<{
+      deviceToken: Type.TString;
+      role: Type.TString;
+      scopes: Type.TArray<Type.TString>;
+      issuedAtMs: Type.TInteger;
+    }>>>;
+  }>;
+  policy: Type.TObject<{
+    maxPayload: Type.TInteger;
+    maxBufferedBytes: Type.TInteger;
+    tickIntervalMs: Type.TInteger;
+    allowedSessionVisibilities: Type.TOptional<Type.TArray<Type.TUnion<[Type.TLiteral<"shared">, Type.TLiteral<"read-only">, Type.TLiteral<"suggest">, Type.TLiteral<"draft">]>>>;
+    hasMultipleSessionSharingIdentities: Type.TOptional<Type.TBoolean>;
+  }>;
+}>;
+/** Standard structured error shape used in response frames and connect failures. */
+declare const ErrorShapeSchema: Type.TObject<{
+  code: Type.TString;
+  message: Type.TString;
+  details: Type.TOptional<Type.TUnknown>;
+  retryable: Type.TOptional<Type.TBoolean>;
+  retryAfterMs: Type.TOptional<Type.TInteger>;
+}>;
+/** Client request frame envelope; `method` selects the payload validator. */
+declare const RequestFrameSchema: Type.TObject<{
+  type: Type.TLiteral<"req">;
+  id: Type.TString;
+  method: Type.TString;
+  params: Type.TOptional<Type.TUnknown>;
+}>;
+/** Server response frame envelope paired with a prior request id. */
+declare const ResponseFrameSchema: Type.TObject<{
+  type: Type.TLiteral<"res">;
+  id: Type.TString;
+  ok: Type.TBoolean;
+  payload: Type.TOptional<Type.TUnknown>;
+  error: Type.TOptional<Type.TObject<{
+    code: Type.TString;
+    message: Type.TString;
+    details: Type.TOptional<Type.TUnknown>;
+    retryable: Type.TOptional<Type.TBoolean>;
+    retryAfterMs: Type.TOptional<Type.TInteger>;
+  }>>;
+}>;
+/** Server event frame envelope; `event` selects the payload validator. */
+declare const EventFrameSchema: Type.TObject<{
+  type: Type.TLiteral<"event">;
+  event: Type.TString;
+  payload: Type.TOptional<Type.TUnknown>;
+  seq: Type.TOptional<Type.TInteger>;
+  stateVersion: Type.TOptional<Type.TObject<{
+    presence: Type.TInteger;
+    health: Type.TInteger;
+  }>>;
+}>;
+declare const GatewayFrameSchema: Type.TUnion<[Type.TObject<{
+  type: Type.TLiteral<"req">;
+  id: Type.TString;
+  method: Type.TString;
+  params: Type.TOptional<Type.TUnknown>;
+}>, Type.TObject<{
+  type: Type.TLiteral<"res">;
+  id: Type.TString;
+  ok: Type.TBoolean;
+  payload: Type.TOptional<Type.TUnknown>;
+  error: Type.TOptional<Type.TObject<{
+    code: Type.TString;
+    message: Type.TString;
+    details: Type.TOptional<Type.TUnknown>;
+    retryable: Type.TOptional<Type.TBoolean>;
+    retryAfterMs: Type.TOptional<Type.TInteger>;
+  }>>;
+}>, Type.TObject<{
+  type: Type.TLiteral<"event">;
+  event: Type.TString;
+  payload: Type.TOptional<Type.TUnknown>;
+  seq: Type.TOptional<Type.TInteger>;
+  stateVersion: Type.TOptional<Type.TObject<{
+    presence: Type.TInteger;
+    health: Type.TInteger;
+  }>>;
+}>]>;
+type ConnectParams = Static<typeof ConnectParamsSchema>;
+type HelloOk = Static<typeof HelloOkSchema>;
+type ErrorShape = Static<typeof ErrorShapeSchema>;
+type RequestFrame = Static<typeof RequestFrameSchema>;
+type ResponseFrame = Static<typeof ResponseFrameSchema>;
+type EventFrame = Static<typeof EventFrameSchema>;
+type GatewayFrame = Static<typeof GatewayFrameSchema>;
+type TickEvent = Static<typeof TickEventSchema>;
+type ShutdownEvent = Static<typeof ShutdownEventSchema>;
+//#endregion
+export { ShutdownEventSchema as _, EventFrame as a, GatewayFrame as c, HelloOkSchema as d, RequestFrame as f, ShutdownEvent as g, ResponseFrameSchema as h, ErrorShapeSchema as i, GatewayFrameSchema as l, ResponseFrame as m, ConnectParamsSchema as n, EventFrameSchema as o, RequestFrameSchema as p, ErrorShape as r, GATEWAY_SERVER_CAPS as s, ConnectParams as t, HelloOk as u, TickEvent as v, TickEventSchema as y };