@combycode/llm-sdk 1.0.0-rc.0

package/dist/helpers/engine.d.ts

@@ -0,0 +1,121 @@
+/** createEngine — build an EngineHandle bag of plugin instances.
+ *
+ *  The EngineHandle is a thin coordinator: shared HookBus + AgentBus,
+ *  optional persistence/cache, NetworkEngine (which owns multi-queue HTTP),
+ *  and convenience accessors for downstream helpers. Classes never consult
+ *  the engine directly; only the createLLM/createAgent/createServer helpers
+ *  resolve fetch/hooks against it.
+ *
+ *  Usage:
+ *
+ *    const engine = createEngine({
+ *      persistence: { type: 'file', dir: './data' },
+ *      cache: { type: 'memory' },
+ *    });
+ *
+ *    const llm = createLLM({ provider: 'anthropic', model: '...', apiKey: '...' });
+ *    // llm.client uses engine.fetch + engine.hooks automatically. */
+import { AgentBus } from '../bus/agent-bus';
+import { HookBus } from '../bus/hook-bus';
+import type { ProviderName } from '../llm/types/provider';
+import { NetworkEngine } from '../network/engine';
+import type { EngineConnect, EngineFetch, EngineFetchStream, FetchFn } from '../network/types';
+import { Cache } from '../plugins/cache/cache';
+import { CostCollector } from '../plugins/cost-collector/collector';
+import { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { Persistence } from '../plugins/persistence/types';
+export interface EngineHandle {
+    /** Trace session id — minted once for this engine (the holder), shared by
+     *  every request built against it. The session half of the OTel trace id. */
+    sessionId: string;
+    /** Shared HookBus across all subsystems built against this engine. */
+    hooks: HookBus;
+    /** Shared AgentBus for plugin → tool / module event communication. */
+    bus: AgentBus;
+    /** Persistence plugin. Always present — defaults to in-memory when no
+     *  `persistence` option was passed to `createEngine`. */
+    persistence: Persistence;
+    /** Optional Cache plugin. */
+    cache: Cache | null;
+    /** Network engine — owns the queue map and fetch lifecycle. */
+    network: NetworkEngine;
+    /** Bound NetworkEngine.fetch (function reference for LLMClient injection). */
+    fetch: EngineFetch;
+    /** Bound NetworkEngine.fetchStream. */
+    fetchStream: EngineFetchStream;
+    /** Bound NetworkEngine.connect — opens a realtime WebSocket (queue-exempt). */
+    connect: EngineConnect;
+    /** ModelCatalog. Always present — populated synchronously with provider
+     *  defaults when `engine.catalog: 'defaults'` (or `true`), else empty.
+     *  CostCollector / MediaOutput / ContextGuard / ContextMeasurer all
+     *  consult this. */
+    catalog: ModelCatalog;
+    /** CostCollector — subscribes to onCompletion + onMediaGenerated and
+     *  prices via catalog. Call `engine.cost.total()` for a running tally. */
+    cost: CostCollector;
+    /** API keys per provider. Helpers (createLLM, createAgent,
+     *  createMediaOutput, complete) read these to wire LLM clients without
+     *  the caller passing apiKey explicitly. */
+    apiKeys: Partial<Record<ProviderName, string>>;
+    /** Tear down all owned plugins. */
+    destroy(): void;
+}
+export interface PersistenceConfig {
+    type: 'memory' | 'file';
+    /** When type='file': directory under which entries are stored. */
+    dir?: string;
+}
+export interface CacheConfig {
+    type: 'memory';
+}
+export interface EngineConfig {
+    /** Trace session id. Pass one from a parent holder (server / orchestrator) to
+     *  correlate; omitted → a fresh `sess_…` is minted for this engine's lifetime. */
+    sessionId?: string;
+    /** Optional shared HookBus — when omitted, a fresh one is created. */
+    hooks?: HookBus;
+    /** Optional shared AgentBus. */
+    bus?: AgentBus;
+    /** Optional persistence backing for plugins that want durability. */
+    persistence?: PersistenceConfig | Persistence;
+    /** Optional cache. */
+    cache?: CacheConfig | Cache;
+    /** Custom low-level fetch transport — forwarded to the NetworkEngine's queue
+     *  (so retry/rate-limit/hooks still apply). Defaults to globalThis.fetch. */
+    fetch?: FetchFn;
+    /** Catalog wiring. Pass:
+     *    - `true` / 'defaults' → load every bundled provider catalog.json
+     *    - existing ModelCatalog instance → use as-is
+     *    - `{ entries: {...} }` → build empty + load() the entries
+     *    - undefined → empty catalog */
+    catalog?: ModelCatalog | true | 'defaults' | {
+        entries: Record<string, unknown>;
+    };
+    /** Per-provider API keys. Helpers consult this when no apiKey is passed
+     *  alongside `model: 'provider/...'`. */
+    apiKeys?: Partial<Record<ProviderName, string>>;
+    /** Register this engine as the default for `coreRegistry.get()` (used by
+     *  helpers when the caller doesn't pass an explicit `engine`). Defaults to
+     *  `true` so `createEngine({ ... })` followed by helper calls just works.
+     *  The FIRST `createEngine()` becomes the default; a second one throws unless
+     *  you pass `registerAsDefault: false` (then pass that engine explicitly to
+     *  helpers). */
+    registerAsDefault?: boolean;
+}
+export declare function createEngine(config?: EngineConfig): EngineHandle;
+declare class CoreRegistry {
+    private current;
+    /** Get the current default engine, creating a bare one on first read. */
+    get(): EngineHandle;
+    /** Set the default engine. Throws if one is already set unless replace=true.
+     *  When replacing, the previous engine is destroyed AFTER the pointer
+     *  swap so engine.destroy callbacks can safely query the registry. */
+    set(engine: EngineHandle, opts?: {
+        replace?: boolean;
+    }): void;
+    /** Clear the default engine. */
+    clear(): void;
+    has(): boolean;
+}
+export declare const coreRegistry: CoreRegistry;
+export {};

package/dist/helpers/estimate-types.d.ts

@@ -0,0 +1,67 @@
+/** estimate() — public types and error classes.
+ *  Extracted per project convention (no inline types in impl files). */
+/** How many output tokens to assume when none are specified.
+ *  Callers can override via `opts.expectedOutputTokens`. */
+export declare const DEFAULT_EXPECTED_OUTPUT_TOKENS = 512;
+/** Fallback model max-output cap when the catalog does not list one for a
+ *  model.  Used only for the `high` (worst-case) bound; deliberately
+ *  conservative rather than 0 so callers get a real upper-bound. */
+export declare const FALLBACK_MAX_OUTPUT_TOKENS = 4096;
+/** The three cost bounds `estimate()` returns. */
+export type EstimateBound = 'low' | 'expected' | 'high';
+/** Breakdown of the estimate by cost category (USD). */
+export interface EstimateBreakdown {
+    /** Cost of the input tokens. */
+    inputUsd: number;
+    /** Cost of the output tokens (varies by bound). */
+    outputUsd: number;
+    /** Per-image cost when present (not yet computed — see assumptions). */
+    imageUsd?: number;
+    /** Audio-input cost when present (not yet computed — see assumptions). */
+    audioUsd?: number;
+}
+/** The full result of `estimate()`. */
+export interface EstimateResult {
+    model: string;
+    /** Input tokens counted (or estimated) from the request. */
+    inputTokens: number;
+    /** Output tokens used for the `expected` bound. */
+    estOutputTokens: number;
+    cost: {
+        /** 0 output tokens (just input cost). */
+        low: number;
+        /** `estOutputTokens` output tokens. */
+        expected: number;
+        /** `maxTokens` or the model's maxOutput cap output tokens. */
+        high: number;
+    };
+    breakdown: EstimateBreakdown;
+    currency: 'USD';
+    /** Human-readable notes explaining assumptions made during estimation. */
+    assumptions: string[];
+}
+/** Thrown when `estimate()` is called with a model that is not in the catalog.
+ *  Distinct from `LLMError` because no network call was made. */
+export declare class UnknownModelError extends Error {
+    readonly provider: string;
+    readonly model: string;
+    constructor(provider: string, model: string);
+}
+/** Thrown by the budget guard when the estimated cost for the chosen `bound`
+ *  exceeds the caller-supplied `maxCostUsd` limit. */
+export declare class BudgetExceededError extends Error {
+    /** The bound that was checked ('low' | 'expected' | 'high'). */
+    readonly bound: EstimateBound;
+    /** The estimate that triggered the guard. */
+    readonly estimate: EstimateResult;
+    /** The limit that was exceeded (USD). */
+    readonly maxCostUsd: number;
+    /** The cost for the checked bound (USD). */
+    readonly costUsd: number;
+    constructor(opts: {
+        bound: EstimateBound;
+        estimate: EstimateResult;
+        maxCostUsd: number;
+        costUsd: number;
+    });
+}

package/dist/helpers/estimate.d.ts

@@ -0,0 +1,45 @@
+/** estimate() — pure, pre-flight cost estimation. Sends nothing to the
+ *  network.  Counts input tokens via the existing HybridTokenCounter (which
+ *  falls back to a heuristic when tiktoken is absent), then prices using the
+ *  ModelCatalog exactly as CostCollector does at runtime.
+ *
+ *    const est = await estimate({
+ *      model: 'anthropic/claude-haiku-4-5',
+ *      prompt: 'Hello',
+ *    });
+ *    // est.cost.expected  — mid-range cost in USD
+ *    // est.cost.high      — worst-case (output = maxOutput cap)
+ */
+import type { ContentPart, Message } from '../llm/types/messages';
+import type { ProviderName } from '../llm/types/provider';
+import { type EngineHandle } from './engine';
+import type { EstimateResult } from './estimate-types';
+export interface EstimateRequest {
+    /** Model string: bare (`gpt-5.4-nano` + `provider`) or namespaced
+     *  (`openai/gpt-5.4-nano`). */
+    model: string;
+    /** Required when `model` is bare. */
+    provider?: ProviderName;
+    /** Either a string prompt, an array of content parts, or a messages array.
+     *  Matches the `prompt` field on `CompleteOptions`. */
+    prompt: string | ContentPart[] | Message[];
+    /** Optional system prompt — included in input-token count. */
+    system?: string;
+    /** Hard limit on output tokens (used for the `high` bound). */
+    maxTokens?: number;
+}
+export interface EstimateOptions {
+    /** Override the model (else taken from `request.model`). */
+    model?: string;
+    /** Caller's guess for the expected output token count. When absent, the
+     *  helper uses `DEFAULT_EXPECTED_OUTPUT_TOKENS` and notes it in
+     *  `assumptions`. */
+    expectedOutputTokens?: number;
+    /** Optional engine for catalog + api-key access. Falls back to coreRegistry. */
+    engine?: EngineHandle;
+}
+/** Pre-flight cost estimate.  Pure — touches no network, no LLM provider.
+ *
+ *  Throws `UnknownModelError` when the model is absent from the catalog
+ *  (so callers never silently get $0 instead of a real estimate). */
+export declare function estimate(request: EstimateRequest, opts?: EstimateOptions): Promise<EstimateResult>;

package/dist/helpers/estimator.d.ts

@@ -0,0 +1,48 @@
+/** estimator.ts — Estimator class: static estimate() + optional adaptive
+ *  calibration (EWMA mean + histogram p90 per provider/model/input-bucket).
+ *
+ *  Usage (opt-in calibration):
+ *
+ *    const estimator = new Estimator({ calibration: { store: 'file', path: './data' } });
+ *
+ *    // Wire it to the engine so completions are recorded automatically:
+ *    const unsub = estimator.subscribeToEngine(engine);
+ *
+ *    // Use calibrated estimates:
+ *    const est = await estimator.estimate({ model: 'anthropic/claude-haiku-4-5', prompt: 'Hi' });
+ *    // est.cost.expected uses the EWMA mean (after data accumulates)
+ *    // est.cost.high     uses the p90 (capped at model ceiling)
+ *    // est.assumptions   records calibration source + count
+ *
+ *  Calling without calibration config is identical to the free estimate() fn. */
+import type { HookBus } from '../bus/hook-bus';
+import type { CompletionContext } from '../bus/hook-map';
+import { type EngineHandle } from './engine';
+import type { EstimateRequest } from './estimate';
+import { DEFAULT_EXPECTED_OUTPUT_TOKENS } from './estimate-types';
+import type { EstimateResult } from './estimate-types';
+import type { EstimatorOptions, CalibrationObservation } from './calibration-types';
+export type { EstimatorOptions } from './calibration-types';
+export declare class Estimator {
+    private readonly calibrationStore;
+    constructor(opts?: EstimatorOptions);
+    /** Pre-flight cost estimate.  When calibration is enabled AND the key has
+     *  data, uses the learned EWMA mean for `expected` and learned p90 (capped)
+     *  for `high`.  Otherwise falls back to the exact static estimate() behavior. */
+    estimate(request: EstimateRequest, opts?: import('./estimate').EstimateOptions): Promise<EstimateResult>;
+    /** Record one completion observation into the calibration store.
+     *  This is the manual "feed" path; subscribeToEngine() wires it automatically. */
+    record(obs: CalibrationObservation): Promise<void>;
+    /** Subscribe to an engine's onCompletion hook so every real completion
+     *  automatically updates the calibration store.
+     *  Returns an unsubscribe function. */
+    subscribeToEngine(engine: EngineHandle): () => void;
+    /** Subscribe directly to a HookBus (for advanced wiring). */
+    subscribeToHooks(hooks: HookBus): () => void;
+    private applyCalibratedBounds;
+}
+/** Compute and record a CalibrationObservation from raw CompletionContext fields.
+ *  Exported so tests can call it without a full engine wiring. */
+export declare function observationFromCompletion(ctx: CompletionContext): CalibrationObservation;
+/** Default_expected fallback re-exported for callers who import from Estimator. */
+export { DEFAULT_EXPECTED_OUTPUT_TOKENS };

package/dist/helpers/handoff-types.d.ts

@@ -0,0 +1,18 @@
+/** Types for the handoff() helper — structured agent-to-agent delegation.
+ *  Extracted per the library rule: types in *-types.ts, never inline. */
+import type { Usage } from '../llm/types/response';
+/** The structured result returned by a handoff tool call. */
+export interface HandoffResult {
+    /** Plain text response from the sub-agent. */
+    text: string;
+    /** Token usage reported by the sub-agent's run. Null when not available. */
+    usage: Usage | null;
+    /** The sub-agent's display name (passed as `name` to handoff()). */
+    agentName: string;
+}
+/** Options for handoff(). */
+export interface HandoffOptions {
+    /** Transform the task string before passing it to the sub-agent.
+     *  Useful for reformatting or adding context without modifying the parent's input. */
+    inputFilter?: (task: string) => string;
+}

package/dist/helpers/handoff.d.ts

@@ -0,0 +1,14 @@
+/** handoff — richer sibling to delegate().
+ *
+ *  Wraps an AgentLoop as an AgentTool but returns a structured HandoffResult
+ *  (text + usage + agentName) serialised as JSON, rather than bare text.
+ *  The parent loop sees usage and routing metadata in the tool result.
+ *
+ *  Like delegate(), it is a normal AgentTool so it flows through
+ *  onToolCallStart — approval gates or hook overrides still apply.
+ *
+ *  delegate() is kept unchanged for back-compat; handoff() is the richer path. */
+import type { AgentLoop } from '../agent/loop';
+import type { AgentTool } from '../agent/types';
+import type { HandoffOptions } from './handoff-types';
+export declare function handoff(name: string, description: string, agent: AgentLoop, opts?: HandoffOptions): AgentTool;

package/dist/helpers/llm.d.ts

@@ -0,0 +1,24 @@
+/** createLLM — convenience helper that builds an LLMClient using the
+ *  current EngineHandle (or the global coreRegistry default) for fetch +
+ *  hooks. Auto-resolves a default ProviderAdapter when none is supplied
+ *  (anthropic/openai/google/xai/openrouter). Accepts model in either
+ *  flat form (`{provider, model, apiKey}`) or namespaced form
+ *  (`{model: 'provider/name'}` — apiKey looked up on engine.apiKeys). */
+import { LLMClient } from '../llm/client';
+import type { LLMClientConfig } from '../llm/client-config';
+import type { ProviderName } from '../llm/types/provider';
+import type { EngineHandle } from './engine';
+export interface CreateLLMOptions extends Omit<LLMClientConfig, 'provider' | 'apiKey' | 'model' | 'fetch' | 'fetchStream' | 'hooks'> {
+    /** Model string. Either bare (e.g. `claude-haiku-4-5` — pair with `provider`)
+     *  or namespaced (e.g. `anthropic/claude-haiku-4-5` — provider parsed). */
+    model: string;
+    /** Required when `model` is bare. Ignored when `model` is namespaced. */
+    provider?: ProviderName;
+    /** Optional — falls back to `engine.apiKeys[provider]` when omitted. */
+    apiKey?: string;
+    engine?: EngineHandle;
+    hooks?: LLMClientConfig['hooks'];
+    fetch?: LLMClientConfig['fetch'];
+    fetchStream?: LLMClientConfig['fetchStream'];
+}
+export declare function createLLM(opts: CreateLLMOptions): LLMClient;

package/dist/helpers/mcp.d.ts

@@ -0,0 +1,82 @@
+/** Public MCP entry points.
+ *
+ *  `connectMcp(config)` — connect to one MCP server (url = Streamable HTTP,
+ *  command = stdio) and get its tools as `AgentTool[]`, ready to drop into
+ *  `complete()` / `createAgent()` with any provider.
+ *  `mcpToolset(configs)` — connect to several servers and get one flat toolset.
+ *
+ *  Client-side execution: the model sees ordinary function tools; our loop runs
+ *  `tools/call`. Works identically across every provider. See docs/design/mcp.md. */
+import type { AgentTool } from '../agent/types';
+import { McpClient } from '../plugins/mcp/client';
+import { type McpAuthProvider } from '../plugins/mcp/oauth';
+import type { SsrfGuardOptions } from '../plugins/mcp/url-guard';
+import { type McpSamplingConfig } from '../plugins/mcp/sampling';
+import { type McpElicitRequestParams, type McpElicitResult, type McpInitializeResult, type McpRoot, type McpServerConfig } from '../plugins/mcp/types';
+import { type EngineHandle } from './engine';
+export interface ConnectMcpOptions {
+    /** Engine providing `fetch`/`fetchStream` for HTTP transports. Default: the registered core engine. */
+    engine?: EngineHandle;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Per-request timeout (ms). */
+    timeoutMs?: number;
+    /** Namespace for tool names. Default: server name / url host / command basename. */
+    namespace?: string;
+    /** Every server->client notification (logging, *_changed, progress, …). */
+    onNotification?: (method: string, params: unknown) => void;
+    /** Re-list tools on `notifications/tools/list_changed` (updates `connection.tools` in place). */
+    autoRefreshTools?: boolean;
+    /** Called after an auto-refresh with the updated tool list. */
+    onToolsChanged?: (tools: AgentTool[]) => void;
+    /** Enable sampling: fulfill the server's `sampling/createMessage` with our LLM
+     *  (pass a model id) or a custom handler. Declares the `sampling` capability. */
+    sampling?: McpSamplingConfig;
+    /** Enable elicitation: answer the server's `elicitation/create`. Declares the capability. */
+    elicit?: (params: McpElicitRequestParams) => Promise<McpElicitResult>;
+    /** Expose filesystem roots to the server (`roots/list`). Declares the capability. */
+    roots?: McpRoot[] | (() => McpRoot[] | Promise<McpRoot[]>);
+    /** Validate tool `structuredContent` against the tool's `outputSchema`. */
+    validateOutput?: boolean;
+    /** Send a `ping` every N ms to keep the connection alive (0 = off). */
+    keepAliveMs?: number;
+    /** OAuth provider for servers that require authorization (HTTP only). On a
+     *  required interactive grant, `connectMcp` throws `McpUnauthorizedError`
+     *  after the provider redirects; finish with `finishMcpAuth`, then reconnect. */
+    auth?: McpAuthProvider;
+    /** SSRF security options for the OAuth flow. All options default to the most
+     *  restrictive posture (https-only, no loopback, same-origin). Use
+     *  `allowInsecureHttp`/`allowLoopback` ONLY for local development. */
+    security?: SsrfGuardOptions;
+}
+export interface McpConnection {
+    /** The server's initialize result (capabilities, serverInfo). */
+    readonly serverInfo: McpInitializeResult | null;
+    /** The server's tools, namespaced and ready for the loop. */
+    readonly tools: AgentTool[];
+    /** Re-fetch the tool list (returns freshly-wrapped AgentTools). */
+    listTools(): Promise<AgentTool[]>;
+    /** The underlying client (resources/prompts/logging/low-level access). */
+    readonly client: McpClient;
+    /** Disconnect (kill the process / terminate the HTTP session). */
+    close(): Promise<void>;
+}
+/** Connect to a single MCP server and return its tools + lifecycle handle. */
+export declare function connectMcp(config: McpServerConfig, opts?: ConnectMcpOptions): Promise<McpConnection>;
+/** Connect to several MCP servers and return one combined, namespaced toolset. */
+/** Finish an interactive OAuth grant: exchange the callback `code` for tokens
+ *  (saved via the provider). The `state` from the authorization callback MUST
+ *  be provided and is validated against the persisted value (CSRF guard).
+ *  Call after catching `McpUnauthorizedError`, then `connectMcp` again. */
+export declare function finishMcpAuth(serverUrl: string, code: string, state: string, opts: {
+    auth: McpAuthProvider;
+    engine?: EngineHandle;
+    security?: SsrfGuardOptions;
+}): Promise<void>;
+export declare function mcpToolset(configs: McpServerConfig[], opts?: ConnectMcpOptions): Promise<{
+    tools: AgentTool[];
+    connections: McpConnection[];
+    close(): Promise<void>;
+}>;

package/dist/helpers/media.d.ts

@@ -0,0 +1,58 @@
+/** createMediaOutput — convenience wrapper around MediaOutput.
+ *
+ *  Pass a `model: 'provider/...'` string and a `dir`; the helper:
+ *    - builds a FileMediaStore at `dir`,
+ *    - threads engine.fetch + hooks + catalog,
+ *    - auto-registers the right MediaProviderAdapter for the model's
+ *      provider (using engine.apiKeys[provider] for credentials),
+ *    - returns a MediaOutputHandle whose `generateImage / generateAudio /
+ *      generateVideo` methods don't repeat provider+model — the configured
+ *      defaults flow through.
+ *
+ *  Override the auto-built adapter via `providers` if you need a custom
+ *  baseURL or shared instance. */
+import type { ProviderName } from '../llm/types/provider';
+import { MediaOutput, type MediaOutputInit } from '../plugins/media/output';
+import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaProviderAdapter, MediaResult, MediaStore, VideoGenRequest } from '../plugins/media/types';
+import type { EngineHandle } from './engine';
+type ProviderAdapterMap = Partial<Record<string, MediaProviderAdapter>>;
+export interface CreateMediaOutputOptions {
+    /** Directory where generated media bytes + metadata land (Node/Bun). Provide
+     *  this OR `store`. */
+    dir?: string;
+    /** Bring your own MediaStore. Use `new MemoryMediaStore()` in the browser
+     *  (FileMediaStore needs a filesystem). Takes precedence over `dir`. */
+    store?: MediaStore;
+    /** Default model. Either bare (`gpt-image-1`, paired with `provider`) or
+     *  namespaced (`openai/gpt-image-1`). The helper builds the matching
+     *  adapter automatically when not overridden via `providers`. */
+    model?: string;
+    /** Required when `model` is bare or omitted. */
+    provider?: ProviderName;
+    /** Optional — falls back to `engine.apiKeys[provider]`. */
+    apiKey?: string;
+    /** Override or extend the auto-built provider adapter map. */
+    providers?: ProviderAdapterMap;
+    engine?: EngineHandle;
+    config?: MediaOutputInit['config'];
+}
+export interface MediaOutputHandle {
+    /** Underlying MediaOutput, in case you need to register more providers
+     *  or call methods that don't have a defaulting wrapper here. */
+    raw: MediaOutput;
+    /** Generate one or more images. `provider` and `model` default to the
+     *  ones passed to `createMediaOutput`. */
+    generateImage(req?: PartialMediaReq<ImageGenRequest>): Promise<MediaResult[]>;
+    generateAudio(req?: PartialMediaReq<AudioGenRequest>): Promise<MediaResult>;
+    editImage(req: PartialMediaReq<ImageEditRequest>): Promise<MediaResult[]>;
+    generateVideo(req?: PartialMediaReq<VideoGenRequest>): Promise<MediaResult>;
+}
+type PartialMediaReq<T extends {
+    provider: string;
+    model?: string;
+}> = Omit<T, 'provider' | 'model'> & {
+    provider?: string;
+    model?: string;
+};
+export declare function createMediaOutput(opts: CreateMediaOutputOptions): MediaOutputHandle;
+export {};

package/dist/helpers/models.d.ts

@@ -0,0 +1,36 @@
+/** Model listing.
+ *
+ *  `listModels()` — the SDK's curated local catalog (sync, no network). The
+ *  fast primary answer: ModelInfo with pricing + capabilities.
+ *
+ *  `listModelsLive()` — live availability from the provider's /models endpoint,
+ *  ENRICHED by default (merged with the frozen catalog; for OpenRouter, which
+ *  isn't bundled, built straight from the live API incl. prices). Pass
+ *  `{ raw: true }` for bare id strings. Results are cached IN MEMORY for 24h
+ *  (override with `refresh: true`). */
+import type { ProviderName } from '../llm/types/provider';
+import type { ModelInfo } from '../plugins/model-catalog/catalog';
+import { type EngineHandle } from './engine';
+/** Curated local catalog (the main answer). */
+export declare function listModels(opts?: {
+    provider?: ProviderName;
+    engine?: EngineHandle;
+}): ModelInfo[];
+export interface ListModelsLiveOptions {
+    provider: ProviderName;
+    apiKey?: string;
+    engine?: EngineHandle;
+    /** Return bare id strings instead of enriched ModelInfo. */
+    raw?: boolean;
+    /** Bypass the 24h memory cache and re-fetch. */
+    refresh?: boolean;
+}
+/** Test/maintenance hook. */
+export declare function clearLiveModelsCache(): void;
+/** Live models — enriched ModelInfo by default; `raw:true` → bare id strings.
+ *  Cached in memory for 24h (use `refresh:true` to force). Routes through
+ *  engine.fetch like every other call (central queue, hooks, rate-limit). */
+export declare function listModelsLive(opts: ListModelsLiveOptions & {
+    raw: true;
+}): Promise<string[]>;
+export declare function listModelsLive(opts: ListModelsLiveOptions): Promise<ModelInfo[]>;

package/dist/helpers/moderate-types.d.ts

@@ -0,0 +1,73 @@
+/** Types for the moderate() helper and the OpenAI Moderations API. */
+import type { ProviderName } from '../llm/types/provider';
+import type { EngineHandle } from './engine';
+/** Boolean flags per harm category. */
+export interface ModerationCategories {
+    harassment: boolean;
+    'harassment/threatening': boolean;
+    hate: boolean;
+    'hate/threatening': boolean;
+    illicit: boolean;
+    'illicit/violent': boolean;
+    'self-harm': boolean;
+    'self-harm/intent': boolean;
+    'self-harm/instructions': boolean;
+    'sexual': boolean;
+    'sexual/minors': boolean;
+    violence: boolean;
+    'violence/graphic': boolean;
+}
+/** Confidence scores (0-1) per harm category -- parallel shape to ModerationCategories. */
+export type ModerationScores = Record<keyof ModerationCategories, number>;
+/** One item's moderation result (one per input element). */
+export interface ModerationResult {
+    /** True when any category was triggered. */
+    flagged: boolean;
+    /** Per-category boolean flags. */
+    categories: ModerationCategories;
+    /** Per-category confidence scores (0-1). */
+    categoryScores: ModerationScores;
+    /** Input types the moderation was applied to, per category (omni models only). */
+    categoryAppliedInputTypes?: Record<string, string[]>;
+}
+/** A text content part for multimodal moderation input. */
+export interface ModerationTextPart {
+    type: 'text';
+    text: string;
+}
+/** An image URL content part for multimodal moderation input. */
+export interface ModerationImageUrlPart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+}
+/** A single content part: text or image_url. */
+export type ModerationContentPart = ModerationTextPart | ModerationImageUrlPart;
+/** Options for the moderate() helper. */
+export interface ModerateOptions {
+    /**
+     * Input to moderate. One of:
+     *   - a single string (returns a single ModerationResult)
+     *   - an array of strings (returns one result per string)
+     *   - a single content-part array (text + image_url, returns a single ModerationResult)
+     *   - an array of content-part arrays (one per item, returns one result per array)
+     */
+    input: string | string[] | ModerationContentPart[] | ModerationContentPart[][];
+    /** Model name. Defaults to omni-moderation-latest. */
+    model?: string;
+    provider?: ProviderName;
+    apiKey?: string;
+    engine?: EngineHandle;
+}
+export interface ModerationRawResult {
+    flagged: boolean;
+    categories: Record<string, boolean>;
+    category_scores: Record<string, number>;
+    category_applied_input_types?: Record<string, string[]>;
+}
+export interface ModerationRawResponse {
+    id: string;
+    model: string;
+    results: ModerationRawResult[];
+}

package/dist/helpers/moderate.d.ts

@@ -0,0 +1,13 @@
+/** moderate() -- one-shot content moderation via OpenAI's moderations API.
+ *
+ *    const result = await moderate({ input: 'some text' });
+ *    if (result.flagged) { ... }
+ *
+ *  When input is a string or content-part array, a single ModerationResult is
+ *  returned. When input is an array of strings (or array of content-part arrays),
+ *  one ModerationResult per element is returned (matching array length).
+ *
+ *  The moderations endpoint is FREE; an honest-zero cost entry is always emitted
+ *  so the cost ledger has a record of each call. HTTP flows through engine.fetch. */
+import type { ModerateOptions, ModerationResult } from './moderate-types';
+export declare function moderate(opts: ModerateOptions): Promise<ModerationResult | ModerationResult[]>;

package/dist/helpers/moderation-guardrail.d.ts

@@ -0,0 +1,29 @@
+/** moderationGuardrail — built-in guardrail backed by the OpenAI moderations API.
+ *
+ *  Creates a Guardrail that calls moderate() on the last user message (input kind)
+ *  or on the assistant response text (output kind). If the moderation result is
+ *  flagged, the guardrail trips with severity 'high'.
+ *
+ *  Usage:
+ *    const guard = moderationGuardrail({ apiKey: '...' });
+ *    const agent = new AgentLoop({ client, guardrails: [guard] });
+ *
+ *  The moderation endpoint is free; a zero-cost entry is always emitted via the
+ *  engine hook bus (see moderate.ts). Requires an OpenAI API key — fails clearly
+ *  when invoked without one. */
+import type { Guardrail } from '../agent/guardrail-types';
+export interface ModerationGuardrailOptions {
+    /** OpenAI API key. Falls back to engine.apiKeys['openai'] when omitted. */
+    apiKey?: string;
+    /** Moderate the input (user messages). Default: true. */
+    input?: boolean;
+    /** Moderate the output (assistant responses). Default: false. */
+    output?: boolean;
+    /** Moderation model. Defaults to the moderate() helper default (omni-moderation-latest). */
+    model?: string;
+    /** Custom guardrail name prefix. Defaults to 'moderation'. */
+    name?: string;
+}
+/** Build one or two Guardrail instances backed by the OpenAI moderations endpoint.
+ *  Pass both into `guardrails` on AgentLoopConfig — one for input, one for output. */
+export declare function moderationGuardrail(opts?: ModerationGuardrailOptions): Guardrail[];