@parall/agent-core 1.37.0 → 1.38.0

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

@@ -0,0 +1,74 @@
+import type { ParallClient } from '@parall/sdk';
+import type { DispatchAdapter, GatewayLogger } from './dispatch-adapter.js';
+import type { DispatchableMessage, MessageDispatchDecision } from './gateway-base.js';
+import type { LaneLedger } from './lane-ledger.js';
+import type { ParallEvent } from './types.js';
+/**
+ * Lane-flow layer: the ledger-aware consumption protocols that sit between
+ * inbound routing and `runDispatch`. Split out of gateway-base.ts (already an
+ * oversized outlier) — the gateway keeps thin delegating methods so tests and
+ * call sites stay on the class surface.
+ */
+/** The slice of ParallAgentGateway the lane-flow functions operate on. */
+export interface LaneFlowHost {
+    laneLedger?: LaneLedger;
+    ledgerDisabled: boolean;
+    shuttingDown: boolean;
+    dispatchedMessages: Set<string>;
+    opts: {
+        client: ParallClient;
+        log?: GatewayLogger;
+        config: {
+            org_id: string;
+        };
+        dispatchAdapter: DispatchAdapter;
+        agentUserId: string;
+    };
+    disableLedger(reason: string): void;
+    usesLaneLedger(event: ParallEvent): boolean;
+    emitDispatchReceived(event: ParallEvent): Promise<void>;
+    runDispatch(event: ParallEvent, sessionKey: string, bodyForAgent: string, earlierEvents?: ParallEvent[], captureText?: string[]): Promise<boolean>;
+    tryClaimMessage(id: string): boolean;
+    buildMessageDispatchDecision(chatId: string, message: DispatchableMessage): Promise<MessageDispatchDecision>;
+    handleInboundEvent(event: ParallEvent): Promise<boolean>;
+}
+/**
+ * Dispatch one group of same-lane message events under the ledger contract:
+ * claim (or reuse) the lane, run the dispatch, then complete when no local
+ * work remains for the lane. No legacy received/ack calls — the claim marks
+ * members received and complete/reply resolve them server-side.
+ */
+export declare function dispatchLaneGroup(host: LaneFlowHost, opts: {
+    events: ParallEvent[];
+    sessionKey: string;
+    body: string;
+    earlier: ParallEvent[];
+    captureText?: string[];
+    hasMoreLocal: () => boolean;
+}): Promise<'dispatched' | 'foreign' | 'shutdown'>;
+/**
+ * Consume one typed dispatch (task/comment/schedule/trigger/approval) under
+ * its typed-lane occupancy guard: claim the dsp:<id> lane (skip when another
+ * pod holds it or the WorkItem is already resolved), run the handler, ack on
+ * success (the doc's option (b): notification delivered, tracked elsewhere),
+ * then release the lane. Legacy run+ack flow when the ledger is unavailable.
+ */
+export declare function consumeTypedDispatch(host: LaneFlowHost, ref: {
+    dispatchEventId?: string;
+    sourceType?: string;
+    sourceId?: string;
+}, run: (dispatchEventId?: string) => Promise<boolean>, ack: (dispatchEventId?: string) => void): Promise<void>;
+/**
+ * Shared consumption of a message WorkItem referenced by id — the ONE
+ * protocol for dispatch catch-up pages and post-complete re-drive hints
+ * (live first delivery stays on the message.new handler, which already has
+ * the payload). Owns: in-memory dedupe, source fetch (deleted source ⇒
+ * administrative ack), self-sender ack, decision routing, ledger-vs-legacy
+ * ack parity, and dedupe-entry cleanup on every non-dispatched path.
+ */
+export declare function consumeMessageWorkItem(host: LaneFlowHost, item: {
+    id: string;
+    source_id: string;
+    chat_id: string;
+}): Promise<void>;
+//# sourceMappingURL=gateway-lane-flow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-lane-flow.d.ts","sourceRoot":"","sources":["../src/gateway-lane-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY,CAAC;QACrB,GAAG,CAAC,EAAE,aAAa,CAAC;QACpB,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3B,eAAe,EAAE,eAAe,CAAC;QACjC,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAC5C,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,WAAW,CACT,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,WAAW,EAAE,EAC7B,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,4BAA4B,CAC1B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACpC,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE;IACJ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,OAAO,CAAC;CAC7B,GACA,OAAO,CAAC,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC,CA6DhD;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACzE,GAAG,EAAE,CAAC,eAAe,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACnD,GAAG,EAAE,CAAC,eAAe,CAAC,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,IAAI,CAAC,CAuDf"}

package/dist/gateway-lane-flow.js

@@ -0,0 +1,167 @@
+import { LedgerUnsupportedError } from './lane-ledger.js';
+/**
+ * Dispatch one group of same-lane message events under the ledger contract:
+ * claim (or reuse) the lane, run the dispatch, then complete when no local
+ * work remains for the lane. No legacy received/ack calls — the claim marks
+ * members received and complete/reply resolve them server-side.
+ */
+export async function dispatchLaneGroup(host, opts) {
+    const ledger = host.laneLedger;
+    const event = opts.events[opts.events.length - 1];
+    let lane;
+    try {
+        lane = await ledger.ensureLane(opts.events);
+    }
+    catch (err) {
+        if (!(err instanceof LedgerUnsupportedError))
+            throw err;
+        // Old server: run this group through the legacy flow inline and let
+        // every later event take the legacy branch via the sticky flag.
+        host.disableLedger('claim endpoint missing');
+        await host.emitDispatchReceived(event);
+        const dispatched = await host.runDispatch(event, opts.sessionKey, opts.body, opts.earlier, opts.captureText);
+        if (!dispatched)
+            return 'shutdown';
+        for (const ev of opts.events) {
+            host.opts.client
+                .ackDispatch(host.opts.config.org_id, {
+                source_type: ev.ackSourceType ?? 'message',
+                source_id: ev.ackSourceId ?? ev.messageId,
+            })
+                .catch(() => { });
+        }
+        return 'dispatched';
+    }
+    if (!lane) {
+        // A healthy incumbent owns the resource. Free the in-memory dedupe
+        // entries so the post-complete re-drive can re-trigger these messages.
+        for (const ev of opts.events) {
+            host.dispatchedMessages.delete(ev.messageId);
+        }
+        return 'foreign';
+    }
+    let dispatched = false;
+    try {
+        dispatched = await host.runDispatch(event, opts.sessionKey, opts.body, opts.earlier, opts.captureText);
+    }
+    catch (err) {
+        // Failed turn: hand the members back so the retry (this pod or the
+        // next) re-claims immediately instead of waiting out the lease.
+        await ledger.release(lane.laneKey).catch(() => { });
+        throw err;
+    }
+    if (!dispatched) {
+        // Shutdown short-circuit — shutdown() releases all active lanes.
+        return 'shutdown';
+    }
+    const pendingInjections = host.opts.dispatchAdapter.hasPendingInjections?.(opts.sessionKey) ?? false;
+    await ledger.completeIfIdle(lane.laneKey, pendingInjections || opts.hasMoreLocal());
+    return 'dispatched';
+}
+/**
+ * Consume one typed dispatch (task/comment/schedule/trigger/approval) under
+ * its typed-lane occupancy guard: claim the dsp:<id> lane (skip when another
+ * pod holds it or the WorkItem is already resolved), run the handler, ack on
+ * success (the doc's option (b): notification delivered, tracked elsewhere),
+ * then release the lane. Legacy run+ack flow when the ledger is unavailable.
+ */
+export async function consumeTypedDispatch(host, ref, run, ack) {
+    if (!host.laneLedger || host.ledgerDisabled) {
+        if (await run(ref.dispatchEventId))
+            ack(ref.dispatchEventId);
+        return;
+    }
+    let lane;
+    try {
+        lane = await host.laneLedger.claimTyped(ref);
+    }
+    catch (err) {
+        if (err instanceof LedgerUnsupportedError) {
+            host.disableLedger('claim endpoint missing');
+            if (await run(ref.dispatchEventId))
+                ack(ref.dispatchEventId);
+            return;
+        }
+        throw err;
+    }
+    if (!lane) {
+        host.opts.log?.info(`typed dispatch ${ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`} not claimable (held elsewhere or already resolved) — skipping`);
+        return;
+    }
+    try {
+        if (await run(lane.typedDispatchEventId))
+            ack(lane.typedDispatchEventId);
+    }
+    finally {
+        // Release the occupancy row. A buffered dispatch may outlive this guard
+        // (lane TTL) — acceptable at-least-once; the ledger's resolution paths
+        // still dedupe the persistent side effects.
+        await host.laneLedger.completeIfIdle(lane.laneKey, false).catch(() => { });
+    }
+}
+/**
+ * Shared consumption of a message WorkItem referenced by id — the ONE
+ * protocol for dispatch catch-up pages and post-complete re-drive hints
+ * (live first delivery stays on the message.new handler, which already has
+ * the payload). Owns: in-memory dedupe, source fetch (deleted source ⇒
+ * administrative ack), self-sender ack, decision routing, ledger-vs-legacy
+ * ack parity, and dedupe-entry cleanup on every non-dispatched path.
+ */
+export async function consumeMessageWorkItem(host, item) {
+    if (host.shuttingDown)
+        return;
+    if (!host.tryClaimMessage(item.source_id))
+        return;
+    const ackItem = () => {
+        host.opts.client.ackDispatchByID(host.opts.config.org_id, item.id).catch(() => { });
+    };
+    let msg = null;
+    try {
+        msg = await host.opts.client.getMessage(item.source_id);
+    }
+    catch (err) {
+        const status = err?.status;
+        if (status !== 404) {
+            host.opts.log?.warn(`message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`);
+            host.dispatchedMessages.delete(item.source_id);
+            return;
+        }
+    }
+    if (!msg || msg.sender_id === host.opts.agentUserId) {
+        host.dispatchedMessages.delete(item.source_id);
+        ackItem();
+        return;
+    }
+    const decision = await host.buildMessageDispatchDecision(item.chat_id, msg);
+    if (decision.action === 'retry') {
+        host.dispatchedMessages.delete(item.source_id);
+        return;
+    }
+    if (decision.action === 'skip') {
+        host.dispatchedMessages.delete(item.source_id);
+        ackItem();
+        return;
+    }
+    decision.event.dispatchEventId = item.id;
+    const laneResolved = host.usesLaneLedger(decision.event);
+    try {
+        const dispatched = await host.handleInboundEvent(decision.event);
+        if (dispatched) {
+            // Ledger runs resolve server-side (reply cover / no_action sweep);
+            // when the ledger is not in effect the WorkItem still needs the
+            // legacy administrative ack — without it the row would sit pending
+            // forever on this path while catch-up would have acked it.
+            if (!laneResolved)
+                ackItem();
+        }
+        else {
+            host.dispatchedMessages.delete(item.source_id);
+        }
+    }
+    catch (err) {
+        // Free the dedupe entry so a later re-drive / catch-up can retry —
+        // same cleanup contract as the other inbound handlers.
+        host.dispatchedMessages.delete(item.source_id);
+        throw err;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './provider-config.js';
 export * from './types.js';
+export * from './lane-key.js';
+export type { LaneFlowHost } from './gateway-lane-flow.js';
 export * from './session-state.js';
 export * from './routing.js';
 export * from './event-format.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,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,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,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,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

@@ -1,5 +1,6 @@
 export * from './provider-config.js';
 export * from './types.js';
+export * from './lane-key.js';
 export * from './session-state.js';
 export * from './routing.js';
 export * from './event-format.js';

package/dist/lane-key.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical lane-key encoding — the SSOT shared by the bridge (writer of
+ * `$PRLL_CONTEXT_DIR/<lane-key>.json`) and the CLI (reader, keyed by the send
+ * target). Both sides MUST use this exact function: the lane key encodes the
+ * full lane identity `(target_uri, thread_root_id)` so a channel lane and a
+ * thread lane in the same chat never collide, and base64url keeps any
+ * target_uri (including typed `dsp:<id>` resources) filesystem-safe with no
+ * escaping ambiguity.
+ */
+export declare function laneKeyForTarget(targetUri: string, threadRootId?: string | null): string;
+/**
+ * PRLL_CONTEXT_DIR root under a per-agent stateDir. Owned here alongside the
+ * lane-key encoding so the whole context-dir contract has one home; runtime
+ * bridges import this instead of re-declaring the path.
+ */
+export declare function dispatchLaneContextDir(stateDir: string): string;
+/** Path of the bridge-owned dispatch context file for a lane. */
+export declare function laneContextFilePath(contextDir: string, targetUri: string, threadRootId?: string | null): string;
+/**
+ * Path of the CLI-owned reply-state sidecar for a lane. Separate file from the
+ * bridge-owned context (two writers, two files): the bridge rewrites the
+ * context file throughout the turn (step_id updates) and would clobber any
+ * CLI state stored inline.
+ */
+export declare function laneReplyStateFilePath(contextDir: string, targetUri: string, threadRootId?: string | null): string;
+/** Shape of the bridge-written per-lane dispatch context file. */
+export type LaneDispatchContextFile = {
+    session_id: string | null;
+    step_id: string | null;
+    chat_id: string | null;
+    trigger_message_id: string | null;
+    no_reply: boolean;
+    /** WorkItem id of the trigger — basis of the `reply:<dsp>` effect key. */
+    dispatch_event_id: string | null;
+    /** Server-minted per-turn lane token; every dispatch-bound write carries it. */
+    lane: string | null;
+    target_uri: string | null;
+    thread_root_id: string | null;
+};
+/** Shape of the CLI-written reply-state sidecar. */
+export type LaneReplyStateFile = {
+    dispatch_event_id: string;
+    reply_committed: boolean;
+};
+//# sourceMappingURL=lane-key.d.ts.map

package/dist/lane-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane-key.d.ts","sourceRoot":"","sources":["../src/lane-key.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAExF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3B,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3B,MAAM,CAER;AAED,kEAAkE;AAClE,MAAM,MAAM,uBAAuB,GAAG;IACpC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gFAAgF;IAChF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,oDAAoD;AACpD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC"}

package/dist/lane-key.js

@@ -0,0 +1,34 @@
+import * as path from 'node:path';
+/**
+ * Canonical lane-key encoding — the SSOT shared by the bridge (writer of
+ * `$PRLL_CONTEXT_DIR/<lane-key>.json`) and the CLI (reader, keyed by the send
+ * target). Both sides MUST use this exact function: the lane key encodes the
+ * full lane identity `(target_uri, thread_root_id)` so a channel lane and a
+ * thread lane in the same chat never collide, and base64url keeps any
+ * target_uri (including typed `dsp:<id>` resources) filesystem-safe with no
+ * escaping ambiguity.
+ */
+export function laneKeyForTarget(targetUri, threadRootId) {
+    return Buffer.from(`${targetUri}\n${threadRootId ?? ''}`, 'utf8').toString('base64url');
+}
+/**
+ * PRLL_CONTEXT_DIR root under a per-agent stateDir. Owned here alongside the
+ * lane-key encoding so the whole context-dir contract has one home; runtime
+ * bridges import this instead of re-declaring the path.
+ */
+export function dispatchLaneContextDir(stateDir) {
+    return path.join(stateDir, 'dispatch-lane-context');
+}
+/** Path of the bridge-owned dispatch context file for a lane. */
+export function laneContextFilePath(contextDir, targetUri, threadRootId) {
+    return path.join(contextDir, `${laneKeyForTarget(targetUri, threadRootId)}.json`);
+}
+/**
+ * Path of the CLI-owned reply-state sidecar for a lane. Separate file from the
+ * bridge-owned context (two writers, two files): the bridge rewrites the
+ * context file throughout the turn (step_id updates) and would clobber any
+ * CLI state stored inline.
+ */
+export function laneReplyStateFilePath(contextDir, targetUri, threadRootId) {
+    return path.join(contextDir, `${laneKeyForTarget(targetUri, threadRootId)}.reply-state.json`);
+}

package/dist/lane-ledger.d.ts

@@ -0,0 +1,112 @@
+import type { ParallClient } from '@parall/sdk';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import type { ParallEvent } from './types.js';
+/** One claimed lane the bridge currently occupies. */
+export type ActiveLane = {
+    laneKey: string;
+    lane: string;
+    targetUri: string;
+    threadRootId?: string;
+    /** source_id (message id) → WorkItem id for members folded into this lane. */
+    folded: Map<string, string>;
+    /** WorkItem id, set for typed lanes (resource = dsp:<id>, single member). */
+    typedDispatchEventId?: string;
+    /** Lease expiry (ms epoch) and TTL from the claim — renewal pacing state. */
+    leaseUntilMs?: number;
+    leaseTtlMs?: number;
+};
+/**
+ * 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 declare class LedgerUnsupportedError extends Error {
+}
+export type LaneGroupOutcome = 'claimed' | 'foreign';
+/**
+ * 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 declare class LaneLedger {
+    private readonly opts;
+    private readonly lanes;
+    constructor(opts: {
+        client: ParallClient;
+        orgId: string;
+        contextDir: string;
+        log?: GatewayLogger;
+    });
+    get contextDir(): string;
+    /** Only chat message events ride the lane ledger; typed events stay on the legacy ack path. */
+    handles(event: ParallEvent): boolean;
+    laneKeyFor(event: ParallEvent): string;
+    getForEvent(event: ParallEvent): ActiveLane | undefined;
+    laneContextPath(lane: ActiveLane): string;
+    /**
+     * 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.
+     */
+    ensureLane(events: ParallEvent[]): Promise<ActiveLane | null>;
+    /**
+     * 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.
+     */
+    steerLive(event: ParallEvent): Promise<boolean>;
+    /**
+     * 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.
+     */
+    completeIfIdle(laneKey: string, hasMoreLocal: boolean): Promise<void>;
+    /**
+     * 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: ActiveLane): void;
+    /**
+     * 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.
+     */
+    release(laneKey: string): Promise<void>;
+    releaseAll(): Promise<void>;
+    /** True when any lane is currently active (used by shutdown logging). */
+    get activeCount(): number;
+    /**
+     * 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.
+     */
+    claimTyped(ref: {
+        dispatchEventId?: string;
+        sourceType?: string;
+        sourceId?: string;
+    }): Promise<ActiveLane | null>;
+    /**
+     * 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.
+     */
+    private removeLaneContext;
+}
+//# sourceMappingURL=lane-ledger.d.ts.map

package/dist/lane-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane-ledger.d.ts","sourceRoot":"","sources":["../src/lane-ledger.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,sDAAsD;AACtD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;CAAG;AAEpD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAAC;AAqBrD;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;gBAGpC,IAAI,EAAE;QACrB,MAAM,EAAE,YAAY,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,aAAa,CAAC;KACrB;IAGH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,+FAA+F;IAC/F,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAIpC,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM;IAOtC,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS;IAIvD,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAIzC;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA4EnE;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BrD;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B3E;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IA6BlC;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,yEAAyE;IACzE,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;OAKG;IACG,UAAU,CAAC,GAAG,EAAE;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA8B9B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;CAW1B"}