@alignfirst/service-openclaw-plugin 0.3.1

package/dist/thread-handoff/receipts.js

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import { readSourceContext } from "./routing.js";
+import { asRecord, nonempty } from "./values.js";
+const RECEIPT_TTL_MS = 60 * 60 * 1_000;
+const CONTEXT_LIMIT = 10_000;
+const RECEIPT_WAIT_MS = 1_000;
+const RECEIPT_POLL_MS = 25;
+export function createReceiptCoordinator(params) {
+    const now = params.now ?? Date.now;
+    const contexts = new Map();
+    const observationErrors = new Map();
+    return {
+        captureContext(context) {
+            const source = readSourceContext(context, params.configuration);
+            if (!source)
+                return;
+            contexts.set(contextKey(source.sessionKey, source.sessionId), { source, capturedAt: now() });
+            pruneContexts(contexts, now());
+        },
+        observe(event, context) {
+            const source = readCachedSource(contexts, context, now());
+            if (!source || event.toolName !== "message" || event.error !== undefined)
+                return;
+            const surface = params.configuration.channelSurfaces[source.channelId];
+            const receipt = parseDeliveryReceipt({
+                event,
+                source,
+                surface,
+                now: now(),
+            });
+            if (!receipt)
+                return;
+            if (typeof receipt === "string") {
+                const threadId = readObservedThreadId(event, surface);
+                params.logger.debug?.(`thread-handoff receipt rejected: surface=${surface} session=${source.sessionKey} thread=${threadId ?? "-"} reason=${receipt}`);
+                return;
+            }
+            const key = lookupKey(receipt.sessionKey, receipt.sessionId, receipt.threadId);
+            try {
+                params.getStore().insertReceipt(receipt, now());
+                observationErrors.delete(key);
+            }
+            catch (error) {
+                const storedError = error instanceof Error ? error : new Error(String(error));
+                observationErrors.set(key, storedError);
+                params.logger.error(`thread-handoff receipt persistence failed: ${storedError.message}`);
+            }
+        },
+        async waitForReceipt(identity) {
+            const key = lookupKey(identity.sourceSessionKey, identity.sourceSessionId, identity.threadId);
+            const deadline = now() + RECEIPT_WAIT_MS;
+            while (true) {
+                const error = observationErrors.get(key);
+                if (error)
+                    throw error;
+                const receipt = params.getStore().findReceipt(identity, now());
+                if (receipt || now() >= deadline)
+                    return receipt;
+                await delay(RECEIPT_POLL_MS);
+            }
+        },
+    };
+}
+function readCachedSource(contexts, context, now) {
+    const sessionKey = nonempty(context.sessionKey);
+    const sessionId = nonempty(context.sessionId);
+    if (!sessionKey || !sessionId)
+        return;
+    pruneContexts(contexts, now);
+    return contexts.get(contextKey(sessionKey, sessionId))?.source;
+}
+function pruneContexts(contexts, now) {
+    for (const [key, value] of contexts) {
+        if (value.capturedAt + RECEIPT_TTL_MS <= now)
+            contexts.delete(key);
+    }
+    while (contexts.size > CONTEXT_LIMIT) {
+        const oldest = contexts.keys().next().value;
+        if (typeof oldest !== "string")
+            return;
+        contexts.delete(oldest);
+    }
+}
+function parseDeliveryReceipt(params) {
+    if (params.surface === "slack" && params.event.params.action === "send") {
+        return parseSlackReceipt(params);
+    }
+    if (params.surface === "discord" && params.event.params.action === "thread-create") {
+        return parseDiscordReceipt(params);
+    }
+    return;
+}
+function parseSlackReceipt(params) {
+    const { event, source } = params;
+    const threadId = nonempty(event.params.threadId);
+    if (!threadId)
+        return "missingThread";
+    const starterText = readStarter(event.params);
+    if (starterText === undefined)
+        return "missingStarter";
+    const destination = readDestination(event.params);
+    const details = readResultDetails(event.result);
+    const result = asRecord(details?.result);
+    const target = asRecord(result?.target);
+    const targetKind = nonempty(target?.kind);
+    const targetId = nonempty(target?.id);
+    if (targetKind === undefined || targetId === undefined)
+        return "unsupportedResultShape";
+    if (!matchesConversation(destination, source.parentConversationId) ||
+        targetKind !== "channel" ||
+        targetId.toLowerCase() !== source.parentConversationId.toLowerCase()) {
+        return "channelMismatch";
+    }
+    const messageDelivery = asRecord(details?.messageDelivery);
+    if (nonempty(details?.deliveryStatus) !== "sent" ||
+        nonempty(messageDelivery?.status) !== "settled") {
+        return "notSent";
+    }
+    if (messageDelivery?.partialDelivery !== false)
+        return "partialDelivery";
+    const starterMessageId = nonempty(result?.messageId);
+    if (!starterMessageId)
+        return "missingMessageId";
+    const deliveryReceipt = asRecord(result?.receipt);
+    const returnedThreadId = nonempty(deliveryReceipt?.threadId);
+    if (returnedThreadId !== undefined && returnedThreadId !== threadId)
+        return "threadMismatch";
+    if (!accountMatches(event.params, source.accountId))
+        return "accountMismatch";
+    return createReceipt({
+        source,
+        threadId,
+        starterText,
+        starterMessageId,
+        toolCallId: event.toolCallId,
+        now: params.now,
+    });
+}
+function parseDiscordReceipt(params) {
+    const { event, source } = params;
+    const starterText = readStarter(event.params);
+    const destination = readDestination(event.params);
+    const anchorMessageId = nonempty(event.params.messageId);
+    const details = readResultDetails(event.result);
+    const thread = asRecord(details?.thread);
+    const threadId = nonempty(thread?.id);
+    if (!threadId)
+        return "missingThread";
+    if (starterText === undefined)
+        return "missingStarter";
+    if (!anchorMessageId)
+        return "missingMessageId";
+    const returnedParent = nonempty(thread?.parent_id) ?? nonempty(thread?.parentId);
+    if (!matchesConversation(destination, source.parentConversationId) ||
+        (returnedParent !== undefined &&
+            returnedParent.toLowerCase() !== source.parentConversationId.toLowerCase())) {
+        return "channelMismatch";
+    }
+    if (details?.ok !== true)
+        return "notSent";
+    if (details.partial === true)
+        return "partialDelivery";
+    if (!accountMatches(event.params, source.accountId))
+        return "accountMismatch";
+    return createReceipt({
+        source,
+        threadId,
+        starterText,
+        toolCallId: event.toolCallId,
+        now: params.now,
+    });
+}
+function readObservedThreadId(event, surface) {
+    if (surface === "slack")
+        return nonempty(event.params.threadId);
+    if (surface !== "discord")
+        return;
+    const details = readResultDetails(event.result);
+    const thread = asRecord(details?.thread);
+    return nonempty(thread?.id);
+}
+function createReceipt(params) {
+    const identity = JSON.stringify([
+        params.source.sessionKey,
+        params.source.sessionId,
+        params.source.channelId,
+        params.source.accountId ?? null,
+        params.source.parentConversationId,
+        params.threadId,
+        params.starterMessageId ?? null,
+        params.starterText,
+        params.toolCallId ?? null,
+    ]);
+    return {
+        schemaVersion: 1,
+        receiptKey: createHash("sha256").update(identity).digest("hex"),
+        ...params.source,
+        threadId: params.threadId,
+        ...(params.starterMessageId ? { starterMessageId: params.starterMessageId } : {}),
+        starterText: params.starterText,
+        ...(params.toolCallId ? { toolCallId: params.toolCallId } : {}),
+        createdAt: params.now,
+        expiresAt: params.now + RECEIPT_TTL_MS,
+    };
+}
+function readResultDetails(value) {
+    const result = asRecord(value);
+    return asRecord(result?.details) ?? result;
+}
+function readStarter(params) {
+    for (const key of ["message", "text", "content"]) {
+        const value = params[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            return value;
+    }
+    return;
+}
+function readDestination(params) {
+    return nonempty(params.to) ?? nonempty(params.target) ?? nonempty(params.channelId);
+}
+function matchesConversation(destination, expected) {
+    if (!destination)
+        return false;
+    const normalized = destination.replace(/^channel:/i, "");
+    return normalized.toLowerCase() === expected.toLowerCase();
+}
+function accountMatches(params, accountId) {
+    const supplied = nonempty(params.accountId);
+    return supplied === undefined || supplied === accountId;
+}
+function contextKey(sessionKey, sessionId) {
+    return `${sessionKey}\u0000${sessionId}`;
+}
+function lookupKey(sessionKey, sessionId, threadId) {
+    return `${contextKey(sessionKey, sessionId)}\u0000${threadId}`;
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/thread-handoff/routing.d.ts

@@ -0,0 +1,18 @@
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/plugin-entry";
+import type { DeliveryReceipt, DeliveryRoute, HandoffRecord, PluginConfiguration, SourceContext } from "./types.js";
+export interface ResolvedHandoffRoute {
+    routeKey: string;
+    targetSessionKey: string;
+    deliveryContext: DeliveryRoute;
+}
+export declare function readSourceContext(context: OpenClawPluginToolContext, configuration: PluginConfiguration): SourceContext | undefined;
+export declare function readConversationId(target: string | undefined): string | undefined;
+export declare function assertSupportedSource(source: SourceContext, configuration: PluginConfiguration): "slack" | "discord";
+export declare function resolveHandoffRoute(source: SourceContext, threadId: string, surface: "slack" | "discord"): ResolvedHandoffRoute;
+export declare function createHandoffRecord(params: {
+    receipt: DeliveryReceipt;
+    route: ResolvedHandoffRoute;
+    handoffId: string;
+    createdAt: number;
+}): HandoffRecord;
+export declare function evidenceMatches(record: HandoffRecord, receipt: DeliveryReceipt): boolean;

package/dist/thread-handoff/routing.js

@@ -0,0 +1,147 @@
+import { buildAgentSessionKey, isAcpSessionKey, isCronSessionKey, isSubagentSessionKey, parseAgentSessionKey, parseThreadSessionSuffix, resolveThreadSessionKeys, } from "openclaw/plugin-sdk/routing";
+import { HandoffError } from "./errors.js";
+import { nonempty } from "./values.js";
+export function readSourceContext(context, configuration) {
+    const deliveryContext = readDeliveryContext(context.deliveryContext);
+    const agentId = nonempty(context.agentId);
+    const sessionKey = nonempty(context.sessionKey);
+    const sessionId = nonempty(context.sessionId);
+    const channelId = nonempty(context.messageChannel) ?? deliveryContext?.channel;
+    const parentConversationId = nonempty(context.nativeChannelId) ?? readConversationId(deliveryContext?.to);
+    const accountId = nonempty(context.agentAccountId) ?? deliveryContext?.accountId;
+    if (!agentId || !sessionKey || !sessionId || !channelId || !parentConversationId)
+        return;
+    if (!configuration.channelSurfaces[channelId])
+        return;
+    return {
+        agentId,
+        sessionKey,
+        sessionId,
+        channelId,
+        ...(accountId ? { accountId } : {}),
+        parentConversationId,
+        ...(deliveryContext ? { deliveryContext } : {}),
+    };
+}
+export function readConversationId(target) {
+    if (!target)
+        return;
+    const thread = /^thread:([^/]+)\/.+/u.exec(target);
+    if (thread)
+        return thread[1];
+    const routed = /^(?:channel|group|dm):(.+)$/u.exec(target);
+    return routed?.[1];
+}
+function readDeliveryContext(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const channel = nonempty(Reflect.get(value, "channel"));
+    const to = nonempty(Reflect.get(value, "to"));
+    if (!channel || !to)
+        return;
+    const accountId = nonempty(Reflect.get(value, "accountId"));
+    const rawThreadId = Reflect.get(value, "threadId");
+    const threadId = typeof rawThreadId === "number" ? String(rawThreadId) : nonempty(rawThreadId);
+    return {
+        channel,
+        to,
+        ...(accountId ? { accountId } : {}),
+        ...(threadId ? { threadId } : {}),
+    };
+}
+export function assertSupportedSource(source, configuration) {
+    const surface = configuration.channelSurfaces[source.channelId];
+    if (!surface) {
+        throw new HandoffError("unsupportedContext", "This channel is not configured for handoff.");
+    }
+    if (isSubagentSessionKey(source.sessionKey) ||
+        isAcpSessionKey(source.sessionKey) ||
+        isCronSessionKey(source.sessionKey)) {
+        throw new HandoffError("unsupportedContext", "Thread handoff requires a regular channel session.");
+    }
+    const parsed = parseAgentSessionKey(source.sessionKey);
+    const thread = parseThreadSessionSuffix(source.sessionKey);
+    if (!parsed ||
+        parsed.agentId !== source.agentId.toLowerCase() ||
+        thread.threadId !== undefined ||
+        !matchesChannelRoute(parsed.rest, source.channelId, source.parentConversationId)) {
+        throw new HandoffError("unsupportedContext", "Thread handoff requires a distinct parent-channel session.");
+    }
+    return surface;
+}
+function matchesChannelRoute(rest, channelId, parentConversationId) {
+    const prefix = `${channelId.toLowerCase()}:channel:`;
+    if (!rest.startsWith(prefix))
+        return false;
+    const peerId = rest.slice(prefix.length);
+    const parent = parentConversationId.toLowerCase();
+    return peerId === parent || peerId.endsWith(`:channel:${parent}`);
+}
+export function resolveHandoffRoute(source, threadId, surface) {
+    const targetSessionKey = surface === "slack"
+        ? resolveThreadSessionKeys({ baseSessionKey: source.sessionKey, threadId }).sessionKey
+        : buildAgentSessionKey({
+            agentId: source.agentId,
+            channel: source.channelId,
+            accountId: source.accountId,
+            peer: { kind: "channel", id: threadId },
+        });
+    if (targetSessionKey === source.sessionKey) {
+        throw new HandoffError("invalidTarget", "The target must be a distinct thread session.");
+    }
+    const deliveryContext = surface === "slack"
+        ? {
+            channel: source.channelId,
+            to: `channel:${source.parentConversationId}`,
+            threadId,
+            ...(source.accountId ? { accountId: source.accountId } : {}),
+        }
+        : {
+            channel: source.channelId,
+            to: `channel:${threadId}`,
+            ...(source.accountId ? { accountId: source.accountId } : {}),
+        };
+    return {
+        routeKey: JSON.stringify([
+            source.agentId,
+            source.channelId,
+            source.accountId ?? null,
+            targetSessionKey,
+        ]),
+        targetSessionKey,
+        deliveryContext,
+    };
+}
+export function createHandoffRecord(params) {
+    return {
+        schemaVersion: 2,
+        routeKey: params.route.routeKey,
+        handoffId: params.handoffId,
+        targetSessionKey: params.route.targetSessionKey,
+        agentId: params.receipt.agentId,
+        sessionKey: params.receipt.sessionKey,
+        sessionId: params.receipt.sessionId,
+        channelId: params.receipt.channelId,
+        ...(params.receipt.accountId ? { accountId: params.receipt.accountId } : {}),
+        parentConversationId: params.receipt.parentConversationId,
+        threadId: params.receipt.threadId,
+        ...(params.receipt.starterMessageId
+            ? { starterMessageId: params.receipt.starterMessageId }
+            : {}),
+        starterText: params.receipt.starterText,
+        deliveryContext: params.route.deliveryContext,
+        createdAt: params.createdAt,
+        attemptCount: 0,
+        state: "pending",
+    };
+}
+export function evidenceMatches(record, receipt) {
+    return (record.sessionKey === receipt.sessionKey &&
+        record.sessionId === receipt.sessionId &&
+        record.channelId === receipt.channelId &&
+        record.accountId === receipt.accountId &&
+        record.parentConversationId === receipt.parentConversationId &&
+        record.threadId === receipt.threadId &&
+        record.starterMessageId === receipt.starterMessageId &&
+        record.starterText === receipt.starterText);
+}

package/dist/thread-handoff/run-ids.d.ts

@@ -0,0 +1,9 @@
+export interface RunIdCache {
+    remember(context: {
+        sessionKey?: string;
+        sessionId?: string;
+        runId?: string;
+    }): void;
+    read(sessionKey: string, sessionId: string): string | undefined;
+}
+export declare function createRunIdCache(now?: () => number): RunIdCache;

package/dist/thread-handoff/run-ids.js

@@ -0,0 +1,39 @@
+const RUN_ID_TTL_MS = 60 * 60 * 1_000;
+const RUN_ID_LIMIT = 10_000;
+export function createRunIdCache(now = Date.now) {
+    const entries = new Map();
+    return {
+        remember(context) {
+            if (context.sessionKey === undefined ||
+                context.sessionId === undefined ||
+                context.runId === undefined) {
+                return;
+            }
+            entries.set(contextKey(context.sessionKey, context.sessionId), {
+                runId: context.runId,
+                capturedAt: now(),
+            });
+            pruneEntries(entries, now());
+        },
+        read(sessionKey, sessionId) {
+            const capturedAt = now();
+            pruneEntries(entries, capturedAt);
+            return entries.get(contextKey(sessionKey, sessionId))?.runId;
+        },
+    };
+}
+function pruneEntries(entries, now) {
+    for (const [key, value] of entries) {
+        if (value.capturedAt + RUN_ID_TTL_MS <= now)
+            entries.delete(key);
+    }
+    while (entries.size > RUN_ID_LIMIT) {
+        const oldest = entries.keys().next().value;
+        if (typeof oldest !== "string")
+            return;
+        entries.delete(oldest);
+    }
+}
+function contextKey(sessionKey, sessionId) {
+    return `${sessionKey}\u0000${sessionId}`;
+}

package/dist/thread-handoff/service.d.ts

@@ -0,0 +1,21 @@
+import type { OpenClawPluginApi, PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+import type { HandoffStore } from "./state.js";
+import type { HandoffRecord, PluginConfiguration } from "./types.js";
+export declare const MAX_ATTEMPTS = 10;
+export declare const ATTEMPT_SPACING_MS = 60000;
+export interface HandoffService {
+    startTurn(record: HandoffRecord): Promise<void>;
+    runForTarget<T>(targetSessionKey: string, operation: () => Promise<T>): Promise<T>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface HandoffServiceParams {
+    runtime: OpenClawPluginApi["runtime"];
+    configuration: PluginConfiguration;
+    getStore: () => HandoffStore;
+    logger: PluginLogger;
+    now?: () => number;
+    scanIntervalMs?: number;
+    attemptSpacingMs?: number;
+}
+export declare function createHandoffService(params: HandoffServiceParams): HandoffService;

package/dist/thread-handoff/service.js

@@ -0,0 +1,159 @@
+import { AsyncResource } from "node:async_hooks";
+import { dispatchTurn } from "./dispatch.js";
+import { errorMessage } from "./values.js";
+export const MAX_ATTEMPTS = 10;
+export const ATTEMPT_SPACING_MS = 60_000;
+const SCAN_INTERVAL_MS = 30_000;
+export function createHandoffService(params) {
+    const now = params.now ?? Date.now;
+    const scanIntervalMs = params.scanIntervalMs ?? SCAN_INTERVAL_MS;
+    const attemptSpacingMs = params.attemptSpacingMs ?? ATTEMPT_SPACING_MS;
+    const dispatchResource = new AsyncResource("alignfirst.thread-handoff.dispatch");
+    const targetWork = new Map();
+    const inFlight = new Map();
+    let timer;
+    let scan;
+    let stopped = true;
+    // The host closes the store once `stop()` resolves. A dispatch that settles afterwards must not
+    // call `getStore()`, which would reopen the database and leak the connection.
+    let storeReleased = false;
+    const service = {
+        async startTurn(record) {
+            if (inFlight.has(record.handoffId))
+                return;
+            const starting = Promise.resolve();
+            inFlight.set(record.handoffId, starting);
+            try {
+                const updated = params.getStore().recordAttempt(record.routeKey, now());
+                if (updated?.state !== "pending")
+                    return;
+                const surface = params.configuration.channelSurfaces[updated.channelId];
+                const turn = surface
+                    ? dispatchResource.runInAsyncScope(() => dispatchTurn({
+                        runtime: params.runtime,
+                        logger: params.logger,
+                        request: buildSeedRequest(updated, surface),
+                    }))
+                    : Promise.reject(new Error(`Channel ${updated.channelId} is not configured for handoff.`));
+                const completion = finishAttempt(params, updated, turn, now, () => storeReleased)
+                    .finally(() => {
+                    if (inFlight.get(updated.handoffId) === completion) {
+                        inFlight.delete(updated.handoffId);
+                    }
+                })
+                    .catch((error) => {
+                    reportCompletionFailure(params.logger, updated.handoffId, error);
+                });
+                inFlight.set(updated.handoffId, completion);
+            }
+            finally {
+                if (inFlight.get(record.handoffId) === starting)
+                    inFlight.delete(record.handoffId);
+            }
+        },
+        runForTarget: (targetSessionKey, operation) => serializeTarget(targetWork, targetSessionKey, operation),
+        async start() {
+            if (!stopped)
+                return;
+            stopped = false;
+            storeReleased = false;
+            params.getStore();
+            await recoverPending(service, params, inFlight, now(), attemptSpacingMs);
+            timer = setInterval(() => {
+                if (scan || stopped)
+                    return;
+                scan = recoverPending(service, params, inFlight, now(), attemptSpacingMs)
+                    .catch((error) => params.logger.error(`thread-handoff recovery failed: ${errorMessage(error)}`))
+                    .finally(() => {
+                    scan = undefined;
+                });
+            }, scanIntervalMs);
+            timer.unref();
+        },
+        async stop() {
+            stopped = true;
+            storeReleased = true;
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            await scan;
+        },
+    };
+    return service;
+}
+async function recoverPending(service, params, inFlight, now, attemptSpacingMs) {
+    const records = params.getStore().listPending({
+        now,
+        spacingMs: attemptSpacingMs,
+        maxAttempts: MAX_ATTEMPTS,
+    });
+    await Promise.all(records
+        .filter((record) => !inFlight.has(record.handoffId))
+        .map((record) => service
+        .runForTarget(record.targetSessionKey, async () => {
+        const current = params.getStore().findHandoffByRoute(record.routeKey);
+        if (current?.state !== "pending")
+            return;
+        await service.startTurn(current);
+    })
+        .catch((error) => params.logger.error(`thread-handoff recovery failed for ${record.handoffId}: ${errorMessage(error)}`))));
+}
+function buildSeedRequest(record, surface) {
+    return {
+        sessionKey: record.targetSessionKey,
+        agentId: record.agentId,
+        channelId: record.channelId,
+        surface,
+        route: record.deliveryContext,
+        parentConversationId: record.parentConversationId,
+        message: "Take over this thread.",
+        messageId: `thread-handoff:${record.handoffId}:${record.attemptCount}`,
+    };
+}
+async function finishAttempt(params, record, turn, now, storeReleased) {
+    let failure;
+    try {
+        await turn;
+    }
+    catch (error) {
+        failure = error;
+    }
+    try {
+        if (failure === undefined) {
+            params.logger.debug?.(`thread-handoff ${record.handoffId} start attempt ${record.attemptCount} completed`);
+        }
+        else {
+            params.logger.warn(`thread-handoff ${record.handoffId} start attempt ${record.attemptCount} failed: ${errorMessage(failure)}`);
+        }
+        // A stale `lastAttemptedAt` only makes the record eligible for recovery sooner after a restart.
+        if (storeReleased())
+            return;
+        const current = params.getStore().recordAttemptEnd(record.routeKey, now());
+        if (current?.state === "pending" && current.attemptCount >= MAX_ATTEMPTS) {
+            params.logger.warn(`thread-handoff ${record.handoffId} stays pending after ${current.attemptCount} start attempts; it remains claimable by the next human message in the thread; inspect it with: openclaw thread-handoff list`);
+        }
+    }
+    catch (error) {
+        reportCompletionFailure(params.logger, record.handoffId, error);
+    }
+}
+function reportCompletionFailure(logger, handoffId, error) {
+    try {
+        logger.error(`thread-handoff ${handoffId} could not finish its start attempt: ${errorMessage(error)}`);
+    }
+    catch {
+        // A detached completion chain must not reject when its final error report fails.
+    }
+}
+async function serializeTarget(work, targetSessionKey, operation) {
+    const previous = work.get(targetSessionKey) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(operation);
+    work.set(targetSessionKey, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (work.get(targetSessionKey) === current)
+            work.delete(targetSessionKey);
+    }
+}

package/dist/thread-handoff/state.d.ts

@@ -0,0 +1,42 @@
+import type { DeliveryReceipt, HandoffRecord, ReceiptIdentity } from "./types.js";
+export interface HandoffStore {
+    insertReceipt(receipt: DeliveryReceipt, now: number): void;
+    findReceipt(identity: ReceiptIdentity, now: number): DeliveryReceipt | undefined;
+    listReceipts(now: number): DeliveryReceipt[];
+    findHandoffByRoute(routeKey: string): HandoffRecord | undefined;
+    insertHandoff(record: HandoffRecord): {
+        inserted: boolean;
+        record: HandoffRecord;
+    };
+    claimHandoff(identity: ClaimIdentity, now: number): ClaimResult;
+    recordAttempt(routeKey: string, startedAt: number): HandoffRecord | undefined;
+    recordAttemptEnd(routeKey: string, endedAt: number): HandoffRecord | undefined;
+    listPending(query: PendingQuery): HandoffRecord[];
+    listHandoffs(): HandoffRecord[];
+    retireHandoff(handoffId: string, options: RetireOptions): boolean;
+    close(): void;
+}
+export interface ClaimIdentity {
+    targetSessionKey: string;
+    agentId: string;
+    sessionId: string;
+    runId?: string;
+    accountId?: string;
+    handoffId?: string;
+}
+export interface ClaimResult {
+    status: "claimed" | "alreadyClaimed" | "none";
+    record?: HandoffRecord;
+}
+/** Pending records last attempted before `now - spacingMs`, with fewer than `maxAttempts`. */
+export interface PendingQuery {
+    now: number;
+    spacingMs: number;
+    maxAttempts: number;
+}
+export interface RetireOptions {
+    /** Also retire a pending record. */
+    force: boolean;
+}
+export declare function createHandoffStore(stateDir: string): HandoffStore;
+export declare function resolveDatabasePath(stateDir: string): string;