@xtrape/capsule-agent-node 0.5.0 → 0.6.1

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,78 @@ 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`, action endpoints,
+`GET /health`),
+registers the instance (sending the registration token if server-ce requires
+one), stores the per-instance access token returned by server-ce, and runs
+authenticated 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,
+  // Optional compatibility fallback for older server-ce deployments. Current
+  // server-ce returns a per-instance access token during registration, and the
+  // SDK uses that token first for heartbeat/deregister.
+  controlToken: process.env.SERVER_CE_CONTROL_TOKEN,
+  // Optional: require authenticated callbacks from server-ce on POST /messages
+  // and action endpoints (x-xtrape-service-callback-token or Authorization: Bearer).
+  callbackToken: process.env.SERVICE_CALLBACK_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,
+  controlToken: process.env.SERVER_CE_CONTROL_TOKEN, // compatibility fallback only
+  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 +471,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 +527,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,7 +445,10 @@ var CeServiceAgent = class {
   manifest;
   address;
   tenant;
+  registrationToken;
+  controlToken;
   fetchImpl;
+  accessToken;
   health = "HEALTHY";
   hbTimer;
   constructor(opts) {
@@ -448,8 +458,19 @@ 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.controlToken = opts.controlToken;
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
+  /**
+   * Header carrying the per-instance access token returned by registration.
+   * Falls back to the transitional control token for compatibility with older
+   * server-ce deployments that did not mint per-instance access tokens yet.
+   */
+  lifecycleAuthHeaders() {
+    if (this.accessToken) return { "x-xtrape-access-token": this.accessToken };
+    return this.controlToken ? { "x-xtrape-control-token": this.controlToken } : void 0;
+  }
   /** The ServiceInstance this agent reports on register/heartbeat. */
   instance() {
     return import_capsule_contracts_node.ServiceInstanceSchema.parse({
@@ -462,10 +483,29 @@ 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() });
-    return { instanceId: this.instanceId };
+    const headers = this.registrationToken ? { "x-xtrape-registration-token": this.registrationToken } : void 0;
+    const response = await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() }, headers);
+    const accessToken = typeof response === "object" && response !== null && "accessToken" in response ? response.accessToken : void 0;
+    if (typeof accessToken === "string" && accessToken.length > 0) {
+      this.accessToken = accessToken;
+    }
+    return { instanceId: this.instanceId, ...this.accessToken ? { accessToken: this.accessToken } : {} };
+  }
+  /**
+   * 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;
@@ -481,7 +521,7 @@ var CeServiceAgent = class {
       health: this.health,
       ...metricsSummary ? { metricsSummary } : {}
     };
-    await this.post(`/v1/instances/${encodeURIComponent(this.instanceId)}/heartbeat`, hb);
+    await this.post(`/v1/instances/${encodeURIComponent(this.instanceId)}/heartbeat`, hb, this.lifecycleAuthHeaders());
   }
   /** Start a periodic heartbeat; returns a stop function. Timer is unref'd. */
   startHeartbeat(intervalMs = 1e4, metrics) {
@@ -501,14 +541,25 @@ var CeServiceAgent = class {
   }
   /** DELETE /v1/instances/{id} — graceful deregister. */
   async deregister() {
-    await this.fetchJson(`/v1/instances/${encodeURIComponent(this.instanceId)}`, { method: "DELETE" });
+    await this.fetchJson(`/v1/instances/${encodeURIComponent(this.instanceId)}`, {
+      method: "DELETE",
+      ...this.lifecycleAuthHeaders() ? { headers: this.lifecycleAuthHeaders() } : {}
+    });
   }
   /**
    * 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);
+    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 +578,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 +587,240 @@ 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 extractCallbackToken(req) {
+  const raw = req.headers["x-xtrape-service-callback-token"];
+  const header = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof header === "string" && header.length > 0) return header;
+  const auth = req.headers["authorization"];
+  if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+    const token = auth.slice("Bearer ".length).trim();
+    return token.length > 0 ? token : void 0;
+  }
+  return void 0;
+}
+function requireCallbackAuthorized(req, res, callbackToken) {
+  if (!callbackToken || extractCallbackToken(req) === callbackToken) return true;
+  send(res, 401, {
+    code: "UNAUTHORIZED",
+    message: "service callback token is missing or invalid",
+    retryable: false
+  });
+  return false;
+}
+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 });
+}
+function sendHandlerError(res, error) {
+  const message = error instanceof Error ? error.message : "action handler failed";
+  send(res, 500, { code: "ACTION_FAILED", message, retryable: false });
+}
+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;
+          }
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) 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;
+        }
+        if (req.method === "GET" && req.url === "/actions") {
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) return;
+          send(
+            res,
+            200,
+            (opts.actions ?? []).map((action) => ({
+              name: action.name,
+              label: action.label,
+              description: action.description,
+              category: action.category,
+              order: action.order,
+              requiresPrepare: typeof action.prepare === "function" ? true : void 0,
+              inputSchema: action.inputSchema
+            }))
+          );
+          return;
+        }
+        const prepareMatch = req.url?.match(/^\/actions\/([^/]+)\/prepare$/);
+        if (req.method === "POST" && prepareMatch) {
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) return;
+          const name = decodeURIComponent(prepareMatch[1]);
+          const action = (opts.actions ?? []).find((candidate) => candidate.name === name);
+          if (!action) {
+            send(res, 404, { code: "ACTION_NOT_FOUND", message: `action ${name} not found`, retryable: false });
+            return;
+          }
+          if (typeof action.prepare !== "function") {
+            send(res, 400, { code: "ACTION_NOT_PREPARABLE", message: `action ${name} has no prepare step`, retryable: false });
+            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;
+          }
+          try {
+            send(res, 200, await action.prepare(payload) ?? {});
+          } catch (error) {
+            sendHandlerError(res, error);
+          }
+          return;
+        }
+        const executeMatch = req.url?.match(/^\/actions\/([^/]+)\/execute$/);
+        if (req.method === "POST" && executeMatch) {
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) return;
+          const name = decodeURIComponent(executeMatch[1]);
+          const action = (opts.actions ?? []).find((candidate) => candidate.name === name);
+          if (!action) {
+            send(res, 404, { code: "ACTION_NOT_FOUND", message: `action ${name} not found`, retryable: false });
+            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;
+          }
+          try {
+            send(res, 200, await action.execute(payload));
+          } catch (error) {
+            sendHandlerError(res, error);
+          }
+          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,
+      controlToken: opts.controlToken,
+      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 +834,6 @@ var CeServiceAgent = class {
   FileTokenStore,
   NetworkError,
   RegistrationError,
-  XtrapeAgent
+  XtrapeAgent,
+  serveCeService
 });

package/dist/index.d.cts

@@ -277,9 +277,27 @@ 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;
+    /**
+     * 0.6.x control-plane token. When server-ce has `SERVER_CE_CONTROL_TOKEN` set,
+     * older non-registration routes may require it. Current server-ce returns a
+     * per-instance access token during registration and the agent uses that token
+     * for heartbeat/deregister; this control token is a compatibility fallback
+     * (see xtrape-server-ce#12).
+     */
+    controlToken?: string;
     /** injectable fetch (tests); defaults to global fetch */
     fetchImpl?: typeof fetch;
 }
+interface CeServiceRegistrationResult {
+    instanceId: string;
+    accessToken?: string;
+}
 type CeMessageReply = string | {
     content: string;
     messageType?: ConversationMessage["messageType"];
@@ -294,16 +312,32 @@ declare class CeServiceAgent {
     private readonly manifest;
     private readonly address;
     private readonly tenant;
+    private readonly registrationToken?;
+    private readonly controlToken?;
     private readonly fetchImpl;
+    private accessToken?;
     private health;
     private hbTimer?;
     constructor(opts: CeServiceAgentOptions);
+    /**
+     * Header carrying the per-instance access token returned by registration.
+     * Falls back to the transitional control token for compatibility with older
+     * server-ce deployments that did not mint per-instance access tokens yet.
+     */
+    private lifecycleAuthHeaders;
     /** The ServiceInstance this agent reports on register/heartbeat. */
     instance(): ServiceInstance;
-    /** POST /v1/instances { manifest, instance } */
-    register(): Promise<{
-        instanceId: string;
-    }>;
+    /** POST /v1/instances { manifest, instance } (sends the registration token if set). */
+    register(): Promise<CeServiceRegistrationResult>;
+    /**
+     * 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 +355,97 @@ 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`, action endpoints (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;
+    /** Optional CE action handlers exposed over GET /actions, POST /actions/:name/prepare, and POST /actions/:name/execute. */
+    actions?: CeServiceActionDefinition[];
+    /** shared registration token, if server-ce requires one */
+    registrationToken?: string;
+    /**
+     * 0.6.x control-plane token forwarded to server-ce on heartbeat/deregister
+     * only as a compatibility fallback. Current server-ce returns a per-instance
+     * access token during registration and the SDK uses that first.
+     */
+    controlToken?: string;
+    /**
+     * Optional inbound callback token. When set, `POST /messages` and action
+     * endpoints (`GET /actions`, `POST /actions/:name/prepare`,
+     * `POST /actions/:name/execute`) must include
+     * `x-xtrape-service-callback-token: <callbackToken>` (or
+     * `Authorization: Bearer <callbackToken>`); otherwise the request is rejected
+     * with 401. Lets a service require authenticated callbacks from server-ce.
+     */
+    callbackToken?: 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;
+}
+/**
+ * What a two-phase action's prepare step returns to the operator UI:
+ * `initialPayload` seeds the execute form, `currentState` is contextual
+ * data to display (e.g. the accounts/balances the decision is based on),
+ * and `inputSchema` optionally overrides the static schema with live options.
+ */
+interface CeActionPrepareResult {
+    /** Longer operator-facing explanation shown on the execution screen. */
+    longDescription?: string;
+    initialPayload?: Record<string, unknown>;
+    currentState?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+}
+interface CeServiceActionDefinition {
+    name: string;
+    label: string;
+    description?: string;
+    /** Operator-facing grouping shown by Panel (capsule ActionDefinition heritage), e.g. "diagnostics". */
+    category?: string;
+    /** Display order within the category; lower sorts first. */
+    order?: number;
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Optional prepare step. When present the action is two-phase: server-ce
+     * calls this before the operator fills the form to fetch live defaults and
+     * current state. Advertised as `requiresPrepare: true` in the action list.
+     */
+    prepare?(input?: unknown): CeActionPrepareResult | Promise<CeActionPrepareResult>;
+    execute(input: unknown): unknown | Promise<unknown>;
+}
+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 CeActionPrepareResult, type CeMessageHandler, type CeMessageReply, type CeServiceActionDefinition, 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,9 +277,27 @@ 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;
+    /**
+     * 0.6.x control-plane token. When server-ce has `SERVER_CE_CONTROL_TOKEN` set,
+     * older non-registration routes may require it. Current server-ce returns a
+     * per-instance access token during registration and the agent uses that token
+     * for heartbeat/deregister; this control token is a compatibility fallback
+     * (see xtrape-server-ce#12).
+     */
+    controlToken?: string;
     /** injectable fetch (tests); defaults to global fetch */
     fetchImpl?: typeof fetch;
 }
+interface CeServiceRegistrationResult {
+    instanceId: string;
+    accessToken?: string;
+}
 type CeMessageReply = string | {
     content: string;
     messageType?: ConversationMessage["messageType"];
@@ -294,16 +312,32 @@ declare class CeServiceAgent {
     private readonly manifest;
     private readonly address;
     private readonly tenant;
+    private readonly registrationToken?;
+    private readonly controlToken?;
     private readonly fetchImpl;
+    private accessToken?;
     private health;
     private hbTimer?;
     constructor(opts: CeServiceAgentOptions);
+    /**
+     * Header carrying the per-instance access token returned by registration.
+     * Falls back to the transitional control token for compatibility with older
+     * server-ce deployments that did not mint per-instance access tokens yet.
+     */
+    private lifecycleAuthHeaders;
     /** The ServiceInstance this agent reports on register/heartbeat. */
     instance(): ServiceInstance;
-    /** POST /v1/instances { manifest, instance } */
-    register(): Promise<{
-        instanceId: string;
-    }>;
+    /** POST /v1/instances { manifest, instance } (sends the registration token if set). */
+    register(): Promise<CeServiceRegistrationResult>;
+    /**
+     * 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 +355,97 @@ 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`, action endpoints (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;
+    /** Optional CE action handlers exposed over GET /actions, POST /actions/:name/prepare, and POST /actions/:name/execute. */
+    actions?: CeServiceActionDefinition[];
+    /** shared registration token, if server-ce requires one */
+    registrationToken?: string;
+    /**
+     * 0.6.x control-plane token forwarded to server-ce on heartbeat/deregister
+     * only as a compatibility fallback. Current server-ce returns a per-instance
+     * access token during registration and the SDK uses that first.
+     */
+    controlToken?: string;
+    /**
+     * Optional inbound callback token. When set, `POST /messages` and action
+     * endpoints (`GET /actions`, `POST /actions/:name/prepare`,
+     * `POST /actions/:name/execute`) must include
+     * `x-xtrape-service-callback-token: <callbackToken>` (or
+     * `Authorization: Bearer <callbackToken>`); otherwise the request is rejected
+     * with 401. Lets a service require authenticated callbacks from server-ce.
+     */
+    callbackToken?: 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;
+}
+/**
+ * What a two-phase action's prepare step returns to the operator UI:
+ * `initialPayload` seeds the execute form, `currentState` is contextual
+ * data to display (e.g. the accounts/balances the decision is based on),
+ * and `inputSchema` optionally overrides the static schema with live options.
+ */
+interface CeActionPrepareResult {
+    /** Longer operator-facing explanation shown on the execution screen. */
+    longDescription?: string;
+    initialPayload?: Record<string, unknown>;
+    currentState?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+}
+interface CeServiceActionDefinition {
+    name: string;
+    label: string;
+    description?: string;
+    /** Operator-facing grouping shown by Panel (capsule ActionDefinition heritage), e.g. "diagnostics". */
+    category?: string;
+    /** Display order within the category; lower sorts first. */
+    order?: number;
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Optional prepare step. When present the action is two-phase: server-ce
+     * calls this before the operator fills the form to fetch live defaults and
+     * current state. Advertised as `requiresPrepare: true` in the action list.
+     */
+    prepare?(input?: unknown): CeActionPrepareResult | Promise<CeActionPrepareResult>;
+    execute(input: unknown): unknown | Promise<unknown>;
+}
+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 CeActionPrepareResult, type CeMessageHandler, type CeMessageReply, type CeServiceActionDefinition, 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,7 +411,10 @@ var CeServiceAgent = class {
   manifest;
   address;
   tenant;
+  registrationToken;
+  controlToken;
   fetchImpl;
+  accessToken;
   health = "HEALTHY";
   hbTimer;
   constructor(opts) {
@@ -415,8 +424,19 @@ 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.controlToken = opts.controlToken;
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
+  /**
+   * Header carrying the per-instance access token returned by registration.
+   * Falls back to the transitional control token for compatibility with older
+   * server-ce deployments that did not mint per-instance access tokens yet.
+   */
+  lifecycleAuthHeaders() {
+    if (this.accessToken) return { "x-xtrape-access-token": this.accessToken };
+    return this.controlToken ? { "x-xtrape-control-token": this.controlToken } : void 0;
+  }
   /** The ServiceInstance this agent reports on register/heartbeat. */
   instance() {
     return ServiceInstanceSchema.parse({
@@ -429,10 +449,29 @@ 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() });
-    return { instanceId: this.instanceId };
+    const headers = this.registrationToken ? { "x-xtrape-registration-token": this.registrationToken } : void 0;
+    const response = await this.post("/v1/instances", { manifest: this.manifest, instance: this.instance() }, headers);
+    const accessToken = typeof response === "object" && response !== null && "accessToken" in response ? response.accessToken : void 0;
+    if (typeof accessToken === "string" && accessToken.length > 0) {
+      this.accessToken = accessToken;
+    }
+    return { instanceId: this.instanceId, ...this.accessToken ? { accessToken: this.accessToken } : {} };
+  }
+  /**
+   * 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;
@@ -448,7 +487,7 @@ var CeServiceAgent = class {
       health: this.health,
       ...metricsSummary ? { metricsSummary } : {}
     };
-    await this.post(`/v1/instances/${encodeURIComponent(this.instanceId)}/heartbeat`, hb);
+    await this.post(`/v1/instances/${encodeURIComponent(this.instanceId)}/heartbeat`, hb, this.lifecycleAuthHeaders());
   }
   /** Start a periodic heartbeat; returns a stop function. Timer is unref'd. */
   startHeartbeat(intervalMs = 1e4, metrics) {
@@ -468,14 +507,25 @@ var CeServiceAgent = class {
   }
   /** DELETE /v1/instances/{id} — graceful deregister. */
   async deregister() {
-    await this.fetchJson(`/v1/instances/${encodeURIComponent(this.instanceId)}`, { method: "DELETE" });
+    await this.fetchJson(`/v1/instances/${encodeURIComponent(this.instanceId)}`, {
+      method: "DELETE",
+      ...this.lifecycleAuthHeaders() ? { headers: this.lifecycleAuthHeaders() } : {}
+    });
   }
   /**
    * 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);
+    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 +544,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 +553,240 @@ 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 extractCallbackToken(req) {
+  const raw = req.headers["x-xtrape-service-callback-token"];
+  const header = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof header === "string" && header.length > 0) return header;
+  const auth = req.headers["authorization"];
+  if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+    const token = auth.slice("Bearer ".length).trim();
+    return token.length > 0 ? token : void 0;
+  }
+  return void 0;
+}
+function requireCallbackAuthorized(req, res, callbackToken) {
+  if (!callbackToken || extractCallbackToken(req) === callbackToken) return true;
+  send(res, 401, {
+    code: "UNAUTHORIZED",
+    message: "service callback token is missing or invalid",
+    retryable: false
+  });
+  return false;
+}
+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 });
+}
+function sendHandlerError(res, error) {
+  const message = error instanceof Error ? error.message : "action handler failed";
+  send(res, 500, { code: "ACTION_FAILED", message, retryable: false });
+}
+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;
+          }
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) 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;
+        }
+        if (req.method === "GET" && req.url === "/actions") {
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) return;
+          send(
+            res,
+            200,
+            (opts.actions ?? []).map((action) => ({
+              name: action.name,
+              label: action.label,
+              description: action.description,
+              category: action.category,
+              order: action.order,
+              requiresPrepare: typeof action.prepare === "function" ? true : void 0,
+              inputSchema: action.inputSchema
+            }))
+          );
+          return;
+        }
+        const prepareMatch = req.url?.match(/^\/actions\/([^/]+)\/prepare$/);
+        if (req.method === "POST" && prepareMatch) {
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) return;
+          const name = decodeURIComponent(prepareMatch[1]);
+          const action = (opts.actions ?? []).find((candidate) => candidate.name === name);
+          if (!action) {
+            send(res, 404, { code: "ACTION_NOT_FOUND", message: `action ${name} not found`, retryable: false });
+            return;
+          }
+          if (typeof action.prepare !== "function") {
+            send(res, 400, { code: "ACTION_NOT_PREPARABLE", message: `action ${name} has no prepare step`, retryable: false });
+            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;
+          }
+          try {
+            send(res, 200, await action.prepare(payload) ?? {});
+          } catch (error) {
+            sendHandlerError(res, error);
+          }
+          return;
+        }
+        const executeMatch = req.url?.match(/^\/actions\/([^/]+)\/execute$/);
+        if (req.method === "POST" && executeMatch) {
+          if (!requireCallbackAuthorized(req, res, opts.callbackToken)) return;
+          const name = decodeURIComponent(executeMatch[1]);
+          const action = (opts.actions ?? []).find((candidate) => candidate.name === name);
+          if (!action) {
+            send(res, 404, { code: "ACTION_NOT_FOUND", message: `action ${name} not found`, retryable: false });
+            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;
+          }
+          try {
+            send(res, 200, await action.execute(payload));
+          } catch (error) {
+            sendHandlerError(res, error);
+          }
+          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,
+      controlToken: opts.controlToken,
+      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 +799,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.1",
   "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",