@xtrape/capsule-agent-node 0.2.0 → 0.4.0

package/README.md

@@ -6,10 +6,7 @@
 [![Status: Public Review](https://img.shields.io/badge/status-Public%20Review-orange.svg)](https://xtrape-com.github.io/xtrape-capsule-site/)
 [![Docs](https://img.shields.io/badge/docs-xtrape--capsule--site-blue.svg)](https://xtrape-com.github.io/xtrape-capsule-site/agents/node-embedded-agent)
 
-`@xtrape/capsule-agent-node` embeds an Opstage Agent inside a Node.js service.
-The Agent registers with Opstage CE, persists its Agent token, sends heartbeats,
-reports service metadata, exposes configs and health, and polls Commands for
-operator-triggered Actions.
+`@xtrape/capsule-agent-node` supports the stable Node.js Embedded Agent SDK path for single Capsule Services. For multi-service OpHub functionality, use OpHub (Go runtime).
 
 > **Package status:** Xtrape Capsule is currently in **Public Review** before
 > the `v0.1.0 Public Preview` release. This package is published under the
@@ -26,6 +23,10 @@ pnpm add @xtrape/capsule-agent-node@public-review
 
 The current Public Review version may change before `v0.1.0`.
 
+During v0.3 development, this repository may use a local workspace, GitHub
+branch dependency, or `0.3.0-rc.x` package for
+`@xtrape/capsule-contracts-node` until the final `0.3.0` package is published.
+
 For this repository itself:
 
 ```bash
@@ -457,3 +458,24 @@ safety guidance.
 
 Apache-2.0. "Xtrape", "Xtrape Capsule", and "Opstage" are trademarks of their
 respective owners; the open-source license does not grant trademark rights.
+
+## v0.4 Experimental Capsule Bus Hook
+
+The SDK exposes a minimal experimental publish hook into CE's built-in SQLite-backed in-process event-to-command router:
+
+```ts
+await agent.publishBusEvent({
+  eventType: "demo.item.created",
+  payload: { itemId: "item-1" },
+});
+```
+
+The hook posts to Opstage CE as the registered embedded agent and defaults `sourceServiceCode` to the configured service code.
+
+Typed errors for Bus failure modes:
+
+- `BusDisabledError` — `CAPSULE_BUS_DISABLED` (404)
+- `BusRateLimitedError` — `BUS_RATE_LIMITED` (429)
+- `BusDepthExceededError` — `BUS_DEPTH_EXCEEDED` (422)
+
+Capsule Bus is experimental in v0.4: not a standalone Bus Server, external broker, workflow engine, or service mesh API.

package/dist/index.cjs

@@ -23,6 +23,9 @@ __export(index_exports, {
   AgentApiClient: () => AgentApiClient,
   AgentApiError: () => AgentApiError,
   AgentAuthError: () => AgentAuthError,
+  BusDepthExceededError: () => BusDepthExceededError,
+  BusDisabledError: () => BusDisabledError,
+  BusRateLimitedError: () => BusRateLimitedError,
   CapsuleAgent: () => CapsuleAgent,
   FileTokenStore: () => FileTokenStore,
   NetworkError: () => NetworkError,
@@ -64,9 +67,30 @@ var NetworkError = class extends AgentApiError {
     }
   }
 };
+var BusDisabledError = class extends AgentApiError {
+  constructor(message, status, body) {
+    super(status, message, body, "CAPSULE_BUS_DISABLED");
+    this.name = "BusDisabledError";
+  }
+};
+var BusRateLimitedError = class extends AgentApiError {
+  constructor(message, status, body) {
+    super(status, message, body, "BUS_RATE_LIMITED");
+    this.name = "BusRateLimitedError";
+  }
+};
+var BusDepthExceededError = class extends AgentApiError {
+  constructor(message, status, body) {
+    super(status, message, body, "BUS_DEPTH_EXCEEDED");
+    this.name = "BusDepthExceededError";
+  }
+};
 function classifyAgentApiError(status, message, body, code, path) {
   if (status === 401 && path.endsWith("/register")) return new RegistrationError(message, status, body, code);
   if (status === 401 || status === 403) return new AgentAuthError(message, status, body, code);
+  if (code === "CAPSULE_BUS_DISABLED") return new BusDisabledError(message, status, body);
+  if (code === "BUS_RATE_LIMITED") return new BusRateLimitedError(message, status, body);
+  if (code === "BUS_DEPTH_EXCEEDED") return new BusDepthExceededError(message, status, body);
   return new AgentApiError(status, message, body, code);
 }
 
@@ -118,6 +142,10 @@ var AgentApiClient = class {
   reportResult(agentId, token, commandId, req) {
     return this.request(`/api/agents/${agentId}/commands/${commandId}/result`, { method: "POST", token, body: JSON.stringify(req) });
   }
+  /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+  publishBusEvent(agentId, token, req) {
+    return this.request(`/api/agents/${agentId}/bus/events`, { method: "POST", token, body: JSON.stringify({ ...req, experimental: req.experimental ?? "v0.4-experimental" }) });
+  }
 };
 
 // src/token-store/file-token-store.ts
@@ -272,6 +300,14 @@ var CapsuleAgent = class {
   async runHealth() {
     return this.healthProvider();
   }
+  /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+  async publishBusEvent(input) {
+    if (!this.agentId || !this.token) throw new Error("Agent must be started before publishing Capsule Bus events.");
+    const sourceServiceCode = input.sourceServiceCode ?? this.options.service.code;
+    const result = await this.retry(() => this.client.publishBusEvent(this.agentId, this.token, { ...input, sourceServiceCode }));
+    this.log("info", "experimental bus event published", { eventId: result.eventId, eventType: input.eventType, sourceServiceCode, routedCommands: result.routedCommands.length });
+    return result;
+  }
   async reportService() {
     if (!this.agentId || !this.token) return;
     const [health, configs] = await Promise.all([this.runHealth(), this.configProvider()]);
@@ -372,6 +408,9 @@ var CapsuleAgent = class {
   AgentApiClient,
   AgentApiError,
   AgentAuthError,
+  BusDepthExceededError,
+  BusDisabledError,
+  BusRateLimitedError,
   CapsuleAgent,
   FileTokenStore,
   NetworkError,

package/dist/index.d.cts

@@ -1,12 +1,5 @@
-import { HealthReportInput, ConfigItemInput, ActionDefinitionInput, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
+import { ActionPrepareResult, PublishBusEventRequest, RuntimeKind, HealthReportInput, ConfigItemInput, ActionDefinitionInput, PublishBusEventResponse, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
 
-type RuntimeKind = "nodejs" | "java" | "python" | "go" | "other";
-type ActionPrepareResult = {
-    action?: Record<string, unknown>;
-    inputSchema?: Record<string, unknown>;
-    initialPayload?: Record<string, unknown>;
-    currentState?: Record<string, unknown>;
-};
 type AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     success?: boolean;
@@ -94,6 +87,11 @@ interface TokenStore {
     clear(): Promise<void>;
 }
 type ServiceSnapshot = ReportedService;
+/** Experimental v0.4 Capsule Bus publish input. Subject to change before v1.0. */
+type PublishBusEventInput = Omit<PublishBusEventRequest, "sourceServiceCode"> & {
+    sourceServiceCode?: string;
+};
+type PublishBusEventResult = PublishBusEventResponse;
 
 declare class CapsuleAgent {
     private readonly options;
@@ -118,6 +116,8 @@ declare class CapsuleAgent {
     private ensureRegistered;
     private serviceSnapshot;
     runHealth(): Promise<HealthReportInput>;
+    /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+    publishBusEvent(input: PublishBusEventInput): Promise<PublishBusEventResult>;
     private reportService;
     private heartbeat;
     private pollOnce;
@@ -178,6 +178,15 @@ declare class AgentAuthError extends AgentApiError {
 declare class NetworkError extends AgentApiError {
     constructor(message: string, cause?: unknown);
 }
+declare class BusDisabledError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class BusRateLimitedError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class BusDepthExceededError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
 
 declare class AgentApiClient {
     private readonly backendUrl;
@@ -193,7 +202,7 @@ declare class AgentApiClient {
     heartbeat(agentId: string, token: string, req: AgentHeartbeatRequest): Promise<unknown>;
     reportServices(agentId: string, token: string, req: ServiceReportRequest): Promise<unknown>;
     pollCommands(agentId: string, token: string): Promise<{
-        type: "ACTION_PREPARE" | "ACTION_EXECUTE";
+        type: "ACTION_EXECUTE" | "ACTION_PREPARE";
         id: string;
         createdAt: string;
         status: "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "EXPIRED" | "CANCELLED";
@@ -207,6 +216,21 @@ declare class AgentApiClient {
         completedAt?: string | null | undefined;
     }[]>;
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
+    /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+    publishBusEvent(agentId: string, token: string, req: PublishBusEventInput): Promise<{
+        experimental: "v0.4-experimental";
+        eventId: string;
+        routedCommands: {
+            status: "FAILED" | "DRY_RUN" | "CREATED" | "SKIPPED";
+            dryRun: boolean;
+            actionName: string;
+            routeId: string;
+            targetServiceCode: string;
+            commandId?: string | undefined;
+            errorCode?: string | undefined;
+            errorMessage?: string | undefined;
+        }[];
+    }>;
 }
 
-export { type ActionHandler, type ActionPrepareHandler, type ActionPrepareResult, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, type RuntimeKind, type ServiceSnapshot, type StructuredLogger, type TokenStore };
+export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, BusDepthExceededError, BusDisabledError, BusRateLimitedError, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type PublishBusEventInput, type PublishBusEventResult, type RegisteredAction, RegistrationError, type ServiceSnapshot, type StructuredLogger, type TokenStore };

package/dist/index.d.ts

@@ -1,12 +1,5 @@
-import { HealthReportInput, ConfigItemInput, ActionDefinitionInput, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
+import { ActionPrepareResult, PublishBusEventRequest, RuntimeKind, HealthReportInput, ConfigItemInput, ActionDefinitionInput, PublishBusEventResponse, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
 
-type RuntimeKind = "nodejs" | "java" | "python" | "go" | "other";
-type ActionPrepareResult = {
-    action?: Record<string, unknown>;
-    inputSchema?: Record<string, unknown>;
-    initialPayload?: Record<string, unknown>;
-    currentState?: Record<string, unknown>;
-};
 type AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     success?: boolean;
@@ -94,6 +87,11 @@ interface TokenStore {
     clear(): Promise<void>;
 }
 type ServiceSnapshot = ReportedService;
+/** Experimental v0.4 Capsule Bus publish input. Subject to change before v1.0. */
+type PublishBusEventInput = Omit<PublishBusEventRequest, "sourceServiceCode"> & {
+    sourceServiceCode?: string;
+};
+type PublishBusEventResult = PublishBusEventResponse;
 
 declare class CapsuleAgent {
     private readonly options;
@@ -118,6 +116,8 @@ declare class CapsuleAgent {
     private ensureRegistered;
     private serviceSnapshot;
     runHealth(): Promise<HealthReportInput>;
+    /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+    publishBusEvent(input: PublishBusEventInput): Promise<PublishBusEventResult>;
     private reportService;
     private heartbeat;
     private pollOnce;
@@ -178,6 +178,15 @@ declare class AgentAuthError extends AgentApiError {
 declare class NetworkError extends AgentApiError {
     constructor(message: string, cause?: unknown);
 }
+declare class BusDisabledError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class BusRateLimitedError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class BusDepthExceededError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
 
 declare class AgentApiClient {
     private readonly backendUrl;
@@ -193,7 +202,7 @@ declare class AgentApiClient {
     heartbeat(agentId: string, token: string, req: AgentHeartbeatRequest): Promise<unknown>;
     reportServices(agentId: string, token: string, req: ServiceReportRequest): Promise<unknown>;
     pollCommands(agentId: string, token: string): Promise<{
-        type: "ACTION_PREPARE" | "ACTION_EXECUTE";
+        type: "ACTION_EXECUTE" | "ACTION_PREPARE";
         id: string;
         createdAt: string;
         status: "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "EXPIRED" | "CANCELLED";
@@ -207,6 +216,21 @@ declare class AgentApiClient {
         completedAt?: string | null | undefined;
     }[]>;
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
+    /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+    publishBusEvent(agentId: string, token: string, req: PublishBusEventInput): Promise<{
+        experimental: "v0.4-experimental";
+        eventId: string;
+        routedCommands: {
+            status: "FAILED" | "DRY_RUN" | "CREATED" | "SKIPPED";
+            dryRun: boolean;
+            actionName: string;
+            routeId: string;
+            targetServiceCode: string;
+            commandId?: string | undefined;
+            errorCode?: string | undefined;
+            errorMessage?: string | undefined;
+        }[];
+    }>;
 }
 
-export { type ActionHandler, type ActionPrepareHandler, type ActionPrepareResult, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, type RuntimeKind, type ServiceSnapshot, type StructuredLogger, type TokenStore };
+export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, BusDepthExceededError, BusDisabledError, BusRateLimitedError, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type PublishBusEventInput, type PublishBusEventResult, type RegisteredAction, RegistrationError, type ServiceSnapshot, type StructuredLogger, type TokenStore };

package/dist/index.js

@@ -32,9 +32,30 @@ var NetworkError = class extends AgentApiError {
     }
   }
 };
+var BusDisabledError = class extends AgentApiError {
+  constructor(message, status, body) {
+    super(status, message, body, "CAPSULE_BUS_DISABLED");
+    this.name = "BusDisabledError";
+  }
+};
+var BusRateLimitedError = class extends AgentApiError {
+  constructor(message, status, body) {
+    super(status, message, body, "BUS_RATE_LIMITED");
+    this.name = "BusRateLimitedError";
+  }
+};
+var BusDepthExceededError = class extends AgentApiError {
+  constructor(message, status, body) {
+    super(status, message, body, "BUS_DEPTH_EXCEEDED");
+    this.name = "BusDepthExceededError";
+  }
+};
 function classifyAgentApiError(status, message, body, code, path) {
   if (status === 401 && path.endsWith("/register")) return new RegistrationError(message, status, body, code);
   if (status === 401 || status === 403) return new AgentAuthError(message, status, body, code);
+  if (code === "CAPSULE_BUS_DISABLED") return new BusDisabledError(message, status, body);
+  if (code === "BUS_RATE_LIMITED") return new BusRateLimitedError(message, status, body);
+  if (code === "BUS_DEPTH_EXCEEDED") return new BusDepthExceededError(message, status, body);
   return new AgentApiError(status, message, body, code);
 }
 
@@ -86,6 +107,10 @@ var AgentApiClient = class {
   reportResult(agentId, token, commandId, req) {
     return this.request(`/api/agents/${agentId}/commands/${commandId}/result`, { method: "POST", token, body: JSON.stringify(req) });
   }
+  /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+  publishBusEvent(agentId, token, req) {
+    return this.request(`/api/agents/${agentId}/bus/events`, { method: "POST", token, body: JSON.stringify({ ...req, experimental: req.experimental ?? "v0.4-experimental" }) });
+  }
 };
 
 // src/token-store/file-token-store.ts
@@ -240,6 +265,14 @@ var CapsuleAgent = class {
   async runHealth() {
     return this.healthProvider();
   }
+  /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+  async publishBusEvent(input) {
+    if (!this.agentId || !this.token) throw new Error("Agent must be started before publishing Capsule Bus events.");
+    const sourceServiceCode = input.sourceServiceCode ?? this.options.service.code;
+    const result = await this.retry(() => this.client.publishBusEvent(this.agentId, this.token, { ...input, sourceServiceCode }));
+    this.log("info", "experimental bus event published", { eventId: result.eventId, eventType: input.eventType, sourceServiceCode, routedCommands: result.routedCommands.length });
+    return result;
+  }
   async reportService() {
     if (!this.agentId || !this.token) return;
     const [health, configs] = await Promise.all([this.runHealth(), this.configProvider()]);
@@ -339,6 +372,9 @@ export {
   AgentApiClient,
   AgentApiError,
   AgentAuthError,
+  BusDepthExceededError,
+  BusDisabledError,
+  BusRateLimitedError,
   CapsuleAgent,
   FileTokenStore,
   NetworkError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Node.js Agent SDK for embedding Capsule Services into the Opstage governance loop.",
   "keywords": [
     "xtrape",
@@ -35,8 +35,15 @@
     "LICENSE",
     "NOTICE"
   ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "prepack": "pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "^0.2.0"
+    "@xtrape/capsule-contracts-node": "^0.4.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -51,11 +58,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "license": "Apache-2.0",
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
-  }
-}
+  "license": "Apache-2.0"
+}