@openclaw/gateway-protocol 2026.9.6 → 2026.9.8

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.
Files changed (36) hide show
  1. package/README.md +4 -0
  2. package/dist/client-info.d.mts +2 -1
  3. package/dist/client-info.mjs +3 -2
  4. package/dist/connect-error-details.d.mts +4 -3
  5. package/dist/connect-error-details.mjs +13 -16
  6. package/dist/frame-guards.d.mts +2 -2
  7. package/dist/frame-guards.mjs +4 -4
  8. package/dist/{frames-DrA9fYYy.d.mts → frames-ICrB58JF.d.mts} +32 -11
  9. package/dist/{gateway-error-details-B0Ms-xqB.d.mts → gateway-error-details-BH1DM8mu.d.mts} +462 -385
  10. package/dist/gateway-error-details.d.mts +1 -1
  11. package/dist/gateway-error-details.mjs +6 -6
  12. package/dist/index.d.mts +3210 -2803
  13. package/dist/index.mjs +40 -110
  14. package/dist/{protocol-value-normalization-DfM01tqg.mjs → protocol-value-normalization-Oati9UF1.mjs} +1 -1
  15. package/dist/{record-coerce-BVp8Dr-B.mjs → record-coerce-DVQGe6I0.mjs} +1 -1
  16. package/dist/restart-unavailable.d.mts +3 -1
  17. package/dist/restart-unavailable.mjs +4 -2
  18. package/dist/{schema-modules-CClcdadz.d.mts → schema-modules-CRgBq9O3.d.mts} +2759 -1911
  19. package/dist/schema.d.mts +10 -9
  20. package/dist/schema.mjs +50 -21
  21. package/dist/{server-capabilities-CBMEqI9z.mjs → server-capabilities-BnyAklc1.mjs} +6 -1
  22. package/dist/startup-unavailable.d.mts +1 -1
  23. package/dist/startup-unavailable.mjs +1 -1
  24. package/dist/{string-coerce-BJ6bjzdv.mjs → string-coerce-BSD-wsXs.mjs} +1 -1
  25. package/dist/system-agent-context.d.mts +1 -1
  26. package/dist/system-agent-context.mjs +8 -7
  27. package/dist/{theme-DEbDprgp.mjs → theme-_hQKgfH-.mjs} +2 -2
  28. package/dist/{theme-C4mhgADx.d.mts → theme-s6T9Ck6Z.d.mts} +2 -2
  29. package/dist/theme.d.mts +1 -1
  30. package/dist/theme.mjs +1 -1
  31. package/dist/{tools-catalog-CRxZFldZ.mjs → tools-catalog-pKZZLiUu.mjs} +1046 -768
  32. package/dist/{version-COV9CEyr.d.mts → version-BL42XeI-.d.mts} +1 -1
  33. package/dist/version.d.mts +1 -1
  34. package/dist/version.mjs +1 -1
  35. package/package.json +3 -3
  36. package/protocol.schema.json +8776 -4444
package/README.md CHANGED
@@ -89,6 +89,10 @@ names are open strings; consumers must not discard an unfamiliar owner phase.
89
89
  Validation does not authorize a stop or replace lease, process-identity, and
90
90
  readiness checks owned by the controller.
91
91
 
92
+ Leave `includeLifecycle` unset when using older published status validators.
93
+ Request `includeLifecycle: true` only with a validator that supports `ownerId`
94
+ and `phase`.
95
+
92
96
  ## Guard an event without TypeBox
93
97
 
94
98
  Use the lightweight guards when code only needs safe frame discrimination. They
@@ -1,4 +1,4 @@
1
- //#region src/client-info.d.ts
1
+ //#region packages/gateway-protocol/src/client-info.d.ts
2
2
  /** Canonical client ids accepted in gateway hello/connect payloads. */
3
3
  export declare const GATEWAY_CLIENT_IDS: {
4
4
  readonly WEBCHAT_UI: "webchat-ui";
@@ -82,6 +82,7 @@ export type GatewayClientInfo = {
82
82
  export declare const GATEWAY_CLIENT_CAPS: {
83
83
  readonly AGENT_KIND: "agent-kind";
84
84
  readonly APPROVALS: "approvals";
85
+ readonly CHAT_ONLY_ASSISTANT_TEXT: "chat-only-assistant-text";
85
86
  readonly EXEC_APPROVALS: "exec-approvals";
86
87
  readonly INLINE_WIDGETS: "inline-widgets";
87
88
  readonly MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot";
@@ -1,5 +1,5 @@
1
- import { t as normalizeOptionalLowercaseString } from "./string-coerce-BJ6bjzdv.mjs";
2
- //#region src/client-info.ts
1
+ import { t as normalizeOptionalLowercaseString } from "./string-coerce-BSD-wsXs.mjs";
2
+ //#region packages/gateway-protocol/src/client-info.ts
3
3
  /**
4
4
  * Shared gateway client identity contract.
5
5
  *
@@ -42,6 +42,7 @@ const GATEWAY_CLIENT_MODES = {
42
42
  const GATEWAY_CLIENT_CAPS = {
43
43
  AGENT_KIND: "agent-kind",
44
44
  APPROVALS: "approvals",
45
+ CHAT_ONLY_ASSISTANT_TEXT: "chat-only-assistant-text",
45
46
  EXEC_APPROVALS: "exec-approvals",
46
47
  INLINE_WIDGETS: "inline-widgets",
47
48
  MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot",
@@ -1,4 +1,4 @@
1
- //#region src/connect-error-details.d.ts
1
+ //#region packages/gateway-protocol/src/connect-error-details.d.ts
2
2
  /** Structured connect-error codes carried in gateway error `details.code`. */
3
3
  export declare const ConnectErrorDetailCodes: {
4
4
  readonly AUTH_REQUIRED: "AUTH_REQUIRED";
@@ -20,6 +20,7 @@ export declare const ConnectErrorDetailCodes: {
20
20
  readonly AUTH_IDENTITY_HEADER_REQUIRED: "AUTH_IDENTITY_HEADER_REQUIRED";
21
21
  readonly AUTH_VERIFIED_USER_REQUIRED: "AUTH_VERIFIED_USER_REQUIRED";
22
22
  readonly AUTHENTICATED_PROFILE_UNAVAILABLE: "AUTHENTICATED_PROFILE_UNAVAILABLE";
23
+ readonly OPERATOR_ACCESS_DENIED: "OPERATOR_ACCESS_DENIED";
23
24
  readonly CONTROL_UI_BUILD_MISMATCH: "CONTROL_UI_BUILD_MISMATCH";
24
25
  readonly CONTROL_UI_ORIGIN_NOT_ALLOWED: "CONTROL_UI_ORIGIN_NOT_ALLOWED";
25
26
  readonly PROTOCOL_MISMATCH: "PROTOCOL_MISMATCH";
@@ -113,9 +114,9 @@ export declare function classifyGatewayConnectFailure(input: {
113
114
  userMessage: string;
114
115
  remediation: string;
115
116
  } | {
116
- remediation?: string | undefined;
117
- kind: "device-identity-required" | "scope-mismatch" | "rate-limited" | "auth-rejected" | "gateway-rejected" | "unreachable";
117
+ kind: "auth-rejected" | "device-identity-required" | "gateway-rejected" | "rate-limited" | "scope-mismatch" | "unreachable";
118
118
  userMessage: string;
119
+ remediation?: string | undefined;
119
120
  };
120
121
  /** Formats pairing-required details into the canonical user-facing message. */
121
122
  export declare function formatConnectPairingRequiredMessage(details: unknown): string;
@@ -1,6 +1,6 @@
1
- import { n as normalizeOptionalString } from "./string-coerce-BJ6bjzdv.mjs";
2
- import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
3
- //#region ../normalization-core/src/string-normalization.ts
1
+ import { n as normalizeOptionalString } from "./string-coerce-BSD-wsXs.mjs";
2
+ import { r as isRecord } from "./record-coerce-DVQGe6I0.mjs";
3
+ //#region packages/normalization-core/src/string-normalization.ts
4
4
  /** Normalizes array-backed string lists and rejects non-array input as empty. */
5
5
  function normalizeTrimmedStringList(value) {
6
6
  if (!Array.isArray(value)) return [];
@@ -15,7 +15,7 @@ function normalizeOptionalTrimmedStringList(value) {
15
15
  return normalized.length > 0 ? normalized : void 0;
16
16
  }
17
17
  //#endregion
18
- //#region src/connect-error-details.ts
18
+ //#region packages/gateway-protocol/src/connect-error-details.ts
19
19
  /**
20
20
  * Shared gateway connect-error detail helpers.
21
21
  *
@@ -43,6 +43,7 @@ const ConnectErrorDetailCodes = {
43
43
  AUTH_IDENTITY_HEADER_REQUIRED: "AUTH_IDENTITY_HEADER_REQUIRED",
44
44
  AUTH_VERIFIED_USER_REQUIRED: "AUTH_VERIFIED_USER_REQUIRED",
45
45
  AUTHENTICATED_PROFILE_UNAVAILABLE: "AUTHENTICATED_PROFILE_UNAVAILABLE",
46
+ OPERATOR_ACCESS_DENIED: "OPERATOR_ACCESS_DENIED",
46
47
  CONTROL_UI_BUILD_MISMATCH: "CONTROL_UI_BUILD_MISMATCH",
47
48
  CONTROL_UI_ORIGIN_NOT_ALLOWED: "CONTROL_UI_ORIGIN_NOT_ALLOWED",
48
49
  PROTOCOL_MISMATCH: "PROTOCOL_MISMATCH",
@@ -72,12 +73,7 @@ const CONNECT_RECOVERY_NEXT_STEP_VALUES = /* @__PURE__ */ new Set([
72
73
  "wait_then_retry",
73
74
  "review_auth_configuration"
74
75
  ]);
75
- const CONNECT_PAIRING_REQUIRED_REASON_VALUES = /* @__PURE__ */ new Set([
76
- "not-paired",
77
- "role-upgrade",
78
- "scope-upgrade",
79
- "metadata-upgrade"
80
- ]);
76
+ const CONNECT_PAIRING_REQUIRED_REASON_VALUES = new Set(Object.values(ConnectPairingRequiredReasons));
81
77
  const PAIRING_CONNECT_REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
82
78
  const PAIRING_CONNECT_REASON_METADATA = {
83
79
  "not-paired": {
@@ -159,13 +155,15 @@ function readControlUiBuildMismatchId(details) {
159
155
  /** Extracts normalized retry advice from untrusted connect-error details. */
160
156
  function readConnectErrorRecoveryAdvice(details) {
161
157
  if (!isRecord(details)) return {};
162
- const canRetryWithDeviceToken = typeof details.canRetryWithDeviceToken === "boolean" ? details.canRetryWithDeviceToken : void 0;
163
- const normalizedNextStep = normalizeOptionalString(details.recommendedNextStep) ?? "";
164
158
  return {
165
- canRetryWithDeviceToken,
166
- recommendedNextStep: CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0
159
+ canRetryWithDeviceToken: typeof details.canRetryWithDeviceToken === "boolean" ? details.canRetryWithDeviceToken : void 0,
160
+ recommendedNextStep: normalizeConnectRecoveryNextStep(details.recommendedNextStep)
167
161
  };
168
162
  }
163
+ function normalizeConnectRecoveryNextStep(value) {
164
+ const normalized = normalizeOptionalString(value) ?? "";
165
+ return CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalized) ? normalized : void 0;
166
+ }
169
167
  function normalizePairingConnectReason(value) {
170
168
  const normalized = normalizeOptionalString(value) ?? "";
171
169
  return CONNECT_PAIRING_REQUIRED_REASON_VALUES.has(normalized) ? normalized : void 0;
@@ -242,8 +240,7 @@ function readPairingConnectErrorDetails(details) {
242
240
  const reason = normalizePairingConnectReason(details.reason);
243
241
  const requestId = normalizePairingConnectRequestId(details.requestId);
244
242
  const remediationHint = normalizeOptionalString(details.remediationHint) ?? buildPairingConnectRemediationHint(reason);
245
- const normalizedNextStep = normalizeOptionalString(details.recommendedNextStep) ?? "";
246
- const recommendedNextStep = CONNECT_RECOVERY_NEXT_STEP_VALUES.has(normalizedNextStep) ? normalizedNextStep : void 0;
243
+ const recommendedNextStep = normalizeConnectRecoveryNextStep(details.recommendedNextStep);
247
244
  const deviceId = normalizeOptionalString(details.deviceId);
248
245
  const requestedRole = normalizeOptionalString(details.requestedRole);
249
246
  const requestedScopes = normalizeOptionalTrimmedStringList(details.requestedScopes);
@@ -1,5 +1,5 @@
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-DrA9fYYy.mjs";
2
- //#region src/frame-guards.d.ts
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-ICrB58JF.mjs";
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;
5
5
  //#endregion
@@ -1,7 +1,7 @@
1
- import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
2
- import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-DfM01tqg.mjs";
3
- import { t as GATEWAY_SERVER_CAPS } from "./server-capabilities-CBMEqI9z.mjs";
4
- //#region src/frame-guards.ts
1
+ import { r as isRecord } from "./record-coerce-DVQGe6I0.mjs";
2
+ import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-Oati9UF1.mjs";
3
+ import { t as GATEWAY_SERVER_CAPS } from "./server-capabilities-BnyAklc1.mjs";
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;
7
7
  }
@@ -1,16 +1,21 @@
1
1
  import { Static, Type } from "typebox";
2
- //#region src/server-capabilities.d.ts
2
+ //#region packages/gateway-protocol/src/server-capabilities.d.ts
3
3
  /** Stable feature names advertised in Gateway hello responses. */
4
4
  declare const GATEWAY_SERVER_CAPS: {
5
5
  readonly BOARD_WIDGET_PUT_CANVAS_DOC: "board-widget-put-canvas-doc";
6
6
  readonly CHAT_SEND_ROUTING_CONTRACT: "chat-send-routing-contract";
7
+ readonly CONTROL_UI_BROWSER_FOCUS: "control-ui-browser-focus";
7
8
  readonly GATEWAY_RESTART_TARGET_SAFE: "gateway-restart-target-safe-v1";
8
9
  readonly MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot";
9
10
  readonly NODE_WORKER_BUNDLE_RETENTION: "node-worker-bundle-retention-v1";
10
11
  readonly NODE_WORKER_BUNDLE_STATUS: "node-worker-bundle-status-v1";
11
12
  readonly NODE_WORKER_CAPTURED_EXEC_POLICY: "node-worker-captured-exec-policy";
12
13
  readonly NODE_WORKER_ENVIRONMENT_SESSION: "node-worker-environment-session-v1";
14
+ readonly NODE_WORKER_HOST_DIAGNOSTICS: "node-worker-host-diagnostics-v1";
15
+ readonly NODE_WORKER_IDLE_RETENTION: "node-worker-idle-retention-v1";
16
+ readonly NODE_WORKER_LAUNCH_TOOL_NAMES: "node-worker-launch-tool-names-v1";
13
17
  readonly NODE_WORKER_PORTAL_STREAM: "node-worker-portal-stream-v1";
18
+ readonly NODE_WORKER_STATUS_WAIT: "node-worker-status-wait-v1";
14
19
  readonly PUBLISHED_MODEL_CATALOG: "published-model-catalog";
15
20
  readonly PROFILE_BINDING: "profile-binding-v1";
16
21
  readonly PROGRESS_CARD_AGENT_SCOPE: "progress-card-agent-scope-v1";
@@ -25,7 +30,7 @@ declare const GATEWAY_SERVER_CAPS: {
25
30
  readonly TASK_SUGGESTIONS_ACCEPT_MODES: "taskSuggestions.acceptModes";
26
31
  };
27
32
  //#endregion
28
- //#region src/schema/frames.d.ts
33
+ //#region packages/gateway-protocol/src/schema/frames.d.ts
29
34
  /**
30
35
  * Top-level gateway frame schemas.
31
36
  *
@@ -46,7 +51,7 @@ declare const ConnectParamsSchema: Type.TObject<{
46
51
  minProtocol: Type.TInteger;
47
52
  maxProtocol: Type.TInteger;
48
53
  client: Type.TObject<{
49
- 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"]>;
54
+ id: Type.TEnum<["openclaw-android", "openclaw-browser-copilot", "cli", "openclaw-control-ui", "fingerprint", "gateway-client", "openclaw-ios", "openclaw-linux", "openclaw-macos", "node-host", "openclaw-probe", "test", "openclaw-tui", "openclaw-watchos", "webchat", "webchat-ui", "openclaw-worker"]>;
50
55
  displayName: Type.TOptional<Type.TString>;
51
56
  version: Type.TString;
52
57
  buildId: Type.TOptional<Type.TString>;
@@ -55,7 +60,7 @@ declare const ConnectParamsSchema: Type.TObject<{
55
60
  modelIdentifier: Type.TOptional<Type.TString>;
56
61
  /** Self-reported IANA zone. Bounded because the longest real name is well under this cap. */
57
62
  timeZone: Type.TOptional<Type.TString>;
58
- mode: Type.TEnum<["webchat", "cli", "worker", "test", "probe", "ui", "backend", "node"]>;
63
+ mode: Type.TEnum<["backend", "cli", "node", "probe", "test", "ui", "webchat", "worker"]>;
59
64
  instanceId: Type.TOptional<Type.TString>;
60
65
  }>;
61
66
  caps: Type.TOptional<Type.TArray<Type.TString>>;
@@ -121,6 +126,7 @@ declare const HelloOkSchema: Type.TObject<{
121
126
  phase: Type.TUnion<[Type.TLiteral<"accepting">, Type.TLiteral<"preparing">, Type.TLiteral<"draining">, Type.TLiteral<"prepared">]>;
122
127
  }>>;
123
128
  presence: Type.TArray<Type.TObject<{
129
+ connectionId: Type.TOptional<Type.TString>;
124
130
  host: Type.TOptional<Type.TString>;
125
131
  clientId: Type.TOptional<Type.TString>;
126
132
  ip: Type.TOptional<Type.TString>;
@@ -137,6 +143,7 @@ declare const HelloOkSchema: Type.TObject<{
137
143
  ts: Type.TInteger;
138
144
  onlineSince: Type.TOptional<Type.TInteger>;
139
145
  lastActivityAt: Type.TOptional<Type.TInteger>;
146
+ connectionLastActivityAt: Type.TOptional<Type.TInteger>;
140
147
  deviceId: Type.TOptional<Type.TString>;
141
148
  roles: Type.TOptional<Type.TArray<Type.TString>>;
142
149
  scopes: Type.TOptional<Type.TArray<Type.TString>>;
@@ -240,6 +247,10 @@ declare const HelloOkSchema: Type.TObject<{
240
247
  configReload: Type.TOptional<Type.TObject<{
241
248
  hotReloadStatus: Type.TUnion<[Type.TLiteral<"active">, Type.TLiteral<"disabled">]>;
242
249
  }>>;
250
+ childRuntime: Type.TOptional<Type.TObject<{
251
+ execPath: Type.TString;
252
+ available: Type.TBoolean;
253
+ }>>;
243
254
  channels: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
244
255
  channelOrder: Type.TOptional<Type.TArray<Type.TString>>;
245
256
  channelLabels: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
@@ -318,35 +329,45 @@ declare const HelloOkSchema: Type.TObject<{
318
329
  install: Type.TOptional<Type.TObject<{
319
330
  kind: Type.TUnion<[Type.TLiteral<"package">, Type.TLiteral<"git">, Type.TLiteral<"unknown">]>;
320
331
  git: Type.TOptional<Type.TUnion<[Type.TObject<{
321
- status: Type.TLiteral<"current">;
322
332
  currentSha: Type.TOptional<Type.TString>;
333
+ upstreamSha: Type.TOptional<Type.TString>;
334
+ repositoryUrl: Type.TOptional<Type.TString>;
323
335
  commitAtMs: Type.TOptional<Type.TInteger>;
324
336
  installedAtMs: Type.TOptional<Type.TInteger>;
337
+ status: Type.TLiteral<"current">;
325
338
  }>, Type.TObject<{
339
+ currentSha: Type.TOptional<Type.TString>;
340
+ upstreamSha: Type.TOptional<Type.TString>;
341
+ repositoryUrl: Type.TOptional<Type.TString>;
342
+ commitAtMs: Type.TOptional<Type.TInteger>;
343
+ installedAtMs: Type.TOptional<Type.TInteger>;
326
344
  status: Type.TLiteral<"behind">;
327
345
  commitsBehind: Type.TInteger;
346
+ }>, Type.TObject<{
328
347
  currentSha: Type.TOptional<Type.TString>;
348
+ upstreamSha: Type.TOptional<Type.TString>;
349
+ repositoryUrl: Type.TOptional<Type.TString>;
329
350
  commitAtMs: Type.TOptional<Type.TInteger>;
330
351
  installedAtMs: Type.TOptional<Type.TInteger>;
331
- }>, Type.TObject<{
332
352
  status: Type.TLiteral<"ahead">;
333
353
  commitsAhead: Type.TInteger;
354
+ }>, Type.TObject<{
334
355
  currentSha: Type.TOptional<Type.TString>;
356
+ upstreamSha: Type.TOptional<Type.TString>;
357
+ repositoryUrl: Type.TOptional<Type.TString>;
335
358
  commitAtMs: Type.TOptional<Type.TInteger>;
336
359
  installedAtMs: Type.TOptional<Type.TInteger>;
337
- }>, Type.TObject<{
338
360
  status: Type.TLiteral<"diverged">;
339
361
  commitsAhead: Type.TInteger;
340
362
  commitsBehind: Type.TInteger;
363
+ }>, Type.TObject<{
341
364
  currentSha: Type.TOptional<Type.TString>;
365
+ upstreamSha: Type.TOptional<Type.TString>;
366
+ repositoryUrl: Type.TOptional<Type.TString>;
342
367
  commitAtMs: Type.TOptional<Type.TInteger>;
343
368
  installedAtMs: Type.TOptional<Type.TInteger>;
344
- }>, Type.TObject<{
345
369
  status: Type.TLiteral<"unavailable">;
346
370
  reason: Type.TUnion<[Type.TLiteral<"fetch-failed">, Type.TLiteral<"no-upstream">, Type.TLiteral<"no-upstream-sha">, Type.TLiteral<"comparison-failed">, Type.TLiteral<"git-unavailable">]>;
347
- currentSha: Type.TOptional<Type.TString>;
348
- commitAtMs: Type.TOptional<Type.TInteger>;
349
- installedAtMs: Type.TOptional<Type.TInteger>;
350
371
  }>]>>;
351
372
  }>>;
352
373
  target: Type.TOptional<Type.TUnion<[Type.TObject<{