@m64/nats-pi-bridge 0.0.2 → 0.0.4

package/README.md

@@ -6,7 +6,7 @@ Standalone headless service that spawns and manages PI coding agent sessions on
 >
 > **All you need on the host:** Node.js ≥20.6, a NATS server (or `demo.nats.io`), and an API key for any supported model provider.
 
-This bridge exposes session lifecycle + prompting as a `pi-exec` NATS microservice. Callers send structured JSON to a permanent **intake** endpoint to create, list, and stop sessions. Persistent sessions get their own per-session subject for follow-ups using the standard streaming wire protocol shared with the sibling implementations:
+This bridge exposes session lifecycle + prompting as a `pi-exec` NATS microservice. Callers send structured JSON to a permanent **control** endpoint to create, list, and stop sessions. Persistent sessions get their own per-session subject for follow-ups using the standard streaming wire protocol shared with the sibling implementations:
 
 - `nats-pi-channel` — PI extension for **interactive** PI sessions
 - `nats-claude-channel` — Claude Code MCP channel
@@ -34,12 +34,12 @@ In one terminal:
 npx @m64/nats-pi-bridge
 ```
 
-That's it. It connects to `demo.nats.io` by default and registers a `pi-exec` NATS microservice with an intake on `agents.pi-exec.$USER`:
+That's it. It connects to `demo.nats.io` by default and registers a `pi-exec` NATS microservice with a control endpoint on `agents.pi-exec.$USER`:
 
 ```
 pi-exec: connecting to demo.nats.io (context: default)
 pi-exec: connected
-pi-exec: intake registered on agents.pi-exec.yourname
+pi-exec: control registered on agents.pi-exec.yourname
 ```
 
 ### 2. Fire a one-shot prompt
@@ -81,22 +81,73 @@ Ctrl-C the bridge when you're done. Every active session is disposed during grac
 
 ## Architecture
 
-See [DESIGN.md](./DESIGN.md) for the full architectural document.
-
 The bridge runs as a single Node.js process. The `pi-exec` service has:
 
-- **Intake instance** (permanent): `agents.pi-exec.<owner>` — control plane
+- **Control instance** (permanent): `agents.pi-exec.<owner>` — control plane
 - **Per-session instances** (dynamic): `agents.pi-exec.<owner>.<sessionId>` — data plane
 
 Each session is its own NATS microservice instance (the same pattern that `nats-pi-channel` uses across processes — but here within one process). On stop, the session's instance is removed cleanly via `service.stop()`.
 
 ```
 nats micro list
-→ pi-exec │ 0.0.1 │ ABC123 │ intake
-         │       │ DEF456 │ worker-1 — /home/mario/code/nats-zig
-         │       │ GHI789 │ sid-gpt — /home/mario/code/sid-gpt
+→ pi-exec │ 0.0.4 │ ABC123 │ control
+          │       │ DEF456 │ worker-1 — /home/mario/code/nats-zig
+          │       │ GHI789 │ sid-gpt — /home/mario/code/sid-gpt
+```
+
+## NATS server
+
+The Quick Start uses `demo.nats.io` because it's zero-setup, but you'll usually want your own server. The bridge picks the server from a [NATS CLI context](https://docs.nats.io/using-nats/nats-tools/nats_cli#contexts) named via the `NATS_CONTEXT` environment variable.
+
+### Localhost
+
+```bash
+# 1. One-time: create a context pointing at your local NATS
+nats context save local --server nats://localhost:4222
+
+# 2. Run the bridge against it
+NATS_CONTEXT=local npx @m64/nats-pi-bridge
+```
+
+```
+pi-exec: connecting to nats://localhost:4222 (context: local)
+pi-exec: connected
+pi-exec: control registered on agents.pi-exec.m64
+```
+
+> **Don't have a local NATS server yet?** The fastest way:
+>
+> ```bash
+> docker run --rm -p 4222:4222 nats:latest
+> ```
+>
+> Or grab a binary from the [nats-server releases](https://github.com/nats-io/nats-server/releases).
+
+### Make a context the default
+
+To avoid setting `NATS_CONTEXT` on every invocation, drop a one-line config file:
+
+```bash
+mkdir -p ~/.pi-exec
+echo '{"context":"local"}' > ~/.pi-exec/config.json
 ```
 
+After that, plain `npx @m64/nats-pi-bridge` connects to your chosen server.
+
+### Authenticated and remote servers
+
+The same context format works for any NATS auth scheme — credentials files, NKeys, JWTs, TLS, user/password. Anything `nats context save` can store, the bridge can use:
+
+```bash
+nats context save prod \
+  --server nats://nats.example.com:4222 \
+  --creds ~/.nkeys/creds/synadia/MyAccount/me.creds
+
+NATS_CONTEXT=prod npx @m64/nats-pi-bridge
+```
+
+Context files live at `~/.config/nats/context/<name>.json`. See the [NATS CLI context docs](https://docs.nats.io/using-nats/nats-tools/nats_cli#contexts) for the full list of supported fields.
+
 ## Install
 
 ```bash
@@ -149,14 +200,14 @@ Environment overrides:
 | `PI_EXEC_DEFAULT_MODEL` | Default model spec, e.g. `anthropic/claude-sonnet-4-5` |
 | `PI_EXEC_DEFAULT_MAX_LIFETIME` | Default max session lifetime in seconds |
 
-PI credentials are read from `~/.pi/agent/auth.json` (the standard PI agent location). Run `pi /login` interactively once to populate it.
+PI credentials are read from `~/.pi/agent/auth.json` (the standard PI agent location). Create the file directly — see the [Quick Start prerequisite](#quick-start) for the one-liner. If you have PI installed locally, `pi /login` populates it automatically.
 
-## Intake protocol
+## Control protocol
 
 Send structured JSON to `agents.pi-exec.<owner>`:
 
 ```typescript
-type IntakeRequest = {
+type ControlRequest = {
   sessionMode: "run" | "session" | "stop" | "list";
   body?: string;          // prompt text (run/session)
   cwd?: string;           // working directory (run/session) — resolved to absolute

package/dist/server.js

@@ -34,7 +34,7 @@ var DEFAULT_CONTEXT = {
   url: "demo.nats.io",
   description: "NATS demo server (no auth)"
 };
-function intakeSubject(owner2) {
+function controlSubject(owner2) {
   return `agents.pi-exec.${owner2}`;
 }
 function sessionSubject(owner2, sessionId) {
@@ -171,7 +171,7 @@ var requestCounter = 0;
 var sessions = /* @__PURE__ */ new Map();
 var creating = /* @__PURE__ */ new Set();
 var nc;
-var intakeService;
+var controlService;
 var owner;
 var config;
 var authStorage;
@@ -193,17 +193,17 @@ function validateThinkingLevel(level) {
     `invalid thinkingLevel: ${level} (must be one of ${VALID_THINKING_LEVELS.join(", ")})`
   );
 }
-async function createPiSession(intake) {
-  if (!intake.cwd) throw new Error("cwd is required");
-  const absCwd = resolve(intake.cwd);
+async function createPiSession(req) {
+  if (!req.cwd) throw new Error("cwd is required");
+  const absCwd = resolve(req.cwd);
   if (!existsSync(absCwd) || !statSync(absCwd).isDirectory()) {
     throw new Error(`cwd not found or not a directory: ${absCwd}`);
   }
-  const modelSpec = intake.model ?? config.defaultModel;
+  const modelSpec = req.model ?? config.defaultModel;
   const model = resolveModel(modelSpec);
   if (modelSpec && !model) throw new Error(`unknown model: ${modelSpec}`);
   const thinkingLevel = validateThinkingLevel(
-    intake.thinkingLevel ?? config.defaultThinkingLevel
+    req.thinkingLevel ?? config.defaultThinkingLevel
   );
   const { session } = await createAgentSession({
     cwd: absCwd,
@@ -257,9 +257,9 @@ function respondJson(msg, payload) {
   } catch {
   }
 }
-function handleIntakeMessage(err, msg) {
+function handleControlMessage(err, msg) {
   if (err) {
-    process.stderr.write(`pi-exec: intake error: ${err.message}
+    process.stderr.write(`pi-exec: control error: ${err.message}
 `);
     return;
   }
@@ -267,26 +267,26 @@ function handleIntakeMessage(err, msg) {
     respondJson(msg, { error: "shutting_down" });
     return;
   }
-  let intake;
+  let req;
   try {
-    intake = JSON.parse(msg.string());
+    req = JSON.parse(msg.string());
   } catch (e) {
     respondJson(msg, { error: "invalid_json", message: e.message });
     return;
   }
-  if (!intake || typeof intake.sessionMode !== "string") {
+  if (!req || typeof req.sessionMode !== "string") {
     respondJson(msg, { error: "invalid_request", message: "sessionMode required" });
     return;
   }
-  switch (intake.sessionMode) {
+  switch (req.sessionMode) {
     case "run":
-      void handleRunMode(msg, intake);
+      void handleRunMode(msg, req);
       break;
     case "session":
-      void handleSessionMode(msg, intake);
+      void handleSessionMode(msg, req);
       break;
     case "stop":
-      void handleStopMode(msg, intake);
+      void handleStopMode(msg, req);
       break;
     case "list":
       handleListMode(msg);
@@ -294,31 +294,31 @@ function handleIntakeMessage(err, msg) {
     default:
       respondJson(msg, {
         error: "invalid_sessionMode",
-        sessionMode: intake.sessionMode
+        sessionMode: req.sessionMode
       });
   }
 }
-async function handleRunMode(msg, intake) {
+async function handleRunMode(msg, req) {
   const reply = msg.reply;
   if (!reply) {
     respondJson(msg, { error: "no_reply_subject" });
     return;
   }
-  if (!intake.body || !intake.cwd) {
+  if (!req.body || !req.cwd) {
     respondJson(msg, { error: "missing_fields", required: ["body", "cwd"] });
     return;
   }
   let session;
   let unsubscribe;
   try {
-    const created = await createPiSession(intake);
+    const created = await createPiSession(req);
     session = created.session;
     unsubscribe = session.subscribe((ev) => {
       if (ev.type === "message_update" && ev.assistantMessageEvent.type === "text_delta" && ev.assistantMessageEvent.delta) {
         publishChunked(nc, reply, ev.assistantMessageEvent.delta);
       }
     });
-    await session.prompt(intake.body);
+    await session.prompt(req.body);
   } catch (e) {
     try {
       nc.publish(reply, `error: ${e.message}`);
@@ -345,20 +345,20 @@ async function handleRunMode(msg, intake) {
     }
   }
 }
-async function handleSessionMode(msg, intake) {
+async function handleSessionMode(msg, req) {
   const reply = msg.reply;
   if (!reply) {
     respondJson(msg, { error: "no_reply_subject" });
     return;
   }
-  if (!intake.body || !intake.cwd || !intake.sessionId) {
+  if (!req.body || !req.cwd || !req.sessionId) {
     respondJson(msg, {
       error: "missing_fields",
       required: ["body", "cwd", "sessionId"]
     });
     return;
   }
-  const sessionId = sanitizeSessionName(intake.sessionId);
+  const sessionId = sanitizeSessionName(req.sessionId);
   if (!sessionId) {
     respondJson(msg, {
       error: "invalid_sessionId",
@@ -366,10 +366,10 @@ async function handleSessionMode(msg, intake) {
     });
     return;
   }
-  if (sessionId !== intake.sessionId) {
+  if (sessionId !== req.sessionId) {
     respondJson(msg, {
       error: "invalid_sessionId",
-      sessionId: intake.sessionId,
+      sessionId: req.sessionId,
       message: `sessionId must match [a-z0-9_-]+; suggested: ${sessionId}`
     });
     return;
@@ -386,7 +386,7 @@ async function handleSessionMode(msg, intake) {
   creating.add(sessionId);
   let created;
   try {
-    created = await createPiSession(intake);
+    created = await createPiSession(req);
   } catch (e) {
     creating.delete(sessionId);
     respondJson(msg, {
@@ -420,7 +420,7 @@ async function handleSessionMode(msg, intake) {
     thinkingLevel: created.thinkingLevel,
     createdAt: Date.now(),
     lastActivity: Date.now(),
-    maxLifetime: intake.maxLifetime ?? config.defaultMaxLifetime ?? DEFAULT_MAX_LIFETIME_SECONDS,
+    maxLifetime: req.maxLifetime ?? config.defaultMaxLifetime ?? DEFAULT_MAX_LIFETIME_SECONDS,
     subject,
     pendingRequests: /* @__PURE__ */ new Map(),
     requestQueue: [],
@@ -435,8 +435,8 @@ async function handleSessionMode(msg, intake) {
   managed.pendingRequests.set(initialId, {
     requestId: initialId,
     replySubject: reply,
-    from: intake.from ?? "anonymous",
-    body: intake.body,
+    from: req.from ?? "anonymous",
+    body: req.body,
     createdAt: Date.now()
   });
   managed.requestQueue.push(initialId);
@@ -450,12 +450,12 @@ async function handleSessionMode(msg, intake) {
     initialId
   );
 }
-async function handleStopMode(msg, intake) {
-  if (!intake.sessionId) {
+async function handleStopMode(msg, req) {
+  if (!req.sessionId) {
     respondJson(msg, { error: "missing_fields", required: ["sessionId"] });
     return;
   }
-  const sid = sanitizeSessionName(intake.sessionId);
+  const sid = sanitizeSessionName(req.sessionId);
   const managed = sessions.get(sid);
   if (!managed) {
     respondJson(msg, { error: "not_found", sessionId: sid });
@@ -623,7 +623,7 @@ async function shutdown(signal) {
   clearInterval(pruneInterval);
   await Promise.allSettled(Array.from(sessions.values()).map((m) => disposeSession(m)));
   try {
-    await intakeService.stop();
+    await controlService.stop();
   } catch {
   }
   try {
@@ -667,18 +667,18 @@ owner = sanitizeSessionName(process.env.USER ?? "unknown") || "unknown";
 authStorage = AuthStorage.create();
 modelRegistry = ModelRegistry.create(authStorage);
 var svcm = new Svcm(nc);
-intakeService = await svcm.add({
+controlService = await svcm.add({
   name: SERVICE_NAME,
   version: SERVICE_VERSION,
-  description: "intake",
-  metadata: { type: "intake", platform: "pi", owner },
+  description: "control",
+  metadata: { type: "control", platform: "pi", owner },
   queue: ""
 });
-intakeService.addEndpoint("intake", {
-  subject: intakeSubject(owner),
-  handler: handleIntakeMessage
+controlService.addEndpoint("control", {
+  subject: controlSubject(owner),
+  handler: handleControlMessage
 });
-process.stderr.write(`pi-exec: intake registered on ${intakeSubject(owner)}
+process.stderr.write(`pi-exec: control registered on ${controlSubject(owner)}
 `);
 lifetimeInterval = setInterval(checkLifetimes, LIFETIME_CHECK_INTERVAL_MS);
 lifetimeInterval.unref();

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@m64/nats-pi-bridge",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Standalone headless service that spawns and manages PI coding agent sessions on demand via NATS. Control plane / data plane split, streaming wire protocol, multi-session microservice registration.",
   "author": "m64",
   "license": "Apache-2.0",
-  "homepage": "",
+  "homepage": "https://github.com/M64GitHub/nats-pi-bridge#readme",
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "git+https://github.com/M64GitHub/nats-pi-bridge.git"
   },
   "bugs": {
-    "url": ""
+    "url": "https://github.com/M64GitHub/nats-pi-bridge/issues"
   },
   "type": "module",
   "engines": {
@@ -31,7 +31,6 @@
   },
   "files": [
     "dist",
-    "DESIGN.md",
     "README.md",
     "LICENSE"
   ],

package/DESIGN.md

@@ -1,350 +0,0 @@
-# nats-pi-bridge — Design Document
-
-## Overview
-
-Standalone headless service that spawns and manages PI coding agent sessions on demand via NATS. Callers send structured JSON commands to an **intake endpoint** (control plane) to create, run, and stop sessions. Persistent sessions also expose **per-session endpoints** (data plane) for follow-up prompts using the standard streaming wire protocol.
-
-Part of the Synadia NATS AI Agents ecosystem alongside:
-- `@m64/nats-channel` — OpenClaw channel plugin (loads into OpenClaw)
-- `nats-claude-channel` — Claude Code channel (loads into Claude Code via MCP)
-- `@m64/nats-pi-channel` — PI extension (loads into interactive PI sessions)
-
-This bridge is different: it does NOT load into PI. It embeds PI headlessly via the SDK.
-
-## Architecture
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  nats-pi-bridge (standalone service)                         │
-│                                                              │
-│  Service: pi-exec                                            │
-│                                                              │
-│  CONTROL PLANE                                               │
-│  ─────────────                                               │
-│  Intake endpoint: agents.pi-exec.<owner>                     │
-│    Structured JSON commands: run, session, stop, list         │
-│                                                              │
-│  DATA PLANE                                                  │
-│  ──────────                                                  │
-│  Per-session endpoints (registered on demand):               │
-│    agents.pi-exec.<owner>.<sessionId>                        │
-│    Wire protocol: plain text or {from,body}, streaming       │
-│    chunks, empty payload = done                              │
-│                                                              │
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
-│  │ abc123  │  │ def456  │  │ (ephem) │                       │
-│  │ nats-zig│  │ sid-gpt │  │ run cmd │                       │
-│  │ persist │  │ persist │  │ no endpt│                       │
-│  └─────────┘  └─────────┘  └─────────┘                      │
-│                                                              │
-│  sessions: Map<sessionId, ManagedSession>                    │
-└──────────────────────────────────────────────────────────────┘
-```
-
-## Key Design Decisions
-
-### Control plane vs data plane separation
-
-The intake endpoint (`agents.pi-exec.<owner>`) is the **control plane**. It handles session lifecycle: create, stop, list. It accepts structured JSON with a `sessionMode` field.
-
-Per-session endpoints (`agents.pi-exec.<owner>.<sessionId>`) are the **data plane**. They handle prompts using the standard wire protocol shared with all sibling implementations (plain text or `{from, body}` envelope, streaming chunks, empty = done).
-
-**No mixing.** Sending a `sessionMode: "session"` command to the intake for an already-existing session is rejected. Follow-up prompts go to the per-session endpoint. This eliminates ambiguity around field handling (what if `cwd` or `model` differ on reuse?).
-
-### Separate microservice name
-
-The bridge registers as `pi-exec`, not `pi-channel`. This cleanly separates headless/dynamic sessions from interactive PI sessions:
-
-```
-nats micro list
-→ pi-channel    (2 instances)   ← interactive (human at keyboard)
-→ pi-exec       (3 instances)   ← headless (bridge-managed)
-→ claude-channel (1 instance)   ← Claude Code
-```
-
-No namespace collision, no awkward subject prefixes, no cross-service confusion.
-
-### Caller-owned session naming
-
-The caller decides the `sessionId`. UUIDs, hashes, descriptive names — whatever the caller's automation needs. The bridge does not do collision detection on session names. If the sessionId already exists, the intake rejects with the session's endpoint subject so the caller can redirect.
-
-**`sessionId` is required on `session` mode requests.** There is no auto-generation — callers must pick and track their own IDs. The intake rejects missing IDs with `{error:"missing_fields", required:[..., "sessionId"]}`, and rejects IDs that would change under sanitization (`[a-z0-9_-]+`) with `{error:"invalid_sessionId", sessionId, suggested}` so the caller knows exactly what to send next time.
-
-Rationale: the caller addresses the per-session subject by `sessionId`, so it must know the exact value up front — returning a generated ID in the first stream chunk would force every caller to parse a response envelope before the real agent output arrives, which breaks the uniform wire protocol shared with the sibling implementations.
-
-### Subject convention
-
-```
-agents.pi-exec.<owner>                    ← intake (permanent)
-agents.pi-exec.<owner>.<sessionId>         ← per-session (dynamic)
-agents.pi-exec.<owner>.<sessionId>.inspect ← per-session inspect
-```
-
-- `owner`: from `$USER`, sanitized (same as pi-channel / claude-channel)
-- No `org` field for now. Can add later if needed.
-
-## Session Modes
-
-Single field `sessionMode` on the intake request. Four values, no invalid combinations.
-
-### `run` (default, simplest case)
-
-Ephemeral single-shot execution. No endpoint registered, no discoverability, no follow-ups.
-
-```json
-{
-  "sessionMode": "run",
-  "body": "List all TODO comments in the codebase",
-  "cwd": "/home/mario/code/nats-zig",
-  "from": "ci-bot"
-}
-```
-
-Flow:
-1. Create PI session with `SessionManager.inMemory()`
-2. Subscribe to events
-3. Call `session.prompt(body)`
-4. Stream `text_delta` chunks to NATS reply subject
-5. On `agent_end`, publish empty payload (done)
-6. `session.dispose()`
-
-No sessionId needed. No tracking. Fire and forget.
-
-### `session` (persistent, addressable)
-
-Creates a long-lived session with a per-session endpoint for follow-ups.
-
-```json
-{
-  "sessionMode": "session",
-  "body": "Run tests and fix failures",
-  "cwd": "/home/mario/code/nats-zig",
-  "sessionId": "my-worker-1",
-  "from": "orchestrator",
-  "model": "anthropic/claude-sonnet-4-5",
-  "thinkingLevel": "medium",
-  "maxLifetime": 3600
-}
-```
-
-Flow:
-1. Validate required fields (`body`, `cwd`, `sessionId`) and sanitize `sessionId`; reject if any are missing or the ID mutates under sanitization
-2. Check if `sessionId` already exists in sessions Map
-3. If exists → **reject** with error response including the session's endpoint subject
-4. If new → create PI session, register a dedicated `pi-exec` microservice instance for this session, add to Map
-5. Run the initial prompt, stream response on the intake's reply subject
-6. Session stays alive for follow-ups via the per-session endpoint; the per-session service instance is torn down via `service.stop()` on `stop` mode or lifetime expiry
-
-On reuse rejection:
-```json
-{
-  "error": "session_exists",
-  "sessionId": "my-worker-1",
-  "subject": "agents.pi-exec.mario.my-worker-1",
-  "message": "Session already exists. Send follow-up prompts to the session subject."
-}
-```
-
-Fields only used on creation: `cwd`, `model`, `thinkingLevel`, `maxLifetime`.
-
-### `stop`
-
-Disposes a session, removes its endpoint.
-
-```json
-{
-  "sessionMode": "stop",
-  "sessionId": "my-worker-1"
-}
-```
-
-Flow:
-1. Look up `sessionId` in sessions Map
-2. If not found → error response
-3. If found → `session.dispose()`, remove endpoint, remove inspect subscription, delete from Map
-4. Respond with confirmation (non-streaming, single message)
-
-### `list`
-
-Returns all active sessions.
-
-```json
-{
-  "sessionMode": "list"
-}
-```
-
-Response (non-streaming, single JSON message):
-```json
-{
-  "sessions": [
-    {
-      "sessionId": "my-worker-1",
-      "subject": "agents.pi-exec.mario.my-worker-1",
-      "cwd": "/home/mario/code/nats-zig",
-      "createdAt": "2026-04-08T14:30:00Z",
-      "lastActivity": "2026-04-08T14:35:22Z",
-      "maxLifetime": 3600,
-      "remainingLifetime": 3278,
-      "activeRequest": false,
-      "queuedRequests": 0
-    }
-  ]
-}
-```
-
-## Intake protocol summary
-
-| sessionMode | Session exists? | Behavior |
-|---|---|---|
-| `run` | n/a | ephemeral: create, prompt, stream, dispose |
-| `session` | no | create, register endpoint, prompt, stream |
-| `session` | yes | **reject** with session info |
-| `stop` | yes | dispose, confirm |
-| `stop` | no | error: not found |
-| `list` | n/a | return all sessions |
-
-## Per-session endpoint protocol
-
-Identical to the standard wire protocol used by all sibling implementations:
-
-- **Inbound**: plain text or JSON envelope `{"from":"sender","body":"text"}`
-- **Outbound**: streaming text chunks on reply subject
-- **Completion**: empty payload on reply subject
-- **Usage**: `nats req agents.pi-exec.mario.my-worker-1 "Fix the linting errors" --wait-for-empty --timeout 120s`
-
-Requests to per-session endpoints are queued and processed serially (one prompt at a time per session).
-
-## PI SDK integration
-
-Each session is an independent `AgentSession` created via `createAgentSession()`:
-
-```typescript
-const { session } = await createAgentSession({
-  cwd: request.cwd,
-  sessionManager: SessionManager.inMemory(),   // run mode
-  // or: SessionManager.open(sessionFile),      // session mode
-  authStorage,
-  modelRegistry,
-  model: resolvedModel,
-  thinkingLevel: request.thinkingLevel ?? "off",
-});
-```
-
-Streaming via `session.subscribe()`:
-
-```typescript
-session.subscribe((event) => {
-  if (event.type === "message_update" &&
-      event.assistantMessageEvent.type === "text_delta") {
-    nc.publish(replySubject, event.assistantMessageEvent.delta);
-  }
-  if (event.type === "agent_end") {
-    nc.publish(replySubject, "");  // done
-  }
-});
-
-await session.prompt(body);
-```
-
-Multiple sessions in one process is supported — OpenClaw does this in production.
-
-## Session lifecycle & safety
-
-### Max lifetime
-
-Optional `maxLifetime` field in seconds (default: 1800 = 30 minutes). Background interval checks the sessions Map and disposes expired sessions, removes their endpoints. Prevents orphaned sessions if a caller forgets to `stop`.
-
-### Stale request pruning
-
-Same pattern as claude-channel and pi-channel: 60-second interval, prune pending requests older than 30 minutes.
-
-### Graceful shutdown
-
-On process SIGTERM/SIGINT:
-1. Stop accepting new intake requests
-2. For each managed session: `session.dispose()`
-3. For each service endpoint: remove
-4. `service.stop()` → `nc.drain()`
-
-## Internal data structures
-
-```typescript
-type ManagedSession = {
-  session: AgentSession;
-  sessionId: string;
-  cwd: string;
-  createdAt: number;
-  lastActivity: number;
-  maxLifetime: number;          // seconds, 0 = no expiry
-  endpoint: ServiceEndpoint;
-  inspectSub: Subscription;
-  requestQueue: string[];       // queued request IDs
-  activeRequestId: string | null;
-  pendingRequests: Map<string, PendingRequest>;
-};
-
-type PendingRequest = {
-  replySubject: string;
-  from: string;
-  createdAt: number;
-};
-
-const sessions = new Map<string, ManagedSession>();
-```
-
-## Discovery
-
-```bash
-# List all services
-nats micro list
-→ pi-exec (1 instance, N endpoints)
-
-# Detailed info — shows intake + all session endpoints
-nats micro info pi-exec
-→ intake:  agents.pi-exec.mario
-→ session: agents.pi-exec.mario.my-worker-1   │ /home/mario/code/nats-zig
-→ session: agents.pi-exec.mario.sid-gpt-abc   │ /home/mario/code/sid-gpt
-
-# Inspect a specific session
-nats req agents.pi-exec.mario.my-worker-1.inspect "" --timeout 5s
-→ {"name":"my-worker-1","description":"PI agent in /home/mario/code/nats-zig",...}
-```
-
-## Configuration
-
-Config file: `~/.pi-exec/config.json` (separate from pi-channel config)
-
-```json
-{
-  "context": "my-nats-context",
-  "defaultModel": "anthropic/claude-sonnet-4-5",
-  "defaultThinkingLevel": "off",
-  "defaultMaxLifetime": 1800
-}
-```
-
-Environment variable overrides:
-- `NATS_CONTEXT` — NATS CLI context name
-- `PI_EXEC_DEFAULT_MODEL` — default model
-- `PI_EXEC_DEFAULT_MAX_LIFETIME` — default max lifetime in seconds
-
-NATS context loading: same pattern as all sibling implementations — reads from `~/.config/nats/context/<n>.json`.
-
-## What is NOT in v1
-
-- No org namespace support (add later if needed)
-- No encryption / E2E
-- No A2A protocol
-- No session persistence to disk (sessions are in-memory, lost on bridge restart)
-- No authentication on the intake (NATS auth handles access control)
-- No model hot-swap on existing sessions
-- No resource limits (max concurrent sessions, memory caps)
-
-## Future considerations
-
-- **Session persistence**: Use `SessionManager.open(path)` instead of `.inMemory()` so sessions survive bridge restarts
-- **Org support**: Add `org` field to intake, extend subject to `agents.pi-exec.<org>.<owner>.<sessionId>`
-- **Resource limits**: Max sessions per bridge, max concurrent prompts across all sessions
-- **Pub/sub notifications**: Publish session lifecycle events (created, stopped, expired) to a notification subject for monitoring
-- **Multi-bridge coordination**: Multiple bridge instances sharing session state via NATS KV — JetStream as the session registry