akarisp 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,204 @@
+# AkariSP
+
+A small runtime for browser-native LLM sessions (Chrome's Prompt API). It keeps one warm
+**base session** and runs each task in its own **clone**, so repeated tasks don't pay session
+creation every time and never share conversational context.
+
+The same runtime also drives an application-created [WebLLM](#webllm) engine through
+`akarisp/webllm`.
+
+Zero runtime dependencies. No framework, no agent abstraction.
+
+## Install
+
+```bash
+npm install akarisp@alpha
+```
+
+The first release, `0.1.0-alpha.0`, is published under the `alpha` dist-tag. A plain
+`npm install akarisp` installs the `latest` tag, which will exist only after a stable release.
+
+## Usage
+
+```js
+import { createRuntime, TaskError } from 'akarisp';
+
+const runtime = await createRuntime({
+  session: { initialPrompts: [{ role: 'system', content: 'Answer in one sentence.' }] },
+  limit: 1,          // absolute cap on running tasks (default 1)
+  queueCapacity: 32, // waiting tasks beyond the limit (default 32); overflow is rejected
+});
+
+try {
+  const { output, timing } = await runtime.run('What is HTTP?', {
+    signal: AbortSignal.timeout(10_000),
+  });
+  console.log(output, timing); // { queueWait, acquire, prompt, total } in ms
+} catch (e) {
+  if (e instanceof TaskError) {
+    // e.code: 'failed' | 'cancelled' | 'rejected' | 'closed' | 'broken'
+    // e.cause: original error or abort reason; e.timing: phases completed so far
+  }
+}
+
+await runtime.shutdown(); // cancels running tasks, rejects waiting ones, destroys all sessions
+```
+
+Each `run()` clones the base, prompts the clone, and destroys it. The task's promise settles
+only after its session is destroyed and its slot released.
+
+## Streaming
+
+```js
+const stream = runtime.stream('Explain HTTP in two sentences.', {
+  signal: AbortSignal.timeout(10_000),
+});
+for await (const chunk of stream) {
+  output.textContent += chunk;
+  if (userClickedStop) break; // clone destroyed and slot released before the loop exits
+}
+console.log(stream.timing); // final TaskTiming; undefined until the stream has fully ended
+```
+
+- Same limit, queue, cancellation, broken, and shutdown rules as `run()`; both share one queue.
+- Lazy: nothing is queued or cloned until the first pull, so an unused stream costs nothing.
+- Single use: iterating the same stream twice throws `TypeError`.
+- `timing.prompt` runs until the loop sees the model's end; because chunks are pulled, it includes
+  the time your loop body spends on each chunk.
+- `break` is not an error. Cancellation, timeout, model failure, and shutdown end the loop with a
+  `TaskError`, and cleanup happens even if you have stopped pulling chunks.
+
+## Templates
+
+One runtime can hold a small fixed set of named warm base sessions and clone the one each task
+names:
+
+```js
+const runtime = await createRuntime({
+  session: { initialPrompts: [{ role: 'system', content: 'General assistant.' }] }, // optional default
+  templates: {
+    momentum: { initialPrompts: [{ role: 'system', content: 'You analyze momentum.' }] },
+    risk: { initialPrompts: [{ role: 'system', content: 'You analyze risk.' }] },
+  },
+  limit: 2,
+});
+
+await runtime.run(text, { template: 'momentum' });
+for await (const chunk of runtime.stream(text, { template: 'risk' })) render(chunk);
+await runtime.run(text); // uses the default `session` template
+```
+
+- Each template value is passed to `LanguageModel.create()`; the runtime creates and owns every base.
+- With `session`, omitting `template` uses it. With only `templates`, you must name one; otherwise
+  `run()` rejects and `stream()`'s first pull throws `TypeError`. Unknown names throw `TypeError`.
+  Neither consumes a queue entry or slot.
+- All templates share one `limit` and one queue. A clone failure that breaks any base makes the whole
+  runtime `broken`. `shutdown()` destroys every base.
+
+## Snapshot
+
+```js
+const { state, active, queued, limit, queueCapacity } = runtime.snapshot();
+```
+
+Synchronous and read-only: it never waits, admits, cancels, or changes anything, and each call
+returns a fresh plain object. `active` counts tasks holding a concurrency slot, including a task
+whose session is still being destroyed; `queued` counts tasks waiting for a slot (a stream counts
+only after its first pull). After `await runtime.shutdown()` it reports `closed` with `0/0`.
+
+## States
+
+- `ready`: accepts tasks.
+- `broken`: the provider's resource can no longer be trusted for new tasks. With the Prompt
+  API, this means a clone failed with `InvalidStateError`. For WebLLM, see [WebLLM](#webllm). Waiting and new tasks are rejected; tasks already holding a clone finish normally.
+  Create a new runtime.
+- `closed`: after `shutdown()`. `shutdown()` is idempotent and never rejects.
+
+## Performance
+
+AkariSP **amortizes** session initialization across repeated tasks; it does not eliminate it.
+The base session is created once (`createRuntime`), after which each task pays a clone instead
+of a full `LanguageModel.create()`. Measure it on your device with the benchmark in
+[bench/README.md](bench/README.md).
+
+## WebLLM
+
+```js
+import { CreateMLCEngine } from '@mlc-ai/web-llm'; // your dependency, not AkariSP's
+import { createWebLLMRuntime } from 'akarisp/webllm';
+
+const engine = await CreateMLCEngine('Qwen2.5-0.5B-Instruct-q4f16_1-MLC'); // you load the model
+const runtime = await createWebLLMRuntime(engine, {
+  session: { initialPrompts: [{ role: 'system', content: 'Answer in one sentence.' }], temperature: 0 },
+});
+const { output } = await runtime.run('What is HTTP?');
+await runtime.shutdown(); // also unloads the engine
+```
+
+The returned runtime is the same `Runtime`: `run`, `stream`, `snapshot`, `shutdown`, templates,
+`TaskError` codes, and timing behave as above. What differs:
+
+- **Engine**: your application creates the engine and loads the model. AkariSP never
+  downloads a model and does not depend on `@mlc-ai/web-llm`.
+- **Ownership**: once `createWebLLMRuntime` resolves, the runtime uses the engine exclusively
+  (run nothing else on it), and `shutdown()` unloads it after every task's cleanup. If creation
+  rejects, the engine is untouched.
+- **`limit` must be 1**: one engine generates one request at a time. `limit > 1` throws
+  `TypeError`. Extra tasks wait in AkariSP's queue, where cancelling one never affects another.
+- **Templates** are request configuration: `initialPrompts` plus request settings such as
+  `temperature`, all on the one engine. No per-template resource is created.
+- **Tasks**: each task is one streaming request, also for `run()`. Cancellation, timeout,
+  `break`, and shutdown interrupt the generation and drain it before the slot is released, so
+  the next task starts cleanly.
+- **`broken`**: the engine was unloaded or lost when a task started (`ModelNotLoadedError`,
+  `DeviceLostError`). Create a new engine and runtime.
+- **Validated**: with `@mlc-ai/web-llm` 0.2.85 and Qwen2.5-0.5B-Instruct in Chrome with WebGPU
+  ([smoke/README.md](smoke/README.md)). Other WebLLM versions are unverified.
+- **Types**: a `MLCEngine`, `WebWorkerMLCEngine`, or `MLCEngineInterface` is accepted without
+  a cast. This is verified with TypeScript `moduleResolution: "bundler"`. WebLLM 0.2.85's own
+  declarations do not resolve under `node16`/`nodenext`, where its types become `any`.
+
+## Package
+
+- Entry points: `akarisp` (`createRuntime`, `TaskError`, and the types `Runtime`,
+  `RuntimeOptions`, `RuntimeSnapshot`, `TaskStream`, `TaskResult`, `TaskTiming`) and
+  `akarisp/webllm` (`createWebLLMRuntime`). No other path is importable.
+- ESM only. On Node 23.9, `require('akarisp')` also returns the same exports through Node's
+  `require(esm)`; the package ships no CommonJS build.
+- TypeScript declarations are included and verified with `moduleResolution` `bundler`,
+  `node16`, and `nodenext`.
+- Zero runtime dependencies.
+
+## Development
+
+Requires Node ≥ 22.18 (the test runner loads TypeScript directly). This is a development
+requirement only; the package itself runs in browsers.
+
+```bash
+npm test       # node:test: core, browser and WebLLM adapters, boundary, packed-tarball consumer
+npm run build  # tsc → dist/
+npm run test:browser  # Playwright: compatibility page on Chromium / Firefox / WebKit engines
+```
+
+### Browser compatibility
+
+AkariSP's browser integration uses the Prompt API exposed by the current browser. Importing
+AkariSP is safe in any browser, but that does not mean the browser can run a local model, and
+AkariSP cannot make the Prompt API available where the browser does not provide it. Use the
+compatibility harness ([smoke/README.md](smoke/README.md)) to inspect the capabilities and
+lifecycle behavior of a specific browser and version.
+
+Source layout: `src/core/` is the provider-neutral runtime (no browser globals);
+`src/browser/` maps it to the Prompt API's `LanguageModel`; `src/webllm/` maps it to an
+injected WebLLM engine; `src/index.ts` and `src/webllm.ts` are the two public entries.
+
+### Public API snapshot
+
+`api/akarisp.api.txt` records the public surface of the packed package. `npm test` fails if the
+surface changes. After an intentional public API change, run `UPDATE_API=1 npm test` and review
+the diff.
+
+### Release
+
+`npm publish` uses `publishConfig.tag` (`alpha`), so a pre-release never lands on `latest` by
+accident. `prepack` rebuilds `dist/` first.

package/dist/browser/runtime.d.ts

@@ -0,0 +1,4 @@
+import { type Runtime, type RuntimeOptions } from '../core/runtime.ts';
+/** Create a runtime backed by the browser's built-in Prompt API. The native global is read
+ *  only when a base session is created. */
+export declare function createRuntime(options?: RuntimeOptions): Promise<Runtime>;

package/dist/browser/runtime.js

@@ -0,0 +1,15 @@
+import { createCoreRuntime } from "../core/runtime.js";
+// Owns one warm session per template (destroy) and nothing provider-wide, so no close().
+const promptApi = {
+    create: (config) => LanguageModel.create(config),
+    start: (base, options) => base.clone(options),
+    // ponytail: InvalidStateError = base no longer trusted (005 research R2); revisit if the
+    // Prompt API spec defines destroyed-session errors differently.
+    broken: (e) => e instanceof DOMException && e.name === 'InvalidStateError',
+    destroy: (base) => base.destroy(),
+};
+/** Create a runtime backed by the browser's built-in Prompt API. The native global is read
+ *  only when a base session is created. */
+export function createRuntime(options) {
+    return createCoreRuntime(promptApi, options);
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,85 @@
+export interface Session {
+    prompt(input: Prompt, options: {
+        signal: AbortSignal;
+    }): Promise<string>;
+    promptStreaming(input: Prompt, options: {
+        signal: AbortSignal;
+    }): AsyncIterable<string>;
+    destroy(): void | Promise<void>;
+}
+export interface SessionProvider<B> {
+    create(config?: object): Promise<B>;
+    start(base: B, options: {
+        signal: AbortSignal;
+    }): Promise<Session>;
+    /** Consulted only when start() rejects and the task was not aborted: true = runtime broken. */
+    broken(error: unknown): boolean;
+    /** Per-template resource cleanup. */
+    destroy?(base: B): void | Promise<void>;
+    /** Provider-wide resource cleanup; shutdown only, after every destroy(base). */
+    close?(): void | Promise<void>;
+}
+type Prompt = string | readonly object[];
+export interface RuntimeOptions {
+    /** Passed unchanged to the session provider's create() for the unnamed default template. */
+    session?: object;
+    /** Named templates: name → options passed unchanged to the session provider's create(). Fixed for the
+     *  runtime's lifetime. If given without `session`, there is no default template. */
+    templates?: Record<string, object>;
+    /** Absolute cap on running tasks (slot acquire → start task session → prompt → destroy → release).
+     *  Integer ≥ 1. Default 1. */
+    limit?: number;
+    /** Max waiting tasks. Finite integer ≥ 0. Default 32.
+     *  When limit is reached and the queue is full, run() rejects. */
+    queueCapacity?: number;
+}
+export interface Runtime {
+    readonly state: 'ready' | 'broken' | 'closed';
+    /** Start a task session from the template's base → prompt → destroy the task session. */
+    run(input: Prompt, options?: {
+        signal?: AbortSignal;
+        template?: string;
+    }): Promise<TaskResult>;
+    /** Same lifecycle as run(), output as chunks. Lazy: nothing is admitted until the first
+     *  pull. Single-use. Leaving the loop early destroys the task session before the loop exits. */
+    stream(input: Prompt, options?: {
+        signal?: AbortSignal;
+        template?: string;
+    }): TaskStream;
+    /** Synchronous, read-only view of current state. Never waits, never changes anything. */
+    snapshot(): RuntimeSnapshot;
+    /** Reject waiters, cancel running tasks, destroy all sessions. Idempotent and safe to
+     *  call concurrently; never rejects. Resolves only after all cleanup is done. */
+    shutdown(): Promise<void>;
+}
+export interface RuntimeSnapshot {
+    readonly state: Runtime['state'];
+    /** Tasks holding a concurrency slot (task session started → prompt → task session destroyed). */
+    readonly active: number;
+    /** Tasks waiting for a slot. */
+    readonly queued: number;
+    readonly limit: number;
+    readonly queueCapacity: number;
+}
+export interface TaskStream extends AsyncIterable<string> {
+    /** undefined until the task has ended and its resources are cleaned up. */
+    readonly timing: TaskTiming | undefined;
+}
+export interface TaskResult {
+    output: string;
+    timing: TaskTiming;
+}
+/** Milliseconds. A field is set only if its phase completed; total is always set. */
+export interface TaskTiming {
+    queueWait?: number;
+    acquire?: number;
+    prompt?: number;
+    total: number;
+}
+export declare class TaskError extends Error {
+    readonly code: 'failed' | 'cancelled' | 'rejected' | 'closed' | 'broken';
+    readonly timing: TaskTiming;
+    constructor(code: TaskError['code'], timing: TaskTiming, cause?: unknown);
+}
+export declare function createCoreRuntime<B>(provider: SessionProvider<B>, options?: RuntimeOptions): Promise<Runtime>;
+export {};

package/dist/core/runtime.js

@@ -0,0 +1,245 @@
+export class TaskError extends Error {
+    code;
+    timing;
+    constructor(code, timing, cause) {
+        super(`Task ${code}`, { cause });
+        this.name = 'TaskError';
+        this.code = code;
+        this.timing = timing;
+    }
+}
+export async function createCoreRuntime(provider, options = {}) {
+    const { session, templates, limit = 1, queueCapacity = 32 } = options;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new TypeError('limit must be an integer >= 1');
+    if (!Number.isInteger(queueCapacity) || queueCapacity < 0) {
+        throw new TypeError('queueCapacity must be a finite integer >= 0');
+    }
+    if (templates && Object.keys(templates).length === 0 && session === undefined) {
+        throw new TypeError('templates is empty and no session was given');
+    }
+    // One warm base per template; key undefined = unnamed default. Fixed after creation.
+    const bases = new Map();
+    try {
+        // ponytail: sequential creation scales startup with template count; use Promise.allSettled
+        // if startup latency matters.
+        if (templates === undefined || session !== undefined)
+            bases.set(undefined, await provider.create(session));
+        for (const [name, config] of Object.entries(templates ?? {}))
+            bases.set(name, await provider.create(config));
+    }
+    catch (e) {
+        // No close(): provider-wide resources are owned only once creation succeeds.
+        for (const b of bases.values())
+            try {
+                await provider.destroy?.(b);
+            }
+            catch { }
+        throw e;
+    }
+    const pick = (template) => {
+        const base = bases.get(template);
+        if (base)
+            return base;
+        throw new TypeError(template === undefined
+            ? 'template is required: this runtime has no default session'
+            : `unknown template "${template}"`);
+    };
+    let state = 'ready';
+    const closer = new AbortController();
+    let running = 0;
+    const queue = [];
+    let closing;
+    let idle;
+    const drain = (code) => {
+        while (queue.length)
+            queue.shift()(code);
+    };
+    // Called only after the task session is destroyed, so `limit` also caps live task sessions.
+    const release = () => {
+        running--;
+        if (state === 'ready' && queue.length) {
+            running++;
+            queue.shift()();
+        }
+        if (running === 0)
+            idle?.();
+    };
+    // --- Task lifecycle shared by run() and stream() --------------------------------------
+    // State and pre-abort checks, then a slot now or a FIFO wait. Sets `total` on its errors.
+    const admit = async (signal) => {
+        const t0 = performance.now();
+        const timing = { total: 0 };
+        const fail = (code, cause) => {
+            timing.total = performance.now() - t0;
+            return new TaskError(code, timing, cause);
+        };
+        if (state !== 'ready')
+            throw fail(state);
+        if (signal?.aborted)
+            throw fail('cancelled', signal.reason);
+        if (running < limit) {
+            running++;
+            timing.queueWait = 0;
+        }
+        else if (queue.length < queueCapacity) {
+            await new Promise((resolve, reject) => {
+                const leave = (code, cause) => {
+                    signal?.removeEventListener('abort', onAbort);
+                    timing.queueWait = performance.now() - t0;
+                    code ? reject(fail(code, cause)) : resolve();
+                };
+                const onAbort = () => {
+                    queue.splice(queue.indexOf(leave), 1);
+                    leave('cancelled', signal.reason);
+                };
+                signal?.addEventListener('abort', onAbort, { once: true });
+                queue.push(leave);
+            });
+        }
+        else {
+            throw fail('rejected');
+        }
+        // Now a running task holding a slot; the caller must end() it.
+        const sig = signal ? AbortSignal.any([signal, closer.signal]) : closer.signal;
+        return { t0, timing, sig };
+    };
+    // Errors thrown while running leave `total` to end().
+    const failure = (sig, timing, e) => sig.aborted ? new TaskError('cancelled', timing, sig.reason) : new TaskError('failed', timing, e);
+    const acquire = async (base, sig, timing) => {
+        if (sig.aborted)
+            throw new TaskError('cancelled', timing, sig.reason);
+        if (state === 'broken')
+            throw new TaskError('broken', timing); // broke while this task waited
+        const t1 = performance.now();
+        let task;
+        try {
+            task = await provider.start(base, { signal: sig });
+        }
+        catch (e) {
+            if (!sig.aborted && provider.broken(e)) {
+                if (state === 'ready') {
+                    state = 'broken';
+                    drain('broken');
+                }
+                throw new TaskError('broken', timing, e);
+            }
+            throw failure(sig, timing, e);
+        }
+        timing.acquire = performance.now() - t1;
+        return task; // caller owns it before checking sig.aborted, so end() destroys a late task
+    };
+    // Destroy → release slot → total. Runs before the task's outcome settles (FR-009b).
+    // A synchronous destroy() keeps the whole step synchronous (002: timing is published in the
+    // same turn as a paused consumer's abort); a returned promise is awaited, rejection swallowed.
+    const end = (task, t0, timing) => {
+        const done = () => {
+            release();
+            timing.total = performance.now() - t0;
+        };
+        let pending = undefined;
+        try {
+            pending = task?.destroy();
+        }
+        catch { }
+        if (pending)
+            return pending.then(done, done);
+        done();
+    };
+    return {
+        get state() { return state; },
+        snapshot: () => ({ state, active: running, queued: queue.length, limit, queueCapacity }),
+        async run(input, { signal, template } = {}) {
+            const base = pick(template); // before admission: a bad template consumes nothing
+            const { t0, timing, sig } = await admit(signal);
+            let task;
+            try {
+                task = await acquire(base, sig, timing);
+                if (sig.aborted)
+                    throw new TaskError('cancelled', timing, sig.reason);
+                const t2 = performance.now();
+                const output = await task.prompt(input, { signal: sig }).catch((e) => { throw failure(sig, timing, e); });
+                timing.prompt = performance.now() - t2;
+                return { output, timing };
+            }
+            finally {
+                const pending = end(task, t0, timing);
+                if (pending)
+                    await pending;
+            }
+        },
+        stream(input, { signal, template } = {}) {
+            let used = false;
+            const s = {
+                timing: undefined,
+                // Async generator: nothing runs before the first pull (lazy), and `break`/return()
+                // runs `finally` and cancels the provider stream before the loop exit completes.
+                async *[Symbol.asyncIterator]() {
+                    if (used)
+                        throw new TypeError('stream already consumed');
+                    used = true;
+                    const base = pick(template); // first pull, before admission
+                    const { t0, timing, sig } = await admit(signal).catch((e) => {
+                        s.timing = e.timing;
+                        throw e;
+                    });
+                    let task;
+                    let onAbort; // declared before cleanup, which reads it
+                    let cleaning;
+                    // Single-flight: every caller awaits the same cleanup.
+                    const cleanup = () => (cleaning ??= (async () => {
+                        if (onAbort)
+                            sig.removeEventListener('abort', onAbort);
+                        const pending = end(task, t0, timing);
+                        if (pending)
+                            await pending;
+                        s.timing = timing;
+                    })());
+                    try {
+                        task = await acquire(base, sig, timing);
+                        if (sig.aborted)
+                            throw new TaskError('cancelled', timing, sig.reason);
+                        // The consumer may stop pulling while paused at `yield`; clean up on abort anyway.
+                        onAbort = () => void cleanup();
+                        sig.addEventListener('abort', onAbort, { once: true });
+                        const t2 = performance.now();
+                        try {
+                            for await (const chunk of task.promptStreaming(input, { signal: sig })) {
+                                yield chunk;
+                                if (sig.aborted)
+                                    throw sig.reason; // resumed after abort; mapped below
+                            }
+                        }
+                        catch (e) {
+                            throw failure(sig, timing, e);
+                        }
+                        timing.prompt = performance.now() - t2;
+                    }
+                    finally {
+                        await cleanup();
+                    }
+                },
+            };
+            return s;
+        },
+        shutdown() {
+            // Stored synchronously, so repeated and concurrent calls share one cleanup.
+            return (closing ??= (async () => {
+                state = 'closed';
+                drain('closed');
+                closer.abort(new DOMException('Runtime closed', 'AbortError'));
+                if (running)
+                    await new Promise((resolve) => { idle = resolve; });
+                for (const b of bases.values())
+                    try {
+                        await provider.destroy?.(b);
+                    }
+                    catch { }
+                try {
+                    await provider.close?.();
+                }
+                catch { }
+            })());
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createRuntime } from './browser/runtime.ts';
+export { TaskError } from './core/runtime.ts';
+export type { RuntimeOptions, Runtime, RuntimeSnapshot, TaskStream, TaskResult, TaskTiming } from './core/runtime.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createRuntime } from "./browser/runtime.js";
+export { TaskError } from "./core/runtime.js";

package/dist/webllm/runtime.d.ts

@@ -0,0 +1,27 @@
+import { type Runtime, type RuntimeOptions } from '../core/runtime.ts';
+type Chunk = {
+    choices: {
+        delta?: {
+            content?: string | null;
+        };
+    }[];
+};
+/** The subset of a WebLLM MLCEngine this module uses. */
+export interface WebLLMEngine {
+    chat: {
+        completions: {
+            create(request: object): Promise<AsyncIterable<Chunk>>;
+        };
+    };
+    interruptGenerate(): void | Promise<void>;
+    getMessage(): Promise<string>;
+    unload(): Promise<void>;
+}
+/** Create a runtime on an application-created WebLLM engine.
+ *
+ *  Ownership: once this resolves, the runtime uses the engine exclusively (do not run other
+ *  generations on it) and unloads it at shutdown. If creation fails, the engine is untouched.
+ *  `limit` must be 1: one engine generates one request at a time, and waiting tasks must stay in
+ *  AkariSP's queue where cancellation is task-local (007 research E3, E4). */
+export declare function createWebLLMRuntime(engine: WebLLMEngine, options?: RuntimeOptions): Promise<Runtime>;
+export {};

package/dist/webllm/runtime.js

@@ -0,0 +1,80 @@
+import { createCoreRuntime } from "../core/runtime.js";
+/** Create a runtime on an application-created WebLLM engine.
+ *
+ *  Ownership: once this resolves, the runtime uses the engine exclusively (do not run other
+ *  generations on it) and unloads it at shutdown. If creation fails, the engine is untouched.
+ *  `limit` must be 1: one engine generates one request at a time, and waiting tasks must stay in
+ *  AkariSP's queue where cancellation is task-local (007 research E3, E4). */
+export async function createWebLLMRuntime(engine, options = {}) {
+    if (options.limit !== undefined && options.limit > 1) {
+        throw new TypeError('limit must be 1 for a WebLLM engine (one generation at a time)');
+    }
+    // A template is request configuration, so no destroy(base); the engine is the one
+    // provider-wide resource, so close() unloads it.
+    const provider = {
+        create: async (config = {}) => config,
+        start: async (base) => {
+            await engine.getMessage(); // throws ModelNotLoadedError once the engine is unloaded
+            return task(engine, base);
+        },
+        broken: (e) => ['ModelNotLoadedError', 'DeviceLostError'].includes(e?.name),
+        close: () => engine.unload(),
+    };
+    return createCoreRuntime(provider, options);
+}
+function task(engine, base) {
+    const { initialPrompts = [], ...settings } = base;
+    let it;
+    let pulled = false;
+    let done = false;
+    // Always streaming, also for prompt(): a non-streaming request after an interrupt returns ""
+    // in 0.2.85 (E5), while a streaming request resets the interrupt flag.
+    async function* promptStreaming(input, { signal }) {
+        const onAbort = () => void engine.interruptGenerate();
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            const messages = [...initialPrompts, ...(typeof input === 'string' ? [{ role: 'user', content: input }] : input)];
+            it = (await engine.chat.completions.create({ ...settings, messages, stream: true }))[Symbol.asyncIterator]();
+            // ponytail: manual next(), never for-await over `it`: leaving a for-await calls it.return(),
+            // which leaks the engine lock in 0.2.85 (E6). Switch once a release frees it in finally.
+            while (!signal.aborted) {
+                pulled = true;
+                const r = await it.next();
+                if (r.done) {
+                    done = true;
+                    break;
+                }
+                const text = r.value.choices[0]?.delta?.content;
+                if (text)
+                    yield text;
+            }
+            if (signal.aborted)
+                throw signal.reason; // an interrupted generation ends without an error (E8)
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+    return {
+        promptStreaming,
+        async prompt(input, options) {
+            let output = '';
+            for await (const chunk of promptStreaming(input, options))
+                output += chunk;
+            return output;
+        },
+        // Interrupt and drain to the natural end: the only way 0.2.85 releases its lock (E6b).
+        // Called once per task by the core's end().
+        async destroy() {
+            if (!it || done)
+                return;
+            // ponytail: 0.2.85 resets the interrupt flag on the first next(), so an interrupt before it
+            // is lost; pulling first costs up to one time-to-first-token of cleanup latency.
+            if (!pulled && (await it.next()).done)
+                return;
+            await engine.interruptGenerate();
+            while (!(await it.next()).done)
+                ;
+        },
+    };
+}

package/dist/webllm.d.ts

@@ -0,0 +1 @@
+export { createWebLLMRuntime } from './webllm/runtime.ts';

package/dist/webllm.js

@@ -0,0 +1 @@
+export { createWebLLMRuntime } from "./webllm/runtime.js";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "akarisp",
+  "version": "0.1.0-alpha.0",
+  "description": "Lightweight lifecycle runtime for browser LLM sessions: bounded queue, cancellation, and deterministic cleanup for the Chrome Prompt API and WebLLM",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drow724/akariSP.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webllm": {
+      "types": "./dist/webllm.d.ts",
+      "default": "./dist/webllm.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/*.test.ts",
+    "test:browser": "playwright test",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "tag": "alpha"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "typescript": "^5.9.3"
+  }
+}