@xtrape/capsule-contracts-node 0.6.0 → 0.7.0

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 (6) hide show
  1. package/README.md +414 -285
  2. package/dist/index.cjs +17 -0
  3. package/dist/index.d.cts +38 -1
  4. package/dist/index.d.ts +38 -1
  5. package/dist/index.js +15 -0
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -1,181 +1,279 @@
1
1
  # Xtrape Contracts for Node.js
2
2
 
3
- > TypeScript contracts and Zod schemas for Xtrape Agent, Worker, and Panel wire
4
- > protocols.
3
+ > TypeScript contracts, Zod schemas, and inferred TypeScript types for Xtrape
4
+ > service, agent, worker, panel, and server wire protocols.
5
5
 
6
- The npm name `@xtrape/capsule-contracts-node` is a legacy compatibility
7
- identifier. `Capsule` is not a current Xtrape concept. New code should use the
8
- canonical `Worker*` exports; the existing `Capsule*` exports and `services` wire
9
- field remain available until a versioned protocol migration removes them.
6
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
7
+ [![Status: 0.7 milestone](https://img.shields.io/badge/status-0.7.0-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
8
+ [![Docs](https://img.shields.io/badge/docs-xtrape--docs-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
9
+
10
+ ## 1. Package Status
11
+
12
+ The current npm package name is still:
13
+
14
+ ```bash
15
+ @xtrape/capsule-contracts-node
16
+ ```
17
+
18
+ This is a **legacy physical compatibility identifier**. `Capsule` is not a
19
+ current Xtrape concept. New code should prefer the current Xtrape / Worker /
20
+ Service naming where exports are available. Existing `Capsule*` exports and the
21
+ legacy `services` wire field remain available until a versioned protocol
22
+ migration removes them.
23
+
24
+ Current milestone release:
25
+
26
+ ```text
27
+ package version: 0.7.0
28
+ CE contract version: CE_CONTRACT_VERSION = 1
29
+ ```
30
+
31
+ Install:
32
+
33
+ ```bash
34
+ pnpm add @xtrape/capsule-contracts-node@^0.7.0
35
+ ```
36
+
37
+ For this repository itself:
38
+
39
+ ```bash
40
+ pnpm install
41
+ pnpm typecheck
42
+ pnpm test
43
+ pnpm build
44
+ ```
10
45
 
11
- ## Contract Authority Boundary
46
+ ## 2. Contract Authority Boundary
12
47
 
13
48
  | Name | Role |
14
49
  |---|---|
15
- | `xtrape-contracts` | The **future language-neutral schema authority** for Xtrape contracts (not yet a separate repository). |
16
- | `xtrape-contracts-nodejs` (this repo) | The **TypeScript / Zod runtime validation and type implementation**. |
50
+ | `xtrape-contracts` | Future language-neutral schema authority for Xtrape contracts. It is not yet a separate repository. |
51
+ | `xtrape-contracts-nodejs` | This repository. TypeScript / Zod runtime validation and type implementation. |
52
+ | `xtrape-docs` | Current canonical architecture and model baseline until a standalone language-neutral contracts repository exists. |
53
+
54
+ Until a standalone `xtrape-contracts` exists, this package hosts executable
55
+ TypeScript schemas. It should not become a separate conceptual authority. When
56
+ the executable schemas and the canonical architecture docs disagree, correct the
57
+ package to match the canonical model in `xtrape-docs`.
58
+
59
+ This package is not:
60
+
61
+ - a runtime server implementation;
62
+ - an HTTP client SDK;
63
+ - a database model authority;
64
+ - an ID generator;
65
+ - a business workflow or AI planner protocol.
17
66
 
18
- Until a standalone `xtrape-contracts` exists, this package hosts the executable
19
- TypeScript schemas, but it is **not** a separate conceptual authority: the
20
- canonical model lives in [`xtrape-docs`](https://forgejo.xtrape.com/xtrape/xtrape-docs)
21
- (`runtime-platform/02..04`, `architecture/11`). When the two disagree, the
22
- canonical architecture docs win and this package is corrected to match.
67
+ ## 3. CE Phase 0 Frozen Contracts (0.6/0.7 milestones)
23
68
 
24
- ## Xtrape CE 0.1 Phase 0 Contracts
69
+ The CE 0.1 Phase 0 runtime loop is:
25
70
 
26
- The CE 0.1 runtime loop (`Telegram → server-ce → demo xtrape-service → reply`)
27
- depends on a **frozen** set of schemas, exported from this package and validated
28
- by `tests/ce-contracts.spec.ts` (including a field/enum surface guard):
71
+ ```text
72
+ Telegram / caller -> xtrape-server-ce -> demo xtrape-service -> reply
73
+ ```
74
+
75
+ The frozen Phase 0 contract surface is exported from this package and guarded by
76
+ `tests/ce-contracts.spec.ts`.
29
77
 
30
- | Export | Used by |
78
+ | Export | Purpose |
31
79
  |---|---|
32
- | `CE_CONTRACT_VERSION` (`1`) | version negotiation across agent ↔ server-ce |
33
- | `ServiceManifestSchema` / `ServiceManifest` | service registration descriptor |
34
- | `ServiceInstanceSchema` / `ServiceInstance` | registered instance with resolvable address |
35
- | `AgentHeartbeatSchema` / `AgentHeartbeat` | heartbeat / health reporting |
36
- | `ConversationMessageSchema` / `ConversationMessage` | message routing + reply envelope |
37
- | `ErrorModelSchema` / `ErrorModel` (+ `CeErrorCode`) | structured error responses |
80
+ | `CE_CONTRACT_VERSION` (`1`) | Version negotiation across agent / service / server-ce. |
81
+ | `ServiceManifestSchema` / `ServiceManifest` | Service registration descriptor. |
82
+ | `ServiceInstanceSchema` / `ServiceInstance` | Registered runtime instance with resolvable address. |
83
+ | `AgentHeartbeatSchema` / `AgentHeartbeat` | Heartbeat and health reporting. |
84
+ | `ConversationMessageSchema` / `ConversationMessage` | Explicit-target message route and reply envelope. |
85
+ | `ActionAsyncAckSchema` / `ActionAsyncAck` | 202 RUNNING ack for a long-running action execute (server-ce#41 Stage B). |
86
+ | `ActionCommandResultSchema` / `ActionCommandResult` | Async action outcome reported back to server-ce. |
87
+ | `ErrorModelSchema` / `ErrorModel` | Structured CE runtime error envelope. |
88
+ | `CeErrorCode` | Phase 0 CE runtime error code constants. |
89
+
90
+ These schemas are frozen for CE 0.1. Removing fields, renaming fields, changing
91
+ requiredness, or changing enum values is a contract change. If such a change is
92
+ intentional, bump `CE_CONTRACT_VERSION` and update the surface guard together.
93
+
94
+ ### Minimal service manifest
38
95
 
39
96
  ```ts
40
- import { ServiceManifestSchema, CE_CONTRACT_VERSION } from "@xtrape/capsule-contracts-node";
97
+ import {
98
+ CE_CONTRACT_VERSION,
99
+ ServiceManifestSchema,
100
+ } from "@xtrape/capsule-contracts-node";
41
101
 
42
102
  const manifest = ServiceManifestSchema.parse({
43
103
  contractVersion: CE_CONTRACT_VERSION,
44
- service: { id: "demo-echo-service", name: "Demo Echo Service", version: "0.6.0" },
45
- runtime: { language: "node", agent: "xtrape-agent-nodejs" },
104
+ service: {
105
+ id: "demo-echo-service",
106
+ name: "Demo Echo Service",
107
+ version: "0.7.0",
108
+ },
109
+ runtime: {
110
+ language: "node",
111
+ agent: "xtrape-agent-nodejs",
112
+ },
46
113
  capabilities: ["status.query"],
47
- message: { supportedTypes: ["QUERY"] },
114
+ message: {
115
+ supportedTypes: ["QUERY"],
116
+ },
48
117
  });
49
118
  ```
50
119
 
51
- These schemas are frozen for CE 0.1: changing a field or enum is a contract
52
- change that must bump `CE_CONTRACT_VERSION` and update the surface guard. See the
53
- matching examples in `xtrape-docs/docs/runtime-platform/01-phase-0-runtime-mvp.md`.
54
-
55
- [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
56
- [![Status: Release Train 0.6.0](https://img.shields.io/badge/status-0.6.0-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
57
- [![Docs](https://img.shields.io/badge/docs-xtrape--docs-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
120
+ ### Minimal instance registration
58
121
 
59
- `@xtrape/capsule-contracts-node` is the current published TypeScript contract
60
- package for Panel CE, Agent SDKs, and Worker integrations. It exports Zod
61
- schemas, inferred TypeScript types, enum values, ID helpers, pagination helpers,
62
- and protocol error helpers for the Agent/Admin/System wire contracts.
122
+ ```ts
123
+ import {
124
+ CE_CONTRACT_VERSION,
125
+ ServiceInstanceSchema,
126
+ } from "@xtrape/capsule-contracts-node";
63
127
 
64
- > **Package status:** This package follows the unified Xtrape `0.6.0` release
65
- > train. The npm package name remains a compatibility identifier, but release
66
- > versioning now follows the shared Xtrape train version.
128
+ const instance = ServiceInstanceSchema.parse({
129
+ contractVersion: CE_CONTRACT_VERSION,
130
+ serviceId: "demo-echo-service",
131
+ instanceId: "demo-echo-7f3a",
132
+ address: "http://10.0.0.12:8080",
133
+ version: "0.7.0",
134
+ health: "HEALTHY",
135
+ });
136
+ ```
67
137
 
68
- ## Install
138
+ ### Minimal explicit-target message
69
139
 
70
- This repository tracks the `0.6.0` snapshot train. Until the `0.6.0` npm cut is
71
- published, install the latest published compatibility package:
140
+ ```ts
141
+ import {
142
+ CE_CONTRACT_VERSION,
143
+ ConversationMessageSchema,
144
+ } from "@xtrape/capsule-contracts-node";
72
145
 
73
- ```bash
74
- pnpm add @xtrape/capsule-contracts-node@^0.5.1
146
+ const message = ConversationMessageSchema.parse({
147
+ contractVersion: CE_CONTRACT_VERSION,
148
+ messageId: "msg_001",
149
+ conversationId: "conv_tg_123",
150
+ targetType: "SERVICE",
151
+ targetId: "demo-echo-service",
152
+ senderType: "USER",
153
+ senderId: "telegram:123456",
154
+ messageType: "QUERY",
155
+ content: "status?",
156
+ });
75
157
  ```
76
158
 
77
- For this repository itself:
159
+ ## 4. Current Export Groups
78
160
 
79
- ```bash
80
- pnpm install
81
- pnpm build
161
+ The package currently exports both the current CE Phase 0 contracts and legacy
162
+ compatibility surfaces.
163
+
164
+ ### Current CE runtime contracts
165
+
166
+ These are the primary contracts for `xtrape-server-ce`,
167
+ `xtrape-agent-nodejs`, `xtrape-demo`, and `xtrape-telegram` in the 0.7 milestone:
168
+
169
+ ```text
170
+ CE_CONTRACT_VERSION
171
+ ServiceManifestSchema
172
+ ServiceInstanceSchema
173
+ AgentHeartbeatSchema
174
+ ConversationMessageSchema
175
+ ErrorModelSchema
176
+ CeErrorCode
82
177
  ```
83
178
 
84
- ## What is Included
179
+ ### Legacy / compatibility contracts
85
180
 
86
- The package currently exports:
181
+ The package also exports older Panel / Agent / Worker / Command / Audit shapes.
182
+ These remain available for compatibility, but they are not the conceptual source
183
+ of the current Xtrape server governance model.
87
184
 
88
- - Zod itself as `z` for consumers that want one compatible Zod instance.
89
- - Status enum arrays and types: `AgentStatus`, `WorkerStatus` (plus the legacy
90
- `CapsuleServiceStatus` alias),
91
- `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`,
92
- `AuditResult`, `TokenStatus`, `AgentMode`.
93
- - Admin schemas: users, sessions, registration token requests/responses.
94
- - Agent schemas: registration, heartbeat, service report, command result.
95
- - Worker schemas: Worker Manifest, Worker Runtime Report, Worker Instance,
96
- health, config, Action, and Worker Instance detail. Legacy
97
- Capsule-named aliases remain available for wire compatibility.
98
- - Command schemas: create command, command detail, command result.
99
- - Audit and dashboard schemas.
100
- - System health/version schemas.
185
+ | Group | Examples |
186
+ |---|---|
187
+ | Zod re-export | `z` |
188
+ | Status enums | `AgentStatus`, `WorkerStatus`, `CapsuleServiceStatus`, `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`, `AuditResult`, `TokenStatus`, `AgentMode` |
189
+ | Admin | users, sessions, registration token requests/responses |
190
+ | Agent | registration, heartbeat, service report, command result |
191
+ | Worker | Worker manifest, runtime report, instance, health, config, action, detail |
192
+ | Service metadata | `ServiceCapabilitySchema`, `EventMetadataSchema`, `ServiceKindSchema` |
193
+ | Command / action | action definition, action prepare result, command detail, command result |
194
+ | Audit / dashboard | audit event, dashboard summary |
195
+ | System | system health, system version |
196
+ | Experimental bus | `BusEventEnvelopeSchema`, `PublishBusEventRequestSchema`, `PublishBusEventResponseSchema`, `BusRouteRuleSchema`, `CreateBusRouteRuleRequestSchema` |
197
+ | Helpers | `parseSort`, `paginate`, `HttpError`, `ListQueryBase` |
101
198
 
102
199
  The additive v0.4 Worker endpoint aliases and their legacy mappings are recorded
103
200
  in `spec/worker-compatibility-v0.4.json`. The older CE v0.1 OpenAPI file remains
104
- the historical baseline rather than being silently rewritten into a different
201
+ a historical baseline rather than being silently rewritten into a different
105
202
  protocol version.
106
203
 
107
- > **Known contract drift:** the historical structured sources still disagree on
108
- > some Command and effective-status enum values. The `WorkerStatus` export is an
109
- > alias of the currently shipped binding; it does not claim that the unresolved
110
- > enum migration documented in `xtrape-docs` has been completed.
111
- - Helpers: `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
204
+ ## 5. Compatibility Notes
112
205
 
113
- ## Validate Agent Registration
206
+ ### Legacy package and wire names
114
207
 
115
- ```ts
116
- import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
117
-
118
- const request = RegisterAgentRequestSchema.parse(input);
208
+ The following names may still appear in code, changelog, or wire compatibility
209
+ surfaces:
119
210
 
120
- // request.registrationToken starts with opstage_reg_
121
- // request.agent.mode is embedded or ophub
211
+ ```text
212
+ Capsule*
213
+ capsule
214
+ Opstage
215
+ ophub
216
+ services
217
+ svc_
218
+ opstage_reg_
219
+ opstage_agent_
122
220
  ```
123
221
 
124
- Lowercase aliases are also exported for backend compatibility:
222
+ Treat them as compatibility identifiers unless a current architecture document
223
+ explicitly reintroduces them as active concepts.
125
224
 
126
- ```ts
127
- import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
225
+ ### Worker vs Service naming
128
226
 
129
- const request = registerAgentRequestSchema.parse(input);
227
+ Current architecture uses `xtrape-service` as the deployable capability provider
228
+ registered to `xtrape-server`. `Worker` may appear as a user-facing or
229
+ compatibility-facing actor/runtime concept. `CapsuleService` remains a legacy
230
+ wire alias.
231
+
232
+ ### Agent mode compatibility
233
+
234
+ The `AgentMode` values include:
235
+
236
+ ```text
237
+ embedded
238
+ ophub
130
239
  ```
131
240
 
132
- ## v0.3 External-Agent Compatibility and Metadata
241
+ `ophub` is a historical compatibility value for the external-agent/runtime mode.
242
+ It is not a current top-level Xtrape product concept.
243
+
244
+ ### Known contract drift
133
245
 
134
- v0.3 adds the legacy `ophub` Agent-mode wire value for the historical Go
135
- external-Agent runtime. It represents one or more local Workers. It is not the
136
- canonical Gateway role: Gateway routes Agent/control-plane traffic while
137
- preserving Agent protocol semantics.
246
+ Historical structured sources still disagree on some command and
247
+ effective-status enum values. `WorkerStatus` is an alias of the currently
248
+ shipped binding. It does not claim that every older enum migration has been
249
+ completed.
250
+
251
+ ## 6. Common Validation Examples
252
+
253
+ ### Agent registration
138
254
 
139
255
  ```ts
140
- import { RegisterAgentRequestSchema, ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
256
+ import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
141
257
 
142
- RegisterAgentRequestSchema.parse({
143
- registrationToken: "opstage_reg_...",
258
+ const request = RegisterAgentRequestSchema.parse({
259
+ registrationToken: "opstage_reg_example",
144
260
  agent: {
145
- code: "ophub-a",
146
- name: "External Agent A",
147
- mode: "ophub",
148
- runtime: "go",
261
+ code: "embedded-agent-a",
262
+ mode: "embedded",
263
+ runtime: "nodejs",
149
264
  },
150
265
  });
151
-
152
- ServiceReportRequestSchema.parse({
153
- services: [
154
- {
155
- code: "svc-one",
156
- name: "Service One",
157
- version: "0.3.0",
158
- runtime: "nodejs",
159
- manifest: {
160
- kind: "CapsuleService",
161
- code: "svc-one",
162
- name: "Service One",
163
- version: "0.3.0",
164
- runtime: "nodejs",
165
- agentMode: "ophub",
166
- capabilities: [{ name: "inventory.read", label: "Inventory read" }],
167
- events: [{ name: "inventory.changed", direction: "publish", designOnly: true }],
168
- },
169
- },
170
- ],
171
- });
172
266
  ```
173
267
 
174
- Capability metadata is implemented as declarative service metadata. Event
175
- metadata is intentionally a foundation for future legacy event routing work; `designOnly`
176
- events must not be treated as a working event bus.
268
+ Lowercase aliases remain available for backend compatibility:
177
269
 
178
- ## Validate Service Report
270
+ ```ts
271
+ import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
272
+
273
+ const request = registerAgentRequestSchema.parse(input);
274
+ ```
275
+
276
+ ### Service / Worker report
179
277
 
180
278
  ```ts
181
279
  import { ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -183,25 +281,25 @@ import { ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
183
281
  const report = ServiceReportRequestSchema.parse({
184
282
  services: [
185
283
  {
186
- code: "hello-capsule",
187
- name: "Hello Capsule",
188
- version: "0.1.0",
284
+ code: "demo-worker",
285
+ name: "Demo Worker",
286
+ version: "0.7.0",
189
287
  runtime: "nodejs",
190
288
  manifest: {
191
289
  kind: "CapsuleService",
192
- schemaVersion: "1.0",
193
- code: "hello-capsule",
194
- name: "Hello Capsule",
195
- version: "0.1.0",
290
+ code: "demo-worker",
291
+ name: "Demo Worker",
292
+ version: "0.7.0",
196
293
  runtime: "nodejs",
197
294
  agentMode: "embedded",
295
+ capabilities: [{ name: "status.query", label: "Status query" }],
198
296
  },
199
297
  },
200
298
  ],
201
299
  });
202
300
  ```
203
301
 
204
- ## Validate Health Report
302
+ ### Health report
205
303
 
206
304
  ```ts
207
305
  import { HealthReportInputSchema } from "@xtrape/capsule-contracts-node";
@@ -213,35 +311,24 @@ const health = HealthReportInputSchema.parse({
213
311
  });
214
312
  ```
215
313
 
216
- Allowed health statuses are:
217
-
218
- ```ts
219
- import { HealthStatus } from "@xtrape/capsule-contracts-node";
314
+ Protocol-level `HealthStatus` values are:
220
315
 
221
- console.log(HealthStatus); // ["UP", "DEGRADED", "DOWN", "UNKNOWN"]
316
+ ```text
317
+ UP
318
+ DEGRADED
319
+ DOWN
320
+ UNKNOWN
222
321
  ```
223
322
 
224
- `HealthStatus` is the protocol-level status reported by Agents and Capsule
225
- Services:
226
-
227
- - `UP`
228
- - `DEGRADED`
229
- - `DOWN`
230
- - `UNKNOWN`
231
-
232
- Xtrape Panel may derive an operator-facing `effectiveStatus` such as:
323
+ Panel or server implementations may derive separate operator-facing states such
324
+ as `HEALTHY`, `UNHEALTHY`, `STALE`, or `OFFLINE`.
233
325
 
234
- - `HEALTHY`
235
- - `UNHEALTHY`
236
- - `STALE`
237
- - `OFFLINE`
238
-
239
- ## Validate Config and Action Definitions
326
+ ### Config and action definitions
240
327
 
241
328
  ```ts
242
329
  import {
243
- ConfigItemInputSchema,
244
330
  ActionDefinitionInputSchema,
331
+ ConfigItemInputSchema,
245
332
  } from "@xtrape/capsule-contracts-node";
246
333
 
247
334
  const config = ConfigItemInputSchema.parse({
@@ -259,9 +346,7 @@ const action = ActionDefinitionInputSchema.parse({
259
346
  });
260
347
  ```
261
348
 
262
- ## Validate Action Prepare Result
263
-
264
- Use `ActionPrepareResultSchema` to validate the action-prepare payload directly:
349
+ ### Action prepare result
265
350
 
266
351
  ```ts
267
352
  import { ActionPrepareResultSchema } from "@xtrape/capsule-contracts-node";
@@ -278,28 +363,7 @@ const prepare = ActionPrepareResultSchema.parse({
278
363
  });
279
364
  ```
280
365
 
281
- When reported back to Xtrape Panel for an `ACTION_PREPARE` command, this shape is
282
- placed under `ReportCommandResultRequest.data`. Command result reporting still
283
- uses `ReportCommandResultRequestSchema`:
284
-
285
- ```ts
286
- import { ReportCommandResultRequestSchema } from "@xtrape/capsule-contracts-node";
287
-
288
- const prepareResult = ReportCommandResultRequestSchema.parse({
289
- success: true,
290
- data: {
291
- action: { name: "echo", label: "Echo", dangerLevel: "LOW" },
292
- inputSchema: {
293
- type: "object",
294
- properties: { message: { type: "string", default: "hello" } },
295
- },
296
- initialPayload: { message: "hello" },
297
- currentState: { service: "ready" },
298
- },
299
- });
300
- ```
301
-
302
- ## Validate Command Result
366
+ ### Command result
303
367
 
304
368
  ```ts
305
369
  import { ReportCommandResultRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -326,9 +390,47 @@ ReportCommandResultRequestSchema.parse({
326
390
  });
327
391
  ```
328
392
 
329
- ## Error Codes
393
+ ## 7. Experimental Legacy Event Routing
394
+
395
+ The v0.4 event routing surface is experimental and compatibility-oriented. It
396
+ models a small CE in-process event-to-command router. It is not a standalone bus
397
+ server, external broker abstraction, workflow DSL, service mesh, distributed
398
+ event system, or fan-out engine.
399
+
400
+ Key exports:
401
+
402
+ ```text
403
+ BusEventEnvelopeSchema
404
+ PublishBusEventRequestSchema
405
+ PublishBusEventResponseSchema
406
+ BusRouteRuleSchema
407
+ CreateBusRouteRuleRequestSchema
408
+ BusErrorCode
409
+ ```
410
+
411
+ Minimal event payload:
412
+
413
+ ```ts
414
+ import { BusEventEnvelopeSchema } from "@xtrape/capsule-contracts-node";
415
+
416
+ BusEventEnvelopeSchema.parse({
417
+ eventType: "demo.item.created",
418
+ sourceServiceCode: "demo-worker",
419
+ payload: { itemId: "item-1" },
420
+ });
421
+ ```
422
+
423
+ All schemas include or default:
424
+
425
+ ```text
426
+ experimental: "v0.4-experimental"
427
+ ```
428
+
429
+ Consumers should treat this wire surface as unstable until v1.0.
330
430
 
331
- The `ErrorCode` export contains protocol-level error code constants currently
431
+ ## 8. Error Codes
432
+
433
+ The legacy `ErrorCode` export contains protocol-level error constants currently
332
434
  used by CE and SDKs:
333
435
 
334
436
  ```ts
@@ -337,54 +439,61 @@ import { ErrorCode } from "@xtrape/capsule-contracts-node";
337
439
  throw new Error(ErrorCode.VALIDATION_FAILED);
338
440
  ```
339
441
 
340
- Currently exported codes include:
442
+ Current values include:
443
+
444
+ ```text
445
+ INTERNAL_ERROR
446
+ VALIDATION_FAILED
447
+ UNAUTHORIZED
448
+ FORBIDDEN
449
+ NOT_FOUND
450
+ CONFLICT
451
+ CAPSULE_SERVICE_CODE_TAKEN
452
+ CSRF_INVALID
453
+ ACTION_REQUIRES_CONFIRMATION
454
+ COMMAND_EXPIRED
455
+ TOKEN_REVOKED
456
+ TOKEN_EXPIRED
457
+ AGENT_REVOKED
458
+ AGENT_DISABLED
459
+ ```
341
460
 
342
- - `INTERNAL_ERROR`
343
- - `VALIDATION_FAILED`
344
- - `UNAUTHORIZED`
345
- - `FORBIDDEN`
346
- - `NOT_FOUND`
347
- - `CONFLICT`
348
- - `CAPSULE_SERVICE_CODE_TAKEN` (persisted compatibility identifier for a Worker ownership conflict)
349
- - `CSRF_INVALID`
350
- - `ACTION_REQUIRES_CONFIRMATION`
351
- - `COMMAND_EXPIRED`
352
- - `TOKEN_REVOKED`
353
- - `TOKEN_EXPIRED`
354
- - `AGENT_REVOKED`
355
- - `AGENT_DISABLED`
461
+ For CE Phase 0 runtime errors, prefer `CeErrorCode` with `ErrorModelSchema`.
356
462
 
357
- See the OpenAPI contract and docs site for endpoint-specific errors.
463
+ ## 9. ID Generation
358
464
 
359
- ## ID generation
465
+ This package validates IDs at the wire boundary but does **not** mint IDs.
360
466
 
361
- This package validates IDs at the wire boundary (via Zod) but does **not** mint
362
- them. Until v0.1.x there was a small `newId()` helper plus an `idPrefixes`
363
- table; both were removed in `0.2.0` to keep the contracts surface focused on
364
- the wire spec — see [`CHANGELOG.md`](./CHANGELOG.md) and the
365
- "Breaking changes" section at the top of this README.
467
+ `newId()`, `idPrefixes`, and `IdPrefix` were removed in `0.2.0` because runtime
468
+ ID generation does not belong in the contracts package. Consumers that need
469
+ local ID generation should provide their own factory.
366
470
 
367
- Consumers that need local ID generation should provide their own factory.
368
- Example using `nanoid` directly:
471
+ Documented compatibility prefixes include:
369
472
 
370
- ```ts
371
- import { customAlphabet } from "nanoid";
372
-
373
- const idBody = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyz", 21);
374
- const commandId = `cmd_${idBody()}`;
473
+ ```text
474
+ wks_
475
+ usr_
476
+ agt_
477
+ tok_
478
+ svc_
479
+ hlr_
480
+ cfg_
481
+ act_
482
+ cmd_
483
+ crs_
484
+ aud_
375
485
  ```
376
486
 
377
- Documented ID prefixes in use across CE and the Agent SDK include `wks_`,
378
- `usr_`, `agt_`, `tok_`, `svc_`, `hlr_`, `cfg_`, `act_`, `cmd_`, `crs_`, and
379
- `aud_`. These are enforced by the Zod schemas via `z.string().startsWith(...)`.
487
+ Individual schemas enforce prefixes where needed with Zod validators such as
488
+ `z.string().startsWith(...)`.
380
489
 
381
- ## List Helpers
490
+ ## 10. List Helpers
382
491
 
383
492
  ```ts
384
493
  import {
385
494
  ListQueryBase,
386
- parseSort,
387
495
  paginate,
496
+ parseSort,
388
497
  } from "@xtrape/capsule-contracts-node";
389
498
 
390
499
  const query = ListQueryBase.parse({ page: "1", pageSize: "20" });
@@ -392,101 +501,121 @@ const sort = parseSort("-createdAt", ["createdAt", "name"]);
392
501
  const response = paginate(items, query.page, query.pageSize, total);
393
502
  ```
394
503
 
395
- ## Used By
504
+ These helpers are provisional convenience utilities for backend-style consumers.
505
+ They may move out of the contracts package in a future minor version.
396
506
 
397
- - [`xtrape-panel-ce`](https://forgejo.xtrape.com/xtrape/xtrape-panel-ce) —
398
- Xtrape Panel CE backend validation and protocol handling.
399
- - [`xtrape-agent-nodejs`](https://forgejo.xtrape.com/xtrape/xtrape-agent-nodejs)
400
- — Node embedded Agent SDK request/response types.
401
- - [`xtrape-demo`](https://forgejo.xtrape.com/xtrape/xtrape-demo)
402
- — End-to-end runnable Worker that imports these schemas through
403
- the Agent SDK.
404
- - Worker implementations that want local validation before reporting to
405
- Xtrape Panel.
507
+ ## 11. Schema Stability
406
508
 
407
- ## Compatibility
509
+ The package follows semver. Before `1.0.0`, pin matching
510
+ minor versions across CE, Agent SDK, and Contracts.
408
511
 
409
- | Package | Compatible with |
410
- | -------------------------------------- | ---------------------------------------- |
411
- | `@xtrape/capsule-contracts-node@0.2.x` | Xtrape Panel CE `0.2.x` and Agent SDK `0.2.x` |
412
- | `@xtrape/capsule-contracts-node@0.1.x` | Xtrape Panel CE `0.1.x` and Agent SDK `0.1.x` |
512
+ | Group | Stability | Notes |
513
+ |---|---:|---|
514
+ | CE Phase 0 contracts | Frozen for CE 0.1 | Changes require `CE_CONTRACT_VERSION` and surface guard updates. |
515
+ | Status enums | Stable | Existing values should not be removed before v1.0. New values may be added in minor versions. |
516
+ | Agent / backend wire schemas | Evolving | Additive optional fields may land in minor versions. |
517
+ | Worker / service compatibility shapes | Evolving | Legacy aliases retain existing physical wire shapes. |
518
+ | Persisted/read-only shapes | Evolving | Useful for consumers, but track CE storage and should be read as provisional. |
519
+ | Action prepare / command result | Provisional | May tighten before v1.0. |
520
+ | Experimental bus contracts | Experimental | Not a stable data-plane or broker contract. |
521
+ | Helpers | Provisional | Not strictly part of the wire spec. |
413
522
 
414
- Pin matching minor versions across CE, Agent SDK, and Contracts. The wire
415
- protocol may still evolve before `v1.0`.
523
+ Breaking or incompatible changes are recorded in `CHANGELOG.md`.
416
524
 
417
- ## Breaking changes in `0.2.0`
525
+ ## 12. Current Planning
418
526
 
419
- - **`newId()` removed.** The helper minted random IDs with a prefix; it was
420
- never used by CE (entity IDs are minted in the backend). External consumers
421
- that imported `newId` must wire their own factory — see the
422
- [ID generation](#id-generation) section above.
423
- - **`idPrefixes` constant and `IdPrefix` type removed.** Same rationale.
424
- - **`nanoid` runtime dependency removed** as a consequence. Consumers that
425
- relied on a transitive `nanoid` install must now add it directly.
527
+ Active 0.7.0 planning should focus on service governance contracts, not AI task
528
+ routing or Studio-specific workflow contracts.
426
529
 
427
- The wire schemas themselves are **unchanged** between `0.1.x` and `0.2.x`;
428
- existing `0.1.x` agents continue to validate against a `0.2.x` backend.
530
+ Core 0.7.0 directions are:
429
531
 
430
- ## Schema Stability
532
+ ```text
533
+ service governance
534
+ configuration
535
+ credential references
536
+ policy / approval requirement
537
+ explicit invocation boundary
538
+ audit / trace
539
+ operator-facing read models
540
+ ```
431
541
 
432
- The package follows semver. During the current pre-`1.0` release-train phase,
433
- the guarantees per schema group are:
542
+ Out of scope for the core 0.7.0 contract surface:
434
543
 
435
- | Group | Stability | Notes |
436
- | ---------------------------------------------------------------------------------------------------------------- | :---------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
437
- | Status enums (`AgentStatus`, `CapsuleServiceStatus`, `HealthStatus`, `CommandStatus`, `DangerLevel`, `TokenStatus`) | Stable | New values may be added in minor versions; existing values will not be removed before `v1.0`. |
438
- | Agent ↔ Backend wire schemas (`RegisterAgentRequest`, `AgentHeartbeat*`, `ServiceReport*`, `ReportCommandResult*`) | Evolving | Field shape is stable; additive optional fields may land in minor versions. Required fields will not be added before `v1.0` without a deprecation cycle. |
439
- | Worker shapes (`WorkerManifest`, `WorkerRuntimeReport`, `WorkerInstance`, `HealthReportInput`, `ConfigItemInput`, `ActionDefinitionInput`) | Evolving | Legacy aliases retain the existing physical wire shapes. |
440
- | Persisted shapes (`Agent`, `CapsuleService`, `ConfigItem`, `ActionDefinition`, `Command*`, `AuditEvent`, `User`) | Evolving | Track CE storage; safe to consume read-only. |
441
- | `ActionPrepareResultSchema` | Provisional | Added in `0.1.0-public-review.0`. Field shape may still tighten before `v1.0`. |
442
- | `Command.type` enum | Evolving | Currently `ACTION_PREPARE` / `ACTION_EXECUTE`. New types may be added. |
443
- | Error codes (`ErrorCode`) | Evolving | New codes may be added. Existing codes will not change meaning before `v1.0`. |
444
- | Helpers (`parseSort`, `paginate`, `HttpError`, `ListQueryBase`) | Provisional | Helpful for backend-style consumers but not strictly part of the wire spec; may move to a separate utility package in a future minor. (`newId` / `idPrefixes` / `IdPrefix` were removed in `0.2.0` — see "Breaking changes in `0.2.0`" above.) |
544
+ ```text
545
+ intelligent service selection
546
+ business intent routing
547
+ AI planner protocol
548
+ complete workflow engine
549
+ service-to-service data plane
550
+ marketplace / paid transaction contracts
551
+ production deployment orchestration
552
+ ```
445
553
 
446
- **Until `v1.0`**, pin to a single minor across CE / Agent SDK / Contracts.
447
- Breaking changes will be called out in `CHANGELOG.md`.
554
+ See the active Forgejo issue:
448
555
 
449
- ## Documentation
556
+ ```text
557
+ #30 0.7.0: define service governance, configuration, policy, credential, invocation, and audit contracts
558
+ ```
450
559
 
451
- - Public docs repo: https://forgejo.xtrape.com/xtrape/xtrape-site
452
- - Contracts overview: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/overview.md
453
- - Manifest contract: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/manifest.md
454
- - Health contract: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/health.md
455
- - Actions contract: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/actions.md
456
- - Errors: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/errors.md
457
- - Xtrape Panel CE docs: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/opstage-ce/overview.md
560
+ ## 13. Used By
458
561
 
459
- ## Contributing
562
+ - `xtrape-server-ce` — CE headless server runtime and control-plane implementation.
563
+ - `xtrape-agent-nodejs` — Node.js Agent SDK request/response validation.
564
+ - `xtrape-demo` — end-to-end runnable demo service.
565
+ - `xtrape-telegram` — Telegram adapter over server message APIs.
566
+ - `xtrape-panel-ce` — operator UI consumer of server/contract surfaces.
567
+ - Worker and service implementations that want local validation before reporting
568
+ to Xtrape runtime components.
460
569
 
461
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for schema change workflow and PR
462
- checks. See [SECURITY.md](./SECURITY.md) for vulnerability reporting and
463
- contract validation safety guidance.
570
+ ## 14. Development
464
571
 
465
- ## License
572
+ ```bash
573
+ pnpm install
574
+ pnpm typecheck
575
+ pnpm test
576
+ pnpm build
577
+ ```
466
578
 
467
- Apache-2.0. "Xtrape" and "Opstage" are trademarks of their
468
- respective owners; the open-source license does not grant trademark rights.
579
+ Package outputs:
469
580
 
470
- ## v0.4 legacy event routing Experimental
581
+ ```text
582
+ dist/index.js
583
+ dist/index.cjs
584
+ dist/index.d.ts
585
+ ```
471
586
 
472
- `v0.4` adds an experimental legacy event routing contract surface for CE's built-in SQLite-backed in-process event-to-command router. It is intentionally small, single-node, and disabled by default; it is **not** a standalone Bus Server, external broker (NATS / RabbitMQ / Redis Streams / Kafka), workflow DSL, or service mesh. No fan-out (`maxCommandsPerEvent`) in v0.4 — one matched route produces at most one `ACTION_EXECUTE` command.
587
+ Published package files include:
473
588
 
474
- Key exports:
589
+ ```text
590
+ dist
591
+ spec
592
+ README.md
593
+ LICENSE
594
+ NOTICE
595
+ ```
475
596
 
476
- - `BusEventEnvelopeSchema`
477
- - `PublishBusEventRequestSchema`
478
- - `PublishBusEventResponseSchema`
479
- - `BusRouteRuleSchema`
480
- - `CreateBusRouteRuleRequestSchema`
597
+ ## 15. Documentation
481
598
 
482
- Minimal event payload:
599
+ Current canonical docs:
483
600
 
484
- ```ts
485
- BusEventEnvelopeSchema.parse({
486
- eventType: "demo.item.created",
487
- sourceServiceCode: "demo-worker",
488
- payload: { itemId: "item-1" },
489
- });
490
- ```
601
+ - `xtrape-docs/docs/architecture/11-xtrape-ce-system-baseline.md`
602
+ - `xtrape-docs/docs/runtime-platform/01-phase-0-runtime-mvp.md`
603
+ - `xtrape-docs/docs/runtime-platform/02-service-manifest-schema.md`
604
+ - `xtrape-docs/docs/runtime-platform/03-message-protocol-schema.md`
605
+ - `xtrape-docs/docs/runtime-platform/04-agent-registration-heartbeat.md`
606
+ - `xtrape-docs/docs/runtime-platform/05-server-ce-module-design.md`
607
+
608
+ Historical public docs may still mention Opstage or Capsule names. Treat those as
609
+ compatibility references unless later architecture docs explicitly reintroduce
610
+ the terms.
611
+
612
+ ## 16. Contributing
613
+
614
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for schema change workflow and PR
615
+ checks. See [SECURITY.md](./SECURITY.md) for vulnerability reporting and
616
+ contract validation safety guidance.
617
+
618
+ ## 17. License
491
619
 
492
- All schemas include or default `experimental: "v0.4-experimental"`; consumers should treat the wire surface as unstable until v1.0.
620
+ Apache-2.0. "Xtrape" and "Opstage" are trademarks of their respective owners;
621
+ the open-source license does not grant trademark rights.
package/dist/index.cjs CHANGED
@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/index.ts
21
21
  var index_exports = {};
22
22
  __export(index_exports, {
23
+ ActionAsyncAckSchema: () => ActionAsyncAckSchema,
24
+ ActionCommandResultSchema: () => ActionCommandResultSchema,
23
25
  ActionDefinitionInputSchema: () => ActionDefinitionInputSchema,
24
26
  ActionDefinitionSchema: () => ActionDefinitionSchema,
25
27
  ActionPrepareResultSchema: () => ActionPrepareResultSchema,
@@ -235,6 +237,19 @@ var AgentHeartbeatSchema = import_zod.z.object({
235
237
  health: ServiceInstanceHealthSchema,
236
238
  metricsSummary: Json.optional()
237
239
  });
240
+ var ActionAsyncAckSchema = import_zod.z.object({
241
+ contractVersion: import_zod.z.literal(CE_CONTRACT_VERSION),
242
+ status: import_zod.z.literal("RUNNING"),
243
+ commandId: import_zod.z.string().min(1)
244
+ });
245
+ var ActionCommandResultSchema = import_zod.z.object({
246
+ contractVersion: import_zod.z.literal(CE_CONTRACT_VERSION),
247
+ commandId: import_zod.z.string().min(1),
248
+ status: import_zod.z.enum(["COMPLETED", "FAILED"]),
249
+ result: Json.optional(),
250
+ errorCode: import_zod.z.string().optional(),
251
+ errorMessage: import_zod.z.string().optional()
252
+ });
238
253
  var CeErrorCode = {
239
254
  CONTRACT_VERSION_MISMATCH: "CONTRACT_VERSION_MISMATCH",
240
255
  UNKNOWN_INSTANCE: "UNKNOWN_INSTANCE",
@@ -485,6 +500,8 @@ var ErrorCode = {
485
500
  };
486
501
  // Annotate the CommonJS export names for ESM import in node:
487
502
  0 && (module.exports = {
503
+ ActionAsyncAckSchema,
504
+ ActionCommandResultSchema,
488
505
  ActionDefinitionInputSchema,
489
506
  ActionDefinitionSchema,
490
507
  ActionPrepareResultSchema,
package/dist/index.d.cts CHANGED
@@ -305,6 +305,43 @@ declare const AgentHeartbeatSchema: z.ZodObject<{
305
305
  metricsSummary?: Record<string, any> | undefined;
306
306
  }>;
307
307
  type AgentHeartbeat = z.infer<typeof AgentHeartbeatSchema>;
308
+ declare const ActionAsyncAckSchema: z.ZodObject<{
309
+ contractVersion: z.ZodLiteral<1>;
310
+ status: z.ZodLiteral<"RUNNING">;
311
+ commandId: z.ZodString;
312
+ }, "strip", z.ZodTypeAny, {
313
+ status: "RUNNING";
314
+ commandId: string;
315
+ contractVersion: 1;
316
+ }, {
317
+ status: "RUNNING";
318
+ commandId: string;
319
+ contractVersion: 1;
320
+ }>;
321
+ type ActionAsyncAck = z.infer<typeof ActionAsyncAckSchema>;
322
+ declare const ActionCommandResultSchema: z.ZodObject<{
323
+ contractVersion: z.ZodLiteral<1>;
324
+ commandId: z.ZodString;
325
+ status: z.ZodEnum<["COMPLETED", "FAILED"]>;
326
+ result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
327
+ errorCode: z.ZodOptional<z.ZodString>;
328
+ errorMessage: z.ZodOptional<z.ZodString>;
329
+ }, "strip", z.ZodTypeAny, {
330
+ status: "FAILED" | "COMPLETED";
331
+ commandId: string;
332
+ contractVersion: 1;
333
+ errorCode?: string | undefined;
334
+ errorMessage?: string | undefined;
335
+ result?: Record<string, any> | undefined;
336
+ }, {
337
+ status: "FAILED" | "COMPLETED";
338
+ commandId: string;
339
+ contractVersion: 1;
340
+ errorCode?: string | undefined;
341
+ errorMessage?: string | undefined;
342
+ result?: Record<string, any> | undefined;
343
+ }>;
344
+ type ActionCommandResult = z.infer<typeof ActionCommandResultSchema>;
308
345
  declare const CeErrorCode: {
309
346
  readonly CONTRACT_VERSION_MISMATCH: "CONTRACT_VERSION_MISMATCH";
310
347
  readonly UNKNOWN_INSTANCE: "UNKNOWN_INSTANCE";
@@ -7459,4 +7496,4 @@ declare const ErrorCode: {
7459
7496
  };
7460
7497
  type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
7461
7498
 
7462
- export { type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeat, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentHeartbeatSchema, AgentMode, AgentModeSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type BusCommandRequest, BusCommandRequestSchema, BusErrorCode, type BusEventEnvelope, BusEventEnvelopeSchema, type BusEventRecord, BusEventRecordSchema, type BusRouteRule, BusRouteRuleSchema, BusRouteStatus, BusRouteStatusSchema, type BusRoutedCommand, BusRoutedCommandSchema, type BusRoutingRule, BusRoutingRuleSchema, CE_CONTRACT_VERSION, type CapsuleBusExperimental, CapsuleBusExperimentalSchema, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, CeErrorCode, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type ConversationMessage, ConversationMessageSchema, ConversationTargetType, ConversationTargetTypeSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateBusRouteRuleRequest, CreateBusRouteRuleRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type ErrorModel, ErrorModelSchema, type EventMetadata, EventMetadataSchema, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, ListQueryBase, MessageSenderType, MessageSenderTypeSchema, MessageType, MessageTypeSchema, type Pagination, type PublishBusEventRequest, PublishBusEventRequestSchema, type PublishBusEventResponse, PublishBusEventResponseSchema, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ReportedWorker, ReportedWorkerSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceCapability, ServiceCapabilitySchema, type ServiceInstance, ServiceInstanceHealth, ServiceInstanceHealthSchema, ServiceInstanceSchema, ServiceKind, ServiceKindSchema, type ServiceManifest, ServiceManifestSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, type Worker, type WorkerDetail, WorkerDetailSchema, type WorkerInstance, type WorkerInstanceDetail, WorkerInstanceDetailSchema, WorkerInstanceSchema, type WorkerManifest, WorkerManifestSchema, type WorkerReportRequest, WorkerReportRequestSchema, type WorkerRuntimeReport, WorkerRuntimeReportSchema, WorkerSchema, WorkerStatus, WorkerStatusSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, busCommandRequestSchema, busEventEnvelopeSchema, busRouteRuleSchema, busRoutingRuleSchema, configItemInputSchema, createActionCommandRequestSchema, createBusRouteRuleRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, eventMetadataSchema, healthReportInputSchema, paginate, parseSort, publishBusEventRequestSchema, publishBusEventResponseSchema, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, reportedWorkerSchema, resetUserPasswordRequestSchema, serviceCapabilitySchema, serviceReportRequestSchema, updateUserRequestSchema, workerDetailSchema, workerInstanceDetailSchema, workerInstanceSchema, workerManifestSchema, workerReportRequestSchema, workerRuntimeReportSchema, workerSchema };
7499
+ export { type ActionAsyncAck, ActionAsyncAckSchema, type ActionCommandResult, ActionCommandResultSchema, type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeat, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentHeartbeatSchema, AgentMode, AgentModeSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type BusCommandRequest, BusCommandRequestSchema, BusErrorCode, type BusEventEnvelope, BusEventEnvelopeSchema, type BusEventRecord, BusEventRecordSchema, type BusRouteRule, BusRouteRuleSchema, BusRouteStatus, BusRouteStatusSchema, type BusRoutedCommand, BusRoutedCommandSchema, type BusRoutingRule, BusRoutingRuleSchema, CE_CONTRACT_VERSION, type CapsuleBusExperimental, CapsuleBusExperimentalSchema, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, CeErrorCode, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type ConversationMessage, ConversationMessageSchema, ConversationTargetType, ConversationTargetTypeSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateBusRouteRuleRequest, CreateBusRouteRuleRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type ErrorModel, ErrorModelSchema, type EventMetadata, EventMetadataSchema, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, ListQueryBase, MessageSenderType, MessageSenderTypeSchema, MessageType, MessageTypeSchema, type Pagination, type PublishBusEventRequest, PublishBusEventRequestSchema, type PublishBusEventResponse, PublishBusEventResponseSchema, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ReportedWorker, ReportedWorkerSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceCapability, ServiceCapabilitySchema, type ServiceInstance, ServiceInstanceHealth, ServiceInstanceHealthSchema, ServiceInstanceSchema, ServiceKind, ServiceKindSchema, type ServiceManifest, ServiceManifestSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, type Worker, type WorkerDetail, WorkerDetailSchema, type WorkerInstance, type WorkerInstanceDetail, WorkerInstanceDetailSchema, WorkerInstanceSchema, type WorkerManifest, WorkerManifestSchema, type WorkerReportRequest, WorkerReportRequestSchema, type WorkerRuntimeReport, WorkerRuntimeReportSchema, WorkerSchema, WorkerStatus, WorkerStatusSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, busCommandRequestSchema, busEventEnvelopeSchema, busRouteRuleSchema, busRoutingRuleSchema, configItemInputSchema, createActionCommandRequestSchema, createBusRouteRuleRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, eventMetadataSchema, healthReportInputSchema, paginate, parseSort, publishBusEventRequestSchema, publishBusEventResponseSchema, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, reportedWorkerSchema, resetUserPasswordRequestSchema, serviceCapabilitySchema, serviceReportRequestSchema, updateUserRequestSchema, workerDetailSchema, workerInstanceDetailSchema, workerInstanceSchema, workerManifestSchema, workerReportRequestSchema, workerRuntimeReportSchema, workerSchema };
package/dist/index.d.ts CHANGED
@@ -305,6 +305,43 @@ declare const AgentHeartbeatSchema: z.ZodObject<{
305
305
  metricsSummary?: Record<string, any> | undefined;
306
306
  }>;
307
307
  type AgentHeartbeat = z.infer<typeof AgentHeartbeatSchema>;
308
+ declare const ActionAsyncAckSchema: z.ZodObject<{
309
+ contractVersion: z.ZodLiteral<1>;
310
+ status: z.ZodLiteral<"RUNNING">;
311
+ commandId: z.ZodString;
312
+ }, "strip", z.ZodTypeAny, {
313
+ status: "RUNNING";
314
+ commandId: string;
315
+ contractVersion: 1;
316
+ }, {
317
+ status: "RUNNING";
318
+ commandId: string;
319
+ contractVersion: 1;
320
+ }>;
321
+ type ActionAsyncAck = z.infer<typeof ActionAsyncAckSchema>;
322
+ declare const ActionCommandResultSchema: z.ZodObject<{
323
+ contractVersion: z.ZodLiteral<1>;
324
+ commandId: z.ZodString;
325
+ status: z.ZodEnum<["COMPLETED", "FAILED"]>;
326
+ result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
327
+ errorCode: z.ZodOptional<z.ZodString>;
328
+ errorMessage: z.ZodOptional<z.ZodString>;
329
+ }, "strip", z.ZodTypeAny, {
330
+ status: "FAILED" | "COMPLETED";
331
+ commandId: string;
332
+ contractVersion: 1;
333
+ errorCode?: string | undefined;
334
+ errorMessage?: string | undefined;
335
+ result?: Record<string, any> | undefined;
336
+ }, {
337
+ status: "FAILED" | "COMPLETED";
338
+ commandId: string;
339
+ contractVersion: 1;
340
+ errorCode?: string | undefined;
341
+ errorMessage?: string | undefined;
342
+ result?: Record<string, any> | undefined;
343
+ }>;
344
+ type ActionCommandResult = z.infer<typeof ActionCommandResultSchema>;
308
345
  declare const CeErrorCode: {
309
346
  readonly CONTRACT_VERSION_MISMATCH: "CONTRACT_VERSION_MISMATCH";
310
347
  readonly UNKNOWN_INSTANCE: "UNKNOWN_INSTANCE";
@@ -7459,4 +7496,4 @@ declare const ErrorCode: {
7459
7496
  };
7460
7497
  type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
7461
7498
 
7462
- export { type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeat, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentHeartbeatSchema, AgentMode, AgentModeSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type BusCommandRequest, BusCommandRequestSchema, BusErrorCode, type BusEventEnvelope, BusEventEnvelopeSchema, type BusEventRecord, BusEventRecordSchema, type BusRouteRule, BusRouteRuleSchema, BusRouteStatus, BusRouteStatusSchema, type BusRoutedCommand, BusRoutedCommandSchema, type BusRoutingRule, BusRoutingRuleSchema, CE_CONTRACT_VERSION, type CapsuleBusExperimental, CapsuleBusExperimentalSchema, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, CeErrorCode, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type ConversationMessage, ConversationMessageSchema, ConversationTargetType, ConversationTargetTypeSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateBusRouteRuleRequest, CreateBusRouteRuleRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type ErrorModel, ErrorModelSchema, type EventMetadata, EventMetadataSchema, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, ListQueryBase, MessageSenderType, MessageSenderTypeSchema, MessageType, MessageTypeSchema, type Pagination, type PublishBusEventRequest, PublishBusEventRequestSchema, type PublishBusEventResponse, PublishBusEventResponseSchema, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ReportedWorker, ReportedWorkerSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceCapability, ServiceCapabilitySchema, type ServiceInstance, ServiceInstanceHealth, ServiceInstanceHealthSchema, ServiceInstanceSchema, ServiceKind, ServiceKindSchema, type ServiceManifest, ServiceManifestSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, type Worker, type WorkerDetail, WorkerDetailSchema, type WorkerInstance, type WorkerInstanceDetail, WorkerInstanceDetailSchema, WorkerInstanceSchema, type WorkerManifest, WorkerManifestSchema, type WorkerReportRequest, WorkerReportRequestSchema, type WorkerRuntimeReport, WorkerRuntimeReportSchema, WorkerSchema, WorkerStatus, WorkerStatusSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, busCommandRequestSchema, busEventEnvelopeSchema, busRouteRuleSchema, busRoutingRuleSchema, configItemInputSchema, createActionCommandRequestSchema, createBusRouteRuleRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, eventMetadataSchema, healthReportInputSchema, paginate, parseSort, publishBusEventRequestSchema, publishBusEventResponseSchema, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, reportedWorkerSchema, resetUserPasswordRequestSchema, serviceCapabilitySchema, serviceReportRequestSchema, updateUserRequestSchema, workerDetailSchema, workerInstanceDetailSchema, workerInstanceSchema, workerManifestSchema, workerReportRequestSchema, workerRuntimeReportSchema, workerSchema };
7499
+ export { type ActionAsyncAck, ActionAsyncAckSchema, type ActionCommandResult, ActionCommandResultSchema, type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeat, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentHeartbeatSchema, AgentMode, AgentModeSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type BusCommandRequest, BusCommandRequestSchema, BusErrorCode, type BusEventEnvelope, BusEventEnvelopeSchema, type BusEventRecord, BusEventRecordSchema, type BusRouteRule, BusRouteRuleSchema, BusRouteStatus, BusRouteStatusSchema, type BusRoutedCommand, BusRoutedCommandSchema, type BusRoutingRule, BusRoutingRuleSchema, CE_CONTRACT_VERSION, type CapsuleBusExperimental, CapsuleBusExperimentalSchema, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, CeErrorCode, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type ConversationMessage, ConversationMessageSchema, ConversationTargetType, ConversationTargetTypeSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateBusRouteRuleRequest, CreateBusRouteRuleRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type ErrorModel, ErrorModelSchema, type EventMetadata, EventMetadataSchema, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, ListQueryBase, MessageSenderType, MessageSenderTypeSchema, MessageType, MessageTypeSchema, type Pagination, type PublishBusEventRequest, PublishBusEventRequestSchema, type PublishBusEventResponse, PublishBusEventResponseSchema, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ReportedWorker, ReportedWorkerSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceCapability, ServiceCapabilitySchema, type ServiceInstance, ServiceInstanceHealth, ServiceInstanceHealthSchema, ServiceInstanceSchema, ServiceKind, ServiceKindSchema, type ServiceManifest, ServiceManifestSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, type Worker, type WorkerDetail, WorkerDetailSchema, type WorkerInstance, type WorkerInstanceDetail, WorkerInstanceDetailSchema, WorkerInstanceSchema, type WorkerManifest, WorkerManifestSchema, type WorkerReportRequest, WorkerReportRequestSchema, type WorkerRuntimeReport, WorkerRuntimeReportSchema, WorkerSchema, WorkerStatus, WorkerStatusSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, busCommandRequestSchema, busEventEnvelopeSchema, busRouteRuleSchema, busRoutingRuleSchema, configItemInputSchema, createActionCommandRequestSchema, createBusRouteRuleRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, eventMetadataSchema, healthReportInputSchema, paginate, parseSort, publishBusEventRequestSchema, publishBusEventResponseSchema, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, reportedWorkerSchema, resetUserPasswordRequestSchema, serviceCapabilitySchema, serviceReportRequestSchema, updateUserRequestSchema, workerDetailSchema, workerInstanceDetailSchema, workerInstanceSchema, workerManifestSchema, workerReportRequestSchema, workerRuntimeReportSchema, workerSchema };
package/dist/index.js CHANGED
@@ -81,6 +81,19 @@ var AgentHeartbeatSchema = z.object({
81
81
  health: ServiceInstanceHealthSchema,
82
82
  metricsSummary: Json.optional()
83
83
  });
84
+ var ActionAsyncAckSchema = z.object({
85
+ contractVersion: z.literal(CE_CONTRACT_VERSION),
86
+ status: z.literal("RUNNING"),
87
+ commandId: z.string().min(1)
88
+ });
89
+ var ActionCommandResultSchema = z.object({
90
+ contractVersion: z.literal(CE_CONTRACT_VERSION),
91
+ commandId: z.string().min(1),
92
+ status: z.enum(["COMPLETED", "FAILED"]),
93
+ result: Json.optional(),
94
+ errorCode: z.string().optional(),
95
+ errorMessage: z.string().optional()
96
+ });
84
97
  var CeErrorCode = {
85
98
  CONTRACT_VERSION_MISMATCH: "CONTRACT_VERSION_MISMATCH",
86
99
  UNKNOWN_INSTANCE: "UNKNOWN_INSTANCE",
@@ -330,6 +343,8 @@ var ErrorCode = {
330
343
  CAPSULE_SERVICE_CODE_TAKEN: "CAPSULE_SERVICE_CODE_TAKEN"
331
344
  };
332
345
  export {
346
+ ActionAsyncAckSchema,
347
+ ActionCommandResultSchema,
333
348
  ActionDefinitionInputSchema,
334
349
  ActionDefinitionSchema,
335
350
  ActionPrepareResultSchema,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xtrape/capsule-contracts-node",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "TypeScript contracts and Zod schemas for Xtrape Agent, Worker, and Panel wire protocols.",
5
5
  "keywords": [
6
6
  "xtrape",