@xtrape/capsule-agent-node 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionPrepareResult, PublishBusEventRequest, RuntimeKind, HealthReportInput, ConfigItemInput, ActionDefinitionInput, PublishBusEventResponse, 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,9 +103,12 @@ interface TokenStore {
     clear(): Promise<void>;
 }
 type ServiceSnapshot = ReportedService;
-/** Experimental v0.4 Capsule Bus publish input. Subject to change before v1.0. */
-type PublishBusEventInput = Omit<PublishBusEventRequest, "sourceServiceCode"> & {
+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;
 
@@ -114,11 +133,12 @@ declare class CapsuleAgent {
     stop(): Promise<void>;
     private loop;
     private ensureRegistered;
+    private workerDefinition;
     private serviceSnapshot;
     runHealth(): Promise<HealthReportInput>;
-    /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+    /** Legacy v0.4 event-routing compatibility hook. Subject to change before v1.0. */
     publishBusEvent(input: PublishBusEventInput): Promise<PublishBusEventResult>;
-    private reportService;
+    private reportWorker;
     private heartbeat;
     private pollOnce;
     private execute;
@@ -156,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);
@@ -201,6 +222,10 @@ 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_EXECUTE" | "ACTION_PREPARE";
         id: string;
@@ -216,7 +241,7 @@ declare class AgentApiClient {
         completedAt?: string | null | undefined;
     }[]>;
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
-    /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+    /** 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;
@@ -233,4 +258,129 @@ declare class AgentApiClient {
     }>;
 }
 
-export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, BusDepthExceededError, BusDisabledError, BusRateLimitedError, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type PublishBusEventInput, type PublishBusEventResult, type RegisteredAction, RegistrationError, type ServiceSnapshot, type StructuredLogger, type TokenStore };
+/**
+ * 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;
+    /**
+     * 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;
+}
+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 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 } (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>;
+    /** 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;
+}
+
+/**
+ * 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

@@ -101,13 +101,22 @@ 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) });
   }
-  /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+  /** 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" }) });
   }
@@ -180,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;
@@ -213,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) {
@@ -222,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());
     }
   }
@@ -251,38 +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();
   }
-  /** Experimental v0.4 Capsule Bus publish hook. Subject to change before v1.0. */
+  /** 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 Capsule Bus events.");
-    const sourceServiceCode = input.sourceServiceCode ?? this.options.service.code;
+    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 reportService() {
+  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;
@@ -368,6 +390,281 @@ 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 CeInboundMessageValidationError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CeInboundMessageValidationError";
+  }
+};
+var CeServiceAgent = class {
+  serviceId;
+  instanceId;
+  serverUrl;
+  manifest;
+  address;
+  tenant;
+  registrationToken;
+  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.registrationToken = opts.registrationToken;
+    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 } (sends the registration token if set). */
+  async register() {
+    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;
+  }
+  /** 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) {
+    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({
+      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, 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, {
+      ...init,
+      headers: { "content-type": "application/json", ...init.headers ?? {} }
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`server-ce ${path} -> ${res.status}: ${text}`);
+    }
+    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,
@@ -376,7 +673,10 @@ export {
   BusDisabledError,
   BusRateLimitedError,
   CapsuleAgent,
+  CeServiceAgent,
   FileTokenStore,
   NetworkError,
-  RegistrationError
+  RegistrationError,
+  CapsuleAgent as XtrapeAgent,
+  serveCeService
 };