agents/dist/durable-object-lifecycle-ei7M7lqB.d.ts

A home for your AI agents

import {
  T as WSMessage,
  b as LifecycleJobs,
  i as DurableObjectCapability,
  u as LifecycleRouteAddress
} from "./capability-runner-BUBa6Ake.js";
import { DurableObject } from "cloudflare:workers";

//#region src/lifecycle/durable-object-lifecycle.d.ts
/** Internal envelope transported between routed Lifecycle instances. */
type LifecycleRouteEnvelope = {
  readonly capability: string;
  readonly source: LifecycleRouteAddress | undefined;
  readonly payload: unknown;
};
/** Configuration accepted when constructing a {@link Lifecycle}. */
type LifecycleOptions = {
  /**
   * Consecutive alarm invocations that may end in a Durable Object
   * memory-limit reset before the circuit breaker (#1825) seals recovery
   * work instead of backing it off. Default: 3.
   */
  readonly maxAlarmMemoryLimitStrikes?: number;
};
declare class Lifecycle<
  Env extends object = Cloudflare.Env,
  Props extends Record<string, unknown> = Record<string, unknown>
> {
  #private;
  /**
   * Construct and install a lifecycle in one explicit operation.
   *
   * @param host - The Durable Object whose runtime handlers the lifecycle owns.
   * @returns The installed lifecycle.
   */
  static install<
    Env extends object,
    Props extends Record<string, unknown> = Record<string, unknown>
  >(
    host: DurableObject<Env>,
    options?: LifecycleOptions
  ): Lifecycle<Env, Props>;
  /**
   * Bind a lifecycle to a Durable Object instance without mutating its handlers.
   *
   * @param host - The Durable Object whose runtime lifecycle this object owns.
   * @param options - Policy configuration for this lifecycle.
   */
  constructor(host: DurableObject<Env>, options?: LifecycleOptions);
  /**
   * Install platform fetch, alarm, and hibernating WebSocket handlers.
   *
   * Existing handlers are preserved for framework-owned dispatch such as the
   * Agent's sub-agent router and alarm circuit breaker. Calling this method
   * more than once is an error.
   */
  installHandlers(): void;
  /**
   * Add a reusable capability before this lifecycle starts.
   *
   * Capabilities dispatch in registration order, except that a capability
   * declaring `claims: "catch-all"` always comes last, whenever it was
   * installed. Catch-alls are unique per dispatch hook: two may coexist
   * when they claim disjoint traffic (one `onRequest`, one
   * `onWebSocketUpgrade`), but a second catch-all for the same hook could
   * never be reached and is refused.
   *
   * @param capability - The capability to add.
   * @returns This lifecycle.
   */
  use(capability: DurableObjectCapability<Props>): this;
  /** @internal Deliver a generic capability envelope to this Lifecycle. */
  route(envelope: LifecycleRouteEnvelope): Promise<unknown>;
  /**
   * Execute SQL queries against the Durable Object's database
   * @template T Type of the returned rows
   * @param strings SQL query template strings
   * @param values Values to be inserted into the query
   * @returns Array of query results
   */
  sql<T = Record<string, string | number | boolean | null>>(
    strings: TemplateStringsArray,
    ...values: (string | number | boolean | null)[]
  ): T[];
  /**
   * Handle an incoming request for the owning Durable Object.
   *
   * Non-upgrade requests run through the capability middleware chain first,
   * then fall through to the host's `onRequest`.
   */
  fetch(request: Request): Promise<Response>;
  /** @internal Dispatch a hibernating WebSocket message. */
  webSocketMessage(ws: WebSocket, message: WSMessage): Promise<void>;
  /** @internal Dispatch a hibernating WebSocket close. */
  webSocketClose(
    ws: WebSocket,
    code: number,
    reason: string,
    wasClean: boolean
  ): Promise<void>;
  /** @internal Dispatch a hibernating WebSocket error. */
  webSocketError(ws: WebSocket, error: unknown): Promise<void>;
  /**
   * Start lifecycle capabilities and the owning Durable Object.
   *
   * Runtime fetch, alarm, and WebSocket entry points call this automatically.
   * RPC methods may call it explicitly because native RPC bypasses fetch.
   *
   * @param props - Optional properties supplied to capability and host startup.
   */
  start(props?: Props): Promise<void>;
  /**
   * The name used to address this Durable Object.
   *
   * Native `ctx.id.name` is authoritative. A read-only legacy storage fallback
   * lets objects created by older PartyServer releases migrate without new
   * name writes.
   */
  get name(): string;
  /**
   * The host's scoped access to the Lifecycle work queue. Items pushed here
   * are dispatched to the host's `onJob` inside the host invocation
   * boundary.
   */
  get jobs(): LifecycleJobs;
  /**
   * Recompute the physical Durable Object alarm from job-queue state.
   *
   * Concurrent requests are serialized so a later durable-state change cannot
   * be overwritten by an earlier alarm calculation. Queue mutations call this
   * automatically; it stays public for composition roots and tests.
   */
  rearmAlarm(): Promise<void>;
  /**
   * Keep work a job handed off at a bounded return inside the current
   * alarm's memory-limit breaker domain (#1825). Hosts call this where a
   * queue-driven callback detaches long work and returns.
   *
   * @returns True when called during an alarm invocation; false otherwise.
   */
  trackAlarmWork(work: Promise<unknown>): boolean;
  /** Dispose installed capabilities in reverse registration order. */
  dispose(): Promise<void>;
  /** Permanently disable and clear alarms during explicit object teardown. */
  disableAlarms(): Promise<void>;
  /**
   * Run one alarm invocation. The job driver owns the event loop — deadman
   * pre-arm, due-job dispatch with retry and deferral policy, the alarm
   * memory-limit circuit breaker (#1825) — and re-arms the physical alarm
   * from queue state. The host's `onAlarm()` runs after due jobs, inside
   * the host invocation boundary.
   */
  alarm(): Promise<void>;
}
//#endregion
export { LifecycleOptions as n, LifecycleRouteEnvelope as r, Lifecycle as t };
//# sourceMappingURL=durable-object-lifecycle-ei7M7lqB.d.ts.map