@xtrape/capsule-agent-node 0.6.1 → 0.6.2

package/README.md

@@ -88,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:

package/dist/index.cjs

@@ -546,6 +546,27 @@ var CeServiceAgent = class {
       ...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
    * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
@@ -601,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));
@@ -711,6 +733,7 @@ async function serveCeService(opts) {
               category: action.category,
               order: action.order,
               requiresPrepare: typeof action.prepare === "function" ? true : void 0,
+              async: action.async === true ? true : void 0,
               inputSchema: action.inputSchema
             }))
           );
@@ -769,6 +792,33 @@ async function serveCeService(opts) {
             });
             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) {

package/dist/index.d.cts

@@ -346,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).
@@ -435,6 +447,15 @@ interface CeServiceActionDefinition {
      * 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 {

package/dist/index.d.ts

@@ -346,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).
@@ -435,6 +447,15 @@ interface CeServiceActionDefinition {
      * 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 {

package/dist/index.js

@@ -512,6 +512,27 @@ var CeServiceAgent = class {
       ...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
    * (senderType=SERVICE, targeted back at the sender, with replyToMessageId).
@@ -567,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));
@@ -677,6 +699,7 @@ async function serveCeService(opts) {
               category: action.category,
               order: action.order,
               requiresPrepare: typeof action.prepare === "function" ? true : void 0,
+              async: action.async === true ? true : void 0,
               inputSchema: action.inputSchema
             }))
           );
@@ -735,6 +758,33 @@ async function serveCeService(opts) {
             });
             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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.6.1",
+  "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",