@xtrape/capsule-contracts-node 0.5.1 → 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 +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,183 +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
+ ```
10
30
 
11
- ## Contract Authority Boundary
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
+ ```
45
+
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.
66
+
67
+ ## 3. CE 0.1 / 0.6.0 Phase 0 Frozen Contracts
17
68
 
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.
69
+ The CE 0.1 Phase 0 runtime loop is:
23
70
 
24
- ## Xtrape CE 0.1 Phase 0 Contracts
71
+ ```text
72
+ Telegram / caller -> xtrape-server-ce -> demo xtrape-service -> reply
73
+ ```
25
74
 
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):
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.1.0" },
45
- runtime: { language: "node", agent: "xtrape-agent-node" },
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: Public Review](https://img.shields.io/badge/status-Public%20Review-orange.svg)](https://xtrape-com.github.io/xtrape-capsule-site/)
57
- [![Docs](https://img.shields.io/badge/docs-xtrape--capsule--site-blue.svg)](https://xtrape-com.github.io/xtrape-capsule-site/contracts/overview)
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:** Xtrape is currently in **Public Review** before
65
- > the `v0.1.0 Public Preview` release. This package is **published to npm** under the
66
- > `public-review` dist-tag. APIs, contracts, deployment instructions, and SDK
67
- > interfaces may still change.
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
+ ```
68
137
 
69
- ## Install
138
+ ### Minimal explicit-target message
70
139
 
71
- During Public Review, install the prerelease package with:
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@public-review
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
- The current Public Review version may change before `v0.1.0`.
159
+ ## 4. Current Export Groups
78
160
 
79
- For this repository itself:
161
+ The package currently exports both the current CE Phase 0 contracts and legacy
162
+ compatibility surfaces.
80
163
 
81
- ```bash
82
- pnpm install
83
- pnpm build
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
84
178
  ```
85
179
 
86
- ## What is Included
180
+ ### Legacy / compatibility contracts
87
181
 
88
- 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.
89
185
 
90
- - Zod itself as `z` for consumers that want one compatible Zod instance.
91
- - Status enum arrays and types: `AgentStatus`, `WorkerStatus` (plus the legacy
92
- `CapsuleServiceStatus` alias),
93
- `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`,
94
- `AuditResult`, `TokenStatus`, `AgentMode`.
95
- - Admin schemas: users, sessions, registration token requests/responses.
96
- - Agent schemas: registration, heartbeat, service report, command result.
97
- - Worker schemas: Worker Manifest, Worker Runtime Report, Worker Instance,
98
- health, config, Action, and Worker Instance detail. Legacy
99
- Capsule-named aliases remain available for wire compatibility.
100
- - Command schemas: create command, command detail, command result.
101
- - Audit and dashboard schemas.
102
- - 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` |
103
199
 
104
200
  The additive v0.4 Worker endpoint aliases and their legacy mappings are recorded
105
201
  in `spec/worker-compatibility-v0.4.json`. The older CE v0.1 OpenAPI file remains
106
- the historical baseline rather than being silently rewritten into a different
202
+ a historical baseline rather than being silently rewritten into a different
107
203
  protocol version.
108
204
 
109
- > **Known contract drift:** the historical structured sources still disagree on
110
- > some Command and effective-status enum values. The `WorkerStatus` export is an
111
- > alias of the currently shipped binding; it does not claim that the unresolved
112
- > enum migration documented in `xtrape-docs` has been completed.
113
- - Helpers: `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
205
+ ## 5. Compatibility Notes
114
206
 
115
- ## Validate Agent Registration
207
+ ### Legacy package and wire names
116
208
 
117
- ```ts
118
- import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
209
+ The following names may still appear in code, changelog, or wire compatibility
210
+ surfaces:
119
211
 
120
- const request = RegisterAgentRequestSchema.parse(input);
121
-
122
- // request.registrationToken starts with opstage_reg_
123
- // 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_
124
221
  ```
125
222
 
126
- 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.
127
225
 
128
- ```ts
129
- import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
226
+ ### Worker vs Service naming
130
227
 
131
- 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
132
240
  ```
133
241
 
134
- ## 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.
135
251
 
136
- v0.3 adds the legacy `ophub` Agent-mode wire value for the historical Go
137
- external-Agent runtime. It represents one or more local Workers. It is not the
138
- canonical Gateway role: Gateway routes Agent/control-plane traffic while
139
- preserving Agent protocol semantics.
252
+ ## 6. Common Validation Examples
253
+
254
+ ### Agent registration
140
255
 
141
256
  ```ts
142
- import { RegisterAgentRequestSchema, ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
257
+ import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
143
258
 
144
- RegisterAgentRequestSchema.parse({
145
- registrationToken: "opstage_reg_...",
259
+ const request = RegisterAgentRequestSchema.parse({
260
+ registrationToken: "opstage_reg_example",
146
261
  agent: {
147
- code: "ophub-a",
148
- name: "External Agent A",
149
- mode: "ophub",
150
- runtime: "go",
262
+ code: "embedded-agent-a",
263
+ mode: "embedded",
264
+ runtime: "nodejs",
151
265
  },
152
266
  });
153
-
154
- ServiceReportRequestSchema.parse({
155
- services: [
156
- {
157
- code: "svc-one",
158
- name: "Service One",
159
- version: "0.3.0",
160
- runtime: "nodejs",
161
- manifest: {
162
- kind: "CapsuleService",
163
- code: "svc-one",
164
- name: "Service One",
165
- version: "0.3.0",
166
- runtime: "nodejs",
167
- agentMode: "ophub",
168
- capabilities: [{ name: "inventory.read", label: "Inventory read" }],
169
- events: [{ name: "inventory.changed", direction: "publish", designOnly: true }],
170
- },
171
- },
172
- ],
173
- });
174
267
  ```
175
268
 
176
- Capability metadata is implemented as declarative service metadata. Event
177
- metadata is intentionally a foundation for future legacy event routing work; `designOnly`
178
- 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
+ ```
179
276
 
180
- ## Validate Service Report
277
+ ### Service / Worker report
181
278
 
182
279
  ```ts
183
280
  import { ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -185,25 +282,25 @@ import { ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
185
282
  const report = ServiceReportRequestSchema.parse({
186
283
  services: [
187
284
  {
188
- code: "hello-capsule",
189
- name: "Hello Capsule",
190
- version: "0.1.0",
285
+ code: "demo-worker",
286
+ name: "Demo Worker",
287
+ version: "0.6.0",
191
288
  runtime: "nodejs",
192
289
  manifest: {
193
290
  kind: "CapsuleService",
194
- schemaVersion: "1.0",
195
- code: "hello-capsule",
196
- name: "Hello Capsule",
197
- version: "0.1.0",
291
+ code: "demo-worker",
292
+ name: "Demo Worker",
293
+ version: "0.6.0",
198
294
  runtime: "nodejs",
199
295
  agentMode: "embedded",
296
+ capabilities: [{ name: "status.query", label: "Status query" }],
200
297
  },
201
298
  },
202
299
  ],
203
300
  });
204
301
  ```
205
302
 
206
- ## Validate Health Report
303
+ ### Health report
207
304
 
208
305
  ```ts
209
306
  import { HealthReportInputSchema } from "@xtrape/capsule-contracts-node";
@@ -215,35 +312,24 @@ const health = HealthReportInputSchema.parse({
215
312
  });
216
313
  ```
217
314
 
218
- Allowed health statuses are:
315
+ Protocol-level `HealthStatus` values are:
219
316
 
220
- ```ts
221
- import { HealthStatus } from "@xtrape/capsule-contracts-node";
222
-
223
- console.log(HealthStatus); // ["UP", "DEGRADED", "DOWN", "UNKNOWN"]
317
+ ```text
318
+ UP
319
+ DEGRADED
320
+ DOWN
321
+ UNKNOWN
224
322
  ```
225
323
 
226
- `HealthStatus` is the protocol-level status reported by Agents and Capsule
227
- Services:
228
-
229
- - `UP`
230
- - `DEGRADED`
231
- - `DOWN`
232
- - `UNKNOWN`
233
-
234
- Xtrape Panel may derive an operator-facing `effectiveStatus` such as:
235
-
236
- - `HEALTHY`
237
- - `UNHEALTHY`
238
- - `STALE`
239
- - `OFFLINE`
324
+ Panel or server implementations may derive separate operator-facing states such
325
+ as `HEALTHY`, `UNHEALTHY`, `STALE`, or `OFFLINE`.
240
326
 
241
- ## Validate Config and Action Definitions
327
+ ### Config and action definitions
242
328
 
243
329
  ```ts
244
330
  import {
245
- ConfigItemInputSchema,
246
331
  ActionDefinitionInputSchema,
332
+ ConfigItemInputSchema,
247
333
  } from "@xtrape/capsule-contracts-node";
248
334
 
249
335
  const config = ConfigItemInputSchema.parse({
@@ -261,9 +347,7 @@ const action = ActionDefinitionInputSchema.parse({
261
347
  });
262
348
  ```
263
349
 
264
- ## Validate Action Prepare Result
265
-
266
- Use `ActionPrepareResultSchema` to validate the action-prepare payload directly:
350
+ ### Action prepare result
267
351
 
268
352
  ```ts
269
353
  import { ActionPrepareResultSchema } from "@xtrape/capsule-contracts-node";
@@ -280,28 +364,7 @@ const prepare = ActionPrepareResultSchema.parse({
280
364
  });
281
365
  ```
282
366
 
283
- When reported back to Xtrape Panel for an `ACTION_PREPARE` command, this shape is
284
- placed under `ReportCommandResultRequest.data`. Command result reporting still
285
- uses `ReportCommandResultRequestSchema`:
286
-
287
- ```ts
288
- import { ReportCommandResultRequestSchema } from "@xtrape/capsule-contracts-node";
289
-
290
- const prepareResult = ReportCommandResultRequestSchema.parse({
291
- success: true,
292
- data: {
293
- action: { name: "echo", label: "Echo", dangerLevel: "LOW" },
294
- inputSchema: {
295
- type: "object",
296
- properties: { message: { type: "string", default: "hello" } },
297
- },
298
- initialPayload: { message: "hello" },
299
- currentState: { service: "ready" },
300
- },
301
- });
302
- ```
303
-
304
- ## Validate Command Result
367
+ ### Command result
305
368
 
306
369
  ```ts
307
370
  import { ReportCommandResultRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -328,9 +391,47 @@ ReportCommandResultRequestSchema.parse({
328
391
  });
329
392
  ```
330
393
 
331
- ## 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:
413
+
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
+ ```
332
423
 
333
- The `ErrorCode` export contains protocol-level error code constants currently
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
334
435
  used by CE and SDKs:
335
436
 
336
437
  ```ts
@@ -339,54 +440,61 @@ import { ErrorCode } from "@xtrape/capsule-contracts-node";
339
440
  throw new Error(ErrorCode.VALIDATION_FAILED);
340
441
  ```
341
442
 
342
- Currently exported codes include:
343
-
344
- - `INTERNAL_ERROR`
345
- - `VALIDATION_FAILED`
346
- - `UNAUTHORIZED`
347
- - `FORBIDDEN`
348
- - `NOT_FOUND`
349
- - `CONFLICT`
350
- - `CAPSULE_SERVICE_CODE_TAKEN` (persisted compatibility identifier for a Worker ownership conflict)
351
- - `CSRF_INVALID`
352
- - `ACTION_REQUIRES_CONFIRMATION`
353
- - `COMMAND_EXPIRED`
354
- - `TOKEN_REVOKED`
355
- - `TOKEN_EXPIRED`
356
- - `AGENT_REVOKED`
357
- - `AGENT_DISABLED`
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
+ ```
358
461
 
359
- See the OpenAPI contract and docs site for endpoint-specific errors.
462
+ For CE Phase 0 runtime errors, prefer `CeErrorCode` with `ErrorModelSchema`.
360
463
 
361
- ## ID generation
464
+ ## 9. ID Generation
362
465
 
363
- This package validates IDs at the wire boundary (via Zod) but does **not** mint
364
- them. Until v0.1.x there was a small `newId()` helper plus an `idPrefixes`
365
- table; both were removed in `0.2.0` to keep the contracts surface focused on
366
- the wire spec — see [`CHANGELOG.md`](./CHANGELOG.md) and the
367
- "Breaking changes" section at the top of this README.
466
+ This package validates IDs at the wire boundary but does **not** mint IDs.
368
467
 
369
- Consumers that need local ID generation should provide their own factory.
370
- Example using `nanoid` directly:
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.
371
471
 
372
- ```ts
373
- import { customAlphabet } from "nanoid";
472
+ Documented compatibility prefixes include:
374
473
 
375
- const idBody = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyz", 21);
376
- 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_
377
486
  ```
378
487
 
379
- Documented ID prefixes in use across CE and the Agent SDK include `wks_`,
380
- `usr_`, `agt_`, `tok_`, `svc_`, `hlr_`, `cfg_`, `act_`, `cmd_`, `crs_`, and
381
- `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(...)`.
382
490
 
383
- ## List Helpers
491
+ ## 10. List Helpers
384
492
 
385
493
  ```ts
386
494
  import {
387
495
  ListQueryBase,
388
- parseSort,
389
496
  paginate,
497
+ parseSort,
390
498
  } from "@xtrape/capsule-contracts-node";
391
499
 
392
500
  const query = ListQueryBase.parse({ page: "1", pageSize: "20" });
@@ -394,100 +502,121 @@ const sort = parseSort("-createdAt", ["createdAt", "name"]);
394
502
  const response = paginate(items, query.page, query.pageSize, total);
395
503
  ```
396
504
 
397
- ## 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.
398
507
 
399
- - [`xtrape-capsule-ce`](https://github.com/xtrape-com/xtrape-capsule-ce) —
400
- Xtrape Panel CE backend validation and protocol handling.
401
- - [`xtrape-capsule-agent-node`](https://github.com/xtrape-com/xtrape-capsule-agent-node)
402
- — Node embedded Agent SDK request/response types.
403
- - [`xtrape-capsule-demo`](https://github.com/xtrape-com/xtrape-capsule-demo)
404
- — End-to-end runnable Worker that imports these schemas through
405
- the Agent SDK.
406
- - Worker implementations that want local validation before reporting to
407
- Xtrape Panel.
508
+ ## 11. Schema Stability
408
509
 
409
- ## 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.
410
512
 
411
- | Package | Compatible with |
412
- | -------------------------------------- | ---------------------------------------- |
413
- | `@xtrape/capsule-contracts-node@0.2.x` | Xtrape Panel CE `0.2.x` and Agent SDK `0.2.x` |
414
- | `@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. |
415
523
 
416
- Pin matching minor versions across CE, Agent SDK, and Contracts. The wire
417
- protocol may still evolve before `v1.0`.
524
+ Breaking or incompatible changes are recorded in `CHANGELOG.md`.
418
525
 
419
- ## Breaking changes in `0.2.0`
526
+ ## 12. Current Planning
420
527
 
421
- - **`newId()` removed.** The helper minted random IDs with a prefix; it was
422
- never used by CE (entity IDs are minted in the backend). External consumers
423
- that imported `newId` must wire their own factory — see the
424
- [ID generation](#id-generation) section above.
425
- - **`idPrefixes` constant and `IdPrefix` type removed.** Same rationale.
426
- - **`nanoid` runtime dependency removed** as a consequence. Consumers that
427
- 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.
428
530
 
429
- The wire schemas themselves are **unchanged** between `0.1.x` and `0.2.x`;
430
- existing `0.1.x` agents continue to validate against a `0.2.x` backend.
531
+ Core 0.7.0 directions are:
431
532
 
432
- ## 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
+ ```
433
542
 
434
- The package follows semver. For Public Review and Public Preview, the
435
- guarantees per schema group are:
543
+ Out of scope for the core 0.7.0 contract surface:
436
544
 
437
- | Group | Stability | Notes |
438
- | ---------------------------------------------------------------------------------------------------------------- | :---------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
439
- | 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`. |
440
- | 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. |
441
- | Worker shapes (`WorkerManifest`, `WorkerRuntimeReport`, `WorkerInstance`, `HealthReportInput`, `ConfigItemInput`, `ActionDefinitionInput`) | Evolving | Legacy aliases retain the existing physical wire shapes. |
442
- | Persisted shapes (`Agent`, `CapsuleService`, `ConfigItem`, `ActionDefinition`, `Command*`, `AuditEvent`, `User`) | Evolving | Track CE storage; safe to consume read-only. |
443
- | `ActionPrepareResultSchema` | Provisional | Added in `0.1.0-public-review.0`. Field shape may still tighten before `v1.0`. |
444
- | `Command.type` enum | Evolving | Currently `ACTION_PREPARE` / `ACTION_EXECUTE`. New types may be added. |
445
- | Error codes (`ErrorCode`) | Evolving | New codes may be added. Existing codes will not change meaning before `v1.0`. |
446
- | 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
+ ```
447
554
 
448
- **Until `v1.0`**, pin to a single minor across CE / Agent SDK / Contracts.
449
- Breaking changes will be called out in `CHANGELOG.md`.
555
+ See the active Forgejo issue:
450
556
 
451
- ## Documentation
557
+ ```text
558
+ #30 0.7.0: define service governance, configuration, policy, credential, invocation, and audit contracts
559
+ ```
452
560
 
453
- - Contracts overview: https://xtrape-com.github.io/xtrape-capsule-site/contracts/overview
454
- - Manifest contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/manifest
455
- - Health contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/health
456
- - Actions contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/actions
457
- - Errors: https://xtrape-com.github.io/xtrape-capsule-site/contracts/errors
458
- - Xtrape Panel CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
561
+ ## 13. Used By
459
562
 
460
- ## 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.
461
570
 
462
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for schema change workflow and PR
463
- checks. See [SECURITY.md](./SECURITY.md) for vulnerability reporting and
464
- contract validation safety guidance.
571
+ ## 14. Development
572
+
573
+ ```bash
574
+ pnpm install
575
+ pnpm typecheck
576
+ pnpm test
577
+ pnpm build
578
+ ```
465
579
 
466
- ## License
580
+ Package outputs:
467
581
 
468
- Apache-2.0. "Xtrape" and "Opstage" are trademarks of their
469
- respective owners; the open-source license does not grant trademark rights.
582
+ ```text
583
+ dist/index.js
584
+ dist/index.cjs
585
+ dist/index.d.ts
586
+ ```
470
587
 
471
- ## v0.4 legacy event routing Experimental
588
+ Published package files include:
472
589
 
473
- `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.
590
+ ```text
591
+ dist
592
+ spec
593
+ README.md
594
+ LICENSE
595
+ NOTICE
596
+ ```
474
597
 
475
- Key exports:
598
+ ## 15. Documentation
476
599
 
477
- - `BusEventEnvelopeSchema`
478
- - `PublishBusEventRequestSchema`
479
- - `PublishBusEventResponseSchema`
480
- - `BusRouteRuleSchema`
481
- - `CreateBusRouteRuleRequestSchema`
600
+ Current canonical docs:
482
601
 
483
- Minimal event payload:
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`
484
608
 
485
- ```ts
486
- BusEventEnvelopeSchema.parse({
487
- eventType: "demo.item.created",
488
- sourceServiceCode: "demo-worker",
489
- payload: { itemId: "item-1" },
490
- });
491
- ```
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
492
620
 
493
- 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.5.1",
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",