@assemblyline-agents/runtime 0.1.0

package/dist/conversation-transcript.d.ts

@@ -0,0 +1,49 @@
+import type { HarnessContinuation } from "@assemblyline-agents/core";
+import { type ConversationContextHost } from "./conversation-context.js";
+import { type TranscriptPolicyOptions } from "./context-policy-util.js";
+import { type ContinuationEnvelopeSession, type RestoredHarnessSession } from "./harness-continuation.js";
+import type { CheckpointRecord, StateAdapter } from "./state.js";
+/**
+ * Conversation transcript persistence: after a successful conversation run,
+ * the final harness continuation is checkpointed under
+ * {@link TRANSCRIPT_CHECKPOINT_NAME} and a pointer (run id + last observed
+ * provider input tokens) is stamped onto the conversation's metadata. The next
+ * turn in the conversation resumes from that transcript instead of rebuilding
+ * context from flattened recent history. The pointer is an acceleration
+ * layer, never the source of truth: any load/validation failure falls back to
+ * the flattened-history path, and the durable conversation messages and
+ * `/history` projection are unchanged.
+ */
+export declare const TRANSCRIPT_CHECKPOINT_NAME = "conversation.transcript";
+export declare const TRANSCRIPT_METADATA_KEY = "transcript";
+/** Narrow host slice: `state` plus the runtime's checkpoint creator. */
+export interface ConversationTranscriptHost {
+    state: StateAdapter;
+    createCheckpoint(input: Omit<CheckpointRecord, "id" | "createdAt">): Promise<CheckpointRecord>;
+}
+export interface LoadedConversationTranscript {
+    restored: RestoredHarnessSession;
+    sourceRunId: string;
+    lastInputTokens?: number;
+}
+export declare function persistConversationTranscriptImpl(host: ConversationTranscriptHost, input: {
+    runId: string;
+    conversationId: string;
+    session: ContinuationEnvelopeSession;
+    continuation: HarnessContinuation;
+    lastInputTokens?: number;
+}): Promise<void>;
+/**
+ * Load the conversation's stored transcript, or undefined when there is none.
+ * Emits `context.transcript_fallback` on the new run for pointer/checkpoint
+ * shapes that exist but cannot be restored, so degraded turns are auditable.
+ */
+export declare function loadConversationTranscriptImpl(host: ConversationTranscriptHost, conversationId: string, runId: string): Promise<LoadedConversationTranscript | undefined>;
+/** A transcript ready for resume, with the resolved trim settings. */
+export interface ResumableConversationTranscript {
+    loaded: LoadedConversationTranscript;
+    settings: TranscriptPolicyOptions;
+}
+/** Policy-gated transcript load: resolves ContextPolicy transcript options first. */
+export declare function loadResumableConversationTranscriptImpl(contextHost: ConversationContextHost, transcriptHost: ConversationTranscriptHost, conversationId: string, runId: string): Promise<ResumableConversationTranscript | undefined>;
+//# sourceMappingURL=conversation-transcript.d.ts.map

package/dist/conversation-transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-transcript.d.ts","sourceRoot":"","sources":["../src/conversation-transcript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAc,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAwB,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC/F,OAAO,EAA2B,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACjG,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,EAC5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AACpE,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,YAAY,CAAC;IACpB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,iCAAiC,CACrD,IAAI,EAAE,0BAA0B,EAChC,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,2BAA2B,CAAC;IACrC,YAAY,EAAE,mBAAmB,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;GAIG;AACH,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,0BAA0B,EAChC,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,4BAA4B,GAAG,SAAS,CAAC,CAoBnD;AAED,sEAAsE;AACtE,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,4BAA4B,CAAC;IACrC,QAAQ,EAAE,uBAAuB,CAAC;CACnC;AAED,qFAAqF;AACrF,wBAAsB,uCAAuC,CAC3D,WAAW,EAAE,uBAAuB,EACpC,cAAc,EAAE,0BAA0B,EAC1C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,+BAA+B,GAAG,SAAS,CAAC,CAKtD"}

package/dist/conversation-transcript.js

@@ -0,0 +1,77 @@
+import { resolveContextPolicy } from "./conversation-context.js";
+import { transcriptPolicyOptions } from "./context-policy-util.js";
+import { buildHarnessContinuationEnvelope, storedHarnessContinuation } from "./harness-continuation.js";
+/**
+ * Conversation transcript persistence: after a successful conversation run,
+ * the final harness continuation is checkpointed under
+ * {@link TRANSCRIPT_CHECKPOINT_NAME} and a pointer (run id + last observed
+ * provider input tokens) is stamped onto the conversation's metadata. The next
+ * turn in the conversation resumes from that transcript instead of rebuilding
+ * context from flattened recent history. The pointer is an acceleration
+ * layer, never the source of truth: any load/validation failure falls back to
+ * the flattened-history path, and the durable conversation messages and
+ * `/history` projection are unchanged.
+ */
+export const TRANSCRIPT_CHECKPOINT_NAME = "conversation.transcript";
+export const TRANSCRIPT_METADATA_KEY = "transcript";
+export async function persistConversationTranscriptImpl(host, input) {
+    // Stores without updateConversation cannot hold the pointer; resume simply
+    // stays disabled for them and the fallback path serves every turn.
+    if (!host.state.updateConversation)
+        return;
+    const envelope = buildHarnessContinuationEnvelope(input.session, input.continuation);
+    await host.createCheckpoint({
+        runId: input.runId,
+        name: TRANSCRIPT_CHECKPOINT_NAME,
+        data: envelope
+    });
+    const pointer = { runId: input.runId };
+    if (input.lastInputTokens !== undefined)
+        pointer.lastInputTokens = input.lastInputTokens;
+    await host.state.updateConversation(input.conversationId, {
+        metadata: { [TRANSCRIPT_METADATA_KEY]: pointer }
+    });
+    await host.state.appendEvent(input.runId, "context.transcript_persisted", {
+        conversationId: input.conversationId,
+        ...(input.lastInputTokens !== undefined ? { lastInputTokens: input.lastInputTokens } : {})
+    });
+}
+/**
+ * Load the conversation's stored transcript, or undefined when there is none.
+ * Emits `context.transcript_fallback` on the new run for pointer/checkpoint
+ * shapes that exist but cannot be restored, so degraded turns are auditable.
+ */
+export async function loadConversationTranscriptImpl(host, conversationId, runId) {
+    const conversation = await host.state.getConversation(conversationId);
+    const pointer = conversation?.metadata?.[TRANSCRIPT_METADATA_KEY];
+    if (!isJsonObject(pointer) || typeof pointer.runId !== "string")
+        return undefined;
+    const checkpoints = await host.state.listCheckpoints(pointer.runId);
+    const latest = [...checkpoints].reverse().find((checkpoint) => checkpoint.name === TRANSCRIPT_CHECKPOINT_NAME);
+    const restored = storedHarnessContinuation(latest?.data);
+    if (!restored) {
+        await host.state.appendEvent(runId, "context.transcript_fallback", {
+            conversationId,
+            sourceRunId: pointer.runId,
+            reason: latest ? "invalid_envelope" : "missing_checkpoint"
+        });
+        return undefined;
+    }
+    const loaded = { restored, sourceRunId: pointer.runId };
+    if (typeof pointer.lastInputTokens === "number" && Number.isFinite(pointer.lastInputTokens)) {
+        loaded.lastInputTokens = pointer.lastInputTokens;
+    }
+    return loaded;
+}
+/** Policy-gated transcript load: resolves ContextPolicy transcript options first. */
+export async function loadResumableConversationTranscriptImpl(contextHost, transcriptHost, conversationId, runId) {
+    const settings = transcriptPolicyOptions(await resolveContextPolicy(contextHost));
+    if (!settings.resume)
+        return undefined;
+    const loaded = await loadConversationTranscriptImpl(transcriptHost, conversationId, runId);
+    return loaded ? { loaded, settings } : undefined;
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=conversation-transcript.js.map

package/dist/conversation-transcript.js.map

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

package/dist/conversation-turn-dispatch.d.ts

@@ -0,0 +1,46 @@
+import type { ChannelTurn } from "./channel.js";
+import { RunCapacityError, type SemaphoreAdmission } from "./concurrency.js";
+import type { RuntimeLogger } from "./logging.js";
+import type { RunAgentResult } from "./runtime-types.js";
+import type { ConversationTurnRecord, ResolvedStateAdapter, RunRecord } from "./state.js";
+export interface ConversationTurnDispatchHost {
+    state: ResolvedStateAdapter;
+    logger: RuntimeLogger;
+    agentScope: string;
+    maxRunDurationMs: number;
+    now(): Date;
+    agentEnabled(): Promise<boolean>;
+    admitRunOrReject(): SemaphoreAdmission | RunCapacityError;
+    runTurn(turn: ChannelTurn, admission: SemaphoreAdmission, onRunCreated: (run: RunRecord) => Promise<void>): Promise<RunAgentResult>;
+}
+export interface EnqueueConversationTurnInput {
+    turn: ChannelTurn;
+    idempotencyScope: string;
+    idempotencyKey: string;
+}
+/**
+ * Runtime-owned dispatcher for accepted channel events. It serializes turns
+ * within one logical conversation while consuming normal run capacity across
+ * different conversations.
+ */
+export declare class ConversationTurnDispatcher {
+    private readonly host;
+    private drainPromise;
+    private drainRequested;
+    constructor(host: ConversationTurnDispatchHost);
+    enqueue(input: EnqueueConversationTurnInput): Promise<{
+        inserted: boolean;
+        record: ConversationTurnRecord;
+    }>;
+    requestDrain(): void;
+    recover(): Promise<ConversationTurnRecord[]>;
+    settleRunResult(result: RunAgentResult): Promise<ConversationTurnRecord | undefined>;
+    settleRunRecord(run: RunRecord): Promise<ConversationTurnRecord | undefined>;
+    startWorker(intervalMs?: number): {
+        stop(): void;
+    };
+    private drain;
+    private execute;
+}
+export declare function conversationTurnQueueStatus(run: RunRecord): "blocked" | "completed" | "failed" | "cancelled";
+//# sourceMappingURL=conversation-turn-dispatch.d.ts.map

package/dist/conversation-turn-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-turn-dispatch.d.ts","sourceRoot":"","sources":["../src/conversation-turn-dispatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,sBAAsB,EACtB,oBAAoB,EACpB,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,oBAAoB,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,IAAI,IAAI,CAAC;IACZ,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,gBAAgB,IAAI,kBAAkB,GAAG,gBAAgB,CAAC;IAC1D,OAAO,CACL,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,kBAAkB,EAC7B,YAAY,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAC9C,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,WAAW,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB;AAkCD;;;;GAIG;AACH,qBAAa,0BAA0B;IAIzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,cAAc,CAAS;gBAEF,IAAI,EAAE,4BAA4B;IAEzD,OAAO,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,sBAAsB,CAAA;KAAE,CAAC;IAclH,YAAY,IAAI,IAAI;IASd,OAAO,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAoB5C,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAUpF,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAUlF,WAAW,CAAC,UAAU,SAAQ,GAAG;QAAE,IAAI,IAAI,IAAI,CAAA;KAAE;YAanC,KAAK;YAgCL,OAAO;CA4DtB;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAG5G"}

package/dist/conversation-turn-dispatch.js

@@ -0,0 +1,201 @@
+import { RunCapacityError } from "./concurrency.js";
+import { safeJson } from "./json-util.js";
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const PARKED_STATUSES = new Set([
+    "waiting_for_approval",
+    "waiting_for_input",
+    "waiting_for_connection",
+    "suspended"
+]);
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function queueStatusForRun(run) {
+    if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
+        return run.status;
+    }
+    return "blocked";
+}
+function channelTurnFromPayload(record) {
+    const payload = record.payload;
+    if (typeof payload.eventId !== "string" ||
+        typeof payload.channel !== "string" ||
+        typeof payload.conversationId !== "string" ||
+        typeof payload.message !== "string") {
+        throw new Error(`Conversation turn ${record.id} has an invalid persisted payload.`);
+    }
+    return payload;
+}
+/**
+ * Runtime-owned dispatcher for accepted channel events. It serializes turns
+ * within one logical conversation while consuming normal run capacity across
+ * different conversations.
+ */
+export class ConversationTurnDispatcher {
+    host;
+    drainPromise;
+    drainRequested = false;
+    constructor(host) {
+        this.host = host;
+    }
+    async enqueue(input) {
+        const queued = await this.host.state.enqueueConversationTurn({
+            agentScope: this.host.agentScope,
+            conversationId: input.turn.conversationId,
+            channel: input.turn.channel,
+            eventId: input.turn.eventId,
+            payload: safeJson(input.turn),
+            idempotencyScope: input.idempotencyScope,
+            idempotencyKey: input.idempotencyKey
+        });
+        this.requestDrain();
+        return { inserted: queued.inserted, record: queued.turn };
+    }
+    requestDrain() {
+        this.drainRequested = true;
+        if (this.drainPromise)
+            return;
+        this.drainPromise = this.drain().finally(() => {
+            this.drainPromise = undefined;
+            if (this.drainRequested)
+                this.requestDrain();
+        });
+    }
+    async recover() {
+        const recovered = await this.host.state.recoverExpiredConversationTurns(this.host.now());
+        const active = (await Promise.all([
+            this.host.state.listConversationTurns({ agentScope: this.host.agentScope, status: "running" }),
+            this.host.state.listConversationTurns({ agentScope: this.host.agentScope, status: "blocked" })
+        ])).flat().filter((turn) => turn.runId);
+        for (const turn of active) {
+            const run = await this.host.state.getRun(turn.runId);
+            if (!run || (!TERMINAL_STATUSES.has(run.status) && !PARKED_STATUSES.has(run.status)))
+                continue;
+            const settled = await this.host.state.settleConversationTurnByRunId(run.id, queueStatusForRun(run), run.terminalError ? { error: run.terminalError } : undefined);
+            if (settled)
+                recovered.push(settled);
+        }
+        this.requestDrain();
+        return recovered;
+    }
+    async settleRunResult(result) {
+        const settled = await this.host.state.settleConversationTurnByRunId(result.run.id, queueStatusForRun(result.run), result.run.terminalError ? { error: result.run.terminalError } : undefined);
+        if (settled && TERMINAL_STATUSES.has(settled.status))
+            this.requestDrain();
+        return settled;
+    }
+    async settleRunRecord(run) {
+        const settled = await this.host.state.settleConversationTurnByRunId(run.id, queueStatusForRun(run), run.terminalError ? { error: run.terminalError } : undefined);
+        if (settled && TERMINAL_STATUSES.has(settled.status))
+            this.requestDrain();
+        return settled;
+    }
+    startWorker(intervalMs = 1_000) {
+        void this.recover().catch((error) => {
+            this.host.logger.warn("conversation turn recovery failed", { error: errorMessage(error) });
+        });
+        const timer = setInterval(() => {
+            void this.recover().catch((error) => {
+                this.host.logger.warn("conversation turn recovery failed", { error: errorMessage(error) });
+            });
+        }, Math.max(100, Math.floor(intervalMs)));
+        timer.unref?.();
+        return { stop: () => clearInterval(timer) };
+    }
+    async drain() {
+        this.drainRequested = false;
+        while (true) {
+            if (!(await this.host.agentEnabled()))
+                return;
+            const admission = this.host.admitRunOrReject();
+            if (admission instanceof RunCapacityError)
+                return;
+            try {
+                await admission.ready;
+            }
+            catch (error) {
+                admission.release();
+                if (error instanceof RunCapacityError)
+                    return;
+                throw error;
+            }
+            let record;
+            try {
+                record = await this.host.state.leaseNextConversationTurn({
+                    agentScope: this.host.agentScope,
+                    leaseForMs: Math.max(5 * 60_000, this.host.maxRunDurationMs + 5 * 60_000),
+                    now: this.host.now()
+                });
+            }
+            catch (error) {
+                admission.release();
+                throw error;
+            }
+            if (!record) {
+                admission.release();
+                return;
+            }
+            void this.execute(record, admission);
+        }
+    }
+    async execute(record, admission) {
+        const leaseToken = record.leaseToken;
+        if (!leaseToken) {
+            admission.release();
+            return;
+        }
+        let runId;
+        try {
+            const turn = channelTurnFromPayload(record);
+            const result = await this.host.runTurn(turn, admission, async (run) => {
+                runId = run.id;
+                await this.host.state.attachConversationTurnRun(record.id, leaseToken, run.id);
+            });
+            await this.host.state.settleConversationTurn(record.id, leaseToken, queueStatusForRun(result.run), result.run.terminalError
+                ? { runId: result.run.id, error: result.run.terminalError }
+                : { runId: result.run.id });
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            if (runId) {
+                const attachedRunId = runId;
+                const currentRun = await this.host.state.getRun(attachedRunId).catch(() => undefined);
+                const status = currentRun ? queueStatusForRun(currentRun) : "blocked";
+                await this.host.state.settleConversationTurn(record.id, leaseToken, status, { runId: attachedRunId, error: message }).catch((settleError) => {
+                    this.host.logger.error("conversation turn settlement failed", {
+                        turnId: record.id,
+                        runId: attachedRunId,
+                        error: errorMessage(settleError)
+                    });
+                });
+            }
+            else {
+                await this.host.state.retryConversationTurn(record.id, leaseToken, message).catch((retryError) => {
+                    this.host.logger.error("conversation turn retry scheduling failed", {
+                        turnId: record.id,
+                        error: errorMessage(retryError)
+                    });
+                });
+            }
+            this.host.logger.error("conversation turn dispatch failed", {
+                turnId: record.id,
+                eventId: record.eventId,
+                conversationId: record.conversationId,
+                error: message
+            });
+        }
+        finally {
+            // `run()` owns the admission once invoked. Failures before invocation
+            // are the only path where execute still holds it.
+            if (!runId)
+                admission.release();
+            this.requestDrain();
+        }
+    }
+}
+export function conversationTurnQueueStatus(run) {
+    if (PARKED_STATUSES.has(run.status))
+        return "blocked";
+    return queueStatusForRun(run);
+}
+//# sourceMappingURL=conversation-turn-dispatch.js.map

package/dist/conversation-turn-dispatch.js.map

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

package/dist/delivery-queue.d.ts

@@ -0,0 +1,89 @@
+import type { JsonObject } from "@assemblyline-agents/core";
+import type { ChannelTurn } from "./channel.js";
+import type { DeliveryObligation, RunRecord, StateAdapter } from "./index.js";
+import type { RuntimeLogger } from "./logging.js";
+/**
+ * Durable delivery queue: lease/retry record helpers shared by the state
+ * adapters, plus the worker loop that drains deferred deliveries. Mirrors the
+ * sandbox-sync job queue so at-least-once channel delivery survives process
+ * crashes and works across replicas (postgres leases use
+ * `for update skip locked`).
+ */
+export declare const DEFAULT_DELIVERY_QUEUE_MAX_ATTEMPTS = 5;
+export type DeliveryObligationInput = Omit<DeliveryObligation, "id" | "createdAt" | "updatedAt" | "attemptCount" | "maxAttempts" | "nextAttemptAt"> & {
+    attemptCount?: number;
+    maxAttempts?: number;
+    nextAttemptAt?: string;
+};
+export type DeliveryObligationPatch = {
+    [Key in keyof Omit<DeliveryObligation, "id" | "createdAt">]?: Omit<DeliveryObligation, "id" | "createdAt">[Key] | undefined;
+};
+export interface DeliveryLeaseOptions {
+    now?: Date;
+    limit?: number;
+    leaseForMs?: number;
+}
+export interface DeliveryFailureInput {
+    error: string;
+    now?: Date;
+    retryDelayMs?: number;
+    /** Non-retryable failures go terminal regardless of remaining attempts. */
+    permanent?: boolean;
+}
+export interface DeliveryExecutionResult {
+    deliveryId: string;
+    runId: string;
+    status: "sent" | "retrying" | "failed";
+    error?: string;
+}
+export interface QueuedDeliverySendOutcome {
+    ok: boolean;
+    error?: string;
+    retryable?: boolean;
+    metadata?: JsonObject;
+}
+/** Narrow slice of the runtime the delivery worker needs. */
+export interface DeliveryQueueHost {
+    state: StateAdapter;
+    logger: RuntimeLogger;
+    now(): Date;
+    leaseMs: number;
+    batchSize: number;
+    sendQueuedDelivery(delivery: DeliveryObligation): Promise<QueuedDeliverySendOutcome>;
+    agentEnabled(): Promise<boolean>;
+}
+export declare function createDeliveryRecord(input: DeliveryObligationInput): DeliveryObligation;
+/** Fill queue defaults on rows persisted before the durable delivery queue existed. */
+export declare function normalizeDeliveryRecord(delivery: DeliveryObligation): DeliveryObligation;
+export declare function applyDeliveryPatch(current: DeliveryObligation, patch: DeliveryObligationPatch): DeliveryObligation;
+export declare function isDeliveryDue(delivery: DeliveryObligation, now: Date): boolean;
+export declare function deliveryQueueRetryDelayMs(attemptCount: number): number;
+/** Feature detection: adapters opt into the durable queue by implementing the lease methods. */
+export declare function stateSupportsDeliveryQueue(state: StateAdapter): boolean;
+/**
+ * Move a failed in-process delivery onto the durable queue instead of marking
+ * it terminally failed: status back to `pending` with exponential backoff so a
+ * delivery worker (possibly in another process, after a crash) retries it.
+ */
+export declare function deferFailedDelivery(input: {
+    state: StateAdapter;
+    delivery: DeliveryObligation;
+    runId: string;
+    error: string;
+    attempts: number;
+    maxAttempts: number;
+    now: Date;
+}): Promise<DeliveryObligation>;
+/** Recover expired leases, lease due deliveries, and attempt each send once. */
+export declare function runDueDeliveriesImpl(host: DeliveryQueueHost, options?: DeliveryLeaseOptions): Promise<DeliveryExecutionResult[]>;
+export declare function finalDeliveryIdempotencyKey(run: RunRecord, channel: string, turn?: ChannelTurn): string;
+export declare function deliveryFileName(path: string): string;
+export declare function deliveryFileContentType(path: string): string;
+export declare function startDeliveryWorkerImpl(host: DeliveryQueueHost, options: {
+    intervalMs: number;
+    batchSize?: number;
+    leaseForMs?: number;
+}): {
+    stop(): void;
+} | undefined;
+//# sourceMappingURL=delivery-queue.d.ts.map

package/dist/delivery-queue.d.ts.map

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