@xtrape/capsule-contracts-node 0.6.0 → 0.6.1

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 +415 -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,280 @@
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: Release Train 0.6.0](https://img.shields.io/badge/status-0.6.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 release train:
25
+
26
+ ```text
27
+ package version: 0.6.0
28
+ CE contract version: CE_CONTRACT_VERSION = 1
29
+ ```
30
+
31
+ Install:
32
+
33
+ ```bash
34
+ pnpm add @xtrape/capsule-contracts-node@^0.6.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:
17
60
 
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.
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.
23
66
 
24
- ## Xtrape CE 0.1 Phase 0 Contracts
67
+ ## 3. CE 0.1 / 0.6.0 Phase 0 Frozen Contracts
25
68
 
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):
69
+ The CE 0.1 Phase 0 runtime loop is:
29
70
 
30
- | Export | Used by |
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`.
77
+
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.6.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.6.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.6.0 release
168
+ train:
169
+
170
+ ```text
171
+ CE_CONTRACT_VERSION
172
+ ServiceManifestSchema
173
+ ServiceInstanceSchema
174
+ AgentHeartbeatSchema
175
+ ConversationMessageSchema
176
+ ErrorModelSchema
177
+ CeErrorCode
82
178
  ```
83
179
 
84
- ## What is Included
180
+ ### Legacy / compatibility contracts
85
181
 
86
- The package currently exports:
182
+ The package also exports older Panel / Agent / Worker / Command / Audit shapes.
183
+ These remain available for compatibility, but they are not the conceptual source
184
+ of the current Xtrape server governance model.
87
185
 
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.
186
+ | Group | Examples |
187
+ |---|---|
188
+ | Zod re-export | `z` |
189
+ | Status enums | `AgentStatus`, `WorkerStatus`, `CapsuleServiceStatus`, `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`, `AuditResult`, `TokenStatus`, `AgentMode` |
190
+ | Admin | users, sessions, registration token requests/responses |
191
+ | Agent | registration, heartbeat, service report, command result |
192
+ | Worker | Worker manifest, runtime report, instance, health, config, action, detail |
193
+ | Service metadata | `ServiceCapabilitySchema`, `EventMetadataSchema`, `ServiceKindSchema` |
194
+ | Command / action | action definition, action prepare result, command detail, command result |
195
+ | Audit / dashboard | audit event, dashboard summary |
196
+ | System | system health, system version |
197
+ | Experimental bus | `BusEventEnvelopeSchema`, `PublishBusEventRequestSchema`, `PublishBusEventResponseSchema`, `BusRouteRuleSchema`, `CreateBusRouteRuleRequestSchema` |
198
+ | Helpers | `parseSort`, `paginate`, `HttpError`, `ListQueryBase` |
101
199
 
102
200
  The additive v0.4 Worker endpoint aliases and their legacy mappings are recorded
103
201
  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
202
+ a historical baseline rather than being silently rewritten into a different
105
203
  protocol version.
106
204
 
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`.
112
-
113
- ## Validate Agent Registration
205
+ ## 5. Compatibility Notes
114
206
 
115
- ```ts
116
- import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
207
+ ### Legacy package and wire names
117
208
 
118
- const request = RegisterAgentRequestSchema.parse(input);
209
+ The following names may still appear in code, changelog, or wire compatibility
210
+ surfaces:
119
211
 
120
- // request.registrationToken starts with opstage_reg_
121
- // request.agent.mode is embedded or ophub
212
+ ```text
213
+ Capsule*
214
+ capsule
215
+ Opstage
216
+ ophub
217
+ services
218
+ svc_
219
+ opstage_reg_
220
+ opstage_agent_
122
221
  ```
123
222
 
124
- Lowercase aliases are also exported for backend compatibility:
223
+ Treat them as compatibility identifiers unless a current architecture document
224
+ explicitly reintroduces them as active concepts.
125
225
 
126
- ```ts
127
- import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
226
+ ### Worker vs Service naming
128
227
 
129
- const request = registerAgentRequestSchema.parse(input);
228
+ Current architecture uses `xtrape-service` as the deployable capability provider
229
+ registered to `xtrape-server`. `Worker` may appear as a user-facing or
230
+ compatibility-facing actor/runtime concept. `CapsuleService` remains a legacy
231
+ wire alias.
232
+
233
+ ### Agent mode compatibility
234
+
235
+ The `AgentMode` values include:
236
+
237
+ ```text
238
+ embedded
239
+ ophub
130
240
  ```
131
241
 
132
- ## v0.3 External-Agent Compatibility and Metadata
242
+ `ophub` is a historical compatibility value for the external-agent/runtime mode.
243
+ It is not a current top-level Xtrape product concept.
244
+
245
+ ### Known contract drift
246
+
247
+ Historical structured sources still disagree on some command and
248
+ effective-status enum values. `WorkerStatus` is an alias of the currently
249
+ shipped binding. It does not claim that every older enum migration has been
250
+ completed.
133
251
 
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.
252
+ ## 6. Common Validation Examples
253
+
254
+ ### Agent registration
138
255
 
139
256
  ```ts
140
- import { RegisterAgentRequestSchema, ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
257
+ import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
141
258
 
142
- RegisterAgentRequestSchema.parse({
143
- registrationToken: "opstage_reg_...",
259
+ const request = RegisterAgentRequestSchema.parse({
260
+ registrationToken: "opstage_reg_example",
144
261
  agent: {
145
- code: "ophub-a",
146
- name: "External Agent A",
147
- mode: "ophub",
148
- runtime: "go",
262
+ code: "embedded-agent-a",
263
+ mode: "embedded",
264
+ runtime: "nodejs",
149
265
  },
150
266
  });
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
267
  ```
173
268
 
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.
269
+ Lowercase aliases remain available for backend compatibility:
270
+
271
+ ```ts
272
+ import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
273
+
274
+ const request = registerAgentRequestSchema.parse(input);
275
+ ```
177
276
 
178
- ## Validate Service Report
277
+ ### Service / Worker report
179
278
 
180
279
  ```ts
181
280
  import { ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -183,25 +282,25 @@ import { ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
183
282
  const report = ServiceReportRequestSchema.parse({
184
283
  services: [
185
284
  {
186
- code: "hello-capsule",
187
- name: "Hello Capsule",
188
- version: "0.1.0",
285
+ code: "demo-worker",
286
+ name: "Demo Worker",
287
+ version: "0.6.0",
189
288
  runtime: "nodejs",
190
289
  manifest: {
191
290
  kind: "CapsuleService",
192
- schemaVersion: "1.0",
193
- code: "hello-capsule",
194
- name: "Hello Capsule",
195
- version: "0.1.0",
291
+ code: "demo-worker",
292
+ name: "Demo Worker",
293
+ version: "0.6.0",
196
294
  runtime: "nodejs",
197
295
  agentMode: "embedded",
296
+ capabilities: [{ name: "status.query", label: "Status query" }],
198
297
  },
199
298
  },
200
299
  ],
201
300
  });
202
301
  ```
203
302
 
204
- ## Validate Health Report
303
+ ### Health report
205
304
 
206
305
  ```ts
207
306
  import { HealthReportInputSchema } from "@xtrape/capsule-contracts-node";
@@ -213,35 +312,24 @@ const health = HealthReportInputSchema.parse({
213
312
  });
214
313
  ```
215
314
 
216
- Allowed health statuses are:
315
+ Protocol-level `HealthStatus` values are:
217
316
 
218
- ```ts
219
- import { HealthStatus } from "@xtrape/capsule-contracts-node";
220
-
221
- console.log(HealthStatus); // ["UP", "DEGRADED", "DOWN", "UNKNOWN"]
317
+ ```text
318
+ UP
319
+ DEGRADED
320
+ DOWN
321
+ UNKNOWN
222
322
  ```
223
323
 
224
- `HealthStatus` is the protocol-level status reported by Agents and Capsule
225
- Services:
226
-
227
- - `UP`
228
- - `DEGRADED`
229
- - `DOWN`
230
- - `UNKNOWN`
324
+ Panel or server implementations may derive separate operator-facing states such
325
+ as `HEALTHY`, `UNHEALTHY`, `STALE`, or `OFFLINE`.
231
326
 
232
- Xtrape Panel may derive an operator-facing `effectiveStatus` such as:
233
-
234
- - `HEALTHY`
235
- - `UNHEALTHY`
236
- - `STALE`
237
- - `OFFLINE`
238
-
239
- ## Validate Config and Action Definitions
327
+ ### Config and action definitions
240
328
 
241
329
  ```ts
242
330
  import {
243
- ConfigItemInputSchema,
244
331
  ActionDefinitionInputSchema,
332
+ ConfigItemInputSchema,
245
333
  } from "@xtrape/capsule-contracts-node";
246
334
 
247
335
  const config = ConfigItemInputSchema.parse({
@@ -259,9 +347,7 @@ const action = ActionDefinitionInputSchema.parse({
259
347
  });
260
348
  ```
261
349
 
262
- ## Validate Action Prepare Result
263
-
264
- Use `ActionPrepareResultSchema` to validate the action-prepare payload directly:
350
+ ### Action prepare result
265
351
 
266
352
  ```ts
267
353
  import { ActionPrepareResultSchema } from "@xtrape/capsule-contracts-node";
@@ -278,28 +364,7 @@ const prepare = ActionPrepareResultSchema.parse({
278
364
  });
279
365
  ```
280
366
 
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
367
+ ### Command result
303
368
 
304
369
  ```ts
305
370
  import { ReportCommandResultRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -326,9 +391,47 @@ ReportCommandResultRequestSchema.parse({
326
391
  });
327
392
  ```
328
393
 
329
- ## Error Codes
394
+ ## 7. Experimental Legacy Event Routing
395
+
396
+ The v0.4 event routing surface is experimental and compatibility-oriented. It
397
+ models a small CE in-process event-to-command router. It is not a standalone bus
398
+ server, external broker abstraction, workflow DSL, service mesh, distributed
399
+ event system, or fan-out engine.
400
+
401
+ Key exports:
402
+
403
+ ```text
404
+ BusEventEnvelopeSchema
405
+ PublishBusEventRequestSchema
406
+ PublishBusEventResponseSchema
407
+ BusRouteRuleSchema
408
+ CreateBusRouteRuleRequestSchema
409
+ BusErrorCode
410
+ ```
411
+
412
+ Minimal event payload:
330
413
 
331
- The `ErrorCode` export contains protocol-level error code constants currently
414
+ ```ts
415
+ import { BusEventEnvelopeSchema } from "@xtrape/capsule-contracts-node";
416
+
417
+ BusEventEnvelopeSchema.parse({
418
+ eventType: "demo.item.created",
419
+ sourceServiceCode: "demo-worker",
420
+ payload: { itemId: "item-1" },
421
+ });
422
+ ```
423
+
424
+ All schemas include or default:
425
+
426
+ ```text
427
+ experimental: "v0.4-experimental"
428
+ ```
429
+
430
+ Consumers should treat this wire surface as unstable until v1.0.
431
+
432
+ ## 8. Error Codes
433
+
434
+ The legacy `ErrorCode` export contains protocol-level error constants currently
332
435
  used by CE and SDKs:
333
436
 
334
437
  ```ts
@@ -337,54 +440,61 @@ import { ErrorCode } from "@xtrape/capsule-contracts-node";
337
440
  throw new Error(ErrorCode.VALIDATION_FAILED);
338
441
  ```
339
442
 
340
- Currently exported codes include:
443
+ Current values include:
444
+
445
+ ```text
446
+ INTERNAL_ERROR
447
+ VALIDATION_FAILED
448
+ UNAUTHORIZED
449
+ FORBIDDEN
450
+ NOT_FOUND
451
+ CONFLICT
452
+ CAPSULE_SERVICE_CODE_TAKEN
453
+ CSRF_INVALID
454
+ ACTION_REQUIRES_CONFIRMATION
455
+ COMMAND_EXPIRED
456
+ TOKEN_REVOKED
457
+ TOKEN_EXPIRED
458
+ AGENT_REVOKED
459
+ AGENT_DISABLED
460
+ ```
341
461
 
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`
462
+ For CE Phase 0 runtime errors, prefer `CeErrorCode` with `ErrorModelSchema`.
356
463
 
357
- See the OpenAPI contract and docs site for endpoint-specific errors.
464
+ ## 9. ID Generation
358
465
 
359
- ## ID generation
466
+ This package validates IDs at the wire boundary but does **not** mint IDs.
360
467
 
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.
468
+ `newId()`, `idPrefixes`, and `IdPrefix` were removed in `0.2.0` because runtime
469
+ ID generation does not belong in the contracts package. Consumers that need
470
+ local ID generation should provide their own factory.
366
471
 
367
- Consumers that need local ID generation should provide their own factory.
368
- Example using `nanoid` directly:
472
+ Documented compatibility prefixes include:
369
473
 
370
- ```ts
371
- import { customAlphabet } from "nanoid";
372
-
373
- const idBody = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyz", 21);
374
- const commandId = `cmd_${idBody()}`;
474
+ ```text
475
+ wks_
476
+ usr_
477
+ agt_
478
+ tok_
479
+ svc_
480
+ hlr_
481
+ cfg_
482
+ act_
483
+ cmd_
484
+ crs_
485
+ aud_
375
486
  ```
376
487
 
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(...)`.
488
+ Individual schemas enforce prefixes where needed with Zod validators such as
489
+ `z.string().startsWith(...)`.
380
490
 
381
- ## List Helpers
491
+ ## 10. List Helpers
382
492
 
383
493
  ```ts
384
494
  import {
385
495
  ListQueryBase,
386
- parseSort,
387
496
  paginate,
497
+ parseSort,
388
498
  } from "@xtrape/capsule-contracts-node";
389
499
 
390
500
  const query = ListQueryBase.parse({ page: "1", pageSize: "20" });
@@ -392,101 +502,121 @@ const sort = parseSort("-createdAt", ["createdAt", "name"]);
392
502
  const response = paginate(items, query.page, query.pageSize, total);
393
503
  ```
394
504
 
395
- ## Used By
505
+ These helpers are provisional convenience utilities for backend-style consumers.
506
+ They may move out of the contracts package in a future minor version.
396
507
 
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.
508
+ ## 11. Schema Stability
406
509
 
407
- ## Compatibility
510
+ The package follows semver. During the pre-`1.0.0` release train, pin matching
511
+ minor versions across CE, Agent SDK, and Contracts.
408
512
 
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` |
513
+ | Group | Stability | Notes |
514
+ |---|---:|---|
515
+ | CE Phase 0 contracts | Frozen for CE 0.1 | Changes require `CE_CONTRACT_VERSION` and surface guard updates. |
516
+ | Status enums | Stable | Existing values should not be removed before v1.0. New values may be added in minor versions. |
517
+ | Agent / backend wire schemas | Evolving | Additive optional fields may land in minor versions. |
518
+ | Worker / service compatibility shapes | Evolving | Legacy aliases retain existing physical wire shapes. |
519
+ | Persisted/read-only shapes | Evolving | Useful for consumers, but track CE storage and should be read as provisional. |
520
+ | Action prepare / command result | Provisional | May tighten before v1.0. |
521
+ | Experimental bus contracts | Experimental | Not a stable data-plane or broker contract. |
522
+ | Helpers | Provisional | Not strictly part of the wire spec. |
413
523
 
414
- Pin matching minor versions across CE, Agent SDK, and Contracts. The wire
415
- protocol may still evolve before `v1.0`.
524
+ Breaking or incompatible changes are recorded in `CHANGELOG.md`.
416
525
 
417
- ## Breaking changes in `0.2.0`
526
+ ## 12. Current Planning
418
527
 
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.
528
+ Active 0.7.0 planning should focus on service governance contracts, not AI task
529
+ routing or Studio-specific workflow contracts.
426
530
 
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.
531
+ Core 0.7.0 directions are:
429
532
 
430
- ## Schema Stability
533
+ ```text
534
+ service governance
535
+ configuration
536
+ credential references
537
+ policy / approval requirement
538
+ explicit invocation boundary
539
+ audit / trace
540
+ operator-facing read models
541
+ ```
431
542
 
432
- The package follows semver. During the current pre-`1.0` release-train phase,
433
- the guarantees per schema group are:
543
+ Out of scope for the core 0.7.0 contract surface:
434
544
 
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.) |
545
+ ```text
546
+ intelligent service selection
547
+ business intent routing
548
+ AI planner protocol
549
+ complete workflow engine
550
+ service-to-service data plane
551
+ marketplace / paid transaction contracts
552
+ production deployment orchestration
553
+ ```
445
554
 
446
- **Until `v1.0`**, pin to a single minor across CE / Agent SDK / Contracts.
447
- Breaking changes will be called out in `CHANGELOG.md`.
555
+ See the active Forgejo issue:
448
556
 
449
- ## Documentation
557
+ ```text
558
+ #30 0.7.0: define service governance, configuration, policy, credential, invocation, and audit contracts
559
+ ```
450
560
 
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
561
+ ## 13. Used By
458
562
 
459
- ## Contributing
563
+ - `xtrape-server-ce` — CE headless server runtime and control-plane implementation.
564
+ - `xtrape-agent-nodejs` — Node.js Agent SDK request/response validation.
565
+ - `xtrape-demo` — end-to-end runnable demo service.
566
+ - `xtrape-telegram` — Telegram adapter over server message APIs.
567
+ - `xtrape-panel-ce` — operator UI consumer of server/contract surfaces.
568
+ - Worker and service implementations that want local validation before reporting
569
+ to Xtrape runtime components.
460
570
 
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.
571
+ ## 14. Development
464
572
 
465
- ## License
573
+ ```bash
574
+ pnpm install
575
+ pnpm typecheck
576
+ pnpm test
577
+ pnpm build
578
+ ```
466
579
 
467
- Apache-2.0. "Xtrape" and "Opstage" are trademarks of their
468
- respective owners; the open-source license does not grant trademark rights.
580
+ Package outputs:
469
581
 
470
- ## v0.4 legacy event routing Experimental
582
+ ```text
583
+ dist/index.js
584
+ dist/index.cjs
585
+ dist/index.d.ts
586
+ ```
471
587
 
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.
588
+ Published package files include:
473
589
 
474
- Key exports:
590
+ ```text
591
+ dist
592
+ spec
593
+ README.md
594
+ LICENSE
595
+ NOTICE
596
+ ```
475
597
 
476
- - `BusEventEnvelopeSchema`
477
- - `PublishBusEventRequestSchema`
478
- - `PublishBusEventResponseSchema`
479
- - `BusRouteRuleSchema`
480
- - `CreateBusRouteRuleRequestSchema`
598
+ ## 15. Documentation
481
599
 
482
- Minimal event payload:
600
+ Current canonical docs:
483
601
 
484
- ```ts
485
- BusEventEnvelopeSchema.parse({
486
- eventType: "demo.item.created",
487
- sourceServiceCode: "demo-worker",
488
- payload: { itemId: "item-1" },
489
- });
490
- ```
602
+ - `xtrape-docs/docs/architecture/11-xtrape-ce-system-baseline.md`
603
+ - `xtrape-docs/docs/runtime-platform/01-phase-0-runtime-mvp.md`
604
+ - `xtrape-docs/docs/runtime-platform/02-service-manifest-schema.md`
605
+ - `xtrape-docs/docs/runtime-platform/03-message-protocol-schema.md`
606
+ - `xtrape-docs/docs/runtime-platform/04-agent-registration-heartbeat.md`
607
+ - `xtrape-docs/docs/runtime-platform/05-server-ce-module-design.md`
608
+
609
+ Historical public docs may still mention Opstage or Capsule names. Treat those as
610
+ compatibility references unless later architecture docs explicitly reintroduce
611
+ the terms.
612
+
613
+ ## 16. Contributing
614
+
615
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for schema change workflow and PR
616
+ checks. See [SECURITY.md](./SECURITY.md) for vulnerability reporting and
617
+ contract validation safety guidance.
618
+
619
+ ## 17. License
491
620
 
492
- All schemas include or default `experimental: "v0.4-experimental"`; consumers should treat the wire surface as unstable until v1.0.
621
+ Apache-2.0. "Xtrape" and "Opstage" are trademarks of their respective owners;
622
+ 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.6.1",
4
4
  "description": "TypeScript contracts and Zod schemas for Xtrape Agent, Worker, and Panel wire protocols.",
5
5
  "keywords": [
6
6
  "xtrape",