agents 0.22.0 → 0.23.0

package/dist/tasks-BRJ5zgya.d.ts

@@ -0,0 +1,517 @@
+import {
+  _ as LifecycleJobOutcome,
+  d as LifecycleRouteContext,
+  g as LifecycleJobContext,
+  o as MemoryLimitContext,
+  s as LifecycleCapability
+} from "./capability-runner-Be_-PLR1.js";
+
+//#region src/tasks/duration.d.ts
+/**
+ * Duration parsing for the Tasks capability. Durations appear in step
+ * retry delays, per-attempt timeouts, and durable sleeps.
+ */
+/** Units accepted in a {@link TaskDurationString}. */
+type TaskDurationUnit = "second" | "minute" | "hour" | "day" | "week";
+/**
+ * A human-readable duration such as `"10 seconds"` or `"1 day"`.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskDurationString = `${number} ${TaskDurationUnit}${"" | "s"}`;
+//#endregion
+//#region src/tasks/types.d.ts
+/**
+ * JSON-serializable data accepted as Task input, step results, metadata,
+ * and final results.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskJson =
+  | string
+  | number
+  | boolean
+  | null
+  | TaskJson[]
+  | {
+      [key: string]: TaskJson;
+    };
+/**
+ * A value a Task handler or step callback may produce. `undefined` and
+ * `void` persist as SQL `NULL` and restore as `undefined`.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskValue = TaskJson | undefined | void;
+/**
+ * Constraint for a Tasks definitions map: named handlers invoked from the
+ * beginning on every execution attempt, with completed steps returning
+ * journaled results instead of running again. An unclean interruption —
+ * process loss mid-attempt — replays the handler the same way; durable
+ * progress lives in the step journal and in whatever durable state the
+ * handler wrote (a stream's cursor, an idempotent external write), so
+ * handlers resume from evidence instead of receiving a recovery callback.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskHandlers = Record<
+  string,
+  (input: never, step: TaskStep) => TaskValue | Promise<TaskValue>
+>;
+/**
+ * Default definitions surface for a Tasks constructed without a typed map:
+ * any name compiles with an untyped input. At runtime a name must be
+ * declared in the constructor map or supplied by a composition-root
+ * resolver; a bare Tasks rejects it otherwise.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskCallbacks = Record<
+  string,
+  (input: unknown, step: TaskStep) => TaskValue | Promise<TaskValue>
+>;
+/**
+ * The input type a registered Task definition accepts.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskInput<Handler> = Handler extends (
+  input: infer Input,
+  ...rest: never[]
+) => unknown
+  ? Input
+  : never;
+/**
+ * The settled output type a registered Task definition produces.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskOutput<Handler> = Handler extends (...args: never[]) => infer Output
+  ? Awaited<Output> extends TaskValue
+    ? Awaited<Output>
+    : never
+  : never;
+/**
+ * Per-attempt context passed to a `step.do()` callback.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface TaskStepAttempt {
+  /** One-based attempt number for this named step. */
+  readonly attempt: number;
+  /**
+   * Stable external deduplication key for this step: identical across
+   * attempts and replays of the same run.
+   */
+  readonly idempotencyKey: string;
+  /** Aborted on cancellation or when this attempt's timeout elapses. */
+  readonly signal: AbortSignal;
+}
+/**
+ * Retry and timeout policy for one `step.do()` call.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface TaskStepConfig {
+  retries?: {
+    /** Total attempts, including the first. */ limit?: number /** Delay before the first retry. */;
+    delay?:
+      | number
+      | TaskDurationString /** Delay growth across retries. Defaults to exponential. */;
+    backoff?: "constant" | "linear" | "exponential";
+  };
+  /** Timeout of one callback attempt. */
+  timeout?: number | TaskDurationString;
+}
+/**
+ * The step API a Task handler receives. Named steps are the run's durable
+ * journal: `do` memoizes completed results, sleeps persist their first
+ * deadline, and both suspend the execution attempt rather than holding the
+ * invocation open.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface TaskStep {
+  /**
+   * The step an unclean interruption left mid-execution, or `null` on a
+   * clean attempt — the durable evidence a replayed handler branches on
+   * before re-entering irreversible work. Populated when a lost attempt's
+   * claim is taken over; a retry park or first attempt sees `null`.
+   */
+  readonly interrupted: {
+    readonly name: string;
+    readonly attempt: number;
+  } | null;
+  /** Run a named step once, replaying its journaled result thereafter. */
+  do<T extends TaskValue>(
+    name: string,
+    callback: (attempt: TaskStepAttempt) => T | Promise<T>
+  ): Promise<T>;
+  do<T extends TaskValue>(
+    name: string,
+    config: TaskStepConfig,
+    callback: (attempt: TaskStepAttempt) => T | Promise<T>
+  ): Promise<T>;
+  /**
+   * Sleep durably. The first recorded deadline is authoritative; replays
+   * before it suspend again, replays after it continue.
+   */
+  sleep(name: string, duration: number | TaskDurationString): Promise<void>;
+  /** Sleep durably until a wall-clock time. */
+  sleepUntil(name: string, when: number | Date): Promise<void>;
+  /**
+   * Update observable progress. Replays stay silent until execution reaches
+   * new ground, so old progress is not re-published as new.
+   */
+  status(message: string): Promise<void>;
+  /** The stable external deduplication key `step.do(name, ...)` would get. */
+  idempotencyKey(name: string): string;
+}
+/**
+ * States a Task run moves through.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskRunState =
+  | "pending"
+  | "running"
+  | "waiting"
+  | "completed"
+  | "failed"
+  | "cancelled";
+/** Why a waiting run is waiting. */
+type TaskWaitReason = "sleep" | "retry";
+/** Safe projection of an error retained with a failed run. */
+interface TaskError {
+  name: string;
+  message: string;
+}
+/**
+ * Options accepted when starting one Task run.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface TaskRunOptions {
+  /** Stable key deduplicating repeated acceptance attempts onto one run. */
+  idempotencyKey?: string;
+  /** Caller-selected run ID. Generated when omitted. */
+  runId?: string;
+  /** JSON metadata retained with the run. */
+  metadata?: Record<string, TaskJson>;
+  /** Keep terminal state for inspection. Defaults to `true`. */
+  retain?: boolean;
+}
+/**
+ * Durable acceptance receipt returned by `Task.run()`. `accepted: false`
+ * means an existing run matched `runId` or `idempotencyKey`; it is not an
+ * error.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface TaskReceipt {
+  runId: string;
+  definition: string;
+  accepted: boolean;
+  state: TaskRunState;
+  createdAt: number;
+}
+/**
+ * Read-only snapshot of one Task run, discriminated by state.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type TaskRunSnapshot<Output extends TaskValue> =
+  | {
+      runId: string;
+      definition: string;
+      state: "pending";
+      createdAt: number;
+      metadata?: Record<string, TaskJson>;
+    }
+  | {
+      runId: string;
+      definition: string;
+      state: "running";
+      attempt: number;
+      startedAt: number;
+      createdAt: number;
+      statusMessage?: string;
+      metadata?: Record<string, TaskJson>;
+    }
+  | {
+      runId: string;
+      definition: string;
+      state: "waiting";
+      reason: TaskWaitReason;
+      wakeAt: number;
+      createdAt: number;
+      statusMessage?: string;
+      metadata?: Record<string, TaskJson>;
+    }
+  | {
+      runId: string;
+      definition: string;
+      state: "completed";
+      result: Output;
+      createdAt: number;
+      settledAt: number;
+      metadata?: Record<string, TaskJson>;
+    }
+  | {
+      runId: string;
+      definition: string;
+      state: "failed";
+      error: TaskError;
+      createdAt: number;
+      settledAt: number;
+      metadata?: Record<string, TaskJson>;
+    }
+  | {
+      runId: string;
+      definition: string;
+      state: "cancelled";
+      reason?: string;
+      createdAt: number;
+      settledAt: number;
+      metadata?: Record<string, TaskJson>;
+    };
+/**
+ * Typed handle for one named Task definition, returned by
+ * `tasks.create()`. The handle holds no state of its own; it addresses runs
+ * of its definition through the owning capability.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface Task<Input, Output extends TaskValue> {
+  readonly name: string;
+  /** Durably accept a run and return without waiting for terminal state. */
+  run(input: Input, options?: TaskRunOptions): Promise<TaskReceipt>;
+  /** Read one run of this definition. */
+  get(runId: string): Promise<TaskRunSnapshot<Output> | null>;
+  /** Read one run of this definition by its idempotency key. */
+  getByIdempotencyKey(
+    idempotencyKey: string
+  ): Promise<TaskRunSnapshot<Output> | null>;
+  /** Request cooperative cancellation. True when a live run was cancelled. */
+  cancel(runId: string, reason?: string): Promise<boolean>;
+}
+//#endregion
+//#region src/tasks/options.d.ts
+/** Events emitted while Tasks accepts, executes, retries, or settles runs. */
+type TaskEventType =
+  | "task:accepted"
+  | "task:attempt:started"
+  | "task:attempt:interrupted"
+  | "task:step:started"
+  | "task:step:retry"
+  | "task:step:completed"
+  | "task:waiting"
+  | "task:completed"
+  | "task:failed"
+  | "task:cancelled"
+  | "task:deleted";
+/**
+ * Definitions and policy for a Tasks capability.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface TasksOptions<Handlers extends TaskHandlers = TaskCallbacks> {
+  /**
+   * Named Task definitions this capability can run. Each run row persists a
+   * definition name; declaring the map in the constructor re-registers the
+   * names on every Durable Object wake, so recovery of in-flight runs is
+   * correct by construction. Names outside this map are rejected unless a
+   * composition-root resolver supplies them.
+   */
+  readonly definitions?: Handlers;
+  /** Default step retry policy, overridable per `step.do()`. */
+  readonly retries?: TaskStepConfig["retries"];
+  /** Default timeout of one step callback attempt. Default: 5 minutes. */
+  readonly stepTimeout?: number | TaskDurationString;
+  /** Observe terminal run failures. Runs inside the host invocation context. */
+  readonly onError?: (error: unknown) => void | Promise<void>;
+}
+//#endregion
+//#region src/tasks/tasks.d.ts
+/** Filters accepted by {@link Tasks.list}. */
+type TaskListOptions = {
+  definition?: string;
+  status?: TaskRunState | TaskRunState[];
+  limit?: number;
+};
+/** Filters accepted by {@link Tasks.delete}. */
+type TaskDeleteOptions = {
+  status?: Array<"completed" | "failed" | "cancelled">;
+  settledBefore?: Date;
+  limit?: number;
+};
+/**
+ * Durable replayable execution for a Lifecycle Object.
+ *
+ * Declare named definitions in the constructor and install the instance with
+ * `Lifecycle.use()`. The constructor map is the registry: it is rebuilt on
+ * every Durable Object wake, so in-flight runs always resolve their
+ * persisted definition names. Each definition's handler replays from the
+ * beginning on every execution attempt; completed steps return journaled
+ * results, sleeps consult persisted deadlines, and interrupted work
+ * continues from the first unfinished step after process loss.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class Tasks<
+  Handlers extends TaskHandlers = TaskCallbacks
+> extends LifecycleCapability {
+  #private;
+  /**
+   * Create a Tasks capability.
+   *
+   * @param options - Named definitions plus default step retry/timeout
+   * policy and alarm batching. Declaring `definitions` types {@link run} and
+   * {@link handle} against the map — names and inputs are checked where the
+   * handlers are declared and where runs start. Names outside the map are
+   * rejected unless a composition-root resolver supplies them.
+   */
+  constructor(options?: TasksOptions<Handlers>);
+  /**
+   * @internal Framework aperture: register one reserved (`__cf`-prefixed)
+   * Task definition directly on this instance, bypassing the constructor's
+   * `definitions` map so a host's own subclass layers can each declare their
+   * own `definitions` / `taskDefinitions` field without colliding with — or
+   * being silently clobbered by — a framework's internal names. Call once per
+   * name from the owning host's own constructor, unconditionally, so the
+   * definition is rebuilt identically on every Durable Object wake: an
+   * in-flight run resolves the same handler for its persisted definition name
+   * every time, or it cannot resume.
+   *
+   * Throws if `name` does not carry the reserved `__cf` prefix — this is not
+   * a general-purpose registration path; declare ordinary definitions in the
+   * constructor's `definitions` map instead — or if `name` is already
+   * registered, which is always a real conflict: this method runs exactly
+   * once per name per Tasks construction.
+   */
+  register(name: string, definition: TaskCallbacks[string]): void;
+  /**
+   * Durably accept one run of a declared definition and return a receipt
+   * without waiting for terminal state. The same `idempotencyKey` or `runId`
+   * joins the existing run (`accepted: false`) instead of creating a second.
+   */
+  run<Name extends keyof Handlers & string>(
+    definition: Name,
+    input?: TaskInput<Handlers[Name]>,
+    options?: TaskRunOptions
+  ): Promise<TaskReceipt>;
+  /**
+   * A typed handle scoped to one declared definition: its `run`, `get`,
+   * `getByIdempotencyKey`, and `cancel` see only that definition's runs. The
+   * handle is a pure lens over this capability — it holds no state and may
+   * be created at any time.
+   */
+  handle<Name extends keyof Handlers & string>(
+    definition: Name
+  ): Task<TaskInput<Handlers[Name]>, TaskOutput<Handlers[Name]>>;
+  /** Migrate storage and reconcile run deadlines during Lifecycle startup. */
+  onStart(): Promise<void>;
+  /** Drive one due run's wake dispatched by the Lifecycle event loop. */
+  onJob(context: LifecycleJobContext): Promise<LifecycleJobOutcome | void>;
+  /**
+   * Alarm memory-limit breaker policy (#1825) for the run whose wake struck.
+   *
+   * The run row is the durable source of truth: startup reconciliation
+   * re-derives due-now wakes from it, so the breaker's queue-row backoff
+   * and purge alone cannot contain a run whose attempt deterministically
+   * exhausts memory — a fresh isolate would resurrect it immediately. On a
+   * strike the run's claim is stripped and its deadline pushed to the
+   * backoff wake: the row keeps its state, so a struck `running` row still
+   * reads as an interrupted attempt (`step.interrupted`) when it is
+   * reclaimed, while reconciliation leaves the claimless row alone instead
+   * of flooring its deadline to now. When the breaker seals, the run
+   * terminally fails with an observable `task:failed` outcome.
+   */
+  onMemoryLimit(context: MemoryLimitContext): Promise<void>;
+  /**
+   * @internal Framework aperture: durably accept one run — reserved
+   * (`__cf`-prefixed) definition names included, which the public `run()`
+   * refuses so users cannot start framework runs — and drive its first
+   * attempt in the caller's invocation, resolving when that attempt reaches
+   * its next durable boundary. The receipt's run may already be terminal
+   * when this resolves; callers that need the outcome read it from their own
+   * channel (the run handler settles it) or from the snapshot.
+   */
+  __DO_NOT_USE_WILL_BREAK__runAttached(
+    definition: string,
+    input: unknown,
+    options?: TaskRunOptions
+  ): Promise<TaskReceipt>;
+  /**
+   * @internal Framework aperture: durably accept one run — reserved names
+   * included — and leave its first attempt to the durable queue wake instead
+   * of warm-starting it in the caller's invocation. Chat recovery uses this
+   * so a continuation always runs under an alarm, where `trackAlarmWork`
+   * keeps its model turn inside the memory-limit breaker domain.
+   */
+  __DO_NOT_USE_WILL_BREAK__enqueue(
+    definition: string,
+    input: unknown,
+    options?: TaskRunOptions
+  ): Promise<TaskReceipt>;
+  /** Handle Tasks protocol messages routed by another Lifecycle. */
+  onRoute(context: LifecycleRouteContext): Promise<unknown>;
+  /**
+   * @internal Framework aperture: bulk-cancel this root's routed wake
+   * mirrors for every run owned by a deleted facet subtree. The runs and
+   * their step journals live on the deleted facets' own storage and are
+   * wiped with them; only this root's mirror job needs an explicit cancel,
+   * or it stays due forever, retrying a dispatch to a facet that is gone.
+   */
+  __DO_NOT_USE_WILL_BREAK__cleanupRoutePrefix(prefix: string): Promise<void>;
+  /** Read one run by ID across all definitions. */
+  get(runId: string): Promise<TaskRunSnapshot<TaskValue> | null>;
+  /** Read one run by idempotency key across all definitions. */
+  getByIdempotencyKey(
+    idempotencyKey: string
+  ): Promise<TaskRunSnapshot<TaskValue> | null>;
+  /** List runs, newest first. */
+  list(options?: TaskListOptions): Promise<TaskRunSnapshot<TaskValue>[]>;
+  /**
+   * Request cooperative cancellation of one run.
+   *
+   * A live attempt is aborted and settles as cancelled at its next step
+   * boundary; a parked run settles immediately.
+   *
+   * @returns True when a non-terminal run accepted the request.
+   */
+  cancel(runId: string, reason?: string): Promise<boolean>;
+  /**
+   * Delete retained terminal runs and their step journals.
+   *
+   * @returns The number of runs deleted.
+   */
+  delete(options?: TaskDeleteOptions): Promise<number>;
+}
+//#endregion
+export {
+  TaskDurationUnit as C,
+  TaskDurationString as S,
+  TaskStep as _,
+  TasksOptions as a,
+  TaskValue as b,
+  TaskError as c,
+  TaskJson as d,
+  TaskOutput as f,
+  TaskRunState as g,
+  TaskRunSnapshot as h,
+  TaskEventType as i,
+  TaskHandlers as l,
+  TaskRunOptions as m,
+  TaskListOptions as n,
+  Task as o,
+  TaskReceipt as p,
+  Tasks as r,
+  TaskCallbacks as s,
+  TaskDeleteOptions as t,
+  TaskInput as u,
+  TaskStepAttempt as v,
+  TaskWaitReason as x,
+  TaskStepConfig as y
+};
+//# sourceMappingURL=tasks-BRJ5zgya.d.ts.map