agents/dist/routing/index.d.ts

A home for your AI agents

import {
  r as CapabilityWebSocketUpgradeContext,
  s as LifecycleCapability,
  t as CapabilityRequestContext
} from "../capability-runner-BUBa6Ake.js";
import {
  a as routeAgentRequest,
  c as Agent,
  i as getAgentByName,
  n as AgentOptions,
  r as RoutingRetryOptions,
  t as AgentGetOptions
} from "../agent-routing-B2XLNMxq.js";

//#region src/routing/routed-agents.d.ts
/** A public entry in an {@link RoutedAgents}. */
type RoutedAgentEntry<Metadata = unknown> = {
  /** Stable application-facing identifier used in routes. */ readonly id: string /** Application-owned metadata stored with the entry. */;
  readonly metadata: Metadata | null /** Creation time, as Unix milliseconds. */;
  readonly createdAt: number /** Time the entry or its metadata last changed, as Unix milliseconds. */;
  readonly updatedAt: number;
};
/** Options for creating an entry in an {@link RoutedAgents}. */
type RoutedAgentCreateOptions<Metadata = unknown> = {
  /** Initial application-owned metadata. */ readonly metadata?: Metadata;
};
/** Configuration for an {@link RoutedAgents}. */
type RoutedAgentsOptions<TAgent extends Agent> = {
  /** Top-level Durable Object namespace the entries are created in. */ readonly namespace: DurableObjectNamespace<TAgent> /** One URL-safe path segment under the owning Durable Object. */;
  readonly route: string;
};
/**
 * A durable, routed collection of independent top-level Agents.
 *
 * Install this on the owning Durable Object, typically a per-user hub. It
 * maps public entry IDs to opaque physical Agent names, handles catalog
 * CRUD without waking any target, and forwards matching HTTP requests and
 * WebSocket upgrades to the selected Agent. After an upgrade the target
 * owns the socket, so ordinary frames never wake the owner. The target
 * Agent needs no matching capability. Destroying the owner condemns every
 * remaining entry with a few retries so targets don't casually outlive
 * their catalog — this is best-effort, not a durability guarantee; see
 * {@link RoutedAgents.dispose}.
 *
 * Pick a `route` that cannot appear as a literal path segment elsewhere
 * under the owner (its own name, another route, or a path the owner's own
 * `onRequest` handles) — forwarding matches every occurrence of the route
 * segment in the path, so a coincidental match with no active entry
 * behind it is answered `404` instead of reaching the owner.
 *
 * A forwarded suffix is not searched for a `/sub/{class}/{name}` dynamic
 * agents marker: `Agent.fetch()` resolves that marker against the OWNER's
 * exported classes before this capability's `onRequest` ever runs, so a
 * matching marker is served as a facet of the owner, not forwarded to the
 * target. Address a target's own dynamic agents through a direct
 * connection to that target, not through the owner's route.
 *
 * @experimental The API surface may change before stabilizing.
 */
declare class RoutedAgents<
  TAgent extends Agent = Agent,
  Metadata = unknown
> extends LifecycleCapability {
  #private;
  /**
   * @param options - Target binding and the route segment this capability
   * claims. Install with `this.lifecycle.use()` before startup.
   */
  constructor(options: RoutedAgentsOptions<TAgent>);
  /** Create an entry without waking the target Agent. */
  create(
    options?: RoutedAgentCreateOptions<Metadata>
  ): Promise<RoutedAgentEntry<Metadata>>;
  /** Resolve an active entry to an initialized, typed Agent stub. */
  get(id: string): Promise<DurableObjectStub<TAgent> | null>;
  /**
   * List active entries, most recently updated first. Entries whose
   * `updatedAt` ties are ordered by actual write order, not by the
   * random entry `id`.
   */
  list(): Promise<ReadonlyArray<RoutedAgentEntry<Metadata>>>;
  /** Replace an active entry's metadata. Returns false for unknown IDs. */
  setMetadata(id: string, metadata: Metadata | null): Promise<boolean>;
  /**
   * Make an entry unreachable, condemn its Agent, then remove the row.
   * Returns false for unknown IDs.
   *
   * The target is condemned through Agent's deferred teardown, which
   * durably marks it and returns without aborting the isolate; its storage
   * is wiped on its own next wake, moments later, and the marker survives
   * interruption. A failed RPC leaves a hidden `deleting` row so a
   * repeated call retries.
   */
  delete(id: string): Promise<boolean>;
  onStart(): void;
  /**
   * Condemn every remaining entry (including one already `deleting`, in
   * case its own condemnation RPC never landed) when the owner itself is
   * destroyed.
   *
   * `Agent.destroy()` disposes capabilities before it wipes its own
   * storage, so the catalog is still readable here — without this, the
   * catalog would vanish with the owner while every target it named kept
   * running and billing storage, unreachable forever.
   *
   * This is best-effort, not a durability guarantee: `Agent.destroy()`
   * wipes the owner's storage immediately after disposal regardless of
   * whether any capability's `dispose()` reports failure, so a target
   * that is still unreachable after retries here is orphaned for good —
   * there is no later "repeated call retries" for a catalog row that no
   * longer exists. Retrying briefly here converts the common transient
   * failure into a condemned target instead of an orphan; it cannot
   * convert a target that is durably unreachable.
   */
  dispose(): Promise<void>;
  /** Forward a matching HTTP request to the selected Agent. */
  onRequest({
    request
  }: CapabilityRequestContext): Promise<Response | undefined>;
  /** Forward a matching upgrade so the selected Agent owns the WebSocket. */
  onWebSocketUpgrade({
    request
  }: CapabilityWebSocketUpgradeContext): Promise<Response | undefined>;
}
//#endregion
export {
  type AgentGetOptions,
  type AgentOptions,
  type RoutedAgentCreateOptions,
  type RoutedAgentEntry,
  RoutedAgents,
  type RoutedAgentsOptions,
  type RoutingRetryOptions,
  getAgentByName,
  routeAgentRequest
};
//# sourceMappingURL=index.d.ts.map