@openclaw/gateway-protocol 2026.8.1-beta.1 → 2026.8.1-beta.3

package/CHANGELOG.md

@@ -7,11 +7,14 @@ version and the additive schema surface. Dates are authoring dates (2026).
 
 ## Unreleased
 
+- Add bounded `sessions.patchMany` session mutation orchestration.
+- Preserve required legacy agent-default fields while adding honest `ownership` and `selectionRequired` state to agent lists and initial snapshots.
 - 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.
 - Add optional `step` on `SystemAgentChatResult` carrying the full awaited wizard step.
+- Project plugin tab `placement` in `hello-ok` so active plugins can target native Control UI routes.
 
 ## Protocol v4 (current)
 

package/README.md

@@ -128,7 +128,7 @@ Several identifier names coexist because they identify different things:
 
 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.
+label, Control UI short ID, or parent/agent scope.
 
 ### Intentionally open fields
 

package/dist/client-info.d.mts

@@ -59,7 +59,8 @@ type GatewayClientMode = (typeof GATEWAY_CLIENT_MODES)[keyof typeof GATEWAY_CLIE
 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`. */
+  version: string; /** Exact immutable artifact identity when the client can report one. */
+  buildId?: 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. */

package/dist/client-info.mjs

@@ -1,3 +1,4 @@
+import { n as normalizeOptionalProtocolString } from "./protocol-value-normalization-DcAoxLUs.mjs";
 //#region src/client-info.ts
 /**
 * Shared gateway client identity contract.
@@ -5,9 +6,8 @@
 * 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;
+function normalizeOptionalProtocolLowercaseString(raw) {
+	return normalizeOptionalProtocolString(raw)?.toLowerCase();
 }
 /** Canonical client ids accepted in gateway hello/connect payloads. */
 const GATEWAY_CLIENT_IDS = {
@@ -59,7 +59,7 @@ 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);
+	const normalized = normalizeOptionalProtocolLowercaseString(raw);
 	if (!normalized) return;
 	return GATEWAY_CLIENT_ID_SET.has(normalized) ? normalized : void 0;
 }
@@ -69,7 +69,7 @@ function normalizeGatewayClientName(raw) {
 }
 /** Normalizes untrusted client modes and rejects unknown values. */
 function normalizeGatewayClientMode(raw) {
-	const normalized = normalizeOptionalLowercaseString(raw);
+	const normalized = normalizeOptionalProtocolLowercaseString(raw);
 	if (!normalized) return;
 	return GATEWAY_CLIENT_MODE_SET.has(normalized) ? normalized : void 0;
 }

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

@@ -17,6 +17,8 @@ declare const ConnectErrorDetailCodes: {
   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 AUTH_IDENTITY_HEADER_REQUIRED: "AUTH_IDENTITY_HEADER_REQUIRED";
+  readonly CONTROL_UI_BUILD_MISMATCH: "CONTROL_UI_BUILD_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";
@@ -70,6 +72,8 @@ declare function resolveAuthConnectErrorDetailCode(reason: string | undefined):
 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;
+/** Read the exact target artifact from an untrusted reload-required rejection. */
+declare function readControlUiBuildMismatchId(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. */
@@ -103,6 +107,24 @@ declare function buildPairingConnectCloseReason(params: {
 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;
+/** Classifies Gateway connect failures from structured details, with one legacy text fallback. */
+declare function classifyGatewayConnectFailure(input: {
+  details?: unknown;
+  reason?: string | null;
+  message?: string | null;
+}): {
+  kind: "pairing-required";
+  userMessage: string;
+  remediation: string;
+} | {
+  kind: "identity-proxy";
+  userMessage: string;
+  remediation: string;
+} | {
+  remediation?: string | undefined;
+  kind: "device-identity-required" | "scope-mismatch" | "rate-limited" | "auth-rejected" | "gateway-rejected" | "unreachable";
+  userMessage: string;
+};
 /** 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. */
@@ -111,4 +133,4 @@ declare function formatConnectErrorMessage(params: {
   details?: unknown;
 }): string;
 //#endregion
-export { ConnectErrorDetailCodes, ConnectPairingRequiredDetails, ConnectPairingRequiredReason, buildPairingConnectCloseReason, buildPairingConnectErrorDetails, buildPairingConnectErrorMessage, buildPairingConnectRecoveryTitle, describePairingConnectRequirement, formatConnectErrorMessage, formatConnectPairingRequiredMessage, normalizePairingConnectRequestId, readConnectErrorDetailCode, readConnectErrorRecoveryAdvice, readConnectPairingRequiredMessage, readPairingConnectErrorDetails, resolveAuthConnectErrorDetailCode, resolveDeviceAuthConnectErrorDetailCode };
+export { ConnectErrorDetailCodes, ConnectPairingRequiredDetails, ConnectPairingRequiredReason, buildPairingConnectCloseReason, buildPairingConnectErrorDetails, buildPairingConnectErrorMessage, buildPairingConnectRecoveryTitle, classifyGatewayConnectFailure, describePairingConnectRequirement, formatConnectErrorMessage, formatConnectPairingRequiredMessage, normalizePairingConnectRequestId, readConnectErrorDetailCode, readConnectErrorRecoveryAdvice, readConnectPairingRequiredMessage, readControlUiBuildMismatchId, readPairingConnectErrorDetails, resolveAuthConnectErrorDetailCode, resolveDeviceAuthConnectErrorDetailCode };

package/dist/connect-error-details.mjs

@@ -1,3 +1,5 @@
+import { n as isRecord } from "./record-coerce-BKHrZ46I.mjs";
+import { n as normalizeOptionalProtocolString } from "./protocol-value-normalization-DcAoxLUs.mjs";
 //#region src/connect-error-details.ts
 /**
 * Shared gateway connect-error detail helpers.
@@ -5,13 +7,9 @@
 * 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) {
+function normalizeOptionalConnectDetailStringList(value) {
 	if (!Array.isArray(value)) return;
-	const values = value.map((entry) => normalizeOptionalString(entry)).filter((entry) => Boolean(entry));
+	const values = value.map((entry) => normalizeOptionalProtocolString(entry)).filter((entry) => Boolean(entry));
 	return values.length > 0 ? values : void 0;
 }
 /** Structured connect-error codes carried in gateway error `details.code`. */
@@ -32,6 +30,8 @@ const ConnectErrorDetailCodes = {
 	AUTH_TAILSCALE_PROXY_MISSING: "AUTH_TAILSCALE_PROXY_MISSING",
 	AUTH_TAILSCALE_WHOIS_FAILED: "AUTH_TAILSCALE_WHOIS_FAILED",
 	AUTH_TAILSCALE_IDENTITY_MISMATCH: "AUTH_TAILSCALE_IDENTITY_MISMATCH",
+	AUTH_IDENTITY_HEADER_REQUIRED: "AUTH_IDENTITY_HEADER_REQUIRED",
+	CONTROL_UI_BUILD_MISMATCH: "CONTROL_UI_BUILD_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",
@@ -97,6 +97,7 @@ const CONNECT_PAIRING_REQUIRED_MESSAGE_BY_REASON = {
 };
 /** Maps internal auth failure reasons to public connect-error detail codes. */
 function resolveAuthConnectErrorDetailCode(reason) {
+	if (reason?.startsWith("trusted_proxy_missing_header_")) return ConnectErrorDetailCodes.AUTH_IDENTITY_HEADER_REQUIRED;
 	switch (reason) {
 		case "token_missing": return ConnectErrorDetailCodes.AUTH_TOKEN_MISSING;
 		case "token_mismatch": return ConnectErrorDetailCodes.AUTH_TOKEN_MISMATCH;
@@ -130,32 +131,41 @@ function resolveDeviceAuthConnectErrorDetailCode(reason) {
 }
 /** 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;
+	if (!isRecord(details)) return null;
 	const code = details.code;
 	return typeof code === "string" && code.trim().length > 0 ? code.trim() : null;
 }
+/** Read the exact target artifact from an untrusted reload-required rejection. */
+function readControlUiBuildMismatchId(details) {
+	const code = readConnectErrorDetailCode(details);
+	if (code !== ConnectErrorDetailCodes.PROTOCOL_MISMATCH && code !== ConnectErrorDetailCodes.CONTROL_UI_BUILD_MISMATCH) return null;
+	const raw = details;
+	const gatewayBuildId = normalizeOptionalProtocolString(raw.gatewayBuildId);
+	if (!gatewayBuildId || gatewayBuildId.length > 96 || raw.reloadRequired !== true) return null;
+	return gatewayBuildId;
+}
 /** Extracts normalized retry advice from untrusted connect-error details. */
 function readConnectErrorRecoveryAdvice(details) {
-	if (!details || typeof details !== "object" || Array.isArray(details)) return {};
+	if (!isRecord(details)) return {};
 	const raw = details;
 	const canRetryWithDeviceToken = typeof raw.canRetryWithDeviceToken === "boolean" ? raw.canRetryWithDeviceToken : void 0;
-	const normalizedNextStep = normalizeOptionalString(raw.recommendedNextStep) ?? "";
+	const normalizedNextStep = normalizeOptionalProtocolString(raw.recommendedNextStep) ?? "";
 	return {
 		canRetryWithDeviceToken,
 		recommendedNextStep: CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0
 	};
 }
 function normalizePairingConnectReason(value) {
-	const normalized = normalizeOptionalString(value) ?? "";
+	const normalized = normalizeOptionalProtocolString(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);
+	const normalized = normalizeOptionalProtocolString(value);
 	return normalized && PAIRING_CONNECT_REQUEST_ID_PATTERN.test(normalized) ? normalized : void 0;
 }
 function normalizeStringArray(value) {
-	return normalizeArrayBackedTrimmedStringList(value);
+	return normalizeOptionalConnectDetailStringList(value);
 }
 function createPairingConnectErrorDetails(params) {
 	return {
@@ -191,9 +201,9 @@ function buildPairingConnectRecoveryTitle(reason) {
 /** 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 remediationHint = normalizeOptionalProtocolString(params.remediationHint) ?? buildPairingConnectRemediationHint(params.reason);
+	const deviceId = normalizeOptionalProtocolString(params.deviceId);
+	const requestedRole = normalizeOptionalProtocolString(params.requestedRole);
 	const requestedScopes = normalizeStringArray(params.requestedScopes);
 	const approvedRoles = normalizeStringArray(params.approvedRoles);
 	const approvedScopes = normalizeStringArray(params.approvedScopes);
@@ -220,15 +230,15 @@ function buildPairingConnectCloseReason(params) {
 /** 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;
+	if (!isRecord(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 remediationHint = normalizeOptionalProtocolString(raw.remediationHint) ?? buildPairingConnectRemediationHint(reason);
+	const normalizedNextStep = normalizeOptionalProtocolString(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 deviceId = normalizeOptionalProtocolString(raw.deviceId);
+	const requestedRole = normalizeOptionalProtocolString(raw.requestedRole);
 	const requestedScopes = normalizeStringArray(raw.requestedScopes);
 	const approvedRoles = normalizeStringArray(raw.approvedRoles);
 	const approvedScopes = normalizeStringArray(raw.approvedScopes);
@@ -248,7 +258,7 @@ function readPairingConnectErrorDetails(details) {
 }
 /** Parses legacy/string-only pairing-required messages into structured details. */
 function readConnectPairingRequiredMessage(message) {
-	const normalizedMessage = normalizeOptionalString(message);
+	const normalizedMessage = normalizeOptionalProtocolString(message);
 	if (!normalizedMessage) return null;
 	const normalized = normalizedMessage.trim().toLowerCase();
 	let reason;
@@ -264,6 +274,68 @@ function readConnectPairingRequiredMessage(message) {
 		reason
 	};
 }
+const PAIRING_APPROVAL_REMEDIATION = "Run `openclaw devices approve --latest` to preview the pending request, then rerun the printed `openclaw devices approve <requestId>` command and reconnect (pass the same --url and --token/--password flags if you connected with explicit credentials).";
+const DEVICE_TOKEN_REMEDIATION = "Rotate the paired-device token with `openclaw devices rotate --device <deviceId> --role operator`, then reconnect.";
+const SHARED_TOKEN_REMEDIATION = "Verify `gateway.remote.token` matches `gateway.auth.token`. If a paired-device token is stale, rotate it with `openclaw devices rotate --device <deviceId> --role operator`, then reconnect.";
+const SCOPE_MISMATCH_REMEDIATION = "Review approved scopes with `openclaw devices list`; if an upgrade is pending, preview it with `openclaw devices approve --latest`, approve the printed request, then reconnect.";
+const RATE_LIMITED_REMEDIATION = "Wait for the temporary authentication lockout to expire, then retry.";
+const IDENTITY_PROXY_REMEDIATION = "An identity-aware proxy rejected the WebSocket upgrade. Configure gateway.remote.edgeAuth for the configured Gateway origin, then reconnect. See https://docs.openclaw.ai/gateway/remote#gateway-behind-an-identity-aware-proxy.";
+const CLOUDFLARE_ACCESS_REMEDIATION = "Cloudflare Access detected: configure its token header or service-token headers in gateway.remote.edgeAuth.";
+const IDENTITY_PROXY_HTTP_STATUSES = /* @__PURE__ */ new Set([
+	301,
+	302,
+	303,
+	307,
+	308,
+	401,
+	403
+]);
+const GATEWAY_CLOSED_MESSAGE_PATTERN = /\bgateway closed \(\d+\):/i;
+function readIdentityProxyRejection(details) {
+	if (!isRecord(details)) return null;
+	if (details.reason !== "websocket-upgrade-rejected" || typeof details.httpStatus !== "number" || !IDENTITY_PROXY_HTTP_STATUSES.has(details.httpStatus)) return null;
+	const location = normalizeOptionalProtocolString(details.location);
+	if (!location) return { cloudflareAccess: false };
+	try {
+		return { cloudflareAccess: new URL(location).hostname.toLowerCase().replace(/\.+$/u, "").endsWith(".cloudflareaccess.com") };
+	} catch {
+		return { cloudflareAccess: false };
+	}
+}
+/** Classifies Gateway connect failures from structured details, with one legacy text fallback. */
+function classifyGatewayConnectFailure(input) {
+	const code = readConnectErrorDetailCode(input.details);
+	const message = normalizeOptionalProtocolString(input.message);
+	const reason = normalizeOptionalProtocolString(input.reason);
+	const userMessage = message ?? reason;
+	const classificationText = [message, reason].filter((value) => Boolean(value)).join("\n");
+	const normalized = classificationText.toLowerCase();
+	const pairing = readPairingConnectErrorDetails(input.details) ?? readConnectPairingRequiredMessage(classificationText);
+	if (code === ConnectErrorDetailCodes.PAIRING_REQUIRED || pairing) return {
+		kind: "pairing-required",
+		userMessage: code === ConnectErrorDetailCodes.PAIRING_REQUIRED ? formatConnectPairingRequiredMessage(input.details) : userMessage ?? "device pairing required",
+		remediation: PAIRING_APPROVAL_REMEDIATION
+	};
+	const identityProxy = readIdentityProxyRejection(input.details);
+	if (identityProxy) return {
+		kind: "identity-proxy",
+		userMessage: userMessage ?? "identity-aware proxy rejected websocket upgrade",
+		remediation: identityProxy.cloudflareAccess ? `${IDENTITY_PROXY_REMEDIATION}\n${CLOUDFLARE_ACCESS_REMEDIATION}` : IDENTITY_PROXY_REMEDIATION
+	};
+	const deviceIdentityRequired = code === ConnectErrorDetailCodes.DEVICE_IDENTITY_REQUIRED || code === ConnectErrorDetailCodes.CONTROL_UI_DEVICE_IDENTITY_REQUIRED || normalized.includes("device identity required");
+	const scopeMismatch = code === ConnectErrorDetailCodes.AUTH_SCOPE_MISMATCH || normalized.includes("scope mismatch");
+	const rateLimited = code === ConnectErrorDetailCodes.AUTH_RATE_LIMITED || !code && normalized.includes("too many failed authentication attempts");
+	const deviceTokenMismatch = code === ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH || normalized.includes("device token mismatch");
+	const sharedTokenMismatch = code === ConnectErrorDetailCodes.AUTH_TOKEN_MISMATCH || normalized.includes("gateway token mismatch");
+	const authRejected = deviceTokenMismatch || sharedTokenMismatch || code?.startsWith("AUTH_") || code?.startsWith("DEVICE_AUTH_");
+	const kind = deviceIdentityRequired ? "device-identity-required" : scopeMismatch ? "scope-mismatch" : rateLimited ? "rate-limited" : authRejected ? "auth-rejected" : code || GATEWAY_CLOSED_MESSAGE_PATTERN.test(classificationText) ? "gateway-rejected" : "unreachable";
+	const remediation = rateLimited ? RATE_LIMITED_REMEDIATION : scopeMismatch ? SCOPE_MISMATCH_REMEDIATION : deviceTokenMismatch ? DEVICE_TOKEN_REMEDIATION : sharedTokenMismatch ? SHARED_TOKEN_REMEDIATION : void 0;
+	return {
+		kind,
+		userMessage: userMessage ?? (kind === "unreachable" ? "gateway unreachable" : "gateway rejected connection"),
+		...remediation ? { remediation } : {}
+	};
+}
 /** Formats pairing-required details into the canonical user-facing message. */
 function formatConnectPairingRequiredMessage(details) {
 	const pairing = readPairingConnectErrorDetails(details);
@@ -274,7 +346,7 @@ function formatConnectPairingRequiredMessage(details) {
 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";
+	return normalizeOptionalProtocolString(params.message) ?? "gateway request failed";
 }
 function formatProtocolMismatchMessage(message, details) {
 	const raw = details;
@@ -286,11 +358,11 @@ function formatProtocolMismatchMessage(message, details) {
 	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";
+	const normalized = normalizeOptionalProtocolString(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 };
+export { ConnectErrorDetailCodes, buildPairingConnectCloseReason, buildPairingConnectErrorDetails, buildPairingConnectErrorMessage, buildPairingConnectRecoveryTitle, classifyGatewayConnectFailure, describePairingConnectRequirement, formatConnectErrorMessage, formatConnectPairingRequiredMessage, normalizePairingConnectRequestId, readConnectErrorDetailCode, readConnectErrorRecoveryAdvice, readConnectPairingRequiredMessage, readControlUiBuildMismatchId, readPairingConnectErrorDetails, resolveAuthConnectErrorDetailCode, resolveDeviceAuthConnectErrorDetailCode };

package/dist/frame-guards.d.mts

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

package/dist/frame-guards.mjs

@@ -1,25 +1,21 @@
+import { n as isRecord } from "./record-coerce-BKHrZ46I.mjs";
+import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-DcAoxLUs.mjs";
 //#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 (!isNonEmptyProtocolString(value.code) || !isNonEmptyProtocolString(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;
+	if (!isRecord(value) || value.type !== "event" || !isNonEmptyProtocolString(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;
+	if (!isRecord(value) || value.type !== "res" || !isNonEmptyProtocolString(value.id) || typeof value.ok !== "boolean") return false;
 	return value.error === void 0 || isGatewayErrorShape(value.error);
 }
 //#endregion

package/dist/{frames-C2oAsD4y.d.mts → frames-BKvowx_k.d.mts}

@@ -4,7 +4,12 @@ import { Static, Type } from "typebox";
 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 GATEWAY_RESTART_TARGET_SAFE: "gateway-restart-target-safe-v1";
+  readonly NODE_WORKER_BUNDLE_RETENTION: "node-worker-bundle-retention-v1";
+  readonly NODE_WORKER_BUNDLE_STATUS: "node-worker-bundle-status-v1";
+  readonly SYSTEM_AGENT_WIZARD_CANCEL: "openclaw-chat-wizard-cancel";
   readonly SYSTEM_AGENT_SETUP_MODEL_REF: "openclaw-setup-model-ref";
+  readonly TASK_SUGGESTIONS_ACCEPT_MODES: "taskSuggestions.acceptModes";
 };
 /**
  * Top-level gateway frame schemas.
@@ -29,6 +34,7 @@ declare const ConnectParamsSchema: 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;
+    buildId: Type.TOptional<Type.TString>;
     platform: Type.TString;
     deviceFamily: Type.TOptional<Type.TString>;
     modelIdentifier: Type.TOptional<Type.TString>;
@@ -36,7 +42,14 @@ declare const ConnectParamsSchema: Type.TObject<{
     instanceId: Type.TOptional<Type.TString>;
   }>;
   caps: Type.TOptional<Type.TArray<Type.TString>>;
-  commands: Type.TOptional<Type.TArray<Type.TString>>;
+  commands: Type.TOptional<Type.TArray<Type.TString>>; /** Additive Computer Use declaration; the owning core contract validates its bounded shape. */
+  computerUse: Type.TOptional<Type.TUnknown>; /** @deprecated Accepted for the shipped v1 node-host envelope; current hosts use runner inventory. */
+  workerRuns: Type.TOptional<Type.TObject<{
+    bundleHash: Type.TString;
+    openclawVersion: Type.TString;
+    protocolFeatures: Type.TArray<Type.TString>;
+    bundlePrewarm: Type.TOptional<Type.TInteger>;
+  }>>;
   permissions: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
   pathEnv: Type.TOptional<Type.TString>;
   role: Type.TOptional<Type.TString>;
@@ -59,12 +72,14 @@ declare const ConnectParamsSchema: Type.TObject<{
   locale: Type.TOptional<Type.TString>;
   userAgent: Type.TOptional<Type.TString>;
 }>;
-/** Successful gateway hello response with negotiated protocol and initial state. */
+/** Successful gateway hello response with the server protocol and initial state. */
 declare const HelloOkSchema: Type.TObject<{
   type: Type.TLiteral<"hello-ok">;
   protocol: Type.TInteger;
   server: Type.TObject<{
     version: Type.TString;
+    buildId: Type.TOptional<Type.TString>;
+    controlUiBuildSource: Type.TOptional<Type.TUnion<[Type.TLiteral<"bundled">, Type.TLiteral<"configured">]>>;
     connId: Type.TString;
   }>;
   features: Type.TObject<{
@@ -148,6 +163,21 @@ declare const HelloOkSchema: Type.TObject<{
           count: Type.TInteger;
           oldestFailedAt: Type.TOptional<Type.TInteger>;
         }>>;
+        ingressFailed: Type.TOptional<Type.TArray<Type.TObject<{
+          channelId: Type.TString;
+          accountId: Type.TString;
+          count: Type.TInteger;
+          oldestFailedAt: Type.TOptional<Type.TInteger>;
+        }>>>;
+        ingressPressure: Type.TOptional<Type.TArray<Type.TObject<{
+          channelId: Type.TString;
+          accountId: Type.TString;
+          laneCount: Type.TInteger;
+          pendingCount: Type.TInteger;
+          claimedCount: Type.TInteger;
+          blockedCount: Type.TInteger;
+          oldestReceivedAt: Type.TInteger;
+        }>>>;
       }>>;
       modelPricing: Type.TOptional<Type.TObject<{
         state: Type.TUnion<[Type.TLiteral<"ok">, Type.TLiteral<"degraded">, Type.TLiteral<"disabled">]>;
@@ -179,6 +209,7 @@ declare const HelloOkSchema: Type.TObject<{
           prompt: Type.TString;
           target: Type.TString;
           model: Type.TOptional<Type.TString>;
+          session: Type.TOptional<Type.TString>;
           ackMaxChars: Type.TInteger;
         }>;
         sessions: Type.TObject<{
@@ -211,6 +242,9 @@ declare const HelloOkSchema: Type.TObject<{
     stateDir: Type.TOptional<Type.TString>;
     sessionDefaults: Type.TOptional<Type.TObject<{
       defaultAgentId: Type.TString;
+      modelConfigured: Type.TOptional<Type.TBoolean>;
+      ownership: Type.TOptional<Type.TUnion<[Type.TLiteral<"sole">, Type.TLiteral<"legacy">, Type.TLiteral<"explicit">]>>;
+      selectionRequired: Type.TOptional<Type.TBoolean>;
       mainKey: Type.TString;
       mainSessionKey: Type.TString;
       scope: Type.TOptional<Type.TString>;
@@ -220,6 +254,70 @@ declare const HelloOkSchema: Type.TObject<{
       currentVersion: Type.TString;
       latestVersion: Type.TString;
       channel: Type.TString;
+      currentSha: Type.TOptional<Type.TString>;
+      upstreamRef: Type.TOptional<Type.TString>;
+      upstreamSha: Type.TOptional<Type.TString>;
+      commitsBehind: Type.TOptional<Type.TInteger>;
+      commits: Type.TOptional<Type.TArray<Type.TObject<{
+        sha: Type.TString;
+        subject: Type.TString;
+      }>>>;
+    }>>;
+    updateSchedule: Type.TOptional<Type.TObject<{
+      channel: Type.TString;
+      autoEnabled: Type.TBoolean;
+      install: Type.TOptional<Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"package">, Type.TLiteral<"git">, Type.TLiteral<"unknown">]>;
+        git: Type.TOptional<Type.TUnion<[Type.TObject<{
+          status: Type.TLiteral<"current">;
+          currentSha: Type.TOptional<Type.TString>;
+          commitAtMs: Type.TOptional<Type.TInteger>;
+          installedAtMs: Type.TOptional<Type.TInteger>;
+        }>, Type.TObject<{
+          status: Type.TLiteral<"behind">;
+          commitsBehind: Type.TInteger;
+          currentSha: Type.TOptional<Type.TString>;
+          commitAtMs: Type.TOptional<Type.TInteger>;
+          installedAtMs: Type.TOptional<Type.TInteger>;
+        }>, Type.TObject<{
+          status: Type.TLiteral<"ahead">;
+          commitsAhead: Type.TInteger;
+          currentSha: Type.TOptional<Type.TString>;
+          commitAtMs: Type.TOptional<Type.TInteger>;
+          installedAtMs: Type.TOptional<Type.TInteger>;
+        }>, Type.TObject<{
+          status: Type.TLiteral<"diverged">;
+          commitsAhead: Type.TInteger;
+          commitsBehind: Type.TInteger;
+          currentSha: Type.TOptional<Type.TString>;
+          commitAtMs: Type.TOptional<Type.TInteger>;
+          installedAtMs: Type.TOptional<Type.TInteger>;
+        }>, Type.TObject<{
+          status: Type.TLiteral<"unavailable">;
+          reason: Type.TUnion<[Type.TLiteral<"fetch-failed">, Type.TLiteral<"no-upstream">, Type.TLiteral<"no-upstream-sha">, Type.TLiteral<"comparison-failed">, Type.TLiteral<"git-unavailable">]>;
+          currentSha: Type.TOptional<Type.TString>;
+          commitAtMs: Type.TOptional<Type.TInteger>;
+          installedAtMs: Type.TOptional<Type.TInteger>;
+        }>]>>;
+      }>>;
+      target: Type.TOptional<Type.TUnion<[Type.TObject<{
+        kind: Type.TLiteral<"package">;
+        version: Type.TString;
+      }>, Type.TObject<{
+        kind: Type.TLiteral<"git">;
+        upstreamRef: Type.TString;
+        upstreamSha: Type.TString;
+        commitsBehind: Type.TInteger;
+      }>]>>;
+      campaign: Type.TOptional<Type.TObject<{
+        id: Type.TString;
+        state: Type.TUnion<[Type.TLiteral<"waiting-for-idle">, Type.TLiteral<"countdown">, Type.TLiteral<"applying">]>;
+        announcedAtMs: Type.TInteger;
+        applyAtMs: Type.TOptional<Type.TInteger>;
+        holdUntilMs: Type.TOptional<Type.TInteger>;
+        forceAtMs: Type.TInteger;
+        updatedAtMs: Type.TInteger;
+      }>>;
     }>>;
   }>;
   controlUiTabs: Type.TOptional<Type.TArray<Type.TObject<{
@@ -229,6 +327,7 @@ declare const HelloOkSchema: Type.TObject<{
     description: Type.TOptional<Type.TString>;
     icon: Type.TOptional<Type.TString>;
     path: Type.TOptional<Type.TString>;
+    placement: 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>;
@@ -239,11 +338,10 @@ declare const HelloOkSchema: Type.TObject<{
     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>;
+    recoveryMigrationAllowed: Type.TOptional<Type.TLiteral<true>>;
+    recoveryScope: Type.TOptional<Type.TString>;
     role: Type.TString;
     scopes: Type.TArray<Type.TString>;
     issuedAtMs: Type.TOptional<Type.TInteger>;