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

package/README.md

@@ -6,10 +6,7 @@
 [![Status: Public Review](https://img.shields.io/badge/status-Public%20Review-orange.svg)](https://xtrape-com.github.io/xtrape-capsule-site/)
 [![Docs](https://img.shields.io/badge/docs-xtrape--capsule--site-blue.svg)](https://xtrape-com.github.io/xtrape-capsule-site/agents/node-embedded-agent)
 
-`@xtrape/capsule-agent-node` embeds an Opstage Agent inside a Node.js service.
-The Agent registers with Opstage CE, persists its Agent token, sends heartbeats,
-reports service metadata, exposes configs and health, and polls Commands for
-operator-triggered Actions.
+`@xtrape/capsule-agent-node` supports the stable Node.js Embedded Agent SDK path for single Capsule Services. For multi-service OpHub functionality, use OpHub (Go runtime).
 
 > **Package status:** Xtrape Capsule is currently in **Public Review** before
 > the `v0.1.0 Public Preview` release. This package is published under the
@@ -26,6 +23,10 @@ pnpm add @xtrape/capsule-agent-node@public-review
 
 The current Public Review version may change before `v0.1.0`.
 
+During v0.3 development, this repository may use a local workspace, GitHub
+branch dependency, or `0.3.0-rc.x` package for
+`@xtrape/capsule-contracts-node` until the final `0.3.0` package is published.
+
 For this repository itself:
 
 ```bash
@@ -285,7 +286,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:
@@ -300,6 +302,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                                               |

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) {
@@ -130,17 +176,27 @@ function redact(value) {
 
 // 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;
@@ -288,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,12 +1,5 @@
-import { HealthReportInput, ConfigItemInput, ActionDefinitionInput, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
+import { ActionPrepareResult, RuntimeKind, 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;
@@ -15,6 +8,36 @@ type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     error?: 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;
@@ -42,7 +65,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;
@@ -63,6 +93,7 @@ declare class CapsuleAgent {
     private readonly client;
     private readonly store;
     private readonly logger;
+    private readonly structuredLogger?;
     private agentId?;
     private token?;
     private stopped;
@@ -89,6 +120,7 @@ declare class CapsuleAgent {
     private withTimeout;
     private retry;
     private log;
+    private normalizeFields;
 }
 
 declare class FileTokenStore implements TokenStore {
@@ -99,6 +131,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);
@@ -113,7 +186,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";
@@ -129,10 +202,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, type ActionPrepareResult, AgentApiClient, AgentApiError, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, FileTokenStore, type HealthProvider, type RegisteredAction, type RuntimeKind, type ServiceSnapshot, type TokenStore };
+export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, type ServiceSnapshot, type StructuredLogger, type TokenStore };

package/dist/index.d.ts

@@ -1,12 +1,5 @@
-import { HealthReportInput, ConfigItemInput, ActionDefinitionInput, ReportedService, RegisterAgentRequest, AgentHeartbeatRequest, ServiceReportRequest, ReportCommandResultRequest } from '@xtrape/capsule-contracts-node';
+import { ActionPrepareResult, RuntimeKind, 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;
@@ -15,6 +8,36 @@ type ActionHandler = (payload: Record<string, unknown>) => Promise<{
     error?: 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;
@@ -42,7 +65,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;
@@ -63,6 +93,7 @@ declare class CapsuleAgent {
     private readonly client;
     private readonly store;
     private readonly logger;
+    private readonly structuredLogger?;
     private agentId?;
     private token?;
     private stopped;
@@ -89,6 +120,7 @@ declare class CapsuleAgent {
     private withTimeout;
     private retry;
     private log;
+    private normalizeFields;
 }
 
 declare class FileTokenStore implements TokenStore {
@@ -99,6 +131,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);
@@ -113,7 +186,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";
@@ -129,10 +202,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, type ActionPrepareResult, AgentApiClient, AgentApiError, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, FileTokenStore, type HealthProvider, type RegisteredAction, type RuntimeKind, type ServiceSnapshot, type TokenStore };
+export { type ActionHandler, type ActionPrepareHandler, AgentApiClient, AgentApiError, AgentAuthError, type AgentLogLevel, type AgentLogRecord, type AgentMode, CapsuleAgent, type CapsuleAgentOptions, type ConfigProvider, type ConsoleLogger, FileTokenStore, type HealthProvider, NetworkError, type RegisteredAction, RegistrationError, 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) {
@@ -101,17 +144,27 @@ function redact(value) {
 
 // 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;
@@ -259,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,7 +1,7 @@
 {
   "name": "@xtrape/capsule-agent-node",
-  "version": "0.1.0-public-review.1",
-  "description": "Node.js Agent SDK for embedding Capsule Services into the Opstage governance loop.",
+  "version": "0.3.0",
+  "description": "Node.js Embedded Agent SDK for embedding single Capsule Services into the Opstage governance loop. For multi-service OpHub functionality, use OpHub (Go runtime).",
   "keywords": [
     "xtrape",
     "capsule",
@@ -43,13 +43,13 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@xtrape/capsule-contracts-node": "^0.1.0-public-review.0"
+    "@xtrape/capsule-contracts-node": "0.3.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.9",
-    "@types/node": "^22.10.2"
+    "vitest": "^2.1.9"
   },
   "engines": {
     "node": ">=20"