@tanstack-ai-browser/prompt-api 0.0.0-stage → 0.2.1

package/dist/limit.js

@@ -0,0 +1,203 @@
+/** `maxCompletionTokens`, validated like the other adapters validate it. */
+export function outputTokenLimit(options) {
+    const limit = options?.maxCompletionTokens;
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {
+        throw new RangeError("maxCompletionTokens must be a nonnegative safe integer.");
+    }
+    return limit;
+}
+export const outputLimitUsage = (limit, reached) => limit === undefined
+    ? undefined
+    : {
+        outputTokenLimit: limit,
+        outputTokenMeasurement: "estimate-then-context-usage",
+        outputTokenLimitEnforcement: "best-effort",
+        outputTokenLimitReached: reached
+    };
+/** UTF-8 bytes of a string: an upper bound on its tokens. */
+function utf8Bytes(text) {
+    let bytes = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code < 0xdc00 && i + 1 < text.length) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+/** The text of a prompt input (or of messages), without images or audio. */
+export function textOfInput(input) {
+    if (typeof input === "string")
+        return input;
+    return input
+        .map((message) => typeof message.content === "string"
+        ? message.content
+        : message.content
+            .map((part) => (part.type === "text" && typeof part.value === "string" ? part.value : ""))
+            .join(""))
+        .filter(Boolean)
+        .join("\n");
+}
+/**
+ * Live emission stops once the estimate passes this share of the limit, or
+ * once the text passes the limit in UTF-8 bytes. Text sent live can't be
+ * taken back, so it must stay within the limit whatever the estimate says:
+ * no token is shorter than a byte, so text of at most `limit` bytes holds at
+ * most `limit` tokens, however much denser the reply is than the calibration
+ * text. The share keeps longer limits from streaming up to the last token
+ * live, where a low estimate would leave nothing to trim.
+ */
+export const LIVE_FRACTION = 0.75;
+/**
+ * Generation is stopped once the estimate passes STOP_FACTOR × limit +
+ * STOP_SLACK tokens: past the limit, so the exact trim afterwards finds the
+ * limit's worth of text unless the reply holds a fifth fewer tokens per byte
+ * than the calibration text (the estimate is then high by more than 1.25×).
+ * The slack covers short limits, where a chunk or two of noise is a large
+ * share; 8 tokens is about 0.15 s of Gemini Nano's decoding.
+ */
+export const STOP_FACTOR = 1.25;
+export const STOP_SLACK = 8;
+/** Calibration text shorter than this (UTF-8 bytes) is too noisy alone. */
+const MIN_SAMPLE_BYTES = 64;
+/** Calibration measures at most this many characters of text. */
+const MAX_SAMPLE_CHARS = 4000;
+/**
+ * Calibrates when the conversation has almost no text ("hi"): measured with
+ * the model's own tokenizer like any other text, never a fixed ratio.
+ */
+const REFERENCE_TEXT = "The quick brown fox jumps over the lazy dog, then rests in the warm afternoon sun while the farmer counts his sheep.";
+/**
+ * The text a limit's tokens-per-byte ratio is calibrated on: the request's
+ * own text first, then earlier messages (most recent first) while it's
+ * under 64 bytes, then a fixed reference sentence if it still is.
+ */
+export function calibrationSample(texts) {
+    let sample = "";
+    for (const text of texts) {
+        if (!text)
+            continue;
+        if (sample && utf8Bytes(sample) >= MIN_SAMPLE_BYTES)
+            break;
+        sample = sample ? `${sample}\n${text}` : text;
+    }
+    if (utf8Bytes(sample) < MIN_SAMPLE_BYTES) {
+        sample = sample ? `${sample}\n${REFERENCE_TEXT}` : REFERENCE_TEXT;
+    }
+    if (sample.length <= MAX_SAMPLE_CHARS)
+        return sample;
+    const end = sample.charCodeAt(MAX_SAMPLE_CHARS - 1);
+    return sample.slice(0, end >= 0xd800 && end < 0xdc00 ? MAX_SAMPLE_CHARS - 1 : MAX_SAMPLE_CHARS);
+}
+/**
+ * A limiter for one generation. Chrome runs one operation at a time per
+ * model: `measureContextUsage` (on any session or clone) and `clone()` wait
+ * until a generation in progress finishes, so nothing can be measured while
+ * the model writes. Instead, before generating, `sample` (the request's
+ * text) is measured to calibrate a bytes-per-token ratio; while generating,
+ * tokens are estimated from UTF-8 bytes with it; once the generation has
+ * stopped, `finish()` measures exactly and trims.
+ *
+ * Bytes per token, not characters: it varies much less across scripts (a
+ * CJK character is 3 bytes and about a token; English runs about 4 bytes a
+ * token), and no token is shorter than a byte, so the ratio's floor of 1 is
+ * the hard bound tokens ≤ bytes.
+ */
+export async function tokenLimiter(session, limit, sample, signal) {
+    const options = signal ? [{ signal }] : [];
+    let overhead;
+    const measure = async (text) => {
+        signal?.throwIfAborted();
+        if (!text)
+            return 0;
+        overhead ??= await session.measureContextUsage("", ...options);
+        return Math.max(0, (await session.measureContextUsage(text, ...options)) - overhead);
+    };
+    const sampleTokens = limit > 0 ? await measure(sample) : 0;
+    const bytesPerToken = Math.max(1, utf8Bytes(sample) / Math.max(1, sampleTokens));
+    const liveLine = LIVE_FRACTION * limit;
+    const stopLine = STOP_FACTOR * limit + STOP_SLACK;
+    let text = "";
+    let emitted = "";
+    let holding = false;
+    let bytes = 0;
+    let stopped = limit === 0;
+    const estimate = () => bytes / bytesPerToken;
+    const check = () => {
+        if (estimate() >= stopLine)
+            stopped = true;
+    };
+    return {
+        get text() { return text; },
+        get stopped() { return stopped; },
+        push(delta) {
+            if (!delta)
+                return "";
+            text += delta;
+            bytes += utf8Bytes(delta);
+            check();
+            if (!holding && estimate() <= liveLine && bytes <= limit) {
+                emitted += delta;
+                return delta;
+            }
+            holding = true;
+            return "";
+        },
+        async finish() {
+            const tokens = await measure(text);
+            if (tokens <= limit) {
+                return { text, held: text.slice(emitted.length), tokens, reached: stopped || tokens >= limit };
+            }
+            // Over the limit: keep the longest prefix within it, searching by code
+            // point from what was sent live. Token counts need not be monotonic in
+            // the prefix, so the chosen prefix is verified afterwards.
+            const points = Array.from(text);
+            const start = Array.from(emitted).length;
+            let low = start;
+            let high = points.length - 1;
+            let accepted = emitted;
+            while (low <= high) {
+                const middle = Math.floor((low + high) / 2);
+                const prefix = points.slice(0, middle).join("");
+                if ((await measure(prefix)) <= limit) {
+                    accepted = prefix;
+                    low = middle + 1;
+                }
+                else
+                    high = middle - 1;
+            }
+            let acceptedPoints = Array.from(accepted);
+            let count = await measure(accepted);
+            while (count > limit && acceptedPoints.length > start) {
+                acceptedPoints = acceptedPoints.slice(0, -1);
+                accepted = acceptedPoints.join("");
+                count = await measure(accepted);
+            }
+            return { text: accepted, held: accepted.slice(emitted.length), tokens: count, reached: true };
+        }
+    };
+}
+/**
+ * An abort signal for one generation that follows the caller's (with its
+ * reason) and that `stop()` aborts on its own, never touching the caller's.
+ */
+export function internalAbort(signal, reason) {
+    const internal = new AbortController();
+    const cancel = () => internal.abort(signal?.reason);
+    if (signal?.aborted)
+        cancel();
+    else
+        signal?.addEventListener("abort", cancel, { once: true });
+    return {
+        signal: internal.signal,
+        stop: () => internal.abort(new DOMException(reason, "AbortError")),
+        dispose: () => signal?.removeEventListener("abort", cancel)
+    };
+}

package/dist/messages.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The conversation as the Prompt API reads it: user messages with their
+ * images and audio (loaded as Blobs), the model's messages with their tool
+ * calls as ```tool_call fences, and tool results as user messages in a
+ * ```tool_result fence.
+ */
+import type { ModelMessage } from "@tanstack/ai";
+import type { MediaInput } from "./model.js";
+import type { LanguageModelMessage } from "./types.js";
+/** The text of a message's content, without its images or audio. */
+export declare function contentText(content: ModelMessage["content"]): string;
+/** The kinds of media in a conversation, which its session must expect. */
+export declare function mediaIn(messages: ReadonlyArray<ModelMessage>): Array<MediaInput>;
+/**
+ * The conversation as Prompt API messages, from `start` on (a kept session
+ * holds the rest); a step's tool results share one message. Tool names come
+ * from the whole conversation.
+ */
+export declare function toLanguageModelMessages(messages: ReadonlyArray<ModelMessage>, start?: number): Promise<Array<LanguageModelMessage>>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,cAAc,CAAA;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,KAAK,EAAwB,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAE5E,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,UAG3D;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAShF;AAgCD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,EACrC,KAAK,SAAI,GACR,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAiCtC"}

package/dist/messages.js

@@ -0,0 +1,95 @@
+import { toolCallFence, toolResultFence, toolResultLine } from "./tools.js";
+/** The text of a message's content, without its images or audio. */
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    return (content ?? []).map((part) => (part.type === "text" ? part.content : "")).join("");
+}
+/** The kinds of media in a conversation, which its session must expect. */
+export function mediaIn(messages) {
+    const kinds = new Set();
+    for (const m of messages) {
+        if (m.role !== "user" || typeof m.content === "string")
+            continue;
+        for (const part of m.content ?? []) {
+            if (part.type === "image" || part.type === "audio")
+                kinds.add(part.type);
+        }
+    }
+    return [...kinds].sort();
+}
+function base64Blob(value, mimeType) {
+    const data = value.startsWith("data:") ? value.slice(value.indexOf(",") + 1) : value;
+    const bytes = Uint8Array.from(atob(data), (c) => c.charCodeAt(0));
+    return new Blob([bytes], { type: mimeType ?? "" });
+}
+async function loadMedia(type, source) {
+    if (source.type === "data")
+        return base64Blob(source.value, source.mimeType);
+    if (source.type !== "url") {
+        throw new Error(`The Prompt API takes ${type} as data or a URL, not a ${source.type} source.`);
+    }
+    const response = await fetch(source.value);
+    if (!response.ok)
+        throw new Error(`${source.value.slice(0, 120)}: HTTP ${response.status}`);
+    return response.blob();
+}
+async function userContent(content) {
+    if (typeof content === "string" || !content)
+        return content ?? "";
+    if (content.every((part) => part.type === "text"))
+        return contentText(content);
+    return Promise.all(content.map(async (part) => {
+        if (part.type === "text")
+            return { type: "text", value: part.content };
+        if (part.type === "image" || part.type === "audio") {
+            return { type: part.type, value: await loadMedia(part.type, part.source) };
+        }
+        throw new Error(`The Prompt API takes text, images and audio, not ${part.type}.`);
+    }));
+}
+/**
+ * The conversation as Prompt API messages, from `start` on (a kept session
+ * holds the rest); a step's tool results share one message. Tool names come
+ * from the whole conversation.
+ */
+export async function toLanguageModelMessages(messages, start = 0) {
+    const out = [];
+    const toolNames = new Map();
+    for (const m of messages.slice(0, start)) {
+        for (const call of m.toolCalls ?? [])
+            toolNames.set(call.id, call.function.name);
+    }
+    let results;
+    for (const m of messages.slice(start)) {
+        if (m.role === "tool") {
+            const id = m.toolCallId ?? "";
+            const line = toolResultLine(id, toolNames.get(id) ?? "tool", contentText(m.content), m.error);
+            if (results) {
+                results.push(line);
+                out[out.length - 1] = { role: "user", content: toolResultFence(results) };
+            }
+            else {
+                results = [line];
+                out.push({ role: "user", content: toolResultFence(results) });
+            }
+            continue;
+        }
+        results = undefined;
+        if (m.role === "assistant") {
+            for (const call of m.toolCalls ?? [])
+                toolNames.set(call.id, call.function.name);
+            const content = [contentText(m.content), ...(m.toolCalls?.length ? [toolCallFence(m.toolCalls)] : [])]
+                .filter(Boolean)
+                .join("\n");
+            if (content)
+                out.push({ role: "assistant", content });
+        }
+        else {
+            const content = await userContent(m.content);
+            if (content.length > 0)
+                out.push({ role: "user", content });
+        }
+    }
+    return out;
+}

package/dist/model-meta.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The model the Prompt API gives: the browser's own text model ("text", as other Prompt API libraries name it), Gemini
+ * Nano in Chrome and Phi-4-mini in Edge, with what it supports.
+ */
+/** What the browser's model supports. */
+export type PromptApiModelMeta = {
+    /** The model's name for `promptApiText`: "text". */
+    name: string;
+    supports: {
+        input: ReadonlyArray<"text" | "image" | "audio">;
+        output: ReadonlyArray<"text">;
+        capabilities: ReadonlyArray<"tools">;
+    };
+};
+/** The model: whichever one the browser provides. */
+export declare const PROMPT_API_CHAT_MODELS: readonly ["text"];
+/** The model: whichever one the browser provides. */
+export type PromptApiChatModel = (typeof PROMPT_API_CHAT_MODELS)[number];
+/** The model's metadata, by name. */
+export declare const PROMPT_API_MODEL_META: Readonly<Record<PromptApiChatModel, PromptApiModelMeta>>;
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-meta.d.ts","sourceRoot":"","sources":["../src/model-meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE;QACR,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,CAAA;QAChD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;QAC7B,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;KACrC,CAAA;CACF,CAAA;AAWD,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,mBAA2B,CAAA;AAE9D,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAA;AAExE,qCAAqC;AACrC,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAE1F,CAAA"}

package/dist/model-meta.js

@@ -0,0 +1,18 @@
+/**
+ * The model the Prompt API gives: the browser's own text model ("text", as other Prompt API libraries name it), Gemini
+ * Nano in Chrome and Phi-4-mini in Edge, with what it supports.
+ */
+const BUILT_IN = {
+    name: "text",
+    supports: {
+        input: ["text", "image", "audio"],
+        output: ["text"],
+        capabilities: ["tools"]
+    }
+};
+/** The model: whichever one the browser provides. */
+export const PROMPT_API_CHAT_MODELS = [BUILT_IN.name];
+/** The model's metadata, by name. */
+export const PROMPT_API_MODEL_META = {
+    [BUILT_IN.name]: BUILT_IN
+};

package/dist/model.d.ts

@@ -0,0 +1,28 @@
+import type { Availability, DownloadProgressCallback, LanguageModelCreateOptions, LanguageModelSession } from "./types.js";
+export type { Availability, SamplingMode } from "./types.js";
+/** Kinds of input besides text a session can be told to expect. */
+export type MediaInput = "image" | "audio";
+/** Every kind of input besides text, in the order `availableInputModalities` asks. */
+export declare const MEDIA_INPUTS: ReadonlyArray<MediaInput>;
+/** Languages the model is told to expect, in and out, by default. */
+export declare const DEFAULT_LANGUAGES: readonly ["en"];
+/**
+ * What every session expects: text in and out in the languages given (Chrome
+ * checks its safety filters for the output language), and images or audio
+ * in if the conversation has them.
+ */
+export declare function baseOptions(languages?: ReadonlyArray<string>, media?: ReadonlyArray<MediaInput>): LanguageModelCreateOptions;
+/**
+ * Whether this browser can run its built-in model with these options:
+ * "available" (on the device), "downloadable" or "downloading" (it
+ * downloads when a session is created), or "unavailable".
+ */
+export declare function promptApiAvailability(options: LanguageModelCreateOptions): Promise<Availability>;
+/**
+ * A new session. `onDownloadProgress` hears a download, 0 to 1 (Chrome
+ * reports 0 and 1 on every create, so only the steps between are passed
+ * on), then 1 once the session has started. Aborting `signal` stops the
+ * create and destroys the session.
+ */
+export declare function createSession(options: LanguageModelCreateOptions, signal?: AbortSignal, onDownloadProgress?: DownloadProgressCallback): Promise<LanguageModelSession>;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EAExB,0BAA0B,EAC1B,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5D,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,OAAO,CAAA;AAE1C,sFAAsF;AACtF,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,UAAU,CAAsB,CAAA;AAEzE,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,YAAI,IAAI,CAAU,CAAA;AAEhD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,SAAS,GAAE,aAAa,CAAC,MAAM,CAAqB,EACpD,KAAK,GAAE,aAAa,CAAC,UAAU,CAAM,GACpC,0BAA0B,CAK5B;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,YAAY,CAAC,CAEtG;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,0BAA0B,EACnC,MAAM,CAAC,EAAE,WAAW,EACpB,kBAAkB,CAAC,EAAE,wBAAwB,GAC5C,OAAO,CAAC,oBAAoB,CAAC,CAe/B"}

package/dist/model.js

@@ -0,0 +1,53 @@
+/**
+ * The browser's built-in model: whether this browser has one, and its
+ * sessions. The browser downloads the model once for all sites (Chrome
+ * keeps it in its profile) and loads it when a session is created.
+ */
+import { languageModel } from "./types.js";
+/** Every kind of input besides text, in the order `availableInputModalities` asks. */
+export const MEDIA_INPUTS = ["image", "audio"];
+/** Languages the model is told to expect, in and out, by default. */
+export const DEFAULT_LANGUAGES = ["en"];
+/**
+ * What every session expects: text in and out in the languages given (Chrome
+ * checks its safety filters for the output language), and images or audio
+ * in if the conversation has them.
+ */
+export function baseOptions(languages = DEFAULT_LANGUAGES, media = []) {
+    return {
+        expectedInputs: [{ type: "text", languages: [...languages] }, ...media.map((type) => ({ type }))],
+        expectedOutputs: [{ type: "text", languages: [...languages] }]
+    };
+}
+/**
+ * Whether this browser can run its built-in model with these options:
+ * "available" (on the device), "downloadable" or "downloading" (it
+ * downloads when a session is created), or "unavailable".
+ */
+export async function promptApiAvailability(options) {
+    return (await languageModel()?.availability(options)) ?? "unavailable";
+}
+/**
+ * A new session. `onDownloadProgress` hears a download, 0 to 1 (Chrome
+ * reports 0 and 1 on every create, so only the steps between are passed
+ * on), then 1 once the session has started. Aborting `signal` stops the
+ * create and destroys the session.
+ */
+export async function createSession(options, signal, onDownloadProgress) {
+    const api = languageModel();
+    if (!api)
+        throw new Error("This browser has no Prompt API (LanguageModel).");
+    const session = await api.create({
+        ...options,
+        ...(signal && { signal }),
+        monitor(monitor) {
+            monitor.addEventListener("downloadprogress", (event) => {
+                const { loaded } = event;
+                if (loaded > 0 && loaded < 1)
+                    onDownloadProgress?.(loaded);
+            });
+        }
+    });
+    onDownloadProgress?.(1);
+    return session;
+}

package/dist/reasoning.d.ts

@@ -0,0 +1,42 @@
+import type { ModelMessage, ReasoningRequest } from "@tanstack/ai";
+import type { LanguageModelInput, LanguageModelMessage, LanguageModelSession } from "./types.js";
+export type PromptApiReasoning = {
+    levels: "off" | "high";
+    budget: true;
+};
+export type PromptApiReasoningUsage = {
+    reasoningEmulated: true;
+    reasoningTokenMeasurement: "context-usage";
+    reasoningBudgetEnforcement: "best-effort";
+    thinkingTokens: number;
+    thinkingBudgetTokens?: number;
+    thinkingBudgetExhausted: boolean;
+    reasoningMs: number;
+};
+export type DraftReasoningResult = {
+    notes: string;
+    usage: PromptApiReasoningUsage;
+    capReached: boolean;
+};
+export declare function promptReasoningOptions(request: ReasoningRequest | undefined): {
+    enabled: boolean;
+    budget: number | undefined;
+};
+/**
+ * The draft's instruction, quoting the user's latest message: after a tool
+ * result, the newest user message is this instruction itself, and small
+ * models took it for the message to reply to.
+ */
+export declare function draftInstruction(messages: ReadonlyArray<ModelMessage>): LanguageModelMessage;
+export declare function withWorkingNotes(input: LanguageModelInput, notes: string): LanguageModelInput;
+/**
+ * Two-pass adapter emulation, not hidden native model reasoning or native
+ * token control. The draft stops at the thinking `budget` and at `cap`, the
+ * output tokens left for the whole reply (`maxCompletionTokens`, which counts
+ * the draft too), whichever comes first; `capReached` says the cap stopped it.
+ * Under a limit, the draft is held to it as `tokenLimiter` holds any reply:
+ * estimated while it streams, stopped a little past the limit, then measured
+ * and trimmed exactly (the rest of the notes streams once the draft stops).
+ */
+export declare function draftReasoning(session: LanguageModelSession, input: LanguageModelInput, conversation: ReadonlyArray<ModelMessage>, signal: AbortSignal | undefined, budget?: number, cap?: number): AsyncGenerator<string, DraftReasoningResult>;
+//# sourceMappingURL=reasoning.d.ts.map

package/dist/reasoning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning.d.ts","sourceRoot":"","sources":["../src/reasoning.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAIlE,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEhG,MAAM,MAAM,kBAAkB,GAAG;IAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAA;AACzE,MAAM,MAAM,uBAAuB,GAAG;IACpC,iBAAiB,EAAE,IAAI,CAAA;IACvB,yBAAyB,EAAE,eAAe,CAAA;IAC1C,0BAA0B,EAAE,aAAa,CAAA;IACzC,cAAc,EAAE,MAAM,CAAA;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,uBAAuB,EAAE,OAAO,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AACD,MAAM,MAAM,oBAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAA;AAEzG,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS;;;EAK3E;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,oBAAoB,CAQ5F;AACD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAI7F;AAED;;;;;;;;GAQG;AACH,wBAAuB,cAAc,CAAC,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAkDvP"}

package/dist/reasoning.js

@@ -0,0 +1,113 @@
+import { calibrationSample, internalAbort, smallest, textOfInput, tokenLimiter } from "./limit.js";
+import { contentText } from "./messages.js";
+export function promptReasoningOptions(request) {
+    const budget = request?.budgetTokens;
+    if (budget !== undefined && (!Number.isSafeInteger(budget) || budget < 0))
+        throw new RangeError("reasoning.budgetTokens must be a nonnegative safe integer.");
+    if (request?.level !== undefined && request.level !== "off" && request.level !== "high")
+        throw new RangeError("Prompt API emulated reasoning supports off or high.");
+    return { enabled: request?.level === "high", budget };
+}
+/** The longest quote of the user's message the draft instruction carries. */
+const QUOTE_CHARS = 500;
+/**
+ * The draft's instruction, quoting the user's latest message: after a tool
+ * result, the newest user message is this instruction itself, and small
+ * models took it for the message to reply to.
+ */
+export function draftInstruction(messages) {
+    const latest = [...messages].reverse().find((m) => m.role === "user");
+    const text = latest ? contentText(latest.content).trim().replace(/\s+/g, " ") : "";
+    const quote = text.length > QUOTE_CHARS ? `${text.slice(0, QUOTE_CHARS - 1)}…` : text;
+    return {
+        role: "user",
+        content: `Now write notes for yourself before replying to the user's latest message${quote ? `, "${quote}"` : ""}: what's needed, what you already have, and what to do next. Don't call tools or write the reply yet.`
+    };
+}
+export function withWorkingNotes(input, notes) {
+    if (!notes)
+        return input;
+    const messages = typeof input === "string" ? [{ role: "user", content: input }] : input;
+    return [...messages, { role: "user", content: `Working notes to verify against the conversation:\n${notes}\nNow produce the final response or required tool call.` }];
+}
+/**
+ * Two-pass adapter emulation, not hidden native model reasoning or native
+ * token control. The draft stops at the thinking `budget` and at `cap`, the
+ * output tokens left for the whole reply (`maxCompletionTokens`, which counts
+ * the draft too), whichever comes first; `capReached` says the cap stopped it.
+ * Under a limit, the draft is held to it as `tokenLimiter` holds any reply:
+ * estimated while it streams, stopped a little past the limit, then measured
+ * and trimmed exactly (the rest of the notes streams once the draft stops).
+ */
+export async function* draftReasoning(session, input, conversation, signal, budget, cap) {
+    signal?.throwIfAborted();
+    if (budget !== undefined && (!Number.isSafeInteger(budget) || budget < 0))
+        throw new RangeError("reasoning.budgetTokens must be a nonnegative safe integer.");
+    const began = performance.now();
+    const limit = smallest(budget, cap);
+    const usage = (tokens, exhausted) => ({ reasoningEmulated: true, reasoningTokenMeasurement: "context-usage", reasoningBudgetEnforcement: "best-effort", thinkingTokens: tokens, ...(budget !== undefined && { thinkingBudgetTokens: budget }), thinkingBudgetExhausted: exhausted, reasoningMs: performance.now() - began });
+    if (limit === 0)
+        return { notes: "", usage: usage(0, budget === 0), capReached: cap === 0 };
+    let draft;
+    let limiter;
+    const stopper = internalAbort(signal, "Emulated reasoning budget reached");
+    try {
+        draft = await session.clone({ signal });
+        const messages = typeof input === "string" ? [{ role: "user", content: input }] : input;
+        const prompt = [...messages, draftInstruction(conversation)];
+        // Calibrated while the model is idle; nothing is measured mid-draft.
+        if (limit !== undefined)
+            limiter = await tokenLimiter(session, limit, calibrationSample([textOfInput(prompt)]), signal);
+        const stream = draft.promptStreaming(prompt, { signal: stopper.signal });
+        let notes = "";
+        try {
+            for await (const piece of stream) {
+                signal?.throwIfAborted();
+                const parts = Array.isArray(piece) ? piece : [piece];
+                const delta = parts.map(part => typeof part === "string" ? part : part.type === "text" ? String(part.value) : "").join("");
+                if (!delta)
+                    continue;
+                if (!limiter) {
+                    notes += delta;
+                    yield delta;
+                    continue;
+                }
+                const live = limiter.push(delta);
+                if (limiter.stopped)
+                    stopper.stop();
+                if (live)
+                    yield live;
+                if (limiter.stopped)
+                    break;
+            }
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (!limiter?.stopped)
+                throw error;
+        }
+        signal?.throwIfAborted();
+        if (!limiter)
+            return { notes, usage: usage(await notesTokens(session, notes, signal), false), capReached: false };
+        // The draft has stopped: the model is idle, so the exact count is instant.
+        const kept = await limiter.finish();
+        if (kept.held)
+            yield kept.held;
+        return { notes: kept.text, usage: usage(kept.tokens, kept.reached && limit === budget), capReached: kept.reached && limit === cap };
+    }
+    finally {
+        stopper.dispose();
+        // Stops a draft left unread.
+        if (!stopper.signal.aborted)
+            stopper.stop();
+        draft?.destroy();
+    }
+}
+/** Tokens of finished notes, less the empty message's overhead. */
+async function notesTokens(session, notes, signal) {
+    if (!notes)
+        return 0;
+    const options = signal ? [{ signal }] : [];
+    const overhead = await session.measureContextUsage("", ...options);
+    return Math.max(0, (await session.measureContextUsage(notes, ...options)) - overhead);
+}

package/dist/sessions.d.ts

@@ -0,0 +1,48 @@
+import type { PromptMessage } from "./messages.js";
+import type { LanguageModelCreateOptions, LanguageModelSession } from "./types.js";
+/** A session lent to one model call. */
+export type Lease = {
+    session: LanguageModelSession;
+    /** Tokens the session had already read and didn't read again. */
+    cachedTokens: number;
+    /** Time spent creating the session (reading the conversation), in ms. */
+    createMs: number;
+    /** Why the thread's kept session couldn't be used, if it had one. */
+    miss?: string;
+    /** Whether this call reused a previously prepared input prefix. */
+    reused: boolean;
+    /** Whether the browser dropped old turns to make room since the lease began. */
+    overflowed: () => boolean;
+    /** Gives the session back, having read `history` (after the system prompt). */
+    release: (history: Array<PromptMessage>) => void;
+    /** Frees this session; for an isolated call, only its working clone is freed. */
+    discard: () => void;
+};
+/**
+ * A session for a conversation that has read `system` and `prior`: the
+ * thread's own if it has read a start of them (the rest is appended), else
+ * a new one. `media` caches the images and audio loaded for the call.
+ */
+type SessionOptions = {
+    threadId: string | undefined;
+    system: string;
+    prior: Array<PromptMessage>;
+    options: LanguageModelCreateOptions;
+    signal: AbortSignal | undefined;
+    media?: Map<string, Promise<Blob>>;
+    /** Generate on a disposable clone of a cached, unmodified input-prefix session. */
+    isolated?: boolean;
+    /** Disable managed cross-request reuse and retention for this lease only. */
+    retain?: boolean;
+    /** The browser's download of its model, 0 to 1, if a new session starts it. */
+    onDownloadProgress?: (progress: number) => void;
+};
+export declare function leaseSession(options: SessionOptions): Promise<Lease>;
+/**
+ * Frees every session kept, as when the page no longer needs the model.
+ * Sessions a call holds, or is still creating, finish that call and are
+ * freed when it ends instead of going back in the cache.
+ */
+export declare function destroyPromptApiSessions(): void;
+export {};
+//# sourceMappingURL=sessions.d.ts.map