@xtrape/capsule-agent-node 0.4.0 → 0.6.0

package/NOTICE

@@ -1,4 +1,4 @@
-Opstage CE
-Copyright 2026 Xtrape Capsule contributors
+Xtrape Embedded Agent SDK for Node.js
+Copyright 2026 Xtrape contributors
 
-This product includes software developed by the Xtrape Capsule contributors.
+This product includes software developed by the Xtrape contributors.

package/README.md

@@ -1,31 +1,35 @@
-# @xtrape/capsule-agent-node
+# Xtrape Embedded Agent SDK for Node.js
 
-> Node.js embedded Agent SDK for connecting Capsule Services to Opstage.
+> Node.js Embedded Agent SDK for connecting Workers to the Xtrape control plane.
+
+The npm name `@xtrape/capsule-agent-node`, the `CapsuleAgent` export, and some
+existing wire fields are legacy compatibility identifiers. `Capsule` is not a
+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: 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)
+[![Status: Release Train 0.6.0](https://img.shields.io/badge/status-0.6.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)
 
-`@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).
+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:** Xtrape Capsule is currently in **Public Review** before
-> the `v0.1.0 Public Preview` release. This package is published under the
-> `public-review` dist-tag. APIs, contracts, deployment instructions, and SDK
-> interfaces may still change.
+> **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.
 
 ## Install
 
-During Public Review, install the prerelease package with:
+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@public-review
+pnpm add @xtrape/capsule-agent-node@^0.5.0
 ```
 
-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 source-level snapshot integration, use a local checkout of this repository
+and align the rest of the release train separately.
 
 For this repository itself:
 
@@ -34,34 +38,96 @@ pnpm install
 pnpm build
 ```
 
+## Xtrape CE Phase 0 Service Agent
+
+For the Xtrape CE 0.1 runtime loop (`Telegram → xtrape-server-ce → xtrape-service
+→ reply`), use `CeServiceAgent` (or the `serveCeService` bootstrap). An
+`xtrape-service` registers an instance to `xtrape-server-ce`, heartbeats, and
+replies to `ConversationMessage`s. `Service` and `Worker` are roles here, not the
+legacy `Capsule` concept.
+
+### One-call bootstrap
+
+`serveCeService` starts an HTTP listener (`POST /messages`, `GET /health`),
+registers the instance (sending the registration token if server-ce requires
+one), and runs heartbeats — so a service does not copy-paste lifecycle code:
+
+For deployed or containerized use, set `address` to the callback URL that
+`xtrape-server-ce` can actually reach and allowlist, for example
+`http://demo-service:8080`. The SDK only derives a default address when you
+bind to an explicit local-only host such as `127.0.0.1`.
+
+```ts
+import { serveCeService } from "@xtrape/capsule-agent-node";
+
+const svc = await serveCeService({
+  serverUrl: process.env.XTRAPE_SERVER_URL ?? "http://localhost:3000",
+  registrationToken: process.env.SERVER_CE_REGISTRATION_TOKEN,
+  port: 8080,
+  // required in deployed/containerized environments
+  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" },
+    runtime: { language: "node", agent: "xtrape-agent-nodejs" },
+    capabilities: ["status.query"],
+    message: { supportedTypes: ["QUERY"] },
+  },
+  handler: (msg) => `echo: ${msg.content}`,
+});
+
+process.on("SIGTERM", () => void svc.close()); // stop heartbeat + deregister + close
+```
+
+### Lower-level agent
+
+When the service already runs its own HTTP server, use `CeServiceAgent` directly:
+
+```ts
+import { CeServiceAgent } from "@xtrape/capsule-agent-node";
+
+const agent = new CeServiceAgent({
+  serverUrl: "http://localhost:3000",
+  registrationToken: process.env.SERVER_CE_REGISTRATION_TOKEN,
+  address: "http://127.0.0.1:8080",
+  manifest: /* ServiceManifest */ undefined as never,
+});
+
+const stop = await agent.start();          // register + heartbeat
+// in your POST /messages route:
+const reply = await agent.handleMessage(requestJson, (m) => `echo: ${m.content}`);
+// on shutdown:
+await stop();                              // stop heartbeat + deregister
+```
+
 ## Minimal Example
 
-This example matches the current SDK API: create a `CapsuleAgent`, configure
+This example uses the canonical alias `XtrapeAgent`, configures
 providers with `.health()` / `.configs()`, register Actions with `.action()`,
 then call `start()`.
 
 ```ts
-import { CapsuleAgent } from "@xtrape/capsule-agent-node";
+import { XtrapeAgent } from "@xtrape/capsule-agent-node";
 
-const agent = new CapsuleAgent({
+const agent = new XtrapeAgent({
   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
+  // Optional. If omitted, the SDK derives Agent identity from `worker`.
+  // Provide it explicitly when one Agent owns multiple Workers 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",
+    code: "hello-worker-agent",
+    name: "Hello Worker Agent",
     runtime: "nodejs",
   },
-  service: {
-    code: "hello-capsule",
-    name: "Hello Capsule",
+  worker: {
+    code: "hello-worker",
+    name: "Hello Worker",
     version: "0.1.0",
     runtime: "nodejs",
-    description: "Minimal Capsule Service example",
+    description: "Minimal Worker example",
   },
 });
 
@@ -112,10 +178,12 @@ await agent.start();
 
 ## How Registration Works
 
-1. An operator creates a single-use Registration Token in Opstage CE.
-2. The service starts with `registrationToken` and calls the Agent registration
+1. An operator creates a single-use registration credential in Panel CE (the
+   current API calls it a Registration Token).
+2. The Worker starts with `registrationToken` and calls the Agent registration
    API.
-3. Opstage returns an Agent ID and Agent token.
+3. The control plane returns an Agent ID and Agent credential (currently named
+   an Agent token).
 4. The SDK stores the issued credentials in `tokenStore.file` as `<agentId>:<agentToken>`.
 5. Future restarts reuse the stored Agent token; the Registration Token is not
    needed again.
@@ -123,14 +191,15 @@ await agent.start();
 If the token file is lost or the Agent is revoked, create a new Registration
 Token and restart the service with it.
 
-## Service Manifest
+## Worker Manifest
 
-The `service` option describes the Capsule Service reported to Opstage:
+The `worker` option describes the Worker reported to the control plane. The old
+`service` option remains accepted for compatibility:
 
 ```ts
-service: {
-  code: "hello-capsule",          // stable unique service code
-  name: "Hello Capsule",         // operator-facing display name
+worker: {
+  code: "hello-worker",           // stable unique Worker code
+  name: "Hello Worker",           // operator-facing display name
   description: "...",            // optional
   version: "0.1.0",              // service version
   runtime: "nodejs",             // nodejs | java | python | go | other
@@ -138,8 +207,9 @@ service: {
 }
 ```
 
-The SDK wraps this as a `CapsuleService` manifest with `kind: "CapsuleService"`,
-`schemaVersion: "1.0"`, and `agentMode: "embedded"`.
+The SDK wraps this as a Worker manifest with `kind: "Worker"`,
+`schemaVersion: "1.0"`, and `agentMode: "embedded"`. Existing Panel versions
+continue accepting it through the legacy reported-service wire envelope.
 
 ## Health Reporting
 
@@ -153,13 +223,13 @@ agent.health(async () => ({
 }));
 ```
 
-The provider runs for heartbeats and service reports. Do not include secrets in
+The provider runs for heartbeats and Worker Runtime Reports. Do not include secrets in
 `details`.
 
 Agent health providers return protocol-level `HealthStatus` values: `UP`,
 `DEGRADED`, `DOWN`, `UNKNOWN`.
 
-Opstage may derive an operator-facing `effectiveStatus`: `HEALTHY`, `UNHEALTHY`,
+Xtrape Panel may derive an operator-facing `effectiveStatus`: `HEALTHY`, `UNHEALTHY`,
 `STALE`, `OFFLINE`.
 
 ## Config Reporting
@@ -186,8 +256,9 @@ agent.configs(() => [
 ]);
 ```
 
-Configs are reported to Opstage for visibility; the current CE flow does not
-push config values from Opstage into the service.
+Config Definitions and safe observations are reported to Panel for visibility.
+The Worker or deployment platform remains the configuration owner; current CE
+does not push arbitrary values into the Worker.
 
 ## Actions
 
@@ -207,12 +278,12 @@ agent.action({
 });
 ```
 
-Action metadata is published in the service report. The SDK intentionally strips
+Action metadata is published in the Worker Runtime Report. The SDK intentionally strips
 runtime-only handler functions before reporting the Action Catalog.
 
 ## Action Prepare / Execute
 
-Opstage uses two Command types for actions:
+Xtrape Panel uses two Command types for actions:
 
 1. `ACTION_PREPARE` — created when the UI opens an Action panel. The SDK calls
    `prepare()` if present and returns dynamic form metadata such as
@@ -229,8 +300,8 @@ The embedded Agent starts three loops by default:
 
 | Loop           |    Default | Purpose                            |
 | -------------- | ---------: | ---------------------------------- |
-| Heartbeat      | 30 seconds | Agent liveness and latest health   |
-| Service report | 60 seconds | Manifest, configs, actions, health |
+| Heartbeat      | 30 seconds | Agent liveness                     |
+| Worker report  | 60 seconds | Manifest, config observations, Actions, health |
 | Command poll   |  5 seconds | Fetch and execute pending Commands |
 
 You can override intervals:
@@ -240,7 +311,7 @@ new CapsuleAgent({
   // ...
   intervals: {
     heartbeatMs: 30_000,
-    serviceReportMs: 60_000,
+    workerReportMs: 60_000,
     commandPollMs: 5_000,
   },
 });
@@ -265,7 +336,7 @@ Security recommendations:
 
 - chmod the containing directory so only the service user can read it;
 - never commit token files;
-- rotate by revoking the Agent in Opstage and registering a new one;
+- rotate by revoking the Agent in Xtrape Panel and registering a new one;
 - prefer secret managers for production wrappers when available.
 
 ## Security Notes
@@ -342,7 +413,7 @@ try {
     process.exit(65);
   }
   if (err instanceof NetworkError) {
-    console.error("could not reach Opstage:", err.message);
+    console.error("could not reach Xtrape Panel:", err.message);
     process.exit(75);
   }
   throw err;
@@ -390,10 +461,13 @@ and `logger` are configured, `structuredLogger` wins.
 
 | Package                            | Compatible with                                               |
 | ---------------------------------- | ------------------------------------------------------------- |
-| `@xtrape/capsule-agent-node@0.1.x` | Opstage CE `0.1.x` and `@xtrape/capsule-contracts-node@0.1.x` |
+| repository line `0.6.0`            | current Xtrape `0.6.0` snapshot train                         |
+| `@xtrape/capsule-agent-node@0.1.x` | Xtrape Panel CE `0.1.x` and `@xtrape/capsule-contracts-node@0.1.x` |
 
-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`.
+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`.
 
 ## Troubleshooting
 
@@ -405,16 +479,16 @@ The token is single-use and short-lived.
   (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.
+- Check the token has not been revoked from the Xtrape Panel 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.
+  the agent runs on the same host as Xtrape Panel.
 - If you sit behind a reverse proxy, point `backendUrl` at the proxy URL —
-  not the internal Opstage container address.
+  not the internal Xtrape Panel container address.
 - Outbound HTTPS through corporate proxies: respect `HTTPS_PROXY` /
   `NO_PROXY` env vars (`undici` honors them via `setGlobalDispatcher`).
 
@@ -427,7 +501,7 @@ The token is single-use and short-lived.
   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
+  token from the console. Inspect the agent's status in Xtrape Panel; if it shows
   `REVOKED` or `DISABLED`, that's the cause.
 
 ### Heartbeats succeed but action results never arrive
@@ -443,10 +517,10 @@ The token is single-use and short-lived.
 
 ## Documentation
 
-- Site: https://xtrape-com.github.io/xtrape-capsule-site/
-- Node embedded Agent guide: https://xtrape-com.github.io/xtrape-capsule-site/agents/node-embedded-agent
-- Action model: https://xtrape-com.github.io/xtrape-capsule-site/agents/action-model
-- Opstage CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
+- Public docs repo: https://forgejo.xtrape.com/xtrape/xtrape-site
+- Node embedded Agent guide: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/agents/node-embedded-agent.md
+- Action model: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/agents/action-model.md
+- Xtrape Panel CE docs: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/opstage-ce/overview.md
 
 ## Contributing
 
@@ -456,10 +530,10 @@ safety guidance.
 
 ## License
 
-Apache-2.0. "Xtrape", "Xtrape Capsule", and "Opstage" are trademarks of their
+Apache-2.0. "Xtrape" and "Opstage" are trademarks of their
 respective owners; the open-source license does not grant trademark rights.
 
-## v0.4 Experimental Capsule Bus Hook
+## v0.4 Experimental legacy event routing Hook
 
 The SDK exposes a minimal experimental publish hook into CE's built-in SQLite-backed in-process event-to-command router:
 
@@ -470,7 +544,7 @@ await agent.publishBusEvent({
 });
 ```
 
-The hook posts to Opstage CE as the registered embedded agent and defaults `sourceServiceCode` to the configured service code.
+The hook posts to Xtrape Panel CE as the registered embedded agent and defaults `sourceServiceCode` to the configured service code.
 
 Typed errors for Bus failure modes:
 
@@ -478,4 +552,4 @@ Typed errors for Bus failure modes:
 - `BusRateLimitedError` — `BUS_RATE_LIMITED` (429)
 - `BusDepthExceededError` — `BUS_DEPTH_EXCEEDED` (422)
 
-Capsule Bus is experimental in v0.4: not a standalone Bus Server, external broker, workflow engine, or service mesh API.
+legacy event routing is experimental in v0.4: not a standalone Bus Server, external broker, workflow engine, or service mesh API.