agent-tempo 1.0.1

package/dist/adapters/claude-code/adapter.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractiveAttachment = exports.claudeCodeDescriptor = void 0;
+const base_1 = require("../base");
+const terminal_error_1 = require("../terminal-error");
+const config_1 = require("../../config");
+const log = (...args) => console.error('[agent-tempo:poller]', ...args);
+/**
+ * Descriptor for the claude-code 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.
+ */
+exports.claudeCodeDescriptor = {
+    adapterId: 'claude-code',
+    adapterClass: 'interactive',
+    blocksOnLLMTurn: false,
+    // Interactive class — 60s cadence per design §4.3. The base class drives the
+    // heartbeat loop at this interval when the V2 lifecycle path is active.
+    heartbeatMs: 60_000,
+};
+const POLL_BASE_MS = 2000;
+const POLL_BACKOFF_FACTOR = 1.5;
+const POLL_MAX_MS = 30000;
+/**
+ * Poll a session workflow for pending messages and deliver them via `onMessages`.
+ *
+ * Module-private; callers go through {@link InteractiveAttachment.start}. Runs
+ * on the V2 runId-pinned handle so `markDelivered` signals reach the correct
+ * execution.
+ *
+ * **Terminal-error handling (#249 Bug 4):** pre-#249 this loop's catch-all
+ * swallowed every error including `WorkflowNotFoundError` from a CAN-closed
+ * pinned runId, so the poller spun forever against a dead run while the
+ * successor accepted messages no one was draining. Post-fix: classify via
+ * the shared {@link isTerminalWorkflowError}, stop cleanly when seen, and
+ * rely on the base class's heartbeat/watcher `handleRunEndError` path to
+ * run the CAN rebind — which then calls `onReconnected` on
+ * {@link InteractiveAttachment} to start a fresh poller on the successor.
+ *
+ * This fix depends on Bugs 1+2 (tick orphan resistance) — if the heartbeat
+ * loop is dead, `onReconnected` never fires and the poller stays stopped
+ * without a replacement. See the Bug 4 commit message for the revert-together
+ * dependency.
+ */
+function startMessagePoller(handle, onMessages) {
+    let stopped = false;
+    let timeout = null;
+    let currentInterval = POLL_BASE_MS;
+    let consecutiveErrors = 0;
+    const cleanupTimer = () => {
+        if (timeout) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+    };
+    const poll = async () => {
+        if (stopped)
+            return;
+        try {
+            const messages = await handle.query('pendingMessages');
+            if (messages.length > 0) {
+                const ids = messages.map((m) => m.id);
+                // Deliver messages first — only mark delivered after successful notification.
+                // If onMessages throws, messages stay undelivered and retry on next poll cycle.
+                await onMessages(messages);
+                await handle.signal('markDelivered', ids);
+            }
+            // Reset backoff on successful poll
+            currentInterval = POLL_BASE_MS;
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            // #249 Bug 4: surface terminal-class errors instead of swallowing. The
+            // pinned-runId handle throws `WorkflowNotFoundError` /
+            // `WorkflowExecutionAlreadyCompleted` when its run has CAN'd or been
+            // destroyed. Keep polling against the closed run is pointless and masks
+            // the lifecycle event from logs. Stop the poller here; the base class's
+            // heartbeat/watcher tick will trigger CAN rebind or terminal, and
+            // `onReconnected` restarts a fresh poller on the live run.
+            if ((0, terminal_error_1.isTerminalWorkflowError)(err)) {
+                log(`poll hit terminal workflow error — stopping (onReconnected will restart on successor if recoverable):`, err?.message ?? err);
+                stopped = true;
+                cleanupTimer();
+                return;
+            }
+            consecutiveErrors++;
+            // Apply exponential backoff on errors
+            currentInterval = Math.min(currentInterval * POLL_BACKOFF_FACTOR, POLL_MAX_MS);
+            log(`Poll error (attempt ${consecutiveErrors}, next in ${Math.round(currentInterval)}ms):`, err);
+        }
+        if (!stopped) {
+            timeout = setTimeout(poll, currentInterval);
+        }
+    };
+    // Start the first poll
+    timeout = setTimeout(poll, POLL_BASE_MS);
+    return () => {
+        stopped = true;
+        cleanupTimer();
+    };
+}
+/**
+ * Interactive adapter for the Claude Code CLI.
+ *
+ * Delivery model is push-based: messages are fetched via the `pendingMessages`
+ * query, notified to the MCP server via `notifications/claude/channel`, then
+ * `markDelivered` is signaled to the workflow. Delivery does not block on an
+ * LLM turn (`blocksOnLLMTurn: false`).
+ *
+ * V2 attachment lifecycle: the adapter calls `claimAttachment` via
+ * `startV2Lifecycle()`, pins the runId, and runs the delivery poll on the
+ * pinned handle. Base class drives heartbeat + phase watcher in parallel.
+ *
+ * Reconnect (#201): the adapter opts into the base class's reconnect loop
+ * via {@link shouldReconnect}. On a recoverable terminal (lease reaped
+ * workflow-side without a competitor, or superseded-then-released), the
+ * base class runs a budget-bounded backoff + fresh-claim flow, then calls
+ * {@link onReconnected} with a freshly pinned handle so the delivery poll
+ * can resume. Truly terminal events (`destroy`, `reconnect-exhausted`)
+ * still tear the adapter down permanently.
+ *
+ * CAN rebind (#226): when the session workflow continues-as-new, the pinned
+ * runId starts returning `WorkflowExecutionAlreadyCompleted`. The base class
+ * reads the closed run's history, extracts the successor runId from the
+ * `WorkflowExecutionContinuedAsNewEvent`, rebinds `pinnedHandle` in place (no
+ * re-claim — the workflow's §2.3 CAN-boundary lease extension keeps the lease
+ * alive across the transition), and calls {@link onReconnected} so we restart
+ * the poller on the live run. Transparent to upstream.
+ *
+ * PR-H (#132): the legacy unpinned-poll fallback (gated on
+ * `AGENT_TEMPO_LIFECYCLE_V2=0`) has been removed. V2 is the only path.
+ */
+class InteractiveAttachment extends base_1.BaseAttachment {
+    descriptor = exports.claudeCodeDescriptor;
+    /** Current delivery poller stopper; null when no poll is running (pre-claim, mid-reconnect, post-terminal). */
+    stopPoller = null;
+    /** Retained across `onReconnected` calls so the poller can be restarted on a new pinned handle. */
+    onMessages = null;
+    /** True once user-initiated `stop()` has fired or the adapter reached a true terminal. */
+    localStopped = false;
+    constructor(options = {}) {
+        super(options);
+    }
+    /**
+     * Start polling for pending messages and delivering each batch via `onMessages`.
+     * Returns a `stop()` function the caller invokes on shutdown.
+     *
+     * The `handle` argument is forwarded for its `workflowId` only — V2 mode
+     * claims its own runId-pinned handle via the base class for all subsequent
+     * queries/signals.
+     */
+    start(handle, onMessages) {
+        return this.startV2(handle.workflowId, onMessages);
+    }
+    /**
+     * V2 path: claim the attachment, pin the handle, then run the poll/deliver/
+     * markDelivered loop against the pinned handle. The base class simultaneously
+     * drives heartbeats and the `attachmentInfo` watcher, and (via {@link shouldReconnect})
+     * may reclaim on recoverable lease loss without this method firing terminal.
+     *
+     * Returns a stop function that tears down the delivery poll AND the base
+     * class lifecycle. Safe to call multiple times.
+     *
+     * **Error handling:** a `claimAttachment` rejection at startup
+     * (`AttachmentConflict`, `WorkflowGone`) propagates up — the caller in
+     * `server.ts` treats it like any other startup failure. Runtime lease loss
+     * on the pinned handle is first routed through `shouldReconnect`; only truly
+     * terminal reasons (`destroy`, `reconnect-exhausted`) reach `onTerminal`
+     * and tear down the poller permanently.
+     */
+    startV2(workflowId, onMessages) {
+        this.onMessages = onMessages;
+        const stop = () => {
+            if (this.localStopped)
+                return;
+            this.localStopped = true;
+            if (this.stopPoller) {
+                this.stopPoller();
+                this.stopPoller = null;
+            }
+            // Fire-and-forget — V2 graceful exit signals adapterExited to the workflow.
+            void this.stopV2Lifecycle('user-stop', /* graceful */ true);
+        };
+        // Terminal events from the base class: `destroy`, `reconnect-exhausted`, or any
+        // non-reconnectable reason. By the time this fires, the reconnect loop (if
+        // applicable) has already given up; tear the poller down permanently.
+        this.onTerminal((reason) => {
+            log(`terminal (${reason}) — stopping delivery poll permanently`);
+            this.localStopped = true;
+            if (this.stopPoller) {
+                this.stopPoller();
+                this.stopPoller = null;
+            }
+        });
+        // PR-D: when spawned by `restart` or `migrate`, the workflow has
+        // pre-claimed an attachment and passed its id through env. Forward to
+        // `startV2Lifecycle` so the update takes the §9.2 renewal path and the
+        // adapter takes over the existing lease atomically. Absent on first-recruit
+        // spawn (fresh-claim path).
+        const expectedAttachmentId = process.env[config_1.ENV.ATTACHMENT_ID] || undefined;
+        // Kick off claim + heartbeat + watcher. If this throws (conflict/gone),
+        // the caller's startup bails — we haven't started the poll yet.
+        this.startV2Lifecycle(workflowId, expectedAttachmentId)
+            .then((pinned) => {
+            if (this.localStopped)
+                return; // caller bailed between await and here
+            this.stopPoller = startMessagePoller(pinned, onMessages);
+        })
+            .catch((err) => {
+            log(`startV2Lifecycle failed: ${err?.message ?? err}`);
+            // Surface via stop — caller's shutdown path sees the error in logs
+            // and proceeds with graceful shutdown. We don't re-throw here because
+            // start() is synchronous by contract.
+            this.localStopped = true;
+        });
+        return stop;
+    }
+    /**
+     * #201 / #226: reconnect opt-in. The interactive adapter is stateless wrt
+     * in-flight messages (no processing-signal pairing; `markDelivered` is
+     * idempotent), so every recoverable reason is safe to replay on a fresh or
+     * re-bound lease:
+     *
+     *   - `heartbeat-timeout` (#201): the workflow reaped our lease (e.g. laptop
+     *     slept). Re-claim and resume — full budget-bounded reconnect loop.
+     *   - `superseded` (#201): another adapter currently holds our slot. The
+     *     reconnect loop's pre-check will re-query and bail cleanly if that's
+     *     still true; we enter the loop in case the competitor releases during
+     *     our backoff.
+     *   - `continued-as-new` (#226): the session workflow's CAN transition closed
+     *     our pinned runId while the workflow id kept running on a successor. The
+     *     base class transparently rebinds to the successor runId (no re-claim —
+     *     the lease is carried across CAN per §2.3) and our poller resumes.
+     *
+     * Unrecoverable reasons (`destroy`, `gone`, anything else) fall through to
+     * the default `false`, firing terminal directly.
+     */
+    shouldReconnect(reason) {
+        return (reason === 'heartbeat-timeout' ||
+            reason === 'superseded' ||
+            reason === 'continued-as-new');
+    }
+    /**
+     * Tear down the current poller immediately when entering the reconnect loop.
+     * The old pinned handle may still respond to `pendingMessages` queries but
+     * the workflow side will ignore our `markDelivered` signals (our `attachmentId`
+     * is no longer current), so continuing to poll wastes I/O and logs noise.
+     */
+    async onReconnectStart(_reason) {
+        if (this.stopPoller) {
+            this.stopPoller();
+            this.stopPoller = null;
+        }
+    }
+    /**
+     * Fresh pinned handle is live — restart the delivery poller. The workflow's
+     * `pendingMessages` queue carries everything that landed while we were
+     * detached; the first poll will drain it in one batch.
+     */
+    async onReconnected(handle) {
+        if (this.localStopped || !this.onMessages)
+            return;
+        // Belt-and-suspenders: if onReconnectStart was skipped somehow, don't leak.
+        if (this.stopPoller) {
+            this.stopPoller();
+            this.stopPoller = null;
+        }
+        this.stopPoller = startMessagePoller(handle, this.onMessages);
+    }
+}
+exports.InteractiveAttachment = InteractiveAttachment;

package/dist/adapters/claude-code/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * claude-code adapter — barrel export.
+ *
+ * Re-exports the descriptor and class from `./adapter`. `src/adapters/index.ts`
+ * imports the descriptor here at module load and registers it with the
+ * singleton {@link AdapterRegistry}. Direct consumers should fetch from the
+ * registry, not import the descriptor directly.
+ *
+ * The descriptor constant itself lives colocated with the class in `./adapter`
+ * so this file has no inward-pointing imports — breaks the module-graph cycle
+ * flagged in PR-B QA review.
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §4.2.
+ */
+export { InteractiveAttachment, claudeCodeDescriptor } from './adapter';

package/dist/adapters/claude-code/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeDescriptor = exports.InteractiveAttachment = void 0;
+/**
+ * claude-code adapter — barrel export.
+ *
+ * Re-exports the descriptor and class from `./adapter`. `src/adapters/index.ts`
+ * imports the descriptor here at module load and registers it with the
+ * singleton {@link AdapterRegistry}. Direct consumers should fetch from the
+ * registry, not import the descriptor directly.
+ *
+ * The descriptor constant itself lives colocated with the class in `./adapter`
+ * so this file has no inward-pointing imports — breaks the module-graph cycle
+ * flagged in PR-B QA review.
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §4.2.
+ */
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "InteractiveAttachment", { enumerable: true, get: function () { return adapter_1.InteractiveAttachment; } });
+Object.defineProperty(exports, "claudeCodeDescriptor", { enumerable: true, get: function () { return adapter_1.claudeCodeDescriptor; } });

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

@@ -0,0 +1,131 @@
+import { type ChildProcess } from 'child_process';
+import type { AdapterDescriptor, Message } from '../../types';
+import { SdkAttachment, type SdkDeliverResult } from '../sdk/base';
+/**
+ * Descriptor for the claude-code-headless adapter. Colocated with the
+ * class so `adapter.ts` has no import dependency on `index.ts` (avoids
+ * the circular module-graph cycle QA flagged on copilot's PR-B).
+ *
+ * Design reference: `docs/design/520-claude-code-headless-adapter.md` §2.
+ */
+export declare const claudeCodeHeadlessDescriptor: AdapterDescriptor;
+export { CLAUDE_CODE_PERMISSION_MODES, type ClaudeCodeHeadlessPermissionMode, } from './types';
+import type { ClaudeCodeHeadlessPermissionMode } from './types';
+/** Construction options for {@link ClaudeCodeHeadlessAttachment}. */
+export interface ClaudeCodeHeadlessAdapterOptions {
+    /** `--permission-mode` flag value. Default: `'acceptEdits'`. */
+    permissionMode?: ClaudeCodeHeadlessPermissionMode;
+    /** Pass `--dangerously-skip-permissions` instead of `--permission-mode`. Mutually exclusive with `permissionMode`. */
+    dangerouslySkipPermissions?: boolean;
+}
+/**
+ * SDK-class adapter that drives `claude -p` as a per-turn subprocess.
+ *
+ * **PR-2 status**: lifecycle + spawn scaffold complete. `run()` boots the
+ * full V2 lifecycle, hydrates the per-cwd session UUID via the shared
+ * `sessionId` metadata field, and drives the poll loop. `onSuperseded()`
+ * SIGTERMs `this.childProcess` (which PR-3 populates inside `invokeSdk`).
+ * `invokeSdk()` still throws — calling it errors the turn loudly until
+ * PR-3 wires the per-turn `claude -p` invocation.
+ *
+ * Lifecycle inherited from `SdkAttachment` / `BaseAttachment`: claim,
+ * heartbeat, phase watcher, `processingStart`/`End` pairing,
+ * `markDelivered`. No reconnect opt-in (matches claude-api / opencode —
+ * the daemon's `reconcile-on-boot` recovers from lease loss).
+ */
+export declare class ClaudeCodeHeadlessAttachment extends SdkAttachment {
+    readonly descriptor: AdapterDescriptor;
+    /** `--permission-mode` flag value. Resolved at construction; ENV fallback. */
+    protected readonly permissionMode: ClaudeCodeHeadlessPermissionMode;
+    /** Whether to use `--dangerously-skip-permissions` instead of permissionMode. */
+    protected readonly dangerouslySkipPermissions: boolean;
+    /**
+     * In-flight per-turn `claude -p` subprocess. Set by PR-3's `invokeSdk`
+     * before each turn; cleared after exit. `onSuperseded` reads this to
+     * SIGTERM the child on lease revocation.
+     */
+    protected childProcess: ChildProcess | null;
+    /**
+     * Per-cwd Claude Code session UUID. Used as `--session-id` on the first
+     * turn (to PIN the UUID) and `--resume` alone on subsequent turns
+     * (mutually exclusive per CLI v2.1.126 — see §16.9). Hydrated from
+     * `SessionMetadata.sessionId` on `run()` — generated fresh + stashed if
+     * absent. The same field is shared with the interactive Claude Code
+     * adapter (architect-ratified Option (a) post-spike — see PR-3 §16).
+     */
+    protected sessionId: string | null;
+    /** Cached for the per-turn telemetry log. Populated in `run()`. */
+    protected playerName: string;
+    constructor(opts?: ClaudeCodeHeadlessAdapterOptions);
+    /**
+     * Lease-revocation hook — fired by `SdkAttachment` when the base-class
+     * phase watcher detects another claimant stole the attachment.
+     *
+     * Two-step graceful → forced fallback per design §5.7: SIGTERM first
+     * (lets `claude` flush any in-flight stream-json frames + tear down its
+     * MCP child cleanly); SIGKILL after {@link SIGTERM_GRACE_MS} grace if it
+     * doesn't exit. Identical pattern to opencode/adapter.ts:160-173.
+     *
+     * Idempotent — racing signals (lease revoke + cleanup) are safe.
+     */
+    protected onSuperseded(): void;
+    /**
+     * Subprocess entry point. Connects Temporal, waits for the session
+     * workflow to register, hydrates the per-cwd session UUID via metadata,
+     * claims the attachment via V2 lifecycle, and drives the poll loop.
+     *
+     * Design reference: §3.6 (env hygiene), §5.1 (session continuity), §7
+     * (engineer-facing skeleton).
+     */
+    run(): Promise<void>;
+    /**
+     * Poll the workflow for pending messages, drive each one through
+     * `SdkAttachment.deliver()`. Mirrors claude-api's loop shape; the LLM
+     * call lives in `invokeSdk` (PR-3).
+     *
+     * Periodic workflow-status checks detect external termination /
+     * destroy and exit cleanly so the daemon doesn't accumulate zombie
+     * adapter processes after a `destroy` from another player.
+     */
+    private pollLoop;
+    /** True once `onTerminal` fired and cleanup tore down the V2 token. */
+    private shouldStop;
+    /**
+     * Per-turn LLM dispatch. Spawns `claude -p` with the synthesized argv
+     * + inline `--mcp-config`, streams stdout through `StreamJsonReader`,
+     * and returns the closing `result` frame's assembled text + usage.
+     *
+     * Closure-captured `messages[]` carries the multi-cue batch (PR-2 QA
+     * flag — see `pollLoop` for the closure-wrapping rationale). The
+     * representative `_prompt` arg from `SdkAttachment.deliver()` is
+     * unused; we build the prompt argv from `messages` directly.
+     *
+     * `_timeoutMs` is passed through to a Promise.race that SIGTERMs the
+     * subprocess on timeout. The base `SdkAttachment.deliver()` doesn't
+     * enforce its own timeout — we do it here.
+     *
+     * Subprocess failures (exit != 0, no result frame, or
+     * `result.is_error`) flow through the architect-ratified classifier
+     * in `./error-mapper.ts`. The classifier output is logged but the
+     * adapter does NOT call `markDelivered` on failure — the message
+     * stays PENDING so the next poll picks it up. The adapter's own
+     * retry-budget logic (PR-3 follow-up; mirrors #521's claude-api fix)
+     * tracks consecutive failures and escalates to detach when N=10
+     * `retriable-with-backoff` failures pile up.
+     */
+    protected invokeSdkWithBatch(messages: Message[], _prompt: string, timeoutMs: number): Promise<SdkDeliverResult>;
+}
+/**
+ * Encode a cwd into Claude Code's per-cwd project-dir naming scheme.
+ * Confirmed empirically in the §11.2 spike check (issue #520) — every
+ * `:`, `/`, and `\` becomes `-`. Drive prefixes like `C:\` produce a
+ * double-dash (`C--`).
+ *
+ * Pinned by `tests/adapters/claude-code-headless/cwd-encoding.test.ts`
+ * against the captured fixture so a future Claude Code minor bump that
+ * changes the scheme breaks loudly here, not silently in resume.
+ *
+ * Exported for tests only — production callers go through the on-disk
+ * sessionFile-exists check in `invokeSdkWithBatch`.
+ */
+export declare function encodeCwd(cwd: string): string;