@arnilo/prism 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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
+- **Release 0.1.6 (plan 018)** is the coding-agent capability-closeouts patch on the frozen 0.1.x line — five demand-gated closeouts, all shipped, additive-only vs 0.1.5 (freeze manifest `scripts/phase18-freeze-manifest.json`; every closeout flipped to `demanded` by named demand evidence before its task landed, then the demand-gate registry validated demanded ⇒ implemented, deferred ⇒ untouched). (1) **Durable ACP session store** (`acp-session-store`): `@arnilo/prism-ag-ui` gains the host-owned `AcpSessionStore` seam on `CreatePrismAcpAgentOptions` — `save` (upsert on session/new, set_mode, set_config_option, never on cancel/prompt-end), `loadAll` (lazy, once per agent instance, after authorization, cross-tenant entries refused `ERR_PRISM_ACP_INPUT`), `evict` (on close/delete); the persisted entry shape `{sessionId, ownership, modeId, configValues, cwd, additionalDirectories, updatedAt}` deliberately excludes client/controller/budget/pending state; fail-closed restore drops corrupt/oversized entries, re-validates modes/config options, keeps the in-memory registry caps (32 default / 128 hard), and re-resolves the live session binding; absent seam = byte-identical 0.1.5 in-memory behavior; the whole persisted entry rides the optional `SecretRedactor` at the save boundary. (2) **Network-free native sandbox backend** (`native-sandbox`): `@arnilo/prism-coding-security` gains `createNativeSandbox` — spawn + POSIX rlimits + existing path containment, zero new dependencies; every command runs in a fresh network namespace via the OS `unshare` binary (plain or `--map-root-user` preflighted once at creation, fail-closed on macOS/Windows and where netns cannot be created), ulimit chains (`-v`/`-t`/`-n`) with `|| exit 126`, argv-only `exec` (never shell-interpolated), cwd containment via `assertPathInsideRoots`, process-group kill on timeout/abort, env allow-list (host env never inherited), output cap, `close({export})` tar parity, and a documented honest boundary (runs as the invoking OS user; egress denial + rlimits + cwd containment only). (3) **Bounded PDF/Office document reader** (`doc-reader`): new optional package `@arnilo/prism-document-reader` (the 50th publishable manifest) — `createDocumentReader({ maxBytes, maxPages, maxTextBytes, parsers })` behind optional peer parsers `pdf-parse`/`mammoth` (dynamic-import, fail-closed at creation with an install hint when absent), magic-byte format gating (never extension sniffing), null fall-through to the 0.1.5 text path, refuse-over-truncate for over-page PDFs, byte-safe text truncation, optional `SecretRedactor` at the adapter boundary, no embedded-content execution, no external resource fetch (egress tripwire test), extraction envelope recorded in `scripts/budgets.json`; `createReadTool` gains the additive `documentReader` slot with input/page/text caps re-checked in the read flow. (4) **Recursive delete + brace-expanding glob** (`delete-glob`): `delete` gains the per-call opt-in `recursive: true` (symlink children unlinked never followed, iterative post-order walk, per-call fan-out cap 10,000 default / 100,000 hard, partial deletion reported never silent, `maxEntries` bound); `glob` gains host-selected + per-call `braceExpansion` (`{a,b}` textual expansion, max 128 alternatives / 4096 expanded bytes, unbalanced/nested/empty braces and overflow fail closed, default matcher semantics unchanged). (5) **Checkpoint persistence for loaded-skill bodies** (`checkpoint-bodies`): durable runs may set `includeSkillBodies: true` on BOTH run and resume options (alongside `persistSessionState`) — the exact loaded-skill instructions ride the checkpoint (`{name, instructions}` pairs, ≤64 bodies / ≤256-char names / ≤262144-byte bodies / ≤1 MiB total, validated fail-closed on save and load, redacted at rest) so resume re-renders them registry-independently with no `load_skill` round-trip; names-only stays the default and 0.1.3/0.1.2 checkpoint shapes are byte-identical; `maxStateBytes` refuses oversize bodies with a recorded error, never truncates. Release graph **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.6**. Exit gate green (core 1,433/1,433 + 190 script gates incl. phase18-freeze done-phase, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain compat gate at 0.1.6 with 0 breaking deltas then version-literal baseline refresh, evidence in `scripts/phase18-baseline.json`). Store compatibility with 0.1.5: **compatible, no migration** (additive-only; no persisted-shape change). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.1.6 publish handoff` — signed `v0.1.6` tag + npm OIDC).
+
 ## [0.1.5] - 2026-08-11
 
 ### Changed

package/dist/agent-run-lifecycle.d.ts

@@ -20,6 +20,8 @@ export interface AgentRunLifecycleRequest {
     readonly agentId?: string;
     /** Opt-in (plan 015 Task 4): restore persisted loaded-skill names on resume. */
     readonly persistSessionState?: boolean;
+    /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies on resume (requires `persistSessionState` too). */
+    readonly includeSkillBodies?: boolean;
 }
 /** Bounded live-event options for a durable lifecycle resume. */
 export interface AgentRunLifecycleStreamRequest extends AgentRunLifecycleRequest, SubscribeOptions {

package/dist/agent-run-lifecycle.js

@@ -28,6 +28,7 @@ export function createAgentRunLifecycle(options) {
                 fencingToken: options.fencingToken,
                 definitionRevision: resolved.definitionRevision,
                 persistSessionState: request.persistSessionState,
+                includeSkillBodies: request.includeSkillBodies,
             });
         },
         async *resumeStream(ref, resume, request = {}) {
@@ -45,6 +46,7 @@ export function createAgentRunLifecycle(options) {
                 maxQueuedEvents: request.maxQueuedEvents,
                 overflow: request.overflow,
                 persistSessionState: request.persistSessionState,
+                includeSkillBodies: request.includeSkillBodies,
             });
         },
     };
@@ -95,6 +97,11 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     if (options.persistSessionState && state.sessionState?.loadedSkillNames) {
         session.restoreLoadedSkills(state.sessionState.loadedSkillNames);
     }
+    // Plan 018 Task 6 (closeout `checkpoint-bodies`): restore exact instructions so the
+    // resumed session renders them registry-independently (no load_skill round-trip).
+    if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {
+        session.restoreLoadedSkillBodies(state.sessionState.loadedSkillBodies);
+    }
     if (resume.decision !== undefined && resume.decisions !== undefined) {
         throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume accepts exactly one of decision or decisions");
     }

package/dist/agent-run-state.d.ts

@@ -1,5 +1,6 @@
 import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, AgentRunStatusResult, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
+import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export declare const AGENT_RUN_STATE_SCHEMA_VERSION: 1;
 export declare const DEFAULT_MAX_AGENT_RUN_STATE_BYTES: number;
@@ -41,6 +42,7 @@ export interface StoredAgentRunState extends AgentRunState {
      */
     readonly sessionState?: {
         readonly loadedSkillNames?: readonly string[];
+        readonly loadedSkillBodies?: readonly LoadedSkillBodiesEntry[];
     };
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */

package/dist/agent-run-state.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
+import { validateLoadedSkillBodies } from "./skill-load.js";
 export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export const AGENT_RUN_STATE_SCHEMA_VERSION = 1;
 export const DEFAULT_MAX_AGENT_RUN_STATE_BYTES = 256 * 1024;
@@ -241,6 +242,15 @@ function validateSessionState(sessionState) {
     if (!sessionState || typeof sessionState !== "object") {
         throw new AgentRunStateError("Malformed agent run session state");
     }
+    const bodies = sessionState.loadedSkillBodies;
+    if (bodies !== undefined) {
+        try {
+            validateLoadedSkillBodies(bodies);
+        }
+        catch (error) {
+            throw new AgentRunStateError(error instanceof Error ? error.message : String(error));
+        }
+    }
     const names = sessionState.loadedSkillNames;
     if (names === undefined)
         return;

package/dist/agent-session.d.ts

@@ -1,6 +1,7 @@
 import { type StoredAgentRunState } from "./agent-run-state.js";
 import type { Agent, AgentConfig, AgentEvent, AgentRunResult, AgentRunStateOptions, AgentSession, AgentSessionConfig, CompactionOptions, CompactionResult, OwnershipScope, RunDecision, RunOptions, SessionEntry, SteerOptions, SubscribeOptions } from "./contracts.js";
 import { type AgentInput } from "./input.js";
+import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare function createAgent(config: AgentConfig): Agent;
 export declare function createAgentSession(config: AgentSessionConfig & {
     readonly agent: Agent;
@@ -36,8 +37,14 @@ export declare class RuntimeAgentSession implements AgentSession {
     private activeGatedRound?;
     private activeLoopTurn;
     private readonly loadedSkills;
+    /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
+    private restoredSkillBodies;
+    /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
+    private activeRunSkills;
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names: readonly string[]): void;
+    /** Plan 018 Task 6: restore persisted loaded-skill bodies (already validated fail-closed at load). */
+    restoreLoadedSkillBodies(bodies: readonly LoadedSkillBodiesEntry[]): void;
     private ledgerChain;
     private ledgerFailure;
     private snapshotGeneration;

package/dist/agent-session.js

@@ -16,6 +16,7 @@ import { RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.j
 import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext, } from "./session-stores.js";
 import { resolveActiveSkills } from "./skills.js";
 import { createLoadedSkillSet, resolveSkillsDisclosure } from "./skill-disclosure.js";
+import { applyRestoredSkillBodies, snapshotLoadedSkillBodies, validateLoadedSkillBodies, } from "./skill-load.js";
 import { resolveToolResultFold } from "./tool-result-fold.js";
 import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "./structured-output.js";
 import { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
@@ -65,11 +66,22 @@ export class RuntimeAgentSession {
     activeGatedRound;
     activeLoopTurn = 1;
     loadedSkills = createLoadedSkillSet();
+    /** Plan 018 Task 6 (closeout `checkpoint-bodies`): persisted exact instructions, registry-independent. */
+    restoredSkillBodies = [];
+    /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
+    activeRunSkills = [];
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names) {
         for (const name of names)
             this.loadedSkills.add(name);
     }
+    /** Plan 018 Task 6: restore persisted loaded-skill bodies (already validated fail-closed at load). */
+    restoreLoadedSkillBodies(bodies) {
+        validateLoadedSkillBodies(bodies);
+        this.restoredSkillBodies = bodies;
+        for (const entry of bodies)
+            this.loadedSkills.add(entry.name);
+    }
     ledgerChain = Promise.resolve();
     ledgerFailure;
     snapshotGeneration = 0;
@@ -255,6 +267,7 @@ export class RuntimeAgentSession {
             await this.rebuildHistory();
             const { registry, tools } = activeTools(this.agent.config.tools);
             const activeSkills = this.resolveRunSkills(options, tools);
+            this.activeRunSkills = activeSkills; // for the durable bodies snapshot (plan 018 Task 6)
             if (options.model && JSON.stringify(options.model) !== JSON.stringify(this.agent.config.model)) {
                 await this.appendEntry(createSessionEntry({
                     sessionId: this.id,
@@ -464,7 +477,7 @@ export class RuntimeAgentSession {
                         inputBuilder: this.agent.config.inputBuilder,
                         promptBuilder: this.agent.config.promptBuilder,
                         contextProviders,
-                        skills: activeSkills,
+                        skills: this.restoredSkillBodies.length ? applyRestoredSkillBodies(activeSkills, this.restoredSkillBodies) : activeSkills,
                         skillsDisclosure: resolveSkillsDisclosure(options.skillsDisclosure, this.agent.config.skillsDisclosure),
                         toolResultFold: resolveToolResultFold(options.toolResultFold, this.agent.config.toolResultFold),
                         loadedSkills: this.loadedSkills,
@@ -1108,7 +1121,17 @@ export class RuntimeAgentSession {
         if (!durable)
             throw new AgentRunStateError("Durable run state is not configured");
         const persisted = durable.options.persistSessionState
-            ? { ...state, sessionState: { loadedSkillNames: this.loadedSkills.list() } }
+            ? {
+                ...state,
+                sessionState: {
+                    loadedSkillNames: this.loadedSkills.list(),
+                    ...(durable.options.includeSkillBodies
+                        ? {
+                            loadedSkillBodies: snapshotLoadedSkillBodies(this.activeRunSkills, this.loadedSkills, this.restoredSkillBodies.length ? new Map(this.restoredSkillBodies.map((e) => [e.name, e.instructions])) : undefined),
+                        }
+                        : {}),
+                },
+            }
             : state;
         const saved = await saveAgentRunState({
             checkpoints: durable.options.checkpoints,

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;