@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/providers/types.d.ts

@@ -1,5 +1,7 @@
-import type { Chunk } from "@nodetool-ai/protocol";
-export type ProviderId = "openai" | "anthropic" | "ollama" | "llama_cpp" | string;
+import type { Chunk, ProviderId, ProviderSession } from "@nodetool-ai/protocol";
+export { PROVIDER_IDS } from "@nodetool-ai/protocol";
+export type { ProviderId };
+export type { ProviderSession };
 export interface LanguageModel {
     id: string;
     name: string;
@@ -10,18 +12,99 @@ export interface ImageModel {
     name: string;
     provider: ProviderId;
     supportedTasks?: string[];
+    /**
+     * Per-model output-size constraints derived from the provider manifest's
+     * enum fields (e.g. FAL's image_size / aspect_ratio). When present the
+     * picker offers only these values so users can't request a ratio the
+     * endpoint will silently ignore.
+     */
+    aspectRatios?: string[];
+    resolutions?: string[];
 }
 export interface VideoModel {
     id: string;
     name: string;
     provider: ProviderId;
     supportedTasks?: string[];
+    /**
+     * Per-model option constraints derived from the provider manifest's enum
+     * fields. When present the composer offers only these values (e.g. a model
+     * that only supports 5s/10s clips), avoiding 422s from unsupported params.
+     */
+    durations?: number[];
+    resolutions?: string[];
+    aspectRatios?: string[];
+}
+export interface ModelArtifactRef {
+    source: "huggingface";
+    repoId: string;
+    revision?: string;
+    path?: string;
+}
+export interface ModelAdapterInfo {
+    state: "installed" | "missing_dependency" | "unknown";
+    reasonCode?: string;
+    reason?: string;
+    artifactRef?: ModelArtifactRef;
 }
 export interface TTSModel {
     id: string;
     name: string;
     provider: ProviderId;
     voices?: string[];
+    capabilities?: string[];
+    languages?: string[];
+    sampleRate?: number;
+    requiresReferenceText?: boolean;
+    /** Execution adapter facts reported by the local worker without loading weights. */
+    adapter?: ModelAdapterInfo;
+}
+export interface TextToSpeechParams {
+    text: string;
+    model: string;
+    voice?: string;
+    speed?: number;
+    referenceAudio?: Uint8Array;
+    referenceText?: string;
+    language?: string;
+    instructions?: string;
+    /** Requested output container; raw-PCM providers may ignore this hint. */
+    audioFormat?: string;
+}
+export interface MusicModel {
+    id: string;
+    name: string;
+    provider: ProviderId;
+    /** Capability hints, e.g. `["text_to_music"]`. */
+    supportedTasks?: string[];
+}
+/**
+ * A model that takes audio and hands back audio: voice conversion, isolation
+ * and denoise, stem separation, audio super-resolution, audio inpaint/extend.
+ * None of these generate from a prompt alone, so they belong in no TTS or
+ * music picker — offered as one, they fail at call time with nothing to work
+ * on. `isAudioTransformNode` in `manifest-models.ts` is what identifies them.
+ */
+export interface AudioToAudioModel {
+    id: string;
+    name: string;
+    provider: ProviderId;
+    /** Capability hints, e.g. `["audio_to_audio"]`. */
+    supportedTasks?: string[];
+}
+export interface AudioToAudioParams {
+    model: AudioToAudioModel;
+    /** What the transform should do, for endpoints that take direction. */
+    prompt?: string | null;
+    /** Target voice, for voice-conversion endpoints that name one. */
+    voice?: string | null;
+    /** How far from the source to move, for endpoints that take it (0..1). */
+    strength?: number | null;
+    seed?: number | null;
+    /** Requested output container hint (e.g. "mp3", "wav"). */
+    audioFormat?: string | null;
+    /** Per-call timeout. Providers translate this into a max polling window. */
+    timeoutSeconds?: number | null;
 }
 export interface ASRModel {
     id: string;
@@ -49,16 +132,102 @@ export interface ToolCall {
     thought_signature?: string;
     /** Raw Gemini parts to echo back (preserves thought content). */
     _rawGeminiParts?: unknown[];
+    _anthropicThinkingBlocks?: AnthropicThinkingBlock[];
 }
+export type AnthropicThinkingBlock = {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+} | {
+    type: "redacted_thinking";
+    data: string;
+};
+export type ProviderThinkingDisplay = "summarized" | "omitted";
+export type ProviderThinkingConfig = {
+    type: "adaptive";
+    display?: ProviderThinkingDisplay;
+} | {
+    type: "manual";
+    budgetTokens: number;
+    display?: ProviderThinkingDisplay;
+} | {
+    type: "disabled";
+};
+export type ProviderEffort = "low" | "medium" | "high" | "xhigh" | "max";
+export interface ProviderCacheControl {
+    type: "ephemeral";
+    ttl?: "5m" | "1h";
+}
+export type ProviderToolCaller = "direct" | "code_execution_20250825" | "code_execution_20260120" | "code_execution_20260521";
+/**
+ * Canonical name for the web-search tool. Providers with a built-in web search
+ * (`supportsNativeWebSearch`) render a tool with this name as their native
+ * server-side search instead of a function call; everyone else falls back to
+ * the SerpAPI-backed `WebSearchTool`.
+ */
+export declare const WEB_SEARCH_TOOL_NAME = "web_search";
+/**
+ * Canonical name for the image-generation tool. Providers with a built-in,
+ * server-side image generator (`supportsNativeImageGeneration`, e.g. the
+ * OpenAI Responses `image_generation` tool) render a tool with this name as
+ * their native tool: the generated image arrives inside the model turn as an
+ * `image_generation_call` output item — there is no function-call round-trip —
+ * and the provider surfaces it as image content on the assistant message.
+ * Providers without native support fall back to a function tool that calls
+ * `textToImage`/`imageToImage`.
+ */
+export declare const IMAGE_GENERATION_TOOL_NAME = "image_generation";
 export interface ProviderTool {
     name: string;
     description?: string;
     inputSchema?: Record<string, unknown>;
+    inputExamples?: Record<string, unknown>[];
+    cacheControl?: ProviderCacheControl;
+    strict?: boolean;
+    deferLoading?: boolean;
+    allowedCallers?: ProviderToolCaller[];
     type?: "function" | "code_interpreter";
+    /**
+     * Optional self-contained executor for this tool. When present,
+     * {@link BaseProvider.generateLoop} (and the Claude Agent SDK MCP handlers)
+     * dispatch the tool call to `execute` directly, instead of routing it through
+     * the harness-supplied `executeTool` callback. Returns the result fed back to
+     * the model — plain text, or {@link MessageContent} blocks for results that
+     * carry images. Tools without `execute` still flow through `executeTool`.
+     */
+    execute?: (args: Record<string, unknown>, toolCallId?: string) => Promise<string | MessageContent[]>;
+    /**
+     * When `true`, the agentic loop ends after this tool runs: `generateLoop`
+     * finishes emitting the current turn's results, then stops iterating (and the
+     * Claude Agent SDK loop is aborted). Use for tools that signal completion
+     * (e.g. a `finish`/`submit` tool). Defaults to falsy (loop continues).
+     */
+    terminal?: boolean;
+}
+/**
+ * A user-defined skill handed to a provider that drives its own agent loop.
+ *
+ * The Claude Agent SDK has a native skill mechanism (a `Skill` tool with
+ * progressive disclosure), but it only discovers skills from the filesystem
+ * via `settingSources` — which {@link ClaudeAgentProvider} deliberately locks
+ * to `[]`. This shape lets the harness hand the user's DB-backed skills to the
+ * provider, which materializes them as an isolated local plugin so the native
+ * loop can list and load them on demand. Providers that don't own their loop
+ * (the base `generateLoop`) ignore it; those receive skills baked into the
+ * system prompt instead.
+ */
+export interface ProviderSkill {
+    /** Filesystem-safe skill name (matches the SKILL.md `name` frontmatter). */
+    name: string;
+    /** One-line "when to use this" summary shown in the skill listing. */
+    description: string;
+    /** The full skill instructions (the SKILL.md body). */
+    content: string;
 }
 export interface MessageTextContent {
     type: "text";
     text: string;
+    citations?: MessageCitation[];
 }
 export interface MessageImageContent {
     type: "image_url";
@@ -76,19 +245,102 @@ export interface MessageAudioContent {
         mimeType?: string;
     };
 }
-export type MessageContent = MessageTextContent | MessageImageContent | MessageAudioContent;
+export interface MessageVideoContent {
+    type: "video";
+    video: {
+        uri?: string;
+        data?: Uint8Array | string;
+        mimeType?: string;
+    };
+}
+export interface MessageDocumentContent {
+    type: "document";
+    document: {
+        uri?: string;
+        data?: Uint8Array | string;
+        mimeType?: string;
+        title?: string;
+    };
+    citations?: boolean;
+    context?: string;
+}
+interface MessageDocumentCitationBase {
+    citedText: string;
+    documentIndex: number;
+    documentTitle?: string | null;
+    fileId?: string | null;
+}
+export interface MessageCharCitation extends MessageDocumentCitationBase {
+    type: "char_location";
+    startCharIndex: number;
+    endCharIndex: number;
+}
+export interface MessagePageCitation extends MessageDocumentCitationBase {
+    type: "page_location";
+    startPageNumber: number;
+    endPageNumber: number;
+}
+export interface MessageContentBlockCitation extends MessageDocumentCitationBase {
+    type: "content_block_location";
+    startBlockIndex: number;
+    endBlockIndex: number;
+}
+export interface MessageWebSearchCitation {
+    type: "web_search_result_location";
+    citedText: string;
+    encryptedIndex: string;
+    url: string;
+    title?: string | null;
+}
+export interface MessageSearchResultCitation {
+    type: "search_result_location";
+    citedText: string;
+    searchResultIndex: number;
+    source: string;
+    title?: string | null;
+    startBlockIndex: number;
+    endBlockIndex: number;
+}
+export type MessageCitation = MessageCharCitation | MessagePageCitation | MessageContentBlockCitation | MessageWebSearchCitation | MessageSearchResultCitation;
+export type MessageContent = MessageTextContent | MessageImageContent | MessageAudioContent | MessageVideoContent | MessageDocumentContent;
+export interface ProviderToolErrorResult {
+    content: string | MessageContent[];
+    isError: true;
+}
+export type ProviderToolResult = string | MessageContent[] | ProviderToolErrorResult;
+export declare function isProviderToolErrorResult(result: ProviderToolResult): result is ProviderToolErrorResult;
 export interface Message {
     role: "system" | "user" | "assistant" | "tool";
     content?: string | MessageContent[] | null;
     toolCalls?: ToolCall[] | null;
     toolCallId?: string | null;
+    isError?: boolean;
     threadId?: string | null;
     /** Provider-specific raw parts to echo back (e.g., Gemini thought parts). */
     _rawGeminiParts?: unknown[];
+    _anthropicThinkingBlocks?: AnthropicThinkingBlock[];
+}
+/**
+ * A reusable entity (character, prop, location, style) riding along with a
+ * generation call for cross-shot consistency. Any provider consumer — nodes,
+ * the chat WebSocket, CLI — can attach these to the params; {@link BaseProvider}
+ * expands them centrally before the concrete provider runs: the descriptor
+ * joins the prompt as a `Consistency references:` block, and on image-editing
+ * tasks the reference image bytes are appended to the source-image list.
+ */
+export interface EntityReference {
+    /** Display name, referenced from the prompt text. */
+    name: string;
+    /** Canonical visual descriptor injected into the prompt. */
+    descriptor?: string | null;
+    /** Encoded reference image bytes (routed to image inputs on editing tasks). */
+    image?: Uint8Array | null;
 }
 export interface TextToImageParams {
     model: ImageModel;
     prompt: string;
+    /** Consistency entities; descriptors join the prompt (t2i takes no images). */
+    entities?: EntityReference[] | null;
     negativePrompt?: string | null;
     width?: number;
     height?: number;
@@ -100,10 +352,21 @@ export interface TextToImageParams {
     seed?: number | null;
     scheduler?: string | null;
     safetyCheck?: boolean | null;
+    /**
+     * Cancellation for the upstream request. Providers that can abort their
+     * transport honor it; the rest ignore it (the caller still discards the
+     * result). Optional so provider implementations opt in individually.
+     */
+    signal?: AbortSignal;
 }
 export interface ImageToImageParams {
     model: ImageModel;
     prompt: string;
+    /**
+     * Consistency entities; descriptors join the prompt and reference images are
+     * appended to the source-image list (after the caller's own images).
+     */
+    entities?: EntityReference[] | null;
     negativePrompt?: string | null;
     targetWidth?: number | null;
     targetHeight?: number | null;
@@ -115,10 +378,159 @@ export interface ImageToImageParams {
     strength?: number | null;
     seed?: number | null;
     scheduler?: string | null;
+    /**
+     * Cancellation for the upstream request. Providers that can abort their
+     * transport honor it; the rest ignore it (the caller still discards the
+     * result). Optional so provider implementations opt in individually.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Inpaint (mask-guided edit): regenerate the masked region of one or more
+ * source images according to a prompt. Identical to {@link ImageToImageParams}
+ * but the `mask` is required — endpoints are selected and routed by their
+ * declared mask field. White pixels in the mask mark the region to regenerate.
+ */
+export interface InpaintingParams extends ImageToImageParams {
+    /** Mask image — white pixels indicate the region to regenerate. */
+    mask: Uint8Array;
+}
+/**
+ * Increase the resolution / detail of an image. Some upscalers (e.g. Clarity,
+ * Magic Refiner) accept a guiding `prompt` and `creativity` to hallucinate
+ * detail; pure ESRGAN-style models ignore them.
+ */
+export interface UpscaleImageParams {
+    model: ImageModel;
+    /** Target magnification factor, e.g. 2 or 4. */
+    scale?: number | null;
+    prompt?: string | null;
+    /** 0–1 hint for how much new detail the model may invent. */
+    creativity?: number | null;
+    seed?: number | null;
+}
+/**
+ * How far to grow the canvas on each side, in source-image pixels.
+ *
+ * Endpoints spell outpainting three ways: per-side pixel counts
+ * (`fal-ai/image-apps-v2/outpaint`), per-side booleans plus one ratio
+ * (`fal-ai/wan-vace-14b/outpainting`), and a target canvas or aspect ratio
+ * (`bria/expand-image`, `fal-ai/ltx-2.3-quality/outpaint`). Pixels are the one
+ * spelling that carries the others' information, so callers state pixels and
+ * each provider reduces them to what its endpoint declares.
+ */
+export interface OutpaintPadding {
+    left?: number | null;
+    right?: number | null;
+    top?: number | null;
+    bottom?: number | null;
+}
+/**
+ * Outpaint (uncrop): keep the source image and generate new content in the
+ * area the padding adds around it. The inverse of {@link InpaintingParams} —
+ * inpainting repaints inside the frame, outpainting extends past it.
+ */
+export interface OutpaintImageParams {
+    model: ImageModel;
+    /** What belongs in the new area; blank lets the model continue the scene. */
+    prompt?: string | null;
+    entities?: EntityReference[] | null;
+    negativePrompt?: string | null;
+    padding?: OutpaintPadding | null;
+    /** Target canvas aspect ratio, for endpoints that expand to one. */
+    aspectRatio?: string | null;
+    seed?: number | null;
+    signal?: AbortSignal;
+}
+/** Remove the background from an image, returning an image with alpha. */
+export interface RemoveBackgroundParams {
+    model: ImageModel;
+}
+/** A rectangle in source-image pixels. */
+export interface ImageBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A click that includes or excludes a region, in source-image pixels. */
+export interface SegmentPoint {
+    x: number;
+    y: number;
+    /** true = the object is here; false = it is not. */
+    include: boolean;
+}
+/**
+ * Segment an image into object masks. The prompts are alternatives, not a
+ * pipeline: a `prompt` names the concept to find ("the dog"), `points` and
+ * `box` point at one object, and passing none asks the model for whatever it
+ * finds. A model serves only the prompt kinds its endpoint declares.
+ */
+export interface SegmentImageParams {
+    model: ImageModel;
+    /** Concept to segment, for text-promptable models. */
+    prompt?: string | null;
+    points?: SegmentPoint[] | null;
+    box?: ImageBox | null;
+    /** Upper bound on how many masks to return. */
+    maxMasks?: number | null;
+    /** Drop masks the model scores below this (0–1). */
+    minConfidence?: number | null;
+    signal?: AbortSignal;
+}
+/** One object found by {@link SegmentImageParams}. */
+export interface ImageSegmentationMask {
+    /** Encoded mask image — white inside the object, black outside. */
+    mask: Uint8Array;
+    mimeType: string;
+    /** Mask size in pixels, when the provider reports it. */
+    width?: number | null;
+    height?: number | null;
+    /** What the model called this object, when it names them. */
+    label?: string | null;
+    /** Model confidence 0–1, when the model scores its masks. */
+    confidence?: number | null;
+    /** Bounding box in source-image pixels, when the provider reports one. */
+    box?: ImageBox | null;
+}
+/**
+ * Re-light a subject according to a text prompt and/or a background reference.
+ */
+export interface RelightImageParams {
+    model: ImageModel;
+    prompt?: string | null;
+    negativePrompt?: string | null;
+    seed?: number | null;
+}
+/** Convert a raster image into a vector (SVG) representation. */
+export interface VectorizeImageParams {
+    model: ImageModel;
+}
+/**
+ * Generate music / instrumental audio from a text prompt. Mirrors the
+ * `TextTo<Media>Params` pattern. Music providers return a fully-encoded audio
+ * file (mp3/wav/flac), so {@link BaseProvider.textToMusic} resolves to an
+ * {@link EncodedAudioResult} rather than raw PCM samples.
+ */
+export interface TextToMusicParams {
+    model: MusicModel;
+    /** Free-text description of the desired music (style, mood, instruments). */
+    prompt: string;
+    /** Optional song lyrics for vocal models (e.g. Suno, ACE-Step, MiniMax). */
+    lyrics?: string | null;
+    /** Requested duration in seconds (providers clamp to their own limits). */
+    durationSeconds?: number | null;
+    seed?: number | null;
+    /** Requested output container hint (e.g. "mp3", "wav"). */
+    audioFormat?: string | null;
+    /** Per-call timeout. Providers translate this into a max polling window. */
+    timeoutSeconds?: number | null;
 }
 export interface TextToVideoParams {
     model: VideoModel;
     prompt: string;
+    /** Consistency entities; descriptors join the prompt (text-only for video). */
+    entities?: EntityReference[] | null;
     negativePrompt?: string | null;
     numFrames?: number | null;
     /** Requested duration in seconds (provider decides fps). */
@@ -128,10 +540,26 @@ export interface TextToVideoParams {
     guidanceScale?: number | null;
     numInferenceSteps?: number | null;
     seed?: number | null;
+    /** Per-call timeout. Providers translate this into a max polling window. */
+    timeoutSeconds?: number | null;
+    /**
+     * Cancellation for the upstream request. Providers that can abort their
+     * transport honor it; the rest ignore it (the caller still discards the
+     * result). Optional so provider implementations opt in individually.
+     */
+    signal?: AbortSignal;
 }
 export interface ImageToVideoParams {
     model: VideoModel;
     prompt?: string | null;
+    /** Optional final frame for models that interpolate between two images. */
+    endImage?: Uint8Array | null;
+    /**
+     * Consistency entities; descriptors join the prompt. Images are NOT appended
+     * here — the image list's first frame drives the animation, so extra images
+     * would change its meaning.
+     */
+    entities?: EntityReference[] | null;
     negativePrompt?: string | null;
     numFrames?: number | null;
     /** Requested duration in seconds (provider decides fps). */
@@ -141,8 +569,179 @@ export interface ImageToVideoParams {
     guidanceScale?: number | null;
     numInferenceSteps?: number | null;
     seed?: number | null;
+    /** Per-call timeout. Providers translate this into a max polling window. */
+    timeoutSeconds?: number | null;
+    /**
+     * Cancellation for the upstream request. Providers that can abort their
+     * transport honor it; the rest ignore it (the caller still discards the
+     * result). Optional so provider implementations opt in individually.
+     */
+    signal?: AbortSignal;
+}
+export interface ReferenceToVideoInputs {
+    images: Uint8Array[];
+    videos: Uint8Array[];
+    audios?: Uint8Array[];
+}
+export interface ReferenceToVideoParams extends TextToVideoParams {
+    /** Allow conditioning on audio tracks carried by reference videos. */
+    useReferenceVideoAudio?: boolean | null;
+}
+/**
+ * Transform an existing video into a restyled / edited video, guided by a
+ * prompt (e.g. style transfer, motion restyle). Mirrors `ImageToImageParams`
+ * for the video domain.
+ */
+export interface VideoToVideoParams {
+    model: VideoModel;
+    prompt?: string | null;
+    /** Ordered identity/style images, separate from the source video. */
+    referenceImages?: readonly Uint8Array[];
+    referenceAssetIds?: readonly string[];
+    signal?: AbortSignal;
+    /** Consistency entities contribute descriptors and reference images. */
+    entities?: EntityReference[] | null;
+    negativePrompt?: string | null;
+    strength?: number | null;
+    durationSeconds?: number | null;
+    resolution?: string | null;
+    seed?: number | null;
+}
+/** Extend the supplied video window, retaining it in the returned video. */
+export interface ExtendVideoParams {
+    model: VideoModel;
+    prompt: string;
+    mode: "start" | "end";
+    /** Additional source seconds, not the total output duration. */
+    durationSeconds: number;
+    signal?: AbortSignal;
 }
-export type ProviderStreamItem = Chunk | ToolCall;
+/**
+ * Increase the resolution / detail of a video. The video-domain twin of
+ * {@link UpscaleImageParams}: `scale` is a magnification factor and
+ * `targetResolution` names a rung instead ("1080p", "2160p"). Endpoints take
+ * one or the other, so a caller may set both and let the provider pick.
+ */
+export interface UpscaleVideoParams {
+    model: VideoModel;
+    /** Target magnification factor, e.g. 2 or 4. */
+    scale?: number | null;
+    /** Target output resolution, e.g. "1080p" — for endpoints that take a rung. */
+    targetResolution?: string | null;
+    /** Guidance for generative upscalers; pure ESRGAN-style models ignore it. */
+    prompt?: string | null;
+    /** 0-1 hint for how much new detail the model may invent. */
+    creativity?: number | null;
+    seed?: number | null;
+    timeoutSeconds?: number | null;
+    signal?: AbortSignal;
+}
+/**
+ * Frame interpolation: synthesize intermediate frames so a clip plays at a
+ * higher frame rate, or in slow motion at the same one. `targetFps` and
+ * `factor` are alternatives — an endpoint declares one (`target_fps` on Topaz,
+ * `recursive_interpolation_passes` on AMT) and ignores the other.
+ */
+export interface InterpolateVideoParams {
+    model: VideoModel;
+    /** Frames per second to interpolate up to. */
+    targetFps?: number | null;
+    /** Multiply the frame count by this instead of naming an fps. */
+    factor?: number | null;
+    seed?: number | null;
+    timeoutSeconds?: number | null;
+    signal?: AbortSignal;
+}
+/**
+ * Outpaint a video: keep the source footage and generate new content in the
+ * area the padding adds around it, consistently across frames. The video twin
+ * of {@link OutpaintImageParams}.
+ */
+export interface OutpaintVideoParams {
+    model: VideoModel;
+    /** What belongs in the new area; blank lets the model continue the scene. */
+    prompt?: string | null;
+    entities?: EntityReference[] | null;
+    negativePrompt?: string | null;
+    padding?: OutpaintPadding | null;
+    /**
+     * Fraction of the source dimension to add on each padded side, for endpoints
+     * that take one ratio plus per-side switches rather than pixel counts.
+     */
+    expandRatio?: number | null;
+    /** Target canvas aspect ratio, for endpoints that expand to one. */
+    aspectRatio?: string | null;
+    resolution?: string | null;
+    seed?: number | null;
+    timeoutSeconds?: number | null;
+    signal?: AbortSignal;
+}
+/**
+ * Drive a face in a video (or still image) to match speech in an audio track.
+ * The primary visual is passed positionally to `lipSync`; the `audio` bytes
+ * ride along in the params.
+ */
+export interface LipSyncParams {
+    model: VideoModel;
+    /** Encoded audio bytes (e.g. WAV/MP3) the mouth motion should follow. */
+    audio: Uint8Array;
+    seed?: number | null;
+}
+/**
+ * Internal-only stream item carrying a session-continuity update. It is NOT a
+ * wire message — the chat pipeline consumes it to persist the continuation
+ * token onto the assistant message, and never forwards it to clients. A
+ * provider emits one per turn once it has captured/refreshed its session.
+ */
+export interface ProviderSessionUpdate {
+    type: "session";
+    session: ProviderSession;
+}
+/**
+ * A finalized conversation message produced during an agentic loop
+ * ({@link BaseProvider.generateLoop}) — an assistant turn (text + tool calls) or
+ * a tool result. The harness persists/collects these; live text still arrives
+ * as {@link Chunk}s for incremental display. Not a wire message.
+ */
+export interface ProviderMessageEvent {
+    type: "message";
+    message: Message;
+}
+/**
+ * Why an agentic loop ({@link BaseProvider.generateLoop}) stopped, when it was
+ * not the model ending its turn. Yielded as the loop's final item, exactly
+ * once, so a consumer can tell a budget stop from a finished answer — a silent
+ * return reads identically to success and is a bug (invariant I-3).
+ */
+export interface ProviderStop {
+    type: "stop";
+    reason: "budget" | "deadline" | "iterations" | "aborted";
+    /** Human-readable reason, naming the limit that was hit. */
+    detail: string;
+}
+/**
+ * The loop ended because the caller aborted it. One shared value so every
+ * abort path — the base loop's and each override's — says the same thing.
+ */
+export declare const PROVIDER_STOP_ABORTED: ProviderStop;
+export type ProviderStreamItem = Chunk | ToolCall | ProviderSessionUpdate | ProviderMessageEvent | ProviderStop;
+/**
+ * Narrow a stream item to a {@link ProviderSessionUpdate}. `Chunk` carries
+ * `type: "chunk"` and `ToolCall` has no `type`, so a `type === "session"` check
+ * is unambiguous. Existing loops that only switch on chunk/tool-call ignore it.
+ */
+export declare function isProviderSessionUpdate(item: ProviderStreamItem): item is ProviderSessionUpdate;
+/** Narrow a stream item to a {@link Chunk} carrying text content. */
+export declare function isChunk(item: ProviderStreamItem): item is Chunk;
+/**
+ * Narrow a stream item to a {@link ToolCall}. It is the one member of the union
+ * with no `type` discriminator, so it is identified by shape: `name` and `id`.
+ */
+export declare function isToolCall(item: ProviderStreamItem): item is ToolCall;
+/** Narrow a stream item to a {@link ProviderStop}. */
+export declare function isProviderStop(item: ProviderStreamItem): item is ProviderStop;
+/** Narrow a stream item to a {@link ProviderMessageEvent}. */
+export declare function isProviderMessageEvent(item: ProviderStreamItem): item is ProviderMessageEvent;
 export interface StreamingAudioChunk {
     samples: Int16Array;
     /** Sample rate in Hz. Defaults to 24000 when omitted. */