@xtrape/capsule-contracts-node 0.1.0-public-review.1 → 0.3.0

package/README.md

@@ -41,14 +41,14 @@ The package currently exports:
 - Zod itself as `z` for consumers that want one compatible Zod instance.
 - Status enum arrays and types: `AgentStatus`, `CapsuleServiceStatus`,
   `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`,
-  `AuditResult`, `TokenStatus`.
+  `AuditResult`, `TokenStatus`, `AgentMode`.
 - Admin schemas: users, sessions, registration token requests/responses.
 - Agent schemas: registration, heartbeat, service report, command result.
 - Capsule Service schemas: manifest, health, config, action, service detail.
 - Command schemas: create command, command detail, command result.
 - Audit and dashboard schemas.
 - System health/version schemas.
-- Helpers: `newId`, `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
+- Helpers: `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
 
 ## Validate Agent Registration
 
@@ -58,7 +58,7 @@ import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
 const request = RegisterAgentRequestSchema.parse(input);
 
 // request.registrationToken starts with opstage_reg_
-// request.agent.mode is embedded
+// request.agent.mode is embedded or ophub
 ```
 
 Lowercase aliases are also exported for backend compatibility:
@@ -69,6 +69,52 @@ import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
 const request = registerAgentRequestSchema.parse(input);
 ```
 
+## v0.3 OpHub and Metadata
+
+v0.3 adds the experimental `ophub` Agent mode. `sidecar` and `base-image`
+remain OpHub deployment forms, but the wire contract should use
+`mode: "ophub"` for an OpHub that represents one or more local Capsule
+Services.
+
+```ts
+import { RegisterAgentRequestSchema, ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
+
+RegisterAgentRequestSchema.parse({
+  registrationToken: "opstage_reg_...",
+  agent: {
+    code: "ophub-a",
+    name: "OpHub A",
+    mode: "ophub",
+    runtime: "go",
+  },
+});
+
+ServiceReportRequestSchema.parse({
+  services: [
+    {
+      code: "svc-one",
+      name: "Service One",
+      version: "0.3.0",
+      runtime: "nodejs",
+      manifest: {
+        kind: "CapsuleService",
+        code: "svc-one",
+        name: "Service One",
+        version: "0.3.0",
+        runtime: "nodejs",
+        agentMode: "ophub",
+        capabilities: [{ name: "inventory.read", label: "Inventory read" }],
+        events: [{ name: "inventory.changed", direction: "publish", designOnly: true }],
+      },
+    },
+  ],
+});
+```
+
+Capability metadata is implemented as declarative service metadata. Event
+metadata is intentionally a foundation for future Capsule Bus work; `designOnly`
+events must not be treated as a working event bus.
+
 ## Validate Service Report
 
 ```ts
@@ -249,16 +295,27 @@ Currently exported codes include:
 
 See the OpenAPI contract and docs site for endpoint-specific errors.
 
-## ID Helpers
+## ID generation
+
+This package validates IDs at the wire boundary (via Zod) but does **not** mint
+them. Until v0.1.x there was a small `newId()` helper plus an `idPrefixes`
+table; both were removed in `0.2.0` to keep the contracts surface focused on
+the wire spec — see [`CHANGELOG.md`](./CHANGELOG.md) and the
+"Breaking changes" section at the top of this README.
+
+Consumers that need local ID generation should provide their own factory.
+Example using `nanoid` directly:
 
 ```ts
-import { newId } from "@xtrape/capsule-contracts-node";
+import { customAlphabet } from "nanoid";
 
-const commandId = newId("cmd_");
+const idBody = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyz", 21);
+const commandId = `cmd_${idBody()}`;
 ```
 
-Supported prefixes include `wks_`, `usr_`, `agt_`, `tok_`, `svc_`, `hlr_`,
-`cfg_`, `act_`, `cmd_`, `crs_`, and `aud_`.
+Documented ID prefixes in use across CE and the Agent SDK include `wks_`,
+`usr_`, `agt_`, `tok_`, `svc_`, `hlr_`, `cfg_`, `act_`, `cmd_`, `crs_`, and
+`aud_`. These are enforced by the Zod schemas via `z.string().startsWith(...)`.
 
 ## List Helpers
 
@@ -290,10 +347,24 @@ const response = paginate(items, query.page, query.pageSize, total);
 
 | Package                                | Compatible with                          |
 | -------------------------------------- | ---------------------------------------- |
+| `@xtrape/capsule-contracts-node@0.2.x` | Opstage CE `0.2.x` and Agent SDK `0.2.x` |
 | `@xtrape/capsule-contracts-node@0.1.x` | Opstage CE `0.1.x` and Agent SDK `0.1.x` |
 
-During Public Review and Public Preview, keep CE, Agent SDK, and Contracts on
-matching minor versions. The wire protocol may still evolve before `v1.0`.
+Pin matching minor versions across CE, Agent SDK, and Contracts. The wire
+protocol may still evolve before `v1.0`.
+
+## Breaking changes in `0.2.0`
+
+- **`newId()` removed.** The helper minted random IDs with a prefix; it was
+  never used by CE (entity IDs are minted in the backend). External consumers
+  that imported `newId` must wire their own factory — see the
+  [ID generation](#id-generation) section above.
+- **`idPrefixes` constant and `IdPrefix` type removed.** Same rationale.
+- **`nanoid` runtime dependency removed** as a consequence. Consumers that
+  relied on a transitive `nanoid` install must now add it directly.
+
+The wire schemas themselves are **unchanged** between `0.1.x` and `0.2.x`;
+existing `0.1.x` agents continue to validate against a `0.2.x` backend.
 
 ## Schema Stability
 
@@ -309,7 +380,7 @@ guarantees per schema group are:
 | `ActionPrepareResultSchema`                                                                                      | Provisional | Added in `0.1.0-public-review.0`. Field shape may still tighten before `v1.0`.                                                                                       |
 | `Command.type` enum                                                                                              |  Evolving  | Currently `ACTION_PREPARE` / `ACTION_EXECUTE`. New types may be added.                                                                                                |
 | Error codes (`ErrorCode`)                                                                                        |  Evolving  | New codes may be added. Existing codes will not change meaning before `v1.0`.                                                                                        |
-| Helpers (`newId`, `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 — see [#8](https://github.com/xtrape-com/xtrape-capsule-contracts-node/issues/8). |
+| 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.) |
 
 **Until `v1.0`**, pin to a single minor across CE / Agent SDK / Contracts.
 Breaking changes will be called out in `CHANGELOG.md`.

package/dist/index.cjs

@@ -27,6 +27,8 @@ __export(index_exports, {
   AdminSessionSchema: () => AdminSessionSchema,
   AgentHeartbeatRequestSchema: () => AgentHeartbeatRequestSchema,
   AgentHeartbeatResponseSchema: () => AgentHeartbeatResponseSchema,
+  AgentMode: () => AgentMode,
+  AgentModeSchema: () => AgentModeSchema,
   AgentSchema: () => AgentSchema,
   AgentStatus: () => AgentStatus,
   AgentStatusSchema: () => AgentStatusSchema,
@@ -54,6 +56,7 @@ __export(index_exports, {
   DangerLevelSchema: () => DangerLevelSchema,
   DashboardSummarySchema: () => DashboardSummarySchema,
   ErrorCode: () => ErrorCode,
+  EventMetadataSchema: () => EventMetadataSchema,
   HealthReportInputSchema: () => HealthReportInputSchema,
   HealthReportSchema: () => HealthReportSchema,
   HealthStatus: () => HealthStatus,
@@ -66,6 +69,9 @@ __export(index_exports, {
   ReportCommandResultRequestSchema: () => ReportCommandResultRequestSchema,
   ReportedServiceSchema: () => ReportedServiceSchema,
   RuntimeKindSchema: () => RuntimeKindSchema,
+  ServiceCapabilitySchema: () => ServiceCapabilitySchema,
+  ServiceKind: () => ServiceKind,
+  ServiceKindSchema: () => ServiceKindSchema,
   ServiceReportRequestSchema: () => ServiceReportRequestSchema,
   SystemHealthSchema: () => SystemHealthSchema,
   SystemVersionSchema: () => SystemVersionSchema,
@@ -80,21 +86,20 @@ __export(index_exports, {
   createActionCommandRequestSchema: () => createActionCommandRequestSchema,
   createRegistrationTokenRequestSchema: () => createRegistrationTokenRequestSchema,
   createUserRequestSchema: () => createUserRequestSchema,
+  eventMetadataSchema: () => eventMetadataSchema,
   healthReportInputSchema: () => healthReportInputSchema,
-  idPrefixes: () => idPrefixes,
-  newId: () => newId,
   paginate: () => paginate,
   parseSort: () => parseSort,
   registerAgentRequestSchema: () => registerAgentRequestSchema,
   reportCommandResultRequestSchema: () => reportCommandResultRequestSchema,
   reportedServiceSchema: () => reportedServiceSchema,
   resetUserPasswordRequestSchema: () => resetUserPasswordRequestSchema,
+  serviceCapabilitySchema: () => serviceCapabilitySchema,
   serviceReportRequestSchema: () => serviceReportRequestSchema,
   updateUserRequestSchema: () => updateUserRequestSchema,
   z: () => import_zod.z
 });
 module.exports = __toCommonJS(index_exports);
-var import_nanoid = require("nanoid");
 var import_zod = require("zod");
 var AgentStatus = ["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"];
 var CapsuleServiceStatus = ["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"];
@@ -104,32 +109,16 @@ var DangerLevel = ["LOW", "MEDIUM", "HIGH"];
 var AuditActorType = ["USER", "AGENT", "SYSTEM"];
 var AuditResult = ["SUCCESS", "FAILURE"];
 var TokenStatus = ["ACTIVE", "REVOKED", "EXPIRED", "USED"];
-var ErrorCode = {
-  INTERNAL_ERROR: "INTERNAL_ERROR",
-  VALIDATION_FAILED: "VALIDATION_FAILED",
-  UNAUTHORIZED: "UNAUTHORIZED",
-  FORBIDDEN: "FORBIDDEN",
-  NOT_FOUND: "NOT_FOUND",
-  CONFLICT: "CONFLICT",
-  CSRF_INVALID: "CSRF_INVALID",
-  ACTION_REQUIRES_CONFIRMATION: "ACTION_REQUIRES_CONFIRMATION",
-  COMMAND_EXPIRED: "COMMAND_EXPIRED",
-  TOKEN_REVOKED: "TOKEN_REVOKED",
-  TOKEN_EXPIRED: "TOKEN_EXPIRED",
-  AGENT_REVOKED: "AGENT_REVOKED",
-  AGENT_DISABLED: "AGENT_DISABLED"
-};
-var idPrefixes = ["wks_", "usr_", "agt_", "tok_", "svc_", "hlr_", "cfg_", "act_", "cmd_", "crs_", "aud_"];
-var NANO = (0, import_nanoid.customAlphabet)("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_-", 21);
-function newId(prefix) {
-  return `${prefix}${NANO()}`;
-}
+var AgentMode = ["embedded", "ophub"];
+var ServiceKind = ["business", "infrastructure", "system"];
+var ServiceKindSchema = import_zod.z.enum(ServiceKind);
 var AnyJson = import_zod.z.record(import_zod.z.any());
 var AgentStatusSchema = import_zod.z.enum(AgentStatus);
 var CapsuleServiceStatusSchema = import_zod.z.enum(CapsuleServiceStatus);
 var HealthStatusSchema = import_zod.z.enum(HealthStatus);
 var CommandStatusSchema = import_zod.z.enum(CommandStatus);
 var DangerLevelSchema = import_zod.z.enum(DangerLevel).default("LOW");
+var AgentModeSchema = import_zod.z.enum(AgentMode);
 var UserSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("usr_"), username: import_zod.z.string(), displayName: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string(), updatedAt: import_zod.z.string() });
 var UserRole = import_zod.z.enum(["owner", "operator", "viewer"]);
 var createUserRequestSchema = import_zod.z.object({ username: import_zod.z.string().min(1), password: import_zod.z.string().min(12), displayName: import_zod.z.string().optional(), role: UserRole.default("viewer") });
@@ -138,24 +127,41 @@ var resetUserPasswordRequestSchema = import_zod.z.object({ password: import_zod.
 var AdminLoginRequestSchema = import_zod.z.object({ username: import_zod.z.string().min(1), password: import_zod.z.string().min(1) });
 var adminLoginRequestSchema = AdminLoginRequestSchema;
 var AdminSessionSchema = import_zod.z.object({ user: UserSchema, csrfToken: import_zod.z.string(), expiresAt: import_zod.z.string() });
-var AgentSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("agt_"), code: import_zod.z.string(), name: import_zod.z.string().nullable().optional(), mode: import_zod.z.enum(["embedded", "sidecar", "external"]), runtime: import_zod.z.string().nullable().optional(), status: AgentStatusSchema, lastHeartbeatAt: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string(), updatedAt: import_zod.z.string() });
+var AgentSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("agt_"), code: import_zod.z.string(), name: import_zod.z.string().nullable().optional(), mode: AgentModeSchema, runtime: import_zod.z.string().nullable().optional(), status: AgentStatusSchema, lastHeartbeatAt: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string(), updatedAt: import_zod.z.string() });
 var RegistrationTokenSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("tok_"), name: import_zod.z.string(), status: import_zod.z.enum(TokenStatus), expiresAt: import_zod.z.string().nullable().optional(), usedAt: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string() });
 var CreateRegistrationTokenRequestSchema = import_zod.z.object({ name: import_zod.z.string().default("Default registration token").optional(), expiresInSeconds: import_zod.z.number().int().min(60).optional() });
 var createRegistrationTokenRequestSchema = CreateRegistrationTokenRequestSchema;
 var CreateRegistrationTokenResponseSchema = RegistrationTokenSchema.extend({ rawToken: import_zod.z.string().startsWith("opstage_reg_") });
-var CapsuleManifestSchema = import_zod.z.object({ kind: import_zod.z.literal("CapsuleService"), schemaVersion: import_zod.z.string().default("1.0").optional(), code: import_zod.z.string().min(1), name: import_zod.z.string().min(1), description: import_zod.z.string().optional(), version: import_zod.z.string().min(1), runtime: import_zod.z.enum(["nodejs", "java", "python", "go", "other"]), agentMode: import_zod.z.enum(["embedded", "sidecar", "external"]), capabilities: import_zod.z.array(import_zod.z.string()).optional(), labels: import_zod.z.record(import_zod.z.string()).optional() }).passthrough();
+var ServiceCapabilitySchema = import_zod.z.object({ name: import_zod.z.string().min(1).max(120), label: import_zod.z.string().max(200).optional(), description: import_zod.z.string().max(2e3).optional(), metadata: AnyJson.optional() });
+var serviceCapabilitySchema = ServiceCapabilitySchema;
+var EventMetadataSchema = import_zod.z.object({ name: import_zod.z.string().min(1).max(160), direction: import_zod.z.enum(["publish", "subscribe"]).optional(), schema: AnyJson.optional(), designOnly: import_zod.z.boolean().default(true), metadata: AnyJson.optional() });
+var eventMetadataSchema = EventMetadataSchema;
+var CapsuleManifestSchema = import_zod.z.object({ kind: import_zod.z.literal("CapsuleService"), schemaVersion: import_zod.z.string().default("1.0").optional(), code: import_zod.z.string().min(1), name: import_zod.z.string().min(1), description: import_zod.z.string().optional(), version: import_zod.z.string().min(1), runtime: import_zod.z.enum(["nodejs", "java", "python", "go", "other"]), agentMode: AgentModeSchema, capabilities: import_zod.z.array(import_zod.z.union([import_zod.z.string(), ServiceCapabilitySchema])).optional(), events: import_zod.z.array(EventMetadataSchema).optional(), labels: import_zod.z.record(import_zod.z.string()).optional() }).passthrough();
 var HealthReportInputSchema = import_zod.z.object({ status: HealthStatusSchema, message: import_zod.z.string().optional(), details: AnyJson.optional() });
 var healthReportInputSchema = HealthReportInputSchema;
 var ConfigItemInputSchema = import_zod.z.object({ key: import_zod.z.string(), label: import_zod.z.string().optional(), type: import_zod.z.string(), source: import_zod.z.string().optional(), editable: import_zod.z.boolean().optional(), sensitive: import_zod.z.boolean().optional(), valuePreview: import_zod.z.string().optional(), defaultValue: import_zod.z.string().optional(), secretRef: import_zod.z.string().optional() });
 var configItemInputSchema = ConfigItemInputSchema;
 var ActionDefinitionInputSchema = import_zod.z.object({ name: import_zod.z.string(), label: import_zod.z.string(), description: import_zod.z.string().optional(), dangerLevel: import_zod.z.enum(DangerLevel).default("LOW").optional(), requiresConfirmation: import_zod.z.boolean().optional(), category: import_zod.z.string().optional(), order: import_zod.z.number().int().optional(), inputSchema: AnyJson.optional(), outputSchema: AnyJson.optional(), timeoutSeconds: import_zod.z.number().int().positive().optional() });
 var actionDefinitionInputSchema = ActionDefinitionInputSchema;
-var ReportedServiceSchema = import_zod.z.object({ code: import_zod.z.string().min(1).max(80), name: import_zod.z.string().min(1).max(200), description: import_zod.z.string().max(2e3).optional(), version: import_zod.z.string().max(80).optional(), runtime: import_zod.z.string().optional(), manifest: AnyJson, health: HealthReportInputSchema.optional(), configs: import_zod.z.array(ConfigItemInputSchema).optional(), actions: import_zod.z.array(ActionDefinitionInputSchema).optional() });
+var ReportedServiceSchema = import_zod.z.object({
+  code: import_zod.z.string().min(1).max(80),
+  name: import_zod.z.string().min(1).max(200),
+  description: import_zod.z.string().max(2e3).optional(),
+  version: import_zod.z.string().max(80).optional(),
+  runtime: import_zod.z.string().optional(),
+  manifest: AnyJson,
+  capabilities: import_zod.z.array(ServiceCapabilitySchema).optional(),
+  events: import_zod.z.array(EventMetadataSchema).optional(),
+  health: HealthReportInputSchema.optional(),
+  configs: import_zod.z.array(ConfigItemInputSchema).optional(),
+  actions: import_zod.z.array(ActionDefinitionInputSchema).optional(),
+  serviceKind: ServiceKindSchema.optional()
+});
 var reportedServiceSchema = ReportedServiceSchema;
 var ServiceReportRequestSchema = import_zod.z.object({ services: import_zod.z.array(ReportedServiceSchema).min(1) });
 var serviceReportRequestSchema = ServiceReportRequestSchema;
 var RuntimeKindSchema = import_zod.z.enum(["nodejs", "java", "python", "go", "other"]);
-var RegisterAgentRequestSchema = import_zod.z.object({ registrationToken: import_zod.z.string().startsWith("opstage_reg_"), agent: import_zod.z.object({ code: import_zod.z.string(), name: import_zod.z.string().optional(), mode: import_zod.z.literal("embedded"), runtime: RuntimeKindSchema.optional() }), service: ReportedServiceSchema.optional() });
+var RegisterAgentRequestSchema = import_zod.z.object({ registrationToken: import_zod.z.string().startsWith("opstage_reg_"), agent: import_zod.z.object({ code: import_zod.z.string(), name: import_zod.z.string().optional(), mode: AgentModeSchema.default("embedded"), runtime: RuntimeKindSchema.or(import_zod.z.string()).optional() }), service: ReportedServiceSchema.optional() });
 var registerAgentRequestSchema = RegisterAgentRequestSchema;
 var RegisterAgentResponseSchema = import_zod.z.object({ agentId: import_zod.z.string().startsWith("agt_"), agentToken: import_zod.z.string().startsWith("opstage_agent_"), heartbeatIntervalSeconds: import_zod.z.number().int(), commandPollIntervalSeconds: import_zod.z.number().int() });
 var AgentHeartbeatResponseSchema = import_zod.z.object({ heartbeatIntervalSeconds: import_zod.z.number().int(), commandPollIntervalSeconds: import_zod.z.number().int() });
@@ -211,6 +217,21 @@ function parseSort(value, allowed) {
 function paginate(items, page, pageSize, total) {
   return { data: items, pagination: { page, pageSize, total } };
 }
+var ErrorCode = {
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_FOUND: "NOT_FOUND",
+  CONFLICT: "CONFLICT",
+  CSRF_INVALID: "CSRF_INVALID",
+  ACTION_REQUIRES_CONFIRMATION: "ACTION_REQUIRES_CONFIRMATION",
+  COMMAND_EXPIRED: "COMMAND_EXPIRED",
+  TOKEN_REVOKED: "TOKEN_REVOKED",
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  AGENT_REVOKED: "AGENT_REVOKED",
+  AGENT_DISABLED: "AGENT_DISABLED"
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActionDefinitionInputSchema,
@@ -220,6 +241,8 @@ function paginate(items, page, pageSize, total) {
   AdminSessionSchema,
   AgentHeartbeatRequestSchema,
   AgentHeartbeatResponseSchema,
+  AgentMode,
+  AgentModeSchema,
   AgentSchema,
   AgentStatus,
   AgentStatusSchema,
@@ -247,6 +270,7 @@ function paginate(items, page, pageSize, total) {
   DangerLevelSchema,
   DashboardSummarySchema,
   ErrorCode,
+  EventMetadataSchema,
   HealthReportInputSchema,
   HealthReportSchema,
   HealthStatus,
@@ -259,6 +283,9 @@ function paginate(items, page, pageSize, total) {
   ReportCommandResultRequestSchema,
   ReportedServiceSchema,
   RuntimeKindSchema,
+  ServiceCapabilitySchema,
+  ServiceKind,
+  ServiceKindSchema,
   ServiceReportRequestSchema,
   SystemHealthSchema,
   SystemVersionSchema,
@@ -273,15 +300,15 @@ function paginate(items, page, pageSize, total) {
   createActionCommandRequestSchema,
   createRegistrationTokenRequestSchema,
   createUserRequestSchema,
+  eventMetadataSchema,
   healthReportInputSchema,
-  idPrefixes,
-  newId,
   paginate,
   parseSort,
   registerAgentRequestSchema,
   reportCommandResultRequestSchema,
   reportedServiceSchema,
   resetUserPasswordRequestSchema,
+  serviceCapabilitySchema,
   serviceReportRequestSchema,
   updateUserRequestSchema,
   z