@dereekb/openrouter 13.37.0

package/firebase-server/src/lib/openrouter.runtask.handle.d.ts

@@ -0,0 +1,56 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterRunTask } from '@dereekb/openrouter/firebase';
+/**
+ * How a caller should proceed given a run task's current state.
+ *
+ * These three outcomes are what an async-work checkpoint needs, and they map 1:1 onto the
+ * complete / poll-again / failed branches an OpenAI `responses.retrieve(id)` call produces today — so an
+ * existing retry ladder survives the migration unchanged.
+ */
+export type OpenRouterRunTaskOutcome = 'complete' | 'queued' | 'failure' | 'missing';
+/**
+ * Classifies a run task into an outcome.
+ *
+ * `AWAITING_ASYNC_TOOLS` reports as `queued`: from the caller's side it is indistinguishable from
+ * waiting, because it is waiting — just on a tool result rather than on a sweep.
+ *
+ * @param task - The run task, or null when it does not exist.
+ * @returns The outcome.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunTaskOutcome(task: Maybe<OpenRouterRunTask>): OpenRouterRunTaskOutcome;
+/**
+ * Handlers for each outcome.
+ */
+export interface OpenRouterRunTaskResultHandlers<T> {
+    /**
+     * Called with a COMPLETE task.
+     */
+    readonly onComplete: (task: OpenRouterRunTask) => Promise<T> | T;
+    /**
+     * Called while the run is still in flight.
+     */
+    readonly onQueued: (task: OpenRouterRunTask) => Promise<T> | T;
+    /**
+     * Called when the run failed with its retry budget spent.
+     */
+    readonly onFailure: (task: OpenRouterRunTask) => Promise<T> | T;
+    /**
+     * Called when no run task exists for the key.
+     *
+     * Defaults to {@link OpenRouterRunTaskResultHandlers.onFailure} semantics via `onMissing` being
+     * required only when the caller wants to distinguish the two. A missing document is genuinely
+     * different from a failed one — it usually means the enqueue never landed — so it is worth handling.
+     */
+    readonly onMissing: () => Promise<T> | T;
+}
+/**
+ * Creates a reusable dispatcher for a fixed set of handlers.
+ *
+ * @param handlers - The per-outcome handlers.
+ * @returns A function that dispatches a run task.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function handleOpenRouterRunTaskResultFactory<T>(handlers: OpenRouterRunTaskResultHandlers<T>): (task: Maybe<OpenRouterRunTask>) => Promise<T>;

package/firebase-server/src/lib/openrouter.runtask.service.d.ts

@@ -0,0 +1,380 @@
+import { type FirebaseStorageContext } from '@dereekb/firebase';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type OpenRouterAttachedFileReference, type OpenRouterCallResult, type OpenRouterCore, type OpenRouterDeferredToolResolution, type OpenRouterFileReference, type OpenRouterInput, type OpenRouterModelConfig, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type OpenRouterRunTaskKey, type Tool } from '@dereekb/openrouter';
+import { type OpenRouterRunTask, type OpenRouterRunTaskDocument, type OpenRouterRunTaskFirestoreCollections, type OpenRouterRunTaskPendingToolCall, OpenRouterRunTaskState, type OpenRouterRunTaskUnsentToolResult } from '@dereekb/openrouter/firebase';
+import { type OpenRouterFileAttachmentMode } from './openrouter.file.attachment';
+import { type OpenRouterPromptService } from './openrouter.prompt.service';
+/**
+ * Default lease duration. A `RUNNING` task whose lease is older than this is reclaimable.
+ *
+ * Comfortably longer than any single inference plus its retries, so a healthy run is never stolen from
+ * itself, and short enough that a crashed sweep's work resumes on the next tick or two.
+ */
+export declare const DEFAULT_OPENROUTER_LEASE_DURATION: Milliseconds;
+/**
+ * Default number of attempts before a task is marked FAILED.
+ *
+ * Spent only on a failure {@link isRetryableOpenRouterError} classifies as transient; a deterministic
+ * failure reaches `FAILED` on its first attempt.
+ */
+export declare const DEFAULT_OPENROUTER_MAX_ATTEMPTS = 3;
+/**
+ * Maximum tasks one retention page may delete.
+ *
+ * A page's deletes go out as a single Firestore write batch, and a batch takes at most 500 writes.
+ */
+export declare const OPENROUTER_MAX_EXPIRED_RUN_TASK_DELETE_PAGE_SIZE = 500;
+/**
+ * Params for enqueueing a run task.
+ */
+export interface OpenRouterEnqueueRunTaskParams {
+    /**
+     * The run key, which becomes the document id.
+     *
+     * Derive it deterministically (e.g. from the owning NotificationTask's model key) so re-entering the
+     * checkpoint that enqueued the run reuses this document instead of queueing a duplicate.
+     */
+    readonly key: OpenRouterRunTaskKey;
+    /**
+     * The prompt to run.
+     */
+    readonly promptKey: OpenRouterPromptKey;
+    /**
+     * Version to pin. Omit to resolve the prompt's active version.
+     */
+    readonly version?: Maybe<OpenRouterPromptVersionNumber>;
+    /**
+     * The call input.
+     */
+    readonly input?: Maybe<OpenRouterInput>;
+    /**
+     * Files to attach, as GCS object paths. Never signed urls.
+     */
+    readonly files?: Maybe<OpenRouterFileReference[]>;
+    /**
+     * Per-run config overrides.
+     */
+    readonly configOverrides?: Maybe<OpenRouterModelConfig>;
+    /**
+     * A prior run task to continue from — its history seeds this run's `msg`.
+     *
+     * This is what replaces `previous_response_id`, which OpenRouter rejects with a 400.
+     */
+    readonly continueFrom?: Maybe<OpenRouterRunTaskKey>;
+    /**
+     * Whether an existing document for this key is reset back to QUEUED.
+     *
+     * Defaults to false — the enqueue is IDEMPOTENT, so a re-entered checkpoint does not restart a run
+     * that is already in flight or already finished.
+     */
+    readonly restart?: Maybe<boolean>;
+}
+/**
+ * Result of enqueueing a run task.
+ */
+export interface OpenRouterEnqueueRunTaskResult {
+    readonly key: OpenRouterRunTaskKey;
+    readonly document: OpenRouterRunTaskDocument;
+    /**
+     * Whether a new document was written. False when an existing run was reused.
+     */
+    readonly created: boolean;
+    readonly task: OpenRouterRunTask;
+}
+/**
+ * Params for claiming run tasks.
+ */
+export interface OpenRouterClaimRunTasksParams {
+    /**
+     * Maximum number of tasks to claim.
+     */
+    readonly limit: number;
+    /**
+     * Identifier recorded as the lease owner.
+     */
+    readonly leaseOwner: string;
+    /**
+     * Lease duration. Defaults to {@link DEFAULT_OPENROUTER_LEASE_DURATION}.
+     */
+    readonly leaseDuration?: Maybe<Milliseconds>;
+}
+/**
+ * Params for deleting the run tasks past their retention age.
+ */
+export interface OpenRouterDeleteExpiredRunTasksParams {
+    /**
+     * Maximum number of tasks to delete. Clamped to {@link OPENROUTER_MAX_EXPIRED_RUN_TASK_DELETE_PAGE_SIZE}.
+     */
+    readonly limit: number;
+    /**
+     * Tasks queued at or before this date are deleted. Defaults to `now - OPENROUTER_RUN_TASK_MAX_AGE`.
+     *
+     * A parameter rather than always-derived so a sweep can pin one cutoff across every page of a run, and
+     * so a test can assert against a fixed clock.
+     */
+    readonly before?: Maybe<Date>;
+}
+/**
+ * Result of one retention page.
+ */
+export interface OpenRouterDeleteExpiredRunTasksResult {
+    readonly deleted: number;
+    /**
+     * The keys deleted — once the document is gone this is the only record the run existed.
+     */
+    readonly keys: OpenRouterRunTaskKey[];
+}
+/**
+ * Params for resolving a deferred tool call.
+ */
+export interface OpenRouterResolveDeferredToolParams {
+    /**
+     * The run task holding the pending call.
+     */
+    readonly key: OpenRouterRunTaskKey;
+    /**
+     * The task id the pending call was registered under.
+     */
+    readonly taskId: string;
+    /**
+     * The successful output, when the task succeeded.
+     */
+    readonly output?: unknown;
+    /**
+     * The error, when it did not.
+     */
+    readonly error?: Maybe<string>;
+}
+/**
+ * Result of resolving a deferred tool call.
+ */
+export interface OpenRouterResolveDeferredToolResult {
+    /**
+     * Whether a pending call matched and was resolved.
+     *
+     * False for a replayed or already-settled resolution. That is a no-op, not an error — resolutions
+     * arrive from outside this process and can be delivered more than once.
+     */
+    readonly resolved: boolean;
+    /**
+     * Whether every pending call is now resolved, so the run is ready to continue.
+     */
+    readonly ready: boolean;
+}
+/**
+ * Result of running one task.
+ */
+export interface OpenRouterRunTaskExecutionResult {
+    readonly key: OpenRouterRunTaskKey;
+    readonly state: OpenRouterRunTaskState;
+    readonly result?: Maybe<OpenRouterCallResult>;
+    readonly error?: Maybe<unknown>;
+}
+/**
+ * Manages the app-owned run-task queue: the replacement for OpenAI's `background: true` plus its
+ * server-side job store, neither of which OpenRouter has.
+ */
+export declare abstract class OpenRouterRunTaskService {
+    /**
+     * Writes one QUEUED document and returns. Nothing blocks on inference.
+     */
+    abstract enqueueRunTask(params: OpenRouterEnqueueRunTaskParams): Promise<OpenRouterEnqueueRunTaskResult>;
+    /**
+     * Reads a run task by key.
+     */
+    abstract readRunTask(key: OpenRouterRunTaskKey): Promise<Maybe<OpenRouterRunTask>>;
+    /**
+     * Loads a run task document by key.
+     */
+    abstract runTaskDocument(key: OpenRouterRunTaskKey): OpenRouterRunTaskDocument;
+    /**
+     * Claims up to `limit` runnable tasks by lease, transactionally.
+     *
+     * Claiming in a transaction is what makes two overlapping sweeps safe: only one can move a document
+     * out of QUEUED, so a task is never executed twice.
+     */
+    abstract claimNextRunTasks(params: OpenRouterClaimRunTasksParams): Promise<OpenRouterRunTaskDocument[]>;
+    /**
+     * Executes one already-claimed task and writes its result.
+     */
+    abstract executeRunTask(document: OpenRouterRunTaskDocument): Promise<OpenRouterRunTaskExecutionResult>;
+    /**
+     * Delivers a deferred tool result from another process.
+     */
+    abstract resolveDeferredTool(params: OpenRouterResolveDeferredToolParams): Promise<OpenRouterResolveDeferredToolResult>;
+    /**
+     * Deletes one page of run tasks older than {@link OPENROUTER_RUN_TASK_MAX_AGE}, in every state.
+     */
+    abstract deleteExpiredRunTasks(params: OpenRouterDeleteExpiredRunTasksParams): Promise<OpenRouterDeleteExpiredRunTasksResult>;
+    /**
+     * Resolves the files of a task into the attachments for one attempt. Exposed for tests, which is
+     * where the "does a retry get a NEW url" question actually gets answered.
+     */
+    abstract attachFilesForAttempt(files: Maybe<OpenRouterFileReference[]>): Promise<OpenRouterAttachedFileReference[]>;
+}
+/**
+ * Notified when a run task reaches a terminal state.
+ *
+ * This is the in-process replacement for OpenAI's completion webhook: because we hold the HTTP
+ * connection during inference, the runner already knows the moment a run finishes, so it can advance
+ * the owning work directly. No inbound round-trip, nothing to authenticate, and impossible to miss.
+ *
+ * A handler MUST NOT write to the run task document. It is still invoked with `FAILED` for a task the
+ * retention sweep deleted mid-flight — correctly, since the owning NotificationTask has to learn the run
+ * is not coming — and by then there is no document left to update.
+ */
+export type OpenRouterRunTaskTerminalStateHandler = (document: OpenRouterRunTaskDocument, result: OpenRouterRunTaskExecutionResult) => Promise<void>;
+/**
+ * Config for {@link openRouterRunTaskService}.
+ */
+export interface OpenRouterRunTaskServiceConfig {
+    /**
+     * The run task collections.
+     */
+    readonly collections: OpenRouterRunTaskFirestoreCollections;
+    /**
+     * The prompt service used to resolve a run's prompt version.
+     */
+    readonly promptService: OpenRouterPromptService;
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * Storage context used to read/sign the files of a task. Required only when tasks carry files.
+     */
+    readonly storageContext?: Maybe<FirebaseStorageContext>;
+    /**
+     * Environment service that selects how files are attached: a non-production environment attaches them inline.
+     *
+     * This is the whole gate. A signed url is unreachable from OpenRouter when the object lives in the
+     * Firebase storage emulator, so an emulator run has to carry the bytes — and an app should not have
+     * to remember to say so twice.
+     */
+    readonly envService?: Maybe<FirebaseServerEnvService>;
+    /**
+     * Explicit file attachment mode, overriding whatever `envService` would select.
+     */
+    readonly fileAttachmentMode?: Maybe<OpenRouterFileAttachmentMode>;
+    /**
+     * Inline size cap. Defaults to {@link DEFAULT_OPENROUTER_MAX_INLINE_FILE_SIZE_BYTES}.
+     */
+    readonly maxInlineFileSizeBytes?: Maybe<number>;
+    /**
+     * Client-side tools available to every run. Manual (`execute: false`) tools here are what produce a
+     * deferred pause.
+     */
+    readonly tools?: Maybe<readonly Tool[]>;
+    /**
+     * Called when a run reaches a terminal state.
+     */
+    readonly onTerminalState?: Maybe<OpenRouterRunTaskTerminalStateHandler>;
+    /**
+     * Signed-url lifetime. Defaults to {@link DEFAULT_OPENROUTER_SIGNED_URL_TTL}.
+     */
+    readonly signedUrlTtl?: Maybe<Milliseconds>;
+    /**
+     * Attempts a RETRYABLE failure may spend before a task is FAILED. Defaults to
+     * {@link DEFAULT_OPENROUTER_MAX_ATTEMPTS}.
+     */
+    readonly maxAttempts?: Maybe<number>;
+    /**
+     * Default lease duration. Defaults to {@link DEFAULT_OPENROUTER_LEASE_DURATION}.
+     */
+    readonly leaseDuration?: Maybe<Milliseconds>;
+}
+/**
+ * Creates an {@link OpenRouterRunTaskService}.
+ *
+ * @param config - The collections, prompt service, client, and execution settings.
+ * @returns The service.
+ */
+export declare function openRouterRunTaskService(config: OpenRouterRunTaskServiceConfig): OpenRouterRunTaskService;
+/**
+ * Whether a task may be claimed by a sweep running at the given lease cutoff.
+ *
+ * A `RUNNING` task is claimable exactly when its lease has gone stale — that is crash recovery, and it
+ * generalises the ad-hoc "unstick anything processing for over an hour" logic it replaces.
+ *
+ * @param task - The task to check.
+ * @param leaseCutoff - Leases taken at or before this date are stale.
+ * @returns True when the task may be claimed.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isOpenRouterRunTaskClaimable(task: OpenRouterRunTask, leaseCutoff: Date): boolean;
+/**
+ * Whether any pending deferred tool call is still missing its recorded result.
+ *
+ * The one predicate behind "is this run ready to resume": the claim check, the resolution's `ready` flag,
+ * and the conversation append all ask it, and three hand-written copies had already drifted apart.
+ *
+ * @param pending - The pending deferred tool calls.
+ * @param unsent - The recorded-but-unsent tool results.
+ * @returns True when at least one pending call has no recorded result.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function hasUnresolvedOpenRouterPendingToolCalls(pending: Maybe<readonly OpenRouterRunTaskPendingToolCall[]>, unsent: Maybe<readonly OpenRouterRunTaskUnsentToolResult[]>): boolean;
+/**
+ * Extracts an error code from a thrown value.
+ *
+ * @param e - The thrown value.
+ * @returns The code, when one is discernible.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterErrorCode(e: unknown): Maybe<string>;
+/**
+ * Extracts an error message from a thrown value.
+ *
+ * @param e - The thrown value.
+ * @returns The message.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterErrorMessage(e: unknown): string;
+/**
+ * HTTP statuses a retry cannot fix.
+ *
+ * 400 is a malformed request (an invalid model id, a JSON schema the provider rejects), 401/403 are a
+ * credential problem, 402 is an empty account, and 404 is a route or resource that does not exist. Each of
+ * them answers identically on every attempt, so spending the budget on them only delays the FAILED that
+ * the owning work is waiting for.
+ */
+export declare const OPENROUTER_PERMANENT_ERROR_STATUSES: readonly number[];
+/**
+ * Whether a failure is worth another attempt.
+ *
+ * What this encodes is a whitelist of the KNOWN-PERMANENT, not a whitelist of the retryable: anything
+ * unrecognized defaults to RETRYABLE. An unknown failure is far more likely to be a transient upstream blip
+ * than a permanent one, and the attempt budget bounds the cost of being wrong either way — whereas
+ * defaulting the other way would turn one bad minute at a provider into a definitively failed run.
+ *
+ * So the retryable side needs no list of its own. 408 / 409 / 429 and every 5xx, socket-level failures
+ * (`ECONNRESET`, `ETIMEDOUT`, `ECONNREFUSED`, `EAI_AGAIN`), and the Google-infrastructure transients
+ * (`UNAVAILABLE`, `DEADLINE_EXCEEDED`, `ABORTED`) a Firestore or GCS call raises mid-run all reach the
+ * default and are retried.
+ *
+ * Permanent is two cases. {@link OPENROUTER_PERMANENT_ERROR_STATUSES}, read off `status` / `statusCode` /
+ * `code` — which covers both routes into `recordFailure`: a thrown SDK/HTTP error, and the numeric
+ * `error.code` OpenRouter reports in a response body without throwing at all. And an
+ * {@link OpenRouterPromptResolutionError}, which is deterministic by construction: the prompt either exists
+ * at that version or it never will, so re-resolving it is guaranteed to fail identically.
+ *
+ * @param e - The thrown value, or the error reported on a response.
+ * @returns True when another attempt could plausibly succeed.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isRetryableOpenRouterError(e: unknown): boolean;
+/**
+ * The deferred-tool resolutions recorded on a task, in the form the core package's resolver consumes.
+ *
+ * @param task - The run task.
+ * @returns The resolutions.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterDeferredToolResolutionsForRunTask(task: OpenRouterRunTask): OpenRouterDeferredToolResolution[];

package/firebase-server/src/lib/openrouter.runtask.sweep.d.ts

@@ -0,0 +1,170 @@
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type OpenRouterRunTaskExecutionResult, type OpenRouterRunTaskService } from './openrouter.runtask.service';
+/**
+ * Default number of tasks executed concurrently by one sweep.
+ */
+export declare const DEFAULT_OPENROUTER_SWEEP_MAX_PARALLEL_TASKS = 10;
+/**
+ * Default wall-clock budget for one sweep.
+ */
+export declare const DEFAULT_OPENROUTER_SWEEP_MAX_RUN_TIME: Milliseconds;
+/**
+ * Default number of tasks claimed per page.
+ */
+export declare const DEFAULT_OPENROUTER_SWEEP_PAGE_SIZE = 20;
+/**
+ * Default number of expired tasks deleted per retention page.
+ *
+ * Well under the 500-write batch ceiling: retention runs on its own far slower schedule, so there is
+ * nothing to gain from maximising a single page.
+ */
+export declare const DEFAULT_OPENROUTER_EXPIRATION_SWEEP_PAGE_SIZE = 200;
+/**
+ * Default wall-clock budget for one retention sweep.
+ */
+export declare const DEFAULT_OPENROUTER_EXPIRATION_SWEEP_MAX_RUN_TIME: Milliseconds;
+/**
+ * Params for {@link openRouterRunTaskSweep}.
+ */
+export interface OpenRouterRunTaskSweepParams {
+    /**
+     * The run task service to drain.
+     */
+    readonly service: OpenRouterRunTaskService;
+    /**
+     * How many tasks run concurrently. Defaults to {@link DEFAULT_OPENROUTER_SWEEP_MAX_PARALLEL_TASKS}.
+     *
+     * Throughput comes from here, not from a longer wall clock — which is what lets the sweep share a
+     * runner with other workloads.
+     */
+    readonly maxParallelTasks?: Maybe<number>;
+    /**
+     * Hard wall-clock budget. Defaults to {@link DEFAULT_OPENROUTER_SWEEP_MAX_RUN_TIME}.
+     *
+     * The sweep stops CLAIMING new pages once this is spent and returns; whatever is left stays QUEUED for
+     * the next tick. This is a requirement rather than a tuning knob when the sweep shares a scheduled
+     * runner with other work: without it, a deep queue starves every workload behind it.
+     *
+     * It bounds when a new page is claimed, NOT one inference — a single call is atomic and cannot be
+     * interrupted, so an unusually slow one can overrun. Bound that with `requestTimeoutMs` in the prompt
+     * config and keep this well inside the runner's remaining share.
+     */
+    readonly maxRunTimeMs?: Maybe<Milliseconds>;
+    /**
+     * Tasks claimed per page. Defaults to {@link DEFAULT_OPENROUTER_SWEEP_PAGE_SIZE}.
+     */
+    readonly pageSize?: Maybe<number>;
+    /**
+     * Identifier recorded as the lease owner. Defaults to a generated one.
+     */
+    readonly leaseOwner?: Maybe<string>;
+    /**
+     * Lease duration override.
+     */
+    readonly leaseDuration?: Maybe<Milliseconds>;
+    /**
+     * Maximum number of pages to claim in one sweep. Defaults to unlimited (bounded by the time budget).
+     */
+    readonly maxPages?: Maybe<number>;
+}
+/**
+ * Outcome of one sweep.
+ */
+export interface OpenRouterRunTaskSweepResult {
+    /**
+     * Number of tasks claimed and executed.
+     */
+    readonly executed: number;
+    /**
+     * How many reached each terminal or paused state.
+     */
+    readonly completed: number;
+    readonly failed: number;
+    readonly requeued: number;
+    readonly awaitingAsyncTools: number;
+    /**
+     * Number of pages claimed.
+     */
+    readonly pages: number;
+    /**
+     * Whether the sweep stopped because its time budget ran out rather than because the queue was empty.
+     *
+     * The signal that the queue is deeper than one tick can drain.
+     */
+    readonly stoppedForTimeBudget: boolean;
+    /**
+     * Elapsed wall-clock time.
+     */
+    readonly durationMs: Milliseconds;
+    /**
+     * The per-task results, in completion order.
+     */
+    readonly results: OpenRouterRunTaskExecutionResult[];
+}
+/**
+ * Drains the run-task queue within a strict time budget.
+ *
+ * Claim a page by lease, run `maxParallelTasks` at a time, write results, repeat — until the queue is
+ * empty or the budget is spent. Mount it on a schedule the app already runs; it does not need one of its
+ * own, and it must not assume it is the only tenant of the one it gets.
+ *
+ * @param params - The service and budget settings.
+ * @returns What the sweep did.
+ */
+export declare function openRouterRunTaskSweep(params: OpenRouterRunTaskSweepParams): Promise<OpenRouterRunTaskSweepResult>;
+/**
+ * Params for {@link openRouterRunTaskExpirationSweep}.
+ */
+export interface OpenRouterRunTaskExpirationSweepParams {
+    /**
+     * The run task service to delete through.
+     */
+    readonly service: OpenRouterRunTaskService;
+    /**
+     * Tasks queued at or before this date are deleted. Defaults to `now - OPENROUTER_RUN_TASK_MAX_AGE`.
+     */
+    readonly before?: Maybe<Date>;
+    /**
+     * Tasks deleted per page. Defaults to {@link DEFAULT_OPENROUTER_EXPIRATION_SWEEP_PAGE_SIZE}.
+     */
+    readonly pageSize?: Maybe<number>;
+    /**
+     * Hard wall-clock budget. Defaults to {@link DEFAULT_OPENROUTER_EXPIRATION_SWEEP_MAX_RUN_TIME}.
+     */
+    readonly maxRunTimeMs?: Maybe<Milliseconds>;
+    /**
+     * Maximum number of pages to delete in one sweep. Defaults to unlimited (bounded by the time budget).
+     */
+    readonly maxPages?: Maybe<number>;
+}
+/**
+ * Outcome of one retention sweep.
+ */
+export interface OpenRouterRunTaskExpirationSweepResult {
+    /**
+     * Number of tasks deleted.
+     */
+    readonly deleted: number;
+    /**
+     * Number of pages deleted.
+     */
+    readonly pages: number;
+    /**
+     * Whether the sweep stopped because its time budget ran out rather than because nothing was left.
+     */
+    readonly stoppedForTimeBudget: boolean;
+    /**
+     * Elapsed wall-clock time.
+     */
+    readonly durationMs: Milliseconds;
+}
+/**
+ * Deletes every run task past its retention age, within a strict time budget.
+ *
+ * A SEPARATE sweep from {@link openRouterRunTaskSweep}, on a far slower schedule: the drain tick runs every
+ * minute and there is nothing a week-old document gains from being looked at that often.
+ *
+ * @param params - The service and budget settings.
+ * @returns What the sweep deleted.
+ */
+export declare function openRouterRunTaskExpirationSweep(params: OpenRouterRunTaskExpirationSweepParams): Promise<OpenRouterRunTaskExpirationSweepResult>;