agents/dist/index-Dlgtd3Mj.d.ts

A home for your AI agents

import {
  s as LifecycleCapability,
  x as Connection
} from "./capability-runner-BUBa6Ake.js";
//#region src/state/index.d.ts
/**
 * Source of a state change: `"server"` for host code (e.g. `setState()`), or
 * the {@link Connection} the change arrived from. Hosts use it to exclude the
 * originating connection from a broadcast.
 */
type StateChangeSource = Connection | "server";
/**
 * Options for a {@link State} capability. Validation and the post-change hook
 * stay on the host, which passes them in; the capability owns storage and
 * change ordering.
 *
 * @experimental The API surface may change before stabilizing.
 */
interface StateOptions<T = unknown> {
  /** Seeded on first access when nothing is stored. `undefined` seeds nothing. */
  readonly initialState?: T;
  /** Called after a change is validated and persisted. May be async. */
  readonly onChanged?: (
    state: T,
    source: StateChangeSource
  ) => void | Promise<void>;
  /**
   * Synchronous gating hook run before a change is persisted. Throw to reject
   * the change; the throw propagates to the caller of {@link State.set}.
   */
  readonly validateStateChange?: (
    nextState: T,
    source: StateChangeSource
  ) => void;
}
/**
 * Durable state storage for a Lifecycle Object.
 *
 * Owns the `cf_agents_state` state row, lazy load with an in-memory cache, and
 * validated persistence. Install the instance with `Lifecycle.use()`. State
 * validation and the post-change notification hook stay on the host, which
 * injects both callbacks. This capability never touches connections.
 *
 * @experimental The API surface may change before stabilizing.
 */
declare class State<T = unknown> extends LifecycleCapability {
  #private;
  /**
   * Create a durable state capability.
   *
   * @param options - Optional initial state and a synchronous validation hook
   * injected by the host.
   */
  constructor(options?: StateOptions<T>);
  /** Initialize state storage during Lifecycle startup. */
  onStart(): Promise<void>;
  /**
   * Current state.
   *
   * Loads lazily from storage on first access and caches in memory. Row
   * existence in `cf_agents_state` is the signal that state was previously
   * set, so falsy values persist correctly. On a corrupt row, falls back to
   * the initial state (re-persisting it) or clears the row.
   */
  get(): T | undefined;
  /**
   * Validate and persist a state change, then call the change hook.
   *
   * @param nextState - The new state to persist.
   * @param source - `"server"` for host-originated changes, or the originating
   * connection for client-originated changes.
   * @throws Whatever the injected `validateStateChange` throws.
   */
  set(nextState: T, source?: StateChangeSource): void;
}
//#endregion
export { StateChangeSource as n, StateOptions as r, State as t };
//# sourceMappingURL=index-Dlgtd3Mj.d.ts.map