@xtrape/capsule-agent-node 0.5.0 → 0.6.0

package/README.md

@@ -8,31 +8,28 @@ 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)
+[![Status: Release Train 0.6.0](https://img.shields.io/badge/status-0.6.0-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
+[![Docs](https://img.shields.io/badge/docs-xtrape--docs-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
 
 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 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.
+> **Package status:** This package follows the unified Xtrape `0.6.0` release
+> train. The npm package name remains a compatibility identifier, but release
+> versioning now follows the shared Xtrape train version.
 
 ## Install
 
-During Public Review, install the prerelease package with:
+This repository tracks the `0.6.0` snapshot train. Until the `0.6.0` npm cut is
+published, install the latest published compatibility package:
 
 ```bash
-pnpm add @xtrape/capsule-agent-node@public-review
+pnpm add @xtrape/capsule-agent-node@^0.5.0
 ```
 
-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 source-level snapshot integration, use a local checkout of this repository
+and align the rest of the release train separately.
 
 For this repository itself:
 
@@ -41,6 +38,68 @@ pnpm install
 pnpm build
 ```
 
+## Xtrape CE Phase 0 Service Agent
+
+For the Xtrape CE 0.1 runtime loop (`Telegram → xtrape-server-ce → xtrape-service
+→ reply`), use `CeServiceAgent` (or the `serveCeService` bootstrap). An
+`xtrape-service` registers an instance to `xtrape-server-ce`, heartbeats, and
+replies to `ConversationMessage`s. `Service` and `Worker` are roles here, not the
+legacy `Capsule` concept.
+
+### One-call bootstrap
+
+`serveCeService` starts an HTTP listener (`POST /messages`, `GET /health`),
+registers the instance (sending the registration token if server-ce requires
+one), and runs heartbeats — so a service does not copy-paste lifecycle code:
+
+For deployed or containerized use, set `address` to the callback URL that
+`xtrape-server-ce` can actually reach and allowlist, for example
+`http://demo-service:8080`. The SDK only derives a default address when you
+bind to an explicit local-only host such as `127.0.0.1`.
+
+```ts
+import { serveCeService } from "@xtrape/capsule-agent-node";
+
+const svc = await serveCeService({
+  serverUrl: process.env.XTRAPE_SERVER_URL ?? "http://localhost:3000",
+  registrationToken: process.env.SERVER_CE_REGISTRATION_TOKEN,
+  port: 8080,
+  // required in deployed/containerized environments
+  address: process.env.SERVICE_ADDRESS ?? "http://demo-service:8080",
+  manifest: {
+    contractVersion: 1,
+    service: { id: "demo-echo-service", name: "Demo Echo Service", version: "0.6.0" },
+    runtime: { language: "node", agent: "xtrape-agent-nodejs" },
+    capabilities: ["status.query"],
+    message: { supportedTypes: ["QUERY"] },
+  },
+  handler: (msg) => `echo: ${msg.content}`,
+});
+
+process.on("SIGTERM", () => void svc.close()); // stop heartbeat + deregister + close
+```
+
+### Lower-level agent
+
+When the service already runs its own HTTP server, use `CeServiceAgent` directly:
+
+```ts
+import { CeServiceAgent } from "@xtrape/capsule-agent-node";
+
+const agent = new CeServiceAgent({
+  serverUrl: "http://localhost:3000",
+  registrationToken: process.env.SERVER_CE_REGISTRATION_TOKEN,
+  address: "http://127.0.0.1:8080",
+  manifest: /* ServiceManifest */ undefined as never,
+});
+
+const stop = await agent.start();          // register + heartbeat
+// in your POST /messages route:
+const reply = await agent.handleMessage(requestJson, (m) => `echo: ${m.content}`);
+// on shutdown:
+await stop();                              // stop heartbeat + deregister
+```
+
 ## Minimal Example
 
 This example uses the canonical alias `XtrapeAgent`, configures
@@ -402,10 +461,13 @@ and `logger` are configured, `structuredLogger` wins.
 
 | Package                            | Compatible with                                               |
 | ---------------------------------- | ------------------------------------------------------------- |
+| repository line `0.6.0`            | current Xtrape `0.6.0` snapshot train                         |
 | `@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`.
+Use matching release-train versions across CE, Agent SDK, and Contracts. During
+the current `0.6.0` snapshot phase, published compatibility packages may lag
+the repository line until the train npm cut is published. The wire protocol may
+still change before `v1.0`.
 
 ## Troubleshooting
 
@@ -455,10 +517,10 @@ The token is single-use and short-lived.
 
 ## Documentation
 
-- 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
-- Xtrape Panel CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
+- Public docs repo: https://forgejo.xtrape.com/xtrape/xtrape-site
+- Node embedded Agent guide: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/agents/node-embedded-agent.md
+- Action model: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/agents/action-model.md
+- Xtrape Panel CE docs: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/opstage-ce/overview.md
 
 ## Contributing
 

package/dist/index.cjs

@@ -31,7 +31,8 @@ __export(index_exports, {
   FileTokenStore: () => FileTokenStore,
   NetworkError: () => NetworkError,
   RegistrationError: () => RegistrationError,
-  XtrapeAgent: () => CapsuleAgent
+  XtrapeAgent: () => CapsuleAgent,
+  serveCeService: () => serveCeService
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -431,6 +432,12 @@ var CapsuleAgent = class {
 // src/ce/index.ts
 var import_node_crypto = require("crypto");
 var import_capsule_contracts_node = require("@xtrape/capsule-contracts-node");
+var CeInboundMessageValidationError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CeInboundMessageValidationError";
+  }
+};
 var CeServiceAgent = class {
   serviceId;
   instanceId;
@@ -438,6 +445,7 @@ var CeServiceAgent = class {
   manifest;
   address;
   tenant;
+  registrationToken;
   fetchImpl;
   health = "HEALTHY";
   hbTimer;
@@ -448,6 +456,7 @@ var CeServiceAgent = class {
     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.registrationToken = opts.registrationToken;
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
   /** The ServiceInstance this agent reports on register/heartbeat. */
@@ -462,11 +471,26 @@ var CeServiceAgent = class {
       health: this.health
     });
   }
-  /** POST /v1/instances { manifest, instance } */
+  /** POST /v1/instances { manifest, instance } (sends the registration token if set). */
   async register() {
-    await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() });
+    const headers = this.registrationToken ? { "x-xtrape-registration-token": this.registrationToken } : void 0;
+    await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() }, headers);
     return { instanceId: this.instanceId };
   }
+  /**
+   * Lifecycle convenience: register, then start periodic heartbeats. Returns a
+   * `stop()` that stops heartbeats and best-effort deregisters — so a service
+   * does not have to wire register/heartbeat/deregister by hand.
+   */
+  async start(opts = {}) {
+    await this.register();
+    if (opts.heartbeatMs !== 0) this.startHeartbeat(opts.heartbeatMs ?? 1e4, opts.metrics);
+    return async () => {
+      this.stopHeartbeat();
+      await this.deregister().catch(() => {
+      });
+    };
+  }
   setHealth(h) {
     this.health = h;
   }
@@ -508,7 +532,15 @@ var CeServiceAgent = class {
    * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
    */
   async handleMessage(raw, handler) {
-    const msg = import_capsule_contracts_node.ConversationMessageSchema.parse(raw);
+    let msg;
+    try {
+      msg = import_capsule_contracts_node.ConversationMessageSchema.parse(raw);
+    } catch (error) {
+      throw new CeInboundMessageValidationError(
+        error instanceof Error ? error.message : "invalid inbound ConversationMessage",
+        { cause: error }
+      );
+    }
     const out = await handler(msg);
     const reply = typeof out === "string" ? { content: out } : out;
     return import_capsule_contracts_node.ConversationMessageSchema.parse({
@@ -527,8 +559,8 @@ var CeServiceAgent = class {
       ...reply.payload ? { payload: reply.payload } : {}
     });
   }
-  post(path, body) {
-    return this.fetchJson(path, { method: "POST", body: JSON.stringify(body) });
+  post(path, body, headers) {
+    return this.fetchJson(path, { method: "POST", body: JSON.stringify(body), ...headers ? { headers } : {} });
   }
   async fetchJson(path, init) {
     const res = await this.fetchImpl(this.serverUrl + path, {
@@ -536,13 +568,137 @@ var CeServiceAgent = class {
       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;
+    if (!text) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(`server-ce ${path} returned non-JSON success response: ${text}`, { cause: error });
+    }
   }
 };
+
+// src/ce/serve.ts
+var import_node_http = require("http");
+function send(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", (c) => data += c);
+    req.on("end", () => resolve(data));
+    req.on("error", reject);
+  });
+}
+function isLocalOnlyHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+function defaultLocalAddress(host, port) {
+  if (host === "::1") return `http://[::1]:${port}`;
+  return `http://${host}:${port}`;
+}
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}
+function sendMessageError(res, error) {
+  if (error instanceof CeInboundMessageValidationError) {
+    send(res, 400, { code: "VALIDATION_FAILED", message: error.message, retryable: false });
+    return;
+  }
+  const message = error instanceof Error ? error.message : "message handler failed";
+  send(res, 500, { code: "HANDLER_FAILED", message, retryable: true });
+}
+async function serveCeService(opts) {
+  const host = opts.host ?? "0.0.0.0";
+  let agent;
+  const server = (0, import_node_http.createServer)((req, res) => {
+    void (async () => {
+      try {
+        if (req.method === "GET" && req.url === "/health") {
+          send(res, 200, { ok: true, service: opts.manifest.service.id });
+          return;
+        }
+        if (req.method === "POST" && req.url === "/messages") {
+          if (!agent) {
+            send(res, 503, { code: "NOT_READY", message: "service not registered yet", retryable: true });
+            return;
+          }
+          const raw = await readBody(req);
+          let payload;
+          try {
+            payload = raw ? JSON.parse(raw) : {};
+          } catch (error) {
+            send(res, 400, {
+              code: "VALIDATION_FAILED",
+              message: error instanceof Error ? error.message : "invalid JSON request body",
+              retryable: false
+            });
+            return;
+          }
+          const reply = await agent.handleMessage(payload, opts.handler);
+          send(res, 200, reply);
+          return;
+        }
+        send(res, 404, { code: "NOT_FOUND", message: "not found", retryable: false });
+      } catch (e) {
+        sendMessageError(res, e);
+      }
+    })();
+  });
+  await listen(server, opts.port ?? 0, host);
+  const info = server.address();
+  const port = typeof info === "object" && info ? info.port : opts.port ?? 0;
+  const address = opts.address ?? (isLocalOnlyHost(host) ? defaultLocalAddress(host, port) : void 0);
+  if (!address) {
+    await new Promise((resolve) => server.close(() => resolve()));
+    throw new Error(
+      `serveCeService requires an explicit address when host=${host}. For deployed/containerized use, pass a reachable callback URL such as http://demo-service:8080.`
+    );
+  }
+  try {
+    agent = new CeServiceAgent({
+      serverUrl: opts.serverUrl,
+      manifest: opts.manifest,
+      address,
+      instanceId: opts.instanceId,
+      registrationToken: opts.registrationToken,
+      fetchImpl: opts.fetchImpl
+    });
+    await agent.register();
+    if (opts.heartbeatMs !== 0) agent.startHeartbeat(opts.heartbeatMs ?? 1e4);
+  } catch (error) {
+    agent?.stopHeartbeat();
+    await new Promise((resolve) => server.close(() => resolve()));
+    throw error;
+  }
+  return {
+    agent,
+    address,
+    port,
+    async close() {
+      agent?.stopHeartbeat();
+      await agent?.deregister().catch(() => {
+      });
+      await new Promise((resolve) => server.close(() => resolve()));
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentApiClient,
@@ -556,5 +712,6 @@ var CeServiceAgent = class {
   FileTokenStore,
   NetworkError,
   RegistrationError,
-  XtrapeAgent
+  XtrapeAgent,
+  serveCeService
 });

package/dist/index.d.cts

@@ -277,6 +277,12 @@ interface CeServiceAgentOptions {
     address: string;
     /** optional fixed instance id; defaults to `<serviceId>-<rand>` */
     instanceId?: string;
+    /**
+     * Shared registration token. When server-ce has `SERVER_CE_REGISTRATION_TOKEN`
+     * set, registration requires it; the agent sends it as the
+     * `x-xtrape-registration-token` header on register.
+     */
+    registrationToken?: string;
     /** injectable fetch (tests); defaults to global fetch */
     fetchImpl?: typeof fetch;
 }
@@ -294,16 +300,26 @@ declare class CeServiceAgent {
     private readonly manifest;
     private readonly address;
     private readonly tenant;
+    private readonly registrationToken?;
     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 } */
+    /** POST /v1/instances { manifest, instance } (sends the registration token if set). */
     register(): Promise<{
         instanceId: string;
     }>;
+    /**
+     * Lifecycle convenience: register, then start periodic heartbeats. Returns a
+     * `stop()` that stops heartbeats and best-effort deregisters — so a service
+     * does not have to wire register/heartbeat/deregister by hand.
+     */
+    start(opts?: {
+        heartbeatMs?: number;
+        metrics?: () => Record<string, unknown>;
+    }): Promise<() => Promise<void>>;
     setHealth(h: ServiceInstanceHealth): void;
     /** POST /v1/instances/{id}/heartbeat */
     sendHeartbeat(metricsSummary?: Record<string, unknown>): Promise<void>;
@@ -321,4 +337,50 @@ declare class CeServiceAgent {
     private fetchJson;
 }
 
-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 };
+/**
+ * One-call bootstrap for an `xtrape-service`: start an HTTP listener that serves
+ * `POST /messages` (and `GET /health`), register the instance to xtrape-server-ce,
+ * and run heartbeats. Returns a handle whose `close()` stops heartbeats,
+ * deregisters, and closes the listener.
+ *
+ * Uses only `node:http` so it stays framework-agnostic. A service that already
+ * has an HTTP server can use `CeServiceAgent` directly instead.
+ */
+interface ServeCeServiceOptions {
+    /** xtrape-server-ce base URL, e.g. http://localhost:3000 */
+    serverUrl: string;
+    manifest: ServiceManifest;
+    /** business handler invoked per inbound ConversationMessage */
+    handler: CeMessageHandler;
+    /** shared registration token, if server-ce requires one */
+    registrationToken?: string;
+    /** listen port; 0 picks an ephemeral port (default 0) */
+    port?: number;
+    /** listen host (default 0.0.0.0) */
+    host?: string;
+    /**
+     * Address server-ce should call back.
+     *
+     * Required for deployed/containerized use. When omitted, the SDK only derives
+     * a default address for explicit local-only hosts such as `127.0.0.1` or
+     * `localhost`.
+     */
+    address?: string;
+    /** heartbeat interval ms; 0 disables (default 10000) */
+    heartbeatMs?: number;
+    instanceId?: string;
+    /** injectable fetch (tests); defaults to global fetch */
+    fetchImpl?: typeof fetch;
+}
+interface ServeCeServiceHandle {
+    agent: CeServiceAgent;
+    /** advertised address registered with server-ce */
+    address: string;
+    /** actual listening port */
+    port: number;
+    /** stop heartbeats, deregister (best-effort), and close the HTTP server */
+    close(): Promise<void>;
+}
+declare function serveCeService(opts: ServeCeServiceOptions): Promise<ServeCeServiceHandle>;
+
+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 ServeCeServiceHandle, type ServeCeServiceOptions, type ServiceSnapshot, type StructuredLogger, type TokenStore, type WorkerAgentOptions, type WorkerDefinition, type WorkerSnapshot, CapsuleAgent as XtrapeAgent, type XtrapeAgentOptions, serveCeService };

package/dist/index.d.ts

@@ -277,6 +277,12 @@ interface CeServiceAgentOptions {
     address: string;
     /** optional fixed instance id; defaults to `<serviceId>-<rand>` */
     instanceId?: string;
+    /**
+     * Shared registration token. When server-ce has `SERVER_CE_REGISTRATION_TOKEN`
+     * set, registration requires it; the agent sends it as the
+     * `x-xtrape-registration-token` header on register.
+     */
+    registrationToken?: string;
     /** injectable fetch (tests); defaults to global fetch */
     fetchImpl?: typeof fetch;
 }
@@ -294,16 +300,26 @@ declare class CeServiceAgent {
     private readonly manifest;
     private readonly address;
     private readonly tenant;
+    private readonly registrationToken?;
     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 } */
+    /** POST /v1/instances { manifest, instance } (sends the registration token if set). */
     register(): Promise<{
         instanceId: string;
     }>;
+    /**
+     * Lifecycle convenience: register, then start periodic heartbeats. Returns a
+     * `stop()` that stops heartbeats and best-effort deregisters — so a service
+     * does not have to wire register/heartbeat/deregister by hand.
+     */
+    start(opts?: {
+        heartbeatMs?: number;
+        metrics?: () => Record<string, unknown>;
+    }): Promise<() => Promise<void>>;
     setHealth(h: ServiceInstanceHealth): void;
     /** POST /v1/instances/{id}/heartbeat */
     sendHeartbeat(metricsSummary?: Record<string, unknown>): Promise<void>;
@@ -321,4 +337,50 @@ declare class CeServiceAgent {
     private fetchJson;
 }
 
-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 };
+/**
+ * One-call bootstrap for an `xtrape-service`: start an HTTP listener that serves
+ * `POST /messages` (and `GET /health`), register the instance to xtrape-server-ce,
+ * and run heartbeats. Returns a handle whose `close()` stops heartbeats,
+ * deregisters, and closes the listener.
+ *
+ * Uses only `node:http` so it stays framework-agnostic. A service that already
+ * has an HTTP server can use `CeServiceAgent` directly instead.
+ */
+interface ServeCeServiceOptions {
+    /** xtrape-server-ce base URL, e.g. http://localhost:3000 */
+    serverUrl: string;
+    manifest: ServiceManifest;
+    /** business handler invoked per inbound ConversationMessage */
+    handler: CeMessageHandler;
+    /** shared registration token, if server-ce requires one */
+    registrationToken?: string;
+    /** listen port; 0 picks an ephemeral port (default 0) */
+    port?: number;
+    /** listen host (default 0.0.0.0) */
+    host?: string;
+    /**
+     * Address server-ce should call back.
+     *
+     * Required for deployed/containerized use. When omitted, the SDK only derives
+     * a default address for explicit local-only hosts such as `127.0.0.1` or
+     * `localhost`.
+     */
+    address?: string;
+    /** heartbeat interval ms; 0 disables (default 10000) */
+    heartbeatMs?: number;
+    instanceId?: string;
+    /** injectable fetch (tests); defaults to global fetch */
+    fetchImpl?: typeof fetch;
+}
+interface ServeCeServiceHandle {
+    agent: CeServiceAgent;
+    /** advertised address registered with server-ce */
+    address: string;
+    /** actual listening port */
+    port: number;
+    /** stop heartbeats, deregister (best-effort), and close the HTTP server */
+    close(): Promise<void>;
+}
+declare function serveCeService(opts: ServeCeServiceOptions): Promise<ServeCeServiceHandle>;
+
+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 ServeCeServiceHandle, type ServeCeServiceOptions, type ServiceSnapshot, type StructuredLogger, type TokenStore, type WorkerAgentOptions, type WorkerDefinition, type WorkerSnapshot, CapsuleAgent as XtrapeAgent, type XtrapeAgentOptions, serveCeService };

package/dist/index.js

@@ -398,6 +398,12 @@ import {
   ServiceInstanceSchema,
   ConversationMessageSchema
 } from "@xtrape/capsule-contracts-node";
+var CeInboundMessageValidationError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CeInboundMessageValidationError";
+  }
+};
 var CeServiceAgent = class {
   serviceId;
   instanceId;
@@ -405,6 +411,7 @@ var CeServiceAgent = class {
   manifest;
   address;
   tenant;
+  registrationToken;
   fetchImpl;
   health = "HEALTHY";
   hbTimer;
@@ -415,6 +422,7 @@ var CeServiceAgent = class {
     this.tenant = opts.manifest.tenant ?? "default";
     this.serviceId = opts.manifest.service.id;
     this.instanceId = opts.instanceId ?? `${this.serviceId}-${randomUUID().slice(0, 8)}`;
+    this.registrationToken = opts.registrationToken;
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
   /** The ServiceInstance this agent reports on register/heartbeat. */
@@ -429,11 +437,26 @@ var CeServiceAgent = class {
       health: this.health
     });
   }
-  /** POST /v1/instances { manifest, instance } */
+  /** POST /v1/instances { manifest, instance } (sends the registration token if set). */
   async register() {
-    await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() });
+    const headers = this.registrationToken ? { "x-xtrape-registration-token": this.registrationToken } : void 0;
+    await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() }, headers);
     return { instanceId: this.instanceId };
   }
+  /**
+   * Lifecycle convenience: register, then start periodic heartbeats. Returns a
+   * `stop()` that stops heartbeats and best-effort deregisters — so a service
+   * does not have to wire register/heartbeat/deregister by hand.
+   */
+  async start(opts = {}) {
+    await this.register();
+    if (opts.heartbeatMs !== 0) this.startHeartbeat(opts.heartbeatMs ?? 1e4, opts.metrics);
+    return async () => {
+      this.stopHeartbeat();
+      await this.deregister().catch(() => {
+      });
+    };
+  }
   setHealth(h) {
     this.health = h;
   }
@@ -475,7 +498,15 @@ var CeServiceAgent = class {
    * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
    */
   async handleMessage(raw, handler) {
-    const msg = ConversationMessageSchema.parse(raw);
+    let msg;
+    try {
+      msg = ConversationMessageSchema.parse(raw);
+    } catch (error) {
+      throw new CeInboundMessageValidationError(
+        error instanceof Error ? error.message : "invalid inbound ConversationMessage",
+        { cause: error }
+      );
+    }
     const out = await handler(msg);
     const reply = typeof out === "string" ? { content: out } : out;
     return ConversationMessageSchema.parse({
@@ -494,8 +525,8 @@ var CeServiceAgent = class {
       ...reply.payload ? { payload: reply.payload } : {}
     });
   }
-  post(path, body) {
-    return this.fetchJson(path, { method: "POST", body: JSON.stringify(body) });
+  post(path, body, headers) {
+    return this.fetchJson(path, { method: "POST", body: JSON.stringify(body), ...headers ? { headers } : {} });
   }
   async fetchJson(path, init) {
     const res = await this.fetchImpl(this.serverUrl + path, {
@@ -503,13 +534,137 @@ var CeServiceAgent = class {
       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;
+    if (!text) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(`server-ce ${path} returned non-JSON success response: ${text}`, { cause: error });
+    }
   }
 };
+
+// src/ce/serve.ts
+import { createServer } from "http";
+function send(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", (c) => data += c);
+    req.on("end", () => resolve(data));
+    req.on("error", reject);
+  });
+}
+function isLocalOnlyHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+function defaultLocalAddress(host, port) {
+  if (host === "::1") return `http://[::1]:${port}`;
+  return `http://${host}:${port}`;
+}
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}
+function sendMessageError(res, error) {
+  if (error instanceof CeInboundMessageValidationError) {
+    send(res, 400, { code: "VALIDATION_FAILED", message: error.message, retryable: false });
+    return;
+  }
+  const message = error instanceof Error ? error.message : "message handler failed";
+  send(res, 500, { code: "HANDLER_FAILED", message, retryable: true });
+}
+async function serveCeService(opts) {
+  const host = opts.host ?? "0.0.0.0";
+  let agent;
+  const server = createServer((req, res) => {
+    void (async () => {
+      try {
+        if (req.method === "GET" && req.url === "/health") {
+          send(res, 200, { ok: true, service: opts.manifest.service.id });
+          return;
+        }
+        if (req.method === "POST" && req.url === "/messages") {
+          if (!agent) {
+            send(res, 503, { code: "NOT_READY", message: "service not registered yet", retryable: true });
+            return;
+          }
+          const raw = await readBody(req);
+          let payload;
+          try {
+            payload = raw ? JSON.parse(raw) : {};
+          } catch (error) {
+            send(res, 400, {
+              code: "VALIDATION_FAILED",
+              message: error instanceof Error ? error.message : "invalid JSON request body",
+              retryable: false
+            });
+            return;
+          }
+          const reply = await agent.handleMessage(payload, opts.handler);
+          send(res, 200, reply);
+          return;
+        }
+        send(res, 404, { code: "NOT_FOUND", message: "not found", retryable: false });
+      } catch (e) {
+        sendMessageError(res, e);
+      }
+    })();
+  });
+  await listen(server, opts.port ?? 0, host);
+  const info = server.address();
+  const port = typeof info === "object" && info ? info.port : opts.port ?? 0;
+  const address = opts.address ?? (isLocalOnlyHost(host) ? defaultLocalAddress(host, port) : void 0);
+  if (!address) {
+    await new Promise((resolve) => server.close(() => resolve()));
+    throw new Error(
+      `serveCeService requires an explicit address when host=${host}. For deployed/containerized use, pass a reachable callback URL such as http://demo-service:8080.`
+    );
+  }
+  try {
+    agent = new CeServiceAgent({
+      serverUrl: opts.serverUrl,
+      manifest: opts.manifest,
+      address,
+      instanceId: opts.instanceId,
+      registrationToken: opts.registrationToken,
+      fetchImpl: opts.fetchImpl
+    });
+    await agent.register();
+    if (opts.heartbeatMs !== 0) agent.startHeartbeat(opts.heartbeatMs ?? 1e4);
+  } catch (error) {
+    agent?.stopHeartbeat();
+    await new Promise((resolve) => server.close(() => resolve()));
+    throw error;
+  }
+  return {
+    agent,
+    address,
+    port,
+    async close() {
+      agent?.stopHeartbeat();
+      await agent?.deregister().catch(() => {
+      });
+      await new Promise((resolve) => server.close(() => resolve()));
+    }
+  };
+}
 export {
   AgentApiClient,
   AgentApiError,
@@ -522,5 +677,6 @@ export {
   FileTokenStore,
   NetworkError,
   RegistrationError,
-  CapsuleAgent as XtrapeAgent
+  CapsuleAgent as XtrapeAgent,
+  serveCeService
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Node.js Embedded Agent SDK for reporting Workers to the Xtrape control plane.",
   "keywords": [
     "xtrape",
@@ -13,11 +13,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/xtrape-com/xtrape-capsule-agent-node.git"
+    "url": "git+https://forgejo.xtrape.com/xtrape/xtrape-agent-nodejs.git"
   },
-  "homepage": "https://github.com/xtrape-com/xtrape-capsule-agent-node#readme",
+  "homepage": "https://forgejo.xtrape.com/xtrape/xtrape-agent-nodejs#readme",
   "bugs": {
-    "url": "https://github.com/xtrape-com/xtrape-capsule-agent-node/issues"
+    "url": "https://forgejo.xtrape.com/xtrape/xtrape-agent-nodejs/issues"
   },
   "type": "module",
   "main": "./dist/index.cjs",
@@ -44,7 +44,7 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "^0.5.0"
+    "@xtrape/capsule-contracts-node": "^0.6.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",