agim-cli 1.2.45 → 1.2.49

package/dist/core/llm/provider-base.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Chat message role. We intentionally support only the three canonical
+ * roles needed by introspection callers; tool / function roles arrive in
+ * Stage 2 when we add the real agent loop.
+ */
+export type LlmMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * Single chat message as sent to / received from the LLM provider.
+ *
+ * Roles + valid combinations of fields:
+ *
+ *   { role: 'system'    | 'user', content }
+ *     plain text turn.
+ *
+ *   { role: 'assistant', content, toolCalls? }
+ *     model output. content may be the empty string when the model
+ *     emitted only tool calls. toolCalls echoes ChatResult.toolCalls
+ *     verbatim from a prior turn — required for history so the next
+ *     tool-result message can reference call IDs.
+ *
+ *   { role: 'tool',      content, toolCallId }
+ *     reply from agent code to a previous assistant tool call. content
+ *     is the stringified tool result. toolCallId MUST match an id from
+ *     the assistant turn's toolCalls (else providers reject the batch).
+ */
+export interface LlmMessage {
+    role: LlmMessageRole;
+    content: string;
+    /** Required when role='tool'; ignored otherwise. */
+    toolCallId?: string;
+    /** Required to round-trip assistant turns that contained tool calls;
+     *  ignored on user/system/tool messages. Empty/undefined for plain
+     *  assistant text turns. */
+    toolCalls?: ToolCallRequest[];
+    /** DeepSeek / thinking-mode providers echo `reasoning_content` on
+     *  assistant turns; MUST round-trip on subsequent API calls. */
+    reasoningContent?: string;
+    /** Optional multimodal attachments (typically images). Providers with
+     *  `supportsVision() === true` encode these as image_url / image
+     *  content blocks; others ignore the field and only see `content`. The
+     *  text path is preserved verbatim so non-vision providers still know
+     *  an attachment was referenced. */
+    media?: Array<{
+        /** Absolute path to the file on disk. agim only attaches files
+         *  inside the per-user media dir (`~/.agim/media/...`); providers
+         *  read + inline-base64 the bytes. */
+        path: string;
+        /** Optional MIME hint (e.g. 'image/jpeg'). Provider may sniff from
+         *  the extension if absent. */
+        mime?: string;
+    }>;
+}
+/**
+ * Single tool exposed to the LLM. Equivalent to OpenAI's
+ * {type:'function', function:{...}} wrapper and Anthropic's {name,
+ * description, input_schema} entry; providers do the dialect adapt.
+ *
+ * `parameters` MUST be a JSON Schema object (typically
+ * `{type:'object', properties:{...}, required:[...]}`). We don't
+ * validate the schema here — providers usually pass it through verbatim
+ * and the LLM itself enforces the contract.
+ */
+export interface ToolDef {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * One tool call requested by the model. The Stage-2 agent loop iterates
+ * over `ChatResult.toolCalls`, executes each one, then appends matching
+ * `{role:'tool'}` messages and re-invokes the provider. The `id` is
+ * provider-assigned (OpenAI: 'call_...', Anthropic: 'toolu_...') and
+ * MUST round-trip on the tool-result message — providers reject batches
+ * where ids don't match.
+ *
+ * `arguments` is the already-JSON-parsed input. OpenAI returns a JSON
+ * string in `function.arguments`; we parse it client-side so every
+ * caller sees a normal object. When the LLM emits malformed JSON the
+ * provider sets `argumentsRaw` and leaves `arguments` as `{}`; tool
+ * implementations should validate the shape themselves.
+ *
+ * `raw` is reserved for provider-specific metadata that must round-trip
+ * across turns (e.g. Anthropic cache_control hints, future Gemini
+ * thought signatures). The agent loop preserves it verbatim.
+ */
+export interface ToolCallRequest {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    /** When present, JSON parsing of the arguments failed; tools should
+     *  validate or refuse. Kept as a separate field so the common case
+     *  (`arguments` is the parsed object) stays cheap. */
+    argumentsRaw?: string;
+    raw?: unknown;
+}
+/** Tool-choice hint forwarded to providers. Most providers default to
+ *  'auto'; a few callers want to force a specific tool ('required' +
+ *  name) or block all tool use ('none') for one call. Provider support
+ *  varies — unknown values fall back to 'auto'. */
+export type ToolChoice = 'auto' | 'required' | 'none' | {
+    type: 'tool';
+    name: string;
+};
+/** Token + cost usage surfaced by the provider, when available. */
+export interface LlmUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    /** Cost in USD if the provider reports it; otherwise undefined. We
+     *  deliberately don't try to compute cost from a hardcoded price table
+     *  — Stage 1 just passes through whatever the provider says. */
+    costUsd?: number;
+}
+/** Reason the model stopped generating. */
+export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error' | 'unknown';
+/** Per-call options. All fields are optional with sensible defaults. */
+export interface ChatOptions {
+    /** Override the provider's default model for this call. */
+    model?: string;
+    /** Sampling temperature. Default = provider default (usually 0.7). */
+    temperature?: number;
+    /** Max tokens in the completion. Default = provider default. */
+    maxTokens?: number;
+    /** Optional system prompt to prepend (a convenience over building a
+     *  system message yourself; ignored if messages already starts with
+     *  a system message). */
+    system?: string;
+    /** Abort the request when this signal fires. Required by callers that
+     *  manage their own deadlines (memory-consolidate has a 60s cap). */
+    signal?: AbortSignal;
+    /** Internal hard deadline in ms. If both signal and timeoutMs are
+     *  given, the earlier of the two wins. */
+    timeoutMs?: number;
+    /** Called once per provider response (or once per chunk for stream)
+     *  with whatever usage info the provider returned. Best-effort —
+     *  callers should not block on this. */
+    onUsage?: (usage: LlmUsage) => void;
+    /** Extra provider-specific knobs. Each provider documents what it
+     *  reads from this bag; unknown keys are ignored. Keeps the public
+     *  ChatOptions type stable while letting power users tune
+     *  OpenRouter-style headers, DeepSeek-specific thinking mode, etc. */
+    providerOptions?: Record<string, unknown>;
+    /** Stage 2 — tool definitions advertised to the model. When unset
+     *  (or empty) the model has no tool access for this call; this is
+     *  the introspection-caller default and matches Stage-1 behaviour. */
+    tools?: ToolDef[];
+    /** Stage 2 — tool-use hint. 'auto' (default) lets the model decide;
+     *  'required' forces some tool call; 'none' suppresses tools even
+     *  when `tools` is non-empty; `{type:'tool', name}` forces a
+     *  specific tool. Provider support varies; unknown values fall
+     *  back to 'auto'. */
+    toolChoice?: ToolChoice;
+}
+/** Result of a chat call. */
+export interface ChatResult {
+    /** Plain text body. May be the empty string on `finishReason: 'error'`
+     *  or when the model emitted only tool_calls. */
+    text: string;
+    /** Stage 2 — tool calls the model wants the agent loop to execute.
+     *  When present, finishReason is typically 'tool_use'. Stage-1
+     *  introspection callers can simply ignore this field — non-empty
+     *  toolCalls in a chat() call (no agent loop) just means the model
+     *  spent budget on a tool the caller never advertised, which is rare
+     *  but harmless. */
+    toolCalls?: ToolCallRequest[];
+    /** Provider-specific thinking trace (e.g. DeepSeek reasoning_content). */
+    reasoningContent?: string;
+    /** Usage metrics, when the provider reports them. */
+    usage: LlmUsage;
+    /** Why the model stopped. */
+    finishReason: FinishReason;
+    /** Model id the provider actually used (handy for diagnostics when
+     *  the caller relies on the provider's default rather than an explicit
+     *  `opts.model`). */
+    modelUsed: string;
+}
+/** Lightweight stream chunk. Stage 1 streams only text deltas. */
+export interface ChatStreamChunk {
+    textDelta: string;
+    /** Only populated on the final chunk. Earlier chunks have null. */
+    finishReason?: FinishReason | null;
+    /** Only populated on the final chunk, when the provider reports it. */
+    usage?: LlmUsage;
+}
+/**
+ * Common configuration every provider needs. Concrete providers may add
+ * their own fields (e.g. OpenAICompatProvider adds `baseUrl`).
+ */
+export interface ProviderConfigBase {
+    /** Unique identifier within an agim instance — e.g. "deepseek-cheap"
+     *  or "gpt-4-1-judge". This is what `llmRoles` references. */
+    name: string;
+    /** Default model id the provider sends when ChatOptions.model is unset. */
+    model: string;
+    /** Provider type label, surfaced in logs and the web UI. */
+    providerType: string;
+    /** API key — provider implementations look this up via secrets.ts; the
+     *  base class only uses it for logging length / fingerprinting. */
+    apiKey?: string;
+    /** Default temperature; falls back to 0.3 for cheap introspection
+     *  callers (we want deterministic JSON, not creativity). */
+    defaultTemperature?: number;
+    /** Default max output tokens. Tight default so a misconfigured prompt
+     *  can't burn 16k tokens worth of "Sure! Let me explain…". */
+    defaultMaxTokens?: number;
+}
+/**
+ * Base class for every LLM provider. The transport-specific work happens
+ * in `_callApi` / `_callApiStream` which subclasses implement. The base
+ * adds:
+ *   - timeout / AbortSignal merging
+ *   - default system prompt injection
+ *   - onUsage plumbing (callers shouldn't have to defend against missing
+ *     usage info)
+ *   - finishReason normalization
+ */
+export declare abstract class LlmProvider {
+    readonly name: string;
+    readonly model: string;
+    readonly providerType: string;
+    protected readonly apiKey: string | undefined;
+    protected readonly defaultTemperature: number;
+    protected readonly defaultMaxTokens: number;
+    constructor(cfg: ProviderConfigBase);
+    /** True when the provider has the credentials it needs. False suggests
+     *  the operator forgot to set the secret; the registry filters these
+     *  out at load time so `getProvider()` callers don't have to check. */
+    isConfigured(): boolean;
+    /** True when this provider can interpret LlmMessage.media (typically
+     *  image attachments). Default false — only the openai-compat
+     *  provider currently overrides this (operators opt-in via the
+     *  provider's `vision: true` config or a model-name heuristic).
+     *  Anthropic / others fall back to text-only. */
+    supportsVision(): boolean;
+    /**
+     * Buffered chat call: send the full message list, await the entire
+     * response. Used by all Stage-1 introspection callers because the
+     * downstream parsers want a complete JSON string anyway.
+     */
+    chat(messages: LlmMessage[], opts?: ChatOptions): Promise<ChatResult>;
+    /**
+     * Streaming chat call: async-iterable of text deltas. Stage-1 callers
+     * don't use this yet, but it's in the base API so Stage 2's agent loop
+     * (and the future "stream thinking to web UI" feature) can build on it
+     * without API churn.
+     */
+    chatStream(messages: LlmMessage[], opts?: ChatOptions): AsyncIterable<ChatStreamChunk>;
+    /** Concrete providers implement this for buffered responses. */
+    protected abstract _callApi(messages: LlmMessage[], opts: NormalizedOptions, signal: AbortSignal): Promise<ChatResult>;
+    /** Concrete providers implement this for streamed responses. Default
+     *  implementation falls back to buffered + single-chunk yield, so
+     *  providers that don't support streaming still work (the caller sees
+     *  one big chunk on completion). Override for real streaming. */
+    protected _callApiStream(messages: LlmMessage[], opts: NormalizedOptions, signal: AbortSignal): AsyncIterable<ChatStreamChunk>;
+    /**
+     * Prepend `opts.system` as a system message iff the caller didn't
+     * already supply one. Saves callers from threading the same conditional
+     * everywhere; documented in ChatOptions so behaviour is unsurprising.
+     */
+    private _prepareMessages;
+    private _mergeOptions;
+    /**
+     * Merge the caller's AbortSignal with the optional timeout into a
+     * single composite signal. We deliberately don't use AbortSignal.any
+     * because Node 18 doesn't have it; the manual wiring is small enough
+     * to keep us portable. Returns a cleanup fn the caller must invoke to
+     * clear the timeout (prevents the test runner from keeping the event
+     * loop alive past test completion).
+     */
+    private _buildSignal;
+}
+/** Internal normalized form of ChatOptions — concrete providers receive
+ *  this rather than the raw ChatOptions so they don't have to repeat the
+ *  defaulting logic. */
+export interface NormalizedOptions {
+    model: string;
+    temperature: number;
+    maxTokens: number;
+    timeoutMs?: number;
+    providerOptions: Record<string, unknown>;
+    /** Stage 2 — tool definitions to advertise. Empty array → undefined
+     *  so providers can rely on `opts.tools ? ... : ...` shorthand. */
+    tools?: ToolDef[];
+    toolChoice?: ToolChoice;
+}
+/**
+ * Helper for providers that want to format an error consistently. Wrapping
+ * the underlying fetch / SDK error in LlmProviderError makes it easy for
+ * callers (and the registry's "is the provider healthy?" probe) to tell
+ * a transport failure apart from a logic bug.
+ */
+export declare class LlmProviderError extends Error {
+    readonly providerName: string;
+    readonly httpStatus?: number;
+    readonly transient: boolean;
+    constructor(providerName: string, message: string, opts?: {
+        httpStatus?: number;
+        transient?: boolean;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=provider-base.d.ts.map

package/dist/core/llm/provider-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-base.d.ts","sourceRoot":"","sources":["../../../src/core/llm/provider-base.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/provider-base.js

@@ -0,0 +1,222 @@
+// LLM provider abstraction (Stage 1 — D+ plan, 2026-05-23).
+//
+// The goal here is intentionally small: give agim a way to do
+// "single-shot LLM call → text" *without* spawning a CLI agent (Claude
+// Code / Codex / OpenCode). agim stays a CLI bridge in spirit — these
+// providers are only used by internal introspection callers
+// (memory-distill, memory-consolidate, intent-llm, future heartbeat /
+// notification evaluator).
+//
+// Stage 1 explicitly does NOT implement:
+//   - tool calling / agent loop (that's Stage 2)
+//   - MCP client (Stage 2)
+//   - file / shell tools (delegated to MCP in Stage 2)
+//   - Anthropic native messages API (Stage 2)
+//
+// What it DOES support:
+//   - `chat(messages, opts) → ChatResult` for buffered text responses
+//   - `chatStream(...)` async iterable for incremental delivery
+//   - timeouts via AbortSignal
+//   - usage / cost telemetry surfaced through onUsage callback
+//
+// Concrete providers (Stage 1: OpenAICompatProvider only) subclass and
+// implement `_callApi` / `_callApiStream`. The base wraps with timeout +
+// telemetry plumbing so providers stay focused on transport details.
+/**
+ * Base class for every LLM provider. The transport-specific work happens
+ * in `_callApi` / `_callApiStream` which subclasses implement. The base
+ * adds:
+ *   - timeout / AbortSignal merging
+ *   - default system prompt injection
+ *   - onUsage plumbing (callers shouldn't have to defend against missing
+ *     usage info)
+ *   - finishReason normalization
+ */
+export class LlmProvider {
+    name;
+    model;
+    providerType;
+    apiKey;
+    defaultTemperature;
+    defaultMaxTokens;
+    constructor(cfg) {
+        if (!cfg.name)
+            throw new Error('LlmProvider: name is required');
+        if (!cfg.model)
+            throw new Error('LlmProvider: model is required');
+        if (!cfg.providerType)
+            throw new Error('LlmProvider: providerType is required');
+        this.name = cfg.name;
+        this.model = cfg.model;
+        this.providerType = cfg.providerType;
+        this.apiKey = cfg.apiKey;
+        this.defaultTemperature = cfg.defaultTemperature ?? 0.3;
+        this.defaultMaxTokens = cfg.defaultMaxTokens ?? 1024;
+    }
+    /** True when the provider has the credentials it needs. False suggests
+     *  the operator forgot to set the secret; the registry filters these
+     *  out at load time so `getProvider()` callers don't have to check. */
+    isConfigured() {
+        return Boolean(this.apiKey);
+    }
+    /** True when this provider can interpret LlmMessage.media (typically
+     *  image attachments). Default false — only the openai-compat
+     *  provider currently overrides this (operators opt-in via the
+     *  provider's `vision: true` config or a model-name heuristic).
+     *  Anthropic / others fall back to text-only. */
+    supportsVision() {
+        return false;
+    }
+    /**
+     * Buffered chat call: send the full message list, await the entire
+     * response. Used by all Stage-1 introspection callers because the
+     * downstream parsers want a complete JSON string anyway.
+     */
+    async chat(messages, opts = {}) {
+        const prepared = this._prepareMessages(messages, opts);
+        const merged = this._mergeOptions(opts);
+        const signal = this._buildSignal(opts.signal, merged.timeoutMs);
+        const result = await this._callApi(prepared, merged, signal.signal);
+        signal.cleanup();
+        if (opts.onUsage) {
+            try {
+                opts.onUsage(result.usage);
+            }
+            catch { /* swallow — telemetry is best-effort */ }
+        }
+        return result;
+    }
+    /**
+     * Streaming chat call: async-iterable of text deltas. Stage-1 callers
+     * don't use this yet, but it's in the base API so Stage 2's agent loop
+     * (and the future "stream thinking to web UI" feature) can build on it
+     * without API churn.
+     */
+    async *chatStream(messages, opts = {}) {
+        const prepared = this._prepareMessages(messages, opts);
+        const merged = this._mergeOptions(opts);
+        const signal = this._buildSignal(opts.signal, merged.timeoutMs);
+        try {
+            let lastUsage;
+            for await (const chunk of this._callApiStream(prepared, merged, signal.signal)) {
+                if (chunk.usage)
+                    lastUsage = chunk.usage;
+                yield chunk;
+            }
+            if (lastUsage && opts.onUsage) {
+                try {
+                    opts.onUsage(lastUsage);
+                }
+                catch { /* swallow */ }
+            }
+        }
+        finally {
+            signal.cleanup();
+        }
+    }
+    /** Concrete providers implement this for streamed responses. Default
+     *  implementation falls back to buffered + single-chunk yield, so
+     *  providers that don't support streaming still work (the caller sees
+     *  one big chunk on completion). Override for real streaming. */
+    async *_callApiStream(messages, opts, signal) {
+        const result = await this._callApi(messages, opts, signal);
+        yield {
+            textDelta: result.text,
+            finishReason: result.finishReason,
+            usage: result.usage,
+        };
+    }
+    /**
+     * Prepend `opts.system` as a system message iff the caller didn't
+     * already supply one. Saves callers from threading the same conditional
+     * everywhere; documented in ChatOptions so behaviour is unsurprising.
+     */
+    _prepareMessages(messages, opts) {
+        if (!opts.system)
+            return messages;
+        if (messages.length > 0 && messages[0].role === 'system')
+            return messages;
+        return [{ role: 'system', content: opts.system }, ...messages];
+    }
+    _mergeOptions(opts) {
+        return {
+            model: opts.model || this.model,
+            temperature: opts.temperature ?? this.defaultTemperature,
+            maxTokens: opts.maxTokens ?? this.defaultMaxTokens,
+            timeoutMs: opts.timeoutMs,
+            providerOptions: opts.providerOptions ?? {},
+            tools: opts.tools && opts.tools.length > 0 ? opts.tools : undefined,
+            toolChoice: opts.toolChoice,
+        };
+    }
+    /**
+     * Merge the caller's AbortSignal with the optional timeout into a
+     * single composite signal. We deliberately don't use AbortSignal.any
+     * because Node 18 doesn't have it; the manual wiring is small enough
+     * to keep us portable. Returns a cleanup fn the caller must invoke to
+     * clear the timeout (prevents the test runner from keeping the event
+     * loop alive past test completion).
+     */
+    _buildSignal(userSignal, timeoutMs) {
+        if (!userSignal && !timeoutMs) {
+            // Fast path: no constraints, return a never-aborted controller so
+            // _callApi has a single signal contract to work with.
+            const ctrl = new AbortController();
+            return { signal: ctrl.signal, cleanup: () => { } };
+        }
+        const ctrl = new AbortController();
+        let timer = null;
+        const onUserAbort = () => {
+            ctrl.abort(userSignal?.reason ?? new Error('aborted'));
+        };
+        if (userSignal) {
+            if (userSignal.aborted)
+                onUserAbort();
+            else
+                userSignal.addEventListener('abort', onUserAbort, { once: true });
+        }
+        if (timeoutMs && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+            timer = setTimeout(() => ctrl.abort(new Error(`LLM call timed out after ${timeoutMs}ms`)), timeoutMs);
+            if (typeof timer === 'object' && timer && 'unref' in timer) {
+                timer.unref();
+            }
+        }
+        return {
+            signal: ctrl.signal,
+            cleanup: () => {
+                if (timer)
+                    clearTimeout(timer);
+                if (userSignal)
+                    userSignal.removeEventListener('abort', onUserAbort);
+            },
+        };
+    }
+}
+/**
+ * Helper for providers that want to format an error consistently. Wrapping
+ * the underlying fetch / SDK error in LlmProviderError makes it easy for
+ * callers (and the registry's "is the provider healthy?" probe) to tell
+ * a transport failure apart from a logic bug.
+ */
+export class LlmProviderError extends Error {
+    providerName;
+    httpStatus;
+    transient;
+    constructor(providerName, message, opts = {}) {
+        super(message);
+        this.name = 'LlmProviderError';
+        this.providerName = providerName;
+        this.httpStatus = opts.httpStatus;
+        // 429 / 408 / 503 / 504 are conventional "retry-me" codes. Callers
+        // can use this flag to decide whether to back off or fall back to a
+        // CLI agent right away.
+        this.transient = opts.transient ?? (opts.httpStatus === 408 ||
+            opts.httpStatus === 429 ||
+            opts.httpStatus === 503 ||
+            opts.httpStatus === 504);
+        if (opts.cause !== undefined) {
+            this.cause = opts.cause;
+        }
+    }
+}
+//# sourceMappingURL=provider-base.js.map

package/dist/core/llm/provider-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-base.js","sourceRoot":"","sources":["../../../src/core/llm/provider-base.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/registry.d.ts

@@ -0,0 +1,44 @@
+import type { ValidatedConfig } from '../config-schema.js';
+import type { LlmProvider } from './provider-base.js';
+/** Role names recognised by Stage 1 callers. Strings rather than enum so
+ *  forward-compat roles (added in later stages) compile against an older
+ *  agim without type errors. */
+export type LlmRole = 'cheap' | 'evaluator' | 'native-chat' | string;
+/**
+ * Build the registry from a validated config. Idempotent — repeated
+ * calls fully replace the previous state. Logs (info / warn) the load
+ * outcome so operators see what landed at startup.
+ */
+export declare function loadFromConfig(cfg: ValidatedConfig | {
+    llmBackends?: unknown;
+    llmRoles?: unknown;
+}): void;
+/**
+ * Get the provider configured for `role`, or null when no usable
+ * backend is wired. Callers should NEVER throw on null — that's how the
+ * registry tells them "fall back to your CLI path".
+ */
+export declare function getProvider(role: LlmRole): LlmProvider | null;
+/** Look up a provider directly by backend name (mostly for the web
+ *  "Test connection" button and unit tests). */
+export declare function getProviderByName(name: string): LlmProvider | null;
+/** List all configured backends — handy for the web UI roster. */
+export declare function listProviders(): {
+    name: string;
+    providerType: string;
+    model: string;
+}[];
+/** Test/diagnostic: clear the registry. Used by bun tests so module
+ *  state doesn't leak across cases. */
+export declare function _resetRegistry(): void;
+/** Diagnostic snapshot for the cost dashboard's "LLM backends" tile. */
+export declare function describeRegistry(): {
+    backends: {
+        name: string;
+        providerType: string;
+        model: string;
+    }[];
+    roles: Record<string, string>;
+    unconfigured: string[];
+};
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/llm/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/llm/registry.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAG1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAKrD;;gCAEgC;AAChC,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAA;AAoBpE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAqDzG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAI7D;AAED;gDACgD;AAChD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAElE;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAMvF;AAED;uCACuC;AACvC,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,IAAI;IAClC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB,CAMA"}