@xtrape/capsule-agent-node 0.6.0 → 0.6.2

package/README.md

@@ -48,9 +48,11 @@ legacy `Capsule` concept.
 
 ### One-call bootstrap
 
-`serveCeService` starts an HTTP listener (`POST /messages`, `GET /health`),
+`serveCeService` starts an HTTP listener (`POST /messages`, action endpoints,
+`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:
+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
@@ -63,6 +65,13 @@ 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",
@@ -79,6 +88,38 @@ const svc = await serveCeService({
 process.on("SIGTERM", () => void svc.close()); // stop heartbeat + deregister + close
 ```
 
+### CE service actions
+
+Pass `actions` to expose operator-triggerable operations over `GET /actions`,
+`POST /actions/:name/prepare`, and `POST /actions/:name/execute`:
+
+```ts
+const svc = await serveCeService({
+  // ...as above
+  actions: [
+    {
+      name: "relogin",
+      label: "Re-login account",
+      // Optional two-phase prepare: fetch live defaults/current state before
+      // the operator fills the form (advertised as requiresPrepare: true).
+      prepare: async () => ({ initialPayload: { accountId: "acc-1" } }),
+      execute: async (input) => ({ ok: true }),
+    },
+    {
+      name: "full-sync",
+      label: "Full re-sync",
+      // Long-running action (server-ce#41 Stage B): when the pushed execute
+      // carries x-xtrape-command-id, the SDK replies 202 RUNNING immediately,
+      // runs execute in the background, and reports the outcome to server-ce
+      // with the per-instance access token. Against an older server-ce
+      // (no header) the action falls back to synchronous execution.
+      async: true,
+      execute: async (input) => runFullSync(input),
+    },
+  ],
+});
+```
+
 ### Lower-level agent
 
 When the service already runs its own HTTP server, use `CeServiceAgent` directly:
@@ -89,6 +130,7 @@ 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,
 });

package/dist/index.cjs

@@ -446,7 +446,9 @@ var CeServiceAgent = class {
   address;
   tenant;
   registrationToken;
+  controlToken;
   fetchImpl;
+  accessToken;
   health = "HEALTHY";
   hbTimer;
   constructor(opts) {
@@ -457,8 +459,18 @@ var CeServiceAgent = class {
     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({
@@ -474,8 +486,12 @@ var CeServiceAgent = class {
   /** 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 };
+    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
@@ -505,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) {
@@ -525,7 +541,31 @@ 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() } : {}
+    });
+  }
+  /**
+   * Report the outcome of an async action (server-ce#41 Stage B):
+   * POST /v1/instances/{instanceId}/commands/{commandId}/result using the
+   * per-instance access token. `outcome.result` carries the action payload for
+   * COMPLETED; errorCode/errorMessage describe a FAILED run.
+   */
+  async reportCommandResult(commandId, outcome) {
+    const body = {
+      contractVersion: import_capsule_contracts_node.CE_CONTRACT_VERSION,
+      commandId,
+      status: outcome.status,
+      ...outcome.result !== void 0 ? { result: outcome.result } : {},
+      ...outcome.errorCode ? { errorCode: outcome.errorCode } : {},
+      ...outcome.errorMessage ? { errorMessage: outcome.errorMessage } : {}
+    };
+    await this.post(
+      `/v1/instances/${encodeURIComponent(this.instanceId)}/commands/${encodeURIComponent(commandId)}/result`,
+      body,
+      this.lifecycleAuthHeaders()
+    );
   }
   /**
    * Validate an inbound message, run the handler, and build the reply message
@@ -582,6 +622,7 @@ var CeServiceAgent = class {
 
 // src/ce/serve.ts
 var import_node_http = require("http");
+var import_capsule_contracts_node2 = require("@xtrape/capsule-contracts-node");
 function send(res, status, body) {
   res.writeHead(status, { "content-type": "application/json" });
   res.end(JSON.stringify(body));
@@ -597,6 +638,26 @@ function readBody(req) {
 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}`;
@@ -624,6 +685,10 @@ function sendMessageError(res, error) {
   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;
@@ -639,6 +704,7 @@ async function serveCeService(opts) {
             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 {
@@ -655,6 +721,111 @@ async function serveCeService(opts) {
           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,
+              async: action.async === true ? 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;
+          }
+          const commandIdRaw = req.headers["x-xtrape-command-id"];
+          const commandId = Array.isArray(commandIdRaw) ? commandIdRaw[0] : commandIdRaw;
+          if (action.async === true && typeof commandId === "string" && commandId.length > 0 && agent) {
+            const reporter = agent;
+            send(res, 202, { contractVersion: import_capsule_contracts_node2.CE_CONTRACT_VERSION, status: "RUNNING", commandId });
+            void (async () => {
+              let outcome;
+              try {
+                const result = await action.execute(payload);
+                outcome = {
+                  status: "COMPLETED",
+                  ...result !== void 0 && result !== null && typeof result === "object" && !Array.isArray(result) ? { result } : result !== void 0 ? { result: { value: result } } : {}
+                };
+              } catch (error) {
+                outcome = {
+                  status: "FAILED",
+                  errorCode: "ACTION_FAILED",
+                  errorMessage: error instanceof Error ? error.message : "action handler failed"
+                };
+              }
+              try {
+                await reporter.reportCommandResult(commandId, outcome);
+              } catch {
+              }
+            })();
+            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);
@@ -678,6 +849,7 @@ async function serveCeService(opts) {
       address,
       instanceId: opts.instanceId,
       registrationToken: opts.registrationToken,
+      controlToken: opts.controlToken,
       fetchImpl: opts.fetchImpl
     });
     await agent.register();

package/dist/index.d.cts

@@ -283,9 +283,21 @@ interface CeServiceAgentOptions {
      * `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"];
@@ -301,16 +313,22 @@ declare class CeServiceAgent {
     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 } (sends the registration token if set). */
-    register(): Promise<{
-        instanceId: string;
-    }>;
+    register(): Promise<CeServiceRegistrationResult>;
     /**
      * Lifecycle convenience: register, then start periodic heartbeats. Returns a
      * `stop()` that stops heartbeats and best-effort deregisters — so a service
@@ -328,6 +346,18 @@ declare class CeServiceAgent {
     stopHeartbeat(): void;
     /** DELETE /v1/instances/{id} — graceful deregister. */
     deregister(): Promise<void>;
+    /**
+     * Report the outcome of an async action (server-ce#41 Stage B):
+     * POST /v1/instances/{instanceId}/commands/{commandId}/result using the
+     * per-instance access token. `outcome.result` carries the action payload for
+     * COMPLETED; errorCode/errorMessage describe a FAILED run.
+     */
+    reportCommandResult(commandId: string, outcome: {
+        status: "COMPLETED" | "FAILED";
+        result?: Record<string, unknown>;
+        errorCode?: string;
+        errorMessage?: string;
+    }): Promise<void>;
     /**
      * Validate an inbound message, run the handler, and build the reply message
      * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
@@ -339,7 +369,7 @@ declare class CeServiceAgent {
 
 /**
  * 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,
+ * `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.
  *
@@ -352,8 +382,25 @@ interface ServeCeServiceOptions {
     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) */
@@ -372,6 +419,45 @@ interface ServeCeServiceOptions {
     /** 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>;
+    /**
+     * Long-running action (server-ce#41 Stage B). When true and the pushed
+     * execute carries an `x-xtrape-command-id` header, the listener replies
+     * 202 { status: "RUNNING", commandId } immediately, runs `execute` in the
+     * background, and reports the outcome via
+     * `CeServiceAgent.reportCommandResult`. Without the header (older server-ce)
+     * the action falls back to synchronous execution.
+     */
+    async?: boolean;
+    execute(input: unknown): unknown | Promise<unknown>;
+}
 interface ServeCeServiceHandle {
     agent: CeServiceAgent;
     /** advertised address registered with server-ce */
@@ -383,4 +469,4 @@ interface ServeCeServiceHandle {
 }
 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 };
+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

@@ -283,9 +283,21 @@ interface CeServiceAgentOptions {
      * `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"];
@@ -301,16 +313,22 @@ declare class CeServiceAgent {
     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 } (sends the registration token if set). */
-    register(): Promise<{
-        instanceId: string;
-    }>;
+    register(): Promise<CeServiceRegistrationResult>;
     /**
      * Lifecycle convenience: register, then start periodic heartbeats. Returns a
      * `stop()` that stops heartbeats and best-effort deregisters — so a service
@@ -328,6 +346,18 @@ declare class CeServiceAgent {
     stopHeartbeat(): void;
     /** DELETE /v1/instances/{id} — graceful deregister. */
     deregister(): Promise<void>;
+    /**
+     * Report the outcome of an async action (server-ce#41 Stage B):
+     * POST /v1/instances/{instanceId}/commands/{commandId}/result using the
+     * per-instance access token. `outcome.result` carries the action payload for
+     * COMPLETED; errorCode/errorMessage describe a FAILED run.
+     */
+    reportCommandResult(commandId: string, outcome: {
+        status: "COMPLETED" | "FAILED";
+        result?: Record<string, unknown>;
+        errorCode?: string;
+        errorMessage?: string;
+    }): Promise<void>;
     /**
      * Validate an inbound message, run the handler, and build the reply message
      * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
@@ -339,7 +369,7 @@ declare class CeServiceAgent {
 
 /**
  * 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,
+ * `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.
  *
@@ -352,8 +382,25 @@ interface ServeCeServiceOptions {
     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) */
@@ -372,6 +419,45 @@ interface ServeCeServiceOptions {
     /** 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>;
+    /**
+     * Long-running action (server-ce#41 Stage B). When true and the pushed
+     * execute carries an `x-xtrape-command-id` header, the listener replies
+     * 202 { status: "RUNNING", commandId } immediately, runs `execute` in the
+     * background, and reports the outcome via
+     * `CeServiceAgent.reportCommandResult`. Without the header (older server-ce)
+     * the action falls back to synchronous execution.
+     */
+    async?: boolean;
+    execute(input: unknown): unknown | Promise<unknown>;
+}
 interface ServeCeServiceHandle {
     agent: CeServiceAgent;
     /** advertised address registered with server-ce */
@@ -383,4 +469,4 @@ interface ServeCeServiceHandle {
 }
 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 };
+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

@@ -412,7 +412,9 @@ var CeServiceAgent = class {
   address;
   tenant;
   registrationToken;
+  controlToken;
   fetchImpl;
+  accessToken;
   health = "HEALTHY";
   hbTimer;
   constructor(opts) {
@@ -423,8 +425,18 @@ var CeServiceAgent = class {
     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({
@@ -440,8 +452,12 @@ var CeServiceAgent = class {
   /** 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 };
+    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
@@ -471,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) {
@@ -491,7 +507,31 @@ 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() } : {}
+    });
+  }
+  /**
+   * Report the outcome of an async action (server-ce#41 Stage B):
+   * POST /v1/instances/{instanceId}/commands/{commandId}/result using the
+   * per-instance access token. `outcome.result` carries the action payload for
+   * COMPLETED; errorCode/errorMessage describe a FAILED run.
+   */
+  async reportCommandResult(commandId, outcome) {
+    const body = {
+      contractVersion: CE_CONTRACT_VERSION,
+      commandId,
+      status: outcome.status,
+      ...outcome.result !== void 0 ? { result: outcome.result } : {},
+      ...outcome.errorCode ? { errorCode: outcome.errorCode } : {},
+      ...outcome.errorMessage ? { errorMessage: outcome.errorMessage } : {}
+    };
+    await this.post(
+      `/v1/instances/${encodeURIComponent(this.instanceId)}/commands/${encodeURIComponent(commandId)}/result`,
+      body,
+      this.lifecycleAuthHeaders()
+    );
   }
   /**
    * Validate an inbound message, run the handler, and build the reply message
@@ -548,6 +588,7 @@ var CeServiceAgent = class {
 
 // src/ce/serve.ts
 import { createServer } from "http";
+import { CE_CONTRACT_VERSION as CE_CONTRACT_VERSION2 } from "@xtrape/capsule-contracts-node";
 function send(res, status, body) {
   res.writeHead(status, { "content-type": "application/json" });
   res.end(JSON.stringify(body));
@@ -563,6 +604,26 @@ function readBody(req) {
 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}`;
@@ -590,6 +651,10 @@ function sendMessageError(res, error) {
   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;
@@ -605,6 +670,7 @@ async function serveCeService(opts) {
             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 {
@@ -621,6 +687,111 @@ async function serveCeService(opts) {
           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,
+              async: action.async === true ? 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;
+          }
+          const commandIdRaw = req.headers["x-xtrape-command-id"];
+          const commandId = Array.isArray(commandIdRaw) ? commandIdRaw[0] : commandIdRaw;
+          if (action.async === true && typeof commandId === "string" && commandId.length > 0 && agent) {
+            const reporter = agent;
+            send(res, 202, { contractVersion: CE_CONTRACT_VERSION2, status: "RUNNING", commandId });
+            void (async () => {
+              let outcome;
+              try {
+                const result = await action.execute(payload);
+                outcome = {
+                  status: "COMPLETED",
+                  ...result !== void 0 && result !== null && typeof result === "object" && !Array.isArray(result) ? { result } : result !== void 0 ? { result: { value: result } } : {}
+                };
+              } catch (error) {
+                outcome = {
+                  status: "FAILED",
+                  errorCode: "ACTION_FAILED",
+                  errorMessage: error instanceof Error ? error.message : "action handler failed"
+                };
+              }
+              try {
+                await reporter.reportCommandResult(commandId, outcome);
+              } catch {
+              }
+            })();
+            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);
@@ -644,6 +815,7 @@ async function serveCeService(opts) {
       address,
       instanceId: opts.instanceId,
       registrationToken: opts.registrationToken,
+      controlToken: opts.controlToken,
       fetchImpl: opts.fetchImpl
     });
     await agent.register();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Node.js Embedded Agent SDK for reporting Workers to the Xtrape control plane.",
   "keywords": [
     "xtrape",
@@ -44,7 +44,7 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "^0.6.0"
+    "@xtrape/capsule-contracts-node": "^0.6.1"
   },
   "devDependencies": {
     "tsup": "^8.3.5",