agent-tempo 1.0.1

package/dist/adapters/base.d.ts

@@ -0,0 +1,426 @@
+/**
+ * Base adapter infrastructure.
+ *
+ * Owns the V2 attachment lifecycle — `claimAttachment`, heartbeat loop,
+ * `attachmentInfo` phase watcher, `WorkflowNotFound` terminal handling, and
+ * graceful-detach orchestration. PR-H (#132) removed the
+ * `AGENT_TEMPO_LIFECYCLE_V2=0` escape hatch and its PR-A compat shim path;
+ * V2 is now the only path.
+ *
+ * The `SdkAttachment` intermediate class (processing-signal pairing, split-brain
+ * cancellation per §9.3) lives in `src/adapters/sdk/base.ts`.
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §§3.2, 4.3, 9.1–9.5.
+ */
+import type { Client, WorkflowHandle } from '@temporalio/client';
+import type { AdapterClass, AdapterDescriptor, AttachmentToken, AttachmentPhase, DetachReason } from '../types';
+/** Snapshot of adapter state included in every telemetry frame. */
+interface AdapterTelemetrySnapshot {
+    attachmentId: string | null;
+    workflowId: string | null;
+    runId: string | null;
+    heartbeatsSent: number;
+    phaseTicksDone: number;
+}
+/**
+ * Build the structured frame emitted by every lifecycle handler. Pure
+ * function — exposed for unit tests that don't want to spawn a child
+ * process.
+ */
+export declare function buildProcessTerminatingFrame(signal: string, errorMessage?: string, snapshot?: AdapterTelemetrySnapshot[]): string;
+/**
+ * Install the process-lifecycle telemetry handlers. Idempotent. Skipped
+ * by default in test environments (see {@link shouldInstallLifecycleTelemetry}).
+ *
+ * Production callers (and the first `startV2Lifecycle()` call on any
+ * adapter) invoke without arguments. Unit tests pass `{ force: true }`
+ * to bypass the env gate.
+ */
+export declare function installProcessLifecycleTelemetry(opts?: {
+    force?: boolean;
+}): void;
+/** Test-only — uninstall handlers + reset state. */
+export declare function _resetProcessLifecycleTelemetryForTest(): void;
+/** Test-only — direct access to the live-adapter set. */
+export declare function _liveAdaptersForTest(): ReadonlySet<BaseAttachment>;
+/**
+ * Override bundle for the reconnect loop timing (#201). Production defaults are
+ * tuned for laptop-sleep cycles (15-min elapsed budget, 10s base, 60s cap). Tests
+ * override to run the whole loop in <1s. Any field omitted falls back to the
+ * production constant.
+ */
+export interface ReconnectTimingOverrides {
+    baseMs?: number;
+    maxMs?: number;
+    budgetMs?: number;
+    backoffFactor?: number;
+}
+/** Options shared by every adapter extending `BaseAttachment`. */
+export interface BaseAttachmentOptions {
+    /** Temporal client — required for V2 attachment claim + runId pinning. */
+    client?: Client;
+    /** Hostname to announce in `claimAttachment`. Defaults to `os.hostname()` when omitted. */
+    host?: string;
+    /** Test-only: shrink the reconnect backoff/budget. Production callers never set this. */
+    reconnectTiming?: ReconnectTimingOverrides;
+}
+/**
+ * Abstract base class for session adapters.
+ *
+ * Concrete adapters (`InteractiveAttachment`, `CopilotSdkAttachment`) own
+ * their own top-level delivery loop. The base class owns the V2 attachment
+ * lifecycle: claim, heartbeat at `descriptor.heartbeatMs`, phase-watcher
+ * loop, `WorkflowGone` classifier, graceful `adapterExited` on teardown.
+ * Subclasses must call `startV2Lifecycle()` before their delivery loop and
+ * `stopV2Lifecycle()` on shutdown.
+ *
+ * PR-H (#132): the `AGENT_TEMPO_LIFECYCLE_V2` flag and the legacy V1 poll-
+ * only path it gated have been removed. The V2 attachment-lease path is
+ * now the only path.
+ */
+export declare abstract class BaseAttachment {
+    abstract readonly descriptor: AdapterDescriptor;
+    /** Populated at construction for InteractiveAttachment; lazily via `configureV2()` for subprocess adapters (Copilot bridge). */
+    protected client?: Client;
+    protected host?: string;
+    /** V2 state — populated by `startV2Lifecycle()`, null on legacy path. */
+    protected token: AttachmentToken | null;
+    /** Handle pinned to the runId returned by `claimAttachment`. Never resolve by ID alone (§6.3). */
+    protected pinnedHandle: WorkflowHandle | null;
+    private heartbeatTimer;
+    private phaseWatcherTimer;
+    private heartbeatBackoff;
+    private phaseBackoff;
+    private stopped;
+    private terminalFired;
+    private knownPhase;
+    /**
+     * `true` once a heartbeat has successfully landed on the current attachment (or rebind).
+     * Cleared on `startV2Lifecycle`, reconnect-loop success, and CAN rebind so each freshly
+     * live attachment emits its own `heartbeat#1 delivered` diagnostic. Added in #249 to
+     * distinguish "claim OK but heartbeat loop died" from "adapter just hasn't ticked yet."
+     */
+    private firstHeartbeatLogged;
+    /**
+     * Monotonic heartbeat counter for the current attachment cycle. Reset on
+     * claim/reconnect/CAN-rebind. Emitted periodically (every {@link LOOP_SUMMARY_EVERY}
+     * ticks) so a long-running session leaves breadcrumbs in the log proving the loop is
+     * alive — operators can `grep 'heartbeats-delivered='` to confirm health without
+     * parsing Temporal history. Added in #249.
+     */
+    private heartbeatsSent;
+    /**
+     * Mirror of {@link heartbeatsSent} for the phase-watcher loop. Same emission cadence,
+     * same rationale — the watcher is the only self-heal surface when the heartbeat loop
+     * dies silently, so a summary log line proves it's still live too.
+     */
+    private phaseTicksDone;
+    private readonly phaseChangeListeners;
+    private readonly leaseRevokedListeners;
+    private readonly terminalListeners;
+    /**
+     * Pending `abortableSleep` cancellers (#201). `stopV2Lifecycle` iterates and invokes
+     * each so any in-flight reconnect backoff rejects immediately and the loop unwinds
+     * instead of stalling teardown by up to `RECONNECT_MAX_MS`.
+     */
+    private readonly sleepAborters;
+    /**
+     * `true` while `runReconnectLoop` is active. Prevents concurrent reconnect attempts
+     * (e.g. if both the heartbeat and phase-watcher loops observe the same lease expiry
+     * at nearly the same time) and gates heartbeat/watcher ticks from firing new terminals
+     * while the reconnect pre-check is still deciding.
+     */
+    private reconnecting;
+    /** Reconnect loop timing — production constants unless overridden for tests. */
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private readonly reconnectBudgetMs;
+    private readonly reconnectBackoffFactor;
+    constructor(options?: BaseAttachmentOptions);
+    /**
+     * Lazily populate the V2-path dependencies (Temporal client, host). Used by
+     * adapters whose subprocess constructs the client inside `run()` rather
+     * than receiving it from the outer process (Copilot bridge). Must be called
+     * BEFORE `startV2Lifecycle()`.
+     *
+     * C3 (PR-C dual-QA follow-up): rejects late reconfiguration — once a claim
+     * token has been issued, swapping the client out silently would leave the
+     * pinned handle pointing at the previous connection. Future adapters that
+     * mis-order the calls fail loudly instead of drifting.
+     */
+    protected configureV2(client: Client, host: string): void;
+    /** Subscribe to `attachmentInfo.phase` changes observed by the watcher. */
+    onPhaseChange(listener: (phase: AttachmentPhase) => void): () => void;
+    /** Subscribe to lease-revocation events (§9.3 split-brain resolution). */
+    onLeaseRevoked(listener: (reason: DetachReason) => void): () => void;
+    /**
+     * Hypothesis A telemetry — capture the adapter state included in
+     * process-lifecycle log frames. Public so the module-level
+     * `snapshotLiveAdapters()` helper can read private fields without an
+     * `any` cast; consumers other than the telemetry path should not call it.
+     */
+    _captureTelemetrySnapshot(): AdapterTelemetrySnapshot;
+    /**
+     * Subscribe to terminal events — `WorkflowNotFound` (§9.4) and phase `gone`.
+     * Terminal fires at most once per instance. Subclasses stop delivery + exit.
+     */
+    onTerminal(listener: (reason: DetachReason) => void): () => void;
+    /**
+     * V2 lifecycle entry point. Claims (or renews) the attachment, pins the handle by runId,
+     * and starts the heartbeat + phase watcher loops.
+     *
+     * @param workflowId  Target session workflow id.
+     * @param expectedAttachmentId
+     *   PR-D renewal path. When present, the adapter was spawned by `restart` or `migrate`
+     *   — the workflow has already created an `Attachment` with this id and is
+     *   expecting the new adapter to take over. Passing it through to `claimAttachment`
+     *   selects the renewal branch in §9.2 (refresh lease in place, idempotent on retry)
+     *   instead of the fresh-claim branch. Fresh spawn (first recruit) omits this arg.
+     * @returns Pinned `WorkflowHandle` — subclass delivery loop MUST use this for every
+     *          subsequent query/signal (never resolve by id alone).
+     * @throws  Re-throws `claimAttachment` rejections (`AttachmentConflict`, `WorkflowGone`).
+     */
+    protected startV2Lifecycle(workflowId: string, expectedAttachmentId?: string): Promise<WorkflowHandle>;
+    /**
+     * Tear down V2 machinery. Idempotent. Called by subclass on stop, on terminal
+     * events, and on graceful detach completion.
+     *
+     * When `graceful=true` (detach owner) we fire `adapterExited` so the workflow
+     * collapses `draining → detached` immediately per §11.1.
+     */
+    protected stopV2Lifecycle(reason?: DetachReason, graceful?: boolean): Promise<void>;
+    private scheduleHeartbeat;
+    /**
+     * Emit a loud diagnostic when a tick early-returns via one of its guard paths (#249).
+     * Pre-#249 these returns were silent — the only observable effect was "heartbeats stop
+     * arriving." Now operators can grep `adapter.*guard tripped` to confirm or rule out
+     * tick-orphan as a failure mode without needing workflow history.
+     *
+     * `terminalFired=true` / `stopped=true` guards are load-bearing on the terminal path
+     * (don't want to re-enter terminal) so they're expected during teardown; we still log
+     * them but at the same level — operators can correlate timestamps against the preceding
+     * `terminal (...) — stopping delivery poll permanently` line.
+     */
+    private logGuardTrip;
+    /**
+     * Single tick of the heartbeat loop. Try/finally scaffolding (#249) guarantees
+     * reschedule in every path except genuinely terminal state (`stopped`,
+     * `terminalFired`) or when the reconnect loop has taken ownership of scheduling
+     * (`reconnecting`). Pre-#249 the three early-return paths at the top + the
+     * handled-terminal-error path silently orphaned the timer forever; a transient
+     * `reconnecting=true` window or a null-handle race was enough to kill the loop
+     * with no log and no teardown.
+     *
+     * Handled terminals (CAN rebind, destroy) still short-circuit via `return` —
+     * the `finally` block re-checks `reconnecting` / `terminalFired` before
+     * rescheduling, so the reconnect/terminal machinery keeps ownership of
+     * whatever comes next.
+     */
+    private tickHeartbeat;
+    private schedulePhaseWatcher;
+    /**
+     * Single tick of the phase-watcher loop. Same orphan-resistance scaffolding as
+     * {@link tickHeartbeat} (#249): try/finally reschedule, unconditional unless
+     * `stopped` / `terminalFired` / `reconnecting`. When the heartbeat loop dies
+     * silently, the watcher is the only remaining self-heal surface — losing it
+     * too meant the adapter had no path back to a healthy state short of process
+     * restart.
+     */
+    private tickPhaseWatcher;
+    /**
+     * Shared error-classification path for the heartbeat + phase-watcher ticks (#226).
+     *
+     * Returns `true` if the error was a terminal-class (handled inline: CAN rebind
+     * kicked off, or destroy fired). Returns `false` when the caller should treat
+     * the error as transient and continue its backoff.
+     *
+     * Always consults `fetchHistory` on any terminal-class error, because the
+     * Temporal SDK can't distinguish CAN-close from true-complete at the error
+     * level — see {@link isTerminalWorkflowError}. The history lookup is cheap
+     * (only runs on terminal, so at most once per adapter lifetime per terminal)
+     * and safer than re-querying by workflow id (which could race a fresh session
+     * reusing the id).
+     */
+    private handleRunEndError;
+    /**
+     * Fetch the closed pinned run's history and return the runId of a CAN successor
+     * if present, else `null`. Scoped to the pinned (old) run via `this.pinnedHandle`,
+     * so it can't be fooled by a fresh session that happens to reuse the workflow id.
+     *
+     * Called only on the terminal path from {@link handleRunEndError}, so the cost
+     * of `fetchHistory` (a full event stream for the closed run) is paid at most
+     * once per terminal — not on every tick.
+     */
+    private findCanSuccessorRunId;
+    /**
+     * Fire the terminal hook — the adapter is going dark and won't recover.
+     *
+     * #258: emits a structured log line on every fire so the next post-CAN
+     * silence incident is unambiguous in logs. Pre-#258, a `fireTerminal`
+     * from an unexpected source (the root cause was a silent destroy from
+     * the reconnect-loop pre-check on a transient terminal-class error) was
+     * indistinguishable from process death in workflow history — both produced
+     * "no further heartbeats." The structured log includes:
+     *
+     *   - `reason` — the existing DetachReason
+     *   - `callsite` — the calling function or rationale (passed by every
+     *     callsite so the source is grep-able without parsing stack traces)
+     *   - `attachmentId` / `workflowId` / `runId` — for cross-referencing
+     *     against workflow history when bisecting an incident
+     *   - `heartbeatsSent` / `phaseTicksDone` — the existing #249 counters
+     *     so an operator can correlate "loop alive at N heartbeats, then
+     *     terminal fired at this callsite" without external context
+     *
+     * Idempotent — repeat calls (e.g. reconnect-exhausted re-fires after
+     * destroy) early-return without re-logging. The first fire wins.
+     */
+    private fireTerminal;
+    /**
+     * #258 tiebreaker: confirm whether a workflow is genuinely terminal after
+     * the reconnect-loop pre-check threw a terminal-class error. Used to
+     * distinguish a real workflow-gone state from a transient gRPC /
+     * visibility-API blip that classified as terminal.
+     *
+     * Returns:
+     *  - `{ kind: 'running', statusName }` — workflow is alive (any
+     *    non-terminal status). Caller should treat the original error as
+     *    transient and continue the reconnect loop.
+     *  - `{ kind: 'terminal', statusName }` — workflow is in a terminal
+     *    status (`COMPLETED` / `FAILED` / `CANCELLED` / `TERMINATED` /
+     *    `CONTINUED_AS_NEW` / `TIMED_OUT`). Caller should fire destroy.
+     *  - `{ kind: 'describe-threw' }` — `describe()` itself failed. Treat
+     *    as terminal (fire destroy) — consistent with pre-#258 semantics
+     *    when classification is ambiguous, and avoids spinning forever on
+     *    a workflow we can't reach.
+     *  - `{ kind: 'timed-out' }` — `describe()` exceeded
+     *    {@link DESCRIBE_TIMEOUT_MS}. Treat as terminal (fire destroy) —
+     *    same rationale: prefer clean shutdown to a hung loop.
+     *
+     * The unpinned handle follows any CAN chain to the latest run, so
+     * `desc.status.name === 'CONTINUED_AS_NEW'` here means the workflow
+     * id itself is closed (no successor) — genuinely terminal.
+     */
+    private confirmWorkflowTerminal;
+    /**
+     * Opt-in reconnect policy. Default: return `false` — the base class behaves
+     * exactly as it did before #201 (fire terminal, tear down). Subclasses that
+     * can safely replay delivery on a fresh lease should override and return
+     * `true` for recoverable reasons (typically `heartbeat-timeout` and
+     * `superseded`; never `destroy`).
+     *
+     * Why opt-in: SDK adapters (e.g. Copilot bridge) have their own subprocess
+     * restart logic; double-reconnecting would race their native poller and
+     * produce duplicate `pendingMessages` queries. Keep them on the old
+     * behavior until we've proven reconnect is safe there.
+     */
+    protected shouldReconnect(_reason: DetachReason): boolean;
+    /**
+     * Called once, just before the reconnect loop enters its first backoff sleep.
+     * Subclasses should tear down any delivery loops that are still polling the
+     * stale pinned handle (it may succeed but `markDelivered` will be ignored by
+     * the workflow because our `attachmentId` is no longer current). The default
+     * is a no-op.
+     */
+    protected onReconnectStart(_reason: DetachReason): Promise<void>;
+    /**
+     * Called once on a successful re-claim, with the freshly pinned handle.
+     * Subclasses should restart their delivery loop against `handle`. Runs
+     * before the base class reschedules its own heartbeat + phase-watcher
+     * loops, so the subclass sees a quiescent state.
+     *
+     * Note: the runId returned by `claimAttachment` may differ from the previous
+     * pinned handle's runId (the workflow may have `continueAsNew`'d during the
+     * outage), so subclasses MUST use the `handle` argument — never cache a
+     * handle from before the reconnect.
+     */
+    protected onReconnected(_handle: WorkflowHandle): Promise<void>;
+    /**
+     * Sleep `ms` milliseconds, resolving cleanly on timer and rejecting with
+     * `aborted:stopped` if `stopV2Lifecycle` or `fireTerminal` fires mid-wait.
+     * The canonical pattern for any blocking wait inside an adapter loop —
+     * never use bare `setTimeout` + `Promise` in loop code, or teardown stalls.
+     */
+    protected abortableSleep(ms: number): Promise<void>;
+    /** Reject every in-flight `abortableSleep`. Called on stop + terminal. */
+    private abortSleepers;
+    /**
+     * Consult {@link shouldReconnect}; if true, kick off the reconnect loop in
+     * the background (fire-and-forget), otherwise fire terminal synchronously.
+     * Called by the heartbeat / phase-watcher ticks instead of `fireTerminal`
+     * when the reason is potentially recoverable.
+     */
+    private fireTerminalOrReconnect;
+    /**
+     * #226 CAN rebind. Transparently repoints `pinnedHandle` at the successor run,
+     * keeps the existing `attachmentId` / `leaseMs` (the workflow extended the lease
+     * by one heartbeat interval during the CAN transition per §2.3, so the lease is
+     * still live on the new run), notifies the subclass to restart its delivery
+     * loop, and resumes heartbeat + phase-watcher.
+     *
+     * Why this is safe without re-claiming:
+     *  - The new run carries forward `currentAttachment` verbatim from the old run.
+     *  - The adapter's `attachmentId` still matches, so the next `heartbeat` /
+     *    `markDelivered` / `adapterExited` signal on the new pinned handle will be
+     *    accepted unchanged by the workflow's handlers.
+     *  - If the lease actually did expire before we got here (e.g. adapter was
+     *    offline through multiple CAN cycles), the next phase-watcher tick on the
+     *    new pinned handle will see `phase=detached` + no current attachment and
+     *    fall through to the existing #201 reclaim path — belt-and-suspenders.
+     */
+    private runCanRebind;
+    /**
+     * Budget-bounded reconnect loop.
+     *
+     * Strategy:
+     *   1. Sleep (abortable) with exponential backoff from {@link RECONNECT_BASE_MS}
+     *      up to {@link RECONNECT_MAX_MS}, capped by an elapsed-time budget of
+     *      {@link RECONNECT_TOTAL_BUDGET_MS}.
+     *   2. Query `attachmentInfo` via a fresh unpinned handle:
+     *        • workflow gone → fire `destroy`, exit.
+     *        • phase `gone` → fire `destroy`, exit.
+     *        • someone else holds the lease → fire `superseded`, exit (architect §1).
+     *        • phase `draining` → wait another tick (lease about to reap).
+     *        • otherwise → attempt fresh `claimAttachment`.
+     *   3. On successful claim: rebuild `this.pinnedHandle` from the **new** token's
+     *      `runId` (workflow may have `continueAsNew`'d during outage), reset loop
+     *      state, call subclass hooks, restart heartbeat + watcher.
+     *
+     * Fires `reconnect-exhausted` on budget exhaustion. Exits silently (without
+     * firing terminal) on abort — `stopV2Lifecycle` owns teardown messaging.
+     */
+    private runReconnectLoop;
+}
+/**
+ * Registry of adapter descriptors keyed by `adapterId`.
+ *
+ * Look up the descriptor for a given session by `SessionMetadata.adapterId` (or
+ * fall back to `'claude-code'` for pre-v0.25 sessions that have no adapterId set).
+ * `src/adapters/index.ts` creates the singleton `registry` and registers all
+ * shipped adapters at import time.
+ */
+export declare class AdapterRegistry {
+    private readonly byId;
+    /** Register an adapter descriptor. Replaces any existing entry with the same id. */
+    register(desc: AdapterDescriptor): void;
+    /**
+     * Fetch the descriptor for `adapterId`. Throws if unregistered.
+     *
+     * Callers resolving from possibly-undefined metadata should coalesce first:
+     * `registry.get(metadata.adapterId ?? 'claude-code')`.
+     */
+    get(adapterId: string): AdapterDescriptor;
+    /** `true` if `adapterId` is registered. */
+    has(adapterId: string): boolean;
+    /** Snapshot of all registered descriptors. */
+    all(): readonly AdapterDescriptor[];
+    /**
+     * Resolve an `adapterId` from the legacy `agent` field on {@link SessionMetadata}.
+     * Maps `'claude'` → `'claude-code'`, `'copilot'` → `'copilot'`.
+     *
+     * Used as a fallback when `adapterId` is not yet populated on the session metadata
+     * (e.g. sessions started before PR-B landed). PR-D removes this mapping when the
+     * legacy `AgentType` enum is retired.
+     */
+    resolveFromAgentType(agent: string | undefined): string;
+}
+export type { AdapterClass, AdapterDescriptor };