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

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",
@@ -276,7 +285,8 @@ Main exports:
 - `CapsuleAgent`
 - `FileTokenStore`
 - `AgentApiClient`
-- `AgentApiError`
+- `AgentApiError`, `RegistrationError`, `AgentAuthError`, `NetworkError`
+- `AgentLogLevel`, `AgentLogRecord`, `StructuredLogger`, `ConsoleLogger` (types)
 - SDK option and provider types from `types.ts`
 
 Core methods:
@@ -291,6 +301,90 @@ Core methods:
 | `.stop()`                   | Stops background loops.                                       |
 | `.runHealth()`              | Runs the configured health provider.                          |
 
+### Typed errors
+
+> Added in `0.2.0`. Pre-`0.2` code that catches `AgentApiError` still works
+> because the new classes extend it.
+
+The SDK surfaces four error classes so callers can branch on the failure
+mode without parsing messages:
+
+| Class                | When it's thrown                                                                                                                                        | Should the caller retry? |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `RegistrationError`  | `/api/agents/register` rejects the one-time token (expired, revoked, already used, malformed). Needs operator action — mint a fresh registration token. | No.                      |
+| `AgentAuthError`     | Any non-register call returns 401/403. The agent token has been revoked or the agent disabled. Re-register before resuming.                             | No.                      |
+| `NetworkError`       | `fetch()` threw before getting an HTTP response (DNS failure, ECONNREFUSED, abort, timeout). `status === 0`; carries an optional `cause`.               | Yes — SDK already does.  |
+| `AgentApiError`      | Catch-all parent. Direct instances carry HTTP 4xx/5xx that don't fit the more specific cases (e.g. 409 conflict, 422 validation, 5xx server error).     | Only on 5xx.             |
+
+The SDK's internal `retry()` loop already implements this policy: only
+`NetworkError` and 5xx `AgentApiError` are retried with exponential backoff;
+4xx — including the two typed subclasses — surfaces immediately so the caller
+isn't waiting on a backoff that can never succeed.
+
+```ts
+import {
+  CapsuleAgent,
+  RegistrationError,
+  AgentAuthError,
+  NetworkError,
+} from "@xtrape/capsule-agent-node";
+
+try {
+  await agent.start();
+} catch (err) {
+  if (err instanceof RegistrationError) {
+    console.error("registration token is no longer valid:", err.code);
+    process.exit(64);
+  }
+  if (err instanceof AgentAuthError) {
+    console.error("agent token rejected — was the agent revoked?");
+    process.exit(65);
+  }
+  if (err instanceof NetworkError) {
+    console.error("could not reach Opstage:", err.message);
+    process.exit(75);
+  }
+  throw err;
+}
+```
+
+### Structured logger
+
+> Added in `0.2.0`. Existing zero-config callers (no `logger` / no
+> `structuredLogger`) keep using the global `console` exactly as before.
+
+By default the SDK calls `console.debug` / `.info` / `.warn` / `.error`. For
+JSON-line logging, pino, OpenTelemetry, or any in-house collector, pass a
+`structuredLogger`:
+
+```ts
+import { CapsuleAgent, type StructuredLogger } from "@xtrape/capsule-agent-node";
+
+const collector: StructuredLogger = {
+  log({ level, message, fields }) {
+    process.stdout.write(JSON.stringify({ t: Date.now(), level, message, ...fields }) + "\n");
+  },
+};
+
+const agent = new CapsuleAgent({
+  // ...
+  structuredLogger: collector,
+});
+```
+
+Each record arrives as `{ level: "debug" | "info" | "warn" | "error",
+message: string, fields?: Record<string, unknown> }`. The SDK normalizes the
+optional context before emitting:
+
+- `Error` instances become `{ error: { name, message, stack } }` so they
+  survive `JSON.stringify`.
+- Primitives become `{ value: <primitive> }`.
+- Plain objects pass through unchanged.
+
+In all cases the redactor runs over `fields` first, so tokens and
+secret-bearing keys never reach the collector. If both `structuredLogger`
+and `logger` are configured, `structuredLogger` wins.
+
 ## Version Compatibility
 
 | Package                            | Compatible with                                               |
@@ -300,6 +394,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

@@ -22,21 +22,53 @@ var index_exports = {};
 __export(index_exports, {
   AgentApiClient: () => AgentApiClient,
   AgentApiError: () => AgentApiError,
+  AgentAuthError: () => AgentAuthError,
   CapsuleAgent: () => CapsuleAgent,
-  FileTokenStore: () => FileTokenStore
+  FileTokenStore: () => FileTokenStore,
+  NetworkError: () => NetworkError,
+  RegistrationError: () => RegistrationError
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client/errors.ts
 var AgentApiError = class extends Error {
-  constructor(status, message, body) {
+  constructor(status, message, body, code) {
     super(message);
     this.status = status;
     this.body = body;
+    this.code = code;
+    this.name = "AgentApiError";
   }
   status;
   body;
+  code;
 };
+var RegistrationError = class extends AgentApiError {
+  constructor(message, status, body, code) {
+    super(status, message, body, code);
+    this.name = "RegistrationError";
+  }
+};
+var AgentAuthError = class extends AgentApiError {
+  constructor(message, status, body, code) {
+    super(status, message, body, code);
+    this.name = "AgentAuthError";
+  }
+};
+var NetworkError = class extends AgentApiError {
+  constructor(message, cause) {
+    super(0, message, void 0, "NETWORK_ERROR");
+    this.name = "NetworkError";
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+  }
+};
+function classifyAgentApiError(status, message, body, code, path) {
+  if (status === 401 && path.endsWith("/register")) return new RegistrationError(message, status, body, code);
+  if (status === 401 || status === 403) return new AgentAuthError(message, status, body, code);
+  return new AgentApiError(status, message, body, code);
+}
 
 // src/client/agent-api-client.ts
 var AgentApiClient = class {
@@ -51,10 +83,24 @@ var AgentApiClient = class {
     const headers = new Headers(init.headers);
     headers.set("content-type", "application/json");
     if (init.token) headers.set("authorization", `Bearer ${init.token}`);
-    const res = await fetch(this.url(path), { ...init, headers });
+    let res;
+    try {
+      res = await fetch(this.url(path), { ...init, headers });
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      throw new NetworkError(`Failed to reach ${path}: ${reason}`, cause);
+    }
     const text = await res.text();
-    const body = text ? JSON.parse(text) : void 0;
-    if (!res.ok) throw new AgentApiError(res.status, body?.error?.message ?? res.statusText, body);
+    let body;
+    try {
+      body = text ? JSON.parse(text) : void 0;
+    } catch {
+      body = { error: { message: res.statusText } };
+    }
+    if (!res.ok) {
+      const err = body?.error;
+      throw classifyAgentApiError(res.status, err?.message ?? res.statusText, body, err?.code, path);
+    }
     return body?.data ?? body;
   }
   register(req) {
@@ -78,13 +124,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 +143,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,26 +156,47 @@ 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
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function emitLog(consoleSink, structured, level, message, fields) {
+  if (structured) {
+    structured.log({ level, message, fields });
+    return;
+  }
+  if (fields === void 0) consoleSink[level](message);
+  else consoleSink[level](message, fields);
+}
 var CapsuleAgent = class {
   constructor(options) {
     this.options = options;
     this.client = new AgentApiClient(options.backendUrl);
     this.store = new FileTokenStore(options.tokenStore?.file);
     this.logger = options.logger ?? console;
+    this.structuredLogger = options.structuredLogger;
   }
   options;
   client;
   store;
   logger;
+  structuredLogger;
   agentId;
   token;
   stopped = true;
@@ -274,20 +344,36 @@ var CapsuleAgent = class {
         return await fn();
       } catch (e) {
         last = e;
-        if (e instanceof AgentApiError && e.status < 500) throw e;
+        if (e instanceof NetworkError) {
+        } else if (e instanceof AgentApiError && e.status >= 500) {
+        } else {
+          throw e;
+        }
         await sleep(Math.min(1e3 * 2 ** i, 15e3));
       }
     }
     throw last;
   }
   log(level, msg, obj) {
-    this.logger[level](msg, obj ? redact(obj) : void 0);
+    const fields = obj === void 0 ? void 0 : this.normalizeFields(obj);
+    const redacted = fields ? redact(fields) : void 0;
+    emitLog(this.logger, this.structuredLogger, level, msg, redacted);
+  }
+  normalizeFields(obj) {
+    if (obj instanceof Error) {
+      return { error: { message: obj.message, name: obj.name, stack: obj.stack } };
+    }
+    if (typeof obj === "object" && obj !== null) return obj;
+    return { value: obj };
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentApiClient,
   AgentApiError,
+  AgentAuthError,
   CapsuleAgent,
-  FileTokenStore
+  FileTokenStore,
+  NetworkError,
+  RegistrationError
 });

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,37 @@ 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>;
+/**
+ * Log level emitted by the SDK. Aligns with the four standard `Console`
+ * methods so a plain `console` works as a logger with no adapter.
+ */
+type AgentLogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Structured log record passed to a `StructuredLogger`. The SDK populates
+ * `level` and `message`; `fields` carries an already-redacted Record of
+ * runtime context (agent id, error code, retry count, etc.).
+ */
+interface AgentLogRecord {
+    level: AgentLogLevel;
+    message: string;
+    fields?: Record<string, unknown>;
+}
+/**
+ * A structured log sink. Useful when the host wants to forward SDK events
+ * into a JSON-line logger, pino, OpenTelemetry, or a custom collector
+ * without losing the per-field context to `console.warn`'s positional
+ * argument list.
+ */
+interface StructuredLogger {
+    log(record: AgentLogRecord): void;
+}
+/**
+ * Console-shaped logger (subset of Node's `Console`). The SDK defaults to
+ * the global `console` when neither option is set; if both are provided,
+ * `structuredLogger` wins.
+ */
+type ConsoleLogger = Pick<Console, "debug" | "info" | "warn" | "error">;
 interface CapsuleAgentOptions {
     backendUrl: string;
     registrationToken?: string;
@@ -25,14 +54,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?: {
@@ -43,7 +72,14 @@ interface CapsuleAgentOptions {
     heartbeatIntervalSeconds?: number;
     commandPollIntervalSeconds?: number;
     autoStartLoops?: boolean;
-    logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+    /** Console-shaped sink; default is the global `console`. */
+    logger?: ConsoleLogger;
+    /**
+     * Structured sink. If provided, takes precedence over `logger`. The SDK
+     * still applies its own redaction before calling `log()`, so the host
+     * can route records as-is to a JSON stream.
+     */
+    structuredLogger?: StructuredLogger;
     failOnStartError?: boolean;
 }
 type HealthProvider = () => Promise<HealthReportInput> | HealthReportInput;
@@ -64,6 +100,7 @@ declare class CapsuleAgent {
     private readonly client;
     private readonly store;
     private readonly logger;
+    private readonly structuredLogger?;
     private agentId?;
     private token?;
     private stopped;
@@ -90,6 +127,7 @@ declare class CapsuleAgent {
     private withTimeout;
     private retry;
     private log;
+    private normalizeFields;
 }
 
 declare class FileTokenStore implements TokenStore {
@@ -100,6 +138,47 @@ declare class FileTokenStore implements TokenStore {
     clear(): Promise<void>;
 }
 
+/**
+ * Base class for any failure that crosses the Agent ↔ Backend wire. Use
+ * `instanceof AgentApiError` to catch the family, and the more specific
+ * subclasses below when the caller wants to branch on the failure mode.
+ *
+ * `status === 0` is reserved for transport failures that never reached the
+ * backend (DNS failure, ECONNREFUSED, network timeout, etc.); use
+ * `NetworkError` for those.
+ */
+declare class AgentApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined, code?: string | undefined);
+}
+/**
+ * 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.
+ */
+declare class RegistrationError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown, code?: string);
+}
+/**
+ * The backend rejected the persisted agent token (UNAUTHORIZED, agent
+ * REVOKED, agent DISABLED). The agent must be re-registered with a fresh
+ * registration token before it can resume.
+ */
+declare class AgentAuthError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown, code?: string);
+}
+/**
+ * Transport-level failure: the request did not reach the backend, or the
+ * backend's response was not a parseable HTTP envelope. The SDK retries
+ * these with exponential backoff; surface to the caller only after the
+ * retry budget is exhausted.
+ */
+declare class NetworkError extends AgentApiError {
+    constructor(message: string, cause?: unknown);
+}
+
 declare class AgentApiClient {
     private readonly backendUrl;
     constructor(backendUrl: string);
@@ -114,7 +193,7 @@ declare class AgentApiClient {
     heartbeat(agentId: string, token: string, req: AgentHeartbeatRequest): Promise<unknown>;
     reportServices(agentId: string, token: string, req: ServiceReportRequest): Promise<unknown>;
     pollCommands(agentId: string, token: string): Promise<{
-        type: "ACTION_PREPARE" | "ACTION_EXECUTE" | "ACTION";
+        type: "ACTION_PREPARE" | "ACTION_EXECUTE";
         id: string;
         createdAt: string;
         status: "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "EXPIRED" | "CANCELLED";
@@ -130,10 +209,4 @@ declare class AgentApiClient {
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
 }
 
-declare class AgentApiError extends Error {
-    readonly status: number;
-    readonly body?: unknown | undefined;
-    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, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, type RuntimeKind, type ServiceSnapshot, type StructuredLogger, 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,37 @@ 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>;
+/**
+ * Log level emitted by the SDK. Aligns with the four standard `Console`
+ * methods so a plain `console` works as a logger with no adapter.
+ */
+type AgentLogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Structured log record passed to a `StructuredLogger`. The SDK populates
+ * `level` and `message`; `fields` carries an already-redacted Record of
+ * runtime context (agent id, error code, retry count, etc.).
+ */
+interface AgentLogRecord {
+    level: AgentLogLevel;
+    message: string;
+    fields?: Record<string, unknown>;
+}
+/**
+ * A structured log sink. Useful when the host wants to forward SDK events
+ * into a JSON-line logger, pino, OpenTelemetry, or a custom collector
+ * without losing the per-field context to `console.warn`'s positional
+ * argument list.
+ */
+interface StructuredLogger {
+    log(record: AgentLogRecord): void;
+}
+/**
+ * Console-shaped logger (subset of Node's `Console`). The SDK defaults to
+ * the global `console` when neither option is set; if both are provided,
+ * `structuredLogger` wins.
+ */
+type ConsoleLogger = Pick<Console, "debug" | "info" | "warn" | "error">;
 interface CapsuleAgentOptions {
     backendUrl: string;
     registrationToken?: string;
@@ -25,14 +54,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?: {
@@ -43,7 +72,14 @@ interface CapsuleAgentOptions {
     heartbeatIntervalSeconds?: number;
     commandPollIntervalSeconds?: number;
     autoStartLoops?: boolean;
-    logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+    /** Console-shaped sink; default is the global `console`. */
+    logger?: ConsoleLogger;
+    /**
+     * Structured sink. If provided, takes precedence over `logger`. The SDK
+     * still applies its own redaction before calling `log()`, so the host
+     * can route records as-is to a JSON stream.
+     */
+    structuredLogger?: StructuredLogger;
     failOnStartError?: boolean;
 }
 type HealthProvider = () => Promise<HealthReportInput> | HealthReportInput;
@@ -64,6 +100,7 @@ declare class CapsuleAgent {
     private readonly client;
     private readonly store;
     private readonly logger;
+    private readonly structuredLogger?;
     private agentId?;
     private token?;
     private stopped;
@@ -90,6 +127,7 @@ declare class CapsuleAgent {
     private withTimeout;
     private retry;
     private log;
+    private normalizeFields;
 }
 
 declare class FileTokenStore implements TokenStore {
@@ -100,6 +138,47 @@ declare class FileTokenStore implements TokenStore {
     clear(): Promise<void>;
 }
 
+/**
+ * Base class for any failure that crosses the Agent ↔ Backend wire. Use
+ * `instanceof AgentApiError` to catch the family, and the more specific
+ * subclasses below when the caller wants to branch on the failure mode.
+ *
+ * `status === 0` is reserved for transport failures that never reached the
+ * backend (DNS failure, ECONNREFUSED, network timeout, etc.); use
+ * `NetworkError` for those.
+ */
+declare class AgentApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined, code?: string | undefined);
+}
+/**
+ * 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.
+ */
+declare class RegistrationError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown, code?: string);
+}
+/**
+ * The backend rejected the persisted agent token (UNAUTHORIZED, agent
+ * REVOKED, agent DISABLED). The agent must be re-registered with a fresh
+ * registration token before it can resume.
+ */
+declare class AgentAuthError extends AgentApiError {
+    constructor(message: string, status: number, body?: unknown, code?: string);
+}
+/**
+ * Transport-level failure: the request did not reach the backend, or the
+ * backend's response was not a parseable HTTP envelope. The SDK retries
+ * these with exponential backoff; surface to the caller only after the
+ * retry budget is exhausted.
+ */
+declare class NetworkError extends AgentApiError {
+    constructor(message: string, cause?: unknown);
+}
+
 declare class AgentApiClient {
     private readonly backendUrl;
     constructor(backendUrl: string);
@@ -114,7 +193,7 @@ declare class AgentApiClient {
     heartbeat(agentId: string, token: string, req: AgentHeartbeatRequest): Promise<unknown>;
     reportServices(agentId: string, token: string, req: ServiceReportRequest): Promise<unknown>;
     pollCommands(agentId: string, token: string): Promise<{
-        type: "ACTION_PREPARE" | "ACTION_EXECUTE" | "ACTION";
+        type: "ACTION_PREPARE" | "ACTION_EXECUTE";
         id: string;
         createdAt: string;
         status: "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "EXPIRED" | "CANCELLED";
@@ -130,10 +209,4 @@ declare class AgentApiClient {
     reportResult(agentId: string, token: string, commandId: string, req: ReportCommandResultRequest): Promise<unknown>;
 }
 
-declare class AgentApiError extends Error {
-    readonly status: number;
-    readonly body?: unknown | undefined;
-    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, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, type RuntimeKind, type ServiceSnapshot, type StructuredLogger, type TokenStore };

package/dist/index.js

@@ -1,13 +1,42 @@
 // src/client/errors.ts
 var AgentApiError = class extends Error {
-  constructor(status, message, body) {
+  constructor(status, message, body, code) {
     super(message);
     this.status = status;
     this.body = body;
+    this.code = code;
+    this.name = "AgentApiError";
   }
   status;
   body;
+  code;
 };
+var RegistrationError = class extends AgentApiError {
+  constructor(message, status, body, code) {
+    super(status, message, body, code);
+    this.name = "RegistrationError";
+  }
+};
+var AgentAuthError = class extends AgentApiError {
+  constructor(message, status, body, code) {
+    super(status, message, body, code);
+    this.name = "AgentAuthError";
+  }
+};
+var NetworkError = class extends AgentApiError {
+  constructor(message, cause) {
+    super(0, message, void 0, "NETWORK_ERROR");
+    this.name = "NetworkError";
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+  }
+};
+function classifyAgentApiError(status, message, body, code, path) {
+  if (status === 401 && path.endsWith("/register")) return new RegistrationError(message, status, body, code);
+  if (status === 401 || status === 403) return new AgentAuthError(message, status, body, code);
+  return new AgentApiError(status, message, body, code);
+}
 
 // src/client/agent-api-client.ts
 var AgentApiClient = class {
@@ -22,10 +51,24 @@ var AgentApiClient = class {
     const headers = new Headers(init.headers);
     headers.set("content-type", "application/json");
     if (init.token) headers.set("authorization", `Bearer ${init.token}`);
-    const res = await fetch(this.url(path), { ...init, headers });
+    let res;
+    try {
+      res = await fetch(this.url(path), { ...init, headers });
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      throw new NetworkError(`Failed to reach ${path}: ${reason}`, cause);
+    }
     const text = await res.text();
-    const body = text ? JSON.parse(text) : void 0;
-    if (!res.ok) throw new AgentApiError(res.status, body?.error?.message ?? res.statusText, body);
+    let body;
+    try {
+      body = text ? JSON.parse(text) : void 0;
+    } catch {
+      body = { error: { message: res.statusText } };
+    }
+    if (!res.ok) {
+      const err = body?.error;
+      throw classifyAgentApiError(res.status, err?.message ?? res.statusText, body, err?.code, path);
+    }
     return body?.data ?? body;
   }
   register(req) {
@@ -49,13 +92,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 +111,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,26 +124,47 @@ 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
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function emitLog(consoleSink, structured, level, message, fields) {
+  if (structured) {
+    structured.log({ level, message, fields });
+    return;
+  }
+  if (fields === void 0) consoleSink[level](message);
+  else consoleSink[level](message, fields);
+}
 var CapsuleAgent = class {
   constructor(options) {
     this.options = options;
     this.client = new AgentApiClient(options.backendUrl);
     this.store = new FileTokenStore(options.tokenStore?.file);
     this.logger = options.logger ?? console;
+    this.structuredLogger = options.structuredLogger;
   }
   options;
   client;
   store;
   logger;
+  structuredLogger;
   agentId;
   token;
   stopped = true;
@@ -245,19 +312,35 @@ var CapsuleAgent = class {
         return await fn();
       } catch (e) {
         last = e;
-        if (e instanceof AgentApiError && e.status < 500) throw e;
+        if (e instanceof NetworkError) {
+        } else if (e instanceof AgentApiError && e.status >= 500) {
+        } else {
+          throw e;
+        }
         await sleep(Math.min(1e3 * 2 ** i, 15e3));
       }
     }
     throw last;
   }
   log(level, msg, obj) {
-    this.logger[level](msg, obj ? redact(obj) : void 0);
+    const fields = obj === void 0 ? void 0 : this.normalizeFields(obj);
+    const redacted = fields ? redact(fields) : void 0;
+    emitLog(this.logger, this.structuredLogger, level, msg, redacted);
+  }
+  normalizeFields(obj) {
+    if (obj instanceof Error) {
+      return { error: { message: obj.message, name: obj.name, stack: obj.stack } };
+    }
+    if (typeof obj === "object" && obj !== null) return obj;
+    return { value: obj };
   }
 };
 export {
   AgentApiClient,
   AgentApiError,
+  AgentAuthError,
   CapsuleAgent,
-  FileTokenStore
+  FileTokenStore,
+  NetworkError,
+  RegistrationError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.1.0-public-review.0",
+  "version": "0.2.0",
   "description": "Node.js Agent SDK for embedding Capsule Services into the Opstage governance loop.",
   "keywords": [
     "xtrape",
@@ -35,15 +35,8 @@
     "LICENSE",
     "NOTICE"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "prepack": "pnpm build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
-  },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "^0.1.0-public-review.0"
+    "@xtrape/capsule-contracts-node": "^0.2.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -58,5 +51,11 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "license": "Apache-2.0"
-}
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}