@combycode/llm-sdk 1.0.0-rc.0

package/dist/plugins/context-measurer/measurer.d.ts

@@ -0,0 +1,49 @@
+/** ContextMeasurer — auto-wires measurement + calibration learning.
+ *  Pattern matches CostCollector / FilesRegistry: instantiate → hooks attach. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { Message } from '../../llm/types/messages';
+import type { TokenCounter } from '../../agent/types';
+import type { ConversationHistory } from '../../agent/history';
+import type { ModelCatalog } from '../model-catalog/catalog';
+import type { Persistence } from '../persistence/types';
+import type { CalibrationStore, ContextThresholds, CalibrationConfig } from './types';
+export interface ContextMeasurerConfig {
+    hooks: HookBus;
+    catalog: ModelCatalog;
+    /** Use an explicit counter, else a HybridTokenCounter is built from catalog. */
+    counter?: TokenCounter;
+    /** Persistence for calibration. If absent, no calibration learning occurs. */
+    persistence?: Persistence;
+    /** Explicit calibration store (overrides persistence). */
+    calibrationStore?: CalibrationStore;
+    /** API keys for exact counting endpoints. */
+    countApiKeys?: {
+        anthropic?: string;
+        google?: string;
+    };
+    /** Thresholds for warning/exact escalation. */
+    thresholds?: Partial<ContextThresholds>;
+    /** Calibration tuning (EMA alpha, confidence samples). */
+    calibration?: Partial<CalibrationConfig>;
+}
+export declare class ContextMeasurer {
+    readonly counter: TokenCounter;
+    readonly calibrationStore: CalibrationStore | null;
+    readonly thresholds: ContextThresholds;
+    private hooks;
+    private catalog;
+    private unsubscribers;
+    constructor(config: ContextMeasurerConfig);
+    private wire;
+    destroy(): void;
+    /** Pre-warm calibration cache on startup. */
+    warmCache(): Promise<void>;
+    /** Measure + emit onContextMeasure. Returns final state including any abort
+     *  set by listeners (ContextGuard may set it). */
+    measureAndEmit(provider: string, model: string, messages: Message[], history?: ConversationHistory, system?: string): Promise<{
+        total: number;
+        abort: boolean;
+        abortReason?: string;
+    }>;
+    private learnFromCompletion;
+}

package/dist/plugins/context-measurer/types.d.ts

@@ -0,0 +1,40 @@
+/** ContextMeasurer plugin types — calibration shapes + measurer config. */
+import type { ContentClass } from '../../agent/types';
+export interface CalibrationEntry {
+    provider: string;
+    model: string;
+    contentClass?: ContentClass;
+    charsPerToken: number;
+    samples: number;
+    confidence: number;
+    lastUpdated: number;
+}
+export interface CalibrationStore {
+    get(provider: string, model: string, contentClass?: ContentClass): Promise<CalibrationEntry | null>;
+    update(entry: Omit<CalibrationEntry, 'lastUpdated' | 'confidence'>): Promise<CalibrationEntry>;
+    list(opts?: {
+        provider?: string;
+        model?: string;
+    }): Promise<CalibrationEntry[]>;
+    reset(opts?: {
+        provider?: string;
+        model?: string;
+    }): Promise<void>;
+}
+export interface ContextThresholds {
+    /** Percentage (0-1) at which to warn. Default 0.80. */
+    warn: number;
+    /** Percentage (0-1) at which to upgrade to exact measurement. Default 0.90. */
+    exact: number;
+}
+export interface CalibrationConfig {
+    /** EMA weight for new samples (0-1). Default 0.2. */
+    emaAlpha: number;
+    /** Samples needed to reach full confidence. Default 10. */
+    minSamplesForConfidence: number;
+}
+export declare const CONTEXT_DEFAULTS: {
+    readonly thresholds: ContextThresholds;
+    readonly calibration: CalibrationConfig;
+    readonly charsPerTokenFallback: 4;
+};

package/dist/plugins/cost-collector/collector.d.ts

@@ -0,0 +1,42 @@
+/** CostCollector — listens to onCompletion, computes cost from ModelCatalog
+ *  pricing or provider-reported totals, emits onCostEntry/onBudgetWarning/
+ *  onBudgetExceeded. */
+import type { CostEntry } from '../../bus/hook-map';
+import type { ModelCatalog } from '../model-catalog/catalog';
+import type { Budget, CostCollectorConfig, CostFilter, CostSummary } from './cost-collector-types';
+export declare class CostCollector {
+    private ledger;
+    private hooks;
+    private catalog;
+    private sessionId?;
+    private defaultTags;
+    private budgets;
+    private triggeredThresholds;
+    private _runningTotal;
+    private watchedAgents;
+    private unsub;
+    private unsubMedia;
+    constructor(config: CostCollectorConfig);
+    destroy(): void;
+    addBudget(budget: Budget): void;
+    removeBudget(id: string): void;
+    watchAgent(agent: {
+        stop(): void;
+    }): void;
+    setTag(key: string, value: string): void;
+    total(filter?: CostFilter): CostSummary;
+    byProvider(filter?: CostFilter): Record<string, CostSummary>;
+    byModel(filter?: CostFilter): Record<string, CostSummary>;
+    byTag(tagName: string, filter?: CostFilter): Record<string, CostSummary>;
+    entries(filter?: CostFilter): CostEntry[];
+    get entryCount(): number;
+    get runningTotal(): number;
+    get modelCatalog(): ModelCatalog;
+    export(): CostEntry[];
+    import(entries: CostEntry[]): void;
+    private handleMediaGenerated;
+    private handleCompletion;
+    private checkBudgets;
+    private filterEntries;
+    private groupBy;
+}

package/dist/plugins/cost-collector/cost-collector-internal.d.ts

@@ -0,0 +1,58 @@
+/** CostCollector internals — pure cost-math + filtering helpers, split out of
+ *  the class so each is independently testable. */
+import type { CostEntry } from '../../bus/hook-map';
+import type { ModelCatalog } from '../model-catalog/catalog';
+import type { CostFilter, CostSummary } from './cost-collector-types';
+/** Pull provider-reported cost evidence out of a raw response body. */
+export declare function extractProviderCost(provider: string, raw: unknown): Record<string, unknown>;
+/** The provider's own total cost (USD), when it reports one. */
+export declare function getProviderTotal(provider: string, evidence: Record<string, unknown>): number | null;
+/** Compute a CostEntry cost: provider total when reported, else catalog pricing
+ *  at the billed service tier (tier rates overlay the flat standard rates). */
+export declare function calculateCost(catalog: ModelCatalog, provider: string, model: string, tokens: CostEntry['tokens'], providerEvidence: Record<string, unknown>, tier?: string): CostEntry['cost'];
+/** Media units for unit-priced generation (image count / video seconds / TTS
+ *  chars), plus the resolution that selects a `perUnit` rate. */
+export interface MediaCostUnits {
+    type: 'image' | 'audio' | 'video';
+    count?: number;
+    durationSeconds?: number;
+    textChars?: number;
+    resolution?: string;
+}
+/** Everything `computeCost` needs to price one generation (chat OR media). */
+export interface CostComputeInput {
+    provider: string;
+    model: string;
+    /** Token usage — chat, and token-priced media (gpt-image, gemini-tts). */
+    tokens?: CostEntry['tokens'];
+    /** Unit-priced media facts. */
+    media?: MediaCostUnits;
+    providerEvidence?: Record<string, unknown>;
+    tier?: string;
+}
+/** Compute cost for a speech-to-text transcription billed by audio duration
+ *  (whisper, gpt-4o-transcribe).  Returns a zero-cost entry with `source:
+ *  'unknown'` when the catalog has no `perMinute` rate for this model, so the
+ *  cost pipeline can attach a note instead of emitting nothing.
+ *
+ *  `durationSeconds` is the audio duration measured or derived by the caller
+ *  (WAV header parse, or a caller-supplied hint). */
+export declare function calculateTranscriptionCost(catalog: ModelCatalog, provider: string, model: string, durationSeconds: number | undefined): {
+    cost: CostEntry['cost'];
+    note?: string;
+};
+/** The single cost engine for the whole SDK. Priority ladder:
+ *    1. provider-reported total (when the response carries one)
+ *    2. token cost — usage × per-MTok rates (chat, gpt-image, gemini-tts)
+ *    3. media unit cost — perUnit[resolution] → perImage/perSecond/perMChars
+ *    4. unknown (0)
+ *  Token pricing wins over unit pricing only when the model actually has
+ *  per-token rates, so unit-priced media with incidental usage still prices by
+ *  unit. */
+export declare function computeCost(catalog: ModelCatalog, input: CostComputeInput): CostEntry['cost'];
+/** Does an entry fall within a budget scope (all defined scope keys match)? */
+export declare function matchesScope(entry: CostEntry, scope: Record<string, string | undefined>): boolean;
+/** Predicate for CostFilter (provider/model/time/run/conversation/session). */
+export declare function applyFilter(e: CostEntry, filter: CostFilter): boolean;
+/** Sum a set of entries into a CostSummary. */
+export declare function summarize(entries: CostEntry[]): CostSummary;

package/dist/plugins/cost-collector/cost-collector-types.d.ts

@@ -0,0 +1,42 @@
+/** CostCollector public types: config, budgets, filters, summaries. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { ModelCatalog } from '../model-catalog/catalog';
+export interface CostCollectorConfig {
+    hooks: HookBus;
+    catalog: ModelCatalog;
+    sessionId?: string;
+    defaultTags?: Record<string, string>;
+}
+export interface Budget {
+    id: string;
+    limit: number;
+    scope: Record<string, string | undefined>;
+    thresholds: number[];
+    action: 'warn' | 'stop';
+}
+export interface CostFilter {
+    provider?: string;
+    model?: string;
+    runId?: string;
+    conversationId?: string;
+    sessionId?: string;
+    after?: number;
+    before?: number;
+    [key: string]: string | number | undefined;
+}
+export interface CostSummary {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoning: number;
+    total: number;
+    tokens: {
+        input: number;
+        output: number;
+        cached: number;
+        cacheWrite: number;
+        reasoning: number;
+    };
+    entries: number;
+}

package/dist/plugins/embeddings/types.d.ts

@@ -0,0 +1,23 @@
+/** Embeddings subsystem — text → vector. Mirrors the media adapter contract:
+ *  a thin per-provider adapter whose HTTP flows through the injected EngineFetch
+ *  (so it shares the NetworkEngine queue / retry / hooks). */
+import type { EngineFetch } from '../../network/types';
+export interface EmbedRequest {
+    model: string;
+    /** One string or a batch. */
+    input: string | string[];
+}
+export interface EmbedResult {
+    /** One vector per input, in order. */
+    embeddings: number[][];
+    model: string;
+    /** Vector length (0 when empty). */
+    dimensions: number;
+    usage?: {
+        inputTokens: number;
+    };
+}
+export interface EmbeddingProviderAdapter {
+    readonly name: string;
+    embed(req: EmbedRequest, fetch: EngineFetch): Promise<EmbedResult>;
+}

package/dist/plugins/files/attachment.d.ts

@@ -0,0 +1,79 @@
+/** FileAttachment — represents a file with upload state tracking per provider. */
+export type FileContent = {
+    type: 'buffer';
+    mimeType: string;
+    data: Uint8Array;
+} | {
+    type: 'path';
+    mimeType: string;
+    path: string;
+} | {
+    type: 'blob';
+    mimeType: string;
+    data: Blob;
+} | {
+    type: 'url';
+    url: string;
+    mimeType?: string;
+} | {
+    type: 'base64';
+    mimeType: string;
+    data: string;
+};
+export interface FileUploadState {
+    provider: string;
+    status: 'pending' | 'uploaded' | 'expired' | 'deleted' | 'error';
+    remoteId: string | null;
+    uploadedAt: number | null;
+    expiresAt: number | null;
+    error: string | null;
+}
+export interface FileAttachmentSnapshot {
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    uploads: Array<Omit<FileUploadState, 'provider'> & {
+        provider: string;
+    }>;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+}
+export declare class FileAttachment {
+    readonly id: string;
+    readonly filename: string;
+    readonly mimeType: string;
+    readonly sizeBytes: number;
+    readonly content: FileContent;
+    readonly createdAt: number;
+    readonly metadata: Record<string, unknown>;
+    readonly uploads: Map<string, FileUploadState>;
+    constructor(opts: {
+        id?: string;
+        filename: string;
+        mimeType: string;
+        sizeBytes: number;
+        content: FileContent;
+        metadata?: Record<string, unknown>;
+    });
+    /** Build an attachment from a browser File/Blob (e.g. an <input type="file">
+     *  or drag-drop). Works on Node/Bun too (Blob is a global there). filename /
+     *  mimeType / sizeBytes are taken from the Blob unless overridden. */
+    static fromBlob(blob: Blob, opts?: {
+        id?: string;
+        filename?: string;
+        mimeType?: string;
+        metadata?: Record<string, unknown>;
+    }): FileAttachment;
+    isAvailable(provider: string): boolean;
+    needsUpload(provider: string): boolean;
+    getRef(provider: string): string | null;
+    setUploaded(provider: string, remoteId: string, expiresAt: number | null): void;
+    setError(provider: string, error: string): void;
+    setDeleted(provider: string): void;
+    /** Load file content as base64 */
+    toBase64(): Promise<string>;
+    /** Load raw bytes */
+    toBuffer(): Promise<Uint8Array>;
+    export(): FileAttachmentSnapshot;
+}

package/dist/plugins/files/provider-adapter.d.ts

@@ -0,0 +1,37 @@
+/** FileProviderAdapter — provider-specific file operations.
+ *  Implemented by per-provider files.ts (anthropic/openai/google/xai).
+ *
+ *  All HTTP calls flow through an injected EngineFetch (NetworkEngine queue)
+ *  — adapters do not hold their own fetch fn. FilesRegistry threads
+ *  `engine.fetch` into adapter methods on every call, so rate-limit, retry,
+ *  and observability hooks apply uniformly. */
+import type { EngineFetch } from '../../network/types';
+import type { FileAttachment } from './attachment';
+export interface FileUploadResult {
+    remoteId: string;
+    expiresAt: number | null;
+}
+export interface RemoteFileInfo {
+    remoteId: string;
+    filename: string;
+    sizeBytes: number;
+    createdAt: number;
+    expiresAt?: number;
+}
+export interface FileProviderAdapter {
+    readonly name: string;
+    /** Upload a file. Returns remote id + optional expiry. */
+    upload(file: FileAttachment, fetch: EngineFetch): Promise<FileUploadResult>;
+    /** Delete a remote file. */
+    delete(remoteId: string, fetch: EngineFetch): Promise<void>;
+    /** Get info about a remote file. Returns null if not found. */
+    getInfo(remoteId: string, fetch: EngineFetch): Promise<RemoteFileInfo | null>;
+    /** List all remote files for the configured account. */
+    list(fetch: EngineFetch): Promise<RemoteFileInfo[]>;
+    /** Auto-expiry window in ms, or null for persistent. */
+    expiresAfter: number | null;
+    /** Max file size in bytes. */
+    maxFileSize: number;
+    /** Supported MIME types — null means accept all. */
+    supportedTypes: string[] | null;
+}

package/dist/plugins/files/registry.d.ts

@@ -0,0 +1,48 @@
+/** FilesRegistry — manages files across providers. Subscribes to
+ *  onMessageResolve and resolves file refs into provider-friendly content
+ *  parts (provider_ref / inline base64 / url). */
+import type { HookBus } from '../../bus/hook-bus';
+import type { EngineFetch } from '../../network/types';
+import type { ModelCatalog } from '../model-catalog/catalog';
+import { FileAttachment, type FileContent } from './attachment';
+import type { FileProviderAdapter, RemoteFileInfo } from './provider-adapter';
+import { type FileStrategy } from './strategy';
+export interface FilesRegistryConfig {
+    hooks: HookBus;
+    catalog?: ModelCatalog;
+    strategy?: FileStrategy;
+    /** Engine fetch — every adapter HTTP call dispatches through this so it
+     *  inherits NetworkEngine queue semantics (rate limits, retry, hooks). */
+    fetch: EngineFetch;
+}
+export declare class FilesRegistry {
+    private files;
+    private providers;
+    private hooks;
+    private catalog;
+    private strategy;
+    private fetch;
+    private unsub;
+    constructor(config: FilesRegistryConfig);
+    destroy(): void;
+    registerProvider(name: string, adapter: FileProviderAdapter): void;
+    add(opts: {
+        filename: string;
+        mimeType: string;
+        content: FileContent;
+        sizeBytes?: number;
+        metadata?: Record<string, unknown>;
+    }): FileAttachment;
+    get(id: string): FileAttachment | null;
+    list(): FileAttachment[];
+    remove(id: string): void;
+    upload(fileId: string, provider: string): Promise<string>;
+    deleteRemote(fileId: string, provider: string): Promise<void>;
+    listRemote(provider: string): Promise<RemoteFileInfo[]>;
+    private resolveMessages;
+    private hasFileSource;
+    private resolveFilePart;
+    private executeDecision;
+    private makeInlinePart;
+    private estimateSize;
+}

package/dist/plugins/files/strategy.d.ts

@@ -0,0 +1,38 @@
+/** FileStrategy — pluggable decision maker for how to attach files. */
+import type { ModelInfo } from '../model-catalog/catalog';
+import type { FileAttachment } from './attachment';
+export interface FileStrategyContext {
+    file: FileAttachment;
+    provider: string;
+    model: string;
+    isUploaded: boolean;
+    isExpired: boolean;
+    providerMaxSize: number;
+    providerSupportsType: boolean;
+    modelInfo: ModelInfo | null;
+}
+export type FileDecision = {
+    action: 'upload';
+    reason: string;
+} | {
+    action: 'reupload';
+    reason: string;
+} | {
+    action: 'inline';
+    reason: string;
+} | {
+    action: 'url';
+    reason: string;
+} | {
+    action: 'skip';
+    reason: string;
+};
+export interface FileStrategy {
+    decide(ctx: FileStrategyContext): FileDecision;
+}
+/** Default: upload large files, inline small ones, use URL when available. */
+export declare class DefaultFileStrategy implements FileStrategy {
+    private inlineThreshold;
+    constructor(inlineThreshold?: number);
+    decide(ctx: FileStrategyContext): FileDecision;
+}

package/dist/plugins/internal-tools/backends/local.d.ts

@@ -0,0 +1,12 @@
+/** LocalBackend — in-repo tool library. Synchronous registration, async access. */
+import type { ToolBackend, InternalTool } from '../types';
+export declare class LocalBackend implements ToolBackend {
+    readonly name = "local";
+    private tools;
+    register(tool: InternalTool): this;
+    replace(tool: InternalTool): this;
+    unregister(id: string): boolean;
+    get size(): number;
+    list(): Promise<InternalTool[]>;
+    get(id: string): Promise<InternalTool | null>;
+}

package/dist/plugins/internal-tools/builtin/builtin.d.ts

@@ -0,0 +1,21 @@
+/** Core built-in tool library. Five tools every LLM app eventually needs:
+ *
+ *    summarize  — universal compaction primitive (used by ContextGuard, RAG, output)
+ *    classify   — routing / intent / moderation
+ *    structure  — extract typed structured data from prose
+ *    score      — self-evaluation, judge-LLM patterns, ranking
+ *    clarify    — interactive flows (mate to ask events)
+ *
+ *  Application-specific or domain-heavy tools (fact-extract, format-question,
+ *  format-response, prompt-improve, enhance, variation, title) ship separately
+ *  under `extensions/builtin-tools/` and must be registered manually if needed. */
+import type { LocalBackend } from '../backends/local';
+export { summarizeTool, type SummarizeInput, type SummarizeOutput } from './summarize';
+export { classifyTool, type ClassifyInput, type ClassifyOutput } from './classify';
+export { scoreTool, type ScoreInput, type ScoreOutput } from './score';
+export { structureTool, type StructureInput, type StructureOutput } from './structure';
+export { clarifyTool, type ClarifyInput, type ClarifyOutput } from './clarify';
+/** Core built-in tools shipped with the SDK. */
+export declare const BUILTIN_TOOLS: readonly [import("../types").InternalTool, import("../types").InternalTool, import("../types").InternalTool, import("../types").InternalTool, import("../types").InternalTool];
+/** Register all SDK-core built-in tools on a LocalBackend. */
+export declare function registerBuiltinTools(backend: LocalBackend): void;

package/dist/plugins/internal-tools/builtin/clarify.d.ts

@@ -0,0 +1,12 @@
+/** orxa:clarify@1.0.0 — validate prompt against requirements, produce questions for gaps. */
+import type { InternalTool } from '../types';
+export interface ClarifyInput {
+    prompt: string;
+    requirements: string[];
+}
+export interface ClarifyOutput {
+    satisfied: boolean;
+    missingRequirements: string[];
+    clarificationQuestions: string[];
+}
+export declare const clarifyTool: InternalTool;

package/dist/plugins/internal-tools/builtin/classify.d.ts

@@ -0,0 +1,12 @@
+/** orxa:classify@1.0.0 — select best match from suggestions with confidence. */
+import type { InternalTool } from '../types';
+export interface ClassifyInput {
+    request: string;
+    suggestions: string[];
+}
+export interface ClassifyOutput {
+    selectedIndex: number;
+    confidence: number;
+    reasoning: string;
+}
+export declare const classifyTool: InternalTool;

package/dist/plugins/internal-tools/builtin/score.d.ts

@@ -0,0 +1,13 @@
+/** orxa:score@1.0.0 — score how well an answer fulfills a task, per criteria. */
+import type { InternalTool } from '../types';
+export interface ScoreInput {
+    task: string;
+    answer: string;
+    criteria?: string[];
+}
+export interface ScoreOutput {
+    score: number;
+    breakdown: Record<string, number>;
+    feedback: string;
+}
+export declare const scoreTool: InternalTool;

package/dist/plugins/internal-tools/builtin/structure.d.ts

@@ -0,0 +1,11 @@
+/** orxa:structure@1.0.0 — extract structured JSON from unstructured text per schema. */
+import type { InternalTool } from '../types';
+import type { JsonSchema } from '../../../llm/types/tools';
+export interface StructureInput {
+    request: string;
+    schema: JsonSchema;
+}
+export interface StructureOutput {
+    [key: string]: unknown;
+}
+export declare const structureTool: InternalTool;

package/dist/plugins/internal-tools/builtin/summarize.d.ts

@@ -0,0 +1,19 @@
+/** orxa:summarize@1.0.0 — compact long content while preserving key facts.
+ *  Uses provider-specific variants because strict fact-preservation helps
+ *  Haiku and Flash-Lite (they over-paraphrase by default) but hurts Nano
+ *  (which becomes too literal and fails to compress). */
+import type { InternalTool } from '../types';
+export interface SummarizeInput {
+    content: string;
+    /** Target max characters for the summary text. Converted to max_tokens via catalog ratio. */
+    maxLength?: number;
+    /** Target max tokens for the LLM response. Takes precedence over maxLength. */
+    maxTokens?: number;
+    /** Optional focus for the summary (narrows the content angle). */
+    focus?: string;
+}
+export interface SummarizeOutput {
+    summary: string;
+    keyPoints: string[];
+}
+export declare const summarizeTool: InternalTool;

package/dist/plugins/internal-tools/id.d.ts

@@ -0,0 +1,12 @@
+/** Tool ID parsing and version matching helpers.
+ *  Format: "namespace:name@semver" (e.g. "orxa:summarize@1.0.0"). */
+export interface ParsedToolId {
+    namespace: string;
+    name: string;
+    version: string;
+}
+export declare function parseToolId(id: string): ParsedToolId;
+export declare function tryParseToolId(id: string): ParsedToolId | null;
+export declare function formatToolId(namespace: string, name: string, version: string): string;
+export declare function matchesVersion(requested: string, actual: string): boolean;
+export declare function idWithoutVersion(id: string): string;

package/dist/plugins/internal-tools/registry.d.ts

@@ -0,0 +1,24 @@
+/** ToolRegistry — unified access across multiple backends with caching, search, filtering. */
+import type { InternalTool, ToolBackend, ToolFilter, SearchOptions } from './types';
+import type { ModelCatalog } from '../model-catalog/catalog';
+export declare class ToolRegistry {
+    private backends;
+    private cache;
+    /** Add a backend. First-added wins on ID conflicts. Returns this for chaining. */
+    addBackend(backend: ToolBackend): this;
+    removeBackend(name: string): boolean;
+    invalidate(): void;
+    get(id: string): Promise<InternalTool | null>;
+    list(): Promise<InternalTool[]>;
+    find(filter: ToolFilter, catalog?: ModelCatalog): Promise<InternalTool[]>;
+    search(query: string, opts?: SearchOptions): Promise<InternalTool[]>;
+    /** Models with acceptable compatibility score for this tool, derived from
+     *  catalog's `toolCompat` field on each ModelInfo. */
+    modelsFor(toolId: string, opts?: {
+        minScore?: number;
+        catalog?: ModelCatalog;
+    }): string[];
+    private ensureCache;
+    private matchesFilter;
+    private scoreMatch;
+}

package/dist/plugins/internal-tools/runner/define.d.ts

@@ -0,0 +1,7 @@
+/** defineLLMTool — convert a declarative LLMToolDefinition into an InternalTool
+ *  with execute() that renders templates, calls LLM, parses output. */
+import type { InternalTool } from '../types';
+import type { LLMToolDefinition } from './types';
+export declare const LLM_DEF_KEY: unique symbol;
+export declare function getLLMToolDefinition(tool: InternalTool): LLMToolDefinition | null;
+export declare function defineLLMTool(def: LLMToolDefinition): InternalTool;

package/dist/plugins/internal-tools/runner/json-enforcement.d.ts

@@ -0,0 +1,3 @@
+/** JSON output enforcement — system prompt that forces strict JSON-only output. */
+export declare const JSON_API_SYSTEM_PROMPT = "You are a JSON API endpoint. Your output is parsed directly by code, not read by humans.\n\nABSOLUTE REQUIREMENTS:\n- Output ONLY valid JSON. Nothing else. No exceptions.\n- Your entire response must be parseable by JSON.parse()\n- First character of response must be { and last must be }\n\nFORBIDDEN (will cause parsing errors):\n- NO markdown: ```json or ``` blocks\n- NO prose: \"Here is the JSON:\" or \"Sure, here's...\"\n- NO explanations before or after the JSON\n- NO comments inside JSON\n- NO trailing text\n\nCORRECT OUTPUT FORMAT:\n{\"field\": \"value\", \"number\": 42}\n\nWRONG OUTPUT FORMAT (DO NOT DO THIS):\n```json\n{\"field\": \"value\"}\n```\n\nJSON SYNTAX RULES:\n- Double quotes for all strings and keys\n- No trailing commas\n- Numbers as numeric values (0.85 not \"0.85\")\n- Use null for unknown values, [] for empty arrays\n\nRESPOND WITH RAW JSON ONLY. START WITH { END WITH }";
+export declare function composeJsonSystemPrompt(toolSystemPrompt: string): string;