@openclaw/gateway-protocol 2026.9.2 → 2026.9.3

package/dist/client-info.mjs

@@ -1,4 +1,4 @@
-import { n as normalizeOptionalProtocolString } from "./protocol-value-normalization-DcAoxLUs.mjs";
+import { t as normalizeOptionalLowercaseString } from "./string-coerce-BJ6bjzdv.mjs";
 //#region src/client-info.ts
 /**
 * Shared gateway client identity contract.
@@ -6,9 +6,6 @@ import { n as normalizeOptionalProtocolString } from "./protocol-value-normaliza
 * These values cross the WebSocket handshake boundary, so additions must stay
 * aligned with protocol schemas and server policy checks.
 */
-function normalizeOptionalProtocolLowercaseString(raw) {
-	return normalizeOptionalProtocolString(raw)?.toLowerCase();
-}
 /** Canonical client ids accepted in gateway hello/connect payloads. */
 const GATEWAY_CLIENT_IDS = {
 	WEBCHAT_UI: "webchat-ui",
@@ -61,7 +58,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 = normalizeOptionalProtocolLowercaseString(raw);
+	const normalized = normalizeOptionalLowercaseString(raw);
 	if (!normalized) return;
 	return GATEWAY_CLIENT_ID_SET.has(normalized) ? normalized : void 0;
 }
@@ -71,7 +68,7 @@ function normalizeGatewayClientName(raw) {
 }
 /** Normalizes untrusted client modes and rejects unknown values. */
 function normalizeGatewayClientMode(raw) {
-	const normalized = normalizeOptionalProtocolLowercaseString(raw);
+	const normalized = normalizeOptionalLowercaseString(raw);
 	if (!normalized) return;
 	return GATEWAY_CLIENT_MODE_SET.has(normalized) ? normalized : void 0;
 }

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

@@ -87,18 +87,8 @@ export declare function buildPairingConnectErrorMessage(reason: ConnectPairingRe
 /** Short user-facing recovery title for pairing-required connect failures. */
 export declare function buildPairingConnectRecoveryTitle(reason: ConnectPairingRequiredReason | undefined): string;
 /** Builds sanitized structured details for a pairing-required connect failure. */
-export declare function buildPairingConnectErrorDetails(params: {
+export declare function buildPairingConnectErrorDetails(params: Omit<PairingConnectErrorDetails, "code" | "reason"> & {
   reason: ConnectPairingRequiredReason | undefined;
-  requestId?: string;
-  remediationHint?: string;
-  recommendedNextStep?: ConnectRecoveryNextStep;
-  retryable?: boolean;
-  pauseReconnect?: boolean;
-  deviceId?: string;
-  requestedRole?: string;
-  requestedScopes?: string[];
-  approvedRoles?: string[];
-  approvedScopes?: string[];
 }): PairingConnectErrorDetails;
 /** Builds a sanitized close reason string for WebSocket pairing rejections. */
 export declare function buildPairingConnectCloseReason(params: {

package/dist/connect-error-details.mjs

@@ -1,5 +1,20 @@
 import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
-import { n as normalizeOptionalProtocolString } from "./protocol-value-normalization-DcAoxLUs.mjs";
+import { n as normalizeOptionalString } from "./string-coerce-BJ6bjzdv.mjs";
+//#region ../normalization-core/src/string-normalization.ts
+/** Normalizes array-backed string lists and rejects non-array input as empty. */
+function normalizeTrimmedStringList(value) {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((entry) => {
+		const normalized = normalizeOptionalString(entry);
+		return normalized ? [normalized] : [];
+	});
+}
+/** Returns undefined instead of an empty normalized array-backed string list. */
+function normalizeOptionalTrimmedStringList(value) {
+	const normalized = normalizeTrimmedStringList(value);
+	return normalized.length > 0 ? normalized : void 0;
+}
+//#endregion
 //#region src/connect-error-details.ts
 /**
 * Shared gateway connect-error detail helpers.
@@ -7,11 +22,6 @@ import { n as normalizeOptionalProtocolString } from "./protocol-value-normaliza
 * These details cross client/server boundaries, so readers normalize untrusted
 * payloads before using them in reconnect decisions or user-facing messages.
 */
-function normalizeOptionalConnectDetailStringList(value) {
-	if (!Array.isArray(value)) return;
-	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`. */
 const ConnectErrorDetailCodes = {
 	AUTH_REQUIRED: "AUTH_REQUIRED",
@@ -142,33 +152,29 @@ 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);
+	const gatewayBuildId = normalizeOptionalString(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 (!isRecord(details)) return {};
-	const raw = details;
-	const canRetryWithDeviceToken = typeof raw.canRetryWithDeviceToken === "boolean" ? raw.canRetryWithDeviceToken : void 0;
-	const normalizedNextStep = normalizeOptionalProtocolString(raw.recommendedNextStep) ?? "";
+	const canRetryWithDeviceToken = typeof details.canRetryWithDeviceToken === "boolean" ? details.canRetryWithDeviceToken : void 0;
+	const normalizedNextStep = normalizeOptionalString(details.recommendedNextStep) ?? "";
 	return {
 		canRetryWithDeviceToken,
 		recommendedNextStep: CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0
 	};
 }
 function normalizePairingConnectReason(value) {
-	const normalized = normalizeOptionalProtocolString(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 = normalizeOptionalProtocolString(value);
+	const normalized = normalizeOptionalString(value);
 	return normalized && PAIRING_CONNECT_REQUEST_ID_PATTERN.test(normalized) ? normalized : void 0;
 }
-function normalizeStringArray(value) {
-	return normalizeOptionalConnectDetailStringList(value);
-}
 function createPairingConnectErrorDetails(params) {
 	return {
 		code: ConnectErrorDetailCodes.PAIRING_REQUIRED,
@@ -203,12 +209,12 @@ function buildPairingConnectRecoveryTitle(reason) {
 /** Builds sanitized structured details for a pairing-required connect failure. */
 function buildPairingConnectErrorDetails(params) {
 	const requestId = normalizePairingConnectRequestId(params.requestId);
-	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);
+	const remediationHint = normalizeOptionalString(params.remediationHint) ?? buildPairingConnectRemediationHint(params.reason);
+	const deviceId = normalizeOptionalString(params.deviceId);
+	const requestedRole = normalizeOptionalString(params.requestedRole);
+	const requestedScopes = normalizeOptionalTrimmedStringList(params.requestedScopes);
+	const approvedRoles = normalizeOptionalTrimmedStringList(params.approvedRoles);
+	const approvedScopes = normalizeOptionalTrimmedStringList(params.approvedScopes);
 	return createPairingConnectErrorDetails({
 		reason: params.reason,
 		requestId,
@@ -233,24 +239,23 @@ function buildPairingConnectCloseReason(params) {
 function readPairingConnectErrorDetails(details) {
 	if (readConnectErrorDetailCode(details) !== ConnectErrorDetailCodes.PAIRING_REQUIRED) return null;
 	if (!isRecord(details)) return null;
-	const raw = details;
-	const reason = normalizePairingConnectReason(raw.reason);
-	const requestId = normalizePairingConnectRequestId(raw.requestId);
-	const remediationHint = normalizeOptionalProtocolString(raw.remediationHint) ?? buildPairingConnectRemediationHint(reason);
-	const normalizedNextStep = normalizeOptionalProtocolString(raw.recommendedNextStep) ?? "";
+	const reason = normalizePairingConnectReason(details.reason);
+	const requestId = normalizePairingConnectRequestId(details.requestId);
+	const remediationHint = normalizeOptionalString(details.remediationHint) ?? buildPairingConnectRemediationHint(reason);
+	const normalizedNextStep = normalizeOptionalString(details.recommendedNextStep) ?? "";
 	const recommendedNextStep = CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0;
-	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);
+	const deviceId = normalizeOptionalString(details.deviceId);
+	const requestedRole = normalizeOptionalString(details.requestedRole);
+	const requestedScopes = normalizeOptionalTrimmedStringList(details.requestedScopes);
+	const approvedRoles = normalizeOptionalTrimmedStringList(details.approvedRoles);
+	const approvedScopes = normalizeOptionalTrimmedStringList(details.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,
+		retryable: typeof details.retryable === "boolean" ? details.retryable : void 0,
+		pauseReconnect: typeof details.pauseReconnect === "boolean" ? details.pauseReconnect : void 0,
 		deviceId,
 		requestedRole,
 		requestedScopes,
@@ -260,7 +265,7 @@ function readPairingConnectErrorDetails(details) {
 }
 /** Parses legacy/string-only pairing-required messages into structured details. */
 function readConnectPairingRequiredMessage(message) {
-	const normalizedMessage = normalizeOptionalProtocolString(message);
+	const normalizedMessage = normalizeOptionalString(message);
 	if (!normalizedMessage) return null;
 	const normalized = normalizedMessage.trim().toLowerCase();
 	let reason;
@@ -296,7 +301,7 @@ 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);
+	const location = normalizeOptionalString(details.location);
 	if (!location) return { cloudflareAccess: false };
 	try {
 		return { cloudflareAccess: new URL(location).hostname.toLowerCase().replace(/\.+$/u, "").endsWith(".cloudflareaccess.com") };
@@ -307,8 +312,8 @@ function readIdentityProxyRejection(details) {
 /** 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 message = normalizeOptionalString(input.message);
+	const reason = normalizeOptionalString(input.reason);
 	const userMessage = message ?? reason;
 	const classificationText = [message, reason].filter((value) => Boolean(value)).join("\n");
 	const normalized = classificationText.toLowerCase();
@@ -348,7 +353,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 normalizeOptionalProtocolString(params.message) ?? "gateway request failed";
+	return normalizeOptionalString(params.message) ?? "gateway request failed";
 }
 function formatProtocolMismatchMessage(message, details) {
 	const raw = details;
@@ -360,7 +365,7 @@ 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 = normalizeOptionalProtocolString(message) ?? "protocol mismatch";
+	const normalized = normalizeOptionalString(message) ?? "protocol mismatch";
 	return parts.length > 0 ? `${normalized}: ${parts.join(", ")}` : normalized;
 }
 function normalizeProtocolNumber(value) {

package/dist/frame-guards.mjs

@@ -1,5 +1,5 @@
 import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
-import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-DcAoxLUs.mjs";
+import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-DfM01tqg.mjs";
 //#region src/frame-guards.ts
 function isNonNegativeInteger(value) {
 	return typeof value === "number" && Number.isInteger(value) && value >= 0;

package/dist/{gateway-error-details-qdj19LIh.d.mts → gateway-error-details-DVeCF9AS.d.mts}

@@ -1,4 +1,6 @@
 //#region src/gateway-error-details.d.ts
+/** Display projection for an assistant failure without visible reply content. */
+declare const GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT = "The agent run failed before producing a reply.";
 /** Gateway JSON-RPC style error codes shared by clients and server handlers. */
 declare const ErrorCodes: {
   /** @deprecated Retained for source compatibility; no current server emitter. */
@@ -106,4 +108,4 @@ declare function isMcpAppViewExpiredError(error: unknown): boolean;
  */
 declare function readMissingScopeError(error: unknown): MissingScopeErrorDetails | null;
 //#endregion
-export { readSkillProposalRevisionChangedError as C, readMissingScopeErrorDetails as S, buildSkillProposalRevisionChangedErrorDetails as _, GatewayErrorDetails as a, readGitHubPublicationSelectionRejectedError as b, MissingScopeErrorDetails as c, ProjectCloneFailureCause as d, SetupAdmissionBusyErrorDetails as f, WizardNotFoundErrorDetails as g, UserPrefsLimitExceededErrorDetails as h, GatewayErrorDetailCodes as i, OutboundDeliveryQueuedErrorDetails as l, UnknownAgentIdErrorDetails as m, ErrorCode as n, GitHubPublicationSelectionRejectedErrorDetails as o, SkillProposalRevisionChangedErrorDetails as p, ErrorCodes as r, McpAppViewExpiredErrorDetails as s, CronJobNotFoundErrorDetails as t, ProjectCloneErrorDetails as u, isMcpAppViewExpiredError as v, readMissingScopeError as x, readCronJobNotFoundError as y };
+export { readMissingScopeErrorDetails as C, readMissingScopeError as S, WizardNotFoundErrorDetails as _, GatewayErrorDetailCodes as a, readCronJobNotFoundError as b, McpAppViewExpiredErrorDetails as c, ProjectCloneErrorDetails as d, ProjectCloneFailureCause as f, UserPrefsLimitExceededErrorDetails as g, UnknownAgentIdErrorDetails as h, GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT as i, MissingScopeErrorDetails as l, SkillProposalRevisionChangedErrorDetails as m, ErrorCode as n, GatewayErrorDetails as o, SetupAdmissionBusyErrorDetails as p, ErrorCodes as r, GitHubPublicationSelectionRejectedErrorDetails as s, CronJobNotFoundErrorDetails as t, OutboundDeliveryQueuedErrorDetails as u, buildSkillProposalRevisionChangedErrorDetails as v, readSkillProposalRevisionChangedError as w, readGitHubPublicationSelectionRejectedError as x, isMcpAppViewExpiredError as y };

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

@@ -1,2 +1,2 @@
-import { C as readSkillProposalRevisionChangedError, S as readMissingScopeErrorDetails, _ as buildSkillProposalRevisionChangedErrorDetails, a as GatewayErrorDetails, b as readGitHubPublicationSelectionRejectedError, c as MissingScopeErrorDetails, d as ProjectCloneFailureCause, f as SetupAdmissionBusyErrorDetails, g as WizardNotFoundErrorDetails, h as UserPrefsLimitExceededErrorDetails, i as GatewayErrorDetailCodes, l as OutboundDeliveryQueuedErrorDetails, m as UnknownAgentIdErrorDetails, n as ErrorCode, o as GitHubPublicationSelectionRejectedErrorDetails, p as SkillProposalRevisionChangedErrorDetails, r as ErrorCodes, s as McpAppViewExpiredErrorDetails, t as CronJobNotFoundErrorDetails, u as ProjectCloneErrorDetails, v as isMcpAppViewExpiredError, x as readMissingScopeError, y as readCronJobNotFoundError } from "./gateway-error-details-qdj19LIh.mjs";
-export { CronJobNotFoundErrorDetails, ErrorCode, ErrorCodes, GatewayErrorDetailCodes, GatewayErrorDetails, GitHubPublicationSelectionRejectedErrorDetails, McpAppViewExpiredErrorDetails, MissingScopeErrorDetails, OutboundDeliveryQueuedErrorDetails, ProjectCloneErrorDetails, ProjectCloneFailureCause, SetupAdmissionBusyErrorDetails, SkillProposalRevisionChangedErrorDetails, UnknownAgentIdErrorDetails, UserPrefsLimitExceededErrorDetails, WizardNotFoundErrorDetails, buildSkillProposalRevisionChangedErrorDetails, isMcpAppViewExpiredError, readCronJobNotFoundError, readGitHubPublicationSelectionRejectedError, readMissingScopeError, readMissingScopeErrorDetails, readSkillProposalRevisionChangedError };
+import { C as readMissingScopeErrorDetails, S as readMissingScopeError, _ as WizardNotFoundErrorDetails, a as GatewayErrorDetailCodes, b as readCronJobNotFoundError, c as McpAppViewExpiredErrorDetails, d as ProjectCloneErrorDetails, f as ProjectCloneFailureCause, g as UserPrefsLimitExceededErrorDetails, h as UnknownAgentIdErrorDetails, i as GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT, l as MissingScopeErrorDetails, m as SkillProposalRevisionChangedErrorDetails, n as ErrorCode, o as GatewayErrorDetails, p as SetupAdmissionBusyErrorDetails, r as ErrorCodes, s as GitHubPublicationSelectionRejectedErrorDetails, t as CronJobNotFoundErrorDetails, u as OutboundDeliveryQueuedErrorDetails, v as buildSkillProposalRevisionChangedErrorDetails, w as readSkillProposalRevisionChangedError, x as readGitHubPublicationSelectionRejectedError, y as isMcpAppViewExpiredError } from "./gateway-error-details-DVeCF9AS.mjs";
+export { CronJobNotFoundErrorDetails, ErrorCode, ErrorCodes, GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT, GatewayErrorDetailCodes, GatewayErrorDetails, GitHubPublicationSelectionRejectedErrorDetails, McpAppViewExpiredErrorDetails, MissingScopeErrorDetails, OutboundDeliveryQueuedErrorDetails, ProjectCloneErrorDetails, ProjectCloneFailureCause, SetupAdmissionBusyErrorDetails, SkillProposalRevisionChangedErrorDetails, UnknownAgentIdErrorDetails, UserPrefsLimitExceededErrorDetails, WizardNotFoundErrorDetails, buildSkillProposalRevisionChangedErrorDetails, isMcpAppViewExpiredError, readCronJobNotFoundError, readGitHubPublicationSelectionRejectedError, readMissingScopeError, readMissingScopeErrorDetails, readSkillProposalRevisionChangedError };

package/dist/gateway-error-details.mjs

@@ -1,5 +1,7 @@
 import { t as asNullableRecord } from "./record-coerce-BVp8Dr-B.mjs";
 //#region src/gateway-error-details.ts
+/** Display projection for an assistant failure without visible reply content. */
+const GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT = "The agent run failed before producing a reply.";
 /** Gateway JSON-RPC style error codes shared by clients and server handlers. */
 const ErrorCodes = {
 	/** @deprecated Retained for source compatibility; no current server emitter. */
@@ -111,4 +113,4 @@ function readMissingScopeError(error) {
 	} : null;
 }
 //#endregion
-export { ErrorCodes, GatewayErrorDetailCodes, buildSkillProposalRevisionChangedErrorDetails, isMcpAppViewExpiredError, readCronJobNotFoundError, readGitHubPublicationSelectionRejectedError, readMissingScopeError, readMissingScopeErrorDetails, readSkillProposalRevisionChangedError };
+export { ErrorCodes, GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT, GatewayErrorDetailCodes, buildSkillProposalRevisionChangedErrorDetails, isMcpAppViewExpiredError, readCronJobNotFoundError, readGitHubPublicationSelectionRejectedError, readMissingScopeError, readMissingScopeErrorDetails, readSkillProposalRevisionChangedError };