agents/dist/queue/index.d.ts

A home for your AI agents

import {
  _ as LifecycleJobContext,
  d as LifecycleRouteContext,
  s as LifecycleCapability,
  v as LifecycleJobOutcome
} from "../capability-runner-BUBa6Ake.js";
import { t as RetryOptions } from "../retries-D9B2UCq3.js";
import {
  a as QueuePayload,
  i as QueueItem,
  n as QueueCriteria,
  o as QueuePushOptions,
  r as QueueHandlers,
  t as QueueCallbacks
} from "../types-DCD6BNZH.js";

//#region src/queue/options.d.ts
/** Events emitted while a Queue creates, retries, or fails work. */
type QueueEventType = "queue:create" | "queue:retry" | "queue:error";
/**
 * Optional callbacks and policy for a Queue capability.
 *
 * @experimental The API surface may change before stabilizing.
 */
interface QueueOptions<Handlers extends QueueHandlers = QueueCallbacks> {
  /**
   * Named callbacks this Queue can run. Each item persists a callback name;
   * registration in a field initializer re-binds the names on every Durable
   * Object wake, so register unconditionally. Names outside this map are
   * rejected unless a composition-root resolver supplies them — the internal
   * aperture behind `Agent`'s name-based queue API.
   */
  readonly callbacks?: Handlers;
  /** Default callback retry policy. */
  readonly retry?: RetryOptions;
  /** Observe terminal callback errors. Runs as capability code without host context. */
  readonly onError?: (error: unknown) => void | Promise<void>;
}
//#endregion
//#region src/queue/queue.d.ts
/**
 * Durable background work for a Lifecycle Object.
 *
 * Register callbacks in the constructor and install the instance with
 * `Lifecycle.use()`. Each pushed item becomes a job due immediately in the
 * Lifecycle job queue; Lifecycle owns the physical alarm and the alarm event
 * loop, drives items one at a time in push order, retries a throwing
 * callback per its retry policy, and Queue runs registered callbacks through
 * Lifecycle's host invocation boundary. An item that still fails after its
 * last attempt is dropped after `queue:error` and the `onError` hook.
 *
 * Items survive the Durable Object leaving memory: an isolate that dies mid
 * callback wakes again on the Lifecycle deadman alarm and resumes the queue.
 * Callbacks should therefore be idempotent.
 *
 * @experimental The API surface may change before stabilizing.
 */
declare class Queue<
  Handlers extends QueueHandlers = QueueCallbacks
> extends LifecycleCapability {
  #private;
  /**
   * Create a durable Queue.
   *
   * @param options - Registered callbacks plus optional retry and error
   * policy. Registering `callbacks` types {@link push} against the map —
   * names and payloads are checked where the handlers are declared and where
   * they are pushed. Names outside the map are rejected unless a
   * composition-root resolver supplies them — the internal aperture behind
   * `Agent`'s name-based queue API.
   */
  constructor(options?: QueueOptions<Handlers>);
  /** Migrate legacy `cf_agents_queues` rows into the Lifecycle job queue. */
  onStart(): Promise<void>;
  /** Drive one due item dispatched by the Lifecycle event loop. */
  onJob(context: LifecycleJobContext): Promise<LifecycleJobOutcome | void>;
  /** Observe one item's terminal application failure; the item is dropped. */
  onJobError(
    context: LifecycleJobContext,
    error: unknown
  ): Promise<LifecycleJobOutcome | void>;
  /** Handle Queue protocol messages routed by another Lifecycle. */
  onRoute(context: LifecycleRouteContext): Promise<unknown>;
  /**
   * Push one item for a registered callback. The item is due immediately;
   * the Lifecycle alarm event loop runs it in push order after this call
   * returns.
   *
   * Once the Lifecycle has started (and this Queue is not routed through
   * another Lifecycle), the item row is written synchronously before this
   * method's promise is even returned, so a caller may pair a push with its
   * own writes in one synchronous block — the item then commits atomically
   * with them.
   */
  push<Name extends keyof Handlers & string>(
    callback: Name,
    payload?: QueuePayload<Handlers[Name]>,
    options?: QueuePushOptions
  ): Promise<QueueItem<QueuePayload<Handlers[Name]>>>;
  /** Cancel one pending item. Returns false when no item matched. */
  cancel(id: string): Promise<boolean>;
  /** Cancel every pending item, or every item for one callback. Returns the count. */
  cancelAll(callback?: string): Promise<number>;
  /** Read one pending item. */
  get<T = unknown>(id: string): Promise<QueueItem<T> | undefined>;
  /** List pending items in push order, optionally filtered by callback. */
  list<T = unknown>(criteria?: QueueCriteria): Promise<QueueItem<T>[]>;
  /** @internal Remove items owned by one routed Lifecycle subtree. */
  __DO_NOT_USE_WILL_BREAK__cleanupRoutePrefix(prefix: string): Promise<void>;
}
//#endregion
export {
  Queue,
  type QueueCallbacks,
  type QueueCriteria,
  type QueueEventType,
  type QueueHandlers,
  type QueueItem,
  type QueueOptions,
  type QueuePayload,
  type QueuePushOptions
};
//# sourceMappingURL=index.d.ts.map