@xtrape/capsule-agent-node 0.3.0 → 0.4.0

package/README.md

@@ -458,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,4 +1,4 @@
-import { ActionPrepareResult, RuntimeKind, 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 AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
@@ -87,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;
@@ -111,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;
@@ -171,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;
@@ -186,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";
@@ -200,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, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, 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,4 +1,4 @@
-import { ActionPrepareResult, RuntimeKind, 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 AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
@@ -87,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;
@@ -111,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;
@@ -171,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;
@@ -186,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";
@@ -200,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, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, 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,7 +1,7 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.3.0",
-  "description": "Node.js Embedded Agent SDK for embedding single Capsule Services into the Opstage governance loop. For multi-service OpHub functionality, use OpHub (Go runtime).",
+  "version": "0.4.0",
+  "description": "Node.js Agent SDK for embedding Capsule Services into the Opstage governance loop.",
   "keywords": [
     "xtrape",
     "capsule",
@@ -43,13 +43,13 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "0.3.0"
+    "@xtrape/capsule-contracts-node": "^0.4.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "@types/node": "^22.10.2"
   },
   "engines": {
     "node": ">=20"