agent-tempo 1.0.1

package/dist/adapters/claude-code-headless/stream-json.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Stream-JSON frame parser for `claude -p --output-format stream-json`.
+ *
+ * Issue #520 PR-3. Parses the newline-delimited JSON envelope the Claude
+ * Code CLI emits during a per-turn invocation, accumulating the bits the
+ * adapter needs (assembled assistant text, stop reason, usage, cost, plus
+ * the fatal-/transient-classifier inputs).
+ *
+ * **Schema is grounded in the §11.1 spike fixtures** captured against
+ * `claude --version` 2.1.126 — see `tests/adapters/fixtures/claude-code-headless/`.
+ * Three deltas vs design §5.3 (documented in §16 spike-findings appendix):
+ *
+ *   1. **`result` frame has a `subtype: 'success' | 'error'`** — design listed
+ *      `result` as a top-level type. Reality: `subtype` distinguishes success
+ *      vs error envelopes. Bonus: `is_error: boolean` + `api_error_status:
+ *      number | null` are clean classifier inputs (see {@link ResultFrame}).
+ *   2. **`system/hook_started` + `system/hook_response` + `system/status`** —
+ *      not in design. Emitted whenever the host has Claude Code hooks
+ *      configured (most operators do — SessionStart hooks for project
+ *      context). The `output`/`stdout` fields can carry arbitrary user
+ *      content, so we IGNORE them outright (the fixture corpus shows a
+ *      107KB SessionStart hook body in real captures).
+ *   3. **`rate_limit_event` is a top-level type** — design assumed it was
+ *      a `system/api_retry` subtype. Reality: it's its own frame. AND it
+ *      carries TWO signal modes (informational vs action-required) on the
+ *      same wire shape, distinguished by `rate_limit_info.status`. See
+ *      {@link RateLimitEvent}.
+ *
+ * Pure code; no I/O; trivially unit-testable with synthesized + captured
+ * fixtures. The error classifier (`./error-mapper.ts`) consumes the
+ * accumulator state to emit a single `ApiErrorCategory` per turn.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamJsonReader = void 0;
+exports.newTurnAccumulator = newTurnAccumulator;
+exports.applyFrame = applyFrame;
+/** Build a fresh accumulator. */
+function newTurnAccumulator() {
+    return {
+        assembledText: '',
+        stopReason: null,
+        usage: null,
+        totalCostUsd: null,
+        resultIsError: null,
+        resultApiErrorStatus: null,
+        resultSubtype: null,
+        resultFrameSeen: false,
+        apiRetryEvents: [],
+        rateLimitEvents: [],
+        pluginErrors: [],
+        initModel: null,
+        initApiKeySource: null,
+    };
+}
+/**
+ * Fold one stream-json frame into the accumulator. Pure mutation — return
+ * the same instance for chaining.
+ *
+ * Unknown frame types are silently passed through (the parser is tolerant
+ * by design — Claude Code may add new frame types between minor versions
+ * and we don't want to crash on them; the adapter only ever acts on the
+ * categories we recognize).
+ *
+ * The hook + status frames are explicitly enumerated as IGNORED rather
+ * than falling through `default`, so future readers don't think the
+ * pass-through is accidental.
+ */
+function applyFrame(state, frame) {
+    switch (frame.type) {
+        case 'system':
+            switch (frame.subtype) {
+                case 'init': {
+                    const init = frame;
+                    state.initModel = init.model ?? null;
+                    state.initApiKeySource = init.apiKeySource ?? null;
+                    if (init.plugin_errors && init.plugin_errors.length > 0) {
+                        state.pluginErrors = init.plugin_errors;
+                    }
+                    return state;
+                }
+                case 'api_retry':
+                    state.apiRetryEvents.push(frame);
+                    return state;
+                case 'hook_started':
+                case 'hook_response':
+                case 'status':
+                    // Delta #2 — explicitly ignored. Hook output may carry arbitrary
+                    // operator content (107KB+ in real captures); we don't need it.
+                    return state;
+                default:
+                    return state;
+            }
+        case 'rate_limit_event':
+            // Delta #3 — top-level frame, NOT a system subtype. Two signal modes
+            // overloaded on one type: informational (every turn) vs action-required
+            // (when capped). Classifier distinguishes by `rate_limit_info.status`.
+            state.rateLimitEvents.push(frame);
+            return state;
+        case 'assistant': {
+            // Telemetry only — the canonical assembled text comes from the closing
+            // `result` frame's `result` field. Architect-locked: assistant-frame
+            // text accumulator is observed-only; `result.result` wins.
+            //
+            // We DO opportunistically accumulate text-block content as a fallback
+            // for the case where the subprocess exits without a `result` frame
+            // (turn aborted mid-stream) — better to surface partial output than
+            // nothing. Filter on `c.type === 'text'` to skip thinking + tool_use
+            // blocks (Delta #1 bonus finding — Opus 4.7 emits 'thinking' blocks).
+            const a = frame;
+            const blocks = a.message?.content ?? [];
+            for (const block of blocks) {
+                if (block && block.type === 'text' && typeof block.text === 'string') {
+                    state.assembledText += block.text;
+                }
+            }
+            return state;
+        }
+        case 'user':
+        case 'stream_event':
+            // Tool-result + token-delta frames — telemetry only. We let Claude
+            // Code own the entire tool-dispatch loop (it speaks MCP natively
+            // with the inline --mcp-config we synthesize); the adapter only
+            // observes the conversation, never participates in tool dispatch.
+            return state;
+        case 'result': {
+            const r = frame;
+            state.resultFrameSeen = true;
+            state.resultSubtype = r.subtype ?? null;
+            state.resultIsError = typeof r.is_error === 'boolean' ? r.is_error : null;
+            state.resultApiErrorStatus = typeof r.api_error_status === 'number' ? r.api_error_status : null;
+            if (typeof r.result === 'string') {
+                // Result frame's `result` field is the canonical assembled text.
+                // Overwrites the assistant-frame fallback we accumulated above —
+                // the CLI may have applied final formatting / truncation.
+                state.assembledText = r.result;
+            }
+            state.stopReason = r.stop_reason ?? state.stopReason;
+            if (r.usage)
+                state.usage = r.usage;
+            if (typeof r.total_cost_usd === 'number')
+                state.totalCostUsd = r.total_cost_usd;
+            return state;
+        }
+        default:
+            // Unknown frame type — defensive default. Future CLI versions may
+            // add new types and we don't want to crash; just observe and move on.
+            return state;
+    }
+}
+/**
+ * Stateful line-buffered stream-json reader. Feed it raw stdout chunks;
+ * call `flush()` after subprocess exit to emit any trailing partial line.
+ *
+ * Exposed as a class so the adapter can wire it to the `claude -p`
+ * subprocess's `stdout.on('data', ...)` event without needing a
+ * Transform stream subclass — keeps the dep surface minimal.
+ *
+ * Malformed JSON lines are skipped with a logged warning (defensive —
+ * shouldn't happen in practice but a single bad line shouldn't crash
+ * the turn).
+ */
+class StreamJsonReader {
+    buffer = '';
+    state = newTurnAccumulator();
+    onParseError;
+    constructor(opts = {}) {
+        this.onParseError = opts.onParseError;
+    }
+    /** Feed a chunk of stdout. Triggers `applyFrame` for every complete line. */
+    feed(chunk) {
+        this.buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            this.parseLine(line);
+        }
+    }
+    /** Process any trailing line that didn't end with a newline. Idempotent. */
+    flush() {
+        const trailing = this.buffer.trim();
+        this.buffer = '';
+        this.parseLine(trailing);
+    }
+    /** Snapshot of the current accumulator. Caller may freely mutate. */
+    snapshot() {
+        return this.state;
+    }
+    parseLine(line) {
+        if (!line)
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch (err) {
+            this.onParseError?.(line, err);
+            return;
+        }
+        if (!frame || typeof frame !== 'object' || typeof frame.type !== 'string') {
+            this.onParseError?.(line, new Error('frame missing required `type` field'));
+            return;
+        }
+        this.state = applyFrame(this.state, frame);
+    }
+}
+exports.StreamJsonReader = StreamJsonReader;

package/dist/adapters/claude-code-headless/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure-constant types for the claude-code-headless adapter.
+ *
+ * Lives in its own file so consumers (the adapter class, the spawn
+ * helper, the recruit tool's Zod schema, the `RecruitOutboxEntry` shape,
+ * the `SpawnProcessInput` shape) can import the canonical permission-mode
+ * tuple WITHOUT dragging in `@temporalio/client` (which the adapter class
+ * needs but the others don't). DRY single-source-of-truth — adding a new
+ * permission mode means editing exactly one tuple. Addresses QA Nit 3
+ * from PR-1's review.
+ */
+/**
+ * Permission-mode tuple accepted by `claude -p --permission-mode`. Single
+ * source of truth — all of:
+ *
+ *   - `ClaudeCodeHeadlessPermissionMode` type (this file)
+ *   - `recruit` MCP tool Zod enum
+ *   - `RecruitOutboxEntry.permissionMode`
+ *   - `SpawnProcessInput.permissionMode`
+ *   - `ClaudeCodeHeadlessAdapterOpts.permissionMode` (spawn helper)
+ *   - `ClaudeCodeHeadlessAdapterOptions.permissionMode` (adapter class)
+ *
+ * import / re-derive from this tuple. Adding a new mode requires editing
+ * only this tuple; the type + Zod enum + every consumer's schema follow.
+ */
+export declare const CLAUDE_CODE_PERMISSION_MODES: readonly ["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"];
+/** Permission mode for `claude -p --permission-mode`. Derived from {@link CLAUDE_CODE_PERMISSION_MODES}. */
+export type ClaudeCodeHeadlessPermissionMode = typeof CLAUDE_CODE_PERMISSION_MODES[number];

package/dist/adapters/claude-code-headless/types.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Pure-constant types for the claude-code-headless adapter.
+ *
+ * Lives in its own file so consumers (the adapter class, the spawn
+ * helper, the recruit tool's Zod schema, the `RecruitOutboxEntry` shape,
+ * the `SpawnProcessInput` shape) can import the canonical permission-mode
+ * tuple WITHOUT dragging in `@temporalio/client` (which the adapter class
+ * needs but the others don't). DRY single-source-of-truth — adding a new
+ * permission mode means editing exactly one tuple. Addresses QA Nit 3
+ * from PR-1's review.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_CODE_PERMISSION_MODES = void 0;
+/**
+ * Permission-mode tuple accepted by `claude -p --permission-mode`. Single
+ * source of truth — all of:
+ *
+ *   - `ClaudeCodeHeadlessPermissionMode` type (this file)
+ *   - `recruit` MCP tool Zod enum
+ *   - `RecruitOutboxEntry.permissionMode`
+ *   - `SpawnProcessInput.permissionMode`
+ *   - `ClaudeCodeHeadlessAdapterOpts.permissionMode` (spawn helper)
+ *   - `ClaudeCodeHeadlessAdapterOptions.permissionMode` (adapter class)
+ *
+ * import / re-derive from this tuple. Adding a new mode requires editing
+ * only this tuple; the type + Zod enum + every consumer's schema follow.
+ */
+exports.CLAUDE_CODE_PERMISSION_MODES = [
+    'acceptEdits',
+    'auto',
+    'bypassPermissions',
+    'default',
+    'dontAsk',
+    'plan',
+];

package/dist/adapters/copilot/adapter.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Copilot adapter — SDK class.
+ *
+ * Content lifted verbatim from `src/copilot-bridge.ts` into a class wrapper as
+ * part of PR-B (v0.25 rebuild step 2/7). Zero behavior change: the same
+ * createSession / event-logger / poll / sendAndWait / cleanup flow runs, and
+ * the PR-A compat shim in `src/workflows/session.ts` translates
+ * `updateMetadata({ status })` onto the attachment phase machine.
+ *
+ * Dual-purpose file:
+ *   - `import { CopilotSdkAttachment } from '.../adapter'` → class reference for
+ *     the adapter registry. `run()` is NOT invoked.
+ *   - `node .../adapter.js` (or `ts-node .../adapter.ts`) → executes `run()` as
+ *     the spawned subprocess entry point, gated by `require.main === module`.
+ *
+ * PR-C rewrites this adapter against the v0.25 attachment wire protocol —
+ * `claimAttachment` + heartbeat, `processingStart`/`End` via SdkAttachment.deliver()
+ * wrapper, `onSuperseded` cancellation hook. Until then, the bridge runs its
+ * lifecycle stand-alone.
+ *
+ * Usage (dev / prod):
+ *   npx ts-node src/adapters/copilot/adapter.ts
+ *   node dist/adapters/copilot/adapter.js
+ *
+ * Environment variables:
+ *   AGENT_TEMPO_ENSEMBLE     — ensemble name (default: "default")
+ *   AGENT_TEMPO_PLAYER_NAME  — player ID for workflow registration (set by spawner for deterministic workflow IDs)
+ *   COPILOT_BRIDGE_NAME       — player name for set_name (optional)
+ *   COPILOT_BRIDGE_MODEL      — model to use (optional)
+ *   COPILOT_BRIDGE_SESSION_ID — deterministic session ID for resumable sessions (optional)
+ *   GITHUB_TOKEN              — GitHub auth token (optional, uses logged-in user by default)
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §6 (Class 2 —
+ * SDK), §4.2, §4.4.
+ */
+import type { AdapterDescriptor } from '../../types';
+import { SdkAttachment } from '../sdk/base';
+/**
+ * Descriptor for the copilot adapter. Kept colocated with the class so
+ * `adapter.ts` has no import dependency on `index.ts` (breaks the circular
+ * module-graph cycle flagged in QA review of PR-B). `index.ts` re-exports
+ * this constant alongside the class.
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §4.2–4.3.
+ */
+export declare const copilotDescriptor: AdapterDescriptor;
+/**
+ * SDK-class adapter for the GitHub Copilot CLI.
+ *
+ * Delivery model is pull-based (blocks on LLM turn): the bridge polls the
+ * workflow for pending messages, injects them as prompts via the Copilot SDK's
+ * `session.sendAndWait`, then marks them delivered. `processingStart`/`End` are
+ * paired around each blocking call so the workflow's stale detection doesn't
+ * misclassify a long tool execution as a dead session (fix for #99).
+ *
+ * PR-B lands this as a verbatim lift from the old `src/copilot-bridge.ts`.
+ * PR-C moves the processingStart/End wrapping up into SdkAttachment.deliver()
+ * and introduces `claimAttachment` + heartbeat + `onSuperseded` hooks.
+ */
+export declare class CopilotSdkAttachment extends SdkAttachment {
+    readonly descriptor: AdapterDescriptor;
+    /**
+     * The currently-active Copilot SDK session, stashed here so the
+     * `onSuperseded` hook can disconnect it on lease revocation. Populated in
+     * `run()` after `copilotClient.createSession(...)` and refreshed on each
+     * successful `recreateSession()`. `undefined` before the session is created
+     * and after shutdown.
+     */
+    private activeSession?;
+    /**
+     * Split-brain cancellation hook (§9.3). Called by `SdkAttachment` when the
+     * base-class phase watcher detects that our `attachmentId` no longer matches
+     * the current attachment on the workflow — i.e., another claimant stole the
+     * lease. We tear down the active Copilot session: it's the only
+     * cancellation primitive the SDK exposes, and the adapter is about to exit
+     * anyway.
+     *
+     * Residual ghost-reply window: if `sendAndWait` is already producing a reply
+     * over the network, disconnect may race the response. The reply is dropped
+     * (processingEnd will throw `AttachmentMismatch`, markDelivered never fires)
+     * so delivery semantics stay at-most-once. One LLM turn is wasted; this is
+     * documented in the adapter README per §9.3's guidance.
+     */
+    protected onSuperseded(): void;
+    /**
+     * Entry point for the bridge subprocess.
+     *
+     * Kept as a single async method (instead of being broken up into lifecycle
+     * hooks) to preserve the exact behavior of the pre-PR-B `main()` function.
+     * The bridge claims the attachment via `startV2Lifecycle`, drives
+     * `deliver()` through `SdkAttachment` (synchronous processingStart/End
+     * per §7.1, `expectedAttachmentId` carried on both), and installs
+     * `onSuperseded` to disconnect the Copilot session on lease revocation.
+     *
+     * PR-H (#132): the legacy fire-and-forget processingStart/End path
+     * gated on `AGENT_TEMPO_LIFECYCLE_V2=0` has been removed. V2 is the
+     * only path.
+     */
+    run(): Promise<void>;
+}