@combycode/llm-sdk 1.0.0-rc.0

package/dist/helpers/batch.d.ts

@@ -0,0 +1,74 @@
+/** batch() / submitBatch() / batchJob() — explicit batch processing.
+ *
+ *  A batch request is a deferred complete(): you describe each item the same way
+ *  (prompt/system/maxTokens/…), the helper builds the per-provider body via that
+ *  provider's adapter, submits one batch, and gives back a BatchJob handle.
+ *
+ *  Two modes off the SAME handle:
+ *    - AUTO   : `await batch({...})` or `await job.wait()` — polls until done.
+ *    - MANUAL : keep `job.id`, persist it, later `batchJob({id, provider})` →
+ *               `job.status()` / `job.results()` (results() throws until complete).
+ *
+ *  Reuses the existing per-provider BatchProviderAdapters; all HTTP flows through
+ *  engine.fetch (queue/retry/hooks). */
+import type { ContentPart, Message } from '../llm/types/messages';
+import type { ProviderName } from '../llm/types/provider';
+import type { CompletionResponse } from '../llm/types/response';
+import type { BatchStatus } from '../plugins/batch/types';
+import type { EngineHandle } from './engine';
+export interface BatchRequestInput {
+    /** Correlation id. Defaults to `req-<index>` when omitted. */
+    customId?: string;
+    prompt: string | ContentPart[] | Message[];
+    system?: string;
+    maxTokens?: number;
+    temperature?: number;
+    structured?: {
+        schema: Record<string, unknown>;
+        name?: string;
+    };
+}
+export interface BatchItemResult {
+    customId: string;
+    success: boolean;
+    /** Parsed reply text ('' when failed or empty). */
+    text: string;
+    /** Full normalized response (usage, finishReason, raw), or null on failure. */
+    response: CompletionResponse | null;
+    error: string | null;
+}
+export interface WaitOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    onProgress?: (status: BatchStatus) => void;
+}
+export interface BatchJob {
+    readonly id: string;
+    readonly provider: ProviderName;
+    /** Current provider-side status (manual progress check). */
+    status(): Promise<BatchStatus>;
+    /** Fetch results. Throws if the batch is not yet in a terminal state. */
+    results(): Promise<BatchItemResult[]>;
+    /** Poll until terminal, then return results (auto mode). */
+    wait(opts?: WaitOptions): Promise<BatchItemResult[]>;
+    cancel(): Promise<void>;
+}
+export interface SubmitBatchOptions {
+    model: string;
+    provider?: ProviderName;
+    apiKey?: string;
+    requests: BatchRequestInput[];
+    engine?: EngineHandle;
+}
+export interface BatchJobRef {
+    id: string;
+    provider: ProviderName;
+    apiKey?: string;
+    engine?: EngineHandle;
+}
+/** Submit a batch; returns a handle immediately (no blocking). */
+export declare function submitBatch(opts: SubmitBatchOptions): Promise<BatchJob>;
+/** Reconstruct a handle from a persisted id (resume — manual mode only). */
+export declare function batchJob(ref: BatchJobRef): BatchJob;
+/** One-shot auto mode: submit + wait + results. */
+export declare function batch(opts: SubmitBatchOptions & WaitOptions): Promise<BatchItemResult[]>;

package/dist/helpers/calibration-store.d.ts

@@ -0,0 +1,27 @@
+/** calibration-store.ts — per-key output-token running statistics.
+ *
+ *  Maintains an EWMA mean and a fixed-bin histogram for p90 estimation.
+ *  State is serialized via the Persistence interface (FilePersistence or
+ *  MemoryPersistence) so it survives process restarts when configured. */
+import type { Persistence } from '../plugins/persistence/types';
+import { type InputBucketLabel, type CalibrationObservation, type OutputCalibrationConfig, type OutputCalibrationEntry } from './calibration-types';
+/** Map an input-token count to its named bucket label. */
+export declare function inputBucketLabel(inputTokens: number): InputBucketLabel;
+/** Build the persistence key for a provider/model + bucket. */
+export declare function calibrationKey(provider: string, model: string, bucket: InputBucketLabel): string;
+export declare class OutputCalibrationStore {
+    private readonly persistence;
+    private readonly alpha;
+    constructor(persistence: Persistence, config?: OutputCalibrationConfig);
+    /** Record one observed completion, updating EWMA mean and histogram. */
+    record(obs: CalibrationObservation): Promise<void>;
+    /** Retrieve the calibration entry for a provider/model + input-token count.
+     *  Returns null when no data exists for that key. */
+    get(provider: string, model: string, inputTokens: number): Promise<OutputCalibrationEntry | null>;
+    /** Compute the p90 output-token estimate from a stored entry. */
+    p90(entry: OutputCalibrationEntry): number;
+    /** List all stored keys (for testing/introspection). */
+    listKeys(): Promise<string[]>;
+    private newEntry;
+    private updateEntry;
+}

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

@@ -0,0 +1,64 @@
+/** calibration-types.ts — types and constants for the adaptive output-token
+ *  calibration layer used by Estimator.
+ *
+ *  All tuneable values live here as named constants (no magic numbers). */
+/** Upper edges (exclusive) for input-token size buckets.
+ *  E.g. edge 500 means the bucket covers [prev-edge, 500).
+ *  The last bucket is open-ended: [32000, +inf). */
+export declare const INPUT_SIZE_BUCKET_EDGES: readonly [500, 2000, 8000, 32000];
+/** Human-readable labels, one per bucket (including the final open bucket). */
+export declare const INPUT_SIZE_BUCKET_LABELS: readonly ["0-500", "500-2000", "2000-8000", "8000-32000", "32000+"];
+export type InputBucketLabel = (typeof INPUT_SIZE_BUCKET_LABELS)[number];
+/** Smoothing factor for the exponentially weighted moving average of output
+ *  tokens.  Higher = faster adaptation; lower = smoother, less noisy.
+ *  Range: (0, 1). */
+export declare const CALIBRATION_EWMA_ALPHA = 0.15;
+/** Number of fixed bins in the output-token histogram used to estimate p90.
+ *  More bins = higher resolution but more memory per key.
+ *  Each bin represents a contiguous token-count range of P90_BIN_WIDTH. */
+export declare const P90_HISTOGRAM_BIN_COUNT = 32;
+/** Width of each histogram bin in output tokens. */
+export declare const P90_HISTOGRAM_BIN_WIDTH = 256;
+/** The quantile to track as the "high" calibrated bound. */
+export declare const CALIBRATION_HIGH_QUANTILE = 0.9;
+export declare const OUTPUT_CALIBRATION_KEY_PREFIX = "output-calibration:";
+/** Compact per-key running state stored in persistence. */
+export interface OutputCalibrationEntry {
+    /** Learning key: `provider/model#inputBucket` */
+    key: string;
+    /** EWMA-smoothed mean of observed output tokens. */
+    ewmaMean: number;
+    /** Fixed-count histogram of output token observations.
+     *  Index i covers [i * P90_HISTOGRAM_BIN_WIDTH, (i+1) * P90_HISTOGRAM_BIN_WIDTH).
+     *  The last bin is open-ended (captures all values >= (BIN_COUNT-1) * BIN_WIDTH). */
+    histogram: number[];
+    /** Total observations recorded. */
+    count: number;
+    /** Timestamp of the most recent update. */
+    lastUpdated: number;
+}
+export interface OutputCalibrationConfig {
+    /** EWMA smoothing alpha; defaults to CALIBRATION_EWMA_ALPHA. */
+    ewmaAlpha?: number;
+}
+export interface CalibrationStoreConfig {
+    /** 'file' persists to disk via FilePersistence. 'memory' is in-process only. */
+    store: 'file' | 'memory';
+    /** Required when store='file'. Directory for the FilePersistence JSON files. */
+    path?: string;
+}
+export interface EstimatorOptions {
+    /** When provided, enables adaptive calibration. Without this field the
+     *  Estimator behaves identically to the static estimate() function. */
+    calibration?: CalibrationStoreConfig;
+}
+export interface CalibrationObservation {
+    /** Provider string, e.g. 'anthropic'. */
+    provider: string;
+    /** Model string, e.g. 'claude-haiku-4-5'. */
+    model: string;
+    /** Input-token count for this completion (used to map to bucket). */
+    inputTokens: number;
+    /** Actual output tokens observed. */
+    outputTokens: number;
+}

package/dist/helpers/chain.d.ts

@@ -0,0 +1,30 @@
+/** chain — sequential pipeline where each step's output feeds the next.
+ *
+ *  Each step is either:
+ *    - an object describing a `complete()` call with a `prompt(input)`
+ *      function that takes the previous output and returns the user prompt,
+ *    - or a plain async function `(input: string) => string` (handy for
+ *      delegating to an AgentLoop or running custom logic).
+ *
+ *  Returns a callable. The optional `onStep` callback fires after every
+ *  step with its index, optional name, and produced output — perfect for
+ *  logging the Input → A → Output → B → Output → ... flow. */
+import { type CompleteOptions } from './one-shot';
+export interface ChainStepConfig extends Omit<CompleteOptions, 'prompt'> {
+    /** Optional label surfaced via `onStep` and useful for debugging. */
+    name?: string;
+    /** Receives the previous step's output (or the original input on step 1)
+     *  and returns the user-visible prompt string for this LLM call. */
+    prompt: (input: string) => string;
+}
+export type ChainStepFn = (input: string) => Promise<string> | string;
+export type ChainStep = ChainStepConfig | ChainStepFn;
+export interface ChainOptions {
+    /** Fires after every step with its index, optional name, and output. */
+    onStep?: (info: {
+        index: number;
+        name?: string;
+        output: string;
+    }) => void;
+}
+export declare function chain(steps: ChainStep[], options?: ChainOptions): (input: string) => Promise<string>;

package/dist/helpers/client-pool.d.ts

@@ -0,0 +1,15 @@
+/** ClientPool — keys LLMClients by provider (default) or (provider+model)
+ *  when catalog marks a model as requiresDedicatedClient. Used by
+ *  ClientResolver and (in the legacy SDK) by InternalToolRunner. */
+import { LLMClient } from '../llm/client';
+import type { LLMClientConfig } from '../llm/client-config';
+import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+export declare class ClientPool {
+    private readonly catalog?;
+    private clients;
+    constructor(catalog?: ModelCatalog | undefined);
+    get(provider: string, model: string, config: LLMClientConfig): LLMClient;
+    destroy(): Promise<void>;
+    get size(): number;
+    private keyFor;
+}

package/dist/helpers/client-resolver.d.ts

@@ -0,0 +1,62 @@
+/** ClientResolver — turns a `"provider/model"` string into a pooled LLMClient.
+ *
+ *  Lives on the orchestrator so every module registered with it can share one
+ *  pool of clients (one per provider, keyed per-model only when the catalog
+ *  marks `requiresDedicatedClient`). Wraps the same ClientPool used by
+ *  internal-tool-runners — one keying policy across the SDK. */
+import type { LLMClient } from '../llm/client';
+import type { LLMClientConfig } from '../llm/client-config';
+import type { HookBus } from '../bus/hook-bus';
+import type { ProviderName } from '../llm/types/provider';
+import type { ServiceTier } from '../llm/types/tiers';
+import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { EngineFetch, EngineFetchStream } from '../network/types';
+export interface ClientResolverConfig {
+    /** provider → API key. Providers absent from this map can't be resolved. */
+    apiKeys: Partial<Record<ProviderName, string>>;
+    /** Hooks piped to every constructed LLMClient. */
+    hooks: HookBus;
+    /** Fetch function (typically engine.fetch). When absent, falls back to
+     *  `globalThis.fetch.bind(globalThis)` — fine for simple direct-call use,
+     *  bypasses the NetworkEngine queue + retry. Pass engine.fetch for
+     *  production. */
+    fetch?: EngineFetch;
+    /** Streaming fetch (typically engine.fetchStream). Optional. */
+    fetchStream?: EngineFetchStream;
+    /** Catalog drives pool keying (requiresDedicatedClient) + capability hints. */
+    catalog?: ModelCatalog;
+    /** Extra LLMClient options applied to every resolved client. */
+    clientOptions?: Partial<Omit<LLMClientConfig, 'provider' | 'apiKey' | 'hooks' | 'catalog' | 'model' | 'fetch' | 'fetchStream'>>;
+}
+export interface ResolvedClient {
+    client: LLMClient;
+    provider: ProviderName;
+    model: string;
+}
+export declare class ClientResolver {
+    private readonly cfg;
+    private readonly pool;
+    constructor(cfg: ClientResolverConfig);
+    /** Turn `"anthropic/claude-haiku-4-5"` → resolved client. */
+    resolve(modelId: string): ResolvedClient;
+    availableProviders(): ProviderName[];
+    destroy(): Promise<void>;
+    get size(): number;
+}
+export declare function parseModelId(modelId: string): [ProviderName, string];
+export declare function isNamespacedModelId(modelId: string): boolean;
+/** Resolve a model + optional provider to a concrete { provider, model }.
+ *  A namespaced id ("provider/model") yields its own provider; a bare model
+ *  requires an explicit `provider`. `label` names the caller in the error. */
+export declare function resolveModel(model: string, provider: ProviderName | undefined, label: string): {
+    provider: ProviderName;
+    model: string;
+};
+/** Split a trailing `:tier` off a model id, but only when the suffix is a known
+ *  service tier. `"anthropic/claude-opus-4.8:priority"` → { modelId:
+ *  "anthropic/claude-opus-4.8", serviceTier: "priority" }; `"…/qwen3-coder:free"`
+ *  → unchanged (`:free` is an OpenRouter variant, not a tier). */
+export declare function parseModelTier(modelId: string): {
+    modelId: string;
+    serviceTier?: ServiceTier;
+};

package/dist/helpers/collection.d.ts

@@ -0,0 +1,19 @@
+/** createCollection — typed namespace over `engine.persistence`.
+ *
+ *  Wraps the raw key/value persistence in a small typed handle keyed by
+ *  short names within a single namespace. Lets app code talk in domain
+ *  terms (subagents, prompts, conversations) without juggling key
+ *  prefixes or the underlying file/db wiring. */
+export interface Collection<T> {
+    set(key: string, value: T): Promise<void>;
+    get(key: string): Promise<T | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /** Short keys (without the namespace prefix). */
+    keys(): Promise<string[]>;
+    /** All values. */
+    list(): Promise<T[]>;
+    /** [shortKey, value] pairs. */
+    entries(): Promise<Array<[string, T]>>;
+}
+export declare function createCollection<T>(name: string): Collection<T>;

package/dist/helpers/consolidate.d.ts

@@ -0,0 +1,66 @@
+/** consolidate — multi-agent debate that runs up to N rounds, stops early
+ *  when the agents converge, and produces a final summary.
+ *
+ *  Each round, every agent answers the task in parallel (seeing the prior
+ *  round's answers). After each round a judge LLM evaluates whether the
+ *  agents reached substantive agreement (structured JSON output). When
+ *  it returns `agreed: true`, the loop exits early. Either way a closing
+ *  summary call returns the consensus + per-agent unique points. */
+import type { CompleteOptions, CompleteResult } from './one-shot';
+export interface ConsolidateAgent {
+    /** Display name surfaced via `onRound` and inside summary prompts. */
+    name: string;
+    /** Namespaced model id, e.g. `anthropic/claude-haiku-4-5`. */
+    model: string;
+    /** Persona / role text. */
+    system: string;
+}
+export interface ConsolidateAnswer {
+    agent: string;
+    text: string;
+}
+export interface ConsolidateRoundInfo {
+    round: number;
+    answers: ConsolidateAnswer[];
+    agreed: boolean;
+    judgeReason: string;
+}
+export interface ConsolidateJudge {
+    /** Namespaced model id for the judge. SHOULD be different from any
+     *  participating agent's model — otherwise the judge is evaluating its
+     *  own answer as one of the inputs, which biases the verdict. */
+    model: string;
+    /** Optional override for the judge system prompt. */
+    system?: string;
+}
+/** Internal type for the completion function signature. */
+export type CompleteFn = (opts: CompleteOptions) => Promise<CompleteResult>;
+export interface ConsolidateOptions {
+    /** Two or more agents — heterogeneous models recommended. */
+    agents: ConsolidateAgent[];
+    /** The question / task they are debating. */
+    task: string;
+    /** External judge that decides round-by-round agreement and writes the
+     *  closing summary. Must be a separate model from the debate participants
+     *  to avoid self-evaluation bias. */
+    judge: ConsolidateJudge;
+    /** Maximum rounds before the loop ends regardless of agreement. */
+    rounds?: number;
+    /** Per-agent maxTokens for each round. */
+    maxTokens?: number;
+    /** Fires after every round with the answers + judge verdict. */
+    onRound?: (info: ConsolidateRoundInfo) => void;
+    /** Internal seam for tests — inject a fake complete() instead of the real one.
+     *  Not part of the public API; omit in production code. */
+    _complete?: CompleteFn;
+}
+export interface ConsolidateResult {
+    /** Closing summary text (consensus + per-agent unique points). */
+    summary: string;
+    /** Every round's answers, in order. */
+    rounds: ConsolidateAnswer[][];
+    /** 1-based round index where the judge declared agreement, or null
+     *  if the loop ran to `rounds`. */
+    agreedAt: number | null;
+}
+export declare function consolidate(opts: ConsolidateOptions): Promise<ConsolidateResult>;

package/dist/helpers/content.d.ts

@@ -0,0 +1,25 @@
+/** Content helpers — small builders for inline message parts.
+ *
+ *  loadImageContent does the dirty work of fetching / reading / base64-
+ *  encoding / mime-detecting an image and returns a ready-to-send
+ *  `ContentPart` (type: 'image', source: { type: 'base64', mimeType, data }).
+ *
+ *  Accepts:
+ *    - string starting with 'http://' or 'https://' → fetch
+ *    - any other string                              → read from disk
+ *    - Uint8Array                                    → use bytes directly
+ *
+ *  Mime is auto-detected from URL extension OR file extension OR magic
+ *  bytes (PNG / JPEG / GIF / WebP) when neither path applies. */
+import type { ContentPart } from '../llm/types/messages';
+export interface LoadImageOptions {
+    /** Optional override for the auto-detected mime type. */
+    mimeType?: string;
+    /** Optional User-Agent for URL fetches (some hosts e.g. Wikipedia 429 the default). */
+    userAgent?: string;
+}
+export declare function loadImageContent(source: string | Uint8Array, options?: LoadImageOptions): Promise<ContentPart>;
+/** Load any inline content part (image / PDF document / audio / video), choosing
+ *  the part type from the detected MIME. Use this for mixed attachments;
+ *  `loadImageContent` forces an image part. */
+export declare function loadContent(source: string | Uint8Array, options?: LoadImageOptions): Promise<ContentPart>;

package/dist/helpers/conversation-export.d.ts

@@ -0,0 +1,14 @@
+/** Conversation export — render a Message[] conversation as Markdown for
+ *  archiving / sharing / debugging. Media parts become Markdown links: an inline
+ *  image embeds its data-URL (self-contained, no archive needed); other media
+ *  link to their URL or a short placeholder. */
+import type { Message } from '../llm/types/messages';
+export interface ConversationExportOptions {
+    /** Embed media as data-URL links (self-contained). When false, media is a
+     *  short `[image]` placeholder. Default true. */
+    inlineMedia?: boolean;
+    /** Optional title at the top of the document. */
+    title?: string;
+}
+/** Render a conversation as Markdown. */
+export declare function conversationToMarkdown(messages: Message[], opts?: ConversationExportOptions): string;

package/dist/helpers/conversation-zip.d.ts

@@ -0,0 +1,28 @@
+/** Conversation export as a ZIP archive — Markdown with media pulled OUT into
+ *  separate files (`media/media-001.png`) and referenced by relative link,
+ *  instead of inlined as multi-megabyte data-URLs.
+ *
+ *  The ZIP is written by hand in STORE mode (no compression) so the library
+ *  keeps its zero-runtime-dependency promise — no `jszip`. Store mode is a
+ *  trivial container (local headers + central directory + EOCD); media blobs
+ *  (PNG/MP4/…) are already compressed, so store costs almost nothing. */
+import type { Message } from '../llm/types/messages';
+export interface ConversationZipOptions {
+    /** Document title (H1 at the top of the Markdown). */
+    title?: string;
+    /** Markdown file name inside the archive. Default 'conversation.md'. */
+    markdownName?: string;
+    /** Folder for extracted media. Default 'media'. */
+    mediaDir?: string;
+}
+export interface ConversationZipResult {
+    /** The .zip file bytes — wrap in a Blob to download. */
+    bytes: Uint8Array;
+    /** The Markdown document (also embedded in the zip), for preview/debug. */
+    markdown: string;
+    /** How many media files were extracted into the archive. */
+    mediaCount: number;
+}
+/** Build a downloadable ZIP of the conversation: one Markdown file plus every
+ *  embedded media blob as its own file under `media/`. */
+export declare function conversationToZip(messages: Message[], opts?: ConversationZipOptions): ConversationZipResult;

package/dist/helpers/count-tokens.d.ts

@@ -0,0 +1,26 @@
+/** countTokens() — thin convenience over the existing ContextMeasurer token
+ *  counters. Does NOT implement counting itself: it builds a HybridTokenCounter
+ *  from the engine catalog (which routes per model to tiktoken / provider
+ *  count-API / heuristic) and calls it.
+ *
+ *    const n = await countTokens({ model: 'openai/gpt-5.4-nano', input: 'hello' });
+ *
+ *  `exact:true` (default) uses the precise path where available — tiktoken for
+ *  OpenAI, the count-API for Anthropic/Google (needs apiKey) — and falls back to
+ *  the calibrated heuristic otherwise. `exact:false` is always a sync estimate. */
+import type { Message } from '../llm/types/messages';
+import type { ProviderName } from '../llm/types/provider';
+import { type EngineHandle } from './engine';
+export interface CountTokensOptions {
+    /** Model string. Bare (`gpt-5.4-nano`, pair with `provider`) or namespaced. */
+    model: string;
+    provider?: ProviderName;
+    /** Text or messages to count. */
+    input: string | Message[];
+    /** Key for the exact count-API path (Anthropic/Google). Falls back to engine.apiKeys. */
+    apiKey?: string;
+    /** Use the precise counter where available (default true). false = sync estimate. */
+    exact?: boolean;
+    engine?: EngineHandle;
+}
+export declare function countTokens(opts: CountTokensOptions): Promise<number>;

package/dist/helpers/define-tool.d.ts

@@ -0,0 +1,66 @@
+/** defineTool — concise builder for AgentTool.
+ *
+ *  Reduces tool boilerplate. Instead of:
+ *
+ *    {
+ *      definition: {
+ *        name: 'word_count',
+ *        description: 'Count words',
+ *        parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+ *      },
+ *      execute: async (args) => String((args as {text:string}).text.split(/\s+/).length),
+ *    }
+ *
+ *  write:
+ *
+ *    defineTool({
+ *      name: 'word_count',
+ *      description: 'Count words',
+ *      params: { text: 'string' },
+ *      execute: (args) => String(args.text.split(/\s+/).length),
+ *    })
+ *
+ *  Type inference flows from `params` to the typed `args` parameter of
+ *  `execute`. */
+import type { AgentTool, ToolExecutionContext } from '../agent/types';
+import type { ContentPart } from '../llm/types/messages';
+/** Param spec — one of the JSON-schema scalars or an inline object. */
+export type ParamSpec = 'string' | 'number' | 'integer' | 'boolean' | 'string[]' | 'number[]' | {
+    type: 'string' | 'number' | 'integer' | 'boolean';
+    enum?: readonly string[];
+    description?: string;
+} | {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    description?: string;
+} | {
+    type: 'array';
+    items: unknown;
+    description?: string;
+};
+/** Translate a ParamSpec to its TypeScript type, used to infer `args`. */
+type InferParam<S> = S extends 'string' ? string : S extends 'number' | 'integer' ? number : S extends 'boolean' ? boolean : S extends 'string[]' ? string[] : S extends 'number[]' ? number[] : S extends {
+    type: 'string';
+    enum: infer E;
+} ? E extends readonly (infer U)[] ? U : string : S extends {
+    type: 'string';
+} ? string : S extends {
+    type: 'number' | 'integer';
+} ? number : S extends {
+    type: 'boolean';
+} ? boolean : unknown;
+type InferArgs<P extends Record<string, ParamSpec>> = {
+    [K in keyof P]: InferParam<P[K]>;
+};
+export interface DefineToolInput<P extends Record<string, ParamSpec>> {
+    name: string;
+    description: string;
+    /** Object spec — keys are arg names. All keys are treated as required by
+     *  default; mark optional ones via `optional: ['x']`. */
+    params: P;
+    optional?: ReadonlyArray<keyof P & string>;
+    execute: (args: InferArgs<P>, context: ToolExecutionContext) => Promise<string | ContentPart[]> | string | ContentPart[];
+}
+export declare function defineTool<P extends Record<string, ParamSpec>>(input: DefineToolInput<P>): AgentTool;
+export {};

package/dist/helpers/delegate.d.ts

@@ -0,0 +1,6 @@
+/** delegate — wrap an AgentLoop as a single AgentTool that another agent
+ *  can call. The tool takes a `task: string` and returns the sub-agent's
+ *  reply text. Useful for agent-as-tool composition / routing patterns. */
+import type { AgentLoop } from '../agent/loop';
+import type { AgentTool } from '../agent/types';
+export declare function delegate(name: string, description: string, agent: AgentLoop): AgentTool;

package/dist/helpers/embed.d.ts

@@ -0,0 +1,24 @@
+/** embed() — one-shot text→vector helper, mirroring complete().
+ *
+ *    const { embeddings, dimensions } = await embed({
+ *      model: 'openai/text-embedding-3-small',
+ *      input: 'hello',
+ *    });
+ *    // embeddings[0] is the vector; dimensions is its length.
+ *
+ *  Providers: openai, openrouter (OpenAI-compat), google. (anthropic/xai have no
+ *  first-party embeddings endpoint.) HTTP flows through engine.fetch. */
+import type { ProviderName } from '../llm/types/provider';
+import type { EmbedResult, EmbeddingProviderAdapter } from '../plugins/embeddings/types';
+import { type EngineHandle } from './engine';
+export interface EmbedOptions {
+    /** Model string. Bare (pair with `provider`) or namespaced (`openai/text-embedding-3-small`). */
+    model: string;
+    provider?: ProviderName;
+    apiKey?: string;
+    input: string | string[];
+    /** Override the auto-built provider adapter. */
+    adapter?: EmbeddingProviderAdapter;
+    engine?: EngineHandle;
+}
+export declare function embed(opts: EmbedOptions): Promise<EmbedResult>;