@xtrape/capsule-agent-node 0.1.0-public-review.0 → 0.1.0-public-review.1

package/README.md

@@ -46,6 +46,15 @@ const agent = new CapsuleAgent({
   backendUrl: process.env.OPSTAGE_BACKEND_URL ?? "http://localhost:8080",
   registrationToken: process.env.OPSTAGE_REGISTRATION_TOKEN,
   tokenStore: { file: "./data/agent-token.txt" },
+  // Optional. If omitted, the SDK derives agent identity from `service`.
+  // Provide it explicitly when one Agent owns multiple Capsule Services on
+  // the same host, or when you want a stable agent code that survives
+  // service renames.
+  agent: {
+    code: "hello-capsule-agent",
+    name: "Hello Capsule Agent",
+    runtime: "nodejs",
+  },
   service: {
     code: "hello-capsule",
     name: "Hello Capsule",
@@ -300,6 +309,52 @@ Core methods:
 Use matching minor versions across CE, Agent SDK, and Contracts during Public
 Review and Public Preview. The wire protocol may still change before `v1.0`.
 
+## Troubleshooting
+
+### Registration fails with `401 / REGISTRATION_TOKEN_INVALID`
+
+The token is single-use and short-lived.
+
+- Check the token has not already been consumed by an earlier successful start
+  (registration tokens flip to `USED` on first use).
+- Check the token has not expired. Operators set `expiresInSeconds` when
+  creating the token; the default in CE is short.
+- Check the token has not been revoked from the Opstage console.
+- Re-create a fresh token in the console and start the agent with it.
+
+### Agent reports `ECONNREFUSED` / cannot reach backend
+
+- Confirm `OPSTAGE_BACKEND_URL` resolves from inside the container or host
+  where the agent runs. The default of `http://localhost:8080` only works if
+  the agent runs on the same host as Opstage.
+- If you sit behind a reverse proxy, point `backendUrl` at the proxy URL —
+  not the internal Opstage container address.
+- Outbound HTTPS through corporate proxies: respect `HTTPS_PROXY` /
+  `NO_PROXY` env vars (`undici` honors them via `setGlobalDispatcher`).
+
+### Agent token file is rejected on second start (`401 / UNAUTHORIZED`)
+
+- File permissions: the agent process must be able to read
+  `tokenStore.file`. Run `chmod 600` (owner read/write) and ensure the
+  process owner matches.
+- File contents: the SDK writes `<agentId>:<agentToken>` plaintext. If the
+  file exists but contains anything else, delete it and re-register with a
+  fresh registration token.
+- Token revocation: an operator may have revoked the agent or the agent
+  token from the console. Inspect the agent's status in Opstage; if it shows
+  `REVOKED` or `DISABLED`, that's the cause.
+
+### Heartbeats succeed but action results never arrive
+
+- Confirm the action `name` registered with `agent.action({ name: "..." })`
+  matches the `actionName` the backend dispatches in the command. The SDK
+  reports `ACTION_HANDLER_NOT_FOUND` if they differ.
+- Confirm `start()` is awaited and not called repeatedly — multiple
+  `CapsuleAgent` instances on the same host with the same agent code will
+  fight over heartbeats and command polls.
+- Check `commandPollMs` / `commandPollIntervalSeconds` is not absurdly
+  large; default is 5s.
+
 ## Documentation
 
 - Site: https://xtrape-com.github.io/xtrape-capsule-site/

package/dist/index.cjs

@@ -78,13 +78,17 @@ var AgentApiClient = class {
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
 var FileTokenStore = class {
-  constructor(filePath = "./data/agent-token.json") {
+  constructor(filePath = "./data/agent-token.txt") {
     this.filePath = filePath;
   }
   filePath;
   async load() {
     try {
-      const parsed = JSON.parse(await (0, import_promises.readFile)(this.filePath, "utf8"));
+      const raw = await (0, import_promises.readFile)(this.filePath, "utf8");
+      const trimmed = raw.trim();
+      if (!trimmed) return null;
+      if (!trimmed.startsWith("{")) return trimmed;
+      const parsed = JSON.parse(trimmed);
       if (typeof parsed.agentId === "string" && typeof parsed.agentToken === "string") return `${parsed.agentId}:${parsed.agentToken}`;
       return typeof parsed.agentToken === "string" ? parsed.agentToken : null;
     } catch (e) {
@@ -93,9 +97,8 @@ var FileTokenStore = class {
     }
   }
   async save(token) {
-    const [agentId, agentToken] = token.includes(":") ? token.split(":", 2) : [void 0, token];
     await (0, import_promises.mkdir)((0, import_node_path.dirname)(this.filePath), { recursive: true });
-    await (0, import_promises.writeFile)(this.filePath, JSON.stringify({ ...agentId ? { agentId } : {}, agentToken, savedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), { mode: 384 });
+    await (0, import_promises.writeFile)(this.filePath, token, { mode: 384 });
     try {
       await (0, import_promises.chmod)(this.filePath, 384);
     } catch {
@@ -107,11 +110,22 @@ var FileTokenStore = class {
 };
 
 // src/security/redaction.ts
+var SENSITIVE_KEY = /token|secret|password|cookie|authorization|api[-_]?key\b|generatedKey|rawKey|plainTextKey/i;
+var TOKEN_PATTERN = /opstage_[a-z]+_[A-Za-z0-9_-]+/g;
 function redact(value) {
-  if (typeof value === "string") return value.replace(/opstage_(reg|agent)_[A-Za-z0-9_-]+/g, "opstage_$1_[REDACTED]");
+  if (typeof value === "string") {
+    return value.replace(TOKEN_PATTERN, (match) => {
+      const prefixEnd = match.lastIndexOf("_");
+      return `${match.slice(0, prefixEnd + 1)}[REDACTED]`;
+    });
+  }
   if (!value || typeof value !== "object") return value;
   if (Array.isArray(value)) return value.map(redact);
-  return Object.fromEntries(Object.entries(value).map(([k, v]) => [/token|secret|password|authorization/i.test(k) ? [k, "[REDACTED]"] : [k, redact(v)]]));
+  return Object.fromEntries(
+    Object.entries(value).map(
+      ([k, v]) => SENSITIVE_KEY.test(k) ? [k, "[REDACTED]"] : [k, redact(v)]
+    )
+  );
 }
 
 // src/capsule-agent.ts

package/dist/index.d.cts

@@ -1,5 +1,12 @@
 import { HealthReportInput, ConfigItemInput, ActionDefinitionInput, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
 
+type RuntimeKind = "nodejs" | "java" | "python" | "go" | "other";
+type ActionPrepareResult = {
+    action?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+    initialPayload?: Record<string, unknown>;
+    currentState?: Record<string, unknown>;
+};
 type AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     success?: boolean;
@@ -7,15 +14,7 @@ type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     data?: Record<string, unknown>;
     error?: Record<string, unknown>;
 } | Record<string, unknown>>;
-type ActionPrepareHandler = () => Promise<{
-    action?: Record<string, unknown>;
-    initialPayload?: Record<string, unknown>;
-    currentState?: Record<string, unknown>;
-} | Record<string, unknown>> | {
-    action?: Record<string, unknown>;
-    initialPayload?: Record<string, unknown>;
-    currentState?: Record<string, unknown>;
-} | Record<string, unknown>;
+type ActionPrepareHandler = () => Promise<ActionPrepareResult | Record<string, unknown>> | ActionPrepareResult | Record<string, unknown>;
 interface CapsuleAgentOptions {
     backendUrl: string;
     registrationToken?: string;
@@ -25,14 +24,14 @@ interface CapsuleAgentOptions {
     agent?: {
         code: string;
         name?: string;
-        runtime?: string;
+        runtime?: RuntimeKind;
     };
     service: {
         code: string;
         name: string;
         description?: string;
         version: string;
-        runtime: "nodejs" | "java" | "python" | "go" | "other";
+        runtime: RuntimeKind;
         manifest?: Record<string, unknown>;
     };
     intervals?: {
@@ -136,4 +135,4 @@ declare class AgentApiError extends Error {
     constructor(status: number, message: string, body?: unknown | undefined);
 }
 
-export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, FileTokenStore, type HealthProvider, type RegisteredAction, type ServiceSnapshot, type TokenStore };
+export { type ActionHandler, type ActionPrepareHandler, type ActionPrepareResult, AgentApiClient, AgentApiError, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, FileTokenStore, type HealthProvider, type RegisteredAction, type RuntimeKind, type ServiceSnapshot, type TokenStore };

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 import { HealthReportInput, ConfigItemInput, ActionDefinitionInput, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
 
+type RuntimeKind = "nodejs" | "java" | "python" | "go" | "other";
+type ActionPrepareResult = {
+    action?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+    initialPayload?: Record<string, unknown>;
+    currentState?: Record<string, unknown>;
+};
 type AgentMode = "embedded";
 type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     success?: boolean;
@@ -7,15 +14,7 @@ type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     data?: Record<string, unknown>;
     error?: Record<string, unknown>;
 } | Record<string, unknown>>;
-type ActionPrepareHandler = () => Promise<{
-    action?: Record<string, unknown>;
-    initialPayload?: Record<string, unknown>;
-    currentState?: Record<string, unknown>;
-} | Record<string, unknown>> | {
-    action?: Record<string, unknown>;
-    initialPayload?: Record<string, unknown>;
-    currentState?: Record<string, unknown>;
-} | Record<string, unknown>;
+type ActionPrepareHandler = () => Promise<ActionPrepareResult | Record<string, unknown>> | ActionPrepareResult | Record<string, unknown>;
 interface CapsuleAgentOptions {
     backendUrl: string;
     registrationToken?: string;
@@ -25,14 +24,14 @@ interface CapsuleAgentOptions {
     agent?: {
         code: string;
         name?: string;
-        runtime?: string;
+        runtime?: RuntimeKind;
     };
     service: {
         code: string;
         name: string;
         description?: string;
         version: string;
-        runtime: "nodejs" | "java" | "python" | "go" | "other";
+        runtime: RuntimeKind;
         manifest?: Record<string, unknown>;
     };
     intervals?: {
@@ -136,4 +135,4 @@ declare class AgentApiError extends Error {
     constructor(status: number, message: string, body?: unknown | undefined);
 }
 
-export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, FileTokenStore, type HealthProvider, type RegisteredAction, type ServiceSnapshot, type TokenStore };
+export { type ActionHandler, type ActionPrepareHandler, type ActionPrepareResult, AgentApiClient, AgentApiError, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, FileTokenStore, type HealthProvider, type RegisteredAction, type RuntimeKind, type ServiceSnapshot, type TokenStore };

package/dist/index.js

@@ -49,13 +49,17 @@ var AgentApiClient = class {
 import { mkdir, readFile, rm, writeFile, chmod } from "fs/promises";
 import { dirname } from "path";
 var FileTokenStore = class {
-  constructor(filePath = "./data/agent-token.json") {
+  constructor(filePath = "./data/agent-token.txt") {
     this.filePath = filePath;
   }
   filePath;
   async load() {
     try {
-      const parsed = JSON.parse(await readFile(this.filePath, "utf8"));
+      const raw = await readFile(this.filePath, "utf8");
+      const trimmed = raw.trim();
+      if (!trimmed) return null;
+      if (!trimmed.startsWith("{")) return trimmed;
+      const parsed = JSON.parse(trimmed);
       if (typeof parsed.agentId === "string" && typeof parsed.agentToken === "string") return `${parsed.agentId}:${parsed.agentToken}`;
       return typeof parsed.agentToken === "string" ? parsed.agentToken : null;
     } catch (e) {
@@ -64,9 +68,8 @@ var FileTokenStore = class {
     }
   }
   async save(token) {
-    const [agentId, agentToken] = token.includes(":") ? token.split(":", 2) : [void 0, token];
     await mkdir(dirname(this.filePath), { recursive: true });
-    await writeFile(this.filePath, JSON.stringify({ ...agentId ? { agentId } : {}, agentToken, savedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), { mode: 384 });
+    await writeFile(this.filePath, token, { mode: 384 });
     try {
       await chmod(this.filePath, 384);
     } catch {
@@ -78,11 +81,22 @@ var FileTokenStore = class {
 };
 
 // src/security/redaction.ts
+var SENSITIVE_KEY = /token|secret|password|cookie|authorization|api[-_]?key\b|generatedKey|rawKey|plainTextKey/i;
+var TOKEN_PATTERN = /opstage_[a-z]+_[A-Za-z0-9_-]+/g;
 function redact(value) {
-  if (typeof value === "string") return value.replace(/opstage_(reg|agent)_[A-Za-z0-9_-]+/g, "opstage_$1_[REDACTED]");
+  if (typeof value === "string") {
+    return value.replace(TOKEN_PATTERN, (match) => {
+      const prefixEnd = match.lastIndexOf("_");
+      return `${match.slice(0, prefixEnd + 1)}[REDACTED]`;
+    });
+  }
   if (!value || typeof value !== "object") return value;
   if (Array.isArray(value)) return value.map(redact);
-  return Object.fromEntries(Object.entries(value).map(([k, v]) => [/token|secret|password|authorization/i.test(k) ? [k, "[REDACTED]"] : [k, redact(v)]]));
+  return Object.fromEntries(
+    Object.entries(value).map(
+      ([k, v]) => SENSITIVE_KEY.test(k) ? [k, "[REDACTED]"] : [k, redact(v)]
+    )
+  );
 }
 
 // src/capsule-agent.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.1.0-public-review.0",
+  "version": "0.1.0-public-review.1",
   "description": "Node.js Agent SDK for embedding Capsule Services into the Opstage governance loop.",
   "keywords": [
     "xtrape",