gemi 0.110.0 → 0.112.0

package/dist/ai/jobs/AgentJob.d.ts

@@ -0,0 +1,259 @@
+import { Job } from "../../services/queue/Job";
+import type { GeneratedAttachment, ToolGenerateImageParams, ToolEditImageParams } from "../Agent";
+import { type GenerateParams, type GenerateResult } from "../generate";
+import type { ImageModel } from "../ImageModel";
+import { ToolError } from "../redact";
+import type { Infer, Schema } from "../Schema";
+import { type Attachment, type AttachmentStorage, type AttachmentStore, ScopedAttachments } from "../store/Attachments";
+import type { AgentError, Usage } from "../types";
+import { type AgentJobRecord, type AgentJobStore } from "./AgentJobStore";
+declare const HANDLE: unique symbol;
+/**
+ * What `ctx.jobs.start` and `ctx.jobs.track` answer, and what a tool returns to
+ * say "this call goes on in the background" (#461).
+ *
+ * Returning it is what makes the call's result `running` rather than `ok`: the
+ * model reads that the job started and is told not to start it again, the turn
+ * goes on and ends as usual, and when the job settles the controller renders
+ * its outcome over that result the next time it loads the thread.
+ *
+ * `Output` is the job's settled output, and it is what the tool's output type
+ * becomes, so a client's `ToolShapes` see the job's result as the tool's.
+ */
+export declare class JobHandle<Output = unknown> {
+    /** The job's id. Hand it to whatever settles a tracked job. */
+    readonly id: string;
+    readonly toolCallId: string;
+    readonly summary: unknown;
+    /** Epoch milliseconds, on the job store's clock. */
+    readonly deadlineAt: number;
+    /** Phantom: the settled output's type. Never set. */
+    readonly $output: Output;
+    readonly [HANDLE]: true;
+    constructor(
+    /** The job's id. Hand it to whatever settles a tracked job. */
+    id: string, toolCallId: string, summary: unknown, 
+    /** Epoch milliseconds, on the job store's clock. */
+    deadlineAt: number);
+}
+/** Whether a tool's return value is a `JobHandle`, across copies of the module. */
+export declare function isJobHandle(value: unknown): value is JobHandle;
+/**
+ * `ctx.jobs.start` or `track` from a run that has nowhere to settle a job
+ * into: a stateless turn, a run started without a job store, or a sub-run.
+ *
+ * A `ToolError`, so the model reads why the tool could not go to the
+ * background and can say so, rather than being told the tool broke.
+ */
+export declare class JobsRequireThreadError extends ToolError {
+    readonly code: "jobs_require_thread";
+    constructor(message: string);
+}
+/** What a job settles with. */
+export type AgentJobOutcome = {
+    output: unknown;
+    usage?: Usage;
+} | {
+    error: string | Error | (Pick<AgentError, "message"> & Partial<AgentError>);
+    usage?: Usage;
+};
+/**
+ * Background jobs, from anywhere in the app: settle one, fail one, look one up.
+ *
+ * PROCESS-WIDE, and that is forced. A job is started by a tool inside a run,
+ * and settled by a queue worker, a provider's webhook, a poller or the deadline
+ * sweep, none of which has a controller to read a store from. So the store is
+ * set once, at boot, for every one of them:
+ *
+ *     AgentJobs.use(new DatabaseAgentJobStore(app(DatabaseManager).connection()));
+ *
+ * Until then it is a `MemoryAgentJobStore`, which works in one process and
+ * forgets on restart.
+ */
+export declare const AgentJobs: {
+    /** The store every part of the feature reads and writes. */
+    readonly store: AgentJobStore;
+    /** Sets the store. Call it once, at boot, in every process that starts or runs jobs. */
+    use(store: AgentJobStore): void;
+    get(id: string): Promise<AgentJobRecord | null>;
+    /**
+     * Settles a running job with its output or its error, and answers whether
+     * this call did it.
+     *
+     * COMPARE-AND-SET FROM `running`. The first settle wins and every later one
+     * answers `false` and changes nothing, so a webhook, a poller and the
+     * deadline sweep can all race on one job. A job the deadline sweep has
+     * already failed stays failed: a late result is refused, so the model never
+     * sees a job flip from failed to done.
+     *
+     * An error given as a `ToolError`, a string or an `AgentError`-like object is
+     * shown to the model as it is. Any other `Error` is logged in full and the
+     * model is told only that the job failed, as for a tool that throws (#446).
+     */
+    settle(id: string, outcome: AgentJobOutcome): Promise<boolean>;
+    /** `settle(id, { error })`. */
+    fail(id: string, error: string | Error | AgentError): Promise<boolean>;
+    /**
+     * The deadline sweep: fails every running job whose deadline has passed
+     * with code `"timeout"`, and answers how many it failed.
+     *
+     * Compare-and-set like every settle, so it is safe to run on every
+     * instance at once, and a result that arrives after it is refused. Run it
+     * every minute with `AgentJobDeadlineSweep`; the controller also checks a
+     * thread's jobs when it loads the thread, so an app without cron still sees
+     * overdue jobs fail, just later. The job's queue worker is not stopped: what
+     * it returns afterwards is dropped.
+     */
+    sweep(options?: {
+        limit?: number;
+    }): Promise<number>;
+};
+/** The store's clock, or this process's for a store without one. */
+export declare function clockOf(store: AgentJobStore): Promise<number>;
+/** Fails a running job for its deadline. Compare-and-set: false when it had settled. */
+export declare function expire(store: AgentJobStore, record: AgentJobRecord): Promise<boolean>;
+/** Options for `ctx.jobs.start` and `ctx.jobs.track`. */
+export type StartJobOptions = {
+    /**
+     * What the model and the UI see while the job runs, in place of a result:
+     * which images, which pages. Plain data, and keep it small, since it is in
+     * the history on every later turn.
+     */
+    summary?: unknown;
+    /**
+     * How long the job may run, in milliseconds. Defaults to the tool's
+     * `async.deadlineMs`, else an hour. A job still running then is failed with
+     * code `"timeout"` by the deadline sweep, and a later result is refused.
+     */
+    deadlineMs?: number;
+};
+/** A tool's `ctx.jobs`. See `ToolContext.jobs`. */
+export interface ToolJobs {
+    /**
+     * Records a background job for this tool call and queues `job` to do it.
+     * Return the handle from `execute` to make the call's result `running`.
+     *
+     * At least once, like every queued job: `job.run` may run again after a
+     * crash, so make it idempotent. Only on a threaded run (a turn with a
+     * `threadId` through `AgentController`), and only from a top-level tool.
+     */
+    start<A, O>(job: AgentJobClass<A, O>, args: A, options?: StartJobOptions): Promise<JobHandle<O>>;
+    /**
+     * Records a background job that something else settles: a provider's
+     * webhook, a poller. Pass `handle.id` to it, and call
+     * `AgentJobs.settle(id, { output })` when the work is done.
+     */
+    track<O = unknown>(options?: StartJobOptions): Promise<JobHandle<O>>;
+}
+/** What a run that may start jobs is given. `AgentController` passes it on a threaded turn. */
+export type RunJobs = {
+    /** The run's owner (`runOwner`), recorded on each job. */
+    owner: string | null;
+};
+/** The longest a job runs when nothing says otherwise. */
+export declare const DEFAULT_JOB_DEADLINE_MS: number;
+/** @internal `ctx.jobs` for one tool call. Built by the run, per call. */
+export declare function toolJobs(params: {
+    jobs: RunJobs | undefined;
+    threadId: string | undefined;
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    depth: number;
+    /** The tool's `async` declaration; `undefined` for a tool without one. */
+    async: {
+        deadlineMs?: number;
+    } | undefined;
+    attachments: ScopedAttachments | null;
+}): ToolJobs;
+/** An `AgentJob` subclass, as `ctx.jobs.start` takes it. */
+export type AgentJobClass<A, O> = new () => AgentJob<A, O>;
+/** `generateImage`'s params inside a job: as in a tool, without `showModel` (there is no run to show). */
+export type JobGenerateImageParams = Omit<ToolGenerateImageParams, "showModel">;
+export type JobEditImageParams = Omit<ToolEditImageParams, "showModel">;
+/** Attachments inside a job: the scope of the run that started it. */
+export interface JobAttachments {
+    put(blob: Blob, params?: {
+        name?: string;
+        mimeType?: string;
+    }): Promise<Attachment>;
+    get(id: string): Promise<Attachment>;
+    read: ScopedAttachments["read"];
+    file(id: string): Promise<File>;
+}
+/**
+ * What `AgentJob.run` is handed beside its arguments: the parts of a tool's
+ * `ToolContext` that still mean something with no run around them.
+ */
+export interface AgentJobContext {
+    /** The job's id (`ajob_…`). */
+    readonly id: string;
+    readonly threadId: string;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** The `runOwner` of the run that started it. */
+    readonly owner: string | null;
+    readonly summary: unknown;
+    /** Not aborted yet: cancellation comes with a later release (#461, phase 4). */
+    readonly signal: AbortSignal;
+    /**
+     * The attachments of the run that started the job: what the tool's
+     * `ctx.attachments` was. Throws when that run had no attachment scope.
+     */
+    readonly attachments: JobAttachments;
+    /** `generate`, with its usage counted on the job. See `ToolContext.generate`. */
+    generate<O extends Schema<any>>(params: GenerateParams<O>): Promise<GenerateResult<Infer<O>>>;
+    /** Renders an image and stores it under the run's attachments. Usage is counted on the job. */
+    generateImage(model: ImageModel, params: JobGenerateImageParams): Promise<GeneratedAttachment>;
+    /** Edits images (bytes or attachment ids) and stores the result. Usage is counted on the job. */
+    editImage(model: ImageModel, params: JobEditImageParams): Promise<GeneratedAttachment>;
+    /** What this attempt has spent so far. */
+    readonly usage: Usage;
+}
+/**
+ * A queued job that settles a tool call (#461).
+ *
+ *     class RenderImagesJob extends AgentJob<{ pageId: number; prompts: string[] }, { made: number }> {
+ *       static name = "RenderImagesJob";
+ *       async run({ pageId, prompts }, job) {
+ *         for (const prompt of prompts) await job.generateImage(model, { prompt });
+ *         return { made: prompts.length };
+ *       }
+ *     }
+ *
+ * A gemi `Job`, so it gets the queue's leases, retries, backoff and dead
+ * letters. Register it with the queue like any other job. What `run` returns
+ * settles the tool call `ok`; a throw on the last attempt settles it `error`.
+ * At least once: make `run` idempotent.
+ *
+ * Declare `run` as a method, not as an arrow-function field. Override
+ * `onDeadletter` only with a call to `super.onDeadletter`, which is what fails
+ * the job. `worker = true` is not supported. The queue hands `uniqueId`,
+ * `throttle`, `concurrency`, `onFail` and `onDeadletter` the envelope
+ * `{ jobId, args }`, not `args`.
+ */
+export declare abstract class AgentJob<Args = unknown, Output = unknown> extends Job {
+    /** Phantom: the arguments' type. Never set. */
+    readonly $args: Args;
+    /** Phantom: the output's type. Never set. */
+    readonly $output: Output;
+    /**
+     * Where the job's `attachments` records live. Set it to what the
+     * controller's `attachments` is, as for the controller itself.
+     */
+    attachments: AttachmentStore;
+    /** Where the attachments' bytes live. Defaults to the app's `Storage`. */
+    attachmentStorage: AttachmentStorage;
+    abstract run(args: Args, job: AgentJobContext): Promise<Output> | Output;
+    constructor();
+    /**
+     * Fails the job once the queue has given up on it: its last attempt threw,
+     * it called `this.fail(error, { retry: false })`, or its process died on the
+     * last attempt.
+     */
+    onDeadletter(error: Error, ..._args: any[]): void;
+    /** @internal The queue-facing `run`: see the constructor. */
+    private $runEnvelope;
+}
+export {};
+//# sourceMappingURL=AgentJob.d.ts.map

package/dist/ai/jobs/AgentJob.d.ts.map

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

package/dist/ai/jobs/AgentJobDeadlineSweep.d.ts

@@ -0,0 +1,18 @@
+import { CronJob } from "../../services/cron/CronJob";
+/**
+ * Fails background jobs that ran past their deadline (#461), every minute.
+ *
+ * Schedule it by exporting it from a file under `app/cron`:
+ *
+ *     export { AgentJobDeadlineSweep } from "gemi/ai";
+ *
+ * Safe on every instance at once: each job is failed by compare-and-set. An
+ * app without it still sees an overdue job fail, when the controller next
+ * loads the job's thread.
+ */
+export declare class AgentJobDeadlineSweep extends CronJob {
+    name: string;
+    cron: string;
+    callback(): Promise<void>;
+}
+//# sourceMappingURL=AgentJobDeadlineSweep.d.ts.map

package/dist/ai/jobs/AgentJobDeadlineSweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentJobDeadlineSweep.d.ts","sourceRoot":"","sources":["../../../ai/jobs/AgentJobDeadlineSweep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAGtD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,OAAO;IAChD,IAAI,SAA2B;IAC/B,IAAI,SAAe;IAEb,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAOhC"}

package/dist/ai/jobs/AgentJobStore.d.ts

@@ -0,0 +1,141 @@
+import type { AgentError, Usage } from "../types";
+/**
+ * Where a background job stands (#461).
+ *
+ * `running` until something settles it; `ok` and `error` are final. A job
+ * moves out of `running` once, by compare-and-set (`AgentJobStore.transition`),
+ * so a queue worker, a provider's webhook, a poller and the deadline sweep can
+ * all race to settle the same job and exactly one of them wins.
+ */
+export type AgentJobState = "running" | "ok" | "error";
+/**
+ * One background job, as the job store keeps it.
+ *
+ * The record is the job's state, and it is NOT the tool result. The tool
+ * result in the thread says `running` and points here by `id`; the controller
+ * renders the record's current state over it whenever it loads the thread (see
+ * `overlayJobs`). The record is kept apart from the messages because a live
+ * run writes whole messages to the store, and a job settling during that run
+ * would race those writes and lose.
+ */
+export type AgentJobRecord = {
+    /** `ajob_…`. Handed to the app (`JobHandle.id`) to settle a tracked job. */
+    id: string;
+    threadId: string;
+    /** The run whose tool started the job. */
+    runId: string;
+    /** The tool call whose result this job settles. */
+    toolCallId: string;
+    toolName: string;
+    /** The `runOwner` of the run that started it, or `null` for an anonymous run. */
+    owner: string | null;
+    /** The `AgentJob` class's queue name, or `null` for a job made with `track`. */
+    job: string | null;
+    /**
+     * What the tool said about the job when it started it: what the model and
+     * the UI see while it runs. Server-owned, and kept small by the tool.
+     */
+    summary?: unknown;
+    state: AgentJobState;
+    /** The settled output, on `ok`. */
+    output?: unknown;
+    /** Why it failed, on `error`. Already redacted: this is what the model reads. */
+    error?: AgentError;
+    /** What the job spent on model and image calls. Counted on the turn that started it. */
+    usage?: Usage;
+    /**
+     * Set when the job's tool result never reached the thread: the run died
+     * after the job started and before the result was stored. The job still
+     * runs and settles; nothing in the thread shows it.
+     */
+    orphaned?: true;
+    /**
+     * The attachment scope key of the run that started the job, so the job's
+     * `attachments` are the ones the tool would have had. `null` when the run
+     * had none.
+     */
+    attachmentScope: string | null;
+    /** Epoch milliseconds, on the store's clock. */
+    createdAt: number;
+    updatedAt: number;
+    /** When the deadline sweep fails the job if it is still running. */
+    deadlineAt: number;
+    settledAt?: number;
+};
+/** What `create` is given: the record minus what the store stamps. */
+export type NewAgentJobRecord = Omit<AgentJobRecord, "state" | "createdAt" | "updatedAt" | "deadlineAt" | "settledAt"> & {
+    /** How long from now the job may run, in milliseconds. */
+    deadlineMs: number;
+};
+/** The fields a transition may write. `id`, the thread and the call never change. */
+export type AgentJobUpdate = Partial<Pick<AgentJobRecord, "state" | "output" | "error" | "usage" | "orphaned" | "settledAt">>;
+/**
+ * Where background jobs live.
+ *
+ * `MemoryAgentJobStore` is the default and is not durable. `DatabaseAgentJobStore`
+ * keeps them in a table. An app that already has a jobs table can implement
+ * this over it.
+ */
+export interface AgentJobStore {
+    /** Writes a new `running` record and returns it as stored. */
+    create(job: NewAgentJobRecord): Promise<AgentJobRecord>;
+    get(id: string): Promise<AgentJobRecord | null>;
+    /**
+     * A thread's jobs, newest first. `states` filters, `limit` bounds. Each
+     * record is a copy the caller may keep.
+     */
+    listForThread(threadId: string, options?: {
+        states?: AgentJobState[];
+        limit?: number;
+    }): Promise<AgentJobRecord[]>;
+    /**
+     * Compare-and-set: applies `to` only when the job's state is one of `from`,
+     * and answers whether it did. Bumps `updatedAt`, and stamps `settledAt` when
+     * `to.state` moves the job out of `running`.
+     */
+    transition(id: string, from: AgentJobState[], to: AgentJobUpdate): Promise<boolean>;
+    /** Running jobs whose `deadlineAt` is at or before `now`, oldest deadline first. */
+    overdue(now: number, limit: number): Promise<AgentJobRecord[]>;
+    /**
+     * The store's clock, in epoch milliseconds. The deadline sweep compares
+     * `deadlineAt` against this rather than the process's clock. Optional: a
+     * store without one is compared against `Date.now()`.
+     */
+    now?(): Promise<number>;
+    /**
+     * Runs `fn` in a transaction, so `ctx.jobs.start` writes the record and
+     * queues the job together: both or neither. Optional: without it the record
+     * is written first, and a dispatch that fails then fails the record.
+     */
+    transaction?<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Jobs in a map, for as long as the process lives.
+ *
+ * NOT DURABLE, like `MemoryAgentStore`: a restart loses every record, and a
+ * job that was running is then lost too. The tool result that pointed at it
+ * reads as a lost job on the next turn. It is the default so that jobs work in
+ * development and tests without a table; use `DatabaseAgentJobStore` in
+ * production.
+ *
+ * It only works when the queue runs the jobs in this same process (the memory
+ * queue driver, or a database driver claiming here), since a worker in another
+ * process has a map of its own.
+ */
+export declare class MemoryAgentJobStore implements AgentJobStore {
+    private jobs;
+    create(job: NewAgentJobRecord): Promise<AgentJobRecord>;
+    get(id: string): Promise<AgentJobRecord | null>;
+    listForThread(threadId: string, options?: {
+        states?: AgentJobState[];
+        limit?: number;
+    }): Promise<AgentJobRecord[]>;
+    transition(id: string, from: AgentJobState[], to: AgentJobUpdate): Promise<boolean>;
+    overdue(now: number, limit: number): Promise<AgentJobRecord[]>;
+    now(): Promise<number>;
+    /** Bounds a long-lived thread: running jobs are never dropped, settled ones oldest first. */
+    private trim;
+}
+/** Newest first, with the id as a tie-break so the order is stable. */
+export declare function newestFirst(a: AgentJobRecord, b: AgentJobRecord): number;
+//# sourceMappingURL=AgentJobStore.d.ts.map

package/dist/ai/jobs/AgentJobStore.d.ts.map

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

package/dist/ai/jobs/DatabaseAgentJobStore.d.ts

@@ -0,0 +1,82 @@
+import type { DatabaseConnection } from "../../database/Connection";
+import type { Dialect } from "../../database/dialect";
+import type { AgentJobRecord, AgentJobState, AgentJobStore, AgentJobUpdate, NewAgentJobRecord } from "./AgentJobStore";
+export type DatabaseAgentJobStoreOptions = {
+    /**
+     * The table. Default `gemi_agent_jobs`. A plain identifier (letters, digits
+     * and underscores), because it is spliced into every statement.
+     */
+    table?: string;
+};
+/**
+ * Background jobs (#461) in a table of the app's own database, so a job and
+ * its outcome outlive the process: a deploy in the middle of a render no
+ * longer loses it, and every instance sees the same state.
+ *
+ * Opt in, like the agent store:
+ *
+ *     AgentJobs.use(new DatabaseAgentJobStore(app(DatabaseManager).connection()));
+ *
+ * Written for SQLite, Postgres and MySQL 8 / MariaDB 10.6+ in raw SQL, as the
+ * database queue driver is, and the table is the app's to create: add the
+ * Prisma model from the docs, or call `createTable()`.
+ *
+ * - **Compare-and-set** is `UPDATE … WHERE id = ? AND state IN (…)`, so two
+ *   instances settling one job cannot both win.
+ * - **Time** is epoch milliseconds read from the database's clock, so the
+ *   deadline sweep on any instance agrees on when a job is overdue.
+ * - **Transactions.** `ctx.jobs.start` writes the record and queues the job
+ *   inside `transaction()`. On Postgres and MySQL, with the database queue
+ *   driver on the same connection, both rows commit together or not at all.
+ *   With any other queue the dispatch is held until the record has committed.
+ */
+export declare class DatabaseAgentJobStore implements AgentJobStore {
+    readonly table: string;
+    private readonly sql;
+    private readonly dialect;
+    private readonly connection;
+    constructor(connection: Pick<DatabaseConnection, "sql" | "dialect"> & Partial<Pick<DatabaseConnection, "name">>, options?: DatabaseAgentJobStoreOptions);
+    /**
+     * Creates the table and its indexes if they do not exist: the DDL Prisma
+     * generates for the model in the docs. For tests and for an app that does
+     * not manage its schema with Prisma.
+     */
+    createTable(): Promise<void>;
+    /**
+     * Runs `fn` in a transaction on this store's connection, joining one that is
+     * already open on it. `ctx.jobs.start` writes the record and queues the job
+     * in here.
+     */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    create(job: NewAgentJobRecord): Promise<AgentJobRecord>;
+    get(id: string): Promise<AgentJobRecord | null>;
+    listForThread(threadId: string, options?: {
+        states?: AgentJobState[];
+        limit?: number;
+    }): Promise<AgentJobRecord[]>;
+    transition(id: string, from: AgentJobState[], to: AgentJobUpdate): Promise<boolean>;
+    overdue(now: number, limit: number): Promise<AgentJobRecord[]>;
+    now(): Promise<number>;
+    /**
+     * Deletes settled jobs that settled more than `olderThanMs` ago, and answers
+     * how many. A settled result is written back into the thread on the next
+     * turn, after which the record is only history; nothing removes it unless
+     * this is called, from a cron job say. Running jobs are never pruned.
+     */
+    prune(olderThanMs: number): Promise<number>;
+    /** The open ORM transaction, when it is on this store's connection. */
+    private joinable;
+    /** Read at each call and never kept: a stored transaction handle outlives its transaction. */
+    private q;
+    private column;
+    private name;
+    /** The database's clock, in epoch milliseconds. As in `DatabaseQueueDriver`. */
+    private clock;
+    private ms;
+}
+/**
+ * The table as Prisma generates it for the model in the docs, with
+ * `IF NOT EXISTS` added.
+ */
+export declare function createAgentJobsTableStatements(dialect: Dialect, table: string): string[];
+//# sourceMappingURL=DatabaseAgentJobStore.d.ts.map

package/dist/ai/jobs/DatabaseAgentJobStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseAgentJobStore.d.ts","sourceRoot":"","sources":["../../../ai/jobs/DatabaseAgentJobStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAG9C,UAAU,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,SAAS,CAAC,GACrD,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,EAC3C,OAAO,GAAE,4BAAiC;IAc5C;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC;;;;OAIG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAOhD,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBvD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAM/C,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,OAAO,CAAC,cAAc,EAAE,CAAC;IAwBtB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BnF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAW9D,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC;IAM5B;;;;;OAKG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASjD,uEAAuE;IACvE,OAAO,CAAC,QAAQ;IAOhB,8FAA8F;IAC9F,OAAO,CAAC,CAAC;IAIT,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,IAAI;IAKZ,gFAAgF;IAChF,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,EAAE;CAMX;AAqDD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAyDxF"}

package/dist/ai/jobs/contextBlock.d.ts

@@ -0,0 +1,31 @@
+import type { AgentJobRecord } from "./AgentJobStore";
+/** How many jobs the `<jobs>` block lists by default. */
+export declare const DEFAULT_JOBS_CONTEXT_MAX = 20;
+/** `Agent.create({ jobs })`. */
+export type AgentJobsOptions = {
+    /**
+     * The `<jobs>` block added to the system prompt on a thread that has
+     * background jobs: at most `max` of them (default 20), running ones first,
+     * then the newest settled. `false` leaves it out.
+     */
+    contextBlock?: {
+        max?: number;
+    } | false;
+};
+/**
+ * The `<jobs>` block (#461): what the model is told about the thread's
+ * background jobs on every turn, beside the tool results in the history.
+ *
+ * The history already shows each job's call and its `running` or settled
+ * result. The block is for what the history cannot show: a job whose result
+ * never reached the thread (an orphan), and a list in one place, so a model
+ * asked to "make the images" sees that a job for them is already running
+ * rather than starting another.
+ *
+ * Bounded by count, `max`, running before settled and newest first inside
+ * each. Times are absolute (UTC) rather than ages, so the block is the same
+ * text from one turn to the next until a job starts or settles, and the
+ * prompt cache holds in between. `null` when there is nothing to list.
+ */
+export declare function renderJobsBlock(jobs: AgentJobRecord[], max: number): string | null;
+//# sourceMappingURL=contextBlock.d.ts.map

package/dist/ai/jobs/contextBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextBlock.d.ts","sourceRoot":"","sources":["../../../ai/jobs/contextBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,gCAAgC;AAChC,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;CACzC,CAAC;AAKF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmClF"}

package/dist/ai/jobs/index.d.ts

@@ -0,0 +1,6 @@
+export { AgentJob, type AgentJobClass, type AgentJobContext, type AgentJobOutcome, AgentJobs, DEFAULT_JOB_DEADLINE_MS, type JobAttachments, type JobEditImageParams, type JobGenerateImageParams, JobHandle, JobsRequireThreadError, type RunJobs, type StartJobOptions, type ToolJobs, } from "./AgentJob";
+export { type AgentJobRecord, type AgentJobState, type AgentJobStore, type AgentJobUpdate, MemoryAgentJobStore, type NewAgentJobRecord, } from "./AgentJobStore";
+export { AgentJobDeadlineSweep } from "./AgentJobDeadlineSweep";
+export { type AgentJobsOptions, DEFAULT_JOBS_CONTEXT_MAX } from "./contextBlock";
+export { DatabaseAgentJobStore, type DatabaseAgentJobStoreOptions } from "./DatabaseAgentJobStore";
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../ai/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,SAAS,EACT,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,SAAS,EACT,sBAAsB,EACtB,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,mBAAmB,EACnB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,KAAK,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/ai/jobs/overlay.d.ts

@@ -0,0 +1,49 @@
+import type { Schema } from "../Schema";
+import type { AgentMessage } from "../types";
+import type { AgentJobRecord, AgentJobStore } from "./AgentJobStore";
+/**
+ * The thread with each background job's current state rendered over the tool
+ * result that points at it (#461).
+ *
+ * A tool that returned a `JobHandle` left a `running` result in the thread.
+ * The job settles later, into the job store, and never into the messages: a
+ * live run writes whole messages, and a settle racing those writes would be
+ * overwritten by the run's stale copy. So the messages are brought up to date
+ * here, when the thread is loaded, which `AgentController` does under the
+ * thread's lock before a turn and without writing for `readThread`.
+ *
+ * - A `running` result whose job settled becomes the job's `ok` or `error`
+ *   result, in place, with the job still named on it (`job`).
+ * - A `running` result whose job is still running is left exactly as it is,
+ *   so the request stays byte-identical, and the prompt cache with it, until
+ *   the job settles.
+ * - A `running` result whose job the store does not have becomes an `error`:
+ *   the record was lost (a memory store across a restart), and the work may or
+ *   may not have happened.
+ *
+ * `settled` is the messages that changed, for the caller to write back, so
+ * the store converges and a job settled long ago costs nothing on later loads.
+ *
+ * `orphans` are jobs whose tool result never reached the thread: the run died
+ * between starting the job and storing the result. They are found among the
+ * thread's newest jobs, only once the run that started them is gone, and only
+ * the ones not marked yet; the caller marks them (`orphaned`).
+ */
+export declare function overlayJobs(messages: AgentMessage[], params: {
+    threadId: string;
+    store: AgentJobStore;
+    isRunLive: (runId: string) => boolean | Promise<boolean>;
+    /** The tool's output schema, to check a settled output against. */
+    outputSchemaFor?: (toolName: string) => Schema<any> | undefined;
+    /** How many of the thread's newest jobs to read. At least 50. */
+    scan?: number;
+}): Promise<{
+    messages: AgentMessage[];
+    settled: AgentMessage[];
+    orphans: AgentJobRecord[];
+    /** The thread's newest jobs, as they stand after this pass: for the `<jobs>` block. */
+    jobs: AgentJobRecord[];
+}>;
+/** Marks orphans found by `overlayJobs`. Never throws: it is bookkeeping. */
+export declare function markOrphans(store: AgentJobStore, orphans: AgentJobRecord[], report: (error: unknown) => void): Promise<void>;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/ai/jobs/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../ai/jobs/overlay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAe,YAAY,EAAkB,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAiB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAOpF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,YAAY,EAAE,EACxB,MAAM,EAAE;IACN,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,mEAAmE;IACnE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAChE,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACA,OAAO,CAAC;IACT,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,uFAAuF;IACvF,IAAI,EAAE,cAAc,EAAE,CAAC;CACxB,CAAC,CA2DD;AAED,6EAA6E;AAC7E,wBAAsB,WAAW,CAC/B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,cAAc,EAAE,EACzB,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC/B,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/ai/providers/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../ai/providers/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,YAAY,EAAY,cAAc,EAAoB,MAAM,UAAU,CAAC;AAEzF;;;;;;;GAOG;AAKH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACzD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC3C,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,oBAAoB,CAAA;CAAE,GACzD,gBAAgB,CAuDlB;AAID;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,YAAY,EAAE,oBAAoB,EAClC,KAAK,CAAC,EAAE,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,EAAE,GACnD,kBAAkB,EAAE,CAmJtB;AA4QD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAuB7D;AAuFD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,EAAE,GAAG,SAAS,EAC/D,YAAY,EAAE,oBAAoB,GACjC,aAAa,EAAE,CA2CjB"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../ai/providers/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,YAAY,EAAY,cAAc,EAAoB,MAAM,UAAU,CAAC;AAEzF;;;;;;;GAOG;AAKH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACzD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC3C,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,oBAAoB,CAAA;CAAE,GACzD,gBAAgB,CAuDlB;AAID;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,YAAY,EAAE,oBAAoB,EAClC,KAAK,CAAC,EAAE,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,EAAE,GACnD,kBAAkB,EAAE,CAmJtB;AA4QD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAiC7D;AAuFD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,EAAE,GAAG,SAAS,EAC/D,YAAY,EAAE,oBAAoB,GACjC,aAAa,EAAE,CA2CjB"}