/**
 * `agency.llm` — user-facing TS façade over `runPrompt`.
 *
 * Lets a TS helper issue an LLM call with full participation in the
 * surrounding agent run: cost tracking, the active LLM client, thread
 * accumulation, trace events, checkpoint integration. The codegen
 * emission for Agency-source `llm(...)` is unchanged — it continues to
 * call `runPrompt` directly with its own options shape (tools,
 * removedTools, etc.). Both paths converge inside `runPrompt`.
 *
 * Differences from the codegen path (intentional in v1):
 *  - **No tools.** The `__toolRegistry` is per-Agency-module and
 *    codegen-only; exposing it to TS would leak codegen internals
 *    into the public surface. If a TS helper needs LLM-driven tool
 *    dispatch, define the call as an Agency `def` (which gets the
 *    registry automatically) and invoke that `def` from TS.
 *  - **No `removedTools`, no `maxToolCallRounds`.** Those only make
 *    sense when tools are in play.
 *  - **`opts.model` overrides for THIS call only.** It does NOT
 *    mutate the active LLM client config — every subsequent call
 *    without `opts.model` uses the client's default. This is
 *    important: if the override "stuck" it would silently rebind the
 *    rest of the run to the wrong model.
 *
 * Cost tracking, thread accumulation, and trace events all flow
 * through `runPrompt` automatically — no extra wiring needed here.
 *
 * Throws if called outside an Agency frame. `runPrompt` reads
 * `ctx`/`stack`/`threads` from the active `agencyStore` frame; if no
 * frame is installed, `getRuntimeContext()` throws. TS callers must
 * run inside an Agency frame (either reached from generated code, or
 * wrapped explicitly with `agency.withTestContext` in unit tests).
 */
import type { z } from "zod";
import type { UserContentInput } from "smoltalk";
import type { RetryConfig } from "./llmRetry.js";
import type { MessageThread } from "./state/messageThread.js";
/**
 * Options for `agency.llm`. Extends `RetryConfig` (single source of truth for
 * `retries` / `timeout` / `backoff`, shared with `LlmDefaults` and the type-
 * checker's `llmOptions` shape) so adding a resilience field in one place
 * doesn't require updating three.
 */
export type LlmOpts<S extends z.ZodSchema = z.ZodSchema> = RetryConfig & {
    /** Override the model for this call only. Does NOT mutate the
     *  active LLM client config; the override applies to this single
     *  prompt. Subsequent `agency.llm` calls without `opts.model` use
     *  the client's default. */
    model?: string;
    /** Cap on generated output tokens for this call. Maps to the
     *  provider's `maxTokens`. Set it whenever the expected output is
     *  small and bounded (labels, summaries): without a cap, a model
     *  that fails to emit its stop token — small local models under a
     *  structured-output grammar are the common case — generates until
     *  its context window fills. */
    maxTokens?: number;
    /** Structured-output schema. Maps to `runPrompt`'s `responseFormat`.
     *  When set, the response is parsed and the call returns
     *  `z.infer<S>` instead of the raw string content. */
    schema?: S;
    /** Override the thread the prompt + response are appended to.
     *  Default: the active thread on the current `ThreadStore`. */
    thread?: MessageThread;
};
/** Module-private. Re-exposed only via `agency.llm`.
 *
 *  `prompt` is a string, or an array of text strings and image()/file()
 *  attachments (see `std::thread`), matching smoltalk's user-message content.
 *
 *  Overloads: when `opts.schema` is provided the return type is
 *  `z.infer<S>`; otherwise it's `string`. Order matters — the
 *  schema-bearing overload must come first so TS picks it over the
 *  string-returning fallback. */
export declare function llm<S extends z.ZodSchema>(prompt: string | UserContentInput, opts: LlmOpts<S> & {
    schema: S;
}): Promise<z.infer<S>>;
export declare function llm(prompt: string | UserContentInput, opts?: LlmOpts): Promise<string>;