@parall/agent-core 1.45.0 → 1.46.0

package/dist/session-lifecycle.js

@@ -0,0 +1,446 @@
+/**
+ * SessionLifecycleCoordinator — the single entry point for session status
+ * writes (active / idle / closed).
+ *
+ * SCOPE — this is a **process-local mitigation**, not a distributed fence.
+ * It serializes and orders the lifecycle writes THIS process issues. It does
+ * NOT order across processes, and it cannot fix a write that times out
+ * client-side but lands server-side later, nor an old turn's step retry
+ * landing during a new turn. The structural fix is a server-side turn fence
+ * (design tracked in #1879 — durable step outbox + turn fence); until that
+ * ships, this closes the in-process interleavings that produced the
+ * 2026-07-13 repro.
+ *
+ * The gateway used to fire active and idle PATCHes independently
+ * (fire-and-forget + detached retries). Two independent HTTP requests have
+ * no ordering: turn 1's in-flight idle could land AFTER turn 2's active and
+ * demote a running session — an epoch check on retry TIMERS cannot cancel a
+ * request already on the wire. The coordinator closes that class by being a
+ * serialized desired-state reconciler:
+ *
+ * - Per session it stores only the LATEST desired state plus a monotonic
+ *   generation (bumped by beginTurn and closeSession).
+ * - At most ONE lifecycle write is in flight per session; when it settles
+ *   the loop re-reads the latest desired state and reconciles — so a
+ *   begin(turn N+1), or a closeSession, that arrives while an earlier write
+ *   is in flight simply waits for it to settle and is written AFTER it.
+ * - finishTurn carries the TurnHandle from its beginTurn; a stale handle
+ *   (generation superseded) is ignored outright.
+ * - Retries re-run the reconcile loop against the LATEST desired state —
+ *   they never replay a captured command, so a pending idle retry is
+ *   naturally superseded by a new turn.
+ * - Errors are CLASSIFIED (ports, defaults are conservative): transient →
+ *   bounded backoff; permanent (4xx) → warn + abandon that desired state (a
+ *   later turn retries with a fresh generation); session-stale (the server
+ *   considers the session terminal) → drop the session, never write again.
+ * - beginTurn / closeSession resolve once one write attempt covering their
+ *   generation has SETTLED (success or failure — bounded by the write's own
+ *   timeout, plus at most one in-flight predecessor). The gateway awaits
+ *   beginTurn before persisting the turn's first AgentStep, so a reused idle
+ *   session is reconciled to active before steps arrive and the server's
+ *   presence guard cannot swallow the turn's activity. A failed active write
+ *   warns and lets the step flow continue.
+ * - closeSession's first settle carries a STRUCTURED outcome (`closed` /
+ *   `stale` / `retrying` / `permanent_failure` / `disposed`) plus a
+ *   `terminal` promise that resolves when the close reaches a terminal fate
+ *   — a caller holding cleanup behind the close (ForkSessionFinalizer) can
+ *   keep ownership through `retrying` instead of mistaking "one attempt
+ *   settled" for "close completed".
+ * - Entries are RECLAIMED (no unbounded Map growth on long-lived daemons):
+ *   dropSession removes the entry immediately when idle, or at the end of an
+ *   in-flight write; a `closed` that landed OR failed permanently reclaims
+ *   too — the permanent failure is not hidden by the reclaim, it is reported
+ *   through the close's outcome/terminal before the entry goes away.
+ * - dispose() is absorbing: every later public command is a no-op that never
+ *   re-creates an entry, issues a write, or arms a timer.
+ *
+ * The write port is infrastructure (ParallClient.updateAgentSession);
+ * retries, generations, error classification and the state machine live here.
+ */
+const DEFAULT_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 135_000, 405_000];
+const defaultScheduler = {
+    setTimeout(fn, ms) {
+        const timer = setTimeout(fn, ms);
+        timer.unref?.();
+        return timer;
+    },
+    clearTimeout(timer) {
+        clearTimeout(timer);
+    },
+};
+export class SessionLifecycleCoordinator {
+    opts;
+    sessions = new Map();
+    scheduler;
+    retryDelays;
+    // Generations are coordinator-global and strictly increasing, so a handle
+    // from before an entry was reclaimed can never match a REBUILT entry for
+    // the same session id (per-entry counters restart at 1 — an ABA hazard
+    // where a stale finish would demote a fresh turn).
+    nextGeneration = 0;
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.scheduler = opts.scheduler ?? defaultScheduler;
+        this.retryDelays = opts.retryDelaysMs?.length ? opts.retryDelaysMs : DEFAULT_RETRY_DELAYS_MS;
+    }
+    /** Sessions currently tracked — reclaimed entries are gone (leak probe). */
+    trackedSessions() {
+        return this.sessions.size;
+    }
+    /**
+     * Declare a new turn. Resolves once one write attempt covering this turn's
+     * generation has settled (bounded: at most one in-flight predecessor plus
+     * one active write, each bounded by the write port's own timeout). Always
+     * resolves — a failed active write is warned and reconciled in the
+     * background, never blocks the caller.
+     */
+    async beginTurn(sessionId, triggerMessageId) {
+        // Dispose is absorbing: never touch the map (an upsert here would
+        // re-create an entry nothing will ever reclaim), never write.
+        // Generation 0 can't match any live entry, so the handle is inert.
+        if (this.disposed)
+            return { sessionId, generation: 0 };
+        const entry = this.upsert(sessionId);
+        entry.desired = 'active';
+        entry.triggerMessageId = triggerMessageId;
+        const generation = entry.generation;
+        const settled = this.waitFor(entry, generation);
+        this.pump(sessionId);
+        await settled;
+        return { sessionId, generation };
+    }
+    /**
+     * Declare the turn finished. A stale handle (a newer turn — or a close —
+     * has bumped this session's generation) is ignored: finish(turn N) can
+     * never override begin(turn N+1). Reconciliation runs detached.
+     */
+    finishTurn(handle) {
+        if (this.disposed)
+            return;
+        const entry = this.sessions.get(handle.sessionId);
+        if (!entry || entry.dropped || entry.generation !== handle.generation)
+            return;
+        if (entry.desired === 'closed')
+            return;
+        entry.desired = 'idle';
+        entry.retryAttempt = 0;
+        this.cancelRetry(entry);
+        this.pump(handle.sessionId);
+    }
+    /**
+     * Terminal transition (fork teardown). Serialized behind any in-flight
+     * write — a `closed` can never race the turn's idle — and reclaimed once
+     * settled. Resolves after one bounded settle with a STRUCTURED outcome:
+     * `closed` / `stale` / `permanent_failure` are terminal; `retrying` means
+     * background reconciliation continues — the caller keeps ownership of the
+     * session until `terminal` resolves. A close is never silently "done":
+     * every fate is observable.
+     */
+    async closeSession(sessionId) {
+        if (this.disposed) {
+            return { outcome: 'disposed', terminal: Promise.resolve('disposed') };
+        }
+        const entry = this.upsert(sessionId);
+        entry.desired = 'closed';
+        entry.triggerMessageId = undefined;
+        const generation = entry.generation;
+        const terminal = new Promise((resolve) => {
+            entry.closeWaiters.push({ generation, resolve });
+        });
+        const settled = this.waitFor(entry, generation);
+        this.pump(sessionId);
+        const settle = await settled;
+        return { outcome: closeSettleFor(settle), terminal };
+    }
+    /**
+     * Session is dead (stale / superseded) — no further lifecycle writes, and
+     * the entry is reclaimed (immediately when idle; at the end of an in-flight
+     * write otherwise, unless a new turn revives it in the meantime).
+     */
+    dropSession(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return;
+        entry.dropped = true;
+        this.cancelRetry(entry);
+        this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'dropped');
+        this.reclaim(sessionId, entry);
+    }
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions() {
+        for (const sessionId of [...this.sessions.keys()])
+            this.dropSession(sessionId);
+    }
+    /**
+     * One best-effort reconcile pass over unsettled sessions within a hard
+     * deadline (shutdown). Returns the number still unsettled.
+     */
+    async flush(deadlineMs) {
+        const deadline = Date.now() + deadlineMs;
+        for (const [sessionId, entry] of [...this.sessions.entries()]) {
+            if (this.disposed)
+                break;
+            if (entry.dropped || this.isSettled(entry))
+                continue;
+            this.cancelRetry(entry);
+            entry.retryAttempt = 0;
+            const timeLeft = deadline - Date.now();
+            if (timeLeft <= 0)
+                break;
+            const settled = this.waitFor(entry, entry.generation);
+            this.pump(sessionId);
+            await raceWithDeadline(settled, timeLeft);
+        }
+        let remaining = 0;
+        for (const entry of this.sessions.values()) {
+            if (!entry.dropped && !this.isSettled(entry))
+                remaining += 1;
+        }
+        return remaining;
+    }
+    dispose() {
+        this.disposed = true;
+        for (const entry of this.sessions.values()) {
+            this.cancelRetry(entry);
+            this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'disposed');
+            this.settleCloseTerminal(entry, 'disposed');
+        }
+        this.sessions.clear();
+    }
+    // --- internals ----------------------------------------------------------
+    /**
+     * Get-or-create the entry and take the next generation. A dropped entry is
+     * REUSED (not replaced): its `writing` flag keeps the single-writer chain
+     * intact if a pre-drop write is still on the wire, and the generation stays
+     * monotonic across the drop boundary.
+     */
+    upsert(sessionId) {
+        let entry = this.sessions.get(sessionId);
+        if (!entry) {
+            entry = {
+                desired: 'active',
+                generation: 0,
+                writing: false,
+                retryAttempt: 0,
+                waiters: [],
+                closeWaiters: [],
+                dropped: false,
+            };
+            this.sessions.set(sessionId, entry);
+        }
+        entry.dropped = false;
+        this.nextGeneration += 1;
+        entry.generation = this.nextGeneration;
+        entry.retryAttempt = 0;
+        this.cancelRetry(entry);
+        return entry;
+    }
+    waitFor(entry, generation) {
+        return new Promise((resolve) => {
+            entry.waiters.push({ generation, resolve });
+        });
+    }
+    isReconciled(entry) {
+        return (entry.written !== undefined &&
+            entry.written.state === entry.desired &&
+            entry.written.generation === entry.generation);
+    }
+    isAbandoned(entry) {
+        return (entry.abandoned !== undefined &&
+            entry.abandoned.state === entry.desired &&
+            entry.abandoned.generation === entry.generation);
+    }
+    /** Nothing more to do for the current desired state (written or given up). */
+    isSettled(entry) {
+        return this.isReconciled(entry) || this.isAbandoned(entry);
+    }
+    pump(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry || entry.writing || entry.dropped || this.disposed)
+            return;
+        if (this.isSettled(entry)) {
+            this.resolveWaiters(entry, entry.generation, this.isReconciled(entry) ? 'ok' : 'permanent');
+            this.reclaim(sessionId, entry);
+            return;
+        }
+        entry.writing = true;
+        void this.writeLoop(sessionId, entry);
+    }
+    async writeLoop(sessionId, entry) {
+        try {
+            while (!entry.dropped && !this.disposed && !this.isSettled(entry)) {
+                const snapshot = {
+                    state: entry.desired,
+                    generation: entry.generation,
+                    trigger: entry.triggerMessageId,
+                };
+                let outcome = 'ok';
+                try {
+                    await this.opts.write(sessionId, payloadFor(snapshot));
+                    entry.written = { state: snapshot.state, generation: snapshot.generation };
+                    entry.retryAttempt = 0;
+                    if (snapshot.state === 'closed') {
+                        this.settleCloseTerminal(entry, 'closed', snapshot.generation);
+                    }
+                }
+                catch (err) {
+                    outcome = this.classify(err);
+                    this.opts.log?.warn(`session ${sessionId} ${snapshot.state} write failed (${outcome}, gen ${snapshot.generation}): ${String(err)}`);
+                }
+                // A settle — success or failure — resolves every waiter this
+                // snapshot covers (the bounded beginTurn / closeSession contract).
+                this.resolveWaiters(entry, snapshot.generation, outcome);
+                if (outcome === 'stale') {
+                    // Terminal server-side: never write to this session again.
+                    entry.dropped = true;
+                    this.cancelRetry(entry);
+                    this.settleCloseTerminal(entry, 'stale');
+                    this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'stale');
+                    return;
+                }
+                const desiredUnchanged = snapshot.generation === entry.generation && snapshot.state === entry.desired;
+                if (outcome === 'permanent' && desiredUnchanged) {
+                    // No retry loop against a 4xx — a later turn (fresh generation)
+                    // un-abandons this session automatically.
+                    entry.abandoned = { state: snapshot.state, generation: snapshot.generation };
+                    if (snapshot.state === 'closed') {
+                        this.settleCloseTerminal(entry, 'permanent_failure', snapshot.generation);
+                    }
+                    return;
+                }
+                if (outcome === 'retry' && desiredUnchanged && !entry.dropped && !this.disposed) {
+                    // The retry re-enters pump and replays the LATEST desired state,
+                    // never this snapshot.
+                    this.scheduleRetry(sessionId, entry);
+                    return;
+                }
+                // Success, or the desired state advanced while writing: loop and
+                // reconcile the fresh state immediately.
+            }
+        }
+        finally {
+            entry.writing = false;
+            this.reclaim(sessionId, entry);
+        }
+    }
+    classify(err) {
+        if (this.opts.isSessionStale?.(err))
+            return 'stale';
+        if (this.opts.isRetryable?.(err))
+            return 'retry';
+        return 'permanent';
+    }
+    /**
+     * Drop the entry when it can never write again: dropped (and no write on
+     * the wire), a terminal `closed` that landed, or a `closed` that failed
+     * permanently (its fate has been reported via closeSession's outcome — an
+     * entry kept around would be an unowned leak, not a recovery path). Called
+     * after every write settles and from dropSession — this is what keeps the
+     * Map bounded on a long-lived daemon churning fork sessions.
+     */
+    reclaim(sessionId, entry) {
+        if (this.sessions.get(sessionId) !== entry)
+            return;
+        if (entry.writing)
+            return; // the write's finally will re-run this
+        const closedLanded = entry.desired === 'closed' &&
+            entry.written?.state === 'closed' &&
+            entry.written.generation === entry.generation;
+        const closedAbandoned = entry.desired === 'closed' &&
+            entry.abandoned?.state === 'closed' &&
+            entry.abandoned.generation === entry.generation;
+        if (!entry.dropped && !closedLanded && !closedAbandoned)
+            return;
+        this.cancelRetry(entry);
+        this.settleCloseTerminal(entry, closedLanded ? 'closed' : entry.dropped ? 'stale' : 'permanent_failure');
+        this.resolveWaiters(entry, Number.POSITIVE_INFINITY, closedLanded ? 'ok' : entry.dropped ? 'dropped' : 'permanent');
+        this.sessions.delete(sessionId);
+    }
+    scheduleRetry(sessionId, entry) {
+        if (entry.retryTimer !== undefined)
+            return;
+        if (entry.retryAttempt >= this.retryDelays.length) {
+            this.opts.log?.warn(`session ${sessionId} lifecycle reconcile giving up after ${entry.retryAttempt} retries (desired=${entry.desired})`);
+            entry.abandoned = { state: entry.desired, generation: entry.generation };
+            if (entry.desired === 'closed') {
+                this.settleCloseTerminal(entry, 'permanent_failure');
+            }
+            return;
+        }
+        const delay = this.retryDelays[entry.retryAttempt] ?? 5_000;
+        entry.retryAttempt += 1;
+        entry.retryTimer = this.scheduler.setTimeout(() => {
+            entry.retryTimer = undefined;
+            this.pump(sessionId);
+        }, delay);
+    }
+    cancelRetry(entry) {
+        if (entry.retryTimer !== undefined) {
+            this.scheduler.clearTimeout(entry.retryTimer);
+            entry.retryTimer = undefined;
+        }
+    }
+    resolveWaiters(entry, upToGeneration, settle) {
+        if (entry.waiters.length === 0)
+            return;
+        const remaining = [];
+        for (const waiter of entry.waiters) {
+            if (waiter.generation <= upToGeneration)
+                waiter.resolve(settle);
+            else
+                remaining.push(waiter);
+        }
+        entry.waiters = remaining;
+    }
+    /** Resolve closeSession terminal waiters covered by this settle, once. */
+    settleCloseTerminal(entry, outcome, upToGeneration = Number.POSITIVE_INFINITY) {
+        if (entry.closeWaiters.length === 0)
+            return;
+        const remaining = [];
+        for (const waiter of entry.closeWaiters) {
+            if (waiter.generation <= upToGeneration)
+                waiter.resolve(outcome);
+            else
+                remaining.push(waiter);
+        }
+        entry.closeWaiters = remaining;
+    }
+}
+/** Map a first-settle write outcome onto the closeSession vocabulary. */
+function closeSettleFor(settle) {
+    switch (settle) {
+        case 'ok':
+            return 'closed';
+        case 'retry':
+            return 'retrying';
+        case 'stale':
+        case 'dropped':
+            return 'stale';
+        case 'disposed':
+            return 'disposed';
+        default:
+            return 'permanent_failure';
+    }
+}
+function payloadFor(snapshot) {
+    if (snapshot.state === 'active') {
+        return {
+            status: 'active',
+            ...(snapshot.trigger ? { trigger_message_id: snapshot.trigger } : {}),
+        };
+    }
+    return snapshot.state === 'idle' ? { status: 'idle' } : { status: 'closed' };
+}
+async function raceWithDeadline(work, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), Math.max(0, ms));
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/skills/parall-clips.d.ts

@@ -1,2 +1,2 @@
-export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are packaged capabilities that let agents operate external systems \u2014\nAPIs and websites \u2014 through named commands installed in the org.\n\n## Discover\n\n```bash\nparall clip list            # clips installed in this org\nparall clip info <alias>    # commands, params, version\n```\n\n## Invoke\n\n```bash\nparall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s\n# input: JSON string or plain text, per the command's params in `info`\nparall clip invoke github-tools list-repos '{\"org\":\"acme\"}'\n```\n\nResults are JSON on stdout; failures print an error.\n\n## Behavior rules\n\n- An authorization error (clip not bound to you) is a fail-fast: ask the\n  clip's owner or an admin to bind it \u2014 do not retry or work around it.\n- If the executing runtime is offline or the call times out, report that\n  plainly; do not queue, and never fabricate a result for a run that errored.\n- A clip may act through a person's real logged-in account \u2014 outward,\n  irreversible, or spending actions (post, order, delete, pay) get the same\n  caution as any shared-state change: confirm when intent isn't explicit.\n- Reach for `parall clip list` whenever a task needs capabilities beyond\n  built-in tools.\n";
+export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are packaged capabilities that let agents operate external systems \u2014\nAPIs and websites \u2014 through named commands installed in the org.\n\n## Discover\n\n```bash\nparall clip list            # clips installed in this org\nparall clip info <alias>    # commands, params, version\n```\n\n## Invoke\n\n```bash\nparall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s\n# input: JSON string or plain text, per the command's params in `info`\nparall clip invoke github-tools list-repos '{\"org\":\"acme\"}'\n```\n\nResults are JSON on stdout; failures print an error.\n\n## Behavior rules\n\n- An authorization error (clip not bound to you) is a fail-fast: ask the\n  clip's owner or an admin to bind it \u2014 do not retry or work around it.\n- If the executing runtime is offline or the call times out, report that\n  plainly; do not queue, and never fabricate a result for a run that errored.\n- Hosted browser activation is handled by the CLI: it waits (bounded) while a\n  cold hosted browser starts, so if the invoke still fails, report the error \u2014\n  do not blind-retry in a loop.\n- A clip may act through a person's real logged-in account \u2014 outward,\n  irreversible, or spending actions (post, order, delete, pay) get the same\n  caution as any shared-state change: confirm when intent isn't explicit.\n- Reach for `parall clip list` whenever a task needs capabilities beyond\n  built-in tools.\n";
 //# sourceMappingURL=parall-clips.d.ts.map

package/dist/skills/parall-clips.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,gwCAiC9B,CAAC"}
+{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,q8CAoC9B,CAAC"}

package/dist/skills/parall-clips.js

@@ -26,6 +26,9 @@ Results are JSON on stdout; failures print an error.
   clip's owner or an admin to bind it — do not retry or work around it.
 - If the executing runtime is offline or the call times out, report that
   plainly; do not queue, and never fabricate a result for a run that errored.
+- Hosted browser activation is handled by the CLI: it waits (bounded) while a
+  cold hosted browser starts, so if the invoke still fails, report the error —
+  do not blind-retry in a loop.
 - A clip may act through a person's real logged-in account — outward,
   irreversible, or spending actions (post, order, delete, pay) get the same
   caution as any shared-state change: confirm when intent isn't explicit.

package/dist/step-persister.d.ts

@@ -0,0 +1,66 @@
+import type { AgentStep, CreateAgentStepRequest, ParallClient } from '@parall/sdk';
+import { type StepDrainOutcome } from './step-retry-queue.js';
+/**
+ * AgentStep write path: one place decides inline-write vs park-for-retry.
+ *
+ * Extracted from the gateway so step persistence is a nameable collaborator
+ * instead of more growth in gateway-base.ts. Behavior contract (see
+ * AGENTS.md § Step write resilience): every request carries an
+ * idempotency_key so retries are replay-safe; transient failures park in the
+ * per-session FIFO StepRetryQueue; while a session has parked writes, new
+ * writes queue behind them to preserve ledger order; session-stale errors
+ * propagate to the caller (the gateway's existing recovery contract).
+ */
+export type StepPersisterOpts = {
+    client: ParallClient;
+    orgId: string;
+    agentUserId: string;
+    log?: {
+        warn: (msg: string) => void;
+    };
+    /** Session is dead (SESSION_NOT_LIVE / INVALID_TRANSITION 409). */
+    isSessionStale: (err: unknown) => boolean;
+    /** Retry backoff override (tests). Default: StepRetryQueue's schedule. */
+    retryDelaysMs?: number[];
+};
+export declare function isRetryableStepError(err: unknown): boolean;
+export declare class StepPersister {
+    private readonly opts;
+    private readonly queue;
+    private readonly sealed;
+    private disposed;
+    constructor(opts: StepPersisterOpts);
+    /**
+     * Write one AgentStep, riding the retry queue on transient failure.
+     * Returns the created step, or null when the write was queued or dropped.
+     */
+    persist(sessionId: string, label: string, req: CreateAgentStepRequest): Promise<AgentStep | null>;
+    /**
+     * Close the producer end for a session (finalization began): subsequent
+     * persist() calls are refused with a warn. Parked/in-flight writes keep
+     * retrying — seal gates NEW writes only.
+     */
+    seal(sessionId: string): void;
+    /**
+     * Reclaim a seal once its finalization released the session (the seal set
+     * must not grow forever on a daemon churning fork sessions). After the
+     * session is closed server-side, any late write is rejected there (409).
+     */
+    unseal(sessionId: string): void;
+    /**
+     * Resolves when the session's step queue reaches quiescence — see
+     * StepRetryQueue.awaitSessionDrained. Non-destructive: parked writes keep
+     * retrying on their normal schedule while awaited.
+     */
+    drainSession(sessionId: string): Promise<StepDrainOutcome>;
+    /** DESTRUCTIVE: discards the session's parked writes (server-terminal only). */
+    dropSession(sessionId: string): void;
+    /** Every session is dead (server closed them all — new_session). */
+    dropAllSessions(): void;
+    /** Best-effort single pass over parked writes; returns items still parked. */
+    flush(deadlineMs: number): Promise<number>;
+    pendingTotal(): number;
+    dispose(): void;
+    private enqueue;
+}
+//# sourceMappingURL=step-persister.d.ts.map

package/dist/step-persister.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-persister.d.ts","sourceRoot":"","sources":["../src/step-persister.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAE,KAAK,gBAAgB,EAAkB,MAAM,uBAAuB,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtC,mEAAmE;IACnE,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED,qBAAa,aAAa;IAOZ,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IAGvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,iBAAiB;IAcpD;;;OAGG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAuC5B;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D,gFAAgF;IAChF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKpC,oEAAoE;IACpE,eAAe,IAAI,IAAI;IAKvB,8EAA8E;IAC9E,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C,YAAY,IAAI,MAAM;IAItB,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,OAAO;CAOhB"}

package/dist/step-persister.js

@@ -0,0 +1,116 @@
+import { ApiError } from '@parall/sdk';
+import { StepRetryQueue } from './step-retry-queue.js';
+export function isRetryableStepError(err) {
+    // ApiError status 0 = fetch-level failure (timeout / network); 5xx =
+    // server-side transient. 4xx are contract errors a retry cannot fix.
+    return err instanceof ApiError && (err.status === 0 || err.status >= 500);
+}
+export class StepPersister {
+    opts;
+    queue;
+    // Sessions whose producer end is closed (finalization in progress) — new
+    // writes are refused instead of racing the drain/close sequence.
+    sealed = new Set();
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.queue = new StepRetryQueue({
+            log: opts.log,
+            isRetryable: isRetryableStepError,
+            isSessionStale: opts.isSessionStale,
+            retryDelaysMs: opts.retryDelaysMs,
+            // Inline step writes already drive full stale recovery; a background
+            // retry discovering it just drops the dead session's queue — the next
+            // dispatch hits the same 409 inline and heals.
+            onSessionStale: (sessionId, err) => opts.log?.warn(`queued step hit stale session ${sessionId}: ${String(err)}`),
+        });
+    }
+    /**
+     * Write one AgentStep, riding the retry queue on transient failure.
+     * Returns the created step, or null when the write was queued or dropped.
+     */
+    async persist(sessionId, label, req) {
+        if (this.disposed) {
+            // Absorbing, like the queue and the lifecycle coordinator: a dispatch
+            // still draining past the shutdown deadline must not race the exiting
+            // process with fresh inline writes — its WorkItem is un-acked, so the
+            // re-drive on the replacement pod rewrites these steps idempotently.
+            this.opts.log?.warn(`refusing ${label} step after dispose (shutting down)`);
+            return null;
+        }
+        if (this.sealed.has(sessionId)) {
+            this.opts.log?.warn(`refusing ${label} step for sealed session ${sessionId} (finalization in progress)`);
+            return null;
+        }
+        if (this.queue.hasPending(sessionId)) {
+            // Preserve per-session FIFO while degraded.
+            this.enqueue(sessionId, label, req);
+            return null;
+        }
+        try {
+            return await this.opts.client.createAgentStep(this.opts.orgId, this.opts.agentUserId, sessionId, req);
+        }
+        catch (err) {
+            if (this.opts.isSessionStale(err))
+                throw err;
+            if (isRetryableStepError(err)) {
+                this.opts.log?.warn(`failed to create ${label} step (queued for retry): ${String(err)}`);
+                this.enqueue(sessionId, label, req);
+            }
+            else {
+                this.opts.log?.warn(`failed to create ${label} step: ${String(err)}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Close the producer end for a session (finalization began): subsequent
+     * persist() calls are refused with a warn. Parked/in-flight writes keep
+     * retrying — seal gates NEW writes only.
+     */
+    seal(sessionId) {
+        this.sealed.add(sessionId);
+    }
+    /**
+     * Reclaim a seal once its finalization released the session (the seal set
+     * must not grow forever on a daemon churning fork sessions). After the
+     * session is closed server-side, any late write is rejected there (409).
+     */
+    unseal(sessionId) {
+        this.sealed.delete(sessionId);
+    }
+    /**
+     * Resolves when the session's step queue reaches quiescence — see
+     * StepRetryQueue.awaitSessionDrained. Non-destructive: parked writes keep
+     * retrying on their normal schedule while awaited.
+     */
+    drainSession(sessionId) {
+        return this.queue.awaitSessionDrained(sessionId);
+    }
+    /** DESTRUCTIVE: discards the session's parked writes (server-terminal only). */
+    dropSession(sessionId) {
+        this.sealed.delete(sessionId);
+        this.queue.dropSession(sessionId);
+    }
+    /** Every session is dead (server closed them all — new_session). */
+    dropAllSessions() {
+        this.sealed.clear();
+        this.queue.dropAllSessions();
+    }
+    /** Best-effort single pass over parked writes; returns items still parked. */
+    flush(deadlineMs) {
+        return this.queue.flush(deadlineMs);
+    }
+    pendingTotal() {
+        return this.queue.pendingTotal();
+    }
+    dispose() {
+        this.disposed = true;
+        this.queue.dispose();
+    }
+    enqueue(sessionId, label, req) {
+        this.queue.enqueue(sessionId, label, () => this.opts.client
+            .createAgentStep(this.opts.orgId, this.opts.agentUserId, sessionId, req)
+            .then(() => undefined));
+    }
+}