@xtrape/capsule-agent-node 0.6.1 → 0.7.0

package/README.md

@@ -8,29 +8,23 @@ 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: Release Train 0.6.0](https://img.shields.io/badge/status-0.6.0-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
+[![Status: 0.7 milestone](https://img.shields.io/badge/status-0.7.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:** 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.
+> **Package status:** This package follows Xtrape milestone-aligned component
+> versioning (`MINOR` = milestone). The npm package name remains a
+> compatibility identifier; the current milestone line is `0.7.x`.
 
 ## Install
 
-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@^0.5.0
+pnpm add @xtrape/capsule-agent-node@^0.7.0
 ```
 
-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:
 
 ```bash
@@ -77,7 +71,7 @@ const svc = await serveCeService({
   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" },
+    service: { id: "demo-echo-service", name: "Demo Echo Service", version: "0.7.0" },
     runtime: { language: "node", agent: "xtrape-agent-nodejs" },
     capabilities: ["status.query"],
     message: { supportedTypes: ["QUERY"] },
@@ -88,6 +82,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:
@@ -471,13 +497,12 @@ and `logger` are configured, `structuredLogger` wins.
 
 | Package                            | Compatible with                                               |
 | ---------------------------------- | ------------------------------------------------------------- |
-| repository line `0.6.0`            | current Xtrape `0.6.0` snapshot train                         |
+| repository line `0.7.x`            | Xtrape `0.7` milestone (`xtrape-server-ce` >= 0.7.0, `@xtrape/capsule-contracts-node@^0.7.0`) |
 | `@xtrape/capsule-agent-node@0.1.x` | Xtrape Panel CE `0.1.x` and `@xtrape/capsule-contracts-node@0.1.x` |
 
-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`.
+Pin matching milestone (`MINOR`) versions across CE, Agent SDK, and Contracts;
+patch numbers may differ per component. The wire protocol may still change
+before `v1.0`.
 
 ## Troubleshooting
 

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.7.0",
   "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.7.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",