@openclaw/gateway-protocol 2026.7.2-beta.7 → 2026.8.1-beta.2

package/CHANGELOG.md

@@ -7,10 +7,13 @@ 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.
 
 ## Protocol v4 (current)
 
@@ -126,7 +129,8 @@ Enhancement-only month (no new schema modules):
 - 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`).
+  `openclaw.chat` / `openclaw.setup.*` (2026-07-14, `a6a0716`); add typed hosted-wizard
+  steps and answers to `openclaw.chat` (#114631).
 - 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

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 { i as normalizeOptionalProtocolString } from "./protocol-value-normalization-Bexl3yr1.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,7 @@ 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 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 +71,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 +106,20 @@ 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;
+} | {
+  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 +128,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,4 @@
+import { i as normalizeOptionalProtocolString } from "./protocol-value-normalization-Bexl3yr1.mjs";
 //#region src/connect-error-details.ts
 /**
 * Shared gateway connect-error detail helpers.
@@ -5,13 +6,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 +29,7 @@ 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",
+	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",
@@ -134,28 +132,36 @@ function readConnectErrorDetailCode(details) {
 	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) {
+	if (readConnectErrorDetailCode(details) !== 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 {};
 	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 +197,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);
@@ -224,11 +230,11 @@ function readPairingConnectErrorDetails(details) {
 	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 +254,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 +270,40 @@ 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 GATEWAY_CLOSED_MESSAGE_PATTERN = /\bgateway closed \(\d+\):/i;
+/** 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 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 +314,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 +326,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-BPnee-QV.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-B9De7i2H.mjs";
 
 //#region src/frame-guards.d.ts
 declare function isGatewayEventFrame(value: unknown): value is EventFrame;

package/dist/frame-guards.mjs

@@ -1,25 +1,20 @@
+import { n as isNonEmptyProtocolString, r as isProtocolRecord } from "./protocol-value-normalization-Bexl3yr1.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 (!isProtocolRecord(value)) 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 (!isProtocolRecord(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 (!isProtocolRecord(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-BPnee-QV.d.mts → frames-B9De7i2H.d.mts}

@@ -4,7 +4,9 @@ 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 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 +31,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 +39,13 @@ 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>; /** Additive node-local worker build identity; presence advertises session hosting. */
+  workerRuns: Type.TOptional<Type.TObject<{
+    bundleHash: Type.TString;
+    openclawVersion: Type.TString;
+    protocolFeatures: Type.TArray<Type.TString>;
+  }>>;
   permissions: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
   pathEnv: Type.TOptional<Type.TString>;
   role: Type.TOptional<Type.TString>;
@@ -59,12 +68,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<{
@@ -104,6 +115,7 @@ declare const HelloOkSchema: Type.TObject<{
       durationMs: Type.TOptional<Type.TInteger>;
       eventLoop: Type.TOptional<Type.TObject<{
         degraded: Type.TBoolean;
+        degradedSinceMs: Type.TOptional<Type.TUnion<[Type.TInteger, Type.TNull]>>;
         reasons: Type.TArray<Type.TUnion<[Type.TLiteral<"event_loop_delay">, Type.TLiteral<"event_loop_utilization">, Type.TLiteral<"cpu">]>>;
         intervalMs: Type.TNumber;
         delayP99Ms: Type.TNumber;
@@ -147,6 +159,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">]>;
@@ -178,6 +205,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<{
@@ -210,6 +238,8 @@ declare const HelloOkSchema: Type.TObject<{
     stateDir: Type.TOptional<Type.TString>;
     sessionDefaults: Type.TOptional<Type.TObject<{
       defaultAgentId: Type.TString;
+      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>;
@@ -219,6 +249,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<{
@@ -243,6 +337,8 @@ declare const HelloOkSchema: Type.TObject<{
   }>>;
   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>;
@@ -257,6 +353,10 @@ declare const HelloOkSchema: Type.TObject<{
     maxPayload: Type.TInteger;
     maxBufferedBytes: Type.TInteger;
     tickIntervalMs: Type.TInteger;
+    attachments: Type.TOptional<Type.TObject<{
+      maxBytes: Type.TInteger;
+      maxImageBytes: 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>;
   }>;

package/dist/{gateway-error-details-Btc09cgL.d.mts → gateway-error-details-BXoMHq1i.d.mts}

@@ -1,8 +1,8 @@
 //#region src/gateway-error-details.d.ts
 /** Gateway JSON-RPC style error codes shared by clients and server handlers. */
 declare const ErrorCodes: {
-  /** Client has not completed account/device linking for this gateway. */readonly NOT_LINKED: "NOT_LINKED"; /** Device exists but still needs an explicit pairing approval. */
-  readonly NOT_PAIRED: "NOT_PAIRED"; /** Agent turn exceeded the gateway wait window. */
+  /** @deprecated Retained for source compatibility; no current server emitter. */readonly NOT_LINKED: "NOT_LINKED"; /** Device exists but still needs an explicit pairing approval. */
+  readonly NOT_PAIRED: "NOT_PAIRED"; /** @deprecated Retained for source compatibility; no current server emitter. */
   readonly AGENT_TIMEOUT: "AGENT_TIMEOUT"; /** Request payload failed protocol validation or method preconditions. */
   readonly INVALID_REQUEST: "INVALID_REQUEST"; /** Authenticated caller lacks permission for the requested operation. */
   readonly FORBIDDEN: "FORBIDDEN"; /** Approval resolution referenced a missing or expired approval request. */
@@ -15,7 +15,9 @@ type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 declare const GatewayErrorDetailCodes: {
   readonly MISSING_SCOPE: "MISSING_SCOPE";
   readonly MCP_APP_VIEW_EXPIRED: "MCP_APP_VIEW_EXPIRED";
+  readonly USER_PREFS_LIMIT_EXCEEDED: "USER_PREFS_LIMIT_EXCEEDED";
   readonly SESSION_COMPANION_BUSY: "SESSION_COMPANION_BUSY";
+  readonly PROJECT_CLONE_FAILED: "PROJECT_CLONE_FAILED";
   readonly UNKNOWN_AGENT_ID: "UNKNOWN_AGENT_ID";
   readonly WIZARD_NOT_FOUND: "WIZARD_NOT_FOUND";
 };
@@ -28,6 +30,12 @@ type MissingScopeErrorDetails = {
 type McpAppViewExpiredErrorDetails = {
   code: typeof GatewayErrorDetailCodes.MCP_APP_VIEW_EXPIRED;
 };
+/** Per-profile preference quota details returned by users.prefs.set. */
+type UserPrefsLimitExceededErrorDetails = {
+  code: typeof GatewayErrorDetailCodes.USER_PREFS_LIMIT_EXCEEDED;
+  limit: number;
+  currentCount: number;
+};
 /** Unknown agent details carried by agent-scoped method validation failures. */
 type UnknownAgentIdErrorDetails = {
   code: typeof GatewayErrorDetailCodes.UNKNOWN_AGENT_ID;
@@ -37,8 +45,13 @@ type UnknownAgentIdErrorDetails = {
 type WizardNotFoundErrorDetails = {
   code: typeof GatewayErrorDetailCodes.WIZARD_NOT_FOUND;
 };
+type ProjectCloneFailureCause = "invalid_url" | "auth_required" | "not_found" | "network" | "target_exists" | "clone_failed";
+type ProjectCloneErrorDetails = {
+  code: typeof GatewayErrorDetailCodes.PROJECT_CLONE_FAILED;
+  cause: ProjectCloneFailureCause;
+};
 /** Structured details emitted by method-level failures. */
-type GatewayErrorDetails = MissingScopeErrorDetails | McpAppViewExpiredErrorDetails | UnknownAgentIdErrorDetails | WizardNotFoundErrorDetails;
+type GatewayErrorDetails = MissingScopeErrorDetails | McpAppViewExpiredErrorDetails | UserPrefsLimitExceededErrorDetails | ProjectCloneErrorDetails | UnknownAgentIdErrorDetails | WizardNotFoundErrorDetails;
 /** Reads validated missing-scope details from an untrusted protocol payload. */
 declare function readMissingScopeErrorDetails(details: unknown): MissingScopeErrorDetails | null;
 declare function isMcpAppViewExpiredError(error: unknown): boolean;
@@ -48,4 +61,4 @@ declare function isMcpAppViewExpiredError(error: unknown): boolean;
  */
 declare function readMissingScopeError(error: unknown): MissingScopeErrorDetails | null;
 //#endregion
-export { McpAppViewExpiredErrorDetails as a, WizardNotFoundErrorDetails as c, readMissingScopeErrorDetails as d, GatewayErrorDetails as i, isMcpAppViewExpiredError as l, ErrorCodes as n, MissingScopeErrorDetails as o, GatewayErrorDetailCodes as r, UnknownAgentIdErrorDetails as s, ErrorCode as t, readMissingScopeError as u };
+export { McpAppViewExpiredErrorDetails as a, ProjectCloneFailureCause as c, WizardNotFoundErrorDetails as d, isMcpAppViewExpiredError as f, GatewayErrorDetails as i, UnknownAgentIdErrorDetails as l, readMissingScopeErrorDetails as m, ErrorCodes as n, MissingScopeErrorDetails as o, readMissingScopeError as p, GatewayErrorDetailCodes as r, ProjectCloneErrorDetails as s, ErrorCode as t, UserPrefsLimitExceededErrorDetails as u };

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

@@ -1,2 +1,2 @@
-import { a as McpAppViewExpiredErrorDetails, c as WizardNotFoundErrorDetails, d as readMissingScopeErrorDetails, i as GatewayErrorDetails, l as isMcpAppViewExpiredError, n as ErrorCodes, o as MissingScopeErrorDetails, r as GatewayErrorDetailCodes, s as UnknownAgentIdErrorDetails, t as ErrorCode, u as readMissingScopeError } from "./gateway-error-details-Btc09cgL.mjs";
-export { ErrorCode, ErrorCodes, GatewayErrorDetailCodes, GatewayErrorDetails, McpAppViewExpiredErrorDetails, MissingScopeErrorDetails, UnknownAgentIdErrorDetails, WizardNotFoundErrorDetails, isMcpAppViewExpiredError, readMissingScopeError, readMissingScopeErrorDetails };
+import { a as McpAppViewExpiredErrorDetails, c as ProjectCloneFailureCause, d as WizardNotFoundErrorDetails, f as isMcpAppViewExpiredError, i as GatewayErrorDetails, l as UnknownAgentIdErrorDetails, m as readMissingScopeErrorDetails, n as ErrorCodes, o as MissingScopeErrorDetails, p as readMissingScopeError, r as GatewayErrorDetailCodes, s as ProjectCloneErrorDetails, t as ErrorCode, u as UserPrefsLimitExceededErrorDetails } from "./gateway-error-details-BXoMHq1i.mjs";
+export { ErrorCode, ErrorCodes, GatewayErrorDetailCodes, GatewayErrorDetails, McpAppViewExpiredErrorDetails, MissingScopeErrorDetails, ProjectCloneErrorDetails, ProjectCloneFailureCause, UnknownAgentIdErrorDetails, UserPrefsLimitExceededErrorDetails, WizardNotFoundErrorDetails, isMcpAppViewExpiredError, readMissingScopeError, readMissingScopeErrorDetails };

package/dist/gateway-error-details.mjs

@@ -1,11 +1,12 @@
+import { t as asProtocolRecord } from "./protocol-value-normalization-Bexl3yr1.mjs";
 //#region src/gateway-error-details.ts
 /** Gateway JSON-RPC style error codes shared by clients and server handlers. */
 const ErrorCodes = {
-	/** Client has not completed account/device linking for this gateway. */
+	/** @deprecated Retained for source compatibility; no current server emitter. */
 	NOT_LINKED: "NOT_LINKED",
 	/** Device exists but still needs an explicit pairing approval. */
 	NOT_PAIRED: "NOT_PAIRED",
-	/** Agent turn exceeded the gateway wait window. */
+	/** @deprecated Retained for source compatibility; no current server emitter. */
 	AGENT_TIMEOUT: "AGENT_TIMEOUT",
 	/** Request payload failed protocol validation or method preconditions. */
 	INVALID_REQUEST: "INVALID_REQUEST",
@@ -20,17 +21,16 @@ const ErrorCodes = {
 const GatewayErrorDetailCodes = {
 	MISSING_SCOPE: "MISSING_SCOPE",
 	MCP_APP_VIEW_EXPIRED: "MCP_APP_VIEW_EXPIRED",
+	USER_PREFS_LIMIT_EXCEEDED: "USER_PREFS_LIMIT_EXCEEDED",
 	SESSION_COMPANION_BUSY: "SESSION_COMPANION_BUSY",
+	PROJECT_CLONE_FAILED: "PROJECT_CLONE_FAILED",
 	UNKNOWN_AGENT_ID: "UNKNOWN_AGENT_ID",
 	WIZARD_NOT_FOUND: "WIZARD_NOT_FOUND"
 };
 const LEGACY_MISSING_SCOPE_PATTERN = /\bmissing scope:\s*([a-z0-9._-]+)/i;
-function asRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
 /** Reads validated missing-scope details from an untrusted protocol payload. */
 function readMissingScopeErrorDetails(details) {
-	const record = asRecord(details);
+	const record = asProtocolRecord(details);
 	if (record?.code !== GatewayErrorDetailCodes.MISSING_SCOPE) return null;
 	const missingScope = typeof record.missingScope === "string" ? record.missingScope.trim() : "";
 	const requiredScopes = Array.isArray(record.requiredScopes) ? record.requiredScopes.map((scope) => typeof scope === "string" ? scope.trim() : "") : [];
@@ -42,14 +42,14 @@ function readMissingScopeErrorDetails(details) {
 	};
 }
 function isMcpAppViewExpiredError(error) {
-	return asRecord(asRecord(error)?.details)?.code === GatewayErrorDetailCodes.MCP_APP_VIEW_EXPIRED;
+	return asProtocolRecord(asProtocolRecord(error)?.details)?.code === GatewayErrorDetailCodes.MCP_APP_VIEW_EXPIRED;
 }
 /**
 * Reads a method-level missing-scope failure, preferring structured details.
 * The message fallback keeps clients compatible with gateways predating structured details.
 */
 function readMissingScopeError(error) {
-	const record = asRecord(error);
+	const record = asProtocolRecord(error);
 	if (!record) return null;
 	const structured = readMissingScopeErrorDetails(record.details);
 	if (structured) return structured;