@openclaw/gateway-protocol 2026.9.8 → 2026.10.1-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -0
- package/dist/client-info.d.mts +1 -0
- package/dist/client-info.mjs +1 -0
- package/dist/connect-error-details.d.mts +29 -8
- package/dist/connect-error-details.mjs +56 -85
- package/dist/frame-guards.d.mts +1 -1
- package/dist/frame-guards.mjs +1 -1
- package/dist/{frames-ICrB58JF.d.mts → frames-DrSBm15j.d.mts} +37 -11
- package/dist/index.d.mts +760 -186
- package/dist/index.mjs +56 -40
- package/dist/{schema-modules-CRgBq9O3.d.mts → schema-modules-BlWM3kTv.d.mts} +16442 -14463
- package/dist/schema.d.mts +4 -4
- package/dist/schema.mjs +40 -3
- package/dist/{server-capabilities-BnyAklc1.mjs → server-capabilities-BTjjxElt.mjs} +11 -0
- package/dist/{tools-catalog-pKZZLiUu.mjs → tools-catalog-Cg4qTBai.mjs} +1944 -1444
- package/package.json +3 -2
- package/protocol.schema.json +5817 -162
package/README.md
CHANGED
|
@@ -130,6 +130,16 @@ it does not grant authorization.
|
|
|
130
130
|
|
|
131
131
|
## Contract notes
|
|
132
132
|
|
|
133
|
+
### Retired worker tool imports
|
|
134
|
+
|
|
135
|
+
The `WorkerSessionsSpawn*`, `WorkerSessionsSend*`, `WorkerSessionTool*`,
|
|
136
|
+
`WorkerPortal*`, and `WorkerPresence*` schemas, types, root validators, and associated
|
|
137
|
+
feature/limit constants published in 2026.9.6 and 2026.9.7 remain available for decoding older data. They do
|
|
138
|
+
not register or advertise the retired worker RPCs. Current workers use the
|
|
139
|
+
prepared tool surface and `worker.gatewayTool` transport; migrate integrations to
|
|
140
|
+
`WorkerGatewayTool*`. These imports can be removed only in an explicitly announced
|
|
141
|
+
breaking package API release after consumer migration.
|
|
142
|
+
|
|
133
143
|
### Session identifiers
|
|
134
144
|
|
|
135
145
|
Several identifier names coexist because they identify different things:
|
package/dist/client-info.d.mts
CHANGED
|
@@ -97,6 +97,7 @@ export declare const GATEWAY_CLIENT_CAPS: {
|
|
|
97
97
|
readonly TERMINAL_UPLOAD_PATH_STYLE: "terminal-upload-path-style";
|
|
98
98
|
readonly TOOL_EVENTS: "tool-events";
|
|
99
99
|
readonly UI_COMMANDS: "ui-commands";
|
|
100
|
+
readonly ULTRAFAST: "ultrafast";
|
|
100
101
|
readonly USAGE_REFRESHING: "usage-refreshing";
|
|
101
102
|
};
|
|
102
103
|
/** Optional capability advertised by clients during gateway handshake. */
|
package/dist/client-info.mjs
CHANGED
|
@@ -57,6 +57,7 @@ const GATEWAY_CLIENT_CAPS = {
|
|
|
57
57
|
TERMINAL_UPLOAD_PATH_STYLE: "terminal-upload-path-style",
|
|
58
58
|
TOOL_EVENTS: "tool-events",
|
|
59
59
|
UI_COMMANDS: "ui-commands",
|
|
60
|
+
ULTRAFAST: "ultrafast",
|
|
60
61
|
USAGE_REFRESHING: "usage-refreshing"
|
|
61
62
|
};
|
|
62
63
|
const GATEWAY_CLIENT_ID_SET = new Set(Object.values(GATEWAY_CLIENT_IDS));
|
|
@@ -38,15 +38,10 @@ export declare const ConnectErrorDetailCodes: {
|
|
|
38
38
|
};
|
|
39
39
|
type ConnectErrorDetailCode = (typeof ConnectErrorDetailCodes)[keyof typeof ConnectErrorDetailCodes];
|
|
40
40
|
/** Pairing-specific reasons clients can display and use for reconnect policy. */
|
|
41
|
-
|
|
42
|
-
readonly NOT_PAIRED: "not-paired";
|
|
43
|
-
readonly ROLE_UPGRADE: "role-upgrade";
|
|
44
|
-
readonly SCOPE_UPGRADE: "scope-upgrade";
|
|
45
|
-
readonly METADATA_UPGRADE: "metadata-upgrade";
|
|
46
|
-
};
|
|
47
|
-
export type ConnectPairingRequiredReason = (typeof ConnectPairingRequiredReasons)[keyof typeof ConnectPairingRequiredReasons];
|
|
41
|
+
export type ConnectPairingRequiredReason = keyof typeof PAIRING_CONNECT_REASON_METADATA;
|
|
48
42
|
/** Suggested client-side recovery action for structured connect errors. */
|
|
49
|
-
|
|
43
|
+
declare const CONNECT_RECOVERY_NEXT_STEP_VALUES: readonly ["retry_with_device_token", "update_auth_configuration", "update_auth_credentials", "wait_then_retry", "review_auth_configuration"];
|
|
44
|
+
type ConnectRecoveryNextStep = (typeof CONNECT_RECOVERY_NEXT_STEP_VALUES)[number];
|
|
50
45
|
/** Optional retry guidance extracted from gateway connect-error details. */
|
|
51
46
|
type ConnectErrorRecoveryAdvice = {
|
|
52
47
|
canRetryWithDeviceToken?: boolean;
|
|
@@ -69,6 +64,32 @@ type PairingConnectErrorDetails = {
|
|
|
69
64
|
};
|
|
70
65
|
/** Compact pairing-required subset used by reconnect/status surfaces. */
|
|
71
66
|
export type ConnectPairingRequiredDetails = Pick<PairingConnectErrorDetails, "reason" | "requestId">;
|
|
67
|
+
declare const PAIRING_CONNECT_REASON_METADATA: {
|
|
68
|
+
readonly "not-paired": {
|
|
69
|
+
readonly message: "device pairing required";
|
|
70
|
+
readonly requirement: "device is not approved yet";
|
|
71
|
+
readonly remediationHint: "Approve this device from the pending pairing requests.";
|
|
72
|
+
readonly recoveryTitle: "Gateway pairing approval required.";
|
|
73
|
+
};
|
|
74
|
+
readonly "role-upgrade": {
|
|
75
|
+
readonly message: "role upgrade pending approval";
|
|
76
|
+
readonly requirement: "device is asking for a higher role than currently approved";
|
|
77
|
+
readonly remediationHint: "Review the requested role upgrade, then approve the pending request.";
|
|
78
|
+
readonly recoveryTitle: "Gateway role upgrade approval required.";
|
|
79
|
+
};
|
|
80
|
+
readonly "scope-upgrade": {
|
|
81
|
+
readonly message: "scope upgrade pending approval";
|
|
82
|
+
readonly requirement: "device is asking for more scopes than currently approved";
|
|
83
|
+
readonly remediationHint: "Review the requested scopes, then approve the pending upgrade.";
|
|
84
|
+
readonly recoveryTitle: "Gateway scope upgrade approval required.";
|
|
85
|
+
};
|
|
86
|
+
readonly "metadata-upgrade": {
|
|
87
|
+
readonly message: "device metadata change pending approval";
|
|
88
|
+
readonly requirement: "device identity changed and must be re-approved";
|
|
89
|
+
readonly remediationHint: "Review the refreshed device details, then approve the pending request.";
|
|
90
|
+
readonly recoveryTitle: "Gateway device refresh approval required.";
|
|
91
|
+
};
|
|
92
|
+
};
|
|
72
93
|
/** Maps internal auth failure reasons to public connect-error detail codes. */
|
|
73
94
|
export declare function resolveAuthConnectErrorDetailCode(reason: string | undefined): ConnectErrorDetailCode;
|
|
74
95
|
/** Maps device-auth verifier reasons to public connect-error detail codes. */
|
|
@@ -59,89 +59,79 @@ const ConnectErrorDetailCodes = {
|
|
|
59
59
|
PAIRING_REQUIRED: "PAIRING_REQUIRED",
|
|
60
60
|
CLIENT_VERSION_MISMATCH: "CLIENT_VERSION_MISMATCH"
|
|
61
61
|
};
|
|
62
|
-
/**
|
|
63
|
-
const
|
|
64
|
-
NOT_PAIRED: "not-paired",
|
|
65
|
-
ROLE_UPGRADE: "role-upgrade",
|
|
66
|
-
SCOPE_UPGRADE: "scope-upgrade",
|
|
67
|
-
METADATA_UPGRADE: "metadata-upgrade"
|
|
68
|
-
};
|
|
69
|
-
const CONNECT_RECOVERY_NEXT_STEP_VALUES = /* @__PURE__ */ new Set([
|
|
62
|
+
/** Suggested client-side recovery action for structured connect errors. */
|
|
63
|
+
const CONNECT_RECOVERY_NEXT_STEP_VALUES = [
|
|
70
64
|
"retry_with_device_token",
|
|
71
65
|
"update_auth_configuration",
|
|
72
66
|
"update_auth_credentials",
|
|
73
67
|
"wait_then_retry",
|
|
74
68
|
"review_auth_configuration"
|
|
75
|
-
]
|
|
76
|
-
const CONNECT_PAIRING_REQUIRED_REASON_VALUES = new Set(Object.values(ConnectPairingRequiredReasons));
|
|
69
|
+
];
|
|
77
70
|
const PAIRING_CONNECT_REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
|
|
78
71
|
const PAIRING_CONNECT_REASON_METADATA = {
|
|
79
72
|
"not-paired": {
|
|
73
|
+
message: "device pairing required",
|
|
80
74
|
requirement: "device is not approved yet",
|
|
81
75
|
remediationHint: "Approve this device from the pending pairing requests.",
|
|
82
76
|
recoveryTitle: "Gateway pairing approval required."
|
|
83
77
|
},
|
|
84
78
|
"role-upgrade": {
|
|
79
|
+
message: "role upgrade pending approval",
|
|
85
80
|
requirement: "device is asking for a higher role than currently approved",
|
|
86
81
|
remediationHint: "Review the requested role upgrade, then approve the pending request.",
|
|
87
82
|
recoveryTitle: "Gateway role upgrade approval required."
|
|
88
83
|
},
|
|
89
84
|
"scope-upgrade": {
|
|
85
|
+
message: "scope upgrade pending approval",
|
|
90
86
|
requirement: "device is asking for more scopes than currently approved",
|
|
91
87
|
remediationHint: "Review the requested scopes, then approve the pending upgrade.",
|
|
92
88
|
recoveryTitle: "Gateway scope upgrade approval required."
|
|
93
89
|
},
|
|
94
90
|
"metadata-upgrade": {
|
|
91
|
+
message: "device metadata change pending approval",
|
|
95
92
|
requirement: "device identity changed and must be re-approved",
|
|
96
93
|
remediationHint: "Review the refreshed device details, then approve the pending request.",
|
|
97
94
|
recoveryTitle: "Gateway device refresh approval required."
|
|
98
95
|
}
|
|
99
96
|
};
|
|
100
|
-
const
|
|
101
|
-
"
|
|
102
|
-
"
|
|
103
|
-
"
|
|
104
|
-
"
|
|
105
|
-
|
|
97
|
+
const AUTH_CONNECT_ERROR_CODES = /* @__PURE__ */ new Map([
|
|
98
|
+
["token_missing", ConnectErrorDetailCodes.AUTH_TOKEN_MISSING],
|
|
99
|
+
["token_mismatch", ConnectErrorDetailCodes.AUTH_TOKEN_MISMATCH],
|
|
100
|
+
["token_missing_config", ConnectErrorDetailCodes.AUTH_TOKEN_NOT_CONFIGURED],
|
|
101
|
+
["password_missing", ConnectErrorDetailCodes.AUTH_PASSWORD_MISSING],
|
|
102
|
+
["password_mismatch", ConnectErrorDetailCodes.AUTH_PASSWORD_MISMATCH],
|
|
103
|
+
["password_missing_config", ConnectErrorDetailCodes.AUTH_PASSWORD_NOT_CONFIGURED],
|
|
104
|
+
["bootstrap_token_invalid", ConnectErrorDetailCodes.AUTH_BOOTSTRAP_TOKEN_INVALID],
|
|
105
|
+
["tailscale_user_missing", ConnectErrorDetailCodes.AUTH_TAILSCALE_IDENTITY_MISSING],
|
|
106
|
+
["tailscale_proxy_missing", ConnectErrorDetailCodes.AUTH_TAILSCALE_PROXY_MISSING],
|
|
107
|
+
["tailscale_whois_failed", ConnectErrorDetailCodes.AUTH_TAILSCALE_WHOIS_FAILED],
|
|
108
|
+
["tailscale_user_mismatch", ConnectErrorDetailCodes.AUTH_TAILSCALE_IDENTITY_MISMATCH],
|
|
109
|
+
["rate_limited", ConnectErrorDetailCodes.AUTH_RATE_LIMITED],
|
|
110
|
+
["device_token_mismatch", ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH],
|
|
111
|
+
["scope_mismatch", ConnectErrorDetailCodes.AUTH_SCOPE_MISMATCH],
|
|
112
|
+
[void 0, ConnectErrorDetailCodes.AUTH_REQUIRED]
|
|
113
|
+
]);
|
|
114
|
+
const DEVICE_AUTH_CONNECT_ERROR_CODES = /* @__PURE__ */ new Map([
|
|
115
|
+
["device-id-mismatch", ConnectErrorDetailCodes.DEVICE_AUTH_DEVICE_ID_MISMATCH],
|
|
116
|
+
["device-signature-stale", ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_EXPIRED],
|
|
117
|
+
["device-nonce-missing", ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_REQUIRED],
|
|
118
|
+
["device-nonce-mismatch", ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_MISMATCH],
|
|
119
|
+
["device-signature", ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_INVALID],
|
|
120
|
+
["device-public-key", ConnectErrorDetailCodes.DEVICE_AUTH_PUBLIC_KEY_INVALID]
|
|
121
|
+
]);
|
|
106
122
|
/** Maps internal auth failure reasons to public connect-error detail codes. */
|
|
107
123
|
function resolveAuthConnectErrorDetailCode(reason) {
|
|
108
124
|
if (reason?.startsWith("trusted_proxy_missing_header_")) return ConnectErrorDetailCodes.AUTH_IDENTITY_HEADER_REQUIRED;
|
|
109
|
-
|
|
110
|
-
case "token_missing": return ConnectErrorDetailCodes.AUTH_TOKEN_MISSING;
|
|
111
|
-
case "token_mismatch": return ConnectErrorDetailCodes.AUTH_TOKEN_MISMATCH;
|
|
112
|
-
case "token_missing_config": return ConnectErrorDetailCodes.AUTH_TOKEN_NOT_CONFIGURED;
|
|
113
|
-
case "password_missing": return ConnectErrorDetailCodes.AUTH_PASSWORD_MISSING;
|
|
114
|
-
case "password_mismatch": return ConnectErrorDetailCodes.AUTH_PASSWORD_MISMATCH;
|
|
115
|
-
case "password_missing_config": return ConnectErrorDetailCodes.AUTH_PASSWORD_NOT_CONFIGURED;
|
|
116
|
-
case "bootstrap_token_invalid": return ConnectErrorDetailCodes.AUTH_BOOTSTRAP_TOKEN_INVALID;
|
|
117
|
-
case "tailscale_user_missing": return ConnectErrorDetailCodes.AUTH_TAILSCALE_IDENTITY_MISSING;
|
|
118
|
-
case "tailscale_proxy_missing": return ConnectErrorDetailCodes.AUTH_TAILSCALE_PROXY_MISSING;
|
|
119
|
-
case "tailscale_whois_failed": return ConnectErrorDetailCodes.AUTH_TAILSCALE_WHOIS_FAILED;
|
|
120
|
-
case "tailscale_user_mismatch": return ConnectErrorDetailCodes.AUTH_TAILSCALE_IDENTITY_MISMATCH;
|
|
121
|
-
case "rate_limited": return ConnectErrorDetailCodes.AUTH_RATE_LIMITED;
|
|
122
|
-
case "device_token_mismatch": return ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH;
|
|
123
|
-
case "scope_mismatch": return ConnectErrorDetailCodes.AUTH_SCOPE_MISMATCH;
|
|
124
|
-
case void 0: return ConnectErrorDetailCodes.AUTH_REQUIRED;
|
|
125
|
-
default: return ConnectErrorDetailCodes.AUTH_UNAUTHORIZED;
|
|
126
|
-
}
|
|
125
|
+
return AUTH_CONNECT_ERROR_CODES.get(reason) ?? ConnectErrorDetailCodes.AUTH_UNAUTHORIZED;
|
|
127
126
|
}
|
|
128
127
|
/** Maps device-auth verifier reasons to public connect-error detail codes. */
|
|
129
128
|
function resolveDeviceAuthConnectErrorDetailCode(reason) {
|
|
130
|
-
|
|
131
|
-
case "device-id-mismatch": return ConnectErrorDetailCodes.DEVICE_AUTH_DEVICE_ID_MISMATCH;
|
|
132
|
-
case "device-signature-stale": return ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_EXPIRED;
|
|
133
|
-
case "device-nonce-missing": return ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_REQUIRED;
|
|
134
|
-
case "device-nonce-mismatch": return ConnectErrorDetailCodes.DEVICE_AUTH_NONCE_MISMATCH;
|
|
135
|
-
case "device-signature": return ConnectErrorDetailCodes.DEVICE_AUTH_SIGNATURE_INVALID;
|
|
136
|
-
case "device-public-key": return ConnectErrorDetailCodes.DEVICE_AUTH_PUBLIC_KEY_INVALID;
|
|
137
|
-
default: return ConnectErrorDetailCodes.DEVICE_AUTH_INVALID;
|
|
138
|
-
}
|
|
129
|
+
return DEVICE_AUTH_CONNECT_ERROR_CODES.get(reason) ?? ConnectErrorDetailCodes.DEVICE_AUTH_INVALID;
|
|
139
130
|
}
|
|
140
131
|
/** Reads a non-empty detail code from an untrusted error details payload. */
|
|
141
132
|
function readConnectErrorDetailCode(details) {
|
|
142
133
|
if (!isRecord(details)) return null;
|
|
143
|
-
|
|
144
|
-
return typeof code === "string" && code.trim().length > 0 ? code.trim() : null;
|
|
134
|
+
return normalizeOptionalString(details.code) ?? null;
|
|
145
135
|
}
|
|
146
136
|
/** Read the exact target artifact from an untrusted reload-required rejection. */
|
|
147
137
|
function readControlUiBuildMismatchId(details) {
|
|
@@ -162,11 +152,11 @@ function readConnectErrorRecoveryAdvice(details) {
|
|
|
162
152
|
}
|
|
163
153
|
function normalizeConnectRecoveryNextStep(value) {
|
|
164
154
|
const normalized = normalizeOptionalString(value) ?? "";
|
|
165
|
-
return CONNECT_RECOVERY_NEXT_STEP_VALUES.
|
|
155
|
+
return CONNECT_RECOVERY_NEXT_STEP_VALUES.find((candidate) => candidate === normalized);
|
|
166
156
|
}
|
|
167
157
|
function normalizePairingConnectReason(value) {
|
|
168
158
|
const normalized = normalizeOptionalString(value) ?? "";
|
|
169
|
-
return
|
|
159
|
+
return Object.hasOwn(PAIRING_CONNECT_REASON_METADATA, normalized) ? normalized : void 0;
|
|
170
160
|
}
|
|
171
161
|
/** Normalizes pairing request ids before echoing them in close reasons or UI text. */
|
|
172
162
|
function normalizePairingConnectRequestId(value) {
|
|
@@ -197,36 +187,31 @@ function describePairingConnectRequirement(reason) {
|
|
|
197
187
|
function buildPairingConnectErrorMessage(reason) {
|
|
198
188
|
return reason ? `pairing required: ${describePairingConnectRequirement(reason)}` : "pairing required";
|
|
199
189
|
}
|
|
200
|
-
function buildPairingConnectRemediationHint(reason) {
|
|
201
|
-
return reason ? PAIRING_CONNECT_REASON_METADATA[reason].remediationHint : "Approve the pending device request before retrying.";
|
|
202
|
-
}
|
|
203
190
|
/** Short user-facing recovery title for pairing-required connect failures. */
|
|
204
191
|
function buildPairingConnectRecoveryTitle(reason) {
|
|
205
192
|
return reason ? PAIRING_CONNECT_REASON_METADATA[reason].recoveryTitle : "Gateway pairing approval required.";
|
|
206
193
|
}
|
|
207
194
|
/** Builds sanitized structured details for a pairing-required connect failure. */
|
|
208
195
|
function buildPairingConnectErrorDetails(params) {
|
|
209
|
-
const requestId = normalizePairingConnectRequestId(params.requestId);
|
|
210
|
-
const remediationHint = normalizeOptionalString(params.remediationHint) ?? buildPairingConnectRemediationHint(params.reason);
|
|
211
|
-
const deviceId = normalizeOptionalString(params.deviceId);
|
|
212
|
-
const requestedRole = normalizeOptionalString(params.requestedRole);
|
|
213
|
-
const requestedScopes = normalizeOptionalTrimmedStringList(params.requestedScopes);
|
|
214
|
-
const approvedRoles = normalizeOptionalTrimmedStringList(params.approvedRoles);
|
|
215
|
-
const approvedScopes = normalizeOptionalTrimmedStringList(params.approvedScopes);
|
|
216
196
|
return createPairingConnectErrorDetails({
|
|
197
|
+
...normalizePairingConnectMetadata(params, params.reason),
|
|
217
198
|
reason: params.reason,
|
|
218
|
-
requestId,
|
|
219
|
-
remediationHint,
|
|
220
199
|
recommendedNextStep: params.recommendedNextStep,
|
|
221
200
|
retryable: params.retryable,
|
|
222
|
-
pauseReconnect: params.pauseReconnect
|
|
223
|
-
deviceId,
|
|
224
|
-
requestedRole,
|
|
225
|
-
requestedScopes,
|
|
226
|
-
approvedRoles,
|
|
227
|
-
approvedScopes
|
|
201
|
+
pauseReconnect: params.pauseReconnect
|
|
228
202
|
});
|
|
229
203
|
}
|
|
204
|
+
function normalizePairingConnectMetadata(details, reason) {
|
|
205
|
+
return {
|
|
206
|
+
requestId: normalizePairingConnectRequestId(details.requestId),
|
|
207
|
+
remediationHint: normalizeOptionalString(details.remediationHint) ?? (reason ? PAIRING_CONNECT_REASON_METADATA[reason].remediationHint : "Approve the pending device request before retrying."),
|
|
208
|
+
deviceId: normalizeOptionalString(details.deviceId),
|
|
209
|
+
requestedRole: normalizeOptionalString(details.requestedRole),
|
|
210
|
+
requestedScopes: normalizeOptionalTrimmedStringList(details.requestedScopes),
|
|
211
|
+
approvedRoles: normalizeOptionalTrimmedStringList(details.approvedRoles),
|
|
212
|
+
approvedScopes: normalizeOptionalTrimmedStringList(details.approvedScopes)
|
|
213
|
+
};
|
|
214
|
+
}
|
|
230
215
|
/** Builds a sanitized close reason string for WebSocket pairing rejections. */
|
|
231
216
|
function buildPairingConnectCloseReason(params) {
|
|
232
217
|
const requestId = normalizePairingConnectRequestId(params.requestId);
|
|
@@ -238,26 +223,12 @@ function readPairingConnectErrorDetails(details) {
|
|
|
238
223
|
if (readConnectErrorDetailCode(details) !== ConnectErrorDetailCodes.PAIRING_REQUIRED) return null;
|
|
239
224
|
if (!isRecord(details)) return null;
|
|
240
225
|
const reason = normalizePairingConnectReason(details.reason);
|
|
241
|
-
const requestId = normalizePairingConnectRequestId(details.requestId);
|
|
242
|
-
const remediationHint = normalizeOptionalString(details.remediationHint) ?? buildPairingConnectRemediationHint(reason);
|
|
243
|
-
const recommendedNextStep = normalizeConnectRecoveryNextStep(details.recommendedNextStep);
|
|
244
|
-
const deviceId = normalizeOptionalString(details.deviceId);
|
|
245
|
-
const requestedRole = normalizeOptionalString(details.requestedRole);
|
|
246
|
-
const requestedScopes = normalizeOptionalTrimmedStringList(details.requestedScopes);
|
|
247
|
-
const approvedRoles = normalizeOptionalTrimmedStringList(details.approvedRoles);
|
|
248
|
-
const approvedScopes = normalizeOptionalTrimmedStringList(details.approvedScopes);
|
|
249
226
|
return createPairingConnectErrorDetails({
|
|
227
|
+
...normalizePairingConnectMetadata(details, reason),
|
|
250
228
|
reason,
|
|
251
|
-
|
|
252
|
-
remediationHint,
|
|
253
|
-
recommendedNextStep,
|
|
229
|
+
recommendedNextStep: normalizeConnectRecoveryNextStep(details.recommendedNextStep),
|
|
254
230
|
retryable: typeof details.retryable === "boolean" ? details.retryable : void 0,
|
|
255
|
-
pauseReconnect: typeof details.pauseReconnect === "boolean" ? details.pauseReconnect : void 0
|
|
256
|
-
deviceId,
|
|
257
|
-
requestedRole,
|
|
258
|
-
requestedScopes,
|
|
259
|
-
approvedRoles,
|
|
260
|
-
approvedScopes
|
|
231
|
+
pauseReconnect: typeof details.pauseReconnect === "boolean" ? details.pauseReconnect : void 0
|
|
261
232
|
});
|
|
262
233
|
}
|
|
263
234
|
/** Parses legacy/string-only pairing-required messages into structured details. */
|
|
@@ -266,11 +237,11 @@ function readConnectPairingRequiredMessage(message) {
|
|
|
266
237
|
if (!normalizedMessage) return null;
|
|
267
238
|
const normalized = normalizedMessage.trim().toLowerCase();
|
|
268
239
|
let reason;
|
|
269
|
-
for (const [candidate,
|
|
240
|
+
for (const [candidate, metadata] of Object.entries(PAIRING_CONNECT_REASON_METADATA)) if (normalized.includes(metadata.message)) {
|
|
270
241
|
reason = candidate;
|
|
271
242
|
break;
|
|
272
243
|
}
|
|
273
|
-
if (!reason && normalized.includes("pairing required")) reason =
|
|
244
|
+
if (!reason && normalized.includes("pairing required")) reason = "not-paired";
|
|
274
245
|
if (!reason) return null;
|
|
275
246
|
const requestId = normalizePairingConnectRequestId(normalizedMessage.match(/\(requestId:\s*([^\s)]+)\)/i)?.[1]);
|
|
276
247
|
return {
|
|
@@ -343,7 +314,7 @@ function classifyGatewayConnectFailure(input) {
|
|
|
343
314
|
/** Formats pairing-required details into the canonical user-facing message. */
|
|
344
315
|
function formatConnectPairingRequiredMessage(details) {
|
|
345
316
|
const pairing = readPairingConnectErrorDetails(details);
|
|
346
|
-
const base =
|
|
317
|
+
const base = PAIRING_CONNECT_REASON_METADATA[pairing?.reason ?? "not-paired"].message;
|
|
347
318
|
return pairing?.requestId ? `${base} (requestId: ${pairing.requestId})` : base;
|
|
348
319
|
}
|
|
349
320
|
/** Formats connect errors using structured details before falling back to raw messages. */
|
package/dist/frame-guards.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as EventFrame, d as RequestFrame, l as HelloOk, p as ResponseFrame, r as ErrorShape, s as GatewayFrame, t as ConnectParams, y as GATEWAY_SERVER_CAPS } from "./frames-
|
|
1
|
+
import { a as EventFrame, d as RequestFrame, l as HelloOk, p as ResponseFrame, r as ErrorShape, s as GatewayFrame, t as ConnectParams, y as GATEWAY_SERVER_CAPS } from "./frames-DrSBm15j.mjs";
|
|
2
2
|
//#region packages/gateway-protocol/src/frame-guards.d.ts
|
|
3
3
|
export declare function isGatewayEventFrame(value: unknown): value is EventFrame;
|
|
4
4
|
export declare function isGatewayResponseFrame(value: unknown): value is ResponseFrame;
|
package/dist/frame-guards.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { r as isRecord } from "./record-coerce-DVQGe6I0.mjs";
|
|
2
2
|
import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-Oati9UF1.mjs";
|
|
3
|
-
import { t as GATEWAY_SERVER_CAPS } from "./server-capabilities-
|
|
3
|
+
import { t as GATEWAY_SERVER_CAPS } from "./server-capabilities-BTjjxElt.mjs";
|
|
4
4
|
//#region packages/gateway-protocol/src/frame-guards.ts
|
|
5
5
|
function isNonNegativeInteger(value) {
|
|
6
6
|
return typeof value === "number" && Number.isInteger(value) && value >= 0;
|
|
@@ -6,10 +6,21 @@ declare const GATEWAY_SERVER_CAPS: {
|
|
|
6
6
|
readonly CHAT_SEND_ROUTING_CONTRACT: "chat-send-routing-contract";
|
|
7
7
|
readonly CONTROL_UI_BROWSER_FOCUS: "control-ui-browser-focus";
|
|
8
8
|
readonly GATEWAY_RESTART_TARGET_SAFE: "gateway-restart-target-safe-v1";
|
|
9
|
+
readonly LOCAL_STATE_OWNER_ROUTING: "local-state-owner-routing-v1";
|
|
10
|
+
readonly CHANNELS_PAIRING_LIST_OWNER: "channels-pairing-list-owner-v1";
|
|
11
|
+
readonly CHANNELS_PAIRING_APPROVE_OWNER: "channels-pairing-approve-owner-v1";
|
|
12
|
+
readonly EXEC_APPROVALS_GET_OWNER: "exec-approvals-get-owner-v1";
|
|
13
|
+
readonly EXEC_APPROVALS_SET_OWNER: "exec-approvals-set-owner-v1";
|
|
14
|
+
readonly WORKTREES_REMOVE_OWNER: "worktrees-remove-owner-v1";
|
|
15
|
+
readonly WORKTREES_RESTORE_OWNER: "worktrees-restore-owner-v1";
|
|
16
|
+
readonly WORKTREES_GC_OWNER: "worktrees-gc-owner-v1";
|
|
17
|
+
readonly WORKTREES_RECOVER_REMOVAL_OWNER: "worktrees-recover-removal-owner-v1";
|
|
18
|
+
readonly WORKTREES_RETIRE_SNAPSHOT_OWNER: "worktrees-retire-snapshot-owner-v1";
|
|
9
19
|
readonly MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot";
|
|
10
20
|
readonly NODE_WORKER_BUNDLE_RETENTION: "node-worker-bundle-retention-v1";
|
|
11
21
|
readonly NODE_WORKER_BUNDLE_STATUS: "node-worker-bundle-status-v1";
|
|
12
22
|
readonly NODE_WORKER_CAPTURED_EXEC_POLICY: "node-worker-captured-exec-policy";
|
|
23
|
+
readonly NODE_WORKER_WORKSPACE_QUIESCENCE: "node-worker-workspace-quiescence-v1";
|
|
13
24
|
readonly NODE_WORKER_ENVIRONMENT_SESSION: "node-worker-environment-session-v1";
|
|
14
25
|
readonly NODE_WORKER_HOST_DIAGNOSTICS: "node-worker-host-diagnostics-v1";
|
|
15
26
|
readonly NODE_WORKER_IDLE_RETENTION: "node-worker-idle-retention-v1";
|
|
@@ -31,17 +42,9 @@ declare const GATEWAY_SERVER_CAPS: {
|
|
|
31
42
|
};
|
|
32
43
|
//#endregion
|
|
33
44
|
//#region packages/gateway-protocol/src/schema/frames.d.ts
|
|
34
|
-
/**
|
|
35
|
-
* Top-level gateway frame schemas.
|
|
36
|
-
*
|
|
37
|
-
* These are the WebSocket envelope contracts; method/event payload schemas live
|
|
38
|
-
* in feature-specific modules and are referenced by runtime validators.
|
|
39
|
-
*/
|
|
40
|
-
/** Periodic server heartbeat event payload. */
|
|
41
45
|
declare const TickEventSchema: Type.TObject<{
|
|
42
46
|
ts: Type.TInteger;
|
|
43
47
|
}>;
|
|
44
|
-
/** Server shutdown notice event payload. */
|
|
45
48
|
declare const ShutdownEventSchema: Type.TObject<{
|
|
46
49
|
reason: Type.TString;
|
|
47
50
|
restartExpectedMs: Type.TOptional<Type.TInteger>;
|
|
@@ -105,7 +108,6 @@ declare const ConnectParamsSchema: Type.TObject<{
|
|
|
105
108
|
locale: Type.TOptional<Type.TString>;
|
|
106
109
|
userAgent: Type.TOptional<Type.TString>;
|
|
107
110
|
}>;
|
|
108
|
-
/** Successful gateway hello response with the server protocol and initial state. */
|
|
109
111
|
declare const HelloOkSchema: Type.TObject<{
|
|
110
112
|
type: Type.TLiteral<"hello-ok">;
|
|
111
113
|
protocol: Type.TInteger;
|
|
@@ -327,7 +329,7 @@ declare const HelloOkSchema: Type.TObject<{
|
|
|
327
329
|
channel: Type.TString;
|
|
328
330
|
autoEnabled: Type.TBoolean;
|
|
329
331
|
install: Type.TOptional<Type.TObject<{
|
|
330
|
-
kind: Type.TUnion<[Type.TLiteral<"package">, Type.TLiteral<"git">, Type.TLiteral<"unknown">]>;
|
|
332
|
+
kind: Type.TUnion<[Type.TLiteral<"package">, Type.TLiteral<"git">, Type.TLiteral<"immutable">, Type.TLiteral<"unknown">]>;
|
|
331
333
|
git: Type.TOptional<Type.TUnion<[Type.TObject<{
|
|
332
334
|
currentSha: Type.TOptional<Type.TString>;
|
|
333
335
|
upstreamSha: Type.TOptional<Type.TString>;
|
|
@@ -369,6 +371,30 @@ declare const HelloOkSchema: Type.TObject<{
|
|
|
369
371
|
status: Type.TLiteral<"unavailable">;
|
|
370
372
|
reason: Type.TUnion<[Type.TLiteral<"fetch-failed">, Type.TLiteral<"no-upstream">, Type.TLiteral<"no-upstream-sha">, Type.TLiteral<"comparison-failed">, Type.TLiteral<"git-unavailable">]>;
|
|
371
373
|
}>]>>;
|
|
374
|
+
immutable: Type.TOptional<Type.TObject<{
|
|
375
|
+
root: Type.TString;
|
|
376
|
+
currentSha: Type.TString;
|
|
377
|
+
currentPath: Type.TString;
|
|
378
|
+
activationEnabled: Type.TOptional<Type.TBoolean>;
|
|
379
|
+
activation: Type.TOptional<Type.TObject<{
|
|
380
|
+
operationId: Type.TString;
|
|
381
|
+
phase: Type.TUnion<[Type.TLiteral<"prepared">, Type.TLiteral<"draining">, Type.TLiteral<"stopping">, Type.TLiteral<"stopped">, Type.TLiteral<"publishing">, Type.TLiteral<"starting">, Type.TLiteral<"verifying">, Type.TLiteral<"rollback-stopping">, Type.TLiteral<"rollback-publishing">, Type.TLiteral<"rollback-starting">, Type.TLiteral<"rolled-back">, Type.TLiteral<"recovery-required">]>;
|
|
382
|
+
previousSha: Type.TString;
|
|
383
|
+
candidateSha: Type.TString;
|
|
384
|
+
}>>;
|
|
385
|
+
lastActivation: Type.TOptional<Type.TObject<{
|
|
386
|
+
operationId: Type.TString;
|
|
387
|
+
outcome: Type.TUnion<[Type.TLiteral<"succeeded">, Type.TLiteral<"rolled-back">]>;
|
|
388
|
+
selectedSha: Type.TString;
|
|
389
|
+
verifiedAtMs: Type.TInteger;
|
|
390
|
+
}>>;
|
|
391
|
+
prepared: Type.TOptional<Type.TObject<{
|
|
392
|
+
sha: Type.TString;
|
|
393
|
+
path: Type.TString;
|
|
394
|
+
buildDigest: Type.TString;
|
|
395
|
+
preparedAtMs: Type.TInteger;
|
|
396
|
+
}>>;
|
|
397
|
+
}>>;
|
|
372
398
|
}>>;
|
|
373
399
|
target: Type.TOptional<Type.TUnion<[Type.TObject<{
|
|
374
400
|
kind: Type.TLiteral<"package">;
|
|
@@ -430,6 +456,7 @@ declare const HelloOkSchema: Type.TObject<{
|
|
|
430
456
|
recoveryScope: Type.TOptional<Type.TString>;
|
|
431
457
|
role: Type.TString;
|
|
432
458
|
scopes: Type.TArray<Type.TString>;
|
|
459
|
+
sessionCap: Type.TOptional<Type.TUnion<[Type.TLiteral<"write">, Type.TLiteral<"suggest">, Type.TLiteral<"view">, Type.TLiteral<"none">]>>;
|
|
433
460
|
issuedAtMs: Type.TOptional<Type.TInteger>;
|
|
434
461
|
deviceTokens: Type.TOptional<Type.TArray<Type.TObject<{
|
|
435
462
|
deviceToken: Type.TString;
|
|
@@ -467,7 +494,6 @@ declare const RequestFrameSchema: Type.TObject<{
|
|
|
467
494
|
traceparent: Type.TOptional<Type.TString>;
|
|
468
495
|
expectedProfileId: Type.TOptional<Type.TString>;
|
|
469
496
|
}>;
|
|
470
|
-
/** Server response frame envelope paired with a prior request id. */
|
|
471
497
|
declare const ResponseFrameSchema: Type.TObject<{
|
|
472
498
|
type: Type.TLiteral<"res">;
|
|
473
499
|
id: Type.TString;
|