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

A home for your AI agents

import {
  f as AgentToolProgress,
  g as AgentToolRunPart,
  o as AgentToolEventMessage,
  s as AgentToolEventState,
  y as AgentToolStoredChunk
} from "./agent-tool-types-BC-WFlsz.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 forwarded-chunk counter; advanced even with no tailer attached.
   *
   * This is deliberately a SEPARATE counter from the resumable stream's stored
   * chunk_index — do NOT try to "simplify" it away by sequencing off the store
   * position. Not every forwarded frame is durably stored: progress/milestone
   * frames (`reportProgress`) ride the same `USE_CHAT_RESPONSE` wire type and
   * are snooped + forwarded here, but persist out-of-band (progress snapshot /
   * milestone rows), so they have no store position. Sourcing the sequence from
   * the store would give them a colliding position and the tail's high-water
   * dedupe (`emit`) would silently drop them, breaking live progress/milestone
   * delivery to the parent. This counter sequences stored AND non-stored frames
   * on one monotonic line; the tail realigns it to the stored high-water on each
   * (re)attach so a replay→live handoff stays gap/duplicate-free.
   */
  liveSequences: Map<string, number>;
  /** Per-run last error body, captured for replay to a late-attaching tailer. */
  lastErrors: Map<string, string>;
  /** 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;
}
/**
 * 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.
 */
declare function interceptAgentToolBroadcast(
  msg: string | ArrayBuffer | ArrayBufferView,
  hooks: AgentToolBroadcastHooks
): void;
//#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-DeHe9Xov.d.ts.map