botmux 2.33.0 → 2.34.0

package/dist/workflows/resume.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Resume + reconcile algorithm (events doc v0.1.2 §4.3 + §4.3.1).
+ *
+ * Entry point for daemon restart / hand-off.  Walks the event log,
+ * replays a snapshot, then drives reconcile decisions for each dangling
+ * `effectAttempted` and writes terminal events for `pure skill`
+ * activities that crashed mid-flight (workerLost path).
+ *
+ * Step 7 boundaries:
+ *   - Resume DOES NOT execute activity logic; reconcile uses provider
+ *     capabilities (`readOnlyLookup` / `idempotentSubmit`) to decide
+ *     terminal state without re-issuing user-visible work beyond what
+ *     idempotency guarantees.
+ *   - Resume DOES NOT decide retry policy.  A `freshRetry` decision
+ *     leaves the attempt dangling — the scheduler (Step 8+) is
+ *     responsible for spawning the actual replacement attempt.
+ *   - Dangling waits are left alone (waiting for external signal).
+ *
+ * Round 1 fixes (codex review of `1d14081`):
+ *   F1 — replay surfaces the latest reconcileResult per attempt; resume
+ *        consumes it before re-running the decision tree, so a crash
+ *        between reconcileResult and the terminal event is recoverable.
+ *   F2 — reconcilers receive the materialized effect input via the
+ *        caller-supplied `loadEffectInput` callback.  Reconcilers that
+ *        require input (e.g. Feishu — chatId/rootMessageId/content can't
+ *        be reconstructed from idempotencyKey alone) fail explicitly
+ *        when input is unrecoverable.
+ *   F3 — `retryable` failures from idempotentSubmit do NOT terminate
+ *        the attempt; the activity stays dangling and is surfaced in
+ *        `ResumeResult.transientFailures` for the caller to retry.
+ *   F4 — `resumeStarted` is written ONLY after a preflight validates
+ *        the log is replayable; bad inputs throw without polluting the
+ *        run event log.
+ */
+import type { EventLog } from './events/append.js';
+import { type Snapshot, type AttemptState } from './events/replay.js';
+import type { ActivityCanceledEvent, ActivityFailedEvent, ActivitySucceededEvent, ReconcileResultEvent, ResumeStartedEvent } from './events/types.js';
+export type ReconcileCapability = 'readOnlyLookup' | 'idempotentSubmit' | 'none';
+export type ReconcileDecision = 'replayed' | 'completedByIdempotentSubmit' | 'manual' | 'freshRetry';
+export type ReadOnlyLookupResult = {
+    found: true;
+    externalRefs: Record<string, unknown>;
+    evidence?: Record<string, unknown>;
+} | {
+    found: false;
+    evidence?: Record<string, unknown>;
+};
+export type IdempotentSubmitResult = {
+    ok: true;
+    externalRefs: Record<string, unknown>;
+    evidence?: Record<string, unknown>;
+} | {
+    ok: false;
+    errorCode: string;
+    errorClass: 'retryable' | 'fatal' | 'userFault' | 'manual';
+    errorMessage: string;
+    evidence?: Record<string, unknown>;
+};
+/**
+ * Per-provider capability bundle.  Resume looks up the reconciler by the
+ * `effectAttempted.provider` field; missing entries fall through to
+ * manual/UnknownProviderError.
+ *
+ * Reconcilers receive the materialized effect input alongside the
+ * idempotencyKey: providers like Feishu can't re-construct the request
+ * body from the key alone (the key is a hash, not the body).  When the
+ * caller doesn't supply `loadEffectInput`, resume treats the input as
+ * `undefined`; reconcilers that NEED input MUST declare so via
+ * `requiresEffectInput` so resume can fail fast with a clear error
+ * instead of letting the reconciler silently misbehave.
+ */
+export interface ProviderReconciler {
+    readonly provider: string;
+    /**
+     * When `true`, resume refuses to call this reconciler without a
+     * materialized effect input — i.e. it writes manual/InputUnrecoverable
+     * if `loadEffectInput` is absent or throws.  Feishu sets this; schedule
+     * does not (idempotencyKey is the full key).
+     */
+    readonly requiresEffectInput?: boolean;
+    /**
+     * Pure read against the provider keyed by `idempotencyKey`.  Has no
+     * side effects; safe to call from resume even when we don't intend to
+     * complete the effect.  Schedule has it (`getTask(id)`); Feishu does
+     * not (no uuid-reverse-lookup API).
+     */
+    readOnlyLookup?(idempotencyKey: string, input: unknown): Promise<ReadOnlyLookupResult>;
+    /**
+     * Re-submit the effect with the same `idempotencyKey`.  MAY produce
+     * the side effect for real (if the original pre-invoke crash never
+     * reached the provider); provider dedupe inside TTL guarantees the
+     * second submit returns the original ref instead of a duplicate.
+     */
+    idempotentSubmit?(idempotencyKey: string, input: unknown): Promise<IdempotentSubmitResult>;
+    /**
+     * Canonical form of the loaded effect input — used at resume time to
+     * recompute `inputHash` and compare against `effectAttempted.inputHash`.
+     * MUST mirror the executor's `canonicalInput` exactly; mismatched
+     * canonicalization across resume/dispatch silently breaks idempotency.
+     *
+     * Reconcilers with `requiresEffectInput=true` SHOULD implement this;
+     * resume writes `IdempotencyInputMismatch/manual` if a tampered or
+     * drifted sidecar would otherwise reach the provider with a different
+     * body than the original attempt promised.
+     */
+    canonicalInput?(input: unknown): unknown;
+}
+export type ResumeContext = {
+    /** Authoritative event log for this run.  Resume writes events into it. */
+    log: EventLog;
+    /** Match `log.runId`; passed explicitly so the contract is visible. */
+    runId: string;
+    /** Daemon identifier for the resumeStarted audit event. */
+    daemonId: string;
+    /** Reconcilers keyed by provider name (`feishu-im`, `botmux-schedule`). */
+    reconcilers: Map<string, ProviderReconciler>;
+    /**
+     * Load the materialized effect input that was passed to the original
+     * attempt.  Required for providers that re-submit (Feishu).  Resume
+     * passes the returned value to the reconciler's readOnlyLookup /
+     * idempotentSubmit.
+     *
+     * v0: the caller (daemon) decides where to persist or recover this —
+     * in-memory while alive, or some external storage on cold start.
+     * Resume only consumes the callback.
+     *
+     * Returning `undefined` is treated as "input unrecoverable" and
+     * triggers the manual/InputUnrecoverable path for reconcilers that
+     * declared `requiresEffectInput`.
+     */
+    loadEffectInput?(activityId: string, attemptId: string): Promise<unknown>;
+    /** Injectable clock for deterministic tests.  Defaults to Date.now. */
+    now?: () => number;
+};
+export type ReconcileOutcome = {
+    activityId: string;
+    attemptId: string;
+    idempotencyKey: string;
+    provider: string;
+    capability: ReconcileCapability;
+    decision: ReconcileDecision;
+    evidence: Record<string, unknown>;
+    /**
+     * Terminal event written as a consequence.  null for `replayed` (the
+     * pre-existing terminal IS the consequence) and `freshRetry` (scheduler
+     * issues a new attempt later, not Step 7's job).
+     */
+    terminalEvent: ActivitySucceededEvent | ActivityFailedEvent | null;
+    /** The reconcileResult event written, or null if this outcome reused
+     *  a pre-existing reconcileResult (recovery path — codex F1). */
+    reconcileEvent: ReconcileResultEvent | null;
+    /** True when this outcome recovered a prior crashed reconcile cycle
+     *  rather than running the decision tree from scratch. */
+    recovered: boolean;
+};
+export type WorkerCrashedOutcome = {
+    activityId: string;
+    attemptId: string;
+    terminalEvent: ActivityFailedEvent;
+};
+/**
+ * Recovery of a wait whose resolution event landed but whose activity
+ * terminal was never written (crash between `waitResolved` /
+ * `waitDeadlineExceeded` and the terminal).  Step 8: replay surfaces
+ * these as `Snapshot.danglingWaitResolutions`; resume materializes the
+ * terminal from the recorded resolution.
+ */
+export type WaitRecoveryOutcome = {
+    activityId: string;
+    attemptId: string;
+    /** What the recovery decided to write. */
+    kind: 'succeeded' | 'failed';
+    source: 'resolved' | 'deadlineExceeded';
+    terminalEvent: ActivitySucceededEvent | ActivityFailedEvent;
+};
+/**
+ * Recovery of a cancel whose request landed but whose activity
+ * terminal was never written (crash between `cancelRequested` /
+ * `cancelDelivered` and the terminal).  Step 9: replay surfaces these
+ * as `Snapshot.danglingCancels`.
+ *
+ * The terminal resume writes depends on whether the cancelled
+ * attempt also had a dangling `effectAttempted` (Step 9 round 1
+ * finding 1):
+ *
+ *   - **No effectAttempted** (plain cancel): resume writes
+ *     `activityCanceled` directly, with `cancelOriginEventId`
+ *     pointing at the originating `cancelRequested`.
+ *   - **effectAttempted present** (cancel + effect): resume FIRST
+ *     runs reconcile to capture provider evidence (writes
+ *     `reconcileResult` with cancel-coupled keys — see
+ *     payloads.ts `ReconcileResultPayload` doc), THEN decides:
+ *       - `completedByIdempotentSubmit` / `freshRetry` →
+ *         `activityCanceled` (cancel wins as terminal reason; the
+ *         provider's outcome is preserved in reconcileResult evidence)
+ *       - `manual` (TTL expired / unknown provider / submit errored
+ *         fatally) → `activityFailed{manual}` — we deliberately do
+ *         NOT write `activityCanceled` because provider state is
+ *         unknown and pretending the cancel cleanly succeeded would
+ *         lie to forensics
+ *       - `transient` → NO terminal; the activity stays dangling and
+ *         the next resume cycle retries (surfaces as a
+ *         `TransientReconcileFailure` on `ResumeResult.transientFailures`)
+ */
+export type CancelRecoveryOutcome = {
+    activityId: string;
+    attemptId: string;
+    cancelOriginEventId: string;
+    /** True if cancelDelivered was already written; false means we
+     *  short-circuited a never-delivered cancel.  Both still terminate
+     *  the activity (cancel intent is authoritative). */
+    delivered: boolean;
+    /**
+     * What terminal we ended up writing.  `cancelled` is the regular
+     * cancel terminal; `failed` is the "manual escalation" path when
+     * reconcile evidence is non-conclusive (Step 9 finding 1).
+     */
+    kind: 'cancelled' | 'failed';
+    /** Present when reconcile ran alongside cancel — i.e. the activity
+     *  had a dangling effectAttempted.  Pure cancels (no effect) leave
+     *  this undefined. */
+    reconcileEvent?: ReconcileResultEvent;
+    /**
+     * The reconcile decision that informed the cancel terminal (only
+     * populated when the activity had a dangling effectAttempted).
+     * - For `completedByIdempotentSubmit` and `freshRetry`, terminal is
+     *   `activityCanceled`.
+     * - For `manual`, terminal is `activityFailed{manual}`.
+     */
+    reconcileDecision?: ReconcileDecision;
+    terminalEvent: ActivityCanceledEvent | ActivityFailedEvent;
+};
+/**
+ * Reconcile failures that resume DELIBERATELY does not terminate (codex
+ * F3): a retryable provider failure during idempotentSubmit might mean
+ * "request landed, response lost", and writing a manual terminal there
+ * would freeze the activity in a wrong terminal state.  Resume reports
+ * these back to the caller and leaves the activity dangling so the next
+ * resume cycle can retry.
+ */
+export type TransientReconcileFailure = {
+    activityId: string;
+    attemptId: string;
+    provider: string;
+    idempotencyKey: string;
+    errorCode: string;
+    errorClass: 'retryable';
+    errorMessage: string;
+};
+export type ResumeResult = {
+    resumeStartedEvent: ResumeStartedEvent;
+    /** Snapshot captured after `resumeStarted` is appended.  Returned for
+     *  observability — caller can inspect dangling sets it consumed. */
+    snapshot: Snapshot;
+    reconcileOutcomes: ReconcileOutcome[];
+    workerCrashedOutcomes: WorkerCrashedOutcome[];
+    transientFailures: TransientReconcileFailure[];
+    waitRecoveryOutcomes: WaitRecoveryOutcome[];
+    cancelRecoveryOutcomes: CancelRecoveryOutcome[];
+};
+export declare function resume(ctx: ResumeContext): Promise<ResumeResult>;
+export type { AttemptState };
+//# sourceMappingURL=resume.d.ts.map

package/dist/workflows/resume.d.ts.map

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