@shardworks/claude-code-apparatus 0.1.148 → 0.1.150

package/README.md

@@ -0,0 +1,159 @@
+# `@shardworks/claude-code-apparatus`
+
+Claude Code session provider apparatus for Nexus. Implements the `AnimatorSessionProvider` interface for the Claude Code CLI, enabling the Animator to launch and manage AI sessions. Also provides the **Session Babysitter** — a detached process that hosts sessions independently of the guild lifecycle.
+
+Depends on `@shardworks/animator-apparatus` (types), `@shardworks/tools-apparatus` (tool definitions and routing), and `@shardworks/nexus-core`.
+
+---
+
+## Installation
+
+```json
+{
+  "dependencies": {
+    "@shardworks/claude-code-apparatus": "workspace:*"
+  }
+}
+```
+
+## API
+
+### Session Provider
+
+The default export is a `Plugin` whose apparatus `provides` an `AnimatorSessionProvider`:
+
+```typescript
+import createClaudeCodeProvider from '@shardworks/claude-code-apparatus';
+
+// In guild.json:
+// { "animator": { "sessionProvider": "claude-code" } }
+```
+
+The provider implements `launch()` and `cancel()`:
+
+- **`launch(config)`** — spawns a **detached babysitter process** that hosts the session independently of the guild. The babysitter spawns `claude` in autonomous mode, streams transcripts to SQLite, and reports lifecycle events via HTTP. Returns `{ chunks, result, processInfo }` where:
+  - `chunks` completes immediately (empty) — real-time output is available via the transcripts book
+  - `result` polls the sessions book for terminal status (resolves when the babysitter calls `session-record`)
+  - `processInfo` polls the SessionDoc for `cancelMetadata.pid` (set by the babysitter via `session-running`)
+- **`cancel(cancelMetadata)`** — sends SIGTERM to the claude process using the PID from `cancelMetadata`. Works cross-process regardless of parent-child relationships.
+
+An **attached mode** (`launchAttached()`) is preserved as an internal export for debugging — it spawns claude as a direct child process with in-process MCP server and streaming.
+
+### MCP Server
+
+The package exports functions for running MCP tool servers:
+
+```typescript
+import { createMcpServer, startMcpHttpServer } from '@shardworks/claude-code-apparatus';
+
+// Create an MCP server with resolved tool definitions
+const mcpServer = await createMcpServer(toolDefinitions);
+
+// Or start an HTTP server on an ephemeral port
+const handle = await startMcpHttpServer(toolDefinitions);
+console.log(handle.url); // "http://127.0.0.1:PORT/sse"
+await handle.close();    // cleanup
+```
+
+### Stream Parsing
+
+Exported utilities for parsing Claude's NDJSON output:
+
+```typescript
+import {
+  processNdjsonBuffer,
+  parseStreamJsonMessage,
+  extractFinalAssistantText,
+} from '@shardworks/claude-code-apparatus';
+```
+
+- **`processNdjsonBuffer(buffer, handler)`** — splits NDJSON buffer on newlines, calls handler for each parsed JSON object, returns remaining incomplete buffer.
+- **`parseStreamJsonMessage(msg, acc)`** — processes a single NDJSON message, accumulates transcript/metrics, returns `SessionChunk[]`.
+- **`extractFinalAssistantText(transcript)`** — walks transcript backwards to find the last assistant message's text content.
+
+## Session Babysitter
+
+The babysitter is a standalone Node.js script that runs as a detached process, hosting a claude session independently of the guild. It survives guild restarts.
+
+### Entry Point
+
+```bash
+node dist/babysitter.js  # reads config from stdin
+```
+
+Or import the module for programmatic use:
+
+```typescript
+import { runBabysitter } from '@shardworks/claude-code-apparatus/babysitter';
+```
+
+### Config (via stdin)
+
+The spawning process writes JSON config to the babysitter's stdin:
+
+```typescript
+interface BabysitterConfig {
+  sessionId: string;           // Pre-generated session ID
+  guildToolUrl: string;        // Guild's Tool HTTP API URL (e.g. "http://127.0.0.1:7471")
+  dbPath: string;              // Path to guild's SQLite database
+  claudeArgs: string[];        // CLI args for claude (--model, --system-prompt-file, etc.)
+  cwd: string;                 // Working directory for the claude process
+  env: Record<string, string>; // Environment variables for the claude process
+  prompt: string;              // Initial prompt piped to claude's stdin
+  tools: SerializedTool[];     // Tool definitions with JSON Schema params
+  startedAt: string;           // ISO timestamp of session start
+  provider: string;            // Provider name (e.g. "claude-code")
+  metadata?: Record<string, unknown>;  // Optional session metadata
+}
+
+interface SerializedTool {
+  name: string;
+  description: string;
+  params: Record<string, unknown>;  // JSON Schema
+}
+```
+
+### Lifecycle
+
+1. **Read config** from stdin, parse JSON, validate required fields
+2. **Open SQLite** (WAL mode) for real-time transcript streaming
+3. **Start MCP/SSE proxy server** — registers tools that forward calls to the guild's Tool HTTP API with retry and exponential backoff
+4. **Prepare session files** — temp directory, mcp-config.json pointing to the proxy server
+5. **Spawn claude** — pipes prompt to stdin, captures NDJSON stdout
+6. **Report "running"** — calls `session-running` tool on guild via HTTP (DLQ fallback)
+7. **Stream transcript** — parses NDJSON, writes to `books_animator_transcripts` table in SQLite after each message batch
+8. **Report result** — calls `session-record` tool on guild via HTTP (DLQ fallback)
+9. **Cleanup** — close MCP server, close SQLite, remove temp directory
+
+### Error Handling
+
+- **Tool call proxy errors**: retried with exponential backoff (1s initial, 8s max, 60s timeout). If retries exhaust, returns error to claude as MCP tool result — doesn't crash.
+- **Lifecycle reporting errors**: if guild is unreachable, payload is written to `.nexus/dlq/{sessionId}[-running].json` for later drain.
+- **Top-level errors**: attempts to report `status: 'failed'` to guild, falls back to DLQ, then exits non-zero.
+
+## Exports
+
+| Entry point | Description |
+|---|---|
+| `.` (`src/index.ts`) | Session provider plugin, MCP server, stream parsing utilities, `launchAttached()` |
+| `./babysitter` (`src/babysitter.ts`) | Babysitter module — `runBabysitter()`, config parsing, proxy server, transcript DB |
+
+### Internal Modules
+
+| Module | Description |
+|---|---|
+| `src/detached.ts` | Detached launch — `launchDetached()`, tool serialization (`serializeTools()`), polling helpers |
+
+## Configuration
+
+Configured in `guild.json` under the `animator` key:
+
+```json
+{
+  "animator": {
+    "sessionProvider": "claude-code"
+  }
+}
+```
+
+No additional configuration fields. The model is passed per-session via the Animator.

package/dist/babysitter.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Session Babysitter — detached process that hosts a claude session.
+ *
+ * A standalone Node.js script that:
+ * 1. Reads config from stdin (spawned by the claude-code provider)
+ * 2. Opens the guild's SQLite database for transcript streaming
+ * 3. Starts an MCP/SSE server that proxies tool calls to the guild
+ * 4. Spawns claude with prepared session files
+ * 5. Reports session lifecycle events via the guild's HTTP API
+ * 6. Streams transcript data to SQLite in real-time
+ * 7. Reports the final result and cleans up
+ *
+ * The babysitter is a detached process: it survives guild restarts.
+ * All guild communication is via HTTP (tool server) and SQLite (transcripts).
+ *
+ * See: docs/architecture/detached-sessions.md
+ */
+import { spawn } from 'node:child_process';
+import { type StreamJsonResult } from './index.ts';
+/** A serialized tool definition as received in the babysitter config. */
+export interface SerializedTool {
+    /** Tool name (e.g. 'writ-list'). */
+    name: string;
+    /** Tool description. */
+    description: string;
+    /** JSON Schema for the tool's input parameters. */
+    params: Record<string, unknown>;
+}
+/** Config written to the babysitter's stdin by the spawning process. */
+export interface BabysitterConfig {
+    sessionId: string;
+    guildToolUrl: string;
+    dbPath: string;
+    claudeArgs: string[];
+    cwd: string;
+    env: Record<string, string>;
+    prompt: string;
+    tools: SerializedTool[];
+    startedAt: string;
+    provider: string;
+    metadata?: Record<string, unknown>;
+}
+export interface McpProxyHandle {
+    /** URL for --mcp-config (e.g. "http://127.0.0.1:PORT/sse"). */
+    url: string;
+    /** Shut down the HTTP server and MCP transport. */
+    close(): Promise<void>;
+}
+/**
+ * Read the babysitter config from stdin.
+ *
+ * Reads stdin to completion, parses the JSON, and validates required fields.
+ * The spawning process writes config and closes the write end.
+ */
+export declare function readConfigFromStdin(stream?: NodeJS.ReadableStream): Promise<BabysitterConfig>;
+/**
+ * Call a guild HTTP API endpoint with exponential backoff retry.
+ *
+ * Retries on connection errors (ECONNREFUSED, ECONNRESET, ETIMEDOUT).
+ * Returns the parsed JSON response on success.
+ * Throws after RETRY_TIMEOUT_MS of retrying.
+ */
+export declare function callGuildHttpApi(url: string, sessionId: string, body: unknown, timeoutMs?: number): Promise<unknown>;
+/**
+ * Write a payload to the Dead Letter Queue.
+ *
+ * Creates the DLQ directory if it doesn't exist. Writes the payload as
+ * pretty-printed JSON. Used as a fallback when the guild HTTP API is
+ * unreachable for lifecycle calls.
+ */
+export declare function writeToDlq(cwd: string, filename: string, payload: unknown): void;
+/**
+ * Create an MCP/SSE HTTP server that proxies tool calls to the guild.
+ *
+ * For each tool in the config, registers an MCP tool whose handler
+ * forwards the call to the guild's Tool HTTP API via HTTP POST.
+ *
+ * Uses the low-level MCP Server class to register tools with raw
+ * JSON Schema (the serialized params from the config).
+ */
+export declare function createProxyMcpHttpServer(tools: SerializedTool[], guildToolUrl: string, sessionId: string): Promise<McpProxyHandle>;
+/** Minimal interface for the SQLite database used by the babysitter. */
+export interface TranscriptDb {
+    /** Write a transcript entry (id, content JSON). */
+    writeTranscript(sessionId: string, content: string): void;
+    /** Close the database connection. */
+    close(): void;
+}
+/**
+ * Open the guild's SQLite database for transcript streaming.
+ *
+ * Creates the database file and table if they don't exist.
+ * Enables WAL mode for concurrent read access by other processes
+ * (Oculus, CLI queries, other agents).
+ *
+ * Uses dynamic import() to load better-sqlite3 at runtime. This avoids
+ * requiring the native module at import time (beneficial for type-checking
+ * and testing).
+ */
+export declare function openTranscriptDb(dbPath: string): Promise<TranscriptDb>;
+/**
+ * Initialize a TranscriptDb from a Database constructor.
+ *
+ * Shared logic between openTranscriptDb() and test injection.
+ * Exported for testing — allows injecting a mock Database constructor.
+ */
+export declare function initTranscriptDb(DatabaseConstructor: new (path: string) => {
+    pragma(stmt: string): unknown;
+    prepare(sql: string): {
+        run(...params: unknown[]): void;
+    };
+    exec(sql: string): void;
+    close(): void;
+}, dbPath: string): TranscriptDb;
+/**
+ * Write the current transcript to SQLite.
+ */
+export declare function writeTranscript(db: TranscriptDb, sessionId: string, messages: Record<string, unknown>[]): void;
+/**
+ * Report "running" status to the guild via the session-running tool.
+ *
+ * If the guild is unreachable, writes the payload to the DLQ.
+ */
+export declare function reportRunning(config: BabysitterConfig, claudePid: number, timeoutMs?: number): Promise<void>;
+/**
+ * Report the final session result to the guild via the session-record tool.
+ *
+ * If the guild is unreachable, writes the payload to the DLQ.
+ */
+export declare function reportResult(config: BabysitterConfig, result: StreamJsonResult, transcript: Record<string, unknown>[], timeoutMs?: number): Promise<void>;
+/**
+ * Run the session babysitter.
+ *
+ * This is the main orchestration function. It:
+ * 1. Opens SQLite for transcript streaming
+ * 2. Starts the MCP proxy server
+ * 3. Prepares session files (tmpDir, system prompt, mcp-config)
+ * 4. Spawns claude
+ * 5. Reports "running" status
+ * 6. Streams transcript to SQLite
+ * 7. Reports result on exit
+ * 8. Cleans up
+ */
+export declare function runBabysitter(config: BabysitterConfig, deps?: {
+    /** Injected TranscriptDb for testing (avoids loading better-sqlite3). */
+    db?: TranscriptDb;
+    /** Override spawn for testing. */
+    spawnFn?: typeof spawn;
+    /** Override retry timeout for testing (default: 60_000ms). */
+    retryTimeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=babysitter.d.ts.map

package/dist/babysitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"babysitter.d.ts","sourceRoot":"","sources":["../src/babysitter.ts"],"names":[],"mappings":"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"}