@parall/agent-core 1.45.0 → 1.46.0

package/dist/gateway-lane-flow.d.ts.map

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

package/dist/gateway-lane-flow.js

@@ -218,16 +218,23 @@ export async function settleDrainedTypedGroup(host, events, ids, turnErrored) {
         return;
     }
     // The legacy ack BY ID, never by source — task siblings share a source
-    // pair, and a by-source ack would sweep the undispatched one. Awaited:
-    // these rows are already pending (released at buffer time), so a failed
-    // ack must free the local dedupe claim or the pending retry would be
-    // self-rejected by this pod forever.
+    // pair, and a by-source ack would sweep the undispatched one. Awaited, and
+    // the dedupe claim is freed on EVERY outcome: a claim's lifetime is the
+    // buffer stay (#1149). On failure the row is still pending and its retry
+    // must not be self-rejected; on success the row is terminal — but a
+    // shared-key sibling WorkItem (task assign+update fetch the same
+    // `task:updated_at` pair) must not be rejected by a leftover claim either.
     const legacyAckFrom = async (start) => {
         for (const [j, id] of ids.slice(start).entries()) {
             try {
                 await host.opts.client.ackDispatchByID(host.opts.config.org_id, id);
             }
             catch {
+                // Transient ack failure: the row stays live server-side and its
+                // re-drive re-converges — keep settling the REST of the group (a
+                // propagated error would strand every later id's retained claim).
+            }
+            finally {
                 clearTypedDedupeForEvent(host, events[start + j]);
             }
         }
@@ -246,9 +253,8 @@ export async function settleDrainedTypedGroup(host, events, ids, turnErrored) {
             await legacyAckFrom(i);
             return;
         }
-        if (outcome !== 'ok') {
-            clearTypedDedupeForEvent(host, events[i]);
-        }
+        // Freed on every outcome — see legacyAckFrom's contract note.
+        clearTypedDedupeForEvent(host, events[i]);
     }
 }
 /** Failure backoff pacing for typed dispatch retries (base 2s, cap 5min). */

package/dist/http-keepalive.d.ts

@@ -0,0 +1,4 @@
+export declare function configureHttpKeepAlive(opts?: {
+    keepAliveTimeoutMs?: number;
+}): void;
+//# sourceMappingURL=http-keepalive.d.ts.map

package/dist/http-keepalive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-keepalive.d.ts","sourceRoot":"","sources":["../src/http-keepalive.ts"],"names":[],"mappings":"AAsBA,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAanF"}

package/dist/http-keepalive.js

@@ -0,0 +1,33 @@
+import { Agent, setGlobalDispatcher } from 'undici';
+/**
+ * Keep bridge→api HTTP connections long-lived.
+ *
+ * Node's built-in fetch closes idle pooled connections after ~4s when the
+ * server sends no Keep-Alive hint (our NLB+Envoy edge sends none), so any two
+ * bridge API calls spaced more than a few seconds apart pay a fresh TCP+TLS
+ * handshake. On a degraded long-haul link that handshake is exactly what
+ * fails — established connections (the WS, the runtime's own model stream)
+ * ride through such windows while every bridge call times out (2026-07-10:
+ * step creation losses). A 2-minute idle timeout keeps one warm connection
+ * across an active turn's step cadence, comfortably below the NLB's 350s
+ * idle cutoff.
+ *
+ * Uses undici's global-dispatcher registry, which Node's built-in fetch
+ * shares (verified on Node 22 / undici 7) — so this covers every fetch in
+ * the process: ParallClient, lane-ledger heartbeats, OTLP export.
+ * Node-only; call once from a bridge/daemon entrypoint before any fetch.
+ */
+let installed = false;
+export function configureHttpKeepAlive(opts) {
+    // Idempotent: a second call (e.g. a process hosting several bridge
+    // entrypoints) must not replace — and leak — the already-installed Agent.
+    if (installed)
+        return;
+    installed = true;
+    const keepAliveTimeout = opts?.keepAliveTimeoutMs ?? 120_000;
+    setGlobalDispatcher(new Agent({
+        keepAliveTimeout,
+        // Also cap the server-hinted value: never idle past the edge's cutoff.
+        keepAliveMaxTimeout: keepAliveTimeout,
+    }));
+}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './bridge-workspace.js';
 export * from './dispatch-adapter.js';
 export { createLogger, childLogger } from './logger.js';
 export * from './gateway-base.js';
+export { configureHttpKeepAlive } from './http-keepalive.js';
 export * from './platform-config.js';
 export * from './channel-capability.js';
 export * from './channel-token.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACvF,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAClF,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACvF,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAClF,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -10,6 +10,12 @@ export * from './bridge-workspace.js';
 export * from './dispatch-adapter.js';
 export { createLogger, childLogger } from './logger.js';
 export * from './gateway-base.js';
+export { configureHttpKeepAlive } from './http-keepalive.js';
+// StepPersister / StepRetryQueue / SessionLifecycleCoordinator /
+// ForkSessionFinalizer are internal gateway collaborators — deliberately NOT
+// re-exported from the package root (no external consumer; a root export
+// would become an accidental long-term compat promise). Tests import their
+// built modules directly (e.g. `../dist/step-retry-queue.js`).
 export * from './platform-config.js';
 export * from './channel-capability.js';
 export * from './channel-token.js';

package/dist/session-lifecycle.d.ts

@@ -0,0 +1,198 @@
+/**
+ * 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.
+ */
+export type SessionStatusPayload = {
+    status: 'active';
+    trigger_message_id?: string;
+} | {
+    status: 'idle';
+} | {
+    status: 'closed';
+};
+export type TurnHandle = {
+    sessionId: string;
+    generation: number;
+};
+/**
+ * Terminal fate of a closeSession: `closed` — the write landed; `stale` —
+ * the server already considers the session terminal (equivalent outcome for
+ * the caller); `permanent_failure` — a 4xx or retry exhaustion; the close
+ * will never be written and the server-side session may be left non-closed;
+ * `disposed` — the coordinator shut down before the close settled.
+ */
+export type SessionCloseOutcome = 'closed' | 'stale' | 'permanent_failure' | 'disposed';
+/** First-settle view: `retrying` means a transient failure settled the first
+ * bounded attempt and background reconciliation continues — await `terminal`
+ * for the eventual fate. */
+export type SessionCloseSettle = SessionCloseOutcome | 'retrying';
+export type SessionCloseResult = {
+    /** Outcome of the first bounded settle (one write attempt covering the close). */
+    outcome: SessionCloseSettle;
+    /**
+     * Resolves when the close reaches a terminal state. Already resolved (to
+     * `outcome`) unless `outcome === 'retrying'`.
+     */
+    terminal: Promise<SessionCloseOutcome>;
+};
+export type SessionLifecycleScheduler = {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(timer: unknown): void;
+};
+export type SessionLifecycleOpts = {
+    write: (sessionId: string, payload: SessionStatusPayload) => Promise<void>;
+    /**
+     * Transient failure worth retrying (timeout / network / 5xx). Anything
+     * else is treated as permanent: warn + abandon (no retry loop against a
+     * 400/401/403/404). Default: nothing is retryable — callers that want
+     * retries must classify.
+     */
+    isRetryable?: (err: unknown) => boolean;
+    /**
+     * The server considers this session terminal (409 SESSION_NOT_LIVE /
+     * INVALID_TRANSITION). The session is dropped — no further lifecycle
+     * writes, ever. Default: never stale.
+     */
+    isSessionStale?: (err: unknown) => boolean;
+    log?: {
+        warn: (msg: string) => void;
+    };
+    /** Test port; default wraps global timers and unrefs them. */
+    scheduler?: SessionLifecycleScheduler;
+    /** Reconcile retry backoff. Default 5s→15s→45s→135s→405s (~10 min). */
+    retryDelaysMs?: number[];
+};
+export declare class SessionLifecycleCoordinator {
+    private readonly opts;
+    private readonly sessions;
+    private readonly scheduler;
+    private readonly retryDelays;
+    private nextGeneration;
+    private disposed;
+    constructor(opts: SessionLifecycleOpts);
+    /** Sessions currently tracked — reclaimed entries are gone (leak probe). */
+    trackedSessions(): number;
+    /**
+     * 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.
+     */
+    beginTurn(sessionId: string, triggerMessageId?: string): Promise<TurnHandle>;
+    /**
+     * 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: TurnHandle): void;
+    /**
+     * 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.
+     */
+    closeSession(sessionId: string): Promise<SessionCloseResult>;
+    /**
+     * 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: string): void;
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions(): void;
+    /**
+     * One best-effort reconcile pass over unsettled sessions within a hard
+     * deadline (shutdown). Returns the number still unsettled.
+     */
+    flush(deadlineMs: number): Promise<number>;
+    dispose(): void;
+    /**
+     * 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.
+     */
+    private upsert;
+    private waitFor;
+    private isReconciled;
+    private isAbandoned;
+    /** Nothing more to do for the current desired state (written or given up). */
+    private isSettled;
+    private pump;
+    private writeLoop;
+    private classify;
+    /**
+     * 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.
+     */
+    private reclaim;
+    private scheduleRetry;
+    private cancelRetry;
+    private resolveWaiters;
+    /** Resolve closeSession terminal waiters covered by this settle, once. */
+    private settleCloseTerminal;
+}
+//# sourceMappingURL=session-lifecycle.d.ts.map

package/dist/session-lifecycle.d.ts.map

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