@agency-lang/whisper-local 0.0.1

package/CMakeLists.txt

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.18)
+project(whisper_addon)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# --- whisper.cpp + ggml as static libs ---
+set(WHISPER_BUILD_TESTS    OFF CACHE BOOL "" FORCE)
+set(WHISPER_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(WHISPER_BUILD_SERVER   OFF CACHE BOOL "" FORCE)
+set(GGML_BLAS  OFF CACHE BOOL "" FORCE)
+
+# Build whisper as a static lib so we can link it into the addon .node file.
+set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
+
+# macOS: enable Metal acceleration (free, no API surface needed)
+if(APPLE)
+  set(GGML_METAL ON CACHE BOOL "" FORCE)
+  set(GGML_METAL_EMBED_LIBRARY ON CACHE BOOL "" FORCE)
+else()
+  set(GGML_METAL OFF CACHE BOOL "" FORCE)
+endif()
+
+# Pull in the whole vendored whisper.cpp tree using its own top-level CMakeLists.
+add_subdirectory(vendor/whisper.cpp)
+
+# --- N-API addon ---
+include_directories(${CMAKE_JS_INC})
+
+file(GLOB ADDON_SOURCES "src/addon.cc")
+add_library(${PROJECT_NAME} SHARED ${ADDON_SOURCES} ${CMAKE_JS_SRC})
+set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
+
+target_include_directories(${PROJECT_NAME} PRIVATE
+  vendor/whisper.cpp/include
+  vendor/whisper.cpp/ggml/include
+)
+
+target_link_libraries(${PROJECT_NAME} PRIVATE whisper ${CMAKE_JS_LIB})
+
+# node-addon-api headers
+execute_process(
+  COMMAND node -p "require('node-addon-api').include"
+  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+  OUTPUT_VARIABLE NODE_ADDON_API_DIR
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+string(REGEX REPLACE "\"" "" NODE_ADDON_API_DIR ${NODE_ADDON_API_DIR})
+target_include_directories(${PROJECT_NAME} PRIVATE ${NODE_ADDON_API_DIR})
+add_definitions(-DNAPI_VERSION=8)

package/README.md

@@ -0,0 +1,145 @@
+# @agency-lang/whisper-local
+
+Local Whisper transcription for Agency. No network at runtime, no API key, no data leaves your machine.
+
+## Installation
+
+This package ships as source and ships **no** install/postinstall scripts — `npm install` will not run a compiler or fetch anything. After installing, run the explicit build step below to compile the native addon. This is intentional: postinstall scripts are the most common npm supply-chain attack vector, and silently invoking `cmake` on every install would surprise users who pulled the package as a transitive dependency.
+
+```sh
+# 1. Install (no compilation, no network beyond the npm download itself)
+npm install @agency-lang/whisper-local
+
+# 2. Explicitly build the native addon (one-time, ~30-90 seconds)
+npx -p @agency-lang/whisper-local agency-whisper build
+```
+
+**System dependencies (install before running `agency-whisper build`):**
+
+| Platform | Build tools | Audio decoding |
+|----------|-------------|----------------|
+| macOS    | `xcode-select --install && brew install cmake` | `brew install ffmpeg` |
+| Debian/Ubuntu | `sudo apt install cmake build-essential` | `sudo apt install ffmpeg` |
+| Fedora   | `sudo dnf install cmake gcc-c++` | `sudo dnf install ffmpeg` |
+| Windows  | Not yet supported in source-build v0; wait for prebuilts. | — |
+
+If `agency-whisper build` fails because of missing build tools, the rest of your `node_modules/` is unaffected.
+
+## Quick start
+
+```ts
+import { transcribe } from "pkg::@agency-lang/whisper-local"
+
+node main() {
+  const text = transcribe("interview.m4a", "en", "base.en")
+  print(text)
+}
+```
+
+The first call downloads `ggml-base.en.bin` (~150 MB) into `~/.agency/models/whisper/`. Subsequent calls reuse the cached file.
+
+## API
+
+```
+transcribe(filepath: string, language: string = "", model: string = "base.en"): string
+```
+
+- `filepath` — any audio file ffmpeg can read (mp3, m4a, wav, flac, ogg, webm, mp4, …). Must be a regular file on the local filesystem; URLs and ffmpeg pseudo-protocols (`http://`, `concat:`, `subfile:`, …) are explicitly rejected. See [Operational notes](#operational-notes).
+- `language` — ISO 639-1 code (e.g. `"en"`, `"fr"`, `"de"`). Empty string → whisper.cpp auto-detects.
+- `model` — model name. See the table below.
+
+Returns the joined transcript text. Throws on missing ffmpeg, unknown model, corrupted audio, or SHA-256 mismatch on model download.
+
+## Models
+
+All ten upstream whisper.cpp models are pinned in `models.lock.json` against HuggingFace commit [`5359861c…`](https://huggingface.co/ggerganov/whisper.cpp/tree/5359861c739e955e79d9a303bcbc70fb988958b1) with verified SHA-256 hashes.
+
+| Name | Size | English-only | Notes |
+|------|------|--------------|-------|
+| `tiny`           | 75 MB  | no  | Fastest, lowest accuracy. Good for quick prototypes. |
+| `tiny.en`        | 75 MB  | yes | English-only variant of `tiny`; slightly more accurate. |
+| `base`           | 142 MB | no  | Multilingual base model. |
+| `base.en`        | 142 MB | yes | **Default.** Good accuracy/speed trade-off for English. |
+| `small`          | 466 MB | no  | Noticeable accuracy bump over `base`. |
+| `small.en`       | 466 MB | yes | English-only variant of `small`. |
+| `medium`         | 1.5 GB | no  | Slow on CPU; usable on Apple Silicon. |
+| `medium.en`      | 1.5 GB | yes | English-only variant of `medium`. |
+| `large-v3`       | 2.9 GB | no  | Best accuracy. Use only with adequate RAM (~5 GB peak). |
+| `large-v3-turbo` | 1.6 GB | no  | Approaches `large-v3` quality at ~half the size. |
+
+`.en` variants are slightly more accurate on English-only audio. To add a model from a newer upstream release, see [`docs/DEV.md`](./docs/DEV.md#adding-a-model).
+
+## Pre-downloading models
+
+```sh
+npx -p @agency-lang/whisper-local agency-whisper pull base.en
+npx -p @agency-lang/whisper-local agency-whisper list
+npx -p @agency-lang/whisper-local agency-whisper verify base.en
+```
+
+## Manual model placement
+
+If you can't reach HuggingFace (network-restricted environment, etc.), download `ggml-<name>.bin` yourself and place it at `~/.agency/models/whisper/ggml-<name>.bin`. The package will use it as-is, without re-hashing on every load. To verify a manually-placed file:
+
+```sh
+npx -p @agency-lang/whisper-local agency-whisper verify <name>
+```
+
+## Custom model directory
+
+Set `AGENCY_WHISPER_MODELS_DIR` to use a directory other than `~/.agency/models/whisper/`.
+
+## Operational notes
+
+**Threading.** The native addon runs whisper inference on a libuv worker thread (`Napi::AsyncWorker`), so the JavaScript event loop is *not* blocked during a `transcribe()` call. Other JS work — HTTP requests, timers, etc. — continues to run.
+
+**Per-model serialization.** A `whisper_context` is mutable internal state. We hold a per-model mutex around `whisper_full`, so concurrent `transcribe()` calls on the *same* model serialize cleanly (no races, no corruption) but do not run in parallel. Throughput per model is single-threaded.
+
+**Cross-model parallelism.** Calls on *different* model instances run concurrently on separate libuv worker threads. By default Node sizes the libuv pool at 4 threads. If you run many concurrent transcriptions in the same process (e.g. an Agency program serving multiple users), bump the pool: `UV_THREADPOOL_SIZE=16 node ...` Do this *before* node starts; the pool size is locked at startup.
+
+**Loaded-model cache.** Loaded model contexts are kept in an in-process LRU cache. The default cap is 2 entries (a `large-v3` context can use ~3 GB, so an unbounded cache is dangerous in long-lived processes). Override via `AGENCY_WHISPER_HANDLE_CACHE_MAX`. Set to `0` to disable the cache (load + free per `transcribe()`).
+
+**Memory profile.** The audio decode step buffers the entire decoded PCM in memory before handing it to whisper. At 16 kHz mono float32 that is ~230 MB per hour of audio. Peak RSS during a transcribe is roughly 3× the decoded size (decoded buffer + Float32Array copy + C++ `std::vector` copy). The package rejects any single decode that exceeds 2 GB by default; override per-call via the lower-level `decodeToPcm({ maxPcmBytes })` API or chunk long audio client-side.
+
+**Timeout.** Each ffmpeg invocation has a 10-minute wall-clock cap (configurable via `decodeToPcm({ timeoutMs })`). On expiry the ffmpeg process is `SIGKILL`-ed and the call rejects, so a stuck or pathological input cannot hold the worker forever.
+
+**Input restriction.** `transcribe(filepath)` validates that `filepath` is a regular file before spawning ffmpeg, and the spawn is restricted to ffmpeg's `file` protocol. Inputs starting with `-` or specifying any other protocol (`http://`, `tcp://`, `concat:`, `subfile:`, …) are rejected up front. This matters because Agency programs often pass LLM-driven tool arguments straight into `transcribe()`; without this guard, a crafted "filepath" could turn a transcription into an outbound HTTP fetch or a read of an arbitrary local file.
+
+## Troubleshooting
+
+**`cmake: command not found`** — install cmake (see the install table).
+
+**`ffmpeg not found on PATH`** — install ffmpeg (see the install table).
+
+**`whisper_init_from_file_with_params failed`** — the `.bin` file is corrupted or not a whisper.cpp ggml format. Re-download with `agency-whisper pull <name>` or run `agency-whisper verify <name>` to check.
+
+**`SHA-256 mismatch`** — the downloaded model's hash doesn't match the lockfile. The partial file has been deleted. Re-running usually succeeds; if it persists, file an issue.
+
+**`whisper-local native addon not found`** — you skipped step 2 of installation. Run `npx -p @agency-lang/whisper-local agency-whisper build`.
+
+## Not in v0
+
+- Prebuilt binaries (will arrive via an optional-deps platform matrix).
+- Windows source-build support.
+- Streaming partial results.
+- Speaker diarization.
+- Translation mode.
+
+## For maintainers / contributors
+
+See [`docs/DEV.md`](./docs/DEV.md) for architecture, security model, C++ memory design, vendoring procedure, and testing notes.
+
+## Credits
+
+This package vendors and depends on:
+
+- **[whisper.cpp](https://github.com/ggml-org/whisper.cpp)** by Georgi Gerganov and contributors — MIT License. See `vendor/whisper.cpp/LICENSE`. We use a pinned release; see `vendor/whisper.cpp/VERSION`.
+- **[ggml](https://github.com/ggml-org/ggml)** by Georgi Gerganov and contributors — MIT License. Vendored alongside whisper.cpp.
+- **[node-addon-api](https://github.com/nodejs/node-addon-api)** by the Node.js project — MIT License.
+- **[cmake-js](https://github.com/cmake-js/cmake-js)** — MIT License.
+
+Audio decoding shells out to your system's **[ffmpeg](https://ffmpeg.org)**, which is not bundled or distributed with this package.
+
+## License
+
+ISC. See repository root LICENSE file. Vendored whisper.cpp + ggml source is MIT-licensed; see `vendor/whisper.cpp/LICENSE` for that notice.

package/dist/src/addon.d.ts

@@ -0,0 +1,11 @@
+export type WhisperModelInstance = {
+    transcribe(pcm: Float32Array, opts?: {
+        language?: string;
+        translate?: boolean;
+    }): Promise<string[]>;
+    free(): void;
+};
+export type WhisperModelCtor = new (modelPath: string) => WhisperModelInstance;
+export declare function loadAddon(): {
+    WhisperModel: WhisperModelCtor;
+};

package/dist/src/addon.js

@@ -0,0 +1,22 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPackageRoot } from "./packageRoot.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+let cached = null;
+export function loadAddon() {
+    if (cached)
+        return cached;
+    const pkgRoot = findPackageRoot(__dirname);
+    const addonPath = path.join(pkgRoot, "build", "Release", "whisper_addon.node");
+    if (!existsSync(addonPath)) {
+        throw new Error(`whisper-local native addon not found at ${addonPath}. ` +
+            `Run \`npx -p @agency-lang/whisper-local agency-whisper build\` ` +
+            `to compile it. (No postinstall hook runs this for you — by design.)`);
+    }
+    cached = require(addonPath);
+    return cached;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { loadLockfile, resolveModelDir, resolveModelPath, isModelInstalled, ensureModel, sha256OfFile, ModelManagerError, } from "./modelManager.js";
+import * as fs from "node:fs/promises";
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { findPackageRoot } from "./packageRoot.js";
+async function cmdBuild() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const pkgRoot = findPackageRoot(here);
+    console.log(`Building native addon in ${pkgRoot} ...`);
+    console.log("This compiles vendored whisper.cpp + ggml from source. Expect 30-90 seconds.");
+    console.log("Requires: cmake >= 3.18, a C++17 compiler. (ffmpeg is needed at runtime, not build time.)");
+    // We deliberately spawn the locally-installed cmake-js binary rather than
+    // invoking node's require system, so the user sees real cmake output and
+    // we don't accidentally execute vendored C++ via a hidden code path.
+    const cmakeJs = path.join(pkgRoot, "node_modules", ".bin", "cmake-js");
+    if (!existsSync(cmakeJs)) {
+        console.error(`cmake-js not found at ${cmakeJs}.`);
+        console.error(`Run \`npm install\` (or \`pnpm install\`) inside ${pkgRoot} first.`);
+        process.exit(5);
+    }
+    await new Promise((resolve, reject) => {
+        const child = spawn(cmakeJs, ["compile", "--runtime=node"], {
+            cwd: pkgRoot,
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`cmake-js exited with code ${code}`));
+        });
+    });
+    const addonPath = path.join(pkgRoot, "build", "Release", "whisper_addon.node");
+    if (!existsSync(addonPath)) {
+        console.error(`Build reported success but addon not found at ${addonPath}.`);
+        process.exit(6);
+    }
+    console.log(`Built: ${addonPath}`);
+}
+async function cmdPull(name) {
+    await ensureModel(name);
+    console.log(`Installed: ${resolveModelPath(name)}`);
+}
+async function cmdList() {
+    const dir = resolveModelDir();
+    const lock = await loadLockfile();
+    console.log(`Models directory: ${dir}\n`);
+    for (const [name, entry] of Object.entries(lock.models)) {
+        const installed = await isModelInstalled(name, dir);
+        const sizeMb = Math.round(entry.sizeBytes / 1e6);
+        const tag = installed ? "✓" : " ";
+        console.log(`  ${tag}  ${name.padEnd(16)} ${String(sizeMb).padStart(5)} MB`);
+    }
+}
+async function cmdVerify(name) {
+    const p = resolveModelPath(name);
+    const lock = await loadLockfile();
+    const entry = lock.models[name];
+    if (!entry)
+        throw new ModelManagerError(`unknown model "${name}"`);
+    try {
+        await fs.access(p);
+    }
+    catch {
+        console.error(`Not installed: ${p}`);
+        process.exit(2);
+    }
+    const actual = await sha256OfFile(p);
+    if (actual === entry.sha256) {
+        console.log(`OK: ${name} (${actual})`);
+    }
+    else {
+        console.error(`MISMATCH: ${name}`);
+        console.error(`  expected ${entry.sha256}`);
+        console.error(`  actual   ${actual}`);
+        process.exit(3);
+    }
+}
+function usage() {
+    console.error("Usage: agency-whisper <command> [args]");
+    console.error("  build            Compile the native addon (run once after install)");
+    console.error("  pull <model>     Download a model (e.g. base.en)");
+    console.error("  list             List supported models and installation status");
+    console.error("  verify <model>   Re-hash an installed model and compare to lockfile");
+    process.exit(1);
+}
+const [, , cmd, ...rest] = process.argv;
+try {
+    switch (cmd) {
+        case "build":
+            await cmdBuild();
+            break;
+        case "pull":
+            if (!rest[0])
+                usage();
+            await cmdPull(rest[0]);
+            break;
+        case "list":
+            await cmdList();
+            break;
+        case "verify":
+            if (!rest[0])
+                usage();
+            await cmdVerify(rest[0]);
+            break;
+        default:
+            usage();
+    }
+}
+catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(4);
+}

package/dist/src/ffmpeg.d.ts

@@ -0,0 +1,11 @@
+export declare class FfmpegError extends Error {
+    constructor(message: string);
+}
+export declare const DEFAULT_FFMPEG_TIMEOUT_MS: number;
+export declare const DEFAULT_MAX_PCM_BYTES: number;
+export type DecodeOptions = {
+    timeoutMs?: number;
+    maxPcmBytes?: number;
+};
+export declare function buildFfmpegArgs(filepath: string): string[];
+export declare function decodeToPcm(filepath: string, opts?: DecodeOptions): Promise<Float32Array>;

package/dist/src/ffmpeg.js

@@ -0,0 +1,154 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+export class FfmpegError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FfmpegError";
+    }
+}
+// Default 10-minute wall clock per ffmpeg invocation. Overridable per-call so
+// callers transcribing very long files can opt in to a higher cap.
+export const DEFAULT_FFMPEG_TIMEOUT_MS = 10 * 60 * 1000;
+// Default 2 GB cap on decoded PCM bytes (~2.4 hours of 16 kHz mono float32).
+// Bounds memory growth on attacker-controlled or pathological input. Override
+// per-call when intentionally transcribing very long audio.
+export const DEFAULT_MAX_PCM_BYTES = 2 * 1024 * 1024 * 1024;
+export function buildFfmpegArgs(filepath) {
+    return [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        // Restrict ffmpeg to the local file protocol. Without this, a filepath of
+        // "http://evil/x", "tcp://...", "concat:...", or "subfile,..." would make
+        // ffmpeg perform outbound network requests or read arbitrary local files
+        // outside the one we believe we're transcribing. Since transcribe() is
+        // commonly called with LLM-driven tool arguments in Agency programs, this
+        // matters: never let an attacker turn a transcription into a file read or
+        // SSRF.
+        "-protocol_whitelist",
+        "file",
+        "-i",
+        filepath,
+        "-ac",
+        "1",
+        "-ar",
+        "16000",
+        "-f",
+        "f32le",
+        "-",
+    ];
+}
+function ffmpegInstallHint() {
+    switch (process.platform) {
+        case "darwin":
+            return "Install with: brew install ffmpeg";
+        case "linux":
+            return "Install with: apt install ffmpeg (or your distro's equivalent)";
+        case "win32":
+            return "Install from https://ffmpeg.org/download.html and ensure it's on PATH";
+        default:
+            return "Install ffmpeg and ensure it's on PATH";
+    }
+}
+async function validateInputPath(filepath) {
+    // Reject anything that looks like a CLI flag (e.g. "-version", "-i").
+    // ffmpeg's positional input slot is occupied by the value after our literal
+    // "-i", so a leading-dash filepath cannot smuggle a flag at *that*
+    // position — but the `-protocol_whitelist file` argument earlier in the
+    // command line still leaves us vulnerable to confused-deputy bugs if the
+    // argument order ever changes. Reject up front; a real audio file never
+    // starts with "-".
+    if (filepath.startsWith("-")) {
+        throw new FfmpegError(`refusing path that starts with '-': ${filepath}`);
+    }
+    let st;
+    try {
+        st = await fs.stat(filepath);
+    }
+    catch (err) {
+        throw new FfmpegError(`input file not found or unreadable: ${filepath} (${err.message})`);
+    }
+    if (!st.isFile()) {
+        throw new FfmpegError(`input is not a regular file: ${filepath}`);
+    }
+}
+export async function decodeToPcm(filepath, opts = {}) {
+    await validateInputPath(filepath);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_FFMPEG_TIMEOUT_MS;
+    const maxPcmBytes = opts.maxPcmBytes ?? DEFAULT_MAX_PCM_BYTES;
+    const args = buildFfmpegArgs(filepath);
+    const proc = spawn("ffmpeg", args);
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let oversizeRejected = false;
+    // Force-kill the process and tag the rejection. SIGKILL (vs SIGTERM) is
+    // intentional: a stuck or runaway ffmpeg may ignore TERM, and we'd rather
+    // strand a partial decode than leave a zombie holding CPU.
+    let killReason = null;
+    const kill = (reason) => {
+        if (killReason)
+            return;
+        killReason = reason;
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            // Process may already be gone; the close handler still fires.
+        }
+    };
+    proc.stdout.on("data", (c) => {
+        stdoutBytes += c.byteLength;
+        if (stdoutBytes > maxPcmBytes && !oversizeRejected) {
+            oversizeRejected = true;
+            kill(`decoded output exceeded cap of ${maxPcmBytes} bytes ` +
+                `(~${Math.round(maxPcmBytes / (16000 * 4))} seconds of audio at 16 kHz mono f32)`);
+            return;
+        }
+        stdoutChunks.push(c);
+    });
+    proc.stderr.on("data", (c) => stderrChunks.push(c));
+    const timer = setTimeout(() => {
+        kill(`ffmpeg exceeded timeout of ${timeoutMs} ms`);
+    }, timeoutMs);
+    return new Promise((resolve, reject) => {
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            if (err.code === "ENOENT") {
+                reject(new FfmpegError(`ffmpeg not found on PATH. ${ffmpegInstallHint()}`));
+            }
+            else {
+                reject(new FfmpegError(`failed to spawn ffmpeg: ${err.message}`));
+            }
+        });
+        proc.on("close", (code) => {
+            clearTimeout(timer);
+            if (killReason !== null) {
+                reject(new FfmpegError(killReason));
+                return;
+            }
+            if (code !== 0) {
+                const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
+                reject(new FfmpegError(`ffmpeg exited with code ${code}: ${stderr}`));
+                return;
+            }
+            const buf = Buffer.concat(stdoutChunks);
+            if (buf.byteLength % 4 !== 0) {
+                reject(new FfmpegError(`ffmpeg produced ${buf.byteLength} bytes, not a multiple of 4`));
+                return;
+            }
+            // Wrap the bytes as Float32 in one shot. This is ~100x faster than
+            // looping with buf.readFloatLE(i) and is host-endian-safe on every
+            // platform Node supports: V8 only ships on little-endian hosts (x86_64,
+            // arm64, riscv64 in LE mode), and the f32le ffmpeg output we asked for
+            // is also little-endian, so the two endiannesses match by construction.
+            // We allocate a fresh ArrayBuffer because (a) it's guaranteed 4-byte
+            // aligned, which Float32Array requires, and (b) Buffer.concat returns
+            // memory whose byteOffset may not be aligned.
+            const aligned = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(aligned).set(buf);
+            const f32 = new Float32Array(aligned);
+            resolve(f32);
+        });
+    });
+}

package/dist/src/handleCache.d.ts

@@ -0,0 +1,9 @@
+import type { WhisperModelInstance } from "./addon.js";
+type CachedHandle = {
+    instance: WhisperModelInstance;
+};
+export declare const handleCache: Record<string, CachedHandle>;
+export declare function acquireHandle(key: string, factory: () => WhisperModelInstance): WhisperModelInstance;
+export declare function isCached(key: string): boolean;
+export declare function _clearHandleCache(): void;
+export {};

package/dist/src/handleCache.js

@@ -0,0 +1,83 @@
+// Insertion-order map. Each call to acquireHandle() promotes the entry to
+// most-recently-used. evictOldest() drops the least-recently-used entry.
+export const handleCache = {};
+// Default cap of 2 loaded models. A typical Agency program uses one model;
+// two leaves headroom for "switching from base.en to large-v3 mid-program"
+// without thrashing. Each entry can hold hundreds of MB (a large-v3 context
+// is ~3 GB), so an unbounded cache is dangerous in long-lived processes.
+//
+// Override via AGENCY_WHISPER_HANDLE_CACHE_MAX. Set to 0 to disable caching
+// (every transcribe() loads + frees), or to a large value to opt out of LRU.
+function configuredMax() {
+    const raw = process.env.AGENCY_WHISPER_HANDLE_CACHE_MAX;
+    if (raw === undefined)
+        return 2;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return 2;
+    return Math.floor(n);
+}
+function freeQuiet(key, instance) {
+    try {
+        instance.free();
+    }
+    catch (err) {
+        // free() throws "WhisperModel busy" if a transcribe is still in flight.
+        // The Persistent ref in the addon keeps the model alive until the worker
+        // finishes; we just drop our cache entry. Worst case we leak one model
+        // until its in-flight transcribe completes and JS GC collects it.
+        console.warn(`whisper-local: failed to free model "${key}": ${err.message}`);
+    }
+}
+// Touch an existing entry so it becomes most-recently-used. Implemented by
+// delete + re-insert, which is O(1) on V8's hash map and preserves insertion
+// order semantics for Object.keys().
+function touch(key) {
+    const entry = handleCache[key];
+    if (entry === undefined)
+        return;
+    delete handleCache[key];
+    handleCache[key] = entry;
+}
+export function acquireHandle(key, factory) {
+    const existing = handleCache[key];
+    if (existing) {
+        touch(key);
+        return existing.instance;
+    }
+    const max = configuredMax();
+    // Failure-atomic: construct *first*, then evict + insert. If factory()
+    // throws (corrupt model, OOM, missing GPU, …) we leave the existing
+    // cache contents untouched. A transient load failure must not cost the
+    // user the model they already had loaded.
+    const instance = factory();
+    if (max === 0) {
+        // max=0 means "don't cache" — hand the instance back without storing.
+        // The caller is responsible for free() (transcribe.ts wraps this path
+        // so the model is freed after each call).
+        return instance;
+    }
+    // Evict from the front (least-recently-used) until we have room. We only
+    // need to evict 1 in steady state, but a runtime decrease in max via env
+    // re-read could leave the cache larger than max — handle it generally.
+    while (Object.keys(handleCache).length >= max) {
+        const oldestKey = Object.keys(handleCache)[0];
+        if (oldestKey === undefined)
+            break;
+        const oldest = handleCache[oldestKey];
+        delete handleCache[oldestKey];
+        freeQuiet(oldestKey, oldest.instance);
+    }
+    handleCache[key] = { instance };
+    return instance;
+}
+// Whether a given key is currently cached (test helper).
+export function isCached(key) {
+    return handleCache[key] !== undefined;
+}
+export function _clearHandleCache() {
+    for (const key of Object.keys(handleCache)) {
+        freeQuiet(key, handleCache[key].instance);
+        delete handleCache[key];
+    }
+}

package/dist/src/modelManager.d.ts

@@ -0,0 +1,12 @@
+import type { ModelName, Lockfile, LockfileEntry } from "./types.js";
+export declare class ModelManagerError extends Error {
+    constructor(message: string);
+}
+export declare function resolveModelDir(): string;
+export declare function resolveModelPath(name: ModelName, dir?: string): string;
+export declare function isModelInstalled(name: ModelName, dir?: string): Promise<boolean>;
+export declare function parseLockfile(text: string, source?: string): Lockfile;
+export declare function loadLockfile(): Promise<Lockfile>;
+export declare function sha256OfFile(filepath: string): Promise<string>;
+export declare function downloadModel(entry: LockfileEntry, dest: string): Promise<void>;
+export declare function ensureModel(name: ModelName, dir?: string): Promise<string>;