@uptimizr/agent-core 0.1.0

package/dist/providers/openai.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure translation between the agent-core conversation shape and the OpenAI
+ * Chat Completions wire format. Shared by the bring-your-own hosted adapter
+ * (OpenAI-compatible mode) and the WebLLM adapter — the MLC runtime exposes an
+ * OpenAI-compatible `chat.completions.create`. No I/O, no dependencies: just
+ * shape mapping, so both adapters agree on tool-calling semantics.
+ */
+import type { AgentMessage, AgentToolSchema, ProviderResponse } from "../provider.js";
+/** OpenAI chat message (request side). */
+export interface OpenAiMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_calls?: OpenAiToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+/** OpenAI tool-call (both request echo and response). */
+export interface OpenAiToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** OpenAI tool advertisement (function schema). */
+export interface OpenAiTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** The subset of an OpenAI chat-completion response this module reads. */
+export interface OpenAiCompletion {
+    choices?: Array<{
+        message?: {
+            content?: string | null;
+            tool_calls?: OpenAiToolCall[] | null;
+        };
+    }>;
+}
+/** Map the agent conversation to OpenAI request messages. */
+export declare function toOpenAiMessages(messages: readonly AgentMessage[]): OpenAiMessage[];
+/** Map the read-only tool schemas to OpenAI `tools`. */
+export declare function toOpenAiTools(tools: readonly AgentToolSchema[]): OpenAiTool[];
+/**
+ * Normalise an OpenAI completion into a {@link ProviderResponse}. Tool calls
+ * take precedence; otherwise the message content is the final answer.
+ */
+export declare function parseOpenAiCompletion(completion: OpenAiCompletion): ProviderResponse;
+//# sourceMappingURL=openai.d.ts.map

package/dist/providers/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACtF;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,OAAO,CAAC,EAAE;YACR,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,UAAU,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;SACtC,CAAC;KACH,CAAC,CAAC;CACJ;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,aAAa,EAAE,CAsBnF;AAUD,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,UAAU,EAAE,CAK7E;AAaD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CAkBpF"}

package/dist/providers/openai.js

@@ -0,0 +1,79 @@
+/**
+ * Pure translation between the agent-core conversation shape and the OpenAI
+ * Chat Completions wire format. Shared by the bring-your-own hosted adapter
+ * (OpenAI-compatible mode) and the WebLLM adapter — the MLC runtime exposes an
+ * OpenAI-compatible `chat.completions.create`. No I/O, no dependencies: just
+ * shape mapping, so both adapters agree on tool-calling semantics.
+ */
+/** Map the agent conversation to OpenAI request messages. */
+export function toOpenAiMessages(messages) {
+    return messages.map((message) => {
+        switch (message.role) {
+            case "assistant":
+                return {
+                    role: "assistant",
+                    content: message.content,
+                    ...(message.toolCalls && message.toolCalls.length > 0
+                        ? { tool_calls: message.toolCalls.map(toOpenAiToolCall) }
+                        : {}),
+                };
+            case "tool":
+                return {
+                    role: "tool",
+                    content: message.content,
+                    tool_call_id: message.toolCallId,
+                    name: message.name,
+                };
+            default:
+                return { role: message.role, content: message.content };
+        }
+    });
+}
+function toOpenAiToolCall(call) {
+    return {
+        id: call.id,
+        type: "function",
+        function: { name: call.name, arguments: JSON.stringify(call.arguments ?? {}) },
+    };
+}
+/** Map the read-only tool schemas to OpenAI `tools`. */
+export function toOpenAiTools(tools) {
+    return tools.map((tool) => ({
+        type: "function",
+        function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+    }));
+}
+/** Parse tool-call arguments that arrive as a JSON string (OpenAI encoding). */
+function parseArguments(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Normalise an OpenAI completion into a {@link ProviderResponse}. Tool calls
+ * take precedence; otherwise the message content is the final answer.
+ */
+export function parseOpenAiCompletion(completion) {
+    const message = completion.choices?.[0]?.message;
+    const toolCalls = message?.tool_calls ?? [];
+    const content = message?.content ?? "";
+    if (toolCalls.length > 0) {
+        return {
+            kind: "tool_calls",
+            toolCalls: toolCalls.map((call) => ({
+                id: call.id,
+                name: call.function.name,
+                arguments: parseArguments(call.function.arguments),
+            })),
+            ...(content ? { content } : {}),
+        };
+    }
+    return { kind: "final", content };
+}
+//# sourceMappingURL=openai.js.map

package/dist/providers/openai.js.map

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

package/dist/providers/webllm.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Local, in-browser LLM adapter backed by WebLLM / WebGPU (ADR 0050 §4/§6).
+ *
+ * Zero data egress: the model runs entirely on the user's GPU and nothing —
+ * neither prompt nor results — leaves the browser. The heavy `@mlc-ai/web-llm`
+ * runtime is an **optional** dependency loaded via a lazy `import()` only when
+ * the user actually runs the assistant, so `@uptimizr/agent-core` stays small
+ * and browser-safe for everyone else. Model weights are downloaded on first use
+ * (behind explicit consent) and cached by the runtime in the browser's Cache
+ * Storage — never part of any precache.
+ */
+import type { LlmProvider } from "../provider.js";
+import { type OpenAiCompletion, type OpenAiMessage, type OpenAiTool } from "./openai.js";
+/** A curated model the user may install (ADR 0050 §4). */
+export interface CuratedModel {
+    /** MLC model id passed to the runtime. */
+    id: string;
+    /** Human-friendly name for the picker. */
+    label: string;
+    /** Approximate download size, for the consent disclosure. */
+    downloadSize: string;
+    /** Approximate GPU memory (VRAM) required. */
+    vram: string;
+    /** One-line description of the trade-off. */
+    description: string;
+}
+/**
+ * The complete set of model ids WebLLM supports for `ChatCompletionRequest.tools`
+ * (function calling). WebLLM hard-codes tool-calling to the Hermes-2-Pro /
+ * Hermes-3 family — its tool-call system prompt and output parser are
+ * Hermes-specific — so passing any other model with `tools` throws at runtime.
+ * The assistant relies on tool-calling, so every {@link CuratedModel} MUST be in
+ * this allowlist. Keep this list in sync with WebLLM's own supported set (these
+ * are the exact ids WebLLM names in its runtime error). Plain string membership
+ * only — never build a regex from a model id.
+ */
+export declare const SUPPORTED_TOOL_CALLING_MODELS: readonly string[];
+/**
+ * A small, curated set of **tool-calling-capable** models (ADR 0050 §4). WebLLM
+ * only supports function calling on the 7–8B Hermes family (see
+ * {@link SUPPORTED_TOOL_CALLING_MODELS}), so there is no small (<3 GB) option —
+ * local mode has an inherent ~4 GB download / ~5 GB-VRAM floor. Ordered
+ * smallest-first so the default is the least-friction working model. Sizes are
+ * approximate (sourced from WebLLM's `prebuiltAppConfig`) and shown to the user
+ * before any download.
+ */
+export declare const CURATED_MODELS: readonly CuratedModel[];
+/** Progress report emitted while weights download / the engine initialises. */
+export interface InitProgress {
+    /** Fraction complete in [0, 1]. */
+    progress: number;
+    /** Human-readable status text from the runtime. */
+    text: string;
+}
+/** The minimal slice of the `@mlc-ai/web-llm` runtime this adapter uses. */
+export interface WebLlmEngine {
+    chat: {
+        completions: {
+            create(request: {
+                messages: OpenAiMessage[];
+                tools?: OpenAiTool[];
+                tool_choice?: "auto";
+                stream?: false;
+            }): Promise<OpenAiCompletion>;
+        };
+    };
+    unload?(): Promise<void>;
+}
+/** The subset of the `@mlc-ai/web-llm` module surface this adapter loads. */
+export interface WebLlmRuntime {
+    CreateMLCEngine(model: string, engineConfig?: {
+        initProgressCallback?: (report: {
+            progress: number;
+            text: string;
+        }) => void;
+    }): Promise<WebLlmEngine>;
+}
+/** Options for {@link createWebLlmProvider}. */
+export interface WebLlmProviderOptions {
+    /** Curated model id to load. Defaults to the first curated model. */
+    model?: string;
+    /**
+     * Consent gate invoked once, before weights download begins. Return `false`
+     * (or reject) to abort — the adapter throws {@link WebLlmConsentError} and no
+     * data is downloaded. Use this to show the "~N GB, runs 100% locally" prompt.
+     */
+    confirmDownload?: (model: CuratedModel) => boolean | Promise<boolean>;
+    /** Called with download/initialise progress. */
+    onInitProgress?: (progress: InitProgress) => void;
+    /**
+     * Injectable runtime loader (for tests / custom hosting). Defaults to a lazy
+     * `import("@mlc-ai/web-llm")`.
+     */
+    loadRuntime?: () => Promise<WebLlmRuntime>;
+    /** Injectable WebGPU check (for tests); defaults to real feature detection. */
+    hasWebGpu?: () => boolean;
+}
+/** A WebLLM provider, plus a hook to release GPU resources. */
+export interface WebLlmProvider extends LlmProvider {
+    /** Release the loaded engine and its GPU memory. Safe to call repeatedly. */
+    unload(): Promise<void>;
+}
+/** Thrown when the local backend is used on a browser without WebGPU. */
+export declare class WebGpuUnavailableError extends Error {
+    constructor();
+}
+/** Thrown when the user declines the model-download consent prompt. */
+export declare class WebLlmConsentError extends Error {
+    constructor();
+}
+/**
+ * Thrown when the requested model is not one WebLLM supports for tool-calling
+ * (see {@link SUPPORTED_TOOL_CALLING_MODELS}). Raised as a preflight check —
+ * *before* any weights download or engine init — so the user never downloads
+ * gigabytes only to hit WebLLM's runtime `tools` error. The message mirrors
+ * WebLLM's own so consumers can surface a consistent explanation.
+ */
+export declare class UnsupportedToolCallingModelError extends Error {
+    constructor(modelId: string);
+}
+/**
+ * Create a local WebLLM provider. The runtime and model weights load lazily on
+ * the first {@link LlmProvider.complete} call — construction is cheap and has no
+ * side effects, so it is safe to build eagerly and feature-detect via
+ * {@link isWebGpuAvailable} before offering the local option.
+ */
+export declare function createWebLlmProvider(options?: WebLlmProviderOptions): WebLlmProvider;
+//# sourceMappingURL=webllm.d.ts.map

package/dist/providers/webllm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webllm.d.ts","sourceRoot":"","sources":["../../src/providers/webllm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,gBAAgB,CAAC;AAErF,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAM1D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAsBjD,CAAC;AAEF,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QACJ,WAAW,EAAE;YACX,MAAM,CAAC,OAAO,EAAE;gBACd,QAAQ,EAAE,aAAa,EAAE,CAAC;gBAC1B,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;gBACrB,WAAW,CAAC,EAAE,MAAM,CAAC;gBACrB,MAAM,CAAC,EAAE,KAAK,CAAC;aAChB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;SAC/B,CAAC;KACH,CAAC;IACF,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,eAAe,CACb,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,CAAA;KAAE,GAC7F,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,gDAAgD;IAChD,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IAClD;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,6EAA6E;IAC7E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,yEAAyE;AACzE,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAED,uEAAuE;AACvE,qBAAa,kBAAmB,SAAQ,KAAK;;CAK5C;AAED;;;;;;GAMG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;gBAC7C,OAAO,EAAE,MAAM;CAO5B;AAUD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAuDxF"}

package/dist/providers/webllm.js

@@ -0,0 +1,158 @@
+/**
+ * Local, in-browser LLM adapter backed by WebLLM / WebGPU (ADR 0050 §4/§6).
+ *
+ * Zero data egress: the model runs entirely on the user's GPU and nothing —
+ * neither prompt nor results — leaves the browser. The heavy `@mlc-ai/web-llm`
+ * runtime is an **optional** dependency loaded via a lazy `import()` only when
+ * the user actually runs the assistant, so `@uptimizr/agent-core` stays small
+ * and browser-safe for everyone else. Model weights are downloaded on first use
+ * (behind explicit consent) and cached by the runtime in the browser's Cache
+ * Storage — never part of any precache.
+ */
+import { isWebGpuAvailable } from "./config.js";
+import { parseOpenAiCompletion, toOpenAiMessages, toOpenAiTools, } from "./openai.js";
+/**
+ * The complete set of model ids WebLLM supports for `ChatCompletionRequest.tools`
+ * (function calling). WebLLM hard-codes tool-calling to the Hermes-2-Pro /
+ * Hermes-3 family — its tool-call system prompt and output parser are
+ * Hermes-specific — so passing any other model with `tools` throws at runtime.
+ * The assistant relies on tool-calling, so every {@link CuratedModel} MUST be in
+ * this allowlist. Keep this list in sync with WebLLM's own supported set (these
+ * are the exact ids WebLLM names in its runtime error). Plain string membership
+ * only — never build a regex from a model id.
+ */
+export const SUPPORTED_TOOL_CALLING_MODELS = [
+    "Hermes-2-Pro-Llama-3-8B-q4f16_1-MLC",
+    "Hermes-2-Pro-Llama-3-8B-q4f32_1-MLC",
+    "Hermes-2-Pro-Mistral-7B-q4f16_1-MLC",
+    "Hermes-3-Llama-3.1-8B-q4f32_1-MLC",
+    "Hermes-3-Llama-3.1-8B-q4f16_1-MLC",
+];
+/**
+ * A small, curated set of **tool-calling-capable** models (ADR 0050 §4). WebLLM
+ * only supports function calling on the 7–8B Hermes family (see
+ * {@link SUPPORTED_TOOL_CALLING_MODELS}), so there is no small (<3 GB) option —
+ * local mode has an inherent ~4 GB download / ~5 GB-VRAM floor. Ordered
+ * smallest-first so the default is the least-friction working model. Sizes are
+ * approximate (sourced from WebLLM's `prebuiltAppConfig`) and shown to the user
+ * before any download.
+ */
+export const CURATED_MODELS = [
+    {
+        id: "Hermes-2-Pro-Mistral-7B-q4f16_1-MLC",
+        label: "Hermes 2 Pro (Mistral 7B)",
+        downloadSize: "~3.9 GB",
+        vram: "~4.0 GB",
+        description: "Smallest tool-calling model; the least-friction default.",
+    },
+    {
+        id: "Hermes-2-Pro-Llama-3-8B-q4f16_1-MLC",
+        label: "Hermes 2 Pro (Llama 3 8B)",
+        downloadSize: "~4.6 GB",
+        vram: "~5.0 GB",
+        description: "Stronger Llama-3 base; needs a capable GPU.",
+    },
+    {
+        id: "Hermes-3-Llama-3.1-8B-q4f16_1-MLC",
+        label: "Hermes 3 (Llama 3.1 8B)",
+        downloadSize: "~4.5 GB",
+        vram: "~4.9 GB",
+        description: "Highest quality; needs a capable GPU (~5 GB VRAM).",
+    },
+];
+/** Thrown when the local backend is used on a browser without WebGPU. */
+export class WebGpuUnavailableError extends Error {
+    constructor() {
+        super("WebGPU is not available in this browser; the local model cannot run.");
+        this.name = "WebGpuUnavailableError";
+    }
+}
+/** Thrown when the user declines the model-download consent prompt. */
+export class WebLlmConsentError extends Error {
+    constructor() {
+        super("Model download was not confirmed by the user.");
+        this.name = "WebLlmConsentError";
+    }
+}
+/**
+ * Thrown when the requested model is not one WebLLM supports for tool-calling
+ * (see {@link SUPPORTED_TOOL_CALLING_MODELS}). Raised as a preflight check —
+ * *before* any weights download or engine init — so the user never downloads
+ * gigabytes only to hit WebLLM's runtime `tools` error. The message mirrors
+ * WebLLM's own so consumers can surface a consistent explanation.
+ */
+export class UnsupportedToolCallingModelError extends Error {
+    constructor(modelId) {
+        super(`${modelId} is not supported for tool-calling. The assistant requires function calling; ` +
+            `WebLLM supports it only on these models: ${SUPPORTED_TOOL_CALLING_MODELS.join(", ")}.`);
+        this.name = "UnsupportedToolCallingModelError";
+    }
+}
+function resolveModel(id) {
+    const model = id ? CURATED_MODELS.find((m) => m.id === id) : CURATED_MODELS[0];
+    return model ?? { id: id ?? "", label: id ?? "", downloadSize: "?", vram: "?", description: "" };
+}
+const defaultLoadRuntime = () => import("@mlc-ai/web-llm");
+/**
+ * Create a local WebLLM provider. The runtime and model weights load lazily on
+ * the first {@link LlmProvider.complete} call — construction is cheap and has no
+ * side effects, so it is safe to build eagerly and feature-detect via
+ * {@link isWebGpuAvailable} before offering the local option.
+ */
+export function createWebLlmProvider(options = {}) {
+    const model = resolveModel(options.model);
+    // Preflight (defense-in-depth): fail fast if the model can't do tool-calling,
+    // so we never download weights only to hit WebLLM's runtime `tools` error.
+    if (!SUPPORTED_TOOL_CALLING_MODELS.includes(model.id)) {
+        throw new UnsupportedToolCallingModelError(model.id);
+    }
+    const loadRuntime = options.loadRuntime ?? defaultLoadRuntime;
+    const hasWebGpu = options.hasWebGpu ?? (() => isWebGpuAvailable());
+    let enginePromise;
+    function ensureEngine() {
+        if (!enginePromise) {
+            enginePromise = initEngine().catch((err) => {
+                // Reset so a later attempt (e.g. after granting consent) can retry.
+                enginePromise = undefined;
+                throw err;
+            });
+        }
+        return enginePromise;
+    }
+    async function initEngine() {
+        if (!hasWebGpu())
+            throw new WebGpuUnavailableError();
+        if (options.confirmDownload) {
+            const ok = await options.confirmDownload(model);
+            if (!ok)
+                throw new WebLlmConsentError();
+        }
+        const runtime = await loadRuntime();
+        return runtime.CreateMLCEngine(model.id, {
+            initProgressCallback: options.onInitProgress
+                ? (report) => options.onInitProgress?.({ progress: report.progress, text: report.text })
+                : undefined,
+        });
+    }
+    return {
+        async complete(request) {
+            const engine = await ensureEngine();
+            const completion = await engine.chat.completions.create({
+                messages: toOpenAiMessages(request.messages),
+                tools: toOpenAiTools(request.tools),
+                tool_choice: "auto",
+                stream: false,
+            });
+            return parseOpenAiCompletion(completion);
+        },
+        async unload() {
+            const promise = enginePromise;
+            enginePromise = undefined;
+            if (!promise)
+                return;
+            const engine = await promise.catch(() => undefined);
+            await engine?.unload?.();
+        },
+    };
+}
+//# sourceMappingURL=webllm.js.map

package/dist/providers/webllm.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { QueryParams } from "./client.js";
+/** A resolved read request: the collector path and its query parameters. */
+export interface ReadToolRequest {
+    path: string;
+    params: QueryParams;
+}
+/**
+ * A read-only tool definition. `inputSchema` is a Zod raw shape the MCP runtime
+ * uses to validate arguments; `buildRequest` maps validated arguments to a
+ * `GET` against the collector. Definitions are pure and unit-testable without a
+ * live collector.
+ */
+export interface ReadTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    buildRequest: (args: Record<string, unknown>) => ReadToolRequest;
+}
+/**
+ * The catalog of read-only tools. Each wraps one documented collector query
+ * endpoint (docs/integration.md §Query). There are intentionally **no**
+ * ingestion, mutation, or raw per-session event tools — the surface is
+ * aggregate, read-only, and privacy-preserving (ADR 0003 / ADR 0017).
+ */
+export declare const readTools: readonly ReadTool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,CAAC;CAClE;AAqDD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAwRxC,CAAC"}