modelpact 2.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Avdienko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,372 @@
+# modelpact
+
+[![npm](https://img.shields.io/npm/v/modelpact)](https://www.npmjs.com/package/modelpact)
+[![ci](https://github.com/AvdienkoSergey/modelpact/actions/workflows/ci.yml/badge.svg?event=pull_request)](https://github.com/AvdienkoSergey/modelpact/actions/workflows/ci.yml)
+![dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen)
+![min+gzip: 4.9 kB](https://img.shields.io/badge/min%2Bgzip-4.9%20kB-blue)
+![types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6)
+![node: ≥22](https://img.shields.io/badge/node-%E2%89%A522-339933)
+[![license: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
+
+**One way to talk to a local language model — the one built into the browser,
+Ollama on your machine, or a mock in your tests. Swap the backend, keep the
+code.**
+
+## Why you'd want it
+
+Chrome now ships a language model inside the browser. It runs on the user's
+device: free, offline, private, no API key. For a web app that is the best deal
+in AI — as long as your users are on Chrome.
+
+Everyone else needs a fallback, and every fallback speaks its own dialect. A
+different way to ask "are you available?", a different download story, different
+errors, a different streaming format. Support two backends and you maintain two
+integrations that share nothing.
+
+modelpact is one dialect for all of them.
+
+## What you get
+
+**Swap backends with one line.** The provider is the only place a backend is
+named. Everything after it is identical.
+
+```ts
+const provider = makePromptApiProvider(); // Chrome's built-in model
+const provider = makeOllamaProvider({ model: "granite4:350m" }); // …or a daemon
+const provider = makeMockProvider(); // …or nothing at all, in tests
+```
+
+**Failures that say what to do next.** No parsing exception names. Each failure
+is a plain word with the data you need to act on it: `context-overflow` comes
+with the usage so you can trim, `busy` tells you which call holds the session,
+`unsupported-input` says what was wrong with your message.
+
+**Bugs that don't compile.** You cannot open a session on a model that isn't
+there — the method doesn't exist on that branch. You cannot read an answer
+without handling the failure — the field isn't in the type. TypeScript catches
+it before your users do.
+
+**A conversation you can carry across a reload.** The session keeps the record:
+what you handed it, then every completed turn. It lives in memory for one tab,
+so storing it is yours — `localStorage`, IndexedDB, your server. Read it, store
+it, hand it back to `open`, and the conversation continues where it was. An
+aborted turn never gets in, so what you store is what the model actually saw.
+
+**Download progress for free.** The first time a browser model is used, hundreds
+of megabytes move. You get a progress event; your users get a bar instead of a
+frozen page.
+
+**Tests that need no GPU.** The mock provider is a first-class backend. Your
+suite runs on any CI box.
+
+**Bring your own backend and prove it.** Wrote an adapter for something else?
+Run it through the same conformance suite the built-in providers pass. If it's
+green, it behaves like the others — not "probably", provably.
+
+## See it before you install it
+
+[`demo/`](demo/) is one chat screen with a picker at the top. The picker holds
+six backends, and each of them was one line in
+[`demo/src/providers.ts`](demo/src/providers.ts) — nothing else on the screen
+knows which one is answering.
+
+```sh
+cd demo && npm install && npm run dev
+```
+
+| Pick                                   | What answers                                                         |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| `mock`, `mock-narrow`, `mock-download` | nothing: canned words, streamed one at a time, to stage every branch |
+| `ollama`                               | `granite4:350m` — 708 MB on your machine, offline once it is pulled  |
+| `prompt-api`                           | Chrome's built-in model, behind a consent button for its download    |
+| `webgpu`                               | `SmolLM2-360M` in the tab itself, from a package outside this repo   |
+
+<p align="center">
+  <img src="docs/screenshots/demo-overflow.png" width="49%" alt="The mock on a 60-token window: three turns in, the meter reads 140 / 60 and the overflow notice has fired once.">
+  <img src="docs/screenshots/demo-chrome.png" width="49%" alt="Chrome's built-in model with no weights on this machine yet: the chip says fetching weights, and the download waits for the button.">
+</p>
+
+Everything on that screen is one of the promises above: words arriving one at a
+time, a **Stop** that leaves the session open, the interrupted answer gone from
+the record, a meter, a chip per `AccessKind`, an overflow warning that fires
+once, a download bar that waits to be asked, and a conversation that survives a
+reload and stays in step across two tabs. Nine Playwright specs — one per
+promise, and one per real backend in the picker — drive it in Chromium and are
+the repo's whole browser suite.
+
+The last three rows are the point. A real model on a daemon, the browser's own
+model, and a model on WebGPU are not three integrations here. They are three
+entries in a registry, and the switch over that registry stays exhaustive — add
+a seventh and the build says where a sentence is missing.
+
+## The step, and what stands on it
+
+Talking to a model has three storeys. A transport reaches **one model**. A
+session holds **one conversation** with it and carries the guarantees — one
+generation at a time, an abort that leaves the session open, an overflow that
+fires once, a close that refuses everything after it. Above that, several
+models, a policy, a loop over turns: orchestration.
+
+modelpact is the middle storey, and it is deliberately only that.
+
+| Storey        | What lives there                      | Where                                                                                |
+| ------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| transport     | one model, four answers               | `ModelBackend` — three inside the package, two written outside it                    |
+| session       | one conversation, the guarantees      | **this package**, and nothing above it                                               |
+| orchestration | several models, a policy, a tool loop | [`external/orchestrator`](external/orchestrator), [`external/agent`](external/agent) |
+
+That is the direction this repo is developed in. The package does not grow up
+the stairs; what grows is what stands on it, and [`external/`](external/) is
+where that is tried — each package written the way a stranger would write it,
+against `modelpact` at `file:../..`, through the `exports` map, with no path into
+`src/`. Whatever the published API is not enough for shows up there first.
+
+**A transport from outside.** [`external/webgpu-provider`](external/webgpu-provider)
+is a model in the tab on WebGPU, through `@mlc-ai/web-llm`. It answers the same
+four questions, and `describeContract` runs against it: 34 green. It also found
+two real bugs — a published type that named a global consumers do not have, and a
+backend that errored its own stream and landed in `unknown` instead of `aborted`.
+Both fixed; both now have a guard. The demo depends on this package the way it
+would on anything from npm.
+
+**One storey up.** [`external/orchestrator`](external/orchestrator) puts Claude
+from `claude -p` and a local Ollama model in one conversation, with a policy
+deciding which side answers. Its first version was a `ModelBackend` composed of
+two — and it passed the suite while every guarantee leaked: a meter over two
+windows, an overflow that meant nothing for the other side. Rebuilt one storey
+up it needed **nothing new from the package**: `open({ history })` was already
+the door for handing a side the turns it missed. That is the test of whether a
+storey is right.
+
+**An agent, on the same storey.** [`external/agent`](external/agent) is a
+tool-calling loop over a `Brain` — two methods, `ask` and `record` — which is an
+`AiSession` or an orchestrator behind a two-line adapter. This contract has no
+tool protocol, and it did not need one: a tool call is a schema, honoured or
+refused and never ignored, and where a backend refuses (`claude -p` does,
+measured) the refusal picks prose mode rather than ending the run. A tool result
+goes back as the next user turn. The reference agent's shape survived; its
+`bash` tool and the hundred lines of path containment it needs did not.
+
+Three packages, three storeys, and the thing they share is fifteen exports and
+a test suite. Each export is there because something outside needed it; what is
+not there — storage, a router, a tool protocol, a third role — is not missing,
+it lives upstairs. The next transport is an afternoon and a green suite. The
+next policy or loop is a consumer, not a feature.
+
+## Quick start
+
+```sh
+npm install modelpact
+```
+
+```ts
+import { makeMockProvider } from "modelpact";
+
+const access = await makeMockProvider().access();
+if (access.kind !== "ready") return; // unavailable, or needs a download first
+
+const opened = await access.open({ system: "Answer in one sentence." });
+if (!opened.ok) return;
+
+const reply = await opened.value.prompt("What is this page about?");
+console.log(reply.ok ? reply.value : reply.error.kind);
+```
+
+Swap `makeMockProvider` for any other provider and nothing below it changes.
+That is the whole point of the line.
+
+> **What is in.** The contract, its type-level test, the lifecycle, the
+> conformance suite, and three backends — the mock, Ollama, and Chrome's
+> built-in model. Everything a backend needs is exported, and two more backends
+> plus an orchestrator and an agent have been written outside the package on
+> exactly that — see [The step, and what stands on it](#the-step-and-what-stands-on-it).
+
+### Bring your own backend
+
+A backend answers four questions. The lifecycle does the rest — one generation
+at a time, an abort that leaves the session open, an overflow that fires once, a
+close that refuses everything after it.
+
+```ts
+import { createProvider, ok, type ModelBackend } from "modelpact";
+
+const backend: ModelBackend = {
+  name: "echo",
+  modalities: ["text"],
+  availability: () => ({ kind: "ready" }),
+  connect: () => Promise.resolve(ok(model)), // your `generateStream`, `usage`, `dispose`
+};
+
+export const echo = createProvider(backend);
+```
+
+Then prove it behaves like the others:
+
+```ts
+import { describeContract } from "modelpact/testing";
+
+describeContract("echo", () => echo);
+```
+
+`modelpact/testing` needs `vitest`, which is an optional peer dependency: an app
+that only consumes a provider never loads it.
+
+### Several backends in one app
+
+The list of names belongs to the app, not to this package — a backend written
+elsewhere names itself. Your registry is where the set is known, so a switch over
+it stays exhaustive and a string out of storage cannot pretend to be a name.
+
+```ts
+import { defineProviders, findProviderName } from "modelpact";
+
+const PROVIDERS = defineProviders({ echo, mock: makeMockProvider() });
+
+const name = findProviderName(
+  PROVIDERS,
+  localStorage.getItem("provider") ?? "",
+);
+const provider = name === null ? null : PROVIDERS[name];
+```
+
+## Status
+
+**Versioned, and released by machine.** Semantic versioning from conventional
+commits: [release-please](https://github.com/googleapis/release-please) opens
+the release PR, [`CHANGELOG.md`](CHANGELOG.md) is written from the history, and
+the tagged tree is what `npm publish` builds, with provenance. A `!` in a commit
+is a major, and 2.0 was one — four public names changed for the better, and the
+changelog says which.
+
+**Small on purpose.** ESM only, zero runtime dependencies, and the whole entry
+is 13.6 kB minified, 4.9 kB gzipped, before tree-shaking takes the providers
+you do not import. `modelpact/testing` is a second entry with `vitest` as an
+optional peer, so an app that only consumes a provider never loads it.
+
+**Where it runs.** Node ≥ 22 for the Ollama backend and the suites; any current
+browser for a session over `fetch`; Chrome for the built-in model. The
+published declarations are checked by three outside packages with `skipLibCheck`
+off and `types: []` — if a `.d.ts` ever names a global you do not have, that
+build goes red before yours does.
+
+**What a pull request has to pass.** Typecheck, lint, format, the vitest suites,
+nine Playwright specs in Chromium, and the three packages under `external/` —
+their own tests and their surface guards — on every change, in one run.
+
+**Next.** An OpenAI-compatible HTTP backend: one transport for
+`/v1/chat/completions`, which is the cloud APIs, vLLM, LM Studio and a
+llama.cpp server at once. Same four answers, same suite.
+
+---
+
+## A Deep Dive for Techno-Geeks
+
+`@types/dom-chromium-ai` follows the IDL, and the IDL is looser than
+[the spec](docs/mdn/prompt_api/spec.md):
+several states the algorithm rejects at runtime are writable in the types. A TS
+error at the keyboard beats a `TypeError` in the browser, so
+[`patches/@types+dom-chromium-ai+0.0.17.patch`](patches/@types+dom-chromium-ai+0.0.17.patch) closes the gap.
+
+The patch is applied by `patch-package` on `prepare`, which runs for this repo
+and never for anyone installing the published package. `skipLibCheck` is
+deliberately **off** in `tsconfig.json`: these declarations are the only
+third-party ones in the project, and type-checking them is how a patch that
+stops applying cleanly gets caught.
+
+## The contract
+
+[`src/types`](src/types) is seven files and no runtime dependencies. Each holds one
+layer, and a fact lives on the type it is about: what a field means sits on the
+type rather than at every place it is read, so go-to-definition walks the
+reasoning instead of finding it restated.
+
+| File                                         | Holds                                                                             |
+| -------------------------------------------- | --------------------------------------------------------------------------------- |
+| [`foundations.ts`](src/types/foundations.ts) | `Result`, and the branded `Tokens`, `Fraction`, `JsonSchema`.                     |
+| [`messages.ts`](src/types/messages.ts)       | `AiMessage`, `Modality`, `ModelRequest`.                                          |
+| [`usage.ts`](src/types/usage.ts)             | `ContextUsage` — unknown, unbounded or bounded — and `UsageKind`.                 |
+| [`failures.ts`](src/types/failures.ts)       | `AiFailure` and `FailureKind`, the mapping `failureFromError`, `AiError`.         |
+| [`session.ts`](src/types/session.ts)         | `AiSession`, `ModelAccess` and `AccessKind`, `DownloadMonitor`, the option types. |
+| [`provider.ts`](src/types/provider.ts)       | `ProviderName`, `AiProvider`.                                                     |
+| [`backend.ts`](src/types/backend.ts)         | `ModelBackend`, `ModelConnection` — the four answers a provider supplies.         |
+
+Four ideas carry the rest:
+
+**Refusals are values.** `Result<T, AiFailure>` on the adapter boundary, so the
+failure path is in the signature and cannot be skipped in silence. Inside a
+provider's own implementation, exceptions are fine: `Result` spreads into every
+signature it touches, and only the boundary is worth that cost.
+
+**The failure vocabulary is cut by the caller's next move.** Not by exception
+name. Kinds merge where the reaction would be the same and split where it
+differs, even when the spec throws one exception for both — `unsupported-config`
+(wrong environment) and `unsupported-input` (wrong message) are one
+`NotSupportedError` upstream and two kinds here, because one is fixed by asking
+for less and the other by sending something else.
+
+**Mistakes are made unwritable, not guarded against.** `ModelAccess` carries
+`open` only on the variants where opening can work, so "create a session on an
+unavailable model" is not an error to check for at runtime — there is no
+expression for it.
+
+**A tag is a string, not an enum.** Every union here is discriminated by a
+`kind`, and `AccessKind`, `FailureKind` and `UsageKind` name those sets for a
+`Record` or a signature. They are derived aliases, so a new variant is in them
+already, and they stay types: `"ready"` still passes where one is asked for, and
+nothing of them reaches your bundle. An enum member would be a value, and a
+nominal one — your own `"ready"` would stop being assignable to ours.
+
+**A plain number is not a measurement.** `Tokens` and `Fraction` are separate
+brands over `number`, because a ratio and a percentage (0.5 against 50) are both
+numbers and swapping them is silent. A constructor that validates is the only way
+in.
+
+Four compiler flags beyond `strict` are load-bearing, `exactOptionalPropertyTypes`
+most of all: without it `{ system: undefined }` passes as `SessionOptions`, and
+every invariant that rests on an absent optional field falls apart.
+
+### The types have their own test
+
+[`src/types.test-d.ts`](src/types.test-d.ts) is compiled, never run. Every line
+that must **not** compile carries a `@ts-expect-error`, and TypeScript reports
+`TS2578: Unused '@ts-expect-error' directive` when the expected error fails to
+appear. So the file builds exactly while each listed state stays
+unrepresentable — loosen a type and the build breaks.
+
+It covers twelve of them:
+
+1. A session cannot be opened on an unavailable model
+2. A result cannot be used without handling the failure
+3. Each failure carries only its own fields
+4. An unbounded window cannot be subtracted from by accident
+5. A system turn cannot be smuggled into the history
+6. A schema is not just any object
+7. Availability is asked for a specific request
+8. The provider list is the app's, and switches over it stay exhaustive
+9. The stream stays a stream
+10. The monitor is the platform's, and ours passes for it
+11. A kind alias names the set without closing it to literals
+12. The record is a snapshot, not a handle
+
+It falls under the project tsconfig's `include`, so `npm run typecheck` checks
+it. Vitest deliberately misses it — `include` there is `*.test.ts`.
+
+## Contributing
+
+Conventional commits — release-please reads them — and a pull request against
+`main`; CI is the reviewer that has to say yes first. Everything it runs, runs
+locally:
+
+```sh
+npm ci
+npm run typecheck && npm run lint && npm run format:check && npm test
+npm run test:e2e            # Chromium; the demo server starts itself
+npm run external && npm run external:orchestrator && npm run external:agent
+```
+
+A backend is the most useful thing to bring. Four answers, `createProvider`,
+and `describeContract` green — see [Bring your own backend](#bring-your-own-backend).
+
+## License
+
+[MIT](LICENSE)

package/dist/helpers/abort.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The abort mechanics every provider shares: one session-wide signal mixed
+ * into every generation, so a close ends the in-flight calls and the later
+ * ones alike.
+ */
+import type { AiFailure } from "../types/failures.js";
+export declare function abortFailure(signal: AbortSignal): AiFailure;
+/**
+ * Skips `AbortSignal.any` when there is nothing to link: `any([s])` allocates
+ * a fresh signal and a listener on the original, for nothing. The `reason`
+ * survives either way — it propagates by identity, not by copy.
+ */
+export declare const linkSignals: (sessionSignal: AbortSignal, callerSignal?: AbortSignal) => AbortSignal;
+//# sourceMappingURL=abort.d.ts.map

package/dist/helpers/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/helpers/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAO3D;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,eAAe,WAAW,EAC1B,eAAe,WAAW,KACzB,WAGiD,CAAC"}

package/dist/helpers/abort.js

@@ -0,0 +1,22 @@
+/**
+ * The abort mechanics every provider shares: one session-wide signal mixed
+ * into every generation, so a close ends the in-flight calls and the later
+ * ones alike.
+ */
+export function abortFailure(signal) {
+    const reason = signal.reason;
+    return {
+        kind: "aborted",
+        reason: reason instanceof Error ? reason.message : String(reason),
+        cause: reason,
+    };
+}
+/**
+ * Skips `AbortSignal.any` when there is nothing to link: `any([s])` allocates
+ * a fresh signal and a listener on the original, for nothing. The `reason`
+ * survives either way — it propagates by identity, not by copy.
+ */
+export const linkSignals = (sessionSignal, callerSignal) => callerSignal === undefined
+    ? sessionSignal
+    : AbortSignal.any([sessionSignal, callerSignal]);
+//# sourceMappingURL=abort.js.map

package/dist/helpers/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/helpers/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC9C,MAAM,MAAM,GAAY,MAAM,CAAC,MAAM,CAAC;IACtC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACjE,KAAK,EAAE,MAAM;KACd,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,aAA0B,EAC1B,YAA0B,EACb,EAAE,CACf,YAAY,KAAK,SAAS;IACxB,CAAC,CAAC,aAAa;IACf,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC"}

package/dist/helpers/lifetime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A session is idle, generating, or closed: one cell, not three flags.
+ *
+ * A `running` name beside an `aborted` signal beside a `disposed` boolean lets
+ * every combination compile — closed but busy, a turn with no signal to end
+ * it, an `end()` from a turn abandoned two turns ago freeing the one running
+ * now. Here the phase is a union, the running phase carries the signal that
+ * ends it, and it is its own token: `end` compares identity, so a stale hook
+ * has nothing to free.
+ *
+ * Shared rather than written per provider, for the reason `overflow.ts` is
+ * shared: the contract suite would see each one refuse and never notice they
+ * refuse different things.
+ */
+import { type Result } from "../types/foundations.js";
+import type { AiFailure } from "../types/failures.js";
+/** The two contract calls that generate; `usage` and `close` never conflict. */
+export type GeneratingCall = "prompt" | "promptStream";
+/** Proof that the door was open: the only way to hold one is `begin` agreeing. */
+export interface RunningTurn {
+    readonly callName: GeneratingCall;
+    /** The session's own abort linked with the caller's; hand this to the backend. */
+    readonly signal: AbortSignal;
+}
+export interface SessionLifetime {
+    /** A running turn, or what this call owes the caller: `busy` while another runs, `aborted` once closed. */
+    readonly begin: (callName: GeneratingCall, signal?: AbortSignal) => Result<RunningTurn, AiFailure>;
+    /** Ignored unless `turn` is the one running, which is what keeps an abandoned turn from freeing its successor. */
+    readonly end: (turn: RunningTurn) => void;
+    /** `closed-now` once per session; the caller releases the model on that one. */
+    readonly close: () => "closed-now" | "already-closed";
+}
+export declare function createSessionLifetime(): SessionLifetime;
+//# sourceMappingURL=lifetime.d.ts.map

package/dist/helpers/lifetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifetime.d.ts","sourceRoot":"","sources":["../../src/helpers/lifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEvD,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAYD,MAAM,WAAW,eAAe;IAC9B,2GAA2G;IAC3G,QAAQ,CAAC,KAAK,EAAE,CACd,QAAQ,EAAE,cAAc,EACxB,MAAM,CAAC,EAAE,WAAW,KACjB,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACpC,kHAAkH;IAClH,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,YAAY,GAAG,gBAAgB,CAAC;CACvD;AAaD,wBAAgB,qBAAqB,IAAI,eAAe,CA2CvD"}

package/dist/helpers/lifetime.js

@@ -0,0 +1,71 @@
+/**
+ * A session is idle, generating, or closed: one cell, not three flags.
+ *
+ * A `running` name beside an `aborted` signal beside a `disposed` boolean lets
+ * every combination compile — closed but busy, a turn with no signal to end
+ * it, an `end()` from a turn abandoned two turns ago freeing the one running
+ * now. Here the phase is a union, the running phase carries the signal that
+ * ends it, and it is its own token: `end` compares identity, so a stale hook
+ * has nothing to free.
+ *
+ * Shared rather than written per provider, for the reason `overflow.ts` is
+ * shared: the contract suite would see each one refuse and never notice they
+ * refuse different things.
+ */
+import { err, ok } from "../types/foundations.js";
+import { abortFailure, linkSignals } from "./abort.js";
+/** No signal to read a reason from: closing is not an abort with a cause, it is the end of the session. */
+const CLOSED_FAILURE = {
+    kind: "aborted",
+    reason: "the session is closed",
+};
+const busyFailure = (callName) => ({
+    kind: "busy",
+    detail: `${callName} is already running on this session`,
+});
+export function createSessionLifetime() {
+    let phase = { kind: "idle" };
+    return {
+        begin: (callName, signal) => {
+            switch (phase.kind) {
+                case "closed":
+                    return err(CLOSED_FAILURE);
+                case "generating":
+                    return err(busyFailure(phase.turn.callName));
+                case "idle": {
+                    // The caller's own signal, not the linked one: its reason is the one
+                    // worth reporting, and linking an aborted signal only to read it back
+                    // is work for nothing.
+                    if (signal?.aborted === true)
+                        return err(abortFailure(signal));
+                    const abortController = new AbortController();
+                    const turn = {
+                        callName,
+                        signal: linkSignals(abortController.signal, signal),
+                    };
+                    phase = { kind: "generating", turn, abortController };
+                    return ok(turn);
+                }
+            }
+        },
+        end: (turn) => {
+            if (phase.kind !== "generating")
+                return;
+            if (phase.turn !== turn)
+                return;
+            phase = { kind: "idle" };
+        },
+        close: () => {
+            if (phase.kind === "closed")
+                return "already-closed";
+            // Moved before the abort: the listeners run synchronously, and one of
+            // them reaching back in must find a closed session rather than this one.
+            const previousPhase = phase;
+            phase = { kind: "closed" };
+            if (previousPhase.kind === "generating")
+                previousPhase.abortController.abort();
+            return "closed-now";
+        },
+    };
+}
+//# sourceMappingURL=lifetime.js.map

package/dist/helpers/lifetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifetime.js","sourceRoot":"","sources":["../../src/helpers/lifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAkCvD,2GAA2G;AAC3G,MAAM,cAAc,GAAc;IAChC,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,uBAAuB;CAChC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,QAAwB,EAAa,EAAE,CAAC,CAAC;IAC5D,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,GAAG,QAAQ,qCAAqC;CACzD,CAAC,CAAC;AAEH,MAAM,UAAU,qBAAqB;IACnC,IAAI,KAAK,GAAU,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAEpC,OAAO;QACL,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YAC1B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACnB,KAAK,QAAQ;oBACX,OAAO,GAAG,CAAC,cAAc,CAAC,CAAC;gBAC7B,KAAK,YAAY;oBACf,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAC/C,KAAK,MAAM,CAAC,CAAC,CAAC;oBACZ,qEAAqE;oBACrE,sEAAsE;oBACtE,uBAAuB;oBACvB,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI;wBAAE,OAAO,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;oBAC/D,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;oBAC9C,MAAM,IAAI,GAAG;wBACX,QAAQ;wBACR,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC;qBACpD,CAAC;oBACF,KAAK,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;oBACtD,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC;QACH,CAAC;QAED,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE;YACZ,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;gBAAE,OAAO;YACxC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO;YAChC,KAAK,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAC3B,CAAC;QAED,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,gBAAgB,CAAC;YACrD,sEAAsE;YACtE,yEAAyE;YACzE,MAAM,aAAa,GAAG,KAAK,CAAC;YAC5B,KAAK,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3B,IAAI,aAAa,CAAC,IAAI,KAAK,YAAY;gBACrC,aAAa,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YACxC,OAAO,YAAY,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/helpers/monitor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Download progress as the platform reports it: an `EventTarget` that fires
+ * `downloadprogress`.
+ *
+ * The Prompt API hands `create()` a `CreateMonitor` and fires a `ProgressEvent`
+ * on it. This is the same object for a provider with no browser behind it, and
+ * both satisfy `DownloadMonitor` from `../types/session.ts` —
+ * `src/types.test-d.ts` checks the ambient declaration against it.
+ *
+ * `ProgressEvent` is not a global in Node 22 — `typeof ProgressEvent` is
+ * `"undefined"` there, while `Event`, `EventTarget` and `CustomEvent` are
+ * present — and the vitest suites run in the node environment. So the event is
+ * a subclass of `Event` carrying the three `ProgressEvent` fields, which is
+ * what a listener reads. `CustomEvent` was the alternative and puts the numbers
+ * behind `detail`, where a listener written against the spec would not look.
+ */
+import type { Fraction } from "../types/foundations.js";
+import type { DownloadMonitor } from "../types/session.js";
+export declare const DOWNLOAD_PROGRESS = "downloadprogress";
+/**
+ * `total` is 1 and `loaded` is the ratio. MDN names the normalization on
+ * `ProgressEvent` itself ("if using 1 as a total, then loaded would be a
+ * decimal value between 0 and 1"), and it settles the one thing the Prompt API
+ * docs disagree about: `e.loaded / e.total` and a bare `e.loaded` are the same
+ * number here.
+ */
+export declare class DownloadProgressEvent extends Event {
+    readonly loaded: Fraction;
+    readonly lengthComputable = true;
+    readonly total = 1;
+    constructor(loaded: Fraction);
+}
+/**
+ * Our `CreateMonitor`. `report` is not part of `DownloadMonitor`, so a caller
+ * holding the contract type can listen but cannot invent progress —
+ * `src/types.test-d.ts` checks that it cannot.
+ */
+export declare class ProgressMonitor extends EventTarget implements DownloadMonitor {
+    #private;
+    /**
+     * An `onevent` property is not free with `EventTarget`: only interfaces the
+     * platform defines have one, and it is a listener registration behind an
+     * accessor — assigning twice replaces, assigning null unsubscribes. Here it
+     * also carries the event's type, which `addEventListener` cannot: see the
+     * note on `DownloadMonitor`.
+     */
+    get ondownloadprogress(): ((event: ProgressEvent) => void) | null;
+    set ondownloadprogress(handler: ((event: ProgressEvent) => void) | null);
+    /** Dropped rather than dispatched when it does not move forward — the contract's non-decreasing guarantee. */
+    report(loaded: Fraction): void;
+}
+//# sourceMappingURL=monitor.d.ts.map

package/dist/helpers/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../src/helpers/monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAIlC,QAAQ,CAAC,MAAM,EAAE,QAAQ;IAHrC,QAAQ,CAAC,gBAAgB,QAAQ;IACjC,QAAQ,CAAC,KAAK,KAAK;gBAEE,MAAM,EAAE,QAAQ;CAGtC;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,WAAY,YAAW,eAAe;;IAIzE;;;;;;OAMG;IACH,IAAI,kBAAkB,IAAI,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAEhE;IAED,IAAI,kBAAkB,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,EAWtE;IAED,8GAA8G;IAC9G,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;CAK/B"}