From b3aa2b2084710be3dd1c7ec6528f3deb427861bf Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 14:22:37 -0800 Subject: [PATCH 1/7] Update docs to explain renaming of API features --- README.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0dc3e70..957c731 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,9 @@ The following are potential goals we are not yet certain of: Both of these potential goals could pose challenges to interoperability, so we want to investigate more how important such functionality is to developers to find the right tradeoff. -### Deprecation Notice +### API Updates: Deprecations and Renames + +**Deprecated & Extension-Only:** The following features of the LanguageModel API are **deprecated** and their functionality is now restricted to web extension contexts only: @@ -56,6 +58,16 @@ The following features of the LanguageModel API are **deprecated** and their fun These features may be completely removed in the future. This change is intended to simplify the API and address inconsistencies in parameter support across various models. +**Renamed Attributes/Methods:** + +* `languageModel.inputUsage` is deprecated and renamed to **`languageModel.contextUsage`**. +* `languageModel.inputQuota` is deprecated and renamed to **`languageModel.contextWindow`**. +* `languageModel.measureInputUsage()` is deprecated and renamed to **`languageModel.measureContextUsage()`**. + +**Legacy Aliases (Extension-Only):** + +* The old names (`inputUsage`, `inputQuota`, `measureInputUsage`) are available as deprecated aliases for the new names, but **only within Chrome Extension contexts**. + ## Examples ### Zero-shot prompting @@ -339,7 +351,7 @@ The returned value will be a string that matches the input `RegExp`. If the user If a value that is neither a `RegExp` object or a valid JSON schema object is given, the method will error with a `TypeError`. -By default, the implementation may include the schema or regular expression as part of the message sent to the underlying language model, which will use up some of the [input quota](#tokenization-context-window-length-limits-and-overflow). You can measure how much it will use up by passing the `responseConstraint` option to `session.measureInputUsage()`. If you want to avoid this behavior, you can use the `omitResponseConstraintInput` option. In such cases, it's strongly recommended to include some guidance in the prompt string itself: +By default, the implementation may include the schema or regular expression as part of the message sent to the underlying language model, which will use up some of the [context window](#tokenization-context-window-length-limits-and-overflow). You can measure how much it will use up by passing the `responseConstraint` option to `session.measureContextUsage()`. If you want to avoid this behavior, you can use the `omitResponseConstraintInput` option. In such cases, it's strongly recommended to include some guidance in the prompt string itself: ```js const result = await session.prompt(` @@ -580,15 +592,15 @@ Finally, note that if either prompting or appending has caused an [overflow](#to A given language model session will have a maximum number of tokens it can process. Developers can check their current usage and progress toward that limit by using the following properties on the session object: ```js -console.log(`${session.inputUsage} tokens used, out of ${session.inputQuota} tokens available.`); +console.log(`${session.contextUsage} tokens used, out of ${session.contextWindow} tokens available.`); ``` -To know how many tokens a prompt will consume, without actually processing it, developers can use the `measureInputUsage()` method. This method accepts the same input types as `prompt()`, including strings and multimodal input arrays: +To know how many tokens a prompt will consume, without actually processing it, developers can use the `measureContextUsage()` method. This method accepts the same input types as `prompt()`, including strings and multimodal input arrays: ```js -const stringUsage = await session.measureInputUsage(promptString); +const stringUsage = await session.measureContextUsage(promptString); -const audioUsage = await session.measureInputUsage([{ +const audioUsage = await session.measureContextUsage([{ role: "user", content: [ { type: "text", value: "My response to your critique:" }, @@ -601,10 +613,10 @@ Some notes on this API: * We do not expose the actual tokenization to developers since that would make it too easy to depend on model-specific details. * Implementations must include in their count any control tokens that will be necessary to process the prompt, e.g. ones indicating the start or end of the input. -* The counting process can be aborted by passing an `AbortSignal`, i.e. `session.measureInputUsage(promptString, { signal })`. -* We use the phrases "input usage" and "input quota" in the API, to avoid being specific to the current language model tokenization paradigm. In the future, even if we change paradigms, we anticipate some concept of usage and quota still being applicable, even if it's just string length. +* The counting process can be aborted by passing an `AbortSignal`, i.e. `session.measureContextUsage(promptString, { signal })`. +* We use the phrases "context usage" and "context window" in the API, to avoid being specific to the current language model tokenization paradigm. In the future, even if we change paradigms, we anticipate some concept of usage and quota still being applicable, even if it's just string length. -It's possible to send a prompt that causes the context window to overflow. That is, consider a case where `session.measureInputUsage(promptString) > session.inputQuota - session.inputUsage` before calling `session.prompt(promptString)`, and then the web developer calls `session.prompt(promptString)` anyway. In such cases, the initial portions of the conversation with the language model will be removed, one prompt/response pair at a time, until enough tokens are available to process the new prompt. The exception is the [system prompt](#system-prompts), which is never removed. +It's possible to send a prompt that causes the context window to overflow. That is, consider a case where `session.measureContextUsage(promptString) > session.contextWindow - session.contextUsage` before calling `session.prompt(promptString)`, and then the web developer calls `session.prompt(promptString)` anyway. In such cases, the initial portions of the conversation with the language model will be removed, one prompt/response pair at a time, until enough tokens are available to process the new prompt. The exception is the [system prompt](#system-prompts), which is never removed. Such overflows can be detected by listening for the `"quotaoverflow"` event on the session: @@ -617,7 +629,7 @@ session.addEventListener("quotaoverflow", () => { If it's not possible to remove enough tokens from the conversation history to process the new prompt, then the `prompt()` or `promptStreaming()` call will fail with a `QuotaExceededError` exception and nothing will be removed. This is a proposed new type of exception, which subclasses `DOMException`, and replaces the web platform's existing `"QuotaExceededError"` `DOMException`. See [whatwg/webidl#1465](https://github.com/whatwg/webidl/pull/1465) for this proposal. For our purposes, the important part is that it has the following properties: * `requested`: how many tokens the input consists of -* `quota`: how many tokens were available (which will be less than `requested`, and equal to the value of `session.inputQuota - session.inputUsage` at the time of the call) +* `quota`: how many tokens were available (which will be less than `requested`, and equal to the value of `session.contextWindow - session.contextUsage` at the time of the call) ### Multilingual content and expected input languages @@ -728,7 +740,7 @@ const options = { expectedInputs: [ { type: "text", languages: ["en", "es"] }, { type: "audio", languages: ["en", "es"] } - ], + ] }; const availability = await LanguageModel.availability(options); From 78f796e83947718eef1a1cf76cdea8c290d6a8c7 Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 14:55:36 -0800 Subject: [PATCH 2/7] Update formatting --- README.md | 33 +++++++++++++++++++-------------- index.bs | 12 ++++++++++++ 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 957c731..d5c6da1 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,9 @@ Both of these potential goals could pose challenges to interoperability, so we w ### API Updates: Deprecations and Renames -**Deprecated & Extension-Only:** +To improve API clarity, consistency, and address inconsistencies in parameter support across various models, the LanguageModel API has been updated. + +**Deprecated Features:** The following features of the LanguageModel API are **deprecated** and their functionality is now restricted to web extension contexts only: @@ -58,15 +60,18 @@ The following features of the LanguageModel API are **deprecated** and their fun These features may be completely removed in the future. This change is intended to simplify the API and address inconsistencies in parameter support across various models. -**Renamed Attributes/Methods:** +**Renamed Features:** -* `languageModel.inputUsage` is deprecated and renamed to **`languageModel.contextUsage`**. -* `languageModel.inputQuota` is deprecated and renamed to **`languageModel.contextWindow`**. -* `languageModel.measureInputUsage()` is deprecated and renamed to **`languageModel.measureContextUsage()`**. +The following features have been renamed. The old names are now deprecated and will only function as aliases within Chrome Extension contexts: -**Legacy Aliases (Extension-Only):** +| Old Name (Deprecated in Extensions, Removed in Web) | New Name (Available in All Contexts) | +| :-------------------------------------------------- | :----------------------------------- | +| `languageModel.inputUsage` | `languageModel.contextUsage` | +| `languageModel.inputQuota` | `languageModel.contextWindow` | +| `languageModel.measureInputUsage()` | `languageModel.measureContextUsage()` | +| `languagemodel.onquotaoverflow` | `languagemodel.oncontextwindowoverflow`. | -* The old names (`inputUsage`, `inputQuota`, `measureInputUsage`) are available as deprecated aliases for the new names, but **only within Chrome Extension contexts**. +**Note:** Developers using any of the deprecated names or features within an extension context will receive warnings in the DevTools Issues tab. These deprecated features and aliases may be completely removed in a future Chrome release. ## Examples @@ -441,7 +446,7 @@ analyzeButton.onclick = async (e) => { The promise returned by `append()` will reject if the prompt cannot be appended (e.g., too big, invalid modalities for the session, etc.), or will fulfill once the prompt has been validated, processed, and appended to the session. -Note that `append()` can also cause [overflow](#tokenization-context-window-length-limits-and-overflow), in which case it will evict the oldest non-system prompts from the session and fire the `"quotaoverflow"` event. +Note that `append()` can also cause [overflow](#tokenization-context-window-length-limits-and-overflow), in which case it will evict the oldest non-system prompts from the session and fire the `"contextoverflow"` event. ### Configuration of per-session parameters @@ -589,7 +594,7 @@ Finally, note that if either prompting or appending has caused an [overflow](#to ### Tokenization, context window length limits, and overflow -A given language model session will have a maximum number of tokens it can process. Developers can check their current usage and progress toward that limit by using the following properties on the session object: +A given language model session will have a maximum number of tokens it can process. Developers can check their current context usage and progress toward that limit by using the following properties on the session object: ```js console.log(`${session.contextUsage} tokens used, out of ${session.contextWindow} tokens available.`); @@ -614,22 +619,22 @@ Some notes on this API: * We do not expose the actual tokenization to developers since that would make it too easy to depend on model-specific details. * Implementations must include in their count any control tokens that will be necessary to process the prompt, e.g. ones indicating the start or end of the input. * The counting process can be aborted by passing an `AbortSignal`, i.e. `session.measureContextUsage(promptString, { signal })`. -* We use the phrases "context usage" and "context window" in the API, to avoid being specific to the current language model tokenization paradigm. In the future, even if we change paradigms, we anticipate some concept of usage and quota still being applicable, even if it's just string length. +* We use the phrases "context usage" and "context window" in the API, to avoid being specific to the current language model tokenization paradigm. In the future, even if we change paradigms, we anticipate some concept of usage and context window still being applicable, even if it's just string length. It's possible to send a prompt that causes the context window to overflow. That is, consider a case where `session.measureContextUsage(promptString) > session.contextWindow - session.contextUsage` before calling `session.prompt(promptString)`, and then the web developer calls `session.prompt(promptString)` anyway. In such cases, the initial portions of the conversation with the language model will be removed, one prompt/response pair at a time, until enough tokens are available to process the new prompt. The exception is the [system prompt](#system-prompts), which is never removed. -Such overflows can be detected by listening for the `"quotaoverflow"` event on the session: +Such overflows can be detected by listening for the `"contextoverflow"` event on the session: ```js -session.addEventListener("quotaoverflow", () => { - console.log("We've gone past the quota, and some inputs will be dropped!"); +session.addEventListener("contextoverflow", () => { + console.log("We've gone past the context window, and some inputs will be dropped!"); }); ``` If it's not possible to remove enough tokens from the conversation history to process the new prompt, then the `prompt()` or `promptStreaming()` call will fail with a `QuotaExceededError` exception and nothing will be removed. This is a proposed new type of exception, which subclasses `DOMException`, and replaces the web platform's existing `"QuotaExceededError"` `DOMException`. See [whatwg/webidl#1465](https://github.com/whatwg/webidl/pull/1465) for this proposal. For our purposes, the important part is that it has the following properties: * `requested`: how many tokens the input consists of -* `quota`: how many tokens were available (which will be less than `requested`, and equal to the value of `session.contextWindow - session.contextUsage` at the time of the call) +* `context window`: how many tokens were available (which will be less than `requested`, and equal to the value of `session.contextWindow - session.contextUsage` at the time of the call) ### Multilingual content and expected input languages diff --git a/index.bs b/index.bs index 68cd354..ab831e9 100644 --- a/index.bs +++ b/index.bs @@ -54,11 +54,23 @@ interface LanguageModel : EventTarget { optional LanguageModelAppendOptions options = {} ); + + Promise measureContextUsage( + LanguageModelPrompt input, + optional LanguageModelPromptOptions options = {} + ); + readonly attribute double contextUsage; + readonly attribute unrestricted double contextWindow; + attribute EventHandler oncontextwindowoverflow; + + // **DEPRECATED**: This method is only available in extension contexts. Promise measureInputUsage( LanguageModelPrompt input, optional LanguageModelPromptOptions options = {} ); + // **DEPRECATED**: This attribute is only available in extension contexts. readonly attribute double inputUsage; + // **DEPRECATED**: This attribute is only available in extension contexts. readonly attribute unrestricted double inputQuota; attribute EventHandler onquotaoverflow; From d10d777a80a3de0cdb38511503a2fc83eb957946 Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 14:56:15 -0800 Subject: [PATCH 3/7] Update formatting --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d5c6da1..73c26c8 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ The following are potential goals we are not yet certain of: Both of these potential goals could pose challenges to interoperability, so we want to investigate more how important such functionality is to developers to find the right tradeoff. -### API Updates: Deprecations and Renames +### API Updates: Deprecations and Renaming To improve API clarity, consistency, and address inconsistencies in parameter support across various models, the LanguageModel API has been updated. @@ -64,12 +64,12 @@ These features may be completely removed in the future. This change is intended The following features have been renamed. The old names are now deprecated and will only function as aliases within Chrome Extension contexts: -| Old Name (Deprecated in Extensions, Removed in Web) | New Name (Available in All Contexts) | -| :-------------------------------------------------- | :----------------------------------- | -| `languageModel.inputUsage` | `languageModel.contextUsage` | -| `languageModel.inputQuota` | `languageModel.contextWindow` | -| `languageModel.measureInputUsage()` | `languageModel.measureContextUsage()` | -| `languagemodel.onquotaoverflow` | `languagemodel.oncontextwindowoverflow`. | +| Old Name (Deprecated in Extensions, Removed in Web) | New Name (Available in All Contexts) | +| :-------------------------------------------------- | :----------------------------------------| +| `languageModel.inputUsage` | `languageModel.contextUsage` | +| `languageModel.inputQuota` | `languageModel.contextWindow` | +| `languageModel.measureInputUsage()` | `languageModel.measureContextUsage()` | +| `languagemodel.onquotaoverflow` | `languagemodel.oncontextwindowoverflow`. | **Note:** Developers using any of the deprecated names or features within an extension context will receive warnings in the DevTools Issues tab. These deprecated features and aliases may be completely removed in a future Chrome release. From 2c3cb6d18a7dfb01da8fca54f6106c38c916a14c Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 15:02:50 -0800 Subject: [PATCH 4/7] add onquotaoverflow deprecation comment to idl --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 73c26c8..3e5ebf3 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ The following features have been renamed. The old names are now deprecated and w | `languageModel.measureInputUsage()` | `languageModel.measureContextUsage()` | | `languagemodel.onquotaoverflow` | `languagemodel.oncontextwindowoverflow`. | -**Note:** Developers using any of the deprecated names or features within an extension context will receive warnings in the DevTools Issues tab. These deprecated features and aliases may be completely removed in a future Chrome release. +**Note:** Developers using any of the deprecated features within an extension context will receive warnings in the DevTools Issues tab. These deprecated features and aliases may be completely removed in a future Chrome release. ## Examples From cbbe538abcbc8402c5b70d04f6b10fa49053fc37 Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 15:10:39 -0800 Subject: [PATCH 5/7] add onquotaoverflow deprecation comment to idl --- index.bs | 1 + 1 file changed, 1 insertion(+) diff --git a/index.bs b/index.bs index ab831e9..3a2130a 100644 --- a/index.bs +++ b/index.bs @@ -72,6 +72,7 @@ interface LanguageModel : EventTarget { readonly attribute double inputUsage; // **DEPRECATED**: This attribute is only available in extension contexts. readonly attribute unrestricted double inputQuota; + // **DEPRECATED**: This attribute is only available in extension contexts. attribute EventHandler onquotaoverflow; // **DEPRECATED**: This attribute is only available in extension contexts. From fa3ad2ea81a1adec469a7186d6f52ae996cab22d Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 15:35:16 -0800 Subject: [PATCH 6/7] languagemodel.oncontextwindowoverflow should be languagemodel.oncontextoverflow --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 3a2130a..812520d 100644 --- a/index.bs +++ b/index.bs @@ -61,7 +61,7 @@ interface LanguageModel : EventTarget { ); readonly attribute double contextUsage; readonly attribute unrestricted double contextWindow; - attribute EventHandler oncontextwindowoverflow; + attribute EventHandler oncontextoverflow; // **DEPRECATED**: This method is only available in extension contexts. Promise measureInputUsage( From 43804306014d4c66d99fcee0450ff5761b1adf1f Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Fri, 20 Feb 2026 15:35:46 -0800 Subject: [PATCH 7/7] languagemodel.oncontextwindowoverflow should be languagemodel.oncontextoverflow --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e5ebf3..39427b6 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ The following features have been renamed. The old names are now deprecated and w | `languageModel.inputUsage` | `languageModel.contextUsage` | | `languageModel.inputQuota` | `languageModel.contextWindow` | | `languageModel.measureInputUsage()` | `languageModel.measureContextUsage()` | -| `languagemodel.onquotaoverflow` | `languagemodel.oncontextwindowoverflow`. | +| `languagemodel.onquotaoverflow` | `languagemodel.oncontextoverflow`. | **Note:** Developers using any of the deprecated features within an extension context will receive warnings in the DevTools Issues tab. These deprecated features and aliases may be completely removed in a future Chrome release.