@arnilo/prism 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.7] - 2026-08-12
+
+### Changed
+- **Release 0.1.7 (plan 019)** is the performance-and-DX patch on the frozen 0.1.x line — additive-only vs 0.1.6 (freeze manifest `scripts/phase19-freeze-manifest.json`; every task's diff stayed inside its allowed files, enforced by the phase19 freeze machine; the async `AgUiProjection` item is a verification closeout, not new code). (1) **Prompt-cache telemetry surface** (`cache-telemetry`): dependency-free `createCacheTelemetry()` aggregator in core — host-activated (nothing subscribes by import), consumes `Usage` + `ModelConfig` pairs from the usage `ProviderEvent` or run-ledger records, and reports per-provider/model request counts, aggregate hit rate via the existing `cacheHitRate` math, cache-read/write token totals, and estimated savings via `cacheSavings` when cost metadata exists; bounded cardinality (default cap 256 distinct provider/model keys, overflow collapses into the `CACHE_TELEMETRY_OVERFLOW_KEY` `__overflow__` bucket with an `overflowed` flag, ponytail ceiling named — host-configurable caps or LRU eviction only if a real deployment exceeds it); reports carry token counters/rates only — never prompt content, cache keys, or identity; `record()` is O(1) with validated finite non-negative inputs; no OTel metric emission (demand-gated follow-up). (2) **Model-router selection policies** (`router-selection`): additive `selection` hook on `CreateModelRouterOptions` — `ModelRouterSelectionPolicy` (`name`/`rank`/`observe`); default ordered behavior byte-identical (regression test); reference `createCostLatencySelection` ranks candidates by `ModelCost` (input/output/cacheRead with per-million normalization) then in-memory EMA latency fed from `recordOutcome`'s new optional `latencyMs` (`latencyWeight` 0–1, default 0.5; pure-cost order on cold start); the policy is a permutation-only reorder of already-allowed candidates so it cannot widen allow-list/residency/budget decisions, and any drop/add/duplicate misbehavior fails closed with `ERR_PRISM_MODEL_ROUTER_POLICY`; policy name rides the still-redacted diagnostics; durable latency stats are a demand-gated follow-up requiring a `ModelRouterStateStore` contract change. (3) **Async AgUiProjection closeout** (`async-hooks`): plan 009 Task 15 surface verified with evidence — hooks are typed `Awaitable<T>` (17 hooks), `getMessages` accepts `() => readonly AgUiMessage[] | Promise<...>` so `messagesFromSession` can call async host APIs like `session.entries()`, snapshots are awaited strictly in event order (never `Promise.all`), rejection fails closed per event with sibling hooks still projected, caps apply to awaited values; evidence in `scripts/phase19-baseline.json` `asyncHooks` (`verified: true`, `gapFound: false`). (4) **`prism providers add <name>` scaffold** (`provider-scaffold`): new CLI subcommand (stdlib-only, mirrors `prism init`) scaffolds an OpenAI-compatible provider package into `./<name>` — `package.json` (peer dep `@arnilo/prism`, `sideEffects: false`, publish metadata), `tsconfig.json`, `README.md`, `CHANGELOG.md`, `src/index.ts` (`defineProviderPackage` + `api_key` auth-method registration), `src/provider.ts` (built on `createOpenAICompatibleProvider`), `src/models.ts` (starter `ModelConfig` list), `src/cache.ts` (cache-hint mapping via the shared core helpers), `src/__tests__/provider.test.ts` (offline conformance: stream shape + usage, header ownership, tool-call delta reconstruction, serialized-content coverage, secret-leak redaction), and `docs/providers/<name>.md` stub; flags `--base-url` (http(s) validated), `--env-key` (shell-safe identifier), `--model`, `--force`; npm package-name validation, path-traversal and symlink-escape refusal (nothing can land outside the destination), usage errors exit 2 with nothing written, generated code contains placeholders only — never secrets; scaffold output is host-chosen and never auto-registered into repo workspaces or resolvers; a fixture test proves the generated package typechecks and passes its conformance test offline against the repo build. Release graph stays **50** publishable manifests (root + 49 workspace packages — 14 provider adapters, 9 `prism-*` family/profile, 26 capability incl. `@arnilo/prism-document-reader`) at exact **0.1.7**. Exit gate green (core tests + script gates incl. phase19-freeze done-phase, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain compat gate at 0.1.7 with 0 breaking deltas then version-literal baseline refresh — no `--allow-break` anywhere, evidence in `scripts/phase19-baseline.json`). Store compatibility with 0.1.6: **compatible, no migration** (additive-only; no persisted-shape change; `docs/migration.md` gains no entries). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.1.7 publish handoff` — signed `v0.1.7` tag + npm OIDC). **CI hardening after the exit gate** (same day): the release `verify` job now runs the sdk:ready legs phase-by-phase (explicit rc per leg so a silent failure still names the failing phase) and uploads `sdk-ready.log` as an artifact on failure; the examples demo test compiles the demos in place with the repo tsc before spawning them, so the spawned children are plain JS instead of loading the amaro type-stripping WASM module (whose large per-process virtual reservation fails with `WebAssembly.Instance(): Out of memory` on memory-constrained CI runners); emitted .js files are removed in a finally block.
+
 ## [0.1.6] - 2026-08-11
 
 ### Changed

package/dist/cache-telemetry.d.ts

@@ -0,0 +1,58 @@
+import type { ModelConfig, Usage } from "./contracts-core.js";
+/**
+ * Prompt-cache telemetry surface (0.1.7, plan 019 Task 2).
+ *
+ * Dependency-free aggregator hosts attach to their `usage` `ProviderEvent`
+ * stream (or run-ledger usage records) to get per-provider/model cache
+ * statistics for tuning the `cache_aware` input layout. Explicit activation:
+ * nothing subscribes by import — the host calls `record()`.
+ */
+/** Single provider/model statistics sample. */
+export interface CacheTelemetrySample {
+    readonly provider: string;
+    readonly model: string;
+    readonly requests: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly inputTokens: number;
+    /** Cached-input ratio across the sample (`cacheHitRate` math, aggregated). */
+    readonly hitRate?: number;
+    /** Estimated read-token savings via `cacheSavings` math; present only when
+     *  the sample's model carries cost metadata (`ModelCost.input`/`cacheRead`). */
+    readonly estimatedSavings?: number;
+    readonly currency?: string;
+}
+/** Aggregated report. Samples are sorted by provider then model. */
+export interface CacheTelemetryReport {
+    readonly samples: readonly CacheTelemetrySample[];
+    readonly overflowed: boolean;
+    readonly totalRequests: number;
+    readonly totalCacheReadTokens: number;
+    readonly totalCacheWriteTokens: number;
+}
+export interface CacheTelemetryOptions {
+    /** Distinct provider/model keys before excess keys collapse into the
+     *  `__overflow__` bucket. Default {@link DEFAULT_CACHE_TELEMETRY_CAP}. */
+    readonly maxKeys?: number;
+}
+export interface CacheTelemetry {
+    /** Aggregate one usage record attributed to `model` (or an unknown bucket
+     *  when no model is supplied). Rejects non-finite/negative token counts
+     *  with {@link CacheTelemetryError}; validates before mutating. */
+    record(usage: Usage, model?: ModelConfig): void;
+    /** Snapshot of all samples (O(keys)); never throws. */
+    report(): CacheTelemetryReport;
+    /** Clear all samples (host rotation / long-run reset). */
+    reset(): void;
+    /** Number of distinct provider/model keys held (excluding the overflow bucket). */
+    readonly size: number;
+}
+/** Cardinality ceiling: keys beyond this collapse into `__overflow__`. */
+export declare const DEFAULT_CACHE_TELEMETRY_CAP = 256;
+/** Sample bucket key for provider/model keys beyond the cap. */
+export declare const CACHE_TELEMETRY_OVERFLOW_KEY = "__overflow__";
+export declare class CacheTelemetryError extends Error {
+    readonly code = "ERR_PRISM_CACHE_TELEMETRY";
+    constructor(message: string);
+}
+export declare function createCacheTelemetry(options?: CacheTelemetryOptions): CacheTelemetry;

package/dist/cache-telemetry.js

@@ -0,0 +1,102 @@
+import { cacheHitRate, cacheSavings } from "./cache-helpers.js";
+/** Cardinality ceiling: keys beyond this collapse into `__overflow__`. */
+export const DEFAULT_CACHE_TELEMETRY_CAP = 256;
+/** Sample bucket key for provider/model keys beyond the cap. */
+export const CACHE_TELEMETRY_OVERFLOW_KEY = "__overflow__";
+export class CacheTelemetryError extends Error {
+    code = "ERR_PRISM_CACHE_TELEMETRY";
+    constructor(message) {
+        super(message);
+        this.name = "CacheTelemetryError";
+    }
+}
+function validateTokens(name, value) {
+    if (value === undefined)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new CacheTelemetryError(`${name} must be a non-negative safe integer, got ${value}`);
+    }
+}
+function sampleFor(usage, model) {
+    if (model)
+        return { provider: model.provider, model: model.model };
+    // Provider-only aggregation: no model supplied, attribute to the unknown bucket.
+    return { provider: "unknown", model: "unknown" };
+}
+export function createCacheTelemetry(options = {}) {
+    const maxKeys = options.maxKeys ?? DEFAULT_CACHE_TELEMETRY_CAP;
+    if (!Number.isSafeInteger(maxKeys) || maxKeys < 1) {
+        throw new CacheTelemetryError(`maxKeys must be a positive safe integer, got ${options.maxKeys}`);
+    }
+    // ponytail: fixed per-provider/model key cap with a single __overflow__ bucket;
+    // if real deployments exceed it, upgrade to host-configurable caps or LRU eviction.
+    const samples = new Map();
+    let overflow = false;
+    let overflowSample;
+    function bucket(provider, model) {
+        const key = `${provider}\u0000${model}`;
+        let sample = samples.get(key);
+        if (sample)
+            return sample;
+        if (samples.size >= maxKeys) {
+            overflow = true;
+            if (!overflowSample) {
+                overflowSample = {
+                    provider: CACHE_TELEMETRY_OVERFLOW_KEY,
+                    model: CACHE_TELEMETRY_OVERFLOW_KEY,
+                    requests: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                    inputTokens: 0,
+                };
+            }
+            return overflowSample;
+        }
+        sample = { provider, model, requests: 0, cacheReadTokens: 0, cacheWriteTokens: 0, inputTokens: 0 };
+        samples.set(key, sample);
+        return sample;
+    }
+    return {
+        record(usage, model) {
+            // Validate everything before mutating: a bad record mutates nothing.
+            validateTokens("usage.cacheReadTokens", usage.cacheReadTokens);
+            validateTokens("usage.cacheWriteTokens", usage.cacheWriteTokens);
+            validateTokens("usage.inputTokens", usage.inputTokens);
+            const { provider, model: modelName } = sampleFor(usage, model);
+            const sample = bucket(provider, modelName);
+            sample.requests += 1;
+            sample.cacheReadTokens += usage.cacheReadTokens ?? 0;
+            sample.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+            sample.inputTokens += usage.inputTokens ?? 0;
+            sample.hitRate = cacheHitRate({
+                cacheReadTokens: sample.cacheReadTokens,
+                inputTokens: sample.inputTokens,
+            });
+            if (model?.cost) {
+                // cacheSavings depends only on read tokens + cost metadata, so the
+                // aggregate equals the sum of per-call savings; feed it the totals
+                // to reuse the exact cache-helpers math rather than reimplementing it.
+                const savings = cacheSavings({ cacheReadTokens: sample.cacheReadTokens }, model);
+                sample.estimatedSavings = savings;
+                sample.currency = model.cost.currency;
+            }
+        },
+        report() {
+            const samplesAll = [...samples.values()].sort((a, b) => a.provider === b.provider ? a.model.localeCompare(b.model) : a.provider.localeCompare(b.provider));
+            const listed = overflowSample ? [...samplesAll, overflowSample] : samplesAll;
+            const totalRequests = listed.reduce((sum, s) => sum + s.requests, 0);
+            const totalCacheReadTokens = listed.reduce((sum, s) => sum + s.cacheReadTokens, 0);
+            const totalCacheWriteTokens = listed.reduce((sum, s) => sum + s.cacheWriteTokens, 0);
+            return { samples: listed, overflowed: overflow, totalRequests, totalCacheReadTokens, totalCacheWriteTokens };
+        },
+        reset() {
+            samples.clear();
+            overflow = false;
+            overflowSample = undefined;
+        },
+        get size() {
+            return samples.size;
+        },
+    };
+}
+//# sourceMappingURL=cache-telemetry.js.map

package/dist/cli-provider-add.d.ts

@@ -0,0 +1,37 @@
+import type { Writable } from "node:stream";
+export declare class ProviderAddUsageError extends Error {
+}
+export interface ProviderAddOptions {
+    /** npm-validated provider/package name; also the target directory name. */
+    readonly name: string;
+    readonly baseUrl: string;
+    /** Shell-safe identifier, e.g. `ACME_API_KEY`. Never a secret value. */
+    readonly envKey: string;
+    readonly model: string;
+    readonly force: boolean;
+    readonly help: boolean;
+}
+export interface ProviderAddRuntime {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+    /** Override template root (tests). Defaults to package `templates/provider`. */
+    readonly templatesRoot?: string;
+    /** Override package version stamped into the generated package.json. */
+    readonly packageVersion?: string;
+    /** Working directory used to resolve relative destinations. Defaults to process.cwd(). */
+    readonly cwd?: string;
+}
+export interface ProviderAddResult {
+    readonly targetDir: string;
+    readonly writtenFiles: readonly string[];
+    readonly name: string;
+    readonly totalBytes: number;
+}
+export declare function getProviderAddUsage(): string;
+export declare const providerAddUsage: string;
+export declare function parseProviderAddArgs(argv: readonly string[]): ProviderAddOptions;
+export declare function runProviderAddCommand(argv: readonly string[], runtime: ProviderAddRuntime): Promise<number>;
+export declare function createProviderProject(options: ProviderAddOptions, runtime?: ProviderAddRuntime): Promise<ProviderAddResult>;
+export declare function defaultProviderTemplatesRoot(): string;
+/** npm package-name rules plus traversal refusal. Throws `ProviderAddUsageError` on violation. */
+export declare function validateProviderName(name: string): void;

package/dist/cli-provider-add.js

@@ -0,0 +1,293 @@
+import { accessSync, constants as fsConstants } from "node:fs";
+import { access, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export class ProviderAddUsageError extends Error {
+}
+const NPM_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_NAME_LENGTH = 214;
+const DEFAULT_BASE_URL = "https://api.example.com/v1";
+export function getProviderAddUsage() {
+    return `Usage: prism providers add <name> [options]
+
+Scaffold an OpenAI-compatible provider package (manifest, provider, models, cache
+helpers, conformance test, docs stub) into ./<name>.
+
+Arguments:
+  <name>                       npm-validated package/provider name (lowercase)
+
+Options:
+  --base-url <url>             Default Chat Completions base URL (default: ${DEFAULT_BASE_URL})
+  --env-key <name>             Credential environment-var identifier (default: <NAME>_API_KEY)
+  --model <id>                 Starter model id (default: <name>-large)
+  --force                      Overwrite existing generated files
+  -h, --help                   Show this help
+
+Examples:
+  prism providers add acme --base-url https://api.acme.example/v1 --env-key ACME_API_KEY --model acme-large
+`;
+}
+export const providerAddUsage = getProviderAddUsage();
+export function parseProviderAddArgs(argv) {
+    let name;
+    let baseUrl = DEFAULT_BASE_URL;
+    let envKey;
+    let model;
+    let force = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            help = true;
+            continue;
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--base-url" || arg === "--env-key" || arg === "--model") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                throw new ProviderAddUsageError(`Missing value for ${arg}`);
+            }
+            i += 1;
+            if (arg === "--base-url") {
+                baseUrl = value;
+            }
+            else if (arg === "--env-key") {
+                envKey = value;
+            }
+            else {
+                model = value;
+            }
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new ProviderAddUsageError(`Unknown flag: ${arg}`);
+        }
+        if (name !== undefined) {
+            throw new ProviderAddUsageError(`Unexpected argument: ${arg}`);
+        }
+        name = arg;
+    }
+    if (!help && name === undefined) {
+        throw new ProviderAddUsageError("Missing provider name");
+    }
+    return {
+        name: name ?? "provider",
+        baseUrl,
+        envKey: envKey ?? `${(name ?? "provider").replace(/[^a-z0-9]+/gi, "_").toUpperCase()}_API_KEY`,
+        model: model ?? `${name ?? "provider"}-large`,
+        force,
+        help,
+    };
+}
+export async function runProviderAddCommand(argv, runtime) {
+    let options;
+    try {
+        options = parseProviderAddArgs(argv);
+    }
+    catch (error) {
+        write(runtime.stderr, `${error instanceof Error ? error.message : String(error)}\n${getProviderAddUsage()}`);
+        return 2;
+    }
+    if (options.help) {
+        write(runtime.stdout, getProviderAddUsage());
+        return 0;
+    }
+    try {
+        validateProviderName(options.name);
+        validateBaseUrl(options.baseUrl);
+        if (!ENV_KEY_PATTERN.test(options.envKey)) {
+            throw new ProviderAddUsageError(`Invalid --env-key: ${options.envKey} (must be a shell-safe identifier)`);
+        }
+        const result = await createProviderProject(options, runtime);
+        write(runtime.stdout, [
+            `Scaffolded provider package in ${result.targetDir}`,
+            `  name: ${result.name}`,
+            `  files: ${result.writtenFiles.length}`,
+            `  bytes: ${result.totalBytes}`,
+            "",
+            "Next:",
+            `  cd ${result.name}`,
+            "  npm install",
+            "  npm test",
+            "  Replace the starter model metadata and docs stub with docs-verified values before publishing.",
+            "",
+        ].join("\n"));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof ProviderAddUsageError) {
+            write(runtime.stderr, `${message}\n${getProviderAddUsage()}`);
+            return 2;
+        }
+        write(runtime.stderr, `${message}\n`);
+        return 1;
+    }
+}
+export async function createProviderProject(options, runtime = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    validateProviderName(options.name);
+    const cwd = runtime.cwd ?? process.cwd();
+    const targetDir = resolve(cwd, options.name);
+    const templatesRoot = runtime.templatesRoot ?? defaultProviderTemplatesRoot();
+    const version = runtime.packageVersion ?? (await readPackageVersion());
+    await assertDestinationWritable(targetDir, options.force);
+    const tokens = buildTokens({ ...options, version });
+    const planned = planProviderFiles(templatesRoot, options.name);
+    if (!options.force) {
+        for (const file of planned) {
+            const dest = join(targetDir, file.relativePath);
+            if (await exists(dest)) {
+                throw new ProviderAddUsageError(`Refusing to overwrite existing file: ${file.relativePath} (pass --force to overwrite)`);
+            }
+        }
+    }
+    const writtenFiles = [];
+    let totalBytes = 0;
+    for (const file of planned) {
+        const dest = join(targetDir, file.relativePath);
+        assertPathInside(targetDir, dest);
+        const raw = await readFile(file.sourcePath, "utf8");
+        const content = applyTokens(raw, tokens);
+        await mkdir(dirname(dest), { recursive: true });
+        await assertNoSymlinkEscape(targetDir, dirname(dest));
+        await writeFile(dest, content, "utf8");
+        writtenFiles.push(file.relativePath);
+        totalBytes += Buffer.byteLength(content, "utf8");
+    }
+    return {
+        targetDir,
+        writtenFiles,
+        name: options.name,
+        totalBytes,
+    };
+}
+export function defaultProviderTemplatesRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "provider");
+}
+/** npm package-name rules plus traversal refusal. Throws `ProviderAddUsageError` on violation. */
+export function validateProviderName(name) {
+    if (name.length === 0)
+        throw new ProviderAddUsageError("Missing provider name");
+    if (name.includes("\0"))
+        throw new ProviderAddUsageError("Invalid provider name");
+    if (name.length > MAX_NAME_LENGTH) {
+        throw new ProviderAddUsageError(`Invalid provider name: ${name} (max ${MAX_NAME_LENGTH} chars)`);
+    }
+    if (!NPM_NAME_PATTERN.test(name) || name.includes("..")) {
+        throw new ProviderAddUsageError(`Invalid provider name: ${name} (npm names are lowercase, start with a letter/digit, and contain only letters, digits, -, _, .)`);
+    }
+}
+function validateBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new ProviderAddUsageError(`Invalid --base-url: ${baseUrl} (must be an http(s) URL)`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new ProviderAddUsageError(`Invalid --base-url: ${baseUrl} (must be an http(s) URL)`);
+    }
+}
+function buildTokens(input) {
+    const pascal = input.name
+        .split(/[^a-z0-9]+/i)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+    return {
+        __PROVIDER_ID__: input.name,
+        __PROVIDER_UPPER__: input.name.replace(/[^a-z0-9]+/gi, "_").toUpperCase(),
+        __PROVIDER_PASCAL__: pascal,
+        __PACKAGE_NAME__: input.name,
+        __PRISM_VERSION__: input.version,
+        __BASE_URL__: input.baseUrl.replace(/\/+$/, ""),
+        __ENV_KEY__: input.envKey,
+        __MODEL_ID__: input.model,
+    };
+}
+function planProviderFiles(templatesRoot, name) {
+    const files = [
+        { relativePath: "package.json", sourcePath: join(templatesRoot, "package.json.tmpl") },
+        { relativePath: "tsconfig.json", sourcePath: join(templatesRoot, "tsconfig.json.tmpl") },
+        { relativePath: "README.md", sourcePath: join(templatesRoot, "README.md.tmpl") },
+        { relativePath: "CHANGELOG.md", sourcePath: join(templatesRoot, "CHANGELOG.md.tmpl") },
+        { relativePath: "src/index.ts", sourcePath: join(templatesRoot, "src/index.ts.tmpl") },
+        { relativePath: "src/provider.ts", sourcePath: join(templatesRoot, "src/provider.ts.tmpl") },
+        { relativePath: "src/models.ts", sourcePath: join(templatesRoot, "src/models.ts.tmpl") },
+        { relativePath: "src/cache.ts", sourcePath: join(templatesRoot, "src/cache.ts.tmpl") },
+        { relativePath: "src/__tests__/provider.test.ts", sourcePath: join(templatesRoot, "src/tests/provider.test.ts.tmpl") },
+        { relativePath: `docs/providers/${name}.md`, sourcePath: join(templatesRoot, "docs/providers/NAME.md.tmpl") },
+    ];
+    for (const file of files) {
+        try {
+            accessSync(file.sourcePath, fsConstants.R_OK);
+        }
+        catch {
+            throw new Error(`Missing provider template: ${file.sourcePath}`);
+        }
+    }
+    return files;
+}
+function applyTokens(template, tokens) {
+    let out = template;
+    for (const [token, value] of Object.entries(tokens)) {
+        out = out.split(token).join(value);
+    }
+    if (/__[A-Z0-9_]+__/.test(out)) {
+        const leftover = out.match(/__[A-Z0-9_]+__/g) ?? [];
+        throw new Error(`Unresolved provider template tokens: ${Array.from(new Set(leftover)).join(", ")}`);
+    }
+    return out;
+}
+async function readPackageVersion() {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    if (!pkg.version)
+        throw new Error(`Missing version in ${pkgPath}`);
+    return pkg.version;
+}
+async function assertDestinationWritable(targetDir, force) {
+    if (!(await exists(targetDir))) {
+        await mkdir(targetDir, { recursive: true });
+        return;
+    }
+    const entries = await readdir(targetDir);
+    if (entries.length > 0 && !force) {
+        throw new ProviderAddUsageError(`Destination is not empty: ${targetDir} (pass --force to overwrite generated files)`);
+    }
+}
+function assertPathInside(root, candidate) {
+    const rel = relative(root, candidate);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return;
+    throw new ProviderAddUsageError(`Refusing to write outside destination: ${candidate}`);
+}
+/** Refuse writes whose real parent directory escapes the real target (symlinked dirs). */
+async function assertNoSymlinkEscape(targetDir, parentDir) {
+    const realTarget = await realpath(targetDir);
+    const realParent = await realpath(parentDir);
+    if (realParent !== realTarget && !realParent.startsWith(realTarget + sep)) {
+        throw new ProviderAddUsageError(`Refusing to write through a symlinked directory: ${parentDir}`);
+    }
+}
+async function exists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function write(stream, text) {
+    stream.write(text);
+}
+//# sourceMappingURL=cli-provider-add.js.map

package/dist/cli-runner.d.ts

@@ -60,10 +60,14 @@ export interface CliRuntime {
     readonly initTemplatesRoot?: string;
     /** Override version stamped by `prism init` (tests). */
     readonly initPackageVersion?: string;
+    /** Override provider-scaffold template root (tests). */
+    readonly providerTemplatesRoot?: string;
+    /** Override version stamped by `prism providers add` (tests). */
+    readonly providerPackageVersion?: string;
     /** Working directory for relative `prism init` destinations (tests). */
     readonly cwd?: string;
 }
-export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
+export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
 export declare function parseCliArgs(argv: readonly string[]): CliOptions;
 export declare function runCli(argv: readonly string[], runtime: CliRuntime): Promise<number>;
 export declare function runPromptMode(session: AgentSession, options: CliOptions, stdout: Writable, mode: "print" | "json"): Promise<void>;

package/dist/cli-runner.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import process from "node:process";
 import { initUsage, runInitCommand } from "./cli-init.js";
+import { providerAddUsage, runProviderAddCommand } from "./cli-provider-add.js";
 import { createContributionRegistries, registerDiscoveredContributions } from "./contributions.js";
 import { createAgent, createContributionRegistry, createMockProvider, providerDone, providerTextDelta, resolveInstructionInjectors, } from "./index.js";
 import { discoverAgentBundles } from "./node/agent-definitions.js";
@@ -13,6 +14,7 @@ import { runRpcServer } from "./rpc.js";
 import { createSkillRegistry } from "./skills.js";
 export const usage = `Usage: prism [--mode print|json|rpc] [-p prompt] [options]
        prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
+       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]
 
 Options:
   -p, --prompt <text>        Prompt to run in print/json mode
@@ -209,6 +211,16 @@ export async function runCli(argv, runtime) {
         };
         return runInitCommand(argv.slice(1), initRuntime);
     }
+    if (argv[0] === "providers" && argv[1] === "add") {
+        const providerRuntime = {
+            stdout: runtime.stdout,
+            stderr: runtime.stderr,
+            ...(runtime.providerTemplatesRoot !== undefined ? { templatesRoot: runtime.providerTemplatesRoot } : {}),
+            ...(runtime.providerPackageVersion !== undefined ? { packageVersion: runtime.providerPackageVersion } : {}),
+            ...(runtime.cwd !== undefined ? { cwd: runtime.cwd } : {}),
+        };
+        return runProviderAddCommand(argv.slice(2), providerRuntime);
+    }
     let options;
     try {
         options = parseCliArgs(argv);
@@ -218,7 +230,7 @@ export async function runCli(argv, runtime) {
         return 2;
     }
     if (options.help) {
-        write(runtime.stdout, `${usage}\n${initUsage}`);
+        write(runtime.stdout, `${usage}\n${initUsage}\n${providerAddUsage}`);
         return 0;
     }
     try {

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { ArtifactApproval, ArtifactApprovalState, ArtifactBodyErrorCode, Ar
 export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.js";
 export type { ApplyCacheControlOptions, CacheControlledContentBlock, CacheControlledMessage, CacheControlValue, CacheUsageReport, } from "./cache-helpers.js";
 export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, sanitizeCacheKey } from "./cache-helpers.js";
+export type { CacheTelemetry, CacheTelemetryOptions, CacheTelemetryReport, CacheTelemetrySample, } from "./cache-telemetry.js";
+export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, DEFAULT_CACHE_TELEMETRY_CAP, createCacheTelemetry, } from "./cache-telemetry.js";
 export type { MemoryCheckpointStoreOptions } from "./checkpoints.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export type { DefaultCompactionStrategyOptions } from "./compaction.js";
@@ -105,5 +107,5 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.1.6";
+export declare const version = "0.1.7";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -6,6 +6,7 @@ export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerp
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.js";
 export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, sanitizeCacheKey } from "./cache-helpers.js";
+export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, DEFAULT_CACHE_TELEMETRY_CAP, createCacheTelemetry, } from "./cache-telemetry.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
@@ -57,6 +58,6 @@ export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MI
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.1.6";
+export const version = "0.1.7";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/docs/cli-rpc.md

@@ -36,6 +36,38 @@ prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
 
 Default generation installs only `@arnilo/prism` (mock provider). Selecting a real provider adds exactly one `@arnilo/prism-provider-*` package. Storage, telemetry, memory, and server packages are never added unless a later phase introduces an explicit flag for them. Rerunning without `--force` refuses non-empty destinations and existing generated files. `.env.example` contains placeholders only; `.gitignore` excludes `.env` and local stores.
 
+### `prism providers add` (0.1.7)
+
+```bash
+prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]
+```
+
+Scaffolds an OpenAI-compatible provider package into `./<name>`: `package.json`
+(peer dep on `@arnilo/prism`, `sideEffects: false`, publish metadata mirroring
+first-party providers), `tsconfig.json`, `README.md`, `CHANGELOG.md`,
+`src/index.ts` (`defineProviderPackage` + auth-method registration),
+`src/provider.ts` (built on `createOpenAICompatibleProvider`),
+`src/models.ts` (starter `ModelConfig` list), `src/cache.ts` (cache-hint
+mapping helpers via the shared core helpers), `src/__tests__/provider.test.ts`
+(wired to `@arnilo/prism/testing/provider-conformance`), and a
+`docs/providers/<name>.md` stub.
+
+| Flag / arg | Purpose |
+| --- | --- |
+| `<name>` | npm-validated provider/package name (lowercase); also the target directory. |
+| `--base-url <url>` | Default Chat Completions base URL (default `https://api.example.com/v1`). |
+| `--env-key <name>` | Credential environment-var identifier, e.g. `ACME_API_KEY` (default `<NAME>_API_KEY`). |
+| `--model <id>` | Starter model id (default `<name>-large`). |
+| `--force` | Overwrite generated files when the destination already exists. |
+| `-h`, `--help` | Print providers-add usage. |
+
+Scaffold output is host-chosen: it is never auto-registered into repo
+workspaces, umbrellas, or any resolver. The generated conformance test is
+offline (mock fetch) and proves stream shape, tool-call delta reconstruction,
+header ownership, secret-leak redaction, and serialized-content coverage
+against the base provider. Replace the starter model metadata and the docs
+stub with docs-verified values before publishing.
+
 ### Run/RPC CLI flags
 
 | Flag | Purpose |
@@ -181,6 +213,7 @@ Suspended workflow resume parameters are `{ workflowId, runId, decision: "approv
 - JSONL is processed line by line with Node stdlib; no parser dependency, worker, watcher, or queue is added.
 - Unknown or malformed CLI/RPC input fails closed. Workflow resume validates decision and positive `expectedVersion`; ownership remains host-selected and checkpoint-enforced.
 - `prism init` refuses non-empty destinations without `--force`, keeps writes inside the destination root, and never executes downloaded code beyond the user's later `npm install`.
+- `prism providers add` validates the name against npm package-name rules (lowercase, no separators or `..`), refuses path traversal and symlinked directories escaping the destination, validates `--base-url` as an http(s) URL and `--env-key` as a shell-safe identifier, and writes placeholders only — generated code never contains secrets.
 - Generated `.env.example` values are placeholders only; `.gitignore` excludes `.env` and local store files.
 - Default generated install stays small (~27 MB with TypeScript tooling in a clean consumer install versus Mastra's measured 439 MB scaffold); unselected storage/telemetry/eval/workflow packages are omitted.
 - Branch handles (`handleId`, `sessionId`, `leafId`) are identifiers only; do not encode credentials, tokens, provider objects, or secrets into them.