agents/dist/agent-tools-gGXXkf1z.d.ts

A home for your AI agents

import {
  J as AgentToolRunPart,
  R as AgentToolEventMessage,
  W as AgentToolProgress,
  Z as AgentToolStoredChunk,
  z as AgentToolEventState
} from "./agent-routing-vVMA7m8Y.js";

//#region src/chat/agent-tools.d.ts
type AgentToolProgressEmitResult = "emitted" | "coalesced" | "inactive";
/**
 * Host-injected seams the shared progress emitter needs. Keeps the per-host
 * `reportProgress` thin: Think / AIChatAgent supply how to resolve the active
 * agent-tool run, how to broadcast a chat-response frame, and how to persist the
 * latest snapshot on their own child-run table.
 */
type AgentToolProgressEmitHooks = {
  /** The agent-tool run currently executing in this turn, or null. */ resolveActiveRun: () => {
    runId: string;
    requestId: string;
  } | null /** Broadcast a chat-response frame (id = requestId) to clients/tailers. */;
  broadcast: (
    requestId: string,
    chunkBody: string
  ) => void /** Persist the latest snapshot + signal timestamp on the child run row. */;
  persistSnapshot: (
    runId: string,
    snapshot: {
      fraction?: number;
      message?: string;
      phase?: string;
      data?: unknown;
    },
    at: number
  ) => void;
  /**
   * Persist a durable milestone row, bump the run's signal timestamp, and return
   * the assigned monotonic per-run `sequence` (used to dedupe replay/live races).
   */
  persistMilestone: (
    runId: string,
    name: string,
    data: unknown,
    at: number
  ) => number;
};
/**
 * Shared implementation of `reportProgress` for chat hosts. Builds the reserved
 * transient `data-agent-progress` wire frame, coalesces bursts to a bounded
 * cadence (latest-wins; a `fraction >= 1` "done" frame always flushes), and
 * persists a latest snapshot. `data` rides the live frame but is only persisted
 * when the caller opts in via `{ persist: true }`.
 */
declare class AgentToolProgressEmitter {
  private readonly hooks;
  private readonly _lastEmitAt;
  constructor(hooks: AgentToolProgressEmitHooks);
  report(
    progress: AgentToolProgress,
    options?: {
      persist?: boolean;
    }
  ): AgentToolProgressEmitResult;
  /** Drop coalescing state for a settled run (called on terminal). */
  forget(runId: string): void;
}
declare function createAgentToolEventState<
  Part extends AgentToolRunPart = AgentToolRunPart
>(): AgentToolEventState<Part>;
declare function applyAgentToolEvent<
  Part extends AgentToolRunPart = AgentToolRunPart
>(
  state: AgentToolEventState<Part>,
  message: AgentToolEventMessage
): AgentToolEventState<Part>;
/**
 * @internal Host substrate the {@link interceptAgentToolBroadcast} snoop reads,
 * abstracting the divergent per-host run-lookup and response-frame constant.
 */
interface AgentToolBroadcastHooks {
  /** Live tailers per run; iterated to forward each progress chunk. */
  forwarders: Map<string, Set<(chunk: AgentToolStoredChunk) => void>>;
  /**
   * Per-run live counter of stored chunks; advanced even with no tailer
   * attached, so a stored chunk's live sequence equals its stored chunk_index.
   *
   * Progress/milestone frames (`reportProgress`) ride the same
   * `USE_CHAT_RESPONSE` wire type and are forwarded here, but persist
   * out-of-band (progress snapshot / milestone rows) and have no store
   * position. Neither do chunks too large to store (they carry an
   * `unstoredId`). Both carry the next position WITHOUT consuming it, and
   * tails emit them outside the stored-position high-water dedupe; counting
   * them would push later stored chunks past their stored index, so a chunk
   * stored and broadcast during a tail's drain would be emitted twice. A tail
   * seeds a cold counter from the stored high-water before it attaches.
   */
  liveSequences: Map<string, number>;
  /** Per-run last error body, captured for replay to a late-attaching tailer. */
  lastErrors: Map<string, string>;
  /**
   * Called after a run's error body is captured, so the host can record it
   * durably on the still-open run row (the in-memory {@link lastErrors} entry
   * is lost if the DO is evicted before the run is finalized).
   */
  onError?: (runId: string, body: string) => void;
  /** The host's use-chat-response wire type (`CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE`). */
  responseType: string;
  /** Resolve the agent-tool run that owns a turn request id, or null. */
  runForRequest: (requestId: string) => string | null;
  /**
   * Runs whose chunks the host suppresses (`eventDelivery: "terminal"`). Keeps
   * inspection on after a restart empties the other maps, so a recovered
   * turn's chunks are still attributed and suppressed.
   */
  terminalOnlyRuns?: ReadonlySet<string>;
}
/**
 * Snoop a host's outgoing chat frames while any agent-tool run is in flight and
 * forward the owning run's streamed body to its live tailers (or capture its
 * error), without altering the frame — the caller still broadcasts it (#1575).
 *
 * Shared verbatim by `@cloudflare/ai-chat` and `@cloudflare/think`; the only
 * per-host variance (the response-frame type constant and the run-lookup, whose
 * SQL differs) is supplied via {@link AgentToolBroadcastHooks}. Inspection runs
 * for a run's whole lifecycle (live sequences exist even with no tailer), so
 * error capture never depends on tailer timing. A frame belongs to a run iff it
 * carries that run's turn request id, so concurrent runs can't cross-contaminate
 * each other's progress or error state.
 *
 * Returns the run id when the frame is one of that run's content chunks, so a
 * host can skip broadcasting chunks no client is watching.
 */
declare function interceptAgentToolBroadcast(
  msg: string | ArrayBuffer | ArrayBufferView,
  hooks: AgentToolBroadcastHooks
): string | null;
//#endregion
export {
  applyAgentToolEvent as a,
  AgentToolProgressEmitter as i,
  AgentToolProgressEmitHooks as n,
  createAgentToolEventState as o,
  AgentToolProgressEmitResult as r,
  interceptAgentToolBroadcast as s,
  AgentToolBroadcastHooks as t
};
//# sourceMappingURL=agent-tools-gGXXkf1z.d.ts.map