@elizaos/ui 2.0.0-alpha.43 → 2.0.0-alpha.430

package/packages/typescript/src/utils/action-results.js

@@ -0,0 +1,169 @@
+export const MAX_PROMPTED_ACTION_RESULTS = 8;
+export const MAX_ACTION_RESULT_TEXT_CHARS = 4000;
+export const MAX_ACTION_RESULT_ERROR_CHARS = 2000;
+export const ACTION_RESULT_OVERSIZE_WARNING_TOKENS = 10000;
+export const ACTION_RESULT_TOKEN_ESTIMATE_CHARS = 4;
+export const ACTION_RESULT_FULL_OUTPUT_REFERENCE_KEYS = new Set([
+    "fullOutputPath",
+    "fullOutputFile",
+    "outputPath",
+    "outputFile",
+    "outputFilePath",
+    "stdoutPath",
+    "stdoutFile",
+    "artifactPath",
+    "resultPath",
+    "filePath",
+    "path",
+]);
+export const ACTION_RESULT_FULL_ERROR_REFERENCE_KEYS = new Set([
+    "fullErrorPath",
+    "fullErrorFile",
+    "errorPath",
+    "errorFile",
+    "stderrPath",
+    "stderrFile",
+    "logPath",
+    "logFile",
+]);
+export function estimateActionResultTokens(text) {
+    return Math.ceil(text.length / ACTION_RESULT_TOKEN_ESTIMATE_CHARS);
+}
+export function getActionResultActionName(result) {
+    const actionNameValue = result.data?.actionName;
+    return typeof actionNameValue === "string" && actionNameValue.trim()
+        ? actionNameValue.trim()
+        : "Unknown Action";
+}
+export function stringifyActionResultError(error) {
+    if (error === undefined || error === null) {
+        return undefined;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function getReferenceFromData(data, keys) {
+    if (!data) {
+        return undefined;
+    }
+    for (const key of keys) {
+        const value = data[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+export function getActionResultReference(result, field) {
+    return getReferenceFromData(result.data, field === "text"
+        ? ACTION_RESULT_FULL_OUTPUT_REFERENCE_KEYS
+        : ACTION_RESULT_FULL_ERROR_REFERENCE_KEYS);
+}
+export function truncateMiddle(text, maxChars, reference) {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars) {
+        return trimmed;
+    }
+    let marker = "\n\n[... chars omitted ...]\n\n";
+    let available = Math.max(0, maxChars - marker.length);
+    let headChars = Math.ceil(available / 2);
+    let tailChars = Math.floor(available / 2);
+    const omittedChars = Math.max(0, trimmed.length - headChars - tailChars);
+    marker = `\n\n[... ${omittedChars} chars omitted ...]\n\n`;
+    available = Math.max(0, maxChars - marker.length);
+    headChars = Math.ceil(available / 2);
+    tailChars = Math.floor(available / 2);
+    const rendered = `${trimmed.slice(0, headChars)}${marker}${trimmed.slice(trimmed.length - tailChars)}`;
+    return reference ? `${rendered}\n\nFull output: ${reference}` : rendered;
+}
+export function collectActionResultSizeWarnings(result, thresholdTokens = ACTION_RESULT_OVERSIZE_WARNING_TOKENS) {
+    const actionName = getActionResultActionName(result);
+    const fields = [
+        { field: "text", text: result.text },
+        { field: "error", text: stringifyActionResultError(result.error) },
+    ];
+    return fields.flatMap(({ field, text }) => {
+        if (!text) {
+            return [];
+        }
+        const estimatedTokens = estimateActionResultTokens(text);
+        return estimatedTokens > thresholdTokens
+            ? [
+                {
+                    actionName,
+                    field,
+                    rawCharLength: text.length,
+                    estimatedTokens,
+                    thresholdTokens,
+                },
+            ]
+            : [];
+    });
+}
+export function trimActionResultForPromptState(result, references = {}) {
+    const textReference = references.text ?? getActionResultReference(result, "text");
+    const errorReference = references.error ?? getActionResultReference(result, "error");
+    const data = { ...(result.data ?? {}) };
+    if (textReference) {
+        data.fullOutputPath = textReference;
+    }
+    if (errorReference) {
+        data.fullErrorPath = errorReference;
+    }
+    const text = typeof result.text === "string"
+        ? truncateMiddle(result.text, MAX_ACTION_RESULT_TEXT_CHARS, textReference)
+        : result.text;
+    const errorText = stringifyActionResultError(result.error);
+    const error = errorText === undefined
+        ? result.error
+        : truncateMiddle(errorText, MAX_ACTION_RESULT_ERROR_CHARS, errorReference);
+    return {
+        ...result,
+        ...(text !== undefined ? { text } : {}),
+        ...(error !== undefined ? { error } : {}),
+        data,
+    };
+}
+export function formatActionResultsForPrompt(actionResults, options = {}) {
+    const { header = "# Current Chain Action Results", maxResults = MAX_PROMPTED_ACTION_RESULTS, preserveAbsoluteIndex = true, } = options;
+    if (actionResults.length === 0) {
+        return "No action results available.";
+    }
+    const rendered = actionResults.length > maxResults
+        ? actionResults.slice(-maxResults)
+        : actionResults;
+    const truncatedCount = actionResults.length - rendered.length;
+    const omittedNote = truncatedCount > 0
+        ? [`(${truncatedCount} earlier action result(s) omitted.)`]
+        : [];
+    return [
+        header,
+        ...omittedNote,
+        ...rendered.map((result, index) => {
+            const displayIndex = preserveAbsoluteIndex
+                ? truncatedCount + index + 1
+                : index + 1;
+            const status = result.success === false ? "failed" : "succeeded";
+            const lines = [
+                `${displayIndex}. ${getActionResultActionName(result)} - ${status}`,
+            ];
+            if (typeof result.text === "string" && result.text.trim()) {
+                lines.push(`Output: ${result.text.trim()}`);
+            }
+            const errorText = stringifyActionResultError(result.error);
+            if (errorText) {
+                lines.push(`Error: ${errorText}`);
+            }
+            const outputReference = getActionResultReference(result, "text");
+            if (outputReference &&
+                !lines.some((line) => line.includes(outputReference))) {
+                lines.push(`Full output: ${outputReference}`);
+            }
+            const errorReference = getActionResultReference(result, "error");
+            if (errorReference &&
+                !lines.some((line) => line.includes(errorReference))) {
+                lines.push(`Full error: ${errorReference}`);
+            }
+            return lines.join("\n");
+        }),
+    ].join("\n\n");
+}

package/packages/typescript/src/utils/batch-queue/batch-processor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stateless execution of a **batch** of work items: each item runs through `process` with a
+ * {@link Semaphore} cap, exponential backoff between attempts, and optional `onExhausted`.
+ *
+ * **Why not push failed items back onto a queue:** Inline retries keep item lifecycle simple and
+ * avoid losing work between ticks; releasing the semaphore between attempts lets other items run.
+ *
+ * Reuses `resolveRetryConfig` / `computeBackoff` from `utils/retry.ts` so delay policy matches
+ * the rest of the runtime.
+ */
+import { type RetryConfig } from "../retry.js";
+export interface BatchItemOutcome<T> {
+    item: T;
+    success: boolean;
+    error?: Error;
+    retryCount: number;
+}
+export interface BatchProcessorOptions<T> {
+    /** Max concurrent `process` calls across the batch. */
+    maxParallel: number;
+    /**
+     * After a failed attempt, re-try up to this many times (embedding-style).
+     * Total attempts = maxRetriesAfterFailure + 1. Default 3 → 4 total tries.
+     *
+     * **Interaction with per-item `_batchMaxAttempts`:** If the item is an object with numeric
+     * `_batchMaxAttempts`, that value is used as total attempts (unless `maxAttemptsCap` applies).
+     */
+    maxRetriesAfterFailure?: number;
+    retryPolicy?: RetryConfig;
+    /**
+     * Upper bound on attempts per item after resolving per-item `maxRetries` and global retry config.
+     * Use for shutdown-style paths where items may carry large `maxRetries` but only one try is wanted.
+     */
+    maxAttemptsCap?: number;
+    process: (item: T) => Promise<void>;
+    onExhausted?: (item: T, error: Error) => void | Promise<void>;
+    shouldRetry?: (item: T, error: Error, attempt: number) => boolean;
+}
+export declare class BatchProcessor<T> {
+    private readonly maxParallel;
+    private readonly defaultMaxAttempts;
+    private readonly maxAttemptsCap?;
+    private readonly policy;
+    private readonly process;
+    private readonly onExhausted?;
+    private readonly shouldRetry;
+    private readonly semaphore;
+    constructor(options: BatchProcessorOptions<T>);
+    processBatch(items: T[]): Promise<BatchItemOutcome<T>[]>;
+    private processOne;
+}
+//# sourceMappingURL=batch-processor.d.ts.map

package/packages/typescript/src/utils/batch-queue/batch-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-processor.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/utils/batch-queue/batch-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAGN,KAAK,WAAW,EAGhB,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACvC,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAClE;AA4CD,qBAAa,cAAc,CAAC,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAGH;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAIf;IACb,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAuBvC,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;YAIhD,UAAU;CAsDxB"}

package/packages/typescript/src/utils/batch-queue/batch-processor.js

@@ -0,0 +1,126 @@
+/**
+ * Stateless execution of a **batch** of work items: each item runs through `process` with a
+ * {@link Semaphore} cap, exponential backoff between attempts, and optional `onExhausted`.
+ *
+ * **Why not push failed items back onto a queue:** Inline retries keep item lifecycle simple and
+ * avoid losing work between ticks; releasing the semaphore between attempts lets other items run.
+ *
+ * Reuses `resolveRetryConfig` / `computeBackoff` from `utils/retry.ts` so delay policy matches
+ * the rest of the runtime.
+ */
+import { computeBackoff, resolveRetryConfig, sleep, } from "../retry.js";
+import { Semaphore } from "./semaphore.js";
+function defaultShouldRetry(_item, _err, _attempt) {
+    return true;
+}
+function toBackoffPolicy(resolved) {
+    return {
+        initialMs: resolved.minDelayMs,
+        maxMs: resolved.maxDelayMs,
+        factor: 2,
+        jitter: resolved.jitter,
+    };
+}
+/**
+ * Per-item attempt override via explicit `_batchMaxAttempts` property.
+ *
+ * Uses `_batchMaxAttempts` (not `maxRetries`) to avoid accidentally duck-typing payload fields
+ * that happen to carry `maxRetries` for other purposes. Items must explicitly opt-in to override
+ * the queue-level `maxRetriesAfterFailure` by setting `_batchMaxAttempts` (total attempts, not retries).
+ */
+function getPerItemMaxAttempts(item, fallback) {
+    if (item &&
+        typeof item === "object" &&
+        "_batchMaxAttempts" in item &&
+        typeof item._batchMaxAttempts ===
+            "number") {
+        const attempts = item._batchMaxAttempts;
+        if (Number.isFinite(attempts) && attempts >= 1) {
+            return attempts;
+        }
+    }
+    return fallback;
+}
+export class BatchProcessor {
+    maxParallel;
+    defaultMaxAttempts;
+    maxAttemptsCap;
+    policy;
+    process;
+    onExhausted;
+    shouldRetry;
+    semaphore;
+    constructor(options) {
+        this.maxParallel = Math.max(1, options.maxParallel);
+        // retriesAfter + 1 total attempts: first try + N failures that may retry.
+        const retriesAfter = options.maxRetriesAfterFailure ?? 3;
+        const resolved = resolveRetryConfig({
+            attempts: retriesAfter + 1,
+            minDelayMs: 300,
+            maxDelayMs: 30_000,
+            jitter: 0,
+        }, options.retryPolicy);
+        this.defaultMaxAttempts = resolved.attempts;
+        this.maxAttemptsCap = options.maxAttemptsCap;
+        // Factor 2 in toBackoffPolicy: matches classic exponential backoff between attempts.
+        this.policy = toBackoffPolicy(resolved);
+        this.process = options.process;
+        this.onExhausted = options.onExhausted;
+        this.shouldRetry = options.shouldRetry ?? defaultShouldRetry;
+        this.semaphore = new Semaphore(this.maxParallel);
+    }
+    async processBatch(items) {
+        return Promise.all(items.map((item) => this.processOne(item)));
+    }
+    async processOne(item) {
+        const resolved = getPerItemMaxAttempts(item, this.defaultMaxAttempts);
+        const maxAttempts = Math.max(1, this.maxAttemptsCap !== undefined
+            ? Math.min(resolved, this.maxAttemptsCap)
+            : resolved);
+        let retryCount = 0;
+        let lastError = new Error("unknown");
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            let exhausted = false;
+            await this.semaphore.acquire();
+            try {
+                await this.process(item);
+                return { item, success: true, retryCount };
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt >= maxAttempts ||
+                    !this.shouldRetry(item, lastError, attempt)) {
+                    exhausted = true;
+                }
+                else {
+                    retryCount++;
+                }
+            }
+            finally {
+                this.semaphore.release();
+            }
+            if (exhausted) {
+                if (this.onExhausted) {
+                    try {
+                        await this.onExhausted(item, lastError);
+                    }
+                    catch {
+                        // Keep callback failures from aborting the whole batch
+                    }
+                }
+                return {
+                    item,
+                    success: false,
+                    error: lastError,
+                    retryCount,
+                };
+            }
+            const delayMs = computeBackoff(this.policy, attempt);
+            if (delayMs > 0) {
+                await sleep(delayMs);
+            }
+        }
+        // Unreachable when maxAttempts >= 1 (loop always returns), but satisfies the compiler.
+        return { item, success: false, error: lastError, retryCount };
+    }
+}

package/packages/typescript/src/utils/batch-queue/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Composed batch pipeline: {@link PriorityQueue} (what to run next) +
+ * {@link BatchProcessor} (how to run a slice with concurrency + retries) +
+ * {@link TaskDrain} (when the task system ticks). Use {@link BatchQueue} for services that need
+ * all three; use layers alone when you only need ordering, or only batch execution, or only
+ * repeat-task CRUD.
+ *
+ * **Rationale:** avoid parallel one-off queue + drain + retry implementations as features grow;
+ * see the longer “why not just three lines?” note on the package re-export in `../batch-queue.ts`.
+ */
+import type { IAgentRuntime } from "../../types/runtime.js";
+import type { RetryConfig } from "../retry.js";
+import { type BatchItemOutcome } from "./batch-processor.js";
+import { PriorityQueue, type PriorityQueueStats, type QueuePriority } from "./priority-queue.js";
+export { type BatchItemOutcome, BatchProcessor } from "./batch-processor.js";
+export { PriorityQueue, type PriorityQueueOptions, type PriorityQueueStats, type QueuePriority, } from "./priority-queue.js";
+export { Semaphore } from "./semaphore.js";
+export { TaskDrain, type TaskDrainOptions } from "./task-drain.js";
+export interface DrainStats {
+    batchSize: number;
+    remaining: number;
+    durationMs: number;
+}
+export interface BatchQueueOptions<T> {
+    /** Task worker name and repeat task name (e.g. `EMBEDDING_DRAIN`). */
+    name: string;
+    batchSize: number;
+    drainIntervalMs: number;
+    getPriority: (item: T) => QueuePriority;
+    process: (item: T) => Promise<void>;
+    maxParallel?: number;
+    maxRetriesAfterFailure?: number;
+    retryPolicy?: RetryConfig;
+    maxSize?: number;
+    onPressure?: (queue: PriorityQueue<T>, item: T) => boolean;
+    onOverflowWarning?: (sizeAfter: number, maxSize: number) => void;
+    onExhausted?: (item: T, error: Error) => void | Promise<void>;
+    /** Called after a non-empty batch finishes `processBatch` (includes per-item success/failure). */
+    onDrainBatchOutcomes?: (outcomes: BatchItemOutcome<T>[]) => void;
+    onDrainComplete?: (stats: DrainStats) => void;
+    shouldRetry?: (item: T, error: Error, attempt: number) => boolean;
+    /**
+     * When true, skips registering the task worker and only registers the repeat task — caller must
+     * register `name` with TaskService (e.g. `BATCHER_DRAIN`). Default false.
+     */
+    skipRegisterWorker?: boolean;
+    /** Merged into repeat task metadata (e.g. `{ affinityKey: "room:x" }`). */
+    taskMetadata?: Record<string, unknown>;
+    /** Optional repeat task description in the task store. */
+    taskDescription?: string;
+    drainHighPriorityOnStop?: boolean;
+    /**
+     * When true (default), high-priority flush on {@link BatchQueue.dispose} uses {@link BatchProcessor}
+     * with `maxParallel: 1`, `maxAttemptsCap: 1`, and the same `process` / `onExhausted` / `shouldRetry`
+     * as scheduled drains — bounded concurrency and a single attempt per item (no long retry tail on stop).
+     * When false, uses a direct `process` loop (legacy best-effort; no semaphore).
+     */
+    disposeHighPriorityViaProcessor?: boolean;
+}
+/**
+ * End-to-end queue for “enqueue work, drain on a schedule, process with backpressure.”
+ *
+ * **Why `isDraining`:** Repeat tasks can fire while a drain is still running; we skip re-entry so
+ * two batches don’t process the same logical slice or overlap `process` side effects.
+ *
+ * **Why `dispose` flushes high priority optionally:** Matches embedding shutdown: best-effort
+ * completion for urgent items before deleting the repeat task and clearing the queue.
+ *
+ * **Flush path:** By default the high-priority shutdown slice runs through a dedicated
+ * {@link BatchProcessor} (serial, one attempt per item) so behavior stays aligned with bounded
+ * concurrency; set `disposeHighPriorityViaProcessor: false` only if you need the old direct loop.
+ */
+export declare class BatchQueue<T> {
+    private readonly priorityQueue;
+    private readonly batchProcessor;
+    private taskDrain;
+    private isDraining;
+    private disposed;
+    private readonly batchSize;
+    private readonly options;
+    constructor(options: BatchQueueOptions<T>);
+    enqueue(item: T): boolean;
+    /**
+     * Run one drain cycle (typically from the repeat task worker).
+     */
+    drain(): Promise<void>;
+    /** Wire `TaskDrain` (worker + repeat task unless `skipRegisterWorker`). */
+    start(runtime: IAgentRuntime): Promise<void>;
+    updateDrainInterval(runtime: IAgentRuntime, ms: number): Promise<void>;
+    dispose(runtime: IAgentRuntime, opts?: {
+        flushHighPriority?: boolean;
+    }): Promise<void>;
+    get size(): number;
+    stats(): PriorityQueueStats;
+    clear(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/packages/typescript/src/utils/batch-queue/index.d.ts.map

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

package/packages/typescript/src/utils/batch-queue/index.js

@@ -0,0 +1,175 @@
+/**
+ * Composed batch pipeline: {@link PriorityQueue} (what to run next) +
+ * {@link BatchProcessor} (how to run a slice with concurrency + retries) +
+ * {@link TaskDrain} (when the task system ticks). Use {@link BatchQueue} for services that need
+ * all three; use layers alone when you only need ordering, or only batch execution, or only
+ * repeat-task CRUD.
+ *
+ * **Rationale:** avoid parallel one-off queue + drain + retry implementations as features grow;
+ * see the longer “why not just three lines?” note on the package re-export in `../batch-queue.ts`.
+ */
+import { BatchProcessor } from "./batch-processor.js";
+import { PriorityQueue, } from "./priority-queue.js";
+import { TaskDrain } from "./task-drain.js";
+export { BatchProcessor } from "./batch-processor.js";
+export { PriorityQueue, } from "./priority-queue.js";
+export { Semaphore } from "./semaphore.js";
+export { TaskDrain } from "./task-drain.js";
+/**
+ * End-to-end queue for “enqueue work, drain on a schedule, process with backpressure.”
+ *
+ * **Why `isDraining`:** Repeat tasks can fire while a drain is still running; we skip re-entry so
+ * two batches don’t process the same logical slice or overlap `process` side effects.
+ *
+ * **Why `dispose` flushes high priority optionally:** Matches embedding shutdown: best-effort
+ * completion for urgent items before deleting the repeat task and clearing the queue.
+ *
+ * **Flush path:** By default the high-priority shutdown slice runs through a dedicated
+ * {@link BatchProcessor} (serial, one attempt per item) so behavior stays aligned with bounded
+ * concurrency; set `disposeHighPriorityViaProcessor: false` only if you need the old direct loop.
+ */
+export class BatchQueue {
+    priorityQueue;
+    batchProcessor;
+    taskDrain = null;
+    isDraining = false;
+    disposed = false;
+    batchSize;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.batchSize = Math.max(1, options.batchSize);
+        this.priorityQueue = new PriorityQueue({
+            getPriority: options.getPriority,
+            maxSize: options.maxSize,
+            onPressure: options.onPressure,
+            onOverflowWarning: options.onOverflowWarning,
+        });
+        // Default maxParallel 10: matches prior embedding batch parallelism; callers can set 1 for strict serial.
+        this.batchProcessor = new BatchProcessor({
+            maxParallel: options.maxParallel ?? 10,
+            maxRetriesAfterFailure: options.maxRetriesAfterFailure,
+            retryPolicy: options.retryPolicy,
+            process: options.process,
+            onExhausted: options.onExhausted,
+            shouldRetry: options.shouldRetry,
+        });
+    }
+    enqueue(item) {
+        if (this.disposed) {
+            return false;
+        }
+        return this.priorityQueue.enqueue(item);
+    }
+    /**
+     * Run one drain cycle (typically from the repeat task worker).
+     */
+    async drain() {
+        if (this.disposed || this.isDraining) {
+            return;
+        }
+        this.isDraining = true;
+        const started = Date.now();
+        try {
+            const batch = this.priorityQueue.dequeueBatch(this.batchSize);
+            if (batch.length === 0) {
+                return;
+            }
+            const outcomes = await this.batchProcessor.processBatch(batch);
+            try {
+                this.options.onDrainBatchOutcomes?.(outcomes);
+            }
+            catch {
+                // Keep hook failures from failing a completed batch
+            }
+            const durationMs = Date.now() - started;
+            try {
+                this.options.onDrainComplete?.({
+                    batchSize: batch.length,
+                    remaining: this.priorityQueue.size,
+                    durationMs,
+                });
+            }
+            catch {
+                // Keep hook failures from failing a completed batch
+            }
+        }
+        finally {
+            this.isDraining = false;
+        }
+    }
+    /** Wire `TaskDrain` (worker + repeat task unless `skipRegisterWorker`). */
+    async start(runtime) {
+        if (this.disposed) {
+            throw new Error(`BatchQueue "${this.options.name}" has already been disposed`);
+        }
+        if (this.taskDrain) {
+            return;
+        }
+        const skip = this.options.skipRegisterWorker ?? false;
+        this.taskDrain = new TaskDrain({
+            taskName: this.options.name,
+            description: this.options.taskDescription,
+            intervalMs: this.options.drainIntervalMs,
+            taskMetadata: this.options.taskMetadata,
+            skipRegisterWorker: skip,
+            onDrain: skip
+                ? undefined
+                : async () => {
+                    await this.drain();
+                },
+        }, this.options.drainIntervalMs);
+        await this.taskDrain.start(runtime);
+    }
+    async updateDrainInterval(runtime, ms) {
+        await this.taskDrain?.updateInterval(runtime, ms);
+    }
+    async dispose(runtime, opts) {
+        this.disposed = true;
+        const flush = opts?.flushHighPriority ?? this.options.drainHighPriorityOnStop !== false;
+        if (flush) {
+            const high = this.priorityQueue.drain((item) => this.options.getPriority(item) === "high");
+            const viaProcessor = this.options.disposeHighPriorityViaProcessor !== false;
+            if (high.length > 0) {
+                if (viaProcessor) {
+                    const flushProcessor = new BatchProcessor({
+                        maxParallel: 1,
+                        maxRetriesAfterFailure: 0,
+                        maxAttemptsCap: 1,
+                        process: this.options.process,
+                        onExhausted: this.options.onExhausted,
+                        shouldRetry: this.options.shouldRetry,
+                        retryPolicy: this.options.retryPolicy,
+                    });
+                    const flushOutcomes = await flushProcessor.processBatch(high);
+                    this.options.onDrainBatchOutcomes?.(flushOutcomes);
+                }
+                else {
+                    for (const item of high) {
+                        try {
+                            await this.options.process(item);
+                        }
+                        catch {
+                            /* best effort on shutdown */
+                        }
+                    }
+                }
+            }
+        }
+        await this.taskDrain?.dispose(runtime);
+        this.taskDrain = null;
+        this.priorityQueue.clear();
+    }
+    get size() {
+        return this.priorityQueue.size;
+    }
+    stats() {
+        return this.priorityQueue.stats();
+    }
+    clear() {
+        if (this.disposed) {
+            return;
+        }
+        this.priorityQueue.clear();
+    }
+}