@xtrape/capsule-agent-node 0.3.0 → 0.5.0

package/NOTICE

@@ -1,4 +1,4 @@
-Opstage CE
-Copyright 2026 Xtrape Capsule contributors
+Xtrape Embedded Agent SDK for Node.js
+Copyright 2026 Xtrape contributors
 
-This product includes software developed by the Xtrape Capsule contributors.
+This product includes software developed by the Xtrape contributors.

package/README.md

@@ -1,14 +1,21 @@
-# @xtrape/capsule-agent-node
+# Xtrape Embedded Agent SDK for Node.js
 
-> Node.js embedded Agent SDK for connecting Capsule Services to Opstage.
+> Node.js Embedded Agent SDK for connecting Workers to the Xtrape control plane.
+
+The npm name `@xtrape/capsule-agent-node`, the `CapsuleAgent` export, and some
+existing wire fields are legacy compatibility identifiers. `Capsule` is not a
+current Xtrape concept. New integrations should use `XtrapeAgent` and the
+`worker` option.
 
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![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` supports the stable Node.js Embedded Agent SDK path for single Capsule Services. For multi-service OpHub functionality, use OpHub (Go runtime).
+The package supports the Node.js Embedded Agent mode for one Worker. Multi-Worker
+ownership belongs to a sidecar or external Agent. Gateway, when present, routes
+Agent/control-plane traffic and does not replace the Agent role.
 
-> **Package status:** Xtrape Capsule is currently in **Public Review** before
+> **Package status:** Xtrape is currently in **Public Review** before
 > the `v0.1.0 Public Preview` release. This package is published under the
 > `public-review` dist-tag. APIs, contracts, deployment instructions, and SDK
 > interfaces may still change.
@@ -36,32 +43,32 @@ pnpm build
 
 ## Minimal Example
 
-This example matches the current SDK API: create a `CapsuleAgent`, configure
+This example uses the canonical alias `XtrapeAgent`, configures
 providers with `.health()` / `.configs()`, register Actions with `.action()`,
 then call `start()`.
 
 ```ts
-import { CapsuleAgent } from "@xtrape/capsule-agent-node";
+import { XtrapeAgent } from "@xtrape/capsule-agent-node";
 
-const agent = new CapsuleAgent({
+const agent = new XtrapeAgent({
   backendUrl: process.env.OPSTAGE_BACKEND_URL ?? "http://localhost:8080",
   registrationToken: process.env.OPSTAGE_REGISTRATION_TOKEN,
   tokenStore: { file: "./data/agent-token.txt" },
-  // Optional. If omitted, the SDK derives agent identity from `service`.
-  // Provide it explicitly when one Agent owns multiple Capsule Services on
+  // Optional. If omitted, the SDK derives Agent identity from `worker`.
+  // Provide it explicitly when one Agent owns multiple Workers on
   // the same host, or when you want a stable agent code that survives
   // service renames.
   agent: {
-    code: "hello-capsule-agent",
-    name: "Hello Capsule Agent",
+    code: "hello-worker-agent",
+    name: "Hello Worker Agent",
     runtime: "nodejs",
   },
-  service: {
-    code: "hello-capsule",
-    name: "Hello Capsule",
+  worker: {
+    code: "hello-worker",
+    name: "Hello Worker",
     version: "0.1.0",
     runtime: "nodejs",
-    description: "Minimal Capsule Service example",
+    description: "Minimal Worker example",
   },
 });
 
@@ -112,10 +119,12 @@ await agent.start();
 
 ## How Registration Works
 
-1. An operator creates a single-use Registration Token in Opstage CE.
-2. The service starts with `registrationToken` and calls the Agent registration
+1. An operator creates a single-use registration credential in Panel CE (the
+   current API calls it a Registration Token).
+2. The Worker starts with `registrationToken` and calls the Agent registration
    API.
-3. Opstage returns an Agent ID and Agent token.
+3. The control plane returns an Agent ID and Agent credential (currently named
+   an Agent token).
 4. The SDK stores the issued credentials in `tokenStore.file` as `<agentId>:<agentToken>`.
 5. Future restarts reuse the stored Agent token; the Registration Token is not
    needed again.
@@ -123,14 +132,15 @@ await agent.start();
 If the token file is lost or the Agent is revoked, create a new Registration
 Token and restart the service with it.
 
-## Service Manifest
+## Worker Manifest
 
-The `service` option describes the Capsule Service reported to Opstage:
+The `worker` option describes the Worker reported to the control plane. The old
+`service` option remains accepted for compatibility:
 
 ```ts
-service: {
-  code: "hello-capsule",          // stable unique service code
-  name: "Hello Capsule",         // operator-facing display name
+worker: {
+  code: "hello-worker",           // stable unique Worker code
+  name: "Hello Worker",           // operator-facing display name
   description: "...",            // optional
   version: "0.1.0",              // service version
   runtime: "nodejs",             // nodejs | java | python | go | other
@@ -138,8 +148,9 @@ service: {
 }
 ```
 
-The SDK wraps this as a `CapsuleService` manifest with `kind: "CapsuleService"`,
-`schemaVersion: "1.0"`, and `agentMode: "embedded"`.
+The SDK wraps this as a Worker manifest with `kind: "Worker"`,
+`schemaVersion: "1.0"`, and `agentMode: "embedded"`. Existing Panel versions
+continue accepting it through the legacy reported-service wire envelope.
 
 ## Health Reporting
 
@@ -153,13 +164,13 @@ agent.health(async () => ({
 }));
 ```
 
-The provider runs for heartbeats and service reports. Do not include secrets in
+The provider runs for heartbeats and Worker Runtime Reports. Do not include secrets in
 `details`.
 
 Agent health providers return protocol-level `HealthStatus` values: `UP`,
 `DEGRADED`, `DOWN`, `UNKNOWN`.
 
-Opstage may derive an operator-facing `effectiveStatus`: `HEALTHY`, `UNHEALTHY`,
+Xtrape Panel may derive an operator-facing `effectiveStatus`: `HEALTHY`, `UNHEALTHY`,
 `STALE`, `OFFLINE`.
 
 ## Config Reporting
@@ -186,8 +197,9 @@ agent.configs(() => [
 ]);
 ```
 
-Configs are reported to Opstage for visibility; the current CE flow does not
-push config values from Opstage into the service.
+Config Definitions and safe observations are reported to Panel for visibility.
+The Worker or deployment platform remains the configuration owner; current CE
+does not push arbitrary values into the Worker.
 
 ## Actions
 
@@ -207,12 +219,12 @@ agent.action({
 });
 ```
 
-Action metadata is published in the service report. The SDK intentionally strips
+Action metadata is published in the Worker Runtime Report. The SDK intentionally strips
 runtime-only handler functions before reporting the Action Catalog.
 
 ## Action Prepare / Execute
 
-Opstage uses two Command types for actions:
+Xtrape Panel uses two Command types for actions:
 
 1. `ACTION_PREPARE` — created when the UI opens an Action panel. The SDK calls
    `prepare()` if present and returns dynamic form metadata such as
@@ -229,8 +241,8 @@ The embedded Agent starts three loops by default:
 
 | Loop           |    Default | Purpose                            |
 | -------------- | ---------: | ---------------------------------- |
-| Heartbeat      | 30 seconds | Agent liveness and latest health   |
-| Service report | 60 seconds | Manifest, configs, actions, health |
+| Heartbeat      | 30 seconds | Agent liveness                     |
+| Worker report  | 60 seconds | Manifest, config observations, Actions, health |
 | Command poll   |  5 seconds | Fetch and execute pending Commands |
 
 You can override intervals:
@@ -240,7 +252,7 @@ new CapsuleAgent({
   // ...
   intervals: {
     heartbeatMs: 30_000,
-    serviceReportMs: 60_000,
+    workerReportMs: 60_000,
     commandPollMs: 5_000,
   },
 });
@@ -265,7 +277,7 @@ Security recommendations:
 
 - chmod the containing directory so only the service user can read it;
 - never commit token files;
-- rotate by revoking the Agent in Opstage and registering a new one;
+- rotate by revoking the Agent in Xtrape Panel and registering a new one;
 - prefer secret managers for production wrappers when available.
 
 ## Security Notes
@@ -342,7 +354,7 @@ try {
     process.exit(65);
   }
   if (err instanceof NetworkError) {
-    console.error("could not reach Opstage:", err.message);
+    console.error("could not reach Xtrape Panel:", err.message);
     process.exit(75);
   }
   throw err;
@@ -390,7 +402,7 @@ and `logger` are configured, `structuredLogger` wins.
 
 | Package                            | Compatible with                                               |
 | ---------------------------------- | ------------------------------------------------------------- |
-| `@xtrape/capsule-agent-node@0.1.x` | Opstage CE `0.1.x` and `@xtrape/capsule-contracts-node@0.1.x` |
+| `@xtrape/capsule-agent-node@0.1.x` | Xtrape Panel CE `0.1.x` and `@xtrape/capsule-contracts-node@0.1.x` |
 
 Use matching minor versions across CE, Agent SDK, and Contracts during Public
 Review and Public Preview. The wire protocol may still change before `v1.0`.
@@ -405,16 +417,16 @@ The token is single-use and short-lived.
   (registration tokens flip to `USED` on first use).
 - Check the token has not expired. Operators set `expiresInSeconds` when
   creating the token; the default in CE is short.
-- Check the token has not been revoked from the Opstage console.
+- Check the token has not been revoked from the Xtrape Panel console.
 - Re-create a fresh token in the console and start the agent with it.
 
 ### Agent reports `ECONNREFUSED` / cannot reach backend
 
 - Confirm `OPSTAGE_BACKEND_URL` resolves from inside the container or host
   where the agent runs. The default of `http://localhost:8080` only works if
-  the agent runs on the same host as Opstage.
+  the agent runs on the same host as Xtrape Panel.
 - If you sit behind a reverse proxy, point `backendUrl` at the proxy URL —
-  not the internal Opstage container address.
+  not the internal Xtrape Panel container address.
 - Outbound HTTPS through corporate proxies: respect `HTTPS_PROXY` /
   `NO_PROXY` env vars (`undici` honors them via `setGlobalDispatcher`).
 
@@ -427,7 +439,7 @@ The token is single-use and short-lived.
   file exists but contains anything else, delete it and re-register with a
   fresh registration token.
 - Token revocation: an operator may have revoked the agent or the agent
-  token from the console. Inspect the agent's status in Opstage; if it shows
+  token from the console. Inspect the agent's status in Xtrape Panel; if it shows
   `REVOKED` or `DISABLED`, that's the cause.
 
 ### Heartbeats succeed but action results never arrive
@@ -446,7 +458,7 @@ The token is single-use and short-lived.
 - Site: https://xtrape-com.github.io/xtrape-capsule-site/
 - Node embedded Agent guide: https://xtrape-com.github.io/xtrape-capsule-site/agents/node-embedded-agent
 - Action model: https://xtrape-com.github.io/xtrape-capsule-site/agents/action-model
-- Opstage CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
+- Xtrape Panel CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
 
 ## Contributing
 
@@ -456,5 +468,26 @@ safety guidance.
 
 ## License
 
-Apache-2.0. "Xtrape", "Xtrape Capsule", and "Opstage" are trademarks of their
+Apache-2.0. "Xtrape" and "Opstage" are trademarks of their
 respective owners; the open-source license does not grant trademark rights.
+
+## v0.4 Experimental legacy event routing 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 Xtrape Panel 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)
+
+legacy event routing is experimental in v0.4: not a standalone Bus Server, external broker, workflow engine, or service mesh API.

package/dist/index.cjs

@@ -23,10 +23,15 @@ __export(index_exports, {
   AgentApiClient: () => AgentApiClient,
   AgentApiError: () => AgentApiError,
   AgentAuthError: () => AgentAuthError,
+  BusDepthExceededError: () => BusDepthExceededError,
+  BusDisabledError: () => BusDisabledError,
+  BusRateLimitedError: () => BusRateLimitedError,
   CapsuleAgent: () => CapsuleAgent,
+  CeServiceAgent: () => CeServiceAgent,
   FileTokenStore: () => FileTokenStore,
   NetworkError: () => NetworkError,
-  RegistrationError: () => RegistrationError
+  RegistrationError: () => RegistrationError,
+  XtrapeAgent: () => CapsuleAgent
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -64,9 +69,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);
 }
 
@@ -112,12 +138,25 @@ var AgentApiClient = class {
   reportServices(agentId, token, req) {
     return this.request(`/api/agents/${agentId}/services/report`, { method: "POST", token, body: JSON.stringify(req) });
   }
+  /** Report Workers through the canonical endpoint, with a legacy fallback. */
+  async reportWorkers(agentId, token, req) {
+    try {
+      return await this.request(`/api/agents/${agentId}/workers/report`, { method: "POST", token, body: JSON.stringify(req) });
+    } catch (error) {
+      if (!(error instanceof AgentApiError) || error.status !== 404) throw error;
+      return this.reportServices(agentId, token, { services: req.workers });
+    }
+  }
   pollCommands(agentId, token) {
     return this.request(`/api/agents/${agentId}/commands`, { method: "GET", token });
   }
   reportResult(agentId, token, commandId, req) {
     return this.request(`/api/agents/${agentId}/commands/${commandId}/result`, { method: "POST", token, body: JSON.stringify(req) });
   }
+  /** Legacy v0.4 event-routing compatibility 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
@@ -187,6 +226,12 @@ function emitLog(consoleSink, structured, level, message, fields) {
 var CapsuleAgent = class {
   constructor(options) {
     this.options = options;
+    if (options.worker && options.service) {
+      throw new Error("Agent options accept `worker` or legacy `service`, not both.");
+    }
+    if (!options.worker && !options.service) {
+      throw new Error("Agent options require `worker` (or legacy `service`).");
+    }
     this.client = new AgentApiClient(options.backendUrl);
     this.store = new FileTokenStore(options.tokenStore?.file);
     this.logger = options.logger ?? console;
@@ -220,7 +265,7 @@ var CapsuleAgent = class {
     this.stopped = false;
     try {
       await this.ensureRegistered();
-      await this.reportService();
+      await this.reportWorker();
       await this.heartbeat();
       await this.pollOnce();
     } catch (e) {
@@ -229,7 +274,7 @@ var CapsuleAgent = class {
     }
     if (this.options.autoStartLoops !== false) {
       this.loop("heartbeat", this.options.intervals?.heartbeatMs ?? (this.options.heartbeatIntervalSeconds ?? 30) * 1e3, () => this.heartbeat());
-      this.loop("service-report", this.options.intervals?.serviceReportMs ?? 6e4, () => this.reportService());
+      this.loop("worker-report", this.options.intervals?.workerReportMs ?? this.options.intervals?.serviceReportMs ?? 6e4, () => this.reportWorker());
       this.loop("command-poll", this.options.intervals?.commandPollMs ?? (this.options.commandPollIntervalSeconds ?? 5) * 1e3, () => this.pollOnce());
     }
   }
@@ -258,30 +303,45 @@ var CapsuleAgent = class {
       if (this.agentId) return;
     }
     if (!this.options.registrationToken) throw new Error("OPSTAGE registration token is required for first registration");
-    const agent = this.options.agent ?? { code: this.options.service.code, name: this.options.service.name, runtime: this.options.service.runtime };
+    const worker = this.workerDefinition();
+    const agent = this.options.agent ?? { code: worker.code, name: worker.name, runtime: worker.runtime };
     const res = await this.retry(() => this.client.register({ registrationToken: this.options.registrationToken, agent: { code: agent.code, name: agent.name, mode: "embedded", runtime: agent.runtime ?? "nodejs" }, service: this.serviceSnapshot() }));
     this.agentId = res.agentId;
     this.token = res.agentToken;
     await this.store.save(`${this.agentId}:${this.token}`);
     this.log("info", `registered agent ${this.agentId}`);
   }
+  workerDefinition() {
+    if (this.options.worker) {
+      return this.options.worker;
+    }
+    return this.options.service;
+  }
   serviceSnapshot() {
-    const manifest = { kind: "CapsuleService", schemaVersion: "1.0", code: this.options.service.code, name: this.options.service.name, description: this.options.service.description, version: this.options.service.version, runtime: this.options.service.runtime, agentMode: "embedded", ...this.options.service.manifest ?? {} };
-    return { code: this.options.service.code, name: this.options.service.name, description: this.options.service.description, version: this.options.service.version, runtime: this.options.service.runtime, manifest, actions: [...this.actions.values()].map(({ handler, prepare, inputSchema, outputSchema, ...a }) => a) };
+    const worker = this.workerDefinition();
+    const manifest = { kind: "Worker", schemaVersion: "1.0", code: worker.code, name: worker.name, description: worker.description, version: worker.version, runtime: worker.runtime, agentMode: "embedded", ...worker.manifest ?? {} };
+    return { code: worker.code, name: worker.name, description: worker.description, version: worker.version, runtime: worker.runtime, manifest, actions: [...this.actions.values()].map(({ handler, prepare, inputSchema, outputSchema, ...a }) => a) };
   }
   async runHealth() {
     return this.healthProvider();
   }
-  async reportService() {
+  /** Legacy v0.4 event-routing compatibility hook. Subject to change before v1.0. */
+  async publishBusEvent(input) {
+    if (!this.agentId || !this.token) throw new Error("Agent must be started before publishing routed events.");
+    const sourceServiceCode = input.sourceServiceCode ?? this.workerDefinition().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 reportWorker() {
     if (!this.agentId || !this.token) return;
     const [health, configs] = await Promise.all([this.runHealth(), this.configProvider()]);
-    const svc = { ...this.serviceSnapshot(), health, configs };
-    await this.retry(() => this.client.reportServices(this.agentId, this.token, { services: [svc] }));
+    const worker = { ...this.serviceSnapshot(), health, configs };
+    await this.retry(() => this.client.reportWorkers(this.agentId, this.token, { workers: [worker] }));
   }
   async heartbeat() {
     if (!this.agentId || !this.token) return;
-    const health = await this.runHealth();
-    await this.retry(() => this.client.heartbeat(this.agentId, this.token, { health }));
+    await this.retry(() => this.client.heartbeat(this.agentId, this.token, {}));
   }
   async pollOnce() {
     if (!this.agentId || !this.token) return;
@@ -367,13 +427,134 @@ var CapsuleAgent = class {
     return { value: obj };
   }
 };
+
+// src/ce/index.ts
+var import_node_crypto = require("crypto");
+var import_capsule_contracts_node = require("@xtrape/capsule-contracts-node");
+var CeServiceAgent = class {
+  serviceId;
+  instanceId;
+  serverUrl;
+  manifest;
+  address;
+  tenant;
+  fetchImpl;
+  health = "HEALTHY";
+  hbTimer;
+  constructor(opts) {
+    this.serverUrl = opts.serverUrl.replace(/\/+$/, "");
+    this.manifest = opts.manifest;
+    this.address = opts.address;
+    this.tenant = opts.manifest.tenant ?? "default";
+    this.serviceId = opts.manifest.service.id;
+    this.instanceId = opts.instanceId ?? `${this.serviceId}-${(0, import_node_crypto.randomUUID)().slice(0, 8)}`;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+  /** The ServiceInstance this agent reports on register/heartbeat. */
+  instance() {
+    return import_capsule_contracts_node.ServiceInstanceSchema.parse({
+      contractVersion: import_capsule_contracts_node.CE_CONTRACT_VERSION,
+      serviceId: this.serviceId,
+      instanceId: this.instanceId,
+      tenant: this.tenant,
+      address: this.address,
+      version: this.manifest.service.version,
+      health: this.health
+    });
+  }
+  /** POST /v1/instances { manifest, instance } */
+  async register() {
+    await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() });
+    return { instanceId: this.instanceId };
+  }
+  setHealth(h) {
+    this.health = h;
+  }
+  /** POST /v1/instances/{id}/heartbeat */
+  async sendHeartbeat(metricsSummary) {
+    const hb = {
+      contractVersion: import_capsule_contracts_node.CE_CONTRACT_VERSION,
+      serviceId: this.serviceId,
+      instanceId: this.instanceId,
+      tenant: this.tenant,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      health: this.health,
+      ...metricsSummary ? { metricsSummary } : {}
+    };
+    await this.post(`/v1/instances/${encodeURIComponent(this.instanceId)}/heartbeat`, hb);
+  }
+  /** Start a periodic heartbeat; returns a stop function. Timer is unref'd. */
+  startHeartbeat(intervalMs = 1e4, metrics) {
+    this.stopHeartbeat();
+    this.hbTimer = setInterval(() => {
+      void this.sendHeartbeat(metrics?.()).catch(() => {
+      });
+    }, intervalMs);
+    this.hbTimer.unref?.();
+    return () => this.stopHeartbeat();
+  }
+  stopHeartbeat() {
+    if (this.hbTimer) {
+      clearInterval(this.hbTimer);
+      this.hbTimer = void 0;
+    }
+  }
+  /** DELETE /v1/instances/{id} — graceful deregister. */
+  async deregister() {
+    await this.fetchJson(`/v1/instances/${encodeURIComponent(this.instanceId)}`, { method: "DELETE" });
+  }
+  /**
+   * Validate an inbound message, run the handler, and build the reply message
+   * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
+   */
+  async handleMessage(raw, handler) {
+    const msg = import_capsule_contracts_node.ConversationMessageSchema.parse(raw);
+    const out = await handler(msg);
+    const reply = typeof out === "string" ? { content: out } : out;
+    return import_capsule_contracts_node.ConversationMessageSchema.parse({
+      contractVersion: import_capsule_contracts_node.CE_CONTRACT_VERSION,
+      messageId: `msg_${(0, import_node_crypto.randomUUID)().slice(0, 12)}`,
+      conversationId: msg.conversationId,
+      tenant: msg.tenant ?? "default",
+      // reply back to whoever sent it (USER/SERVICE/SYSTEM are all valid targets)
+      targetType: msg.senderType,
+      targetId: msg.senderId,
+      senderType: "SERVICE",
+      senderId: this.serviceId,
+      messageType: reply.messageType ?? "SUMMARY",
+      content: reply.content,
+      replyToMessageId: msg.messageId,
+      ...reply.payload ? { payload: reply.payload } : {}
+    });
+  }
+  post(path, body) {
+    return this.fetchJson(path, { method: "POST", body: JSON.stringify(body) });
+  }
+  async fetchJson(path, init) {
+    const res = await this.fetchImpl(this.serverUrl + path, {
+      ...init,
+      headers: { "content-type": "application/json", ...init.headers ?? {} }
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : void 0;
+    if (!res.ok) {
+      throw new Error(`server-ce ${path} -> ${res.status}: ${text}`);
+    }
+    return data;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentApiClient,
   AgentApiError,
   AgentAuthError,
+  BusDepthExceededError,
+  BusDisabledError,
+  BusRateLimitedError,
   CapsuleAgent,
+  CeServiceAgent,
   FileTokenStore,
   NetworkError,
-  RegistrationError
+  RegistrationError,
+  XtrapeAgent
 });

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, ConversationMessage, ServiceManifest, ServiceInstance, ServiceInstanceHealth } from '@xtrape/capsule-contracts-node';
 
 type AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
@@ -38,7 +38,15 @@ interface StructuredLogger {
  * `structuredLogger` wins.
  */
 type ConsoleLogger = Pick<Console, "debug" | "info" | "warn" | "error">;
-interface CapsuleAgentOptions {
+interface WorkerDefinition {
+    code: string;
+    name: string;
+    description?: string;
+    version: string;
+    runtime: RuntimeKind;
+    manifest?: Record<string, unknown>;
+}
+interface CapsuleAgentOptionsBase {
     backendUrl: string;
     registrationToken?: string;
     tokenStore?: {
@@ -49,17 +57,12 @@ interface CapsuleAgentOptions {
         name?: string;
         runtime?: RuntimeKind;
     };
-    service: {
-        code: string;
-        name: string;
-        description?: string;
-        version: string;
-        runtime: RuntimeKind;
-        manifest?: Record<string, unknown>;
-    };
     intervals?: {
         heartbeatMs?: number;
         commandPollMs?: number;
+        /** Canonical Worker Runtime Report interval. */
+        workerReportMs?: number;
+        /** @deprecated Compatibility alias for `workerReportMs`. */
         serviceReportMs?: number;
     };
     heartbeatIntervalSeconds?: number;
@@ -75,6 +78,19 @@ interface CapsuleAgentOptions {
     structuredLogger?: StructuredLogger;
     failOnStartError?: boolean;
 }
+/** Canonical Embedded Agent options: exactly one runtime unit via `worker`. */
+type WorkerAgentOptions = CapsuleAgentOptionsBase & {
+    worker: WorkerDefinition;
+    /** @deprecated Legacy alias; do not combine with `worker`. */
+    service?: never;
+};
+/** Legacy Embedded Agent options: exactly one runtime unit via `service`. */
+type LegacyServiceAgentOptions = CapsuleAgentOptionsBase & {
+    /** @deprecated Legacy compatibility alias for `worker`. */
+    service: WorkerDefinition;
+    worker?: never;
+};
+type CapsuleAgentOptions = WorkerAgentOptions | LegacyServiceAgentOptions;
 type HealthProvider = () => Promise<HealthReportInput> | HealthReportInput;
 type ConfigProvider = () => Promise<ConfigItemInput[]> | ConfigItemInput[];
 interface RegisteredAction extends ActionDefinitionInput {
@@ -87,6 +103,14 @@ interface TokenStore {
     clear(): Promise<void>;
 }
 type ServiceSnapshot = ReportedService;
+type WorkerSnapshot = ReportedService;
+type XtrapeAgentOptions = CapsuleAgentOptions;
+/** Legacy v0.4 event-routing publish input. Subject to change before v1.0. */
+type PublishBusEventInput = Omit<PublishBusEventRequest, "sourceServiceCode" | "experimental"> & {
+    sourceServiceCode?: string;
+    experimental?: PublishBusEventRequest["experimental"];
+};
+type PublishBusEventResult = PublishBusEventResponse;
 
 declare class CapsuleAgent {
     private readonly options;
@@ -109,9 +133,12 @@ declare class CapsuleAgent {
     stop(): Promise<void>;
     private loop;
     private ensureRegistered;
+    private workerDefinition;
     private serviceSnapshot;
     runHealth(): Promise<HealthReportInput>;
-    private reportService;
+    /** Legacy v0.4 event-routing compatibility hook. Subject to change before v1.0. */
+    publishBusEvent(input: PublishBusEventInput): Promise<PublishBusEventResult>;
+    private reportWorker;
     private heartbeat;
     private pollOnce;
     private execute;
@@ -149,7 +176,8 @@ declare class AgentApiError extends Error {
 /**
  * The backend rejected the registration token (expired, revoked, already
  * used, malformed). The agent cannot proceed without operator action: a
- * fresh registration token must be created in Opstage.
+ * a fresh registration credential must be created in Panel. The current API
+ * still calls this value a registration token.
  */
 declare class RegistrationError extends AgentApiError {
     constructor(message: string, status: number, body?: unknown, code?: string);
@@ -171,6 +199,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;
@@ -185,8 +222,12 @@ declare class AgentApiClient {
     }>;
     heartbeat(agentId: string, token: string, req: AgentHeartbeatRequest): Promise<unknown>;
     reportServices(agentId: string, token: string, req: ServiceReportRequest): Promise<unknown>;
+    /** Report Workers through the canonical endpoint, with a legacy fallback. */
+    reportWorkers(agentId: string, token: string, req: {
+        workers: ReportedService[];
+    }): 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 +241,84 @@ declare class AgentApiClient {
         completedAt?: string | null | undefined;
     }[]>;
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
+    /** Legacy v0.4 event-routing compatibility 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;
+        }[];
+    }>;
+}
+
+/**
+ * Xtrape CE Phase 0 service agent.
+ *
+ * Framework-agnostic SDK for an `xtrape-service` to:
+ *  - register an instance to `xtrape-server-ce`;
+ *  - send heartbeats;
+ *  - validate inbound ConversationMessages and build replies.
+ *
+ * See xtrape-docs runtime-platform/04 (registration & heartbeat) and /03 (message).
+ */
+interface CeServiceAgentOptions {
+    /** xtrape-server-ce base URL, e.g. http://localhost:3000 */
+    serverUrl: string;
+    /** this service's manifest */
+    manifest: ServiceManifest;
+    /** this instance's reachable address (URL) */
+    address: string;
+    /** optional fixed instance id; defaults to `<serviceId>-<rand>` */
+    instanceId?: string;
+    /** injectable fetch (tests); defaults to global fetch */
+    fetchImpl?: typeof fetch;
+}
+type CeMessageReply = string | {
+    content: string;
+    messageType?: ConversationMessage["messageType"];
+    payload?: Record<string, unknown>;
+};
+/** Handler invoked with a validated inbound message; returns the reply content. */
+type CeMessageHandler = (msg: ConversationMessage) => CeMessageReply | Promise<CeMessageReply>;
+declare class CeServiceAgent {
+    readonly serviceId: string;
+    readonly instanceId: string;
+    private readonly serverUrl;
+    private readonly manifest;
+    private readonly address;
+    private readonly tenant;
+    private readonly fetchImpl;
+    private health;
+    private hbTimer?;
+    constructor(opts: CeServiceAgentOptions);
+    /** The ServiceInstance this agent reports on register/heartbeat. */
+    instance(): ServiceInstance;
+    /** POST /v1/instances { manifest, instance } */
+    register(): Promise<{
+        instanceId: string;
+    }>;
+    setHealth(h: ServiceInstanceHealth): void;
+    /** POST /v1/instances/{id}/heartbeat */
+    sendHeartbeat(metricsSummary?: Record<string, unknown>): Promise<void>;
+    /** Start a periodic heartbeat; returns a stop function. Timer is unref'd. */
+    startHeartbeat(intervalMs?: number, metrics?: () => Record<string, unknown>): () => void;
+    stopHeartbeat(): void;
+    /** DELETE /v1/instances/{id} — graceful deregister. */
+    deregister(): Promise<void>;
+    /**
+     * Validate an inbound message, run the handler, and build the reply message
+     * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
+     */
+    handleMessage(raw: unknown, handler: CeMessageHandler): Promise<ConversationMessage>;
+    private post;
+    private fetchJson;
 }
 
-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 CeMessageHandler, type CeMessageReply, CeServiceAgent, type CeServiceAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, type LegacyServiceAgentOptions, NetworkError, type PublishBusEventInput, type PublishBusEventResult, type RegisteredAction, RegistrationError, type ServiceSnapshot, type StructuredLogger, type TokenStore, type WorkerAgentOptions, type WorkerDefinition, type WorkerSnapshot, CapsuleAgent as XtrapeAgent, type XtrapeAgentOptions };

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, ConversationMessage, ServiceManifest, ServiceInstance, ServiceInstanceHealth } from '@xtrape/capsule-contracts-node';
 
 type AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
@@ -38,7 +38,15 @@ interface StructuredLogger {
  * `structuredLogger` wins.
  */
 type ConsoleLogger = Pick<Console, "debug" | "info" | "warn" | "error">;
-interface CapsuleAgentOptions {
+interface WorkerDefinition {
+    code: string;
+    name: string;
+    description?: string;
+    version: string;
+    runtime: RuntimeKind;
+    manifest?: Record<string, unknown>;
+}
+interface CapsuleAgentOptionsBase {
     backendUrl: string;
     registrationToken?: string;
     tokenStore?: {
@@ -49,17 +57,12 @@ interface CapsuleAgentOptions {
         name?: string;
         runtime?: RuntimeKind;
     };
-    service: {
-        code: string;
-        name: string;
-        description?: string;
-        version: string;
-        runtime: RuntimeKind;
-        manifest?: Record<string, unknown>;
-    };
     intervals?: {
         heartbeatMs?: number;
         commandPollMs?: number;
+        /** Canonical Worker Runtime Report interval. */
+        workerReportMs?: number;
+        /** @deprecated Compatibility alias for `workerReportMs`. */
         serviceReportMs?: number;
     };
     heartbeatIntervalSeconds?: number;
@@ -75,6 +78,19 @@ interface CapsuleAgentOptions {
     structuredLogger?: StructuredLogger;
     failOnStartError?: boolean;
 }
+/** Canonical Embedded Agent options: exactly one runtime unit via `worker`. */
+type WorkerAgentOptions = CapsuleAgentOptionsBase & {
+    worker: WorkerDefinition;
+    /** @deprecated Legacy alias; do not combine with `worker`. */
+    service?: never;
+};
+/** Legacy Embedded Agent options: exactly one runtime unit via `service`. */
+type LegacyServiceAgentOptions = CapsuleAgentOptionsBase & {
+    /** @deprecated Legacy compatibility alias for `worker`. */
+    service: WorkerDefinition;
+    worker?: never;
+};
+type CapsuleAgentOptions = WorkerAgentOptions | LegacyServiceAgentOptions;
 type HealthProvider = () => Promise<HealthReportInput> | HealthReportInput;
 type ConfigProvider = () => Promise<ConfigItemInput[]> | ConfigItemInput[];
 interface RegisteredAction extends ActionDefinitionInput {
@@ -87,6 +103,14 @@ interface TokenStore {
     clear(): Promise<void>;
 }
 type ServiceSnapshot = ReportedService;
+type WorkerSnapshot = ReportedService;
+type XtrapeAgentOptions = CapsuleAgentOptions;
+/** Legacy v0.4 event-routing publish input. Subject to change before v1.0. */
+type PublishBusEventInput = Omit<PublishBusEventRequest, "sourceServiceCode" | "experimental"> & {
+    sourceServiceCode?: string;
+    experimental?: PublishBusEventRequest["experimental"];
+};
+type PublishBusEventResult = PublishBusEventResponse;
 
 declare class CapsuleAgent {
     private readonly options;
@@ -109,9 +133,12 @@ declare class CapsuleAgent {
     stop(): Promise<void>;
     private loop;
     private ensureRegistered;
+    private workerDefinition;
     private serviceSnapshot;
     runHealth(): Promise<HealthReportInput>;
-    private reportService;
+    /** Legacy v0.4 event-routing compatibility hook. Subject to change before v1.0. */
+    publishBusEvent(input: PublishBusEventInput): Promise<PublishBusEventResult>;
+    private reportWorker;
     private heartbeat;
     private pollOnce;
     private execute;
@@ -149,7 +176,8 @@ declare class AgentApiError extends Error {
 /**
  * The backend rejected the registration token (expired, revoked, already
  * used, malformed). The agent cannot proceed without operator action: a
- * fresh registration token must be created in Opstage.
+ * a fresh registration credential must be created in Panel. The current API
+ * still calls this value a registration token.
  */
 declare class RegistrationError extends AgentApiError {
     constructor(message: string, status: number, body?: unknown, code?: string);
@@ -171,6 +199,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;
@@ -185,8 +222,12 @@ declare class AgentApiClient {
     }>;
     heartbeat(agentId: string, token: string, req: AgentHeartbeatRequest): Promise<unknown>;
     reportServices(agentId: string, token: string, req: ServiceReportRequest): Promise<unknown>;
+    /** Report Workers through the canonical endpoint, with a legacy fallback. */
+    reportWorkers(agentId: string, token: string, req: {
+        workers: ReportedService[];
+    }): 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 +241,84 @@ declare class AgentApiClient {
         completedAt?: string | null | undefined;
     }[]>;
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
+    /** Legacy v0.4 event-routing compatibility 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;
+        }[];
+    }>;
+}
+
+/**
+ * Xtrape CE Phase 0 service agent.
+ *
+ * Framework-agnostic SDK for an `xtrape-service` to:
+ *  - register an instance to `xtrape-server-ce`;
+ *  - send heartbeats;
+ *  - validate inbound ConversationMessages and build replies.
+ *
+ * See xtrape-docs runtime-platform/04 (registration & heartbeat) and /03 (message).
+ */
+interface CeServiceAgentOptions {
+    /** xtrape-server-ce base URL, e.g. http://localhost:3000 */
+    serverUrl: string;
+    /** this service's manifest */
+    manifest: ServiceManifest;
+    /** this instance's reachable address (URL) */
+    address: string;
+    /** optional fixed instance id; defaults to `<serviceId>-<rand>` */
+    instanceId?: string;
+    /** injectable fetch (tests); defaults to global fetch */
+    fetchImpl?: typeof fetch;
+}
+type CeMessageReply = string | {
+    content: string;
+    messageType?: ConversationMessage["messageType"];
+    payload?: Record<string, unknown>;
+};
+/** Handler invoked with a validated inbound message; returns the reply content. */
+type CeMessageHandler = (msg: ConversationMessage) => CeMessageReply | Promise<CeMessageReply>;
+declare class CeServiceAgent {
+    readonly serviceId: string;
+    readonly instanceId: string;
+    private readonly serverUrl;
+    private readonly manifest;
+    private readonly address;
+    private readonly tenant;
+    private readonly fetchImpl;
+    private health;
+    private hbTimer?;
+    constructor(opts: CeServiceAgentOptions);
+    /** The ServiceInstance this agent reports on register/heartbeat. */
+    instance(): ServiceInstance;
+    /** POST /v1/instances { manifest, instance } */
+    register(): Promise<{
+        instanceId: string;
+    }>;
+    setHealth(h: ServiceInstanceHealth): void;
+    /** POST /v1/instances/{id}/heartbeat */
+    sendHeartbeat(metricsSummary?: Record<string, unknown>): Promise<void>;
+    /** Start a periodic heartbeat; returns a stop function. Timer is unref'd. */
+    startHeartbeat(intervalMs?: number, metrics?: () => Record<string, unknown>): () => void;
+    stopHeartbeat(): void;
+    /** DELETE /v1/instances/{id} — graceful deregister. */
+    deregister(): Promise<void>;
+    /**
+     * Validate an inbound message, run the handler, and build the reply message
+     * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
+     */
+    handleMessage(raw: unknown, handler: CeMessageHandler): Promise<ConversationMessage>;
+    private post;
+    private fetchJson;
 }
 
-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 CeMessageHandler, type CeMessageReply, CeServiceAgent, type CeServiceAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, type LegacyServiceAgentOptions, NetworkError, type PublishBusEventInput, type PublishBusEventResult, type RegisteredAction, RegistrationError, type ServiceSnapshot, type StructuredLogger, type TokenStore, type WorkerAgentOptions, type WorkerDefinition, type WorkerSnapshot, CapsuleAgent as XtrapeAgent, type XtrapeAgentOptions };

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);
 }
 
@@ -80,12 +101,25 @@ var AgentApiClient = class {
   reportServices(agentId, token, req) {
     return this.request(`/api/agents/${agentId}/services/report`, { method: "POST", token, body: JSON.stringify(req) });
   }
+  /** Report Workers through the canonical endpoint, with a legacy fallback. */
+  async reportWorkers(agentId, token, req) {
+    try {
+      return await this.request(`/api/agents/${agentId}/workers/report`, { method: "POST", token, body: JSON.stringify(req) });
+    } catch (error) {
+      if (!(error instanceof AgentApiError) || error.status !== 404) throw error;
+      return this.reportServices(agentId, token, { services: req.workers });
+    }
+  }
   pollCommands(agentId, token) {
     return this.request(`/api/agents/${agentId}/commands`, { method: "GET", token });
   }
   reportResult(agentId, token, commandId, req) {
     return this.request(`/api/agents/${agentId}/commands/${commandId}/result`, { method: "POST", token, body: JSON.stringify(req) });
   }
+  /** Legacy v0.4 event-routing compatibility 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
@@ -155,6 +189,12 @@ function emitLog(consoleSink, structured, level, message, fields) {
 var CapsuleAgent = class {
   constructor(options) {
     this.options = options;
+    if (options.worker && options.service) {
+      throw new Error("Agent options accept `worker` or legacy `service`, not both.");
+    }
+    if (!options.worker && !options.service) {
+      throw new Error("Agent options require `worker` (or legacy `service`).");
+    }
     this.client = new AgentApiClient(options.backendUrl);
     this.store = new FileTokenStore(options.tokenStore?.file);
     this.logger = options.logger ?? console;
@@ -188,7 +228,7 @@ var CapsuleAgent = class {
     this.stopped = false;
     try {
       await this.ensureRegistered();
-      await this.reportService();
+      await this.reportWorker();
       await this.heartbeat();
       await this.pollOnce();
     } catch (e) {
@@ -197,7 +237,7 @@ var CapsuleAgent = class {
     }
     if (this.options.autoStartLoops !== false) {
       this.loop("heartbeat", this.options.intervals?.heartbeatMs ?? (this.options.heartbeatIntervalSeconds ?? 30) * 1e3, () => this.heartbeat());
-      this.loop("service-report", this.options.intervals?.serviceReportMs ?? 6e4, () => this.reportService());
+      this.loop("worker-report", this.options.intervals?.workerReportMs ?? this.options.intervals?.serviceReportMs ?? 6e4, () => this.reportWorker());
       this.loop("command-poll", this.options.intervals?.commandPollMs ?? (this.options.commandPollIntervalSeconds ?? 5) * 1e3, () => this.pollOnce());
     }
   }
@@ -226,30 +266,45 @@ var CapsuleAgent = class {
       if (this.agentId) return;
     }
     if (!this.options.registrationToken) throw new Error("OPSTAGE registration token is required for first registration");
-    const agent = this.options.agent ?? { code: this.options.service.code, name: this.options.service.name, runtime: this.options.service.runtime };
+    const worker = this.workerDefinition();
+    const agent = this.options.agent ?? { code: worker.code, name: worker.name, runtime: worker.runtime };
     const res = await this.retry(() => this.client.register({ registrationToken: this.options.registrationToken, agent: { code: agent.code, name: agent.name, mode: "embedded", runtime: agent.runtime ?? "nodejs" }, service: this.serviceSnapshot() }));
     this.agentId = res.agentId;
     this.token = res.agentToken;
     await this.store.save(`${this.agentId}:${this.token}`);
     this.log("info", `registered agent ${this.agentId}`);
   }
+  workerDefinition() {
+    if (this.options.worker) {
+      return this.options.worker;
+    }
+    return this.options.service;
+  }
   serviceSnapshot() {
-    const manifest = { kind: "CapsuleService", schemaVersion: "1.0", code: this.options.service.code, name: this.options.service.name, description: this.options.service.description, version: this.options.service.version, runtime: this.options.service.runtime, agentMode: "embedded", ...this.options.service.manifest ?? {} };
-    return { code: this.options.service.code, name: this.options.service.name, description: this.options.service.description, version: this.options.service.version, runtime: this.options.service.runtime, manifest, actions: [...this.actions.values()].map(({ handler, prepare, inputSchema, outputSchema, ...a }) => a) };
+    const worker = this.workerDefinition();
+    const manifest = { kind: "Worker", schemaVersion: "1.0", code: worker.code, name: worker.name, description: worker.description, version: worker.version, runtime: worker.runtime, agentMode: "embedded", ...worker.manifest ?? {} };
+    return { code: worker.code, name: worker.name, description: worker.description, version: worker.version, runtime: worker.runtime, manifest, actions: [...this.actions.values()].map(({ handler, prepare, inputSchema, outputSchema, ...a }) => a) };
   }
   async runHealth() {
     return this.healthProvider();
   }
-  async reportService() {
+  /** Legacy v0.4 event-routing compatibility hook. Subject to change before v1.0. */
+  async publishBusEvent(input) {
+    if (!this.agentId || !this.token) throw new Error("Agent must be started before publishing routed events.");
+    const sourceServiceCode = input.sourceServiceCode ?? this.workerDefinition().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 reportWorker() {
     if (!this.agentId || !this.token) return;
     const [health, configs] = await Promise.all([this.runHealth(), this.configProvider()]);
-    const svc = { ...this.serviceSnapshot(), health, configs };
-    await this.retry(() => this.client.reportServices(this.agentId, this.token, { services: [svc] }));
+    const worker = { ...this.serviceSnapshot(), health, configs };
+    await this.retry(() => this.client.reportWorkers(this.agentId, this.token, { workers: [worker] }));
   }
   async heartbeat() {
     if (!this.agentId || !this.token) return;
-    const health = await this.runHealth();
-    await this.retry(() => this.client.heartbeat(this.agentId, this.token, { health }));
+    await this.retry(() => this.client.heartbeat(this.agentId, this.token, {}));
   }
   async pollOnce() {
     if (!this.agentId || !this.token) return;
@@ -335,12 +390,137 @@ var CapsuleAgent = class {
     return { value: obj };
   }
 };
+
+// src/ce/index.ts
+import { randomUUID } from "crypto";
+import {
+  CE_CONTRACT_VERSION,
+  ServiceInstanceSchema,
+  ConversationMessageSchema
+} from "@xtrape/capsule-contracts-node";
+var CeServiceAgent = class {
+  serviceId;
+  instanceId;
+  serverUrl;
+  manifest;
+  address;
+  tenant;
+  fetchImpl;
+  health = "HEALTHY";
+  hbTimer;
+  constructor(opts) {
+    this.serverUrl = opts.serverUrl.replace(/\/+$/, "");
+    this.manifest = opts.manifest;
+    this.address = opts.address;
+    this.tenant = opts.manifest.tenant ?? "default";
+    this.serviceId = opts.manifest.service.id;
+    this.instanceId = opts.instanceId ?? `${this.serviceId}-${randomUUID().slice(0, 8)}`;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+  /** The ServiceInstance this agent reports on register/heartbeat. */
+  instance() {
+    return ServiceInstanceSchema.parse({
+      contractVersion: CE_CONTRACT_VERSION,
+      serviceId: this.serviceId,
+      instanceId: this.instanceId,
+      tenant: this.tenant,
+      address: this.address,
+      version: this.manifest.service.version,
+      health: this.health
+    });
+  }
+  /** POST /v1/instances { manifest, instance } */
+  async register() {
+    await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() });
+    return { instanceId: this.instanceId };
+  }
+  setHealth(h) {
+    this.health = h;
+  }
+  /** POST /v1/instances/{id}/heartbeat */
+  async sendHeartbeat(metricsSummary) {
+    const hb = {
+      contractVersion: CE_CONTRACT_VERSION,
+      serviceId: this.serviceId,
+      instanceId: this.instanceId,
+      tenant: this.tenant,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      health: this.health,
+      ...metricsSummary ? { metricsSummary } : {}
+    };
+    await this.post(`/v1/instances/${encodeURIComponent(this.instanceId)}/heartbeat`, hb);
+  }
+  /** Start a periodic heartbeat; returns a stop function. Timer is unref'd. */
+  startHeartbeat(intervalMs = 1e4, metrics) {
+    this.stopHeartbeat();
+    this.hbTimer = setInterval(() => {
+      void this.sendHeartbeat(metrics?.()).catch(() => {
+      });
+    }, intervalMs);
+    this.hbTimer.unref?.();
+    return () => this.stopHeartbeat();
+  }
+  stopHeartbeat() {
+    if (this.hbTimer) {
+      clearInterval(this.hbTimer);
+      this.hbTimer = void 0;
+    }
+  }
+  /** DELETE /v1/instances/{id} — graceful deregister. */
+  async deregister() {
+    await this.fetchJson(`/v1/instances/${encodeURIComponent(this.instanceId)}`, { method: "DELETE" });
+  }
+  /**
+   * Validate an inbound message, run the handler, and build the reply message
+   * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
+   */
+  async handleMessage(raw, handler) {
+    const msg = ConversationMessageSchema.parse(raw);
+    const out = await handler(msg);
+    const reply = typeof out === "string" ? { content: out } : out;
+    return ConversationMessageSchema.parse({
+      contractVersion: CE_CONTRACT_VERSION,
+      messageId: `msg_${randomUUID().slice(0, 12)}`,
+      conversationId: msg.conversationId,
+      tenant: msg.tenant ?? "default",
+      // reply back to whoever sent it (USER/SERVICE/SYSTEM are all valid targets)
+      targetType: msg.senderType,
+      targetId: msg.senderId,
+      senderType: "SERVICE",
+      senderId: this.serviceId,
+      messageType: reply.messageType ?? "SUMMARY",
+      content: reply.content,
+      replyToMessageId: msg.messageId,
+      ...reply.payload ? { payload: reply.payload } : {}
+    });
+  }
+  post(path, body) {
+    return this.fetchJson(path, { method: "POST", body: JSON.stringify(body) });
+  }
+  async fetchJson(path, init) {
+    const res = await this.fetchImpl(this.serverUrl + path, {
+      ...init,
+      headers: { "content-type": "application/json", ...init.headers ?? {} }
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : void 0;
+    if (!res.ok) {
+      throw new Error(`server-ce ${path} -> ${res.status}: ${text}`);
+    }
+    return data;
+  }
+};
 export {
   AgentApiClient,
   AgentApiError,
   AgentAuthError,
+  BusDepthExceededError,
+  BusDisabledError,
+  BusRateLimitedError,
   CapsuleAgent,
+  CeServiceAgent,
   FileTokenStore,
   NetworkError,
-  RegistrationError
+  RegistrationError,
+  CapsuleAgent as XtrapeAgent
 };

package/package.json

@@ -1,10 +1,11 @@
 {
   "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.5.0",
+  "description": "Node.js Embedded Agent SDK for reporting Workers to the Xtrape control plane.",
   "keywords": [
     "xtrape",
-    "capsule",
+    "worker",
+    "panel",
     "opstage",
     "agent-sdk",
     "automation",
@@ -39,17 +40,17 @@
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "prepack": "pnpm build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.type-tests.json",
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "0.3.0"
+    "@xtrape/capsule-contracts-node": "^0.5.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"