agents 0.22.0 → 0.24.0

package/dist/capability-runner-BUBa6Ake.d.ts

@@ -0,0 +1,484 @@
+import { t as RetryOptions } from "./retries-D9B2UCq3.js";
+
+//#region src/lifecycle/types.d.ts
+type ImmutablePrimitive = undefined | null | boolean | string | number;
+type Immutable<T> = T extends ImmutablePrimitive
+  ? T
+  : T extends Array<infer U>
+    ? ImmutableArray<U>
+    : T extends Map<infer K, infer V>
+      ? ImmutableMap<K, V>
+      : T extends Set<infer M>
+        ? ImmutableSet<M>
+        : ImmutableObject<T>;
+type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
+/** A payload delivered on a WebSocket connection. */
+type WSMessage = ArrayBuffer | ArrayBufferView | string;
+/** Immutable state persisted in a hibernating WebSocket attachment. */
+type ConnectionState<T> = ImmutableObject<T> | null;
+/** Functional update applied to a connection's current state. */
+type ConnectionSetStateFn<T> = (prevState: ConnectionState<T>) => T;
+/** Context supplied when a lifecycle accepts a WebSocket connection. */
+type ConnectionContext = {
+  /** Original WebSocket upgrade request. */ request: Request;
+};
+/** A WebSocket managed by a Durable Object lifecycle. */
+type Connection<TState = unknown> = WebSocket & {
+  /** Connection identifier */ id: string;
+  /**
+   * The URL of the original WebSocket upgrade request.
+   * Persisted in the WebSocket attachment so it survives hibernation.
+   */
+  uri: string | null;
+  /**
+   * Arbitrary state associated with this connection.
+   * Read-only — use {@link Connection.setState} to update.
+   *
+   * This property is configurable, meaning it can be redefined via
+   * `Object.defineProperty` by downstream consumers (e.g. the Cloudflare
+   * Agents SDK) to namespace or wrap internal state storage.
+   */
+  state: ConnectionState<TState>;
+  /**
+   * Update the state associated with this connection.
+   *
+   * Accepts either a new state value or an updater function that receives
+   * the previous state and returns the next state.
+   *
+   * This property is configurable, meaning it can be redefined via
+   * `Object.defineProperty` by downstream consumers that provide their own
+   * state projection.
+   */
+  setState(
+    state: TState | ConnectionSetStateFn<TState> | null
+  ): ConnectionState<TState>;
+  /**
+   * Tags returned by the owning Durable Object's `getConnectionTags` callback.
+   * Always includes the connection id as the first tag.
+   */
+  tags: readonly string[];
+};
+//#endregion
+//#region src/lifecycle/job-queue.d.ts
+/** One durable job in the Lifecycle queue. */
+type LifecycleJob = {
+  /** Unique job id. Stable across reschedules. */ readonly id: string /** Owning capability id, or `"host"`. */;
+  readonly capability: string /** Serialisable function name the owner dispatches on. */;
+  readonly fn: string /** Due time in epoch milliseconds. */;
+  readonly time: number /** Owner-defined payload, JSON round-tripped. */;
+  readonly payload: unknown /** Retry policy for dispatch, when the pusher supplied one. */;
+  readonly retry:
+    | RetryOptions
+    | undefined /** Whether the job is skipped while a previous run is in flight. */;
+  readonly singleflight: boolean /** Whether the job suppresses ordinary alarm candidates while pending. */;
+  readonly exclusive: boolean /** Whether the alarm memory-limit breaker governs this pending job (#1825). */;
+  readonly recoveryLoop: boolean /** Creation time in epoch seconds. */;
+  readonly createdAt: number;
+};
+/** Options accepted when pushing one job. */
+type LifecycleJobPushOptions = {
+  /** Serialisable function name the owner dispatches on. */ readonly fn: string /** Due time in epoch milliseconds. */;
+  readonly time: number /** Owner-defined payload. Must be JSON-serializable. */;
+  readonly payload?: unknown;
+  /**
+   * Stable job id. A push with an existing id replaces that job.
+   * Omitted ids are generated.
+   */
+  readonly id?: string /** Retry policy for dispatch, overriding the queue default. */;
+  readonly retry?: RetryOptions /** Skip this job while a previous run of it is still in flight. */;
+  readonly singleflight?: boolean;
+  /**
+   * Seconds before an in-flight single-flight run is treated as hung, and
+   * before any long dispatch triggers the slow-dispatch warning. Default: 30.
+   */
+  readonly hungTimeoutSeconds?: number /** Suppress ordinary alarm candidates while this job is pending. */;
+  readonly exclusive?: boolean;
+  /**
+   * Mark this job as part of a recovery loop that can deterministically
+   * exhaust memory. On an alarm memory-limit strike the circuit breaker
+   * (#1825) backs off every pending flagged job to the strike's backoff
+   * time, and purges them all when it seals at the strike budget — so a
+   * doomed loop cannot re-trigger through a sibling row while unrelated
+   * jobs stay untouched.
+   */
+  readonly recoveryLoop?: boolean;
+};
+/**
+ * What the owner tells Lifecycle after one job ran — the drive result.
+ *
+ * `undefined` (or no return) completes the job and deletes it.
+ * `{ rescheduleAt }` suspends the job until a future time.
+ * `"yield"` leaves the job due, waking again immediately.
+ *
+ * A same-id `push()` or `reschedule()` made while the job is dispatching
+ * supersedes the drive result: the newer durable intent wins, and the
+ * result is quietly discarded. Owners that both push and return outcomes
+ * for the same job should derive both from the same durable state so the
+ * two always agree.
+ */
+type LifecycleJobOutcome =
+  | undefined
+  | {
+      readonly rescheduleAt: number;
+    }
+  | "yield";
+/** Context supplied when a job is dispatched to its owner. */
+type LifecycleJobContext = {
+  /** The due job being executed. */ readonly job: LifecycleJob /** 1-indexed dispatch attempt within the current alarm invocation. */;
+  readonly attempt: number;
+};
+/** Job-queue access scoped to one owning capability. */
+type LifecycleJobs = {
+  /**
+   * Push one job. A push with an existing id replaces that job — ids are
+   * scoped to their owner, so replacing (or colliding with) another
+   * owner's job is impossible; a cross-owner id collision throws instead.
+   */
+  readonly push: (
+    options: LifecycleJobPushOptions
+  ) => Promise<LifecycleJob> /** Cancel one owned job. Returns false when no job matched. */;
+  readonly cancel: (
+    id: string
+  ) => Promise<boolean> /** Re-time one owned job. Returns false when no job matched. */;
+  readonly reschedule: (
+    id: string,
+    time: number
+  ) => Promise<boolean> /** Read one owned job. */;
+  readonly get: (
+    id: string
+  ) =>
+    | LifecycleJob
+    | undefined /** List every owned job, ordered by due time. */;
+  readonly list: () => LifecycleJob[];
+  /**
+   * Recompute the physical alarm from queue state without mutating it.
+   * Mutations re-arm automatically; use this only to recover a lost alarm
+   * for existing jobs (e.g. an idempotent push that deduplicated).
+   */
+  readonly rearm: () => Promise<void>;
+};
+//#endregion
+//#region src/lifecycle/capability.d.ts
+/** Opaque address understood by a Lifecycle routing transport. */
+type LifecycleRouteAddress = {
+  /** Stable equality and storage key. */ readonly key: string /** Transport-owned serialized address. */;
+  readonly data: string;
+};
+/** Context supplied with a routed capability message. */
+type LifecycleRouteContext = {
+  /** Address of the sending Lifecycle, or undefined for an unrouted root. */ readonly source:
+    | LifecycleRouteAddress
+    | undefined /** Capability-owned message payload. */;
+  readonly payload: unknown;
+};
+/** Startup state of a Lifecycle. */
+type LifecycleStatus = "zero" | "starting" | "started";
+/** Best-effort telemetry available to every Lifecycle capability. */
+type LifecycleEvents = {
+  /** Publish an event under this capability's stable identity. */ readonly emit: (
+    type: string,
+    payload: unknown
+  ) => void;
+};
+/** Routing available to every Lifecycle capability. */
+type LifecycleRoutes = {
+  /** This Lifecycle's transport address, or undefined at the route root. */ readonly source:
+    | LifecycleRouteAddress
+    | undefined /** Route a capability-owned message to the root Lifecycle. */;
+  readonly toRoot: (
+    payload: unknown
+  ) => Promise<unknown> /** Route a capability-owned message to another Lifecycle. */;
+  readonly to: (
+    target: LifecycleRouteAddress,
+    payload: unknown
+  ) => Promise<unknown>;
+};
+/**
+ * Ambient scope a capability supplies when entering host context on
+ * behalf of a live connection or request.
+ */
+type LifecycleHostContextScope = {
+  /** The connection the callback runs on behalf of, when there is one. */ readonly connection?: Connection /** The request the callback runs on behalf of, when there is one. */;
+  readonly request?: Request;
+};
+/**
+ * The platform's hibernatable-socket surface, exposed narrowly so a
+ * capability that owns connections (e.g. WebSockets) can accept and
+ * enumerate them without holding the whole `DurableObjectState`.
+ * These are workerd API names, not Lifecycle modeling sockets.
+ */
+type LifecycleSockets = {
+  /** Accept a socket into hibernation under the given tags. */ readonly accept: (
+    ws: WebSocket,
+    tags: string[]
+  ) => void /** Every hibernated socket on the object, optionally by tag. */;
+  readonly get: (tag?: string) => WebSocket[];
+};
+/**
+ * Standard services granted to every installed Lifecycle capability.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type LifecycleServices = {
+  /** The host's Durable Object name; see `Lifecycle.name`. */ readonly name: string /** The host class name, as exported from the Worker. */;
+  readonly className: string;
+  readonly storage: DurableObjectStorage;
+  readonly sockets: LifecycleSockets;
+  readonly ready: () => Promise<void>;
+  /**
+   * Startup state: `"zero"` before startup, `"starting"` while capability
+   * and host startup hooks run, `"started"` once `ready()` resolves without
+   * waiting.
+   */
+  readonly status: () => LifecycleStatus;
+  /**
+   * This capability's scoped access to the Lifecycle-owned work queue.
+   * Pushed items are dispatched to `onJob` when due; every queue mutation
+   * re-arms the physical alarm automatically.
+   */
+  readonly jobs: LifecycleJobs;
+  /**
+   * Keep work this capability hands off at a bounded `onJob` return inside
+   * the current alarm's memory-limit breaker domain (#1825). Returns false,
+   * tracking nothing, outside an alarm invocation.
+   */
+  readonly trackAlarmWork: (work: Promise<unknown>) => boolean;
+  /**
+   * Run a capability-held user callback inside the host invocation context.
+   * Capability hooks run outside host context; this is the one boundary for
+   * entering it, and a host composition root may substitute its own wrapper
+   * (Agent adds tracing span scope). Pass `scope` to make a live
+   * connection or request ambient for the callback.
+   */
+  readonly runInHostContext: (
+    fn: () => unknown,
+    scope?: LifecycleHostContextScope
+  ) => Promise<unknown>;
+  readonly events: LifecycleEvents;
+  readonly routes: LifecycleRoutes;
+};
+/**
+ * Base class for capabilities that consume standard Lifecycle services.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare abstract class LifecycleCapability<Props extends object = object> {
+  readonly capabilityId: string;
+  /** How this capability claims traffic; see {@link DurableObjectCapability.claims}. */
+  readonly claims: "selective" | "catch-all";
+  protected constructor(capabilityId: string);
+  /** Default startup hook; capabilities override when they own startup work. */
+  onStart(_context: CapabilityStartContext<Props>): void;
+  /** Standard services when installed, or undefined in isolated unit tests. */
+  protected get lifecycleServices(): LifecycleServices | undefined;
+  /** Standard services supplied when Lifecycle installs this capability. */
+  protected get lifecycle(): LifecycleServices;
+}
+//#endregion
+//#region src/lifecycle/capability-runner.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/** One best-effort event published by a Lifecycle capability. */
+type LifecycleEvent = {
+  /** Stable capability or subsystem name. */ readonly source: string /** Stable event name within that source. */;
+  readonly type: string /** Event-specific data. */;
+  readonly payload: unknown;
+};
+/** Context supplied when durable capabilities start. */
+type CapabilityStartContext<Props extends object = object> = {
+  /** Properties supplied while resolving the Durable Object. */ readonly props:
+    | Props
+    | undefined;
+};
+/** Context supplied when durable capabilities inspect an HTTP request. */
+type CapabilityRequestContext = {
+  /** The request entering the Durable Object. */ readonly request: Request;
+};
+/** Context supplied when a capability inspects a WebSocket upgrade. */
+type CapabilityWebSocketUpgradeContext = {
+  /** The WebSocket upgrade request entering the Durable Object. */ readonly request: Request;
+};
+/**
+ * Context supplied when the alarm memory-limit circuit breaker records a
+ * strike (#1825), to capabilities and the host alike.
+ */
+type MemoryLimitContext = {
+  /** Whether the breaker hit its strike budget and sealed recovery work. */ readonly sealed: boolean /** The backoff wake time (epoch ms) armed for an unsealed strike. */;
+  readonly nextTime?: number;
+  /**
+   * The queue job that was executing when the strike landed. Absent when the
+   * reset happened during startup or host alarm work. Lifecycle has already
+   * backed off or purged its row before invoking memory-limit policy.
+   *
+   * Capabilities whose durable state outlives their queue row use this to
+   * apply the same policy to the underlying work — Tasks routes a struck
+   * routed job's owner this way (see `setTaskRoutedMemoryLimitHandler`).
+   */
+  readonly executing?: LifecycleJob;
+  /**
+   * Recovery-loop jobs removed when this strike sealed the breaker. This is
+   * a pre-purge snapshot because the durable rows no longer exist when
+   * policy hooks run. No current capability reads this — Scheduler's own
+   * former use of it (routing a sealed strike to every purged row's owning
+   * dynamic agent) was retired once Tasks took over routed chat-recovery
+   * wakes — but it stays available for a capability whose routed rows can
+   * be purged as a pack, unlike Tasks' one-run-at-a-time model.
+   */
+  readonly purgedRecoveryLoopJobs?: ReadonlyArray<LifecycleJob>;
+};
+/**
+ * A capability installed into a Durable Object lifecycle.
+ *
+ * Capabilities extending `LifecycleCapability` receive the standard storage,
+ * readiness, alarm, event, and routing surface. Host-specific bindings and
+ * protocol adapters remain explicit constructor dependencies. Hook parameters
+ * carry only phase data; hooks do not run in ambient host context — a
+ * capability-held user callback re-enters host context exactly once,
+ * through `LifecycleServices.runInHostContext(fn, scope)`.
+ *
+ * A capability interacts with Lifecycle through exactly three channels:
+ * these declared hooks, the `LifecycleServices` surface, and
+ * composition-root `set*()` apertures. Any other direct reach in either
+ * direction is a design smell.
+ *
+ * Dispatch contract, hook by hook:
+ * - `onRequest` and `onWebSocketUpgrade` are offered in declaration
+ *   order, the catch-all last; the first capability to return a `Response`
+ *   claims the request, and a claimed upgrade's socket belongs to that
+ *   capability for its whole lifetime.
+ * - `onWebSocketMessage`/`onWebSocketClose`/`onWebSocketError` are
+ *   platform wakes, offered in declaration order; return `true` to
+ *   consume one. Socket ownership is the capability's to determine —
+ *   keep a private hibernation-attachment namespace and recognize your
+ *   own sockets by it.
+ * - `onRoute` is addressed to one capability by its id; `onJob` is
+ *   addressed by the due job's owning capability, with Lifecycle owning
+ *   the queue and the one physical alarm.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface DurableObjectCapability<Props extends object = object> {
+  /**
+   * How this capability claims traffic. Default: `"selective"`.
+   *
+   * A `"selective"` capability answers only requests and upgrades it
+   * recognizes and declines the rest. A `"catch-all"` claims everything
+   * offered to the hooks it implements, so Lifecycle always places it
+   * last, whenever it was installed, and refuses a second catch-all for
+   * the same hook. Catch-alls for disjoint hooks coexist: `WebSockets`
+   * claims every upgrade and implements no `onRequest`, so an HTTP
+   * catch-all installs beside it. Selective HTTP capabilities target
+   * their own routes and run before either.
+   */
+  readonly claims?: "selective" | "catch-all";
+  /** Initialize or recover the capability before the host handles work. */
+  onStart?(context: CapabilityStartContext<Props>): MaybePromise<void>;
+  /**
+   * Act as middleware over HTTP requests, ahead of the host's request handler.
+   *
+   * Return a response to handle the request, or `undefined` to pass it to the
+   * next capability and finally the host.
+   */
+  onRequest?(
+    context: CapabilityRequestContext
+  ): MaybePromise<Response | undefined | void>;
+  /**
+   * Claim a WebSocket upgrade before the host's legacy connection path.
+   *
+   * A capability that returns a response owns that socket and its lifetime,
+   * including any hibernation attachment it needs to recognize the socket
+   * later. Return `undefined` to decline.
+   */
+  onWebSocketUpgrade?(
+    context: CapabilityWebSocketUpgradeContext
+  ): MaybePromise<Response | undefined | void>;
+  /**
+   * Handle a platform `webSocketMessage` wake for a socket this capability
+   * owns. Return `true` to consume the event; anything else offers it to
+   * the next capability and finally the host's legacy path. Ownership is
+   * the capability's to determine — typically via its own hibernation
+   * attachment namespace.
+   */
+  onWebSocketMessage?(
+    ws: WebSocket,
+    message: WSMessage
+  ): MaybePromise<boolean | void>;
+  /** Handle a platform `webSocketClose` wake for an owned socket. */
+  onWebSocketClose?(
+    ws: WebSocket,
+    code: number,
+    reason: string,
+    wasClean: boolean
+  ): MaybePromise<boolean | void>;
+  /** Handle a platform `webSocketError` wake for an owned socket. */
+  onWebSocketError?(
+    ws: WebSocket,
+    error: unknown
+  ): MaybePromise<boolean | void>;
+  /**
+   * Drive one due job this capability pushed into the Lifecycle queue.
+   * Return an outcome to reschedule or retain the job; returning nothing
+   * completes it.
+   *
+   * Dispatch must be bounded: the event loop awaits each job inline, so a
+   * long-running `onJob` delays every other job on this object. Detach
+   * unbounded work (start it, keep durable evidence, return) instead of
+   * awaiting it here; a dispatch that outlives the job's hung timeout
+   * logs a warning and emits `job:slow_dispatch`.
+   */
+  onJob?(
+    context: LifecycleJobContext
+  ): MaybePromise<LifecycleJobOutcome | void>;
+  /**
+   * Observe one job's terminal application failure after retry exhaustion.
+   * The returned outcome decides advancement; returning nothing completes
+   * the job.
+   */
+  onJobError?(
+    context: LifecycleJobContext,
+    error: unknown
+  ): MaybePromise<LifecycleJobOutcome | void>;
+  /**
+   * Apply domain policy after the alarm memory-limit circuit breaker
+   * records a strike (#1825). Lifecycle has already handled the queue: the
+   * executing job and every `recoveryLoop`-flagged job are backed off (or
+   * purged when `sealed`). Runs at the outermost alarm frame, post-unwind,
+   * best-effort — the isolate resets right after, so keep writes small.
+   */
+  onMemoryLimit?(context: MemoryLimitContext): MaybePromise<void>;
+  /** Handle one message routed to this capability identity. */
+  onRoute?(context: LifecycleRouteContext): MaybePromise<unknown>;
+  /** Release live or in-memory resources during explicit host destruction. */
+  dispose?(): MaybePromise<void>;
+}
+//#endregion
+export {
+  ConnectionSetStateFn as C,
+  ConnectionContext as S,
+  WSMessage as T,
+  LifecycleJobContext as _,
+  LifecycleEvent as a,
+  LifecycleJobs as b,
+  LifecycleEvents as c,
+  LifecycleRouteContext as d,
+  LifecycleRoutes as f,
+  LifecycleJob as g,
+  LifecycleStatus as h,
+  DurableObjectCapability as i,
+  LifecycleHostContextScope as l,
+  LifecycleSockets as m,
+  CapabilityStartContext as n,
+  MemoryLimitContext as o,
+  LifecycleServices as p,
+  CapabilityWebSocketUpgradeContext as r,
+  LifecycleCapability as s,
+  CapabilityRequestContext as t,
+  LifecycleRouteAddress as u,
+  LifecycleJobOutcome as v,
+  ConnectionState as w,
+  Connection as x,
+  LifecycleJobPushOptions as y
+};
+//# sourceMappingURL=capability-runner-BUBa6Ake.d.ts.map