@xtrape/capsule-contracts-node 0.2.0 → 0.4.0

package/dist/src/index.js

@@ -0,0 +1,210 @@
+import { z } from "zod";
+export { z };
+export const AgentStatus = ["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"];
+export const CapsuleServiceStatus = ["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"];
+export const HealthStatus = ["UP", "DEGRADED", "DOWN", "UNKNOWN"];
+export const CommandStatus = ["PENDING", "RUNNING", "SUCCEEDED", "FAILED", "EXPIRED", "CANCELLED"];
+export const DangerLevel = ["LOW", "MEDIUM", "HIGH"];
+export const AuditActorType = ["USER", "AGENT", "SYSTEM"];
+export const AuditResult = ["SUCCESS", "FAILURE"];
+export const TokenStatus = ["ACTIVE", "REVOKED", "EXPIRED", "USED"];
+export const AgentMode = ["embedded", "ophub"];
+export const ServiceKind = ["business", "infrastructure", "system"];
+export const ServiceKindSchema = z.enum(ServiceKind);
+// `newId`, `idPrefixes`, and `IdPrefix` were removed in v0.2 — they were a
+// runtime helper that did not belong in a contracts package, and they
+// produced IDs in a different format than the server's actual `createId`
+// (nanoid 21 here vs. randomBytes(12).base64url() on the backend). Consumers
+// that need to mint IDs locally should wire their own factory; the schemas
+// still accept any string whose prefix is one of `agt_` / `svc_` / `tok_` /
+// etc. via `z.string().startsWith(...)`.
+export const AnyJson = z.record(z.any());
+export const AgentStatusSchema = z.enum(AgentStatus);
+export const CapsuleServiceStatusSchema = z.enum(CapsuleServiceStatus);
+export const HealthStatusSchema = z.enum(HealthStatus);
+export const CommandStatusSchema = z.enum(CommandStatus);
+export const DangerLevelSchema = z.enum(DangerLevel).default("LOW");
+export const AgentModeSchema = z.enum(AgentMode);
+export const UserSchema = z.object({ id: z.string().startsWith("usr_"), username: z.string(), displayName: z.string().nullable().optional(), createdAt: z.string(), updatedAt: z.string() });
+export const UserRole = z.enum(["owner", "operator", "viewer"]);
+export const createUserRequestSchema = z.object({ username: z.string().min(1), password: z.string().min(12), displayName: z.string().optional(), role: UserRole.default("viewer") });
+export const updateUserRequestSchema = z.object({ displayName: z.string().optional(), role: UserRole.optional(), status: z.enum(["ACTIVE", "DISABLED"]).optional() });
+export const resetUserPasswordRequestSchema = z.object({ password: z.string().min(12) });
+export const AdminLoginRequestSchema = z.object({ username: z.string().min(1), password: z.string().min(1) });
+export const adminLoginRequestSchema = AdminLoginRequestSchema;
+export const AdminSessionSchema = z.object({ user: UserSchema, csrfToken: z.string(), expiresAt: z.string() });
+export const AgentSchema = z.object({ id: z.string().startsWith("agt_"), code: z.string(), name: z.string().nullable().optional(), mode: AgentModeSchema, runtime: z.string().nullable().optional(), status: AgentStatusSchema, lastHeartbeatAt: z.string().nullable().optional(), createdAt: z.string(), updatedAt: z.string() });
+export const RegistrationTokenSchema = z.object({ id: z.string().startsWith("tok_"), name: z.string(), status: z.enum(TokenStatus), expiresAt: z.string().nullable().optional(), usedAt: z.string().nullable().optional(), createdAt: z.string() });
+export const CreateRegistrationTokenRequestSchema = z.object({ name: z.string().default("Default registration token").optional(), expiresInSeconds: z.number().int().min(60).optional() });
+export const createRegistrationTokenRequestSchema = CreateRegistrationTokenRequestSchema;
+export const CreateRegistrationTokenResponseSchema = RegistrationTokenSchema.extend({ rawToken: z.string().startsWith("opstage_reg_") });
+export const ServiceCapabilitySchema = z.object({ name: z.string().min(1).max(120), label: z.string().max(200).optional(), description: z.string().max(2000).optional(), metadata: AnyJson.optional() });
+export const serviceCapabilitySchema = ServiceCapabilitySchema;
+export const EventMetadataSchema = z.object({ name: z.string().min(1).max(160), direction: z.enum(["publish", "subscribe"]).optional(), schema: AnyJson.optional(), designOnly: z.boolean().default(true), metadata: AnyJson.optional() });
+export const eventMetadataSchema = EventMetadataSchema;
+export const CapsuleManifestSchema = z.object({ kind: z.literal("CapsuleService"), schemaVersion: z.string().default("1.0").optional(), code: z.string().min(1), name: z.string().min(1), description: z.string().optional(), version: z.string().min(1), runtime: z.enum(["nodejs", "java", "python", "go", "other"]), agentMode: AgentModeSchema, capabilities: z.array(z.union([z.string(), ServiceCapabilitySchema])).optional(), events: z.array(EventMetadataSchema).optional(), labels: z.record(z.string()).optional() }).passthrough();
+export const HealthReportInputSchema = z.object({ status: HealthStatusSchema, message: z.string().optional(), details: AnyJson.optional() });
+export const healthReportInputSchema = HealthReportInputSchema;
+export const ConfigItemInputSchema = z.object({ key: z.string(), label: z.string().optional(), type: z.string(), source: z.string().optional(), editable: z.boolean().optional(), sensitive: z.boolean().optional(), valuePreview: z.string().optional(), defaultValue: z.string().optional(), secretRef: z.string().optional() });
+export const configItemInputSchema = ConfigItemInputSchema;
+export const ActionDefinitionInputSchema = z.object({ name: z.string(), label: z.string(), description: z.string().optional(), dangerLevel: z.enum(DangerLevel).default("LOW").optional(), requiresConfirmation: z.boolean().optional(), category: z.string().optional(), order: z.number().int().optional(), inputSchema: AnyJson.optional(), outputSchema: AnyJson.optional(), timeoutSeconds: z.number().int().positive().optional() });
+export const actionDefinitionInputSchema = ActionDefinitionInputSchema;
+export const ReportedServiceSchema = z.object({
+    code: z.string().min(1).max(80),
+    name: z.string().min(1).max(200),
+    description: z.string().max(2000).optional(),
+    version: z.string().max(80).optional(),
+    runtime: z.string().optional(),
+    manifest: AnyJson,
+    capabilities: z.array(ServiceCapabilitySchema).optional(),
+    events: z.array(EventMetadataSchema).optional(),
+    health: HealthReportInputSchema.optional(),
+    configs: z.array(ConfigItemInputSchema).optional(),
+    actions: z.array(ActionDefinitionInputSchema).optional(),
+    serviceKind: ServiceKindSchema.optional(),
+});
+export const reportedServiceSchema = ReportedServiceSchema;
+export const ServiceReportRequestSchema = z.object({ services: z.array(ReportedServiceSchema).min(1) });
+export const serviceReportRequestSchema = ServiceReportRequestSchema;
+export const RuntimeKindSchema = z.enum(["nodejs", "java", "python", "go", "other"]);
+export const RegisterAgentRequestSchema = z.object({ registrationToken: z.string().startsWith("opstage_reg_"), agent: z.object({ code: z.string(), name: z.string().optional(), mode: AgentModeSchema.default("embedded"), runtime: RuntimeKindSchema.or(z.string()).optional() }), service: ReportedServiceSchema.optional() });
+export const registerAgentRequestSchema = RegisterAgentRequestSchema;
+export const RegisterAgentResponseSchema = z.object({ agentId: z.string().startsWith("agt_"), agentToken: z.string().startsWith("opstage_agent_"), heartbeatIntervalSeconds: z.number().int(), commandPollIntervalSeconds: z.number().int() });
+export const AgentHeartbeatResponseSchema = z.object({ heartbeatIntervalSeconds: z.number().int(), commandPollIntervalSeconds: z.number().int() });
+export const AgentHeartbeatRequestSchema = z.object({ serviceId: z.string().startsWith("svc_").optional(), health: HealthReportInputSchema.optional() });
+export const agentHeartbeatRequestSchema = AgentHeartbeatRequestSchema;
+export const CapsuleServiceSchema = z.object({ id: z.string().startsWith("svc_"), agentId: z.string().startsWith("agt_").optional(), code: z.string(), name: z.string(), description: z.string().nullable().optional(), version: z.string().nullable().optional(), runtime: z.string().nullable().optional(), status: CapsuleServiceStatusSchema, healthStatus: HealthStatusSchema.optional(), lastReportedAt: z.string().nullable().optional(), lastHealthAt: z.string().nullable().optional(), createdAt: z.string(), updatedAt: z.string() });
+export const HealthReportSchema = z.object({ id: z.string().startsWith("hlr_"), serviceId: z.string().startsWith("svc_"), agentId: z.string().startsWith("agt_").optional(), status: HealthStatusSchema, message: z.string().nullable().optional(), details: AnyJson.optional(), reportedAt: z.string() });
+export const ConfigItemSchema = z.object({ id: z.string().startsWith("cfg_"), serviceId: z.string().startsWith("svc_"), key: z.string(), label: z.string().nullable().optional(), type: z.string(), source: z.string().nullable().optional(), editable: z.boolean().default(false), sensitive: z.boolean(), valuePreview: z.string().nullable().optional(), defaultValue: z.string().nullable().optional(), secretRef: z.string().nullable().optional() });
+export const ActionDefinitionSchema = z.object({ id: z.string().startsWith("act_"), serviceId: z.string().startsWith("svc_"), name: z.string(), label: z.string(), description: z.string().nullable().optional(), dangerLevel: z.enum(DangerLevel), requiresConfirmation: z.boolean(), category: z.string().optional(), order: z.number().int().optional(), inputSchema: AnyJson.optional(), outputSchema: AnyJson.optional(), timeoutSeconds: z.number().int().optional() });
+export const CapsuleServiceDetailSchema = CapsuleServiceSchema.extend({ manifest: AnyJson.optional(), health: HealthReportSchema.nullable().optional(), configs: z.array(ConfigItemSchema).optional(), actions: z.array(ActionDefinitionSchema).optional() });
+/**
+ * Shape returned by an Agent's action `prepare` handler when responding to an
+ * `ACTION_PREPARE` command. Used by the SDK as the contract between
+ * `prepare()` callbacks and the backend; the backend forwards it to the UI as
+ * the `data` field of the prepare command result.
+ */
+export const ActionPrepareResultSchema = z.object({
+    action: AnyJson.optional(),
+    inputSchema: AnyJson.optional(),
+    initialPayload: AnyJson.optional(),
+    currentState: AnyJson.optional(),
+});
+export const actionPrepareResultSchema = ActionPrepareResultSchema;
+// v0.4 Capsule Bus experimental contracts. These schemas intentionally model
+// a small Opstage-governed event-to-command surface, not a general message
+// broker or workflow DSL. Names and compatibility may change before v1.0.
+export const CapsuleBusExperimentalSchema = z.literal("v0.4-experimental");
+export const BusRouteStatus = ["ENABLED", "DISABLED", "DRY_RUN"];
+export const BusRouteStatusSchema = z.enum(BusRouteStatus);
+export const BusEventEnvelopeSchema = z.object({
+    id: z.string().startsWith("bev_").optional(),
+    experimental: CapsuleBusExperimentalSchema.default("v0.4-experimental"),
+    eventType: z.string().min(1).max(160),
+    sourceServiceCode: z.string().min(1).max(80),
+    sourceServiceId: z.string().startsWith("svc_").optional(),
+    occurredAt: z.string().datetime().optional(),
+    correlationId: z.string().min(1).max(160).optional(),
+    causationId: z.string().min(1).max(160).optional(),
+    payload: AnyJson.default({}).optional(),
+    metadata: AnyJson.default({}).optional(),
+});
+export const PublishBusEventRequestSchema = BusEventEnvelopeSchema.omit({ id: true }).extend({
+    routePolicy: z.object({ dryRun: z.boolean().optional() }).optional(),
+});
+export const BusRouteRuleSchema = z.object({
+    id: z.string().startsWith("brt_").optional(),
+    name: z.string().min(1).max(160),
+    description: z.string().max(1000).optional(),
+    status: BusRouteStatusSchema.optional().default("DISABLED"),
+    match: z.object({
+        eventType: z.string().min(1).max(160),
+        sourceServiceCode: z.string().min(1).max(80).optional(),
+    }),
+    target: z.object({
+        serviceCode: z.string().min(1).max(80),
+        actionName: z.string().min(1).max(128),
+    }),
+    inputMapping: AnyJson.default({}).optional(),
+    metadata: AnyJson.default({}).optional(),
+});
+export const CreateBusRouteRuleRequestSchema = BusRouteRuleSchema.omit({ id: true });
+export const BusCommandRequestSchema = z.object({
+    commandId: z.string().startsWith("cmd_").optional(),
+    commandType: z.literal("ACTION_EXECUTE").default("ACTION_EXECUTE"),
+    targetService: z.string().min(1).max(80),
+    actionName: z.string().min(1).max(128),
+    sourceEventId: z.string().startsWith("bev_").optional(),
+    payload: AnyJson.default({}).optional(),
+    metadata: z.object({
+        routingRuleId: z.string().startsWith("brt_").optional(),
+        correlationId: z.string().min(1).max(160).optional(),
+    }).catchall(z.any()).optional(),
+});
+export const busCommandRequestSchema = BusCommandRequestSchema;
+export const BusRoutingRuleSchema = BusRouteRuleSchema;
+export const busRoutingRuleSchema = BusRoutingRuleSchema;
+export const BusRoutedCommandSchema = z.object({
+    routeId: z.string().startsWith("brt_"),
+    commandId: z.string().startsWith("cmd_").optional(),
+    dryRun: z.boolean(),
+    targetServiceCode: z.string(),
+    actionName: z.string(),
+    status: z.enum(["CREATED", "DRY_RUN", "SKIPPED", "FAILED"]),
+    errorCode: z.string().optional(),
+    errorMessage: z.string().optional(),
+});
+export const PublishBusEventResponseSchema = z.object({
+    eventId: z.string().startsWith("bev_"),
+    experimental: CapsuleBusExperimentalSchema,
+    routedCommands: z.array(BusRoutedCommandSchema),
+});
+export const BusEventRecordSchema = BusEventEnvelopeSchema.extend({
+    id: z.string().startsWith("bev_"),
+    agentId: z.string().startsWith("agt_"),
+    acceptedAt: z.string(),
+    routeCount: z.number().int(),
+});
+export const BusErrorCode = {
+    CAPSULE_BUS_DISABLED: "CAPSULE_BUS_DISABLED",
+    BUS_RATE_LIMITED: "BUS_RATE_LIMITED",
+    BUS_DEPTH_EXCEEDED: "BUS_DEPTH_EXCEEDED",
+};
+export const publishBusEventRequestSchema = PublishBusEventRequestSchema;
+export const publishBusEventResponseSchema = PublishBusEventResponseSchema;
+export const busEventEnvelopeSchema = BusEventEnvelopeSchema;
+export const busRouteRuleSchema = BusRouteRuleSchema;
+export const createBusRouteRuleRequestSchema = CreateBusRouteRuleRequestSchema;
+export const CreateActionCommandRequestSchema = z.object({ payload: AnyJson.optional(), confirmation: z.boolean().optional() });
+export const createActionCommandRequestSchema = CreateActionCommandRequestSchema;
+export const CommandTypeSchema = z.enum(["ACTION_PREPARE", "ACTION_EXECUTE"]);
+export const CommandSchema = z.object({ id: z.string().startsWith("cmd_"), agentId: z.string().startsWith("agt_"), serviceId: z.string().startsWith("svc_"), type: CommandTypeSchema, actionName: z.string(), status: CommandStatusSchema, payload: AnyJson.optional(), createdByUserId: z.string().startsWith("usr_").nullable().optional(), createdAt: z.string(), startedAt: z.string().nullable().optional(), completedAt: z.string().nullable().optional(), expiresAt: z.string().nullable().optional() });
+export const ReportCommandResultRequestSchema = z.object({ success: z.boolean(), message: z.string().optional(), data: AnyJson.optional(), error: AnyJson.optional(), startedAt: z.string().optional(), finishedAt: z.string().optional() });
+export const reportCommandResultRequestSchema = ReportCommandResultRequestSchema;
+export const CommandResultSchema = z.object({ id: z.string().startsWith("crs_"), commandId: z.string().startsWith("cmd_"), success: z.boolean(), message: z.string().nullable().optional(), data: AnyJson.optional(), error: AnyJson.optional(), reportedAt: z.string() });
+export const CommandDetailSchema = CommandSchema.extend({ result: CommandResultSchema.nullable().optional() });
+export const AuditEventSchema = z.object({ id: z.string().startsWith("aud_"), actorType: z.enum(AuditActorType), actorId: z.string().nullable().optional(), action: z.string(), targetType: z.string().nullable().optional(), targetId: z.string().nullable().optional(), result: z.enum(AuditResult), message: z.string().nullable().optional(), metadata: AnyJson.optional(), createdAt: z.string() });
+export const DashboardSummarySchema = z.object({ agentCounts: z.record(z.number().int()), serviceCounts: z.record(z.number().int()), commandCounts: z.record(z.number().int()), recentCommands: z.array(CommandSchema).optional(), recentAuditEvents: z.array(AuditEventSchema).optional() });
+export const SystemHealthSchema = z.object({ status: z.enum(["UP", "DEGRADED", "DOWN"]), timestamp: z.string(), version: z.string(), edition: z.literal("ce"), database: z.object({ status: z.enum(["UP", "DEGRADED", "DOWN"]), kind: z.enum(["sqlite", "postgres", "mysql"]).optional(), latencyMs: z.number().int().optional() }), uptimeSeconds: z.number().int().optional() });
+export const SystemVersionSchema = z.object({ version: z.string(), edition: z.literal("ce"), commit: z.string().optional(), buildTime: z.string().optional() });
+export const ListQueryBase = z.object({ page: z.coerce.number().int().min(1).default(1), pageSize: z.coerce.number().int().min(1).max(100).default(20), sort: z.string().optional() });
+export class HttpError extends Error {
+    httpStatus;
+    code;
+    publicMessage;
+    details;
+    constructor(httpStatus, code, publicMessage, details) {
+        super(publicMessage);
+        this.httpStatus = httpStatus;
+        this.code = code;
+        this.publicMessage = publicMessage;
+        this.details = details;
+    }
+}
+export function parseSort(value, allowed) { if (!value)
+    return []; return value.split(",").filter(Boolean).map(raw => { const desc = raw.startsWith("-"); const field = desc ? raw.slice(1) : raw; if (!allowed.includes(field))
+    throw new HttpError(422, "VALIDATION_FAILED", `Unknown sort field: ${field}`); return { field, direction: desc ? "desc" : "asc" }; }); }
+export function paginate(items, page, pageSize, total) { return { data: items, pagination: { page, pageSize, total } }; }
+export const 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"
+};

package/dist/tests/bus.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/bus.spec.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { BusEventEnvelopeSchema, CreateBusRouteRuleRequestSchema, PublishBusEventResponseSchema, BusCommandRequestSchema, BusRoutingRuleSchema, } from "../src/index";
+describe("v0.4 experimental Capsule Bus contracts", () => {
+    it("validates a minimal event envelope", () => {
+        const parsed = BusEventEnvelopeSchema.parse({
+            eventType: "demo.item.created",
+            sourceServiceCode: "demo-worker",
+            payload: { itemId: "item_1" },
+        });
+        expect(parsed.experimental).toBe("v0.4-experimental");
+    });
+    it("validates an event-to-command route rule", () => {
+        const parsed = CreateBusRouteRuleRequestSchema.parse({
+            name: "Notify on item creation",
+            status: "DRY_RUN",
+            match: { eventType: "demo.item.created", sourceServiceCode: "demo-worker" },
+            target: { serviceCode: "demo-notifier", actionName: "notify" },
+        });
+        expect(parsed.status).toBe("DRY_RUN");
+    });
+    it("rejects non-experimental event envelopes", () => {
+        expect(() => BusEventEnvelopeSchema.parse({
+            experimental: "stable",
+            eventType: "demo.item.created",
+            sourceServiceCode: "demo-worker",
+        })).toThrow();
+    });
+    it("validates command requests linked to source events", () => {
+        const parsed = BusCommandRequestSchema.parse({
+            targetService: "demo-notifier",
+            actionName: "notify",
+            sourceEventId: "bev_123",
+            payload: { itemId: "item-1" },
+            metadata: { routingRuleId: "brt_123", correlationId: "corr-1" },
+        });
+        expect(parsed.commandType).toBe("ACTION_EXECUTE");
+    });
+    it("keeps the implementation-plan BusRoutingRule alias", () => {
+        expect(BusRoutingRuleSchema.parse({
+            name: "Alias route",
+            match: { eventType: "demo.item.created" },
+            target: { serviceCode: "demo-worker", actionName: "notify" },
+        }).status).toBe("DISABLED");
+    });
+    it("validates routed command responses", () => {
+        expect(PublishBusEventResponseSchema.parse({
+            eventId: "bev_123",
+            experimental: "v0.4-experimental",
+            routedCommands: [{ routeId: "brt_123", commandId: "cmd_123", dryRun: false, targetServiceCode: "svc", actionName: "notify", status: "CREATED" }],
+        }).routedCommands).toHaveLength(1);
+    });
+});

package/dist/tests/schema-validation.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/schema-validation.spec.js

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+import { ActionDefinitionInputSchema, AgentModeSchema, AgentHeartbeatRequestSchema, CapsuleManifestSchema, CommandResultSchema, ConfigItemInputSchema, ErrorCode, HealthReportInputSchema, RegisterAgentRequestSchema, RegisterAgentResponseSchema, ReportCommandResultRequestSchema, ServiceReportRequestSchema, eventMetadataSchema, paginate, parseSort, serviceCapabilitySchema, } from "../src/index";
+describe("schema validation", () => {
+    it("accepts a valid ophub agent registration request", () => {
+        const parsed = RegisterAgentRequestSchema.parse({
+            registrationToken: "opstage_reg_public_review_ophub",
+            agent: {
+                code: "demo-agent",
+                name: "Demo Agent",
+                mode: "ophub",
+                runtime: "nodejs",
+            },
+        });
+        expect(parsed.agent.mode).toBe("ophub");
+    });
+    it("accepts a OpHub registration and multi-service report metadata", () => {
+        const parsed = RegisterAgentRequestSchema.parse({
+            registrationToken: "opstage_reg_public_review_ophub",
+            agent: {
+                code: "ophub-a",
+                name: "OpHub A",
+                mode: "ophub",
+                runtime: "go",
+            },
+        });
+        expect(AgentModeSchema.parse("ophub")).toBe("ophub");
+        expect(parsed.agent.mode).toBe("ophub");
+        expect(() => ServiceReportRequestSchema.parse({
+            services: [
+                {
+                    code: "svc-one",
+                    name: "Service One",
+                    manifest: {
+                        kind: "CapsuleService",
+                        code: "svc-one",
+                        name: "Service One",
+                        version: "0.3.0",
+                        runtime: "nodejs",
+                        agentMode: "ophub",
+                        capabilities: [{ name: "accounts.sync", label: "Account sync" }],
+                        events: [{ name: "account.synced", direction: "publish", designOnly: true }],
+                    },
+                    capabilities: [{ name: "accounts.sync" }],
+                    events: [{ name: "account.synced", direction: "publish" }],
+                },
+                {
+                    code: "svc-two",
+                    name: "Service Two",
+                    manifest: {
+                        kind: "CapsuleService",
+                        code: "svc-two",
+                        name: "Service Two",
+                        version: "0.3.0",
+                        runtime: "nodejs",
+                        agentMode: "ophub",
+                    },
+                },
+            ],
+        })).not.toThrow();
+    });
+    it("rejects unsupported health and effective service statuses", () => {
+        expect(() => HealthReportInputSchema.parse({ status: "HEALTHY" })).toThrow();
+        expect(() => HealthReportInputSchema.parse({ status: "OFFLINE" })).toThrow();
+        expect(() => HealthReportInputSchema.parse({ status: "UP" })).not.toThrow();
+    });
+    it("rejects invalid registration credentials", () => {
+        expect(() => RegisterAgentResponseSchema.parse({
+            agentId: "svc_wrong",
+            agentToken: "opstage_agent_token",
+            heartbeatIntervalSeconds: 30,
+            commandPollIntervalSeconds: 5,
+        })).toThrow();
+        expect(() => RegisterAgentResponseSchema.parse({
+            agentId: "agt_123",
+            agentToken: "plain-token",
+            heartbeatIntervalSeconds: 30,
+            commandPollIntervalSeconds: 5,
+        })).toThrow();
+    });
+    it("accepts optional manifest and action fields", () => {
+        const manifest = CapsuleManifestSchema.parse({
+            kind: "CapsuleService",
+            code: "demo-service",
+            name: "Demo Service",
+            version: "0.1.0",
+            runtime: "nodejs",
+            agentMode: "embedded",
+        });
+        const action = ActionDefinitionInputSchema.parse({
+            name: "sync",
+            label: "Sync",
+        });
+        expect(manifest.schemaVersion).toBeUndefined();
+        expect(action.dangerLevel).toBeUndefined();
+    });
+    it("validates capability and event metadata schemas", () => {
+        expect(serviceCapabilitySchema.parse({ name: "backup.create", metadata: { target: "sqlite" } }).name).toBe("backup.create");
+        expect(eventMetadataSchema.parse({ name: "backup.created", direction: "publish" })).toMatchObject({
+            direction: "publish",
+            designOnly: true,
+        });
+    });
+    it("validates service reports, heartbeats, and command results", () => {
+        expect(() => ServiceReportRequestSchema.parse({
+            services: [
+                {
+                    code: "demo-service",
+                    name: "Demo Service",
+                    runtime: "nodejs",
+                    manifest: {},
+                },
+            ],
+        })).not.toThrow();
+        expect(() => ServiceReportRequestSchema.parse({ services: [] })).toThrow();
+        expect(() => AgentHeartbeatRequestSchema.parse({ serviceId: "svc_123", health: { status: "DEGRADED" } })).not.toThrow();
+        expect(() => AgentHeartbeatRequestSchema.parse({ serviceId: "agt_wrong" })).toThrow();
+        expect(() => ReportCommandResultRequestSchema.parse({ success: true, data: { refreshed: true } })).not.toThrow();
+    });
+    it("validates config item inputs and persisted command results", () => {
+        expect(() => ConfigItemInputSchema.parse({
+            key: "apiKey",
+            label: "API key",
+            type: "secret",
+            sensitive: true,
+            secretRef: "secret://api-key",
+        })).not.toThrow();
+        expect(() => CommandResultSchema.parse({
+            id: "crs_123",
+            commandId: "cmd_123",
+            success: false,
+            message: "failed",
+            error: { code: "ACTION_FAILED" },
+            reportedAt: "2026-05-06T00:00:00.000Z",
+        })).not.toThrow();
+        expect(() => CommandResultSchema.parse({
+            id: "cmd_wrong",
+            commandId: "cmd_123",
+            success: true,
+            reportedAt: "2026-05-06T00:00:00.000Z",
+        })).toThrow();
+    });
+    it("exports public error codes and pagination helpers", () => {
+        expect(ErrorCode.VALIDATION_FAILED).toBe("VALIDATION_FAILED");
+        expect(ErrorCode.ACTION_REQUIRES_CONFIRMATION).toBe("ACTION_REQUIRES_CONFIRMATION");
+        expect(parseSort("-createdAt,name", ["createdAt", "name"])).toEqual([
+            { field: "createdAt", direction: "desc" },
+            { field: "name", direction: "asc" },
+        ]);
+        expect(() => parseSort("unknown", ["createdAt"])).toThrow("Unknown sort field: unknown");
+        expect(paginate([{ id: "svc_1" }], 1, 20, 1)).toEqual({
+            data: [{ id: "svc_1" }],
+            pagination: { page: 1, pageSize: 20, total: 1 },
+        });
+    });
+});

package/dist/tests/schema.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/schema.spec.js

@@ -0,0 +1,223 @@
+import { describe, expect, it } from "vitest";
+import { AgentStatus, CapsuleServiceStatus, ErrorCode, AgentStatusSchema, CapsuleServiceStatusSchema, HealthStatusSchema, CommandStatusSchema, DangerLevelSchema, CapsuleManifestSchema, healthReportInputSchema, configItemInputSchema, actionDefinitionInputSchema, reportedServiceSchema, serviceReportRequestSchema, registerAgentRequestSchema, RegisterAgentResponseSchema, AgentHeartbeatResponseSchema, agentHeartbeatRequestSchema, ConfigItemSchema, ActionDefinitionSchema, CommandSchema, reportCommandResultRequestSchema, CommandResultSchema, ListQueryBase, parseSort, paginate, HttpError } from "../src/index";
+describe("Schema Validation", () => {
+    // Test enum schemas
+    it("validates AgentStatusSchema", () => {
+        expect(AgentStatusSchema.parse("ONLINE")).toBe("ONLINE");
+        expect(() => AgentStatusSchema.parse("INVALID")).toThrow();
+    });
+    it("validates CapsuleServiceStatusSchema", () => {
+        expect(CapsuleServiceStatusSchema.parse("HEALTHY")).toBe("HEALTHY");
+        expect(() => CapsuleServiceStatusSchema.parse("INVALID")).toThrow();
+    });
+    it("validates HealthStatusSchema", () => {
+        expect(HealthStatusSchema.parse("UP")).toBe("UP");
+        expect(() => HealthStatusSchema.parse("INVALID")).toThrow();
+    });
+    it("validates CommandStatusSchema", () => {
+        expect(CommandStatusSchema.parse("SUCCEEDED")).toBe("SUCCEEDED");
+        expect(() => CommandStatusSchema.parse("INVALID")).toThrow();
+    });
+    it("validates DangerLevelSchema", () => {
+        expect(DangerLevelSchema.parse("HIGH")).toBe("HIGH");
+        expect(DangerLevelSchema.parse(undefined)).toBe("LOW"); // default
+    });
+    // Test Agent registration schemas
+    it("validates RegisterAgentRequestSchema", () => {
+        const validRequest = {
+            registrationToken: "opstage_reg_abc123",
+            agent: {
+                code: "test-agent",
+                mode: "embedded"
+            }
+        };
+        expect(registerAgentRequestSchema.parse(validRequest)).toEqual(validRequest);
+        expect(() => registerAgentRequestSchema.parse({
+            registrationToken: "invalid_token",
+            agent: { code: "test", mode: "embedded" }
+        })).toThrow();
+    });
+    it("validates RegisterAgentResponseSchema", () => {
+        const validResponse = {
+            agentId: "agt_abc123def456",
+            agentToken: "opstage_agent_xyz789",
+            heartbeatIntervalSeconds: 30,
+            commandPollIntervalSeconds: 10
+        };
+        expect(RegisterAgentResponseSchema.parse(validResponse)).toEqual(validResponse);
+    });
+    // Test Service report schemas
+    it("validates CapsuleManifestSchema", () => {
+        const validManifest = {
+            kind: "CapsuleService",
+            code: "test-service",
+            name: "Test Service",
+            version: "1.0.0",
+            runtime: "nodejs",
+            agentMode: "embedded"
+        };
+        expect(CapsuleManifestSchema.parse(validManifest)).toEqual(validManifest);
+    });
+    it("validates ReportedServiceSchema", () => {
+        const validService = {
+            code: "test-service",
+            name: "Test Service",
+            manifest: {}
+        };
+        expect(reportedServiceSchema.parse(validService)).toEqual(validService);
+    });
+    it("validates ServiceReportRequestSchema", () => {
+        const validRequest = {
+            services: [{
+                    code: "test-service",
+                    name: "Test Service",
+                    manifest: {}
+                }]
+        };
+        expect(serviceReportRequestSchema.parse(validRequest)).toEqual(validRequest);
+    });
+    // Test Health report schemas
+    it("validates HealthReportInputSchema", () => {
+        const validHealth = {
+            status: "UP",
+            message: "All good"
+        };
+        expect(healthReportInputSchema.parse(validHealth)).toEqual(validHealth);
+    });
+    it("validates AgentHeartbeatRequestSchema", () => {
+        const validHeartbeat = {
+            health: {
+                status: "UP"
+            }
+        };
+        expect(agentHeartbeatRequestSchema.parse(validHeartbeat)).toEqual(validHeartbeat);
+    });
+    it("validates AgentHeartbeatResponseSchema", () => {
+        const validResponse = {
+            heartbeatIntervalSeconds: 30,
+            commandPollIntervalSeconds: 10
+        };
+        expect(AgentHeartbeatResponseSchema.parse(validResponse)).toEqual(validResponse);
+    });
+    // Test Config item schemas
+    it("validates ConfigItemInputSchema", () => {
+        const validConfig = {
+            key: "database_url",
+            type: "string",
+            sensitive: true
+        };
+        expect(configItemInputSchema.parse(validConfig)).toEqual(validConfig);
+    });
+    it("validates ConfigItemSchema", () => {
+        const validConfig = {
+            id: "cfg_abc123def456",
+            serviceId: "svc_abc123def456",
+            key: "database_url",
+            type: "string",
+            sensitive: true,
+            editable: false // default value from schema
+        };
+        expect(ConfigItemSchema.parse(validConfig)).toEqual(validConfig);
+    });
+    // Test Action definition schemas
+    it("validates ActionDefinitionInputSchema", () => {
+        const validAction = {
+            name: "restart",
+            label: "Restart Service",
+            dangerLevel: "MEDIUM"
+        };
+        expect(actionDefinitionInputSchema.parse(validAction)).toEqual(validAction);
+    });
+    it("validates ActionDefinitionSchema", () => {
+        const validAction = {
+            id: "act_abc123def456",
+            serviceId: "svc_abc123def456",
+            name: "restart",
+            label: "Restart Service",
+            dangerLevel: "MEDIUM",
+            requiresConfirmation: false
+        };
+        expect(ActionDefinitionSchema.parse(validAction)).toEqual(validAction);
+    });
+    // Test Command schemas
+    it("validates CommandSchema", () => {
+        const validCommand = {
+            id: "cmd_abc123def456",
+            agentId: "agt_abc123def456",
+            serviceId: "svc_abc123def456",
+            type: "ACTION_EXECUTE",
+            actionName: "restart",
+            status: "PENDING",
+            createdAt: "2026-05-06T13:22:30Z"
+        };
+        expect(CommandSchema.parse(validCommand)).toEqual(validCommand);
+    });
+    it("validates ReportCommandResultRequestSchema", () => {
+        const validResult = {
+            success: true,
+            message: "Command completed successfully"
+        };
+        expect(reportCommandResultRequestSchema.parse(validResult)).toEqual(validResult);
+    });
+    it("validates CommandResultSchema", () => {
+        const validResult = {
+            id: "crs_abc123def456",
+            commandId: "cmd_abc123def456",
+            success: true,
+            reportedAt: "2026-05-06T13:22:30Z"
+        };
+        expect(CommandResultSchema.parse(validResult)).toEqual(validResult);
+    });
+    // Test Error codes
+    it("exports ErrorCode correctly", () => {
+        expect(ErrorCode.INTERNAL_ERROR).toBe("INTERNAL_ERROR");
+        expect(ErrorCode.UNAUTHORIZED).toBe("UNAUTHORIZED");
+        expect(Object.values(ErrorCode)).toContain("VALIDATION_FAILED");
+    });
+    // Test pagination helpers
+    it("ListQueryBase validates pagination", () => {
+        expect(ListQueryBase.parse({})).toEqual({ page: 1, pageSize: 20 });
+        expect(ListQueryBase.parse({ page: 2, pageSize: 50 })).toEqual({ page: 2, pageSize: 50 });
+        expect(() => ListQueryBase.parse({ pageSize: 200 })).toThrow(); // max 100
+        expect(() => ListQueryBase.parse({ page: 0 })).toThrow(); // min 1
+    });
+    it("parseSort handles sort fields", () => {
+        const allowedFields = ["name", "createdAt"];
+        expect(parseSort("name,-createdAt", allowedFields)).toEqual([
+            { field: "name", direction: "asc" },
+            { field: "createdAt", direction: "desc" }
+        ]);
+        expect(() => parseSort("invalidField", allowedFields)).toThrow(HttpError);
+    });
+    it("paginate creates pagination object", () => {
+        const items = [1, 2, 3];
+        const result = paginate(items, 1, 10, 3);
+        expect(result).toEqual({
+            data: items,
+            pagination: { page: 1, pageSize: 10, total: 3 }
+        });
+    });
+    // Test that README examples match actual exports
+    it("README examples should match actual exports", () => {
+        // This ensures we don't have drift between documentation and implementation
+        expect(AgentStatus).toBeDefined();
+        expect(CapsuleServiceStatus).toBeDefined();
+        expect(ErrorCode).toBeDefined();
+    });
+    // Test that schemas don't over-constrain future draft fields
+    it("schemas allow additional fields via passthrough", () => {
+        const manifestWithExtra = {
+            kind: "CapsuleService",
+            code: "test",
+            name: "Test",
+            version: "1.0.0",
+            runtime: "nodejs",
+            agentMode: "embedded",
+            // Additional fields that might be added in future
+            experimentalFeature: true,
+            metadata: { custom: "value" }
+        };
+        // Should not throw - passthrough allows extra fields
+        expect(CapsuleManifestSchema.parse(manifestWithExtra)).toEqual(manifestWithExtra);
+    });
+});