@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/jobs/ai-jobs.d.ts

@@ -0,0 +1,558 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AiJob, type AiJobApplied, type AiJobKind, type AiJobOutput, type AiJobPlan, type AiJobReview, type AiJobStatus, type AiJobStepTokens, type AiJobSummary } from '../model/ai-jobs.types';
+import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types';
+import { type AiActivityActor } from '../activity/ai-activity';
+import { type AiEffort, type AiUsage } from '../runtime/ai-runtime';
+import { AI_JOB_INLINE_BUDGET_MS, AI_JOB_SWEEP_BUDGET_MS } from './ai-job-budget';
+import { type AiJobStepOutcome, type AiJobStepRunner } from './ai-job-text-step';
+import { type AssistReservation } from '../usage/assist-usage';
+/**
+ * AI generation jobs — the Firestore state machine (AGL-2904).
+ *
+ * One document per job under the org, written only by this module through
+ * the Admin SDK; the rules let a member READ their org's jobs and nobody
+ * write them. The console route creates a job and runs its first step
+ * inline when it can; the AI jobs beat, a console route of its own, claims
+ * and runs whatever is queued, across every org, inside a wall-clock budget
+ * (`ai-jobs-beat.ts`). Both go through
+ * `runAiJobStep`, so there is exactly one place a step is claimed, metered,
+ * run and recorded.
+ *
+ * ── Credits, per step ────────────────────────────────────────────────────
+ *
+ * Every step is an assist message to the meter: `reserveAssistMessage`
+ * BEFORE the provider is called — the same read-and-increment transaction
+ * the chat route takes, so a job cannot slip past the org's monthly ceiling
+ * by being asynchronous — and `recordAssistCost` after, at the serving
+ * model's rates, so the usage rollup and the invoice see a job's tokens
+ * exactly as they see a chat turn's. The credit figure on the job is that
+ * cost at the plan's credit rate, rounded up like every other credit.
+ *
+ * A refused reservation is NOT a failure. The org is out of credits, over
+ * its cap, or has switched overage off — all things a member can change —
+ * so the job parks as `needs_input` with the refusal in customer-safe words
+ * and the beat tries it again once it has rested. `failed` is reserved for
+ * a step that cannot succeed by waiting.
+ *
+ * ── What a step may not do ───────────────────────────────────────────────
+ *
+ * A step runner writes drafts and returns. It does not touch the job
+ * document, the meter or the lease: the machine owns those, so a runner
+ * written next month cannot forget the reservation or record itself done
+ * while the provider is still generating.
+ */
+export declare const AI_JOBS_COLLECTION = "aiJobs";
+/**
+ * How long a claim holds the step: longer than the longest any holder can
+ * still be running it, which is the beat route's 300 s function ceiling
+ * (AGL-3026). A lease that ran out under a live holder would let the next
+ * beat claim the same step and call the provider for it a second time, and
+ * the beat fires every minute while a sweep may run for most of five, so
+ * this is what keeps overlapping beats apart. A step abandoned by a process
+ * that died is recovered once it runs out, by the first beat after that.
+ */
+export declare const AI_JOB_LEASE_MS = 330000;
+/** A step handed back by a retryable provider failure this many times fails. */
+export declare const AI_JOB_STEP_MAX_ATTEMPTS = 3;
+/**
+ * The most passes one step may take by asking to continue (AGL-2910), for a
+ * kind that registers no bound of its own. A site audit's passes are its
+ * units of generated work; this bounds a runner that never finishes, not a
+ * real site.
+ */
+export declare const AI_JOB_STEP_MAX_PASSES = 40;
+/**
+ * The nominal credit figure shown as held per outstanding step. Not a
+ * bound — the reservation and the monthly ceiling are — but the console
+ * must show a running job as costing something before its bill is known.
+ *
+ * NOMINAL, and nothing reads it as more (AGL-3030): the band, the Free
+ * taste's account allowance and every refusal are measured on recorded
+ * spend, and the one real reservation a step takes is a message, counted
+ * when the step is claimed and settled — metered or handed back — before the
+ * step is recorded. So a job holds nothing real between steps, and a job
+ * parked for a person shows nothing held either: `recordStep` releases the
+ * figure when a step parks for review, and `resumeAiJob` holds it again for
+ * the steps a person's resume queues.
+ */
+export declare const AI_JOB_STEP_RESERVE_CREDITS = 50;
+/**
+ * The inline doors' budget and the beat's, declared beside the time a step is
+ * planned against (`ai-job-budget.ts`, AGL-3036) so a step's least time and
+ * the budgets it has to fit are read in one place.
+ */
+export { AI_JOB_INLINE_BUDGET_MS, AI_JOB_SWEEP_BUDGET_MS };
+/** Jobs one beat reads as candidates; the budget usually stops it first. */
+export declare const AI_JOB_SWEEP_MAX_JOBS = 25;
+/** Parked jobs one beat re-queues, on top of the active candidates. */
+export declare const AI_JOB_SWEEP_MAX_PARKED = 5;
+/** How long a `needs_input` job rests before the beat tries its reservation again. */
+export declare const AI_JOB_NEEDS_INPUT_RETRY_MS: number;
+export declare const AI_JOB_NOT_AVAILABLE_COPY = "This kind of AI job is not available yet.";
+export declare const AI_JOB_REFUSED_COPY = "The model declined this brief. Try rephrasing it.";
+type Firestore = FirebaseFirestore.Firestore;
+export declare function isAiJobTerminal(status: AiJobStatus): boolean;
+/** The step a planned kind runs first (AGL-2935). */
+export declare const AI_JOB_PLAN_STEP = "plan";
+/**
+ * The kinds that build site structure, and so plan before they generate
+ * (AGL-2935): the plan their first step proposes is what their generation
+ * step executes, once a person has confirmed it.
+ */
+export declare const AI_PLANNED_JOB_KINDS: readonly AiJobKind[];
+export interface AiJobStepRegistration {
+    /**
+     * The least time, in milliseconds, one run of the kind's step needs before
+     * it starts (AGL-2907): its generation's worst case at the rates
+     * `ai-job-budget.ts` assumes — every model call it may make, with the step's
+     * own reads and writes (AGL-3036). The beat leaves the step queued rather
+     * than start it with less time left, and an inline door leaves it for the
+     * beat, because a provider call the caller's budget cuts off is still
+     * generated and billed upstream while the meter records nothing.
+     *
+     * Every generation step the plugin registers declares one (AGL-3035), and a
+     * spec over the console surface's registrations fails on a step that does
+     * not. Absent, the step starts whenever it is claimed.
+     */
+    minimumMs?: number;
+    /**
+     * For a step whose runs need different times, the least time the run this
+     * job would make next needs (AGL-3035): a page job's pass that builds a
+     * layout needs a layout's time, where its section passes need a section's,
+     * and a scaffold's pass needs what the unit it hands on needs. Never read as
+     * less than `minimumMs`, which is then the least any run of the step needs.
+     */
+    minimumMsFor?: (job: AiJob) => number;
+}
+/** Idempotent per kind; last registration wins. */
+export declare function registerAiJobStep(kind: AiJobKind, runner: AiJobStepRunner, registration?: AiJobStepRegistration): void;
+/**
+ * The least time a step needs before it starts: the plan step's own minimum
+ * for the plan step of any kind (AGL-3026), and the kind's registered
+ * minimum for the kind's own step — the least any run of it needs.
+ */
+export declare function aiJobStepMinimumMs(kind: AiJobKind, stepName: string): number;
+/**
+ * The least time the next run of a job's own step needs (AGL-3035): what the
+ * kind registered, or more where the kind says this job's next run needs
+ * more. A step that delegates a unit to another kind — a page job's creation,
+ * a scaffold's page — asks this of the job it derives for the unit.
+ */
+export declare function aiJobStepRunMinimumMs(job: AiJob): number;
+/** The least time the job's next step needs; 0 when no step is left to run. */
+export declare function aiJobNextStepMinimumMs(job: AiJob): number;
+export declare function aiJobStepRunnerFor(kind: AiJobKind): AiJobStepRunner | null;
+/**
+ * A kind whose step works through more units than the default bounds
+ * (AGL-2911). A scaffold's unit is a whole page and its site is eight of
+ * them, where an audit's is one page's listing, so the runaway bound the
+ * default gives an audit would cut a real site short. The kind registers its
+ * own beside its runner, so the machine keeps no list of kinds and the bound
+ * sits with the plan that explains it.
+ */
+export declare function registerAiJobStepPasses(kind: AiJobKind, maxPasses: number): void;
+/** The passes a kind's step may take; the default where it registered none. */
+export declare function aiJobStepMaxPasses(kind: AiJobKind): number;
+/**
+ * The plan step every planned kind runs first. Registered by its own module
+ * (`ai-job-plan-step.ts`), which the plugin's server surface loads, so this
+ * machine — and every spec that drives it — never loads the inventory
+ * reader and the Admin SDK behind it. `null` unregisters it, minimum and all.
+ *
+ * `minimumMs` means for the plan step what it means for a kind's step
+ * (AGL-3026): a plan answered at its ceiling takes longer than an inline
+ * door's budget, so the step says so, and both doors leave it for the beat.
+ */
+export declare function registerAiJobPlanStep(runner: AiJobStepRunner | null, registration?: AiJobStepRegistration): void;
+/**
+ * Whether AI generation is paused for a workspace, as the jobs doors read it
+ * (AGL-3037). `staff` is a verified staff caller on an inline door; the beat
+ * has none.
+ */
+export type AiJobPauseReader = (input: {
+    orgId: string;
+    staff: boolean;
+}) => Promise<boolean>;
+/**
+ * The reader `runAiJobStep` asks before it claims a step. Registered by its
+ * own module (`ai-jobs-pause.ts`), which the plugin's console surface calls,
+ * so this machine — and every spec that drives it — never loads the Admin SDK
+ * the lockdown reads run on. `null` unregisters it; a machine with no reader
+ * runs every job, as a process with no lockdown carrier would.
+ */
+export declare function registerAiJobPauseReader(reader: AiJobPauseReader | null): void;
+/** Whether a pause reader is registered: what a surface that runs jobs must have. */
+export declare function aiJobPauseReaderRegistered(): boolean;
+/** The runner for one step of one job: the plan step by its name, else the kind's own. */
+export declare function aiJobRunnerForStep(kind: AiJobKind, stepName: string): AiJobStepRunner | null;
+/**
+ * The step names a job of this kind carries, in order. A planned kind plans
+ * only once something can build the plan: until its generation runner is
+ * registered, its job fails fast and free, rather than spending on a plan
+ * nothing will execute.
+ */
+export declare function aiJobStepNames(kind: AiJobKind): string[];
+export interface CreateAiJobInput {
+    orgId: string;
+    hostId?: string | null;
+    kind: AiJobKind;
+    brief: string;
+    inputs?: Record<string, unknown>;
+    /** The model the creator picked (AGL-2942); absent or `null` for Auto. */
+    model?: string | null;
+    createdBy: string;
+    /** The creator's address, for the activity row; the document stores the uid only. */
+    createdByEmail?: string | null;
+}
+/**
+ * A new job, `queued`, with its step plan laid out and nothing run.
+ *
+ * The activity row is written once the document is, so the feed never names
+ * a job that does not exist. The brief's length stands in for the brief,
+ * which is the customer's own text and is not logged (AGL-2929).
+ */
+export declare function createAiJob(firestore: Firestore, input: CreateAiJobInput, now?: Date): Promise<AiJob>;
+export declare function getAiJob(firestore: Firestore, orgId: string, jobId: string): Promise<AiJob | null>;
+export interface ListAiJobsOptions {
+    status?: AiJobStatus;
+    limit?: number;
+}
+/** Newest first. Needs the (status, createdAt) index when filtered. */
+export declare function listAiJobs(firestore: Firestore, orgId: string, options?: ListAiJobsOptions): Promise<AiJob[]>;
+/** The wire form. `running` is the lease, read against `now`. */
+export declare function aiJobSummary(job: AiJob, now?: Date): AiJobSummary;
+export interface ClaimedAiJobStep {
+    job: AiJob;
+    stepIndex: number;
+}
+/**
+ * Take the lease on the job's next step, in one transaction.
+ *
+ * Refuses — `null` — when the job is terminal or parked, when it has no
+ * step left, or when ANOTHER owner's lease has not yet expired. That last
+ * clause is the whole point: the console route and two overlapping beats
+ * can all look at one job inside the same minute, and only one of them may
+ * spend the reservation for its step. An expired lease is claimable, which
+ * is how a step abandoned mid-flight by a frozen process is recovered — the
+ * stale lease is released by being taken, not by a sweep of its own.
+ */
+export declare function claimNextStep(firestore: Firestore, orgId: string, jobId: string, owner: string, now?: Date): Promise<ClaimedAiJobStep | null>;
+/**
+ * Extend the lease while a long step is still running. `false` when the
+ * caller no longer holds it — the step was recovered by someone else, and
+ * the caller's result must not overwrite theirs.
+ */
+export declare function heartbeatStep(firestore: Firestore, orgId: string, jobId: string, owner: string, now?: Date): Promise<boolean>;
+/**
+ * Leave a job whose workspace's AI is paused where it is (AGL-3037), moved to
+ * the back of the beat's queue. Nothing is claimed: its steps, their attempts
+ * and its lease stay exactly as they were, so resuming AI runs the job from
+ * where it stopped. Only `updatedAt` moves — the beat's queue is ordered by it,
+ * and a paused workspace's jobs left at the front would fill every beat's
+ * candidates and starve every other workspace's.
+ *
+ * `null`, writing nothing, for a job a claim would not take either: terminal,
+ * parked, no step left, or another owner's live lease.
+ */
+export declare function holdPausedAiJob(firestore: Firestore, orgId: string, jobId: string, owner: string, now?: Date): Promise<AiJob | null>;
+export interface RecordStepInput {
+    /** `pending` hands the step back for another attempt. */
+    status: 'done' | 'failed' | 'pending';
+    creditsSpent: number;
+    error?: string | null;
+    outputs?: AiJobOutput[];
+    /** The plan the step proposed, kept on the job (AGL-2935). */
+    plan?: AiJobPlan;
+    /** The step stopped for a person: the job parks `needs_review` in this same write. */
+    review?: AiJobReview;
+    /**
+     * With `pending`: the step is handed back because it made progress and
+     * asked to continue (AGL-2910), not because an attempt failed. Its
+     * attempts count again from zero and its passes by one.
+     */
+    continued?: boolean;
+    /** What the run cost in tokens and time (AGL-2937), added to the step's totals. */
+    tokens?: AiJobStepTokenRun;
+}
+/** One run of a step's runner, as the machine measured it (AGL-2937). */
+export interface AiJobStepTokenRun {
+    usage: AiUsage;
+    model: string;
+    effort: AiEffort | null;
+    latencyMs: number;
+    /** Why the run's last model call stopped (AGL-3042). */
+    stopReason: string | null;
+}
+/**
+ * The runs whose stop reasons a step's record keeps (AGL-3042), newest last.
+ * A page job that builds a layout, a form and a component, then five sections
+ * and its last pass, runs its generation step nine times: twelve keep such a
+ * page whole with room for three retries.
+ *
+ * What it costs the document: an entry is at most 67 bytes as Firestore sizes
+ * it (the two field names, 11 and 7; a stop reason, a provider's ASCII word of
+ * at most `AI_JOB_STEP_STOP_REASON_MAX_CHARS` characters, 41; an integer, 8),
+ * so a step's list is at most 813 bytes with its field name, and a job's two
+ * steps at most 1,626 of the 1,048,576 bytes a document may hold.
+ */
+export declare const AI_JOB_STEP_LAST_RUNS = 12;
+/** The longest stop reason a run's entry keeps; every one a provider names today is shorter. */
+export declare const AI_JOB_STEP_STOP_REASON_MAX_CHARS = 40;
+/**
+ * A step's measure with one more run added: the four counts and the time
+ * summed, the model and effort taken from the run, and why it stopped
+ * appended to the latest runs (AGL-3042).
+ */
+export declare function addAiJobStepTokens(current: AiJobStepTokens | null | undefined, run: AiJobStepTokenRun): AiJobStepTokens;
+export interface RecordedStep {
+    job: AiJob;
+    /** Steps still to run after this one. */
+    remaining: number;
+}
+/**
+ * Record what a step cost and produced, and hand the lease back.
+ *
+ * Credits and outputs are recorded whatever the job's status is by now —
+ * a job canceled while its provider call was in flight still spent the
+ * tokens, and hiding that would make the bill disagree with the document.
+ * The status transition is the caller's next call (`completeAiJob`,
+ * `failAiJob`), except that a step handed back or a step with more steps
+ * behind it re-queues here, so the beat sees it without another write —
+ * and a step that stopped for a person parks the job `needs_review` here,
+ * in the same transaction, so no beat can claim the next step in between.
+ */
+export declare function recordStep(firestore: Firestore, orgId: string, jobId: string, owner: string, stepIndex: number, input: RecordStepInput, now?: Date): Promise<RecordedStep>;
+/** Every step done: the job is `done` and holds nothing. */
+export declare function completeAiJob(firestore: Firestore, orgId: string, jobId: string, now?: Date): Promise<AiJob>;
+/**
+ * Terminal failure. `message` is the only thing a customer reads, so it is
+ * a fixed sentence; whatever the provider or the runner actually said goes
+ * to the log beside the ids an operator would search for.
+ */
+export declare function failAiJob(firestore: Firestore, orgId: string, jobId: string, message: string, detail?: {
+    stepIndex?: number;
+    error?: unknown;
+}, now?: Date): Promise<AiJob>;
+/**
+ * Park the job for something only the workspace can change. The running
+ * step goes back to `pending` so the same step is what runs when the beat
+ * tries again; its attempt is not counted, because nothing was attempted.
+ */
+export declare function markAiJobNeedsInput(firestore: Firestore, orgId: string, jobId: string, reason: string, now?: Date): Promise<AiJob>;
+/**
+ * Cancel. Idempotent — a terminal job is returned unchanged — and it does
+ * not wait for a step in flight: the runner holding the lease finishes its
+ * provider call, records what it cost, and finds the job canceled when it
+ * goes to complete it.
+ *
+ * The activity row is written only when the cancel changed something: a
+ * second cancel of the same job is not a second act. `actor` is the member
+ * who canceled; a cancel with nobody named is recorded as nobody's rather
+ * than as the creator's.
+ */
+export declare function cancelAiJob(firestore: Firestore, orgId: string, jobId: string, now?: Date, actor?: AiActivityActor | null): Promise<{
+    job: AiJob;
+    changed: boolean;
+}>;
+/**
+ * Resume a job that stopped for a person (AGL-2935): confirm its plan, or
+ * try again the step whose answer broke a building rule. One transaction,
+ * so two confirmations land once; anything but a `needs_review` job comes
+ * back unchanged. The pending step's attempts start over — a person asking
+ * again is not a provider failing again — and a confirmed plan with no step
+ * left behind it completes the job rather than queueing nothing. The steps
+ * it queues are held at the nominal figure again, which the park released —
+ * and a confirmed plan is held at what the whole job is estimated to cost
+ * (AGL-3031), creations included, where that is more.
+ */
+export declare function resumeAiJob(firestore: Firestore, orgId: string, jobId: string, actor: {
+    uid: string;
+}, now?: Date): Promise<{
+    job: AiJob;
+    changed: boolean;
+}>;
+/**
+ * Record what a person applied from a finished job's outputs (AGL-2910): the
+ * versions an apply opened and the listings it staged. The apply door calls
+ * this after its own writes, so the record names only what exists. It never
+ * changes the job's status, its steps or its spend.
+ */
+export declare function recordAiJobApplied(firestore: Firestore, orgId: string, jobId: string, applied: AiJobApplied, now?: Date): Promise<AiJob>;
+export type AiJobAuditAction = 'ai.job.output' | 'ai.job.cancel' | 'ai.job.resume' | 'ai.job.apply';
+export interface AiJobAuditEntry {
+    action: AiJobAuditAction;
+    actorUid: string;
+    actorEmail?: string | null;
+    orgId: string;
+    jobId: string;
+    after: Record<string, unknown>;
+}
+/**
+ * One `adminAudit` row, the same writer shape the billing routes use. Never
+ * throws: an audit row that fails to land is logged, not turned into a
+ * failed job the customer paid for.
+ */
+export declare function writeAiJobAudit(firestore: Firestore, entry: AiJobAuditEntry): Promise<void>;
+/**
+ * The refusal in customer-safe words. The org's own wall names the switch
+ * (AGL-2653); a cap, a band and a budget are told apart because one is a
+ * figure the org set, one is what its plan sold, and one is the operator's
+ * backstop; the message cap resets on a clock the others do not.
+ */
+export declare function aiJobRefusalText(org: Partial<AglynOrgBilling> | null, reservation: Pick<AssistReservation, 'refusedBy' | 'budgetUsd' | 'allotment' | 'capReason' | 'overageLimitUsd' | 'overageUnpaidUsd'>): string;
+export interface RunAiJobStepOptions {
+    /** Who is claiming: a request id or a beat id. */
+    owner: string;
+    now?: Date;
+    /**
+     * A reservation the caller already holds for THIS step — the console
+     * route's gate ladder takes one before the job exists. Every later step
+     * reserves for itself.
+     */
+    reservation?: AssistReservation;
+    /** The org billing document when the caller has it; read otherwise. */
+    org?: Partial<AglynOrgBilling> | null;
+    /** Ends the provider call when the caller's budget does. */
+    signal?: AbortSignal;
+    /**
+     * The person on the request when a route runs the step inline. The beat
+     * has none: what a step produces is then credited to the job's creator,
+     * whose brief it is, never to nobody (AGL-2929).
+     */
+    actor?: AiActivityActor;
+    /**
+     * A verified staff claim on the request when a route runs the step inline.
+     * The workspace's AI pause lets staff through here as the gate ladder does,
+     * so staff can verify a pause with one generation (AGL-3037). The beat has
+     * no caller and never passes it.
+     */
+    staff?: boolean;
+}
+export type AiJobStepRun = 
+/** Nothing to do: terminal, parked, no step left, or another owner's lease. */
+{
+    outcome: 'not-claimable';
+}
+/** The reservation was refused; the job is parked with the reason. */
+ | {
+    outcome: 'needs_input';
+    job: AiJob;
+}
+/** The step stopped for a person (AGL-2935): its plan waits, or its answer broke a rule twice. */
+ | {
+    outcome: 'needs_review';
+    job: AiJob;
+}
+/** The step ran and was recorded; `job.status` says whether more remain. */
+ | {
+    outcome: 'done';
+    job: AiJob;
+} | {
+    outcome: 'failed';
+    job: AiJob;
+}
+/** A retryable provider failure; the step is pending again. */
+ | {
+    outcome: 'requeued';
+    job: AiJob;
+}
+/**
+ * AI is paused for the job's workspace (AGL-3037): nothing was claimed,
+ * reserved or run, and the job waits where it stopped, at the back of the
+ * beat's queue, until staff resume AI.
+ */
+ | {
+    outcome: 'paused';
+    job: AiJob;
+};
+/** A step outcome that carries no tokens and no cost: the provider was never reached. */
+export declare function aiJobStepSpentNothing(outcome: Pick<AiJobStepOutcome, 'usage' | 'estCostUsd'>): boolean;
+/**
+ * Pause, claim, reserve, run, meter, record — one step of one job.
+ *
+ * The order is the invariant. The workspace's AI pause is asked BEFORE the
+ * claim, so a paused workspace's job is neither claimed nor reserved for.
+ * The reservation is taken AFTER the claim so a refused claim costs nothing,
+ * and BEFORE the runner so the org's ceiling binds before a token is spent.
+ * The cost is recorded before the step is, so a process cut off between the
+ * two leaves the bill right and the step recoverable, never the other way
+ * round.
+ */
+export declare function runAiJobStep(firestore: Firestore, orgId: string, jobId: string, options: RunAiJobStepOptions): Promise<AiJobStepRun>;
+export interface DueAiJob {
+    orgId: string;
+    jobId: string;
+}
+export interface SweepAiJobsOptions {
+    firestore: Firestore;
+    /** The beat's identity for its leases. */
+    owner: string;
+    now?: () => number;
+    budgetMs?: number;
+    maxJobs?: number;
+    /** Test seams; the defaults query Firestore and run the real step. */
+    listDue?: () => Promise<DueAiJob[]>;
+    runStep?: (orgId: string, jobId: string, options: RunAiJobStepOptions) => Promise<AiJobStepRun>;
+}
+export interface SweepAiJobsResult {
+    /** Candidates the queries returned. */
+    due: number;
+    /** Steps this sweep actually ran to a recorded result. */
+    ran: number;
+    /** Claims another owner held, or jobs with nothing left. */
+    skipped: number;
+    /**
+     * Jobs whose workspace's AI staff have paused (AGL-3037): held where they
+     * stopped and moved to the back of the queue, to run once AI is resumed.
+     */
+    paused: number;
+    /** Candidates left untouched because the wall clock ran out. */
+    remaining: number;
+    budgetExhausted: boolean;
+}
+/**
+ * Every job the beat should look at, oldest first: queued and running
+ * across every org, then `needs_input` jobs that have rested long enough
+ * for the org's standing to have changed. Two queries rather than one, so
+ * a workspace with many parked jobs cannot fill the candidate list and
+ * starve the queue behind it. Both use the collection-group index on
+ * (status, updatedAt).
+ *
+ * The ordering is the cursor. A job this sweep touches has its `updatedAt`
+ * moved and goes to the back of the next query; one it did not reach keeps
+ * its place at the front. So there is no stored position to fall behind
+ * or skip past — the same shape `media-move.ts` gives its budgeted loop,
+ * where what was not done is simply what is asked for next.
+ */
+export declare function listDueAiJobs(firestore: Firestore, nowMs: number, maxJobs?: number, maxParked?: number): Promise<DueAiJob[]>;
+/**
+ * Run due steps until the budget is spent, and account for every candidate.
+ *
+ * The bound is wall clock, not a count, for the reason `media-move.ts`
+ * gives: one step is one provider round trip of unknown length, so any
+ * fixed number would be wrong for some brief. The budget is checked BETWEEN
+ * jobs, and the step in flight gets the time that is left as its abort
+ * signal, so the sweep still finishes whichever step it has started. At
+ * least one candidate is always attempted, so a beat that yields having
+ * done nothing cannot starve a queue behind a slow clock.
+ *
+ * A `needs_input` job is re-queued before its step is claimed, because the
+ * claim admits only queued and running jobs; the reservation inside the
+ * step is what decides whether the org's standing has changed.
+ */
+export declare function sweepAiJobs(options: SweepAiJobsOptions): Promise<SweepAiJobsResult>;