@openclaw/gateway-protocol 2026.9.4 → 2026.9.6

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 CHANGED
@@ -81,6 +81,14 @@ console.log(frame.id, frame.method);
81
81
  the validator for the selected method's `params`; the root entry point exports those
82
82
  validators as `validate*Params` functions.
83
83
 
84
+ External lifecycle controllers can validate suspension responses with
85
+ `validateGatewaySuspendPrepareResult` and `validateGatewaySuspendStatusResult`.
86
+ These use the canonical result schemas without changing the payload. Preserve
87
+ optional `writeCustody`: absence means unknown custody, not an empty list. Phase
88
+ names are open strings; consumers must not discard an unfamiliar owner phase.
89
+ Validation does not authorize a stop or replace lease, process-identity, and
90
+ readiness checks owned by the controller.
91
+
84
92
  ## Guard an event without TypeBox
85
93
 
86
94
  Use the lightweight guards when code only needs safe frame discrimination. They
@@ -84,8 +84,11 @@ export declare const GATEWAY_CLIENT_CAPS: {
84
84
  readonly APPROVALS: "approvals";
85
85
  readonly EXEC_APPROVALS: "exec-approvals";
86
86
  readonly INLINE_WIDGETS: "inline-widgets";
87
+ readonly MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot";
88
+ readonly MODEL_SELECTION_POLICY: "model-selection-policy";
87
89
  readonly RUN_TOOL_BINDINGS: "run-tool-bindings";
88
90
  readonly SESSION_SCOPED_EVENTS: "session-scoped-events";
91
+ readonly SKILL_CURATOR_LIVE_INVENTORY: "skill-curator-live-inventory";
89
92
  readonly PLUGIN_APPROVALS: "plugin-approvals";
90
93
  readonly TASK_SUGGESTIONS: "task-suggestions";
91
94
  readonly TERMINAL_OFFSET_SEQ: "terminal-offset-seq";
@@ -44,8 +44,11 @@ const GATEWAY_CLIENT_CAPS = {
44
44
  APPROVALS: "approvals",
45
45
  EXEC_APPROVALS: "exec-approvals",
46
46
  INLINE_WIDGETS: "inline-widgets",
47
+ MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot",
48
+ MODEL_SELECTION_POLICY: "model-selection-policy",
47
49
  RUN_TOOL_BINDINGS: "run-tool-bindings",
48
50
  SESSION_SCOPED_EVENTS: "session-scoped-events",
51
+ SKILL_CURATOR_LIVE_INVENTORY: "skill-curator-live-inventory",
49
52
  PLUGIN_APPROVALS: "plugin-approvals",
50
53
  TASK_SUGGESTIONS: "task-suggestions",
51
54
  TERMINAL_OFFSET_SEQ: "terminal-offset-seq",
@@ -1,5 +1,5 @@
1
- import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
2
1
  import { n as normalizeOptionalString } from "./string-coerce-BJ6bjzdv.mjs";
2
+ import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
3
3
  //#region ../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) {
@@ -1,6 +1,6 @@
1
- import { a as EventFrame, d as RequestFrame, l as HelloOk, p as ResponseFrame, r as ErrorShape, s as GatewayFrame, t as ConnectParams } from "./frames-B3ABtpZk.mjs";
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
2
  //#region 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
6
- export type { ConnectParams, ErrorShape, EventFrame, GatewayFrame, HelloOk, RequestFrame, ResponseFrame };
6
+ export { type ConnectParams, type ErrorShape, type EventFrame, GATEWAY_SERVER_CAPS, type GatewayFrame, type HelloOk, type RequestFrame, type ResponseFrame };
@@ -1,5 +1,6 @@
1
1
  import { r as isRecord } from "./record-coerce-BVp8Dr-B.mjs";
2
2
  import { t as isNonEmptyProtocolString } from "./protocol-value-normalization-DfM01tqg.mjs";
3
+ import { t as GATEWAY_SERVER_CAPS } from "./server-capabilities-CBMEqI9z.mjs";
3
4
  //#region src/frame-guards.ts
4
5
  function isNonNegativeInteger(value) {
5
6
  return typeof value === "number" && Number.isInteger(value) && value >= 0;
@@ -19,4 +20,4 @@ function isGatewayResponseFrame(value) {
19
20
  return value.error === void 0 || isGatewayErrorShape(value.error);
20
21
  }
21
22
  //#endregion
22
- export { isGatewayEventFrame, isGatewayResponseFrame };
23
+ export { GATEWAY_SERVER_CAPS, isGatewayEventFrame, isGatewayResponseFrame };
@@ -1,4 +1,30 @@
1
1
  import { Static, Type } from "typebox";
2
+ //#region src/server-capabilities.d.ts
3
+ /** Stable feature names advertised in Gateway hello responses. */
4
+ declare const GATEWAY_SERVER_CAPS: {
5
+ readonly BOARD_WIDGET_PUT_CANVAS_DOC: "board-widget-put-canvas-doc";
6
+ readonly CHAT_SEND_ROUTING_CONTRACT: "chat-send-routing-contract";
7
+ readonly GATEWAY_RESTART_TARGET_SAFE: "gateway-restart-target-safe-v1";
8
+ readonly MODEL_CATALOG_SNAPSHOT: "model-catalog-snapshot";
9
+ readonly NODE_WORKER_BUNDLE_RETENTION: "node-worker-bundle-retention-v1";
10
+ readonly NODE_WORKER_BUNDLE_STATUS: "node-worker-bundle-status-v1";
11
+ readonly NODE_WORKER_CAPTURED_EXEC_POLICY: "node-worker-captured-exec-policy";
12
+ readonly NODE_WORKER_ENVIRONMENT_SESSION: "node-worker-environment-session-v1";
13
+ readonly NODE_WORKER_PORTAL_STREAM: "node-worker-portal-stream-v1";
14
+ readonly PUBLISHED_MODEL_CATALOG: "published-model-catalog";
15
+ readonly PROFILE_BINDING: "profile-binding-v1";
16
+ readonly PROGRESS_CARD_AGENT_SCOPE: "progress-card-agent-scope-v1";
17
+ readonly SESSION_SCOPED_CHAT_METADATA: "session-scoped-chat-metadata";
18
+ readonly SESSION_SCOPED_MODEL_CATALOG: "session-scoped-model-catalog";
19
+ readonly SESSION_UNREAD_ACK_CONTRACT: "session-unread-ack-contract";
20
+ readonly SESSION_GOAL_START: "session-goal-start-v1";
21
+ readonly SESSION_SETTINGS_CONTRACT: "session-settings-contract";
22
+ readonly SESSION_SETTINGS_CAS: "session-settings-cas-v1";
23
+ readonly SYSTEM_AGENT_WIZARD_CANCEL: "openclaw-chat-wizard-cancel";
24
+ readonly SYSTEM_AGENT_SETUP_MODEL_REF: "openclaw-setup-model-ref";
25
+ readonly TASK_SUGGESTIONS_ACCEPT_MODES: "taskSuggestions.acceptModes";
26
+ };
27
+ //#endregion
2
28
  //#region src/schema/frames.d.ts
3
29
  /**
4
30
  * Top-level gateway frame schemas.
@@ -47,6 +73,15 @@ declare const ConnectParamsSchema: Type.TObject<{
47
73
  pathEnv: Type.TOptional<Type.TString>;
48
74
  role: Type.TOptional<Type.TString>;
49
75
  scopes: Type.TOptional<Type.TArray<Type.TString>>;
76
+ /** Initial catalog read scope; method authorization still owns access. */
77
+ modelCatalog: Type.TOptional<Type.TUnion<[Type.TObject<{
78
+ agentId: Type.TOptional<Type.TString>;
79
+ sessionKey: Type.TOptional<Type.TString>;
80
+ }>, Type.TObject<{
81
+ agentId: Type.TOptional<Type.TString>;
82
+ shortId: Type.TString;
83
+ slugHint: Type.TOptional<Type.TString>;
84
+ }>]>>;
50
85
  device: Type.TOptional<Type.TObject<{
51
86
  id: Type.TString;
52
87
  publicKey: Type.TString;
@@ -87,6 +122,7 @@ declare const HelloOkSchema: Type.TObject<{
87
122
  }>>;
88
123
  presence: Type.TArray<Type.TObject<{
89
124
  host: Type.TOptional<Type.TString>;
125
+ clientId: Type.TOptional<Type.TString>;
90
126
  ip: Type.TOptional<Type.TString>;
91
127
  version: Type.TOptional<Type.TString>;
92
128
  platform: Type.TOptional<Type.TString>;
@@ -130,6 +166,13 @@ declare const HelloOkSchema: Type.TObject<{
130
166
  delayMaxMs: Type.TNumber;
131
167
  utilization: Type.TNumber;
132
168
  cpuCoreRatio: Type.TNumber;
169
+ cpuBreakdown: Type.TOptional<Type.TObject<{
170
+ mainThreadCoreRatio: Type.TOptional<Type.TNumber>;
171
+ workerCoreRatio: Type.TOptional<Type.TNumber>;
172
+ otherThreadsCoreRatio: Type.TOptional<Type.TNumber>;
173
+ hostUtilization: Type.TOptional<Type.TNumber>;
174
+ hostCpuCount: Type.TOptional<Type.TInteger>;
175
+ }>>;
133
176
  }>>;
134
177
  plugins: Type.TOptional<Type.TObject<{
135
178
  loaded: Type.TArray<Type.TString>;
@@ -262,6 +305,7 @@ declare const HelloOkSchema: Type.TObject<{
262
305
  currentSha: Type.TOptional<Type.TString>;
263
306
  upstreamRef: Type.TOptional<Type.TString>;
264
307
  upstreamSha: Type.TOptional<Type.TString>;
308
+ repositoryUrl: Type.TOptional<Type.TString>;
265
309
  commitsBehind: Type.TOptional<Type.TInteger>;
266
310
  commits: Type.TOptional<Type.TArray<Type.TObject<{
267
311
  sha: Type.TString;
@@ -344,6 +388,19 @@ declare const HelloOkSchema: Type.TObject<{
344
388
  kind: Type.TString;
345
389
  label: Type.TString;
346
390
  }>>>;
391
+ controlUiLinkReaders: Type.TOptional<Type.TArray<Type.TObject<{
392
+ pluginId: Type.TString;
393
+ id: Type.TString;
394
+ label: Type.TString;
395
+ icon: Type.TOptional<Type.TString>;
396
+ linkReader: Type.TObject<{
397
+ hosts: Type.TArray<Type.TString>;
398
+ pathPattern: Type.TString;
399
+ detailMethod: Type.TString;
400
+ previewMethod: Type.TOptional<Type.TString>;
401
+ imageMethod: Type.TOptional<Type.TString>;
402
+ }>;
403
+ }>>>;
347
404
  pluginSurfaceUrls: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
348
405
  auth: Type.TObject<{
349
406
  method: Type.TOptional<Type.TUnion<[Type.TLiteral<"none">, Type.TLiteral<"token">, Type.TLiteral<"password">, Type.TLiteral<"tailscale">, Type.TLiteral<"device-token">, Type.TLiteral<"bootstrap-token">, Type.TLiteral<"trusted-proxy">]>>;
@@ -387,6 +444,7 @@ declare const RequestFrameSchema: Type.TObject<{
387
444
  method: Type.TString;
388
445
  params: Type.TOptional<Type.TUnknown>;
389
446
  traceparent: Type.TOptional<Type.TString>;
447
+ expectedProfileId: Type.TOptional<Type.TString>;
390
448
  }>;
391
449
  /** Server response frame envelope paired with a prior request id. */
392
450
  declare const ResponseFrameSchema: Type.TObject<{
@@ -412,6 +470,7 @@ declare const EventFrameSchema: Type.TObject<{
412
470
  presence: Type.TInteger;
413
471
  health: Type.TInteger;
414
472
  }>>;
473
+ recipientProfileId: Type.TOptional<Type.TString>;
415
474
  }>;
416
475
  declare const GatewayFrameSchema: Type.TUnion<[Type.TObject<{
417
476
  type: Type.TLiteral<"req">;
@@ -419,6 +478,7 @@ declare const GatewayFrameSchema: Type.TUnion<[Type.TObject<{
419
478
  method: Type.TString;
420
479
  params: Type.TOptional<Type.TUnknown>;
421
480
  traceparent: Type.TOptional<Type.TString>;
481
+ expectedProfileId: Type.TOptional<Type.TString>;
422
482
  }>, Type.TObject<{
423
483
  type: Type.TLiteral<"res">;
424
484
  id: Type.TString;
@@ -440,6 +500,7 @@ declare const GatewayFrameSchema: Type.TUnion<[Type.TObject<{
440
500
  presence: Type.TInteger;
441
501
  health: Type.TInteger;
442
502
  }>>;
503
+ recipientProfileId: Type.TOptional<Type.TString>;
443
504
  }>]>;
444
505
  type ConnectParams = Static<typeof ConnectParamsSchema>;
445
506
  type HelloOk = Static<typeof HelloOkSchema>;
@@ -451,4 +512,4 @@ type GatewayFrame = Static<typeof GatewayFrameSchema>;
451
512
  type TickEvent = Static<typeof TickEventSchema>;
452
513
  type ShutdownEvent = Static<typeof ShutdownEventSchema>;
453
514
  //#endregion
454
- export { TickEvent as _, EventFrame as a, GatewayFrameSchema as c, RequestFrame as d, RequestFrameSchema as f, ShutdownEventSchema as g, ShutdownEvent as h, ErrorShapeSchema as i, HelloOk as l, ResponseFrameSchema as m, ConnectParamsSchema as n, EventFrameSchema as o, ResponseFrame as p, ErrorShape as r, GatewayFrame as s, ConnectParams as t, HelloOkSchema as u, TickEventSchema as v };
515
+ export { TickEvent as _, EventFrame as a, GatewayFrameSchema as c, RequestFrame as d, RequestFrameSchema as f, ShutdownEventSchema as g, ShutdownEvent as h, ErrorShapeSchema as i, HelloOk as l, ResponseFrameSchema as m, ConnectParamsSchema as n, EventFrameSchema as o, ResponseFrame as p, ErrorShape as r, GatewayFrame as s, ConnectParams as t, HelloOkSchema as u, TickEventSchema as v, GATEWAY_SERVER_CAPS as y };