agent-tempo 1.0.1

package/dist/adapters/claude-api/api-error.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Anthropic-API error classifier for the claude-api adapter (#521).
+ *
+ * Parallels `src/adapters/terminal-error.ts` (#249) for Temporal-side
+ * errors. Categorizes failures from `messages.create` (streaming or not)
+ * into:
+ *
+ *   - **`fatal`** — non-retriable. The adapter should detach + exit,
+ *     surfacing a clear reason in stderr so the operator can fix the
+ *     underlying problem. Examples: 400 `invalid_request_error` (bad
+ *     model id, low credits, tokens-too-large), 401 unauthorized,
+ *     403 permission denied, 404 model not found, 422 unprocessable.
+ *
+ *   - **`retriable`** — transient. The adapter should sleep
+ *     (`retryAfterMs` if the server provided one, else exponential
+ *     backoff with jitter) and retry, up to `DEFAULT_RETRY_BUDGET`
+ *     consecutive failures. After that the verdict escalates to
+ *     fatal so we don't hot-loop on a sustained outage. Examples: 408
+ *     request timeout, 429 rate limit, 5xx server errors, 529
+ *     overloaded, network / connection drops.
+ *
+ * **Why duck-typing instead of `instanceof`.** The `@anthropic-ai/sdk`
+ * is an optional dependency (#131) — importing its error classes here
+ * would couple every adapter consumer to the SDK. Status / name
+ * sniffing also tolerates minor-version drift in the SDK's class
+ * hierarchy without a rebuild. Same tradeoff `terminal-error.ts`
+ * makes for `@temporalio/client`.
+ *
+ * Acceptance criteria mapping (issue #521):
+ *   1. Classifier: `classifyApiError(err): ApiErrorVerdict`
+ *   2. Adapter consumes verdict in `adapter.ts` catch block at the
+ *      former `deliver error` line.
+ *   3. Exponential backoff: `computeBackoffMs(attempt)` — pure function,
+ *      injectable randomness for deterministic tests.
+ *   4. Retry budget: `DEFAULT_RETRY_BUDGET` (= 10 consecutive failures).
+ *   5. Detach reason surfaces: logged on stderr (operator-visible) and
+ *      the adapter detaches with `DetachReason: 'agent-exited'` so
+ *      `attachment_info` shows a non-recoverable detach.
+ */
+export type ApiErrorClassification = 'fatal' | 'retriable';
+export interface ApiErrorVerdict {
+    /** Coarse-grained verdict driving the adapter's retry decision. */
+    classification: ApiErrorClassification;
+    /** Short reason string suitable for log + operator-facing surface. */
+    reason: string;
+    /** HTTP status code if the error carried one. */
+    status?: number;
+    /**
+     * If the server requested a specific wait (`retry-after` header), this
+     * is that wait in milliseconds. Caller honors this verbatim instead of
+     * applying exponential backoff. Absent means "use computeBackoffMs".
+     */
+    retryAfterMs?: number;
+}
+/** Minimal Headers shape we read off Anthropic SDK errors. */
+interface HeadersLike {
+    get(name: string): string | null;
+}
+/** Retry budget — give up after this many consecutive retriable failures. */
+export declare const DEFAULT_RETRY_BUDGET = 10;
+/**
+ * Classify an error thrown out of `messages.create` (or surrounding
+ * helper calls inside the adapter's deliver path).
+ */
+export declare function classifyApiError(err: unknown): ApiErrorVerdict;
+/**
+ * Parse the standard HTTP `retry-after` header (seconds value, or
+ * HTTP-date). Returns ms, or `undefined` if absent / unparseable.
+ *
+ * Anthropic's API uses the integer-seconds form on 429 responses
+ * (per their docs), but we tolerate the HTTP-date form too for
+ * forward-compat with proxies that rewrite it.
+ *
+ * Exported for unit testing.
+ */
+export declare function parseRetryAfter(headers: HeadersLike | undefined): number | undefined;
+/**
+ * Compute exponential-backoff delay (ms) for the Nth retriable failure.
+ *
+ * Doubling cadence with a 30s cap + ±25% jitter so synchronized retries
+ * (e.g. a multi-player ensemble all hitting the same 5xx blip) spread
+ * across a window. Attempt is 1-indexed (1 = first retry).
+ *
+ *   attempt 1 →   750-1250 ms    (base 1000)
+ *   attempt 2 →  1500-2500 ms    (base 2000)
+ *   attempt 3 →  3000-5000 ms    (base 4000)
+ *   attempt 4 →  6000-10000 ms   (base 8000)
+ *   attempt 5 → 12000-20000 ms   (base 16000)
+ *   attempt 6+→ 22500-37500 ms   (cap 30000)
+ *
+ * Pure function with injectable randomness so tests can pin the result.
+ *
+ * Exported for unit testing.
+ */
+export declare function computeBackoffMs(attempt: number, random?: () => number): number;
+export {};

package/dist/adapters/claude-api/api-error.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Anthropic-API error classifier for the claude-api adapter (#521).
+ *
+ * Parallels `src/adapters/terminal-error.ts` (#249) for Temporal-side
+ * errors. Categorizes failures from `messages.create` (streaming or not)
+ * into:
+ *
+ *   - **`fatal`** — non-retriable. The adapter should detach + exit,
+ *     surfacing a clear reason in stderr so the operator can fix the
+ *     underlying problem. Examples: 400 `invalid_request_error` (bad
+ *     model id, low credits, tokens-too-large), 401 unauthorized,
+ *     403 permission denied, 404 model not found, 422 unprocessable.
+ *
+ *   - **`retriable`** — transient. The adapter should sleep
+ *     (`retryAfterMs` if the server provided one, else exponential
+ *     backoff with jitter) and retry, up to `DEFAULT_RETRY_BUDGET`
+ *     consecutive failures. After that the verdict escalates to
+ *     fatal so we don't hot-loop on a sustained outage. Examples: 408
+ *     request timeout, 429 rate limit, 5xx server errors, 529
+ *     overloaded, network / connection drops.
+ *
+ * **Why duck-typing instead of `instanceof`.** The `@anthropic-ai/sdk`
+ * is an optional dependency (#131) — importing its error classes here
+ * would couple every adapter consumer to the SDK. Status / name
+ * sniffing also tolerates minor-version drift in the SDK's class
+ * hierarchy without a rebuild. Same tradeoff `terminal-error.ts`
+ * makes for `@temporalio/client`.
+ *
+ * Acceptance criteria mapping (issue #521):
+ *   1. Classifier: `classifyApiError(err): ApiErrorVerdict`
+ *   2. Adapter consumes verdict in `adapter.ts` catch block at the
+ *      former `deliver error` line.
+ *   3. Exponential backoff: `computeBackoffMs(attempt)` — pure function,
+ *      injectable randomness for deterministic tests.
+ *   4. Retry budget: `DEFAULT_RETRY_BUDGET` (= 10 consecutive failures).
+ *   5. Detach reason surfaces: logged on stderr (operator-visible) and
+ *      the adapter detaches with `DetachReason: 'agent-exited'` so
+ *      `attachment_info` shows a non-recoverable detach.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY_BUDGET = void 0;
+exports.classifyApiError = classifyApiError;
+exports.parseRetryAfter = parseRetryAfter;
+exports.computeBackoffMs = computeBackoffMs;
+/** Retry budget — give up after this many consecutive retriable failures. */
+exports.DEFAULT_RETRY_BUDGET = 10;
+/**
+ * Classify an error thrown out of `messages.create` (or surrounding
+ * helper calls inside the adapter's deliver path).
+ */
+function classifyApiError(err) {
+    const e = (err ?? {});
+    const name = e.name ?? '';
+    const status = typeof e.status === 'number' ? e.status : undefined;
+    const apiType = e.type ?? e.error?.type ?? '';
+    const apiMessage = e.error?.message ?? e.message ?? '';
+    // User / lease-revoke abort path. `APIUserAbortError` (status undefined)
+    // is fired by the SDK when we call `AbortController.abort()` in
+    // `onSuperseded`. Don't retry — the next loop iteration's
+    // `shouldStop()` check will exit cleanly. We classify as `fatal` so
+    // the caller short-circuits, but the caller's `shouldStop()` guard
+    // means we won't double-fire the detach signal.
+    if (name === 'APIUserAbortError' || name === 'AbortError') {
+        return {
+            classification: 'fatal',
+            reason: 'request aborted',
+        };
+    }
+    // No status — either an SDK connection error (network drop, DNS
+    // failure, fetch threw) or a plain Error from non-SDK code (e.g.
+    // JSON.parse threw, tool dispatch threw before the SDK call). Treat
+    // as retriable so we don't wedge on a brief network blip. The retry
+    // budget will catch sustained outages.
+    if (status === undefined) {
+        return {
+            classification: 'retriable',
+            reason: `connection error: ${truncate(apiMessage || e.message || name || 'unknown')}`,
+        };
+    }
+    // 5xx → retriable. Covers 500, 502, 503, 504, 529 (overloaded).
+    if (status >= 500) {
+        return {
+            classification: 'retriable',
+            reason: `server error ${status}${apiType ? ` (${apiType})` : ''}`,
+            status,
+        };
+    }
+    // 429 rate limit → retriable, honoring `retry-after` if present.
+    if (status === 429) {
+        return {
+            classification: 'retriable',
+            reason: 'rate limited (429)',
+            status,
+            retryAfterMs: parseRetryAfter(e.headers),
+        };
+    }
+    // 408 request timeout → retriable.
+    if (status === 408) {
+        return {
+            classification: 'retriable',
+            reason: 'request timeout (408)',
+            status,
+        };
+    }
+    // Any other 4xx → fatal. Covers 400 invalid_request_error (bad
+    // model id, low credits, tokens-too-large), 401 unauthorized, 403
+    // permission denied, 404 model not found, 409 conflict, 422
+    // unprocessable. Retrying these is futile — the request itself is
+    // rejected, not the network — so we surface the failure
+    // immediately instead of burning quota.
+    if (status >= 400) {
+        const detail = apiType || truncate(apiMessage) || name || 'bad request';
+        return {
+            classification: 'fatal',
+            reason: `${status} ${detail}`,
+            status,
+        };
+    }
+    // Unrecognized 1xx/2xx/3xx with status (shouldn't happen — the SDK
+    // only throws on >=400). Be permissive: bias toward retriable so we
+    // don't wedge on an unexpected shape. The budget will still cap
+    // hot-loop failures.
+    return {
+        classification: 'retriable',
+        reason: `unrecognized error status=${status}`,
+        status,
+    };
+}
+/**
+ * Parse the standard HTTP `retry-after` header (seconds value, or
+ * HTTP-date). Returns ms, or `undefined` if absent / unparseable.
+ *
+ * Anthropic's API uses the integer-seconds form on 429 responses
+ * (per their docs), but we tolerate the HTTP-date form too for
+ * forward-compat with proxies that rewrite it.
+ *
+ * Exported for unit testing.
+ */
+function parseRetryAfter(headers) {
+    const raw = headers?.get?.('retry-after');
+    if (!raw)
+        return undefined;
+    // Numeric (seconds) — common case for Anthropic.
+    const secs = Number(raw);
+    if (Number.isFinite(secs)) {
+        if (secs <= 0)
+            return 0;
+        return Math.floor(secs * 1000);
+    }
+    // HTTP-date fallback.
+    const dateMs = Date.parse(raw);
+    if (Number.isFinite(dateMs)) {
+        const delta = dateMs - Date.now();
+        return delta <= 0 ? 0 : delta;
+    }
+    // Unparseable — let the caller fall back to exponential backoff.
+    return undefined;
+}
+/**
+ * Compute exponential-backoff delay (ms) for the Nth retriable failure.
+ *
+ * Doubling cadence with a 30s cap + ±25% jitter so synchronized retries
+ * (e.g. a multi-player ensemble all hitting the same 5xx blip) spread
+ * across a window. Attempt is 1-indexed (1 = first retry).
+ *
+ *   attempt 1 →   750-1250 ms    (base 1000)
+ *   attempt 2 →  1500-2500 ms    (base 2000)
+ *   attempt 3 →  3000-5000 ms    (base 4000)
+ *   attempt 4 →  6000-10000 ms   (base 8000)
+ *   attempt 5 → 12000-20000 ms   (base 16000)
+ *   attempt 6+→ 22500-37500 ms   (cap 30000)
+ *
+ * Pure function with injectable randomness so tests can pin the result.
+ *
+ * Exported for unit testing.
+ */
+function computeBackoffMs(attempt, random = Math.random) {
+    if (attempt <= 0)
+        return 0;
+    const BASE_MS = 1000;
+    const CAP_MS = 30_000;
+    const exp = Math.min(CAP_MS, BASE_MS * 2 ** (attempt - 1));
+    // ±25% jitter — `random()` returns [0, 1), so (random*0.5 - 0.25) gives
+    // [-0.25, +0.25).
+    const jitter = (random() * 0.5 - 0.25) * exp;
+    return Math.max(0, Math.round(exp + jitter));
+}
+function truncate(s, max = 80) {
+    return s.length > max ? s.slice(0, max) + '…' : s;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * claude-api 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 — same cycle-avoidance pattern
+ * the copilot adapter uses.
+ *
+ * Design reference: docs/design/131-claude-api-adapter.md §2 (adapter class
+ * placement) + §3.5 (optional dep gating).
+ */
+export { DirectApiAttachment, claudeApiDescriptor } from './adapter';

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

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeApiDescriptor = exports.DirectApiAttachment = void 0;
+/**
+ * claude-api 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 — same cycle-avoidance pattern
+ * the copilot adapter uses.
+ *
+ * Design reference: docs/design/131-claude-api-adapter.md §2 (adapter class
+ * placement) + §3.5 (optional dep gating).
+ */
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "DirectApiAttachment", { enumerable: true, get: function () { return adapter_1.DirectApiAttachment; } });
+Object.defineProperty(exports, "claudeApiDescriptor", { enumerable: true, get: function () { return adapter_1.claudeApiDescriptor; } });

package/dist/adapters/claude-api/mcp-bridge.d.ts

@@ -0,0 +1,50 @@
+import { Client as McpClient } from '@modelcontextprotocol/sdk/client/index.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type RegisterAllTempoToolsOpts } from '../../server-tools';
+/**
+ * Anthropic Messages API tool shape — the JSON contract `messages.create`
+ * accepts in its `tools` array. Mirrors the MCP tool shape exactly except
+ * for the field name (`inputSchema` → `input_schema`). Declared here
+ * (rather than imported from `@anthropic-ai/sdk`) so this module can ship
+ * without the optional Anthropic dep — only the adapter's spawn-time entry
+ * point requires the SDK to be installed.
+ */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: object;
+}
+/**
+ * Live in-process MCP bridge — server + client + cached tool list. Returned
+ * from {@link bootMcpBridge} and held by `DirectApiAttachment` for the
+ * duration of the session.
+ */
+export interface McpBridge {
+    /** MCP client — call `bridge.client.callTool({ name, arguments })` from the tool-use loop. */
+    client: McpClient;
+    /**
+     * Cached Anthropic-shaped tool list (translated from MCP `listTools()` once
+     * at session start). Tools don't change mid-session in v1, so the cache is
+     * safe; if a Phase 2 adds dynamic tool registration, refresh on a signal.
+     */
+    tools: AnthropicTool[];
+    /**
+     * Dispatch a tool call from the adapter's streaming loop. Returns the MCP
+     * `CallToolResult` content + isError shape, ready to slot into a
+     * Messages API `tool_result` block (`content`, `is_error`).
+     */
+    callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResult>;
+    /** Tear down both halves of the in-memory transport on shutdown. */
+    close: () => Promise<void>;
+}
+/**
+ * Boot the in-process MCP bridge for the claude-api adapter. Registers the
+ * full tempo tool surface against an `McpServer`, pairs an `McpClient` via
+ * `InMemoryTransport.createLinkedPair()`, calls `client.listTools()` once
+ * to populate the cached Anthropic-shaped tool array.
+ *
+ * @param opts Same option struct `registerAllTempoTools` consumes —
+ *             identity + workflow handle + conductor flag. The adapter
+ *             builds it from its env-var contract.
+ */
+export declare function bootMcpBridge(opts: RegisterAllTempoToolsOpts): Promise<McpBridge>;

package/dist/adapters/claude-api/mcp-bridge.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootMcpBridge = bootMcpBridge;
+/**
+ * In-process MCP bridge for the claude-api adapter.
+ *
+ * Boots an MCP `Server` (the same `McpServer` class `src/server.ts` uses),
+ * registers every tempo tool onto it via the shared `registerAllTempoTools`
+ * helper, and pairs an MCP `Client` to it via
+ * `InMemoryTransport.createLinkedPair()` — no subprocess, no stdio buffering,
+ * direct in-process JS calls under the hood.
+ *
+ * Why in-process (vs stdio sidecar):
+ *   - No second process to manage / lifecycle / clean up
+ *   - Zero stdio buffering edge cases
+ *   - ~50 LoC of glue vs 200+ for a sidecar
+ *   - MCP boundary preserved — adding a new tempo tool lights up
+ *     automatically with no adapter change
+ *
+ * The bridge owns the schema translation (MCP `inputSchema` → Anthropic
+ * Messages API `input_schema`) so the adapter's tool-use loop can hand
+ * the converted list straight to `messages.create({ tools })`.
+ *
+ * Design reference: `docs/design/131-claude-api-adapter.md` §4 (in-process
+ * MCP).
+ */
+const fs = __importStar(require("fs"));
+const path_1 = require("path");
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
+const server_tools_1 = require("../../server-tools");
+/**
+ * Resolve agent-tempo's `version` from its own `package.json`. Walks up
+ * from `__dirname` searching for a `package.json` whose `name` matches —
+ * robust across all build contexts:
+ *   - `src/adapters/claude-api/mcp-bridge.ts` (ts-node dev)
+ *   - `dist/adapters/claude-api/mcp-bridge.js` (production)
+ *   - `dist-test/src/adapters/claude-api/mcp-bridge.js` (mocha integration build)
+ *
+ * The naive `require('../../../package.json')` worked for the first two
+ * but hit ENOENT in the third because `dist-test/` adds an extra `src/`
+ * layer that shifts the relative anchor (caught by CI on PR #455).
+ *
+ * Cached after first resolve so repeated `bootMcpBridge` calls don't re-walk.
+ * Falls back to `'0.0.0-unknown'` if the walk fails — only used as a
+ * diagnostic-grade `version` field on the MCP server/client identity, not
+ * for any version-gating behaviour.
+ */
+let cachedPackageVersion = null;
+function packageVersion() {
+    if (cachedPackageVersion !== null)
+        return cachedPackageVersion;
+    let resolved = '0.0.0-unknown';
+    let dir = __dirname;
+    for (let i = 0; i < 8; i++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync((0, path_1.join)(dir, 'package.json'), 'utf8'));
+            if (pkg && pkg.name === 'agent-tempo' && typeof pkg.version === 'string') {
+                resolved = pkg.version;
+                break;
+            }
+        }
+        catch { /* not here, walk up */ }
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    cachedPackageVersion = resolved;
+    return resolved;
+}
+/**
+ * Boot the in-process MCP bridge for the claude-api adapter. Registers the
+ * full tempo tool surface against an `McpServer`, pairs an `McpClient` via
+ * `InMemoryTransport.createLinkedPair()`, calls `client.listTools()` once
+ * to populate the cached Anthropic-shaped tool array.
+ *
+ * @param opts Same option struct `registerAllTempoTools` consumes —
+ *             identity + workflow handle + conductor flag. The adapter
+ *             builds it from its env-var contract.
+ */
+async function bootMcpBridge(opts) {
+    const server = new mcp_js_1.McpServer({
+        name: 'agent-tempo',
+        version: packageVersion(),
+    });
+    (0, server_tools_1.registerAllTempoTools)(server, opts);
+    const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    const client = new index_js_1.Client({
+        name: 'claude-api-adapter',
+        version: packageVersion(),
+    });
+    await client.connect(clientTransport);
+    const { tools: mcpTools } = await client.listTools();
+    const tools = mcpTools.map((t) => ({
+        name: t.name,
+        description: t.description ?? '',
+        input_schema: t.inputSchema,
+    }));
+    return {
+        client,
+        tools,
+        callTool: async (name, args) => {
+            const result = await client.callTool({ name, arguments: args });
+            return result;
+        },
+        close: async () => {
+            // Closing the client transport drains both halves of the linked pair.
+            // McpServer/McpClient close methods are best-effort; swallow per-half
+            // errors so a partial teardown doesn't mask the original shutdown
+            // cause from upstream callers.
+            try {
+                await client.close();
+            }
+            catch { /* ignore */ }
+            try {
+                await server.close();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}

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

@@ -0,0 +1,133 @@
+/**
+ * claude-code adapter — interactive class.
+ *
+ * Owns the V2 attachment lifecycle for Claude Code CLI sessions: claims the
+ * attachment, drives the base-class heartbeat + phase-watcher loops, and runs
+ * the delivery poll against a runId-pinned handle. PR-H (#132) removed the
+ * `AGENT_TEMPO_LIFECYCLE_V2=0` escape hatch that previously gated V1 vs V2.
+ *
+ * Delivery itself (per design §5.3): push via MCP notification, ack via
+ * `markDelivered`. No `processingStart`/`End` pairs — those are for SDK
+ * adapters (`CopilotSdkAttachment`).
+ *
+ * **This file runs in the Node.js adapter process, NOT the Temporal workflow
+ * sandbox.** `setTimeout` / `setInterval` are appropriate here; the pre-bundled
+ * workflow code lives in `src/workflows/`.
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §5 (interactive),
+ * §§3.2, 4.3 (base lifecycle), §9.4 (WorkflowNotFound).
+ */
+import type { WorkflowHandle } from '@temporalio/client';
+import { BaseAttachment, type BaseAttachmentOptions } from '../base';
+import type { AdapterDescriptor, DetachReason } from '../../types';
+import { Message } from '../../types';
+/**
+ * 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.
+ */
+export declare const claudeCodeDescriptor: AdapterDescriptor;
+/**
+ * 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.
+ */
+export declare class InteractiveAttachment extends BaseAttachment {
+    readonly descriptor: AdapterDescriptor;
+    /** Current delivery poller stopper; null when no poll is running (pre-claim, mid-reconnect, post-terminal). */
+    private stopPoller;
+    /** Retained across `onReconnected` calls so the poller can be restarted on a new pinned handle. */
+    private onMessages;
+    /** True once user-initiated `stop()` has fired or the adapter reached a true terminal. */
+    private localStopped;
+    constructor(options?: BaseAttachmentOptions);
+    /**
+     * 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: WorkflowHandle, onMessages: (messages: Message[]) => Promise<void> | void): () => void;
+    /**
+     * 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.
+     */
+    private startV2;
+    /**
+     * #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.
+     */
+    protected shouldReconnect(reason: DetachReason): boolean;
+    /**
+     * 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.
+     */
+    protected onReconnectStart(_reason: DetachReason): Promise<void>;
+    /**
+     * 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.
+     */
+    protected onReconnected(handle: WorkflowHandle): Promise<void>;
+}