@arnilo/prism 0.1.5 → 0.1.7

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/contracts-run-state.d.ts

@@ -156,6 +156,17 @@ export interface AgentRunStateOptions {
      * Default off: checkpoint shape is identical to 0.1.2.
      */
     readonly persistSessionState?: boolean;
+    /**
+     * Opt-in (plan 018 Task 6 closeout `checkpoint-bodies`): alongside
+     * `persistSessionState`, persist the exact loaded-skill instructions
+     * (`{name, instructions}` pairs, redacted at the checkpoint boundary like all state)
+     * so resume re-renders them registry-independently — no `load_skill` round-trip, no
+     * drift when the live registry changed or lost the skill. Both the run and the resume
+     * options must set it. Bounds: ≤64 bodies, ≤256-char names, ≤262144-byte bodies,
+     * ≤1 MiB total; the `maxStateBytes` ceiling refuses oversize with a recorded error
+     * (never silently truncates). Default off: checkpoint shape is identical to 0.1.3.
+     */
+    readonly includeSkillBodies?: boolean;
 }
 /** Versioned, redacted checkpoint payload. Treat as opaque except status/version/interruption. */
 export interface AgentRunState {
@@ -188,6 +199,8 @@ export interface AgentRunResumeOptions {
     readonly resumeNestedRun?: ResumeNestedRun;
     /** Opt-in (plan 015 Task 4): restore persisted loaded-skill names into the resumed session catalog. */
     readonly persistSessionState?: boolean;
+    /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */
+    readonly includeSkillBodies?: boolean;
 }
 /** Bounded, abortable options for `resumeAgentRunStream()`. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {

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";
@@ -86,8 +88,8 @@ export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries,
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
 export type { LoadedSkillSet, SkillRenderContext, SkillsDisclosure } from "./skill-disclosure.js";
 export { createLoadedSkillSet, DEFAULT_MAX_SKILL_CATALOG_ENTRIES, DEFAULT_MAX_SKILL_DESCRIPTION_BYTES, DEFAULT_MAX_SKILL_INSTRUCTION_BYTES, EMPTY_SKILL_DESCRIPTION, HARD_MAX_SKILL_CATALOG_ENTRIES, HARD_MAX_SKILL_DESCRIPTION_BYTES, HARD_MAX_SKILL_INSTRUCTION_BYTES, isSkillDisclosureError, resolveSkillsDisclosure, SkillDisclosureError, } from "./skill-disclosure.js";
-export type { CreateLoadSkillToolOptions, ResolveSkillLoadOptions } from "./skill-load.js";
-export { createLoadSkillTool, DEFAULT_LOAD_SKILL_TOOL_NAME, isSkillLoadError, MAX_LOAD_SKILL_RESULT_BYTES, resolveSkillLoad, SKILL_LOAD_ERROR_CODE, SkillLoadError, } from "./skill-load.js";
+export type { CreateLoadSkillToolOptions, LoadedSkillBodiesEntry, ResolveSkillLoadOptions, } from "./skill-load.js";
+export { applyRestoredSkillBodies, createLoadSkillTool, DEFAULT_LOAD_SKILL_TOOL_NAME, HARD_MAX_PERSISTED_SKILL_BODY_TOTAL_BYTES, isSkillLoadError, MAX_LOAD_SKILL_RESULT_BYTES, MAX_PERSISTED_SKILL_BODIES, MAX_PERSISTED_SKILL_BODY_BYTES, MAX_PERSISTED_SKILL_BODY_NAME_CHARS, resolveSkillLoad, SKILL_LOAD_ERROR_CODE, SkillLoadError, snapshotLoadedSkillBodies, validateLoadedSkillBodies, } from "./skill-load.js";
 export type { ResolveActiveSkillsOptions, SkillRegistryOptions } from "./skills.js";
 export { createSkillRegistry, resolveActiveSkills } from "./skills.js";
 export { artifactStructuredOutputRequest, assertStructuredOutputRequestSupported, DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH, DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES, modelSupportsStructuredOutput, resolveRunProviderOptions, StructuredOutputError, validateStructuredOutputOptions, withoutStructuredOutput, } from "./structured-output.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.5";
+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";
@@ -46,7 +47,7 @@ export { assertPermission, assertTrusted, checkPermission, createStaticPermissio
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext, } from "./session-stores.js";
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
 export { createLoadedSkillSet, DEFAULT_MAX_SKILL_CATALOG_ENTRIES, DEFAULT_MAX_SKILL_DESCRIPTION_BYTES, DEFAULT_MAX_SKILL_INSTRUCTION_BYTES, EMPTY_SKILL_DESCRIPTION, HARD_MAX_SKILL_CATALOG_ENTRIES, HARD_MAX_SKILL_DESCRIPTION_BYTES, HARD_MAX_SKILL_INSTRUCTION_BYTES, isSkillDisclosureError, resolveSkillsDisclosure, SkillDisclosureError, } from "./skill-disclosure.js";
-export { createLoadSkillTool, DEFAULT_LOAD_SKILL_TOOL_NAME, isSkillLoadError, MAX_LOAD_SKILL_RESULT_BYTES, resolveSkillLoad, SKILL_LOAD_ERROR_CODE, SkillLoadError, } from "./skill-load.js";
+export { applyRestoredSkillBodies, createLoadSkillTool, DEFAULT_LOAD_SKILL_TOOL_NAME, HARD_MAX_PERSISTED_SKILL_BODY_TOTAL_BYTES, isSkillLoadError, MAX_LOAD_SKILL_RESULT_BYTES, MAX_PERSISTED_SKILL_BODIES, MAX_PERSISTED_SKILL_BODY_BYTES, MAX_PERSISTED_SKILL_BODY_NAME_CHARS, resolveSkillLoad, SKILL_LOAD_ERROR_CODE, SkillLoadError, snapshotLoadedSkillBodies, validateLoadedSkillBodies, } from "./skill-load.js";
 export { createSkillRegistry, resolveActiveSkills } from "./skills.js";
 export { artifactStructuredOutputRequest, assertStructuredOutputRequestSupported, DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH, DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES, modelSupportsStructuredOutput, resolveRunProviderOptions, StructuredOutputError, validateStructuredOutputOptions, withoutStructuredOutput, } from "./structured-output.js";
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.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.5";
+export const version = "0.1.7";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/skill-load.d.ts

@@ -3,6 +3,29 @@ import { type LoadedSkillSet } from "./skill-disclosure.js";
 export declare const DEFAULT_LOAD_SKILL_TOOL_NAME: "load_skill";
 export declare const SKILL_LOAD_ERROR_CODE: "skill_load_failed";
 export declare const MAX_LOAD_SKILL_RESULT_BYTES = 512;
+export declare const MAX_PERSISTED_SKILL_BODIES = 64;
+export declare const MAX_PERSISTED_SKILL_BODY_NAME_CHARS = 256;
+export declare const MAX_PERSISTED_SKILL_BODY_BYTES = 262144;
+export declare const HARD_MAX_PERSISTED_SKILL_BODY_TOTAL_BYTES: number;
+/** One persisted loaded-skill body (plan 018 closeout `checkpoint-bodies`). */
+export interface LoadedSkillBodiesEntry {
+    readonly name: string;
+    readonly instructions: string;
+}
+/** Fail-closed shape/cap validation for a persisted bodies payload (load and save sides). */
+export declare function validateLoadedSkillBodies(value: unknown): asserts value is readonly LoadedSkillBodiesEntry[];
+/**
+ * Snapshot the exact instructions of every loaded skill (registry-independent).
+ * Loaded names without instructions are skipped (they render no body anyway);
+ * a restored body for a loaded name wins over the registry body.
+ */
+export declare function snapshotLoadedSkillBodies(skills: readonly Skill[], loaded: LoadedSkillSet, restored?: ReadonlyMap<string, string>): LoadedSkillBodiesEntry[];
+/**
+ * Apply persisted bodies to the skills a resumed session will render: replace the
+ * instructions of known skills and append synthesized skills for names the live
+ * registry no longer serves, so the exact loaded text renders registry-independently.
+ */
+export declare function applyRestoredSkillBodies(skills: readonly Skill[], bodies: readonly LoadedSkillBodiesEntry[]): readonly Skill[];
 export declare class SkillLoadError extends Error {
     readonly code: "skill_load_failed";
     constructor(message: string);

package/dist/skill-load.js

@@ -3,6 +3,80 @@ import { HARD_MAX_SKILL_INSTRUCTION_BYTES } from "./skill-disclosure.js";
 export const DEFAULT_LOAD_SKILL_TOOL_NAME = "load_skill";
 export const SKILL_LOAD_ERROR_CODE = "skill_load_failed";
 export const MAX_LOAD_SKILL_RESULT_BYTES = 512;
+// Bodies-mode persistence bounds (plan 018 Task 6 closeout `checkpoint-bodies`): the
+// checkpoint `maxStateBytes` ceiling is the documented outer bound (oversize refuses at
+// save with a recorded error); these caps bound the bodies payload itself on load.
+// ponytail: module constants, not tunable options — hosts tune maxStateBytes for the ceiling.
+export const MAX_PERSISTED_SKILL_BODIES = 64; // names-mode parity (MAX_PERSISTED_SKILL_NAMES)
+export const MAX_PERSISTED_SKILL_BODY_NAME_CHARS = 256; // names-mode parity
+export const MAX_PERSISTED_SKILL_BODY_BYTES = 262_144; // = HARD_MAX_SKILL_INSTRUCTION_BYTES (loader parity)
+export const HARD_MAX_PERSISTED_SKILL_BODY_TOTAL_BYTES = 1024 * 1024; // = HARD_MAX_AGENT_RUN_STATE_BYTES
+/** Fail-closed shape/cap validation for a persisted bodies payload (load and save sides). */
+export function validateLoadedSkillBodies(value) {
+    if (!Array.isArray(value) || value.length > MAX_PERSISTED_SKILL_BODIES) {
+        throw new SkillLoadError(`Loaded-skill bodies exceed ${MAX_PERSISTED_SKILL_BODIES} entries`);
+    }
+    let totalBytes = 0;
+    for (const entry of value) {
+        if (!entry || typeof entry !== "object" || typeof entry.name !== "string") {
+            throw new SkillLoadError("Malformed loaded-skill body entry: name must be a string");
+        }
+        const { name, instructions } = entry;
+        if (name.length > MAX_PERSISTED_SKILL_BODY_NAME_CHARS) {
+            throw new SkillLoadError(`Loaded-skill body name exceeds ${MAX_PERSISTED_SKILL_BODY_NAME_CHARS} chars`);
+        }
+        if (typeof instructions !== "string") {
+            throw new SkillLoadError("Malformed loaded-skill body entry: instructions must be a string");
+        }
+        const bodyBytes = Buffer.byteLength(instructions, "utf8");
+        if (bodyBytes > MAX_PERSISTED_SKILL_BODY_BYTES) {
+            throw new SkillLoadError(`Loaded-skill body exceeds ${MAX_PERSISTED_SKILL_BODY_BYTES} bytes`);
+        }
+        totalBytes += Buffer.byteLength(name, "utf8") + bodyBytes;
+        if (totalBytes > HARD_MAX_PERSISTED_SKILL_BODY_TOTAL_BYTES) {
+            throw new SkillLoadError(`Loaded-skill bodies exceed ${HARD_MAX_PERSISTED_SKILL_BODY_TOTAL_BYTES} total bytes`);
+        }
+    }
+}
+/**
+ * Snapshot the exact instructions of every loaded skill (registry-independent).
+ * Loaded names without instructions are skipped (they render no body anyway);
+ * a restored body for a loaded name wins over the registry body.
+ */
+export function snapshotLoadedSkillBodies(skills, loaded, restored) {
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+    const entries = [];
+    for (const name of loaded.list()) {
+        const instructions = restored?.get(name) ?? byName.get(name)?.instructions;
+        if (!instructions)
+            continue;
+        entries.push({ name, instructions });
+    }
+    validateLoadedSkillBodies(entries); // refuses oversize with a recorded error (never truncates)
+    return entries;
+}
+/**
+ * Apply persisted bodies to the skills a resumed session will render: replace the
+ * instructions of known skills and append synthesized skills for names the live
+ * registry no longer serves, so the exact loaded text renders registry-independently.
+ */
+export function applyRestoredSkillBodies(skills, bodies) {
+    validateLoadedSkillBodies(bodies);
+    if (bodies.length === 0)
+        return skills;
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+    const out = skills.map((skill) => {
+        const body = bodies.find((entry) => entry.name === skill.name);
+        return body ? { ...skill, instructions: body.instructions } : skill;
+    });
+    const known = new Set(skills.map((skill) => skill.name));
+    for (const entry of bodies) {
+        if (!known.has(entry.name)) {
+            out.push({ name: entry.name, instructions: entry.instructions });
+        }
+    }
+    return out;
+}
 export class SkillLoadError extends Error {
     code = SKILL_LOAD_ERROR_CODE;
     constructor(message) {

package/docs/acp.md

@@ -111,7 +111,7 @@ const agent = createPrismAcpAgent({
 
 ### Persistence and ownership
 
-- **The agent never persists `modeId`/`configValues`.** Defaults are recomputed per session from the `modes`/`configOptions` seams — a fresh `session/new`, `load`, or `resume` always starts from `defaultModeId` / option `defaultValue`, and the agent's per-session registry is in-memory only. Persisting mode/config across sessions is a **host** decision, and host-side persistence MUST be ownership-scoped.
+- **Without the durability seam the agent never persists `modeId`/`configValues`.** Defaults are recomputed per session from the `modes`/`configOptions` seams — a fresh `session/new`, `load`, or `resume` always starts from `defaultModeId` / option `defaultValue`, and the agent's per-session registry is in-memory only. Persisting mode/config across sessions is a **host** decision, and host-side persistence MUST be ownership-scoped.
 - **Host persistence MUST key by `sessions.ownership`.** `authorize` binds transport identity to ownership; a host store that persists `modeId`/`configValues` must refuse any restore whose stored ownership differs from the current session's ownership — a `sessionId` alone is never a sufficient key (session ids may collide across tenants). A cross-tenant restore rejects with `ERR_PRISM_ACP_INPUT` and never returns the other tenant's mode/config.
 - **Ownership-scoped restore (host-owned store).** The store is keyed by `sessionId` and records the owning `userId`; restore refuses on mismatch (this exact pattern is asserted in `packages/ag-ui/src/__tests__/acp-modes-config.test.ts`):
 
@@ -133,7 +133,7 @@ const agent = createPrismAcpAgent({
   ```
 
   Because the agent recomputes defaults on every `load`/`resume`, a host that restores state re-applies it after load through the same gated seams (`session/set_mode`, `session/set_config_option` — both run the `apply`/`onChange` hooks) and must refuse cross-tenant loads at the `authorize` seam first (falsy `authorize` = `Unauthorized ACP session`, before any mode/config state is reachable).
-- **Agent-owned persistence is 0.2.0.** A durable, ownership-scoped ACP session store (agent-side persistence of mode/config and session state) is roadmap 0.2.0 Module E, demand-gated; on the 0.1.x line the agent stays a thin per-session registry. See the [Host security guide](host-security.md) fail-closed checklist for the ACP boundary rows.
+- **Durable registry (0.1.6, plan 018 closeout `acp-session-store`).** Pass `sessionStore` (`AcpSessionStore` from `@arnilo/prism-ag-ui/acp`) to let a restarted agent restore its live-session registry: `save` (on `session/new`, `set_mode`, `set_config_option`), `loadAll` (once per agent instance, lazily on first authorized touch), `evict` (on `close`/`delete`). The stored entry carries `sessionId`, `ownership`, `modeId`, `configValues`, `cwd`, `additionalDirectories`, `updatedAt` — never ephemeral stream state (client/controller/budget) or pending decisions. Restore re-resolves the live `AgentSession` through your `sessionFactory`, re-validates cwd/directories and mode/config values against the seams, enforces the registry cap, and drops corrupt or seam-mismatched entries fail-closed. The seam is additive-only: absent `sessionStore` ⇒ the agent behaves exactly as 0.1.5. Storage topology stays host-owned; the store is the trust boundary for tampering/replay. The full threat model and test mapping live in `docs/_evidence/phase18-primitive-review.md`; enforcement tests in `packages/ag-ui/src/__tests__/acp-session-store.test.ts`. The host-owned mode/config store pattern above stays valid for hosts that persist without the agent seam.
 
 ## Security and performance notes
 

package/docs/agent-session-runtime.md

@@ -198,7 +198,7 @@ if (result.status === "suspended") {
 }
 ```
 
-Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. The fingerprint hashes the agent id/name, `definitionRevision`, model, instructions, system-prompt contributions, skills (name/instructions/tool names), tool definitions (name/parameters/exclusive), guardrail definitions (name/stage/revision), and loop strategy — changing any of them without bumping `definitionRevision` fails resume closed instead of silently continuing with different agent semantics. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. State is bounded at save by `runState.maxStateBytes` (default 256 KB, at most the 1 MB hard cap); load bounds against the 1 MB hard cap only, so state saved with a raised limit stays resumable while oversized records are still rejected. Since 0.1.3 (plan 015 Task 4), durable runs may opt in to session-state persistence with `persistSessionState: true` on both the run and resume options: the loaded-skill **name catalog** (≤64 names, ≤256 chars each) rides the checkpoint and is restored into the resumed session's `LoadedSkillSet`; skill **bodies are never persisted** and re-resolve from the live registry via `load_skill`. Default off keeps the checkpoint shape byte-identical to 0.1.2. Built-in loop options are durable; custom `AgentLoopStrategy` instances are durable when they declare `snapshot`/`restore` hooks (see [Agent loops § Durable runs](agent-loops.md#durable-runs)) and reject before provider work otherwise.
+Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. The fingerprint hashes the agent id/name, `definitionRevision`, model, instructions, system-prompt contributions, skills (name/instructions/tool names), tool definitions (name/parameters/exclusive), guardrail definitions (name/stage/revision), and loop strategy — changing any of them without bumping `definitionRevision` fails resume closed instead of silently continuing with different agent semantics. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. State is bounded at save by `runState.maxStateBytes` (default 256 KB, at most the 1 MB hard cap); load bounds against the 1 MB hard cap only, so state saved with a raised limit stays resumable while oversized records are still rejected. Since 0.1.3 (plan 015 Task 4), durable runs may opt in to session-state persistence with `persistSessionState: true` on both the run and resume options: the loaded-skill **name catalog** (≤64 names, ≤256 chars each) rides the checkpoint and is restored into the resumed session's `LoadedSkillSet`; skill **bodies are never persisted** and re-resolve from the live registry via `load_skill`. Since 0.1.6 (plan 018 closeout `checkpoint-bodies`), `includeSkillBodies: true` on BOTH the run and resume options additionally persists the exact loaded-skill **instructions** (`{name, instructions}` pairs, redacted at the checkpoint boundary like all state, ≤64 bodies / ≤256-char names / ≤262144-byte bodies / ≤1 MiB total) so resume re-renders them registry-independently — no `load_skill` round-trip and no dependence on the registry still serving the same text; `maxStateBytes` (default 256 KB) refuses oversize bodies with a recorded error, never silently truncates. Default off keeps the checkpoint shape byte-identical to 0.1.3. Built-in loop options are durable; custom `AgentLoopStrategy` instances are durable when they declare `snapshot`/`restore` hooks (see [Agent loops § Durable runs](agent-loops.md#durable-runs)) and reject before provider work otherwise.
 
 ## Secure composition
 

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.