@parall/agent-core 1.37.0 → 1.38.0

package/dist/lane-ledger.js

@@ -0,0 +1,333 @@
+import * as fs from 'node:fs';
+import { ApiError } from '@parall/sdk';
+import { laneContextFilePath, laneKeyForTarget } from './lane-key.js';
+/**
+ * Thrown when the server predates the dispatch ledger (claim endpoint 404s
+ * during a rolling deploy). The gateway falls back to the legacy
+ * received/ack flow for the rest of its lifetime.
+ */
+export class LedgerUnsupportedError extends Error {
+}
+function isStaleLane(err) {
+    return err instanceof ApiError && err.status === 409 && err.code === 'STALE_LANE';
+}
+function isNotFound(err) {
+    return err instanceof ApiError && err.status === 404;
+}
+/**
+ * A pre-ledger server (or an edge that doesn't know the route) answers the
+ * claim endpoint with an UNSTRUCTURED 404 — no app error code. Our own
+ * handlers always attach a code, so a coded 404 is a semantic answer, not a
+ * missing endpoint. Transient edge 404s during rolling deploys are further
+ * contained by the reconnect re-probe (ledgerDisabled resets on hello).
+ */
+function isEndpointMissing(err) {
+    return err instanceof ApiError && err.status === 404 && !err.code;
+}
+/**
+ * LaneLedger is the bridge-side client of the server dispatch ledger
+ * (docs/engineering-design/agent-dispatch-idempotency-design.md): it claims
+ * lane occupancy just-in-time before a message dispatch, folds mid-turn
+ * same-target messages via steer, completes (no_action sweep + release) when
+ * the local queue for a lane runs dry, and releases leftovers on shutdown.
+ *
+ * It is also the single writer of the per-lane dispatch context files under
+ * PRLL_CONTEXT_DIR (`<lane-key>.json`) that the CLI reads to derive dispatch
+ * effect keys. The CLI's reply-state sidecar lives next to it and is never
+ * touched here (two writers, two files).
+ */
+export class LaneLedger {
+    opts;
+    lanes = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get contextDir() {
+        return this.opts.contextDir;
+    }
+    /** Only chat message events ride the lane ledger; typed events stay on the legacy ack path. */
+    handles(event) {
+        return event.type === 'message' && event.targetId.startsWith('cht_');
+    }
+    laneKeyFor(event) {
+        if (event.type !== 'message' && event.dispatchEventId) {
+            return laneKeyForTarget(`dsp:${event.dispatchEventId}`);
+        }
+        return laneKeyForTarget(`prll://${event.targetId}`, event.threadRootId);
+    }
+    getForEvent(event) {
+        return this.lanes.get(this.laneKeyFor(event));
+    }
+    laneContextPath(lane) {
+        return laneContextFilePath(this.opts.contextDir, lane.targetUri, lane.threadRootId);
+    }
+    /**
+     * Claim (or reuse) the lane for a group of same-lane message events and
+     * fold every group member into it. Returns 'foreign' when a healthy
+     * incumbent (another pod) holds the resource — the caller must not
+     * dispatch; the events stay pending server-side and re-drive after the
+     * incumbent completes.
+     */
+    async ensureLane(events) {
+        const trigger = events[events.length - 1];
+        const laneKey = this.laneKeyFor(trigger);
+        let lane = this.lanes.get(laneKey);
+        if (!lane) {
+            const targetUri = `prll://${trigger.targetId}`;
+            let res;
+            try {
+                res = await this.opts.client.claimDispatch(this.opts.orgId, {
+                    target_uri: targetUri,
+                    thread_root_id: trigger.threadRootId,
+                    limit: 100,
+                });
+            }
+            catch (err) {
+                if (isEndpointMissing(err))
+                    throw new LedgerUnsupportedError('claim endpoint unavailable');
+                throw err;
+            }
+            if (!res.claimed || !res.lane) {
+                this.opts.log?.info(`lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`);
+                return null;
+            }
+            const leaseUntilMs = Date.parse(res.lease_until ?? '');
+            lane = {
+                laneKey,
+                lane: res.lane,
+                targetUri,
+                threadRootId: trigger.threadRootId,
+                folded: new Map(),
+                ...(Number.isNaN(leaseUntilMs)
+                    ? {}
+                    : { leaseUntilMs, leaseTtlMs: Math.max(leaseUntilMs - Date.now(), 60_000) }),
+            };
+            for (const ev of res.events ?? []) {
+                lane.folded.set(ev.source_id, ev.id);
+            }
+            this.lanes.set(laneKey, lane);
+        }
+        // Fold group members the claim didn't cover (they arrived after the
+        // claim, or this group reuses an already-active lane). Fail closed on ANY
+        // fold failure: an un-folded message dispatched now would not be covered
+        // by this lane's reply/complete, so its still-live WorkItem would re-drive
+        // later and the model would handle it twice. Releasing hands the folded
+        // members back to pending immediately; the re-drive / live hint path
+        // re-delivers the whole group under a fresh claim.
+        for (const ev of events) {
+            if (lane.folded.has(ev.messageId))
+                continue;
+            try {
+                const res = await this.opts.client.steerDispatch(this.opts.orgId, {
+                    lane: lane.lane,
+                    target_uri: lane.targetUri,
+                    thread_root_id: lane.threadRootId,
+                    ...(ev.dispatchEventId
+                        ? { dispatch_event_id: ev.dispatchEventId }
+                        : { source_type: 'message', source_id: ev.messageId }),
+                });
+                lane.folded.set(ev.messageId, res.dispatch_event_id);
+            }
+            catch (err) {
+                if (isStaleLane(err)) {
+                    // We lost the lane mid-group — drop local state; the takeover
+                    // owner (or the next claim) picks the members up.
+                    this.lanes.delete(laneKey);
+                    return null;
+                }
+                this.opts.log?.warn(`steer fold failed for ${ev.messageId} — failing closed, releasing lane: ${String(err)}`);
+                await this.release(laneKey);
+                return null;
+            }
+        }
+        return lane;
+    }
+    /**
+     * Fold a live mid-turn message into its active lane BEFORE injecting it
+     * into the running turn. Injection without a successful fold is forbidden —
+     * an un-folded injected message would be re-driven after complete and the
+     * model would handle it twice.
+     */
+    async steerLive(event) {
+        const laneKey = this.laneKeyFor(event);
+        const lane = this.lanes.get(laneKey);
+        if (!lane)
+            return false;
+        if (lane.folded.has(event.messageId))
+            return true;
+        try {
+            const res = await this.opts.client.steerDispatch(this.opts.orgId, {
+                lane: lane.lane,
+                target_uri: lane.targetUri,
+                thread_root_id: lane.threadRootId,
+                ...(event.dispatchEventId
+                    ? { dispatch_event_id: event.dispatchEventId }
+                    : { source_type: 'message', source_id: event.messageId }),
+            });
+            lane.folded.set(event.messageId, res.dispatch_event_id);
+            return true;
+        }
+        catch (err) {
+            if (isStaleLane(err)) {
+                this.lanes.delete(laneKey);
+            }
+            else {
+                this.opts.log?.warn(`live steer failed for ${event.messageId}: ${String(err)}`);
+            }
+            return false;
+        }
+    }
+    /**
+     * Complete the lane when no local work remains for it: the server sweeps
+     * still-leased members as no_action, releases the occupancy row, and
+     * re-drives any same-target pending work. A STALE_LANE answer means a
+     * takeover already owns the resource — local state is dropped either way.
+     */
+    async completeIfIdle(laneKey, hasMoreLocal) {
+        const lane = this.lanes.get(laneKey);
+        if (!lane || hasMoreLocal)
+            return;
+        this.lanes.delete(laneKey);
+        this.removeLaneContext(lane);
+        try {
+            const res = await this.opts.client.completeDispatch(this.opts.orgId, {
+                lane: lane.lane,
+                target_uri: lane.targetUri,
+                thread_root_id: lane.threadRootId,
+            });
+            if (res.swept_no_action > 0 || res.redriven) {
+                this.opts.log?.info(`lane complete for ${lane.targetUri}: swept ${res.swept_no_action} no_action, redriven=${res.redriven}`);
+            }
+        }
+        catch (err) {
+            if (isStaleLane(err)) {
+                this.opts.log?.info(`lane complete skipped for ${lane.targetUri} — taken over`);
+                return;
+            }
+            // Lease expiry recovers the members; complete is not retried here.
+            this.opts.log?.warn(`lane complete failed for ${lane.targetUri}: ${String(err)}`);
+        }
+    }
+    /**
+     * Long-turn keepalive: renew the lane's lease on runtime activity, throttled
+     * so a chatty turn doesn't spam the server. Without this, a legitimately
+     * long turn (> lane TTL) would be dethroned mid-flight and every subsequent
+     * write misfired with STALE_LANE — the design doc's "long turns renew via
+     * step writes". Fire-and-forget: a failed renewal is surfaced by the next
+     * write's incumbency check anyway.
+     */
+    maybeRenew(lane) {
+        const now = Date.now();
+        // Server-driven pacing: renew once less than half the lease TTL remains.
+        // Hardcoding a client-side rhythm would silently break every published
+        // runtime image the day the server shortens its lane TTL.
+        const ttl = lane.leaseTtlMs ?? 10 * 60_000;
+        const until = lane.leaseUntilMs ?? now; // unknown lease → renew now
+        if (until - now > ttl / 2)
+            return;
+        lane.leaseUntilMs = now + ttl; // optimistic; corrected by the response
+        void this.opts.client
+            .heartbeatDispatchLane(this.opts.orgId, {
+            lane: lane.lane,
+            target_uri: lane.targetUri,
+            thread_root_id: lane.threadRootId,
+        })
+            .then((res) => {
+            const until = Date.parse(res?.lease_until ?? '');
+            if (!Number.isNaN(until))
+                lane.leaseUntilMs = until;
+        })
+            .catch((err) => {
+            if (isStaleLane(err)) {
+                this.lanes.delete(lane.laneKey);
+                this.opts.log?.warn(`lane ${lane.targetUri} was taken over during the turn`);
+                return;
+            }
+            this.opts.log?.warn(`lane heartbeat failed for ${lane.targetUri}: ${String(err)}`);
+        });
+    }
+    /**
+     * Release a lane's unresolved members back to pending (dispatch error /
+     * shutdown) so the next pod re-claims immediately instead of waiting out
+     * the lease.
+     */
+    async release(laneKey) {
+        const lane = this.lanes.get(laneKey);
+        if (!lane)
+            return;
+        this.lanes.delete(laneKey);
+        this.removeLaneContext(lane);
+        try {
+            await this.opts.client.releaseDispatchLane(this.opts.orgId, lane.lane);
+        }
+        catch (err) {
+            this.opts.log?.warn(`lane release failed for ${lane.targetUri}: ${String(err)}`);
+        }
+    }
+    async releaseAll() {
+        const keys = [...this.lanes.keys()];
+        for (const key of keys) {
+            await this.release(key);
+        }
+    }
+    /** True when any lane is currently active (used by shutdown logging). */
+    get activeCount() {
+        return this.lanes.size;
+    }
+    /**
+     * Claim the single-member lane of one typed WorkItem (resource = dsp:<id>),
+     * by WorkItem id or by source identity (the live task.assigned event has no
+     * WorkItem id). Returns null when a healthy incumbent (another pod) holds
+     * it or the WorkItem is already resolved — the caller must skip processing.
+     */
+    async claimTyped(ref) {
+        let res;
+        try {
+            res = await this.opts.client.claimDispatch(this.opts.orgId, {
+                dispatch_event_id: ref.dispatchEventId,
+                source_type: ref.dispatchEventId ? undefined : ref.sourceType,
+                source_id: ref.dispatchEventId ? undefined : ref.sourceId,
+            });
+        }
+        catch (err) {
+            if (isEndpointMissing(err))
+                throw new LedgerUnsupportedError('claim endpoint unavailable');
+            throw err;
+        }
+        if (!res.claimed || !res.lane || !res.events?.length)
+            return null;
+        const workItem = res.events[0];
+        const targetUri = `dsp:${workItem.id}`;
+        const leaseUntilMs = Date.parse(res.lease_until ?? '');
+        const lane = {
+            laneKey: laneKeyForTarget(targetUri),
+            lane: res.lane,
+            targetUri,
+            folded: new Map([[workItem.source_id, workItem.id]]),
+            typedDispatchEventId: workItem.id,
+            ...(Number.isNaN(leaseUntilMs)
+                ? {}
+                : { leaseUntilMs, leaseTtlMs: Math.max(leaseUntilMs - Date.now(), 60_000) }),
+        };
+        this.lanes.set(lane.laneKey, lane);
+        return lane;
+    }
+    /**
+     * Remove the per-lane context file (and its CLI sidecar) when the lane
+     * ends. A leftover file would make a later cross-context send to the same
+     * target bind a dead lane token and misfire with STALE_LANE instead of
+     * taking the plain non-ledger path.
+     */
+    removeLaneContext(lane) {
+        const contextPath = this.laneContextPath(lane);
+        for (const p of [contextPath, contextPath.replace(/\.json$/, '.reply-state.json')]) {
+            try {
+                fs.rmSync(p, { force: true });
+            }
+            catch {
+                // Best-effort: a stale file only re-surfaces as a server-side
+                // STALE_LANE, never as a wrong write.
+            }
+        }
+    }
+}

package/dist/types.d.ts

@@ -72,6 +72,8 @@ export type ParallEvent = {
     sentAt?: string;
     ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run' | 'channel_message';
     ackSourceId?: string;
+    /** WorkItem id, when known (dispatch catch-up / re-drive hints carry it; live message.new does not). */
+    dispatchEventId?: string;
     /** Unread message count in the target chat since agent's last interaction. */
     unreadCount?: number;
     /** Channel cursor: the last message ID the agent read. */

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.37.0"
+    "@parall/sdk": "1.38.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch-adapter.ts

@@ -23,6 +23,12 @@ export type DispatchContext = {
   contextFilePath?: string;
   /** @deprecated Use contextFilePath. Kept for runtimes that haven't migrated. */
   stepIdFilePath?: string;
+  /**
+   * PRLL_CONTEXT_DIR contract: the per-agent directory holding per-lane
+   * dispatch context files (`<lane-key>.json`, see lane-key.ts). Stable for
+   * the life of the bridge — safe to pin into spawn env.
+   */
+  contextDirPath?: string;
   client: ParallClient;
   log?: GatewayLogger;
 };