@arnilo/prism 0.1.6 → 0.2.0

package/docs/release-and-install.md

@@ -274,6 +274,49 @@ git push origin v0.1.2        # tag push triggers release.yml publish job (prove
 
 **Rollback notes.** `release:publish --version 0.1.2 --resume --report release-artifacts/publish-report.json` resumes an interrupted publication and skips only registry versions whose internal dependency fingerprint matches the local manifest. A failed package aborts the run with its status written to the report; re-run after fixing the cause. npm cannot unpublish the `0.1.2` line after 72 hours — a post-publication defect ships as a `0.1.x` patch (additive-only compat promise, `release:gate` enforced), or as a documented break in the next line with a `docs/migration.md` entry. `0.1.2` is store-compatible with `0.1.1` in **both directions** (no migration ran — same checksum-protected contract), so an operator may defer or roll back the patch without a database rollback.
 
+### 0.2.0 publish handoff (plan 020 Task 6)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.2.0** (plan 020) is the first cut of the 0.2.x review-remediation line — fail-closed runtime and sandbox security. API surface **additive-only** vs 0.1.7 (plain compat gate at 0.2.0: 0 breaking declaration deltas — the three blockers are behavior tightenings, not removals; `containmentClaim` retained deprecated; baseline text regenerated with `--update-baseline`, no `--allow-break` anywhere; freeze manifest `scripts/phase20-freeze-manifest.json` machine-checks each task's diff stayed inside its allowed files). Shipped: (1) **durable-resume input validation** — `assertValidAgentRunResume` at the top of `prepareAgentRunResume` covers all four public resume entrypoints; unknown legacy decisions (`"sideways"`), malformed batches, oversized reasons/elicitation, duplicate approval ids fail closed `ERR_PRISM_DECISION_*` with zero checkpoint writes/tool calls (server parser stays defense in depth); (2) **work-tool environment isolation** — `createCliRunner` children get a fixed base allow-list + explicit env + forced HOME/telemetry controls + late-bound per-identity tokens, 64-name/64-KiB caps `ERR_PRISM_WORK_ENV`, absolute binary/configDir, linear output capture; (3) **explicit sandbox capabilities** — `SandboxAdapter.capabilities` (six immutable booleans, omission/malformed ⇒ all false), composition capabilities from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege false; docs/coding-security.md capability table, docs/host-security.md authorization guidance. New regression surface: `scripts/phase20-security.test.mjs` (public built entrypoints, wired into `security:threat-suites`), packed plain-JS consumer regressions in install-smoke, and the sandbox-browser workflow's fail-loud 0.2.0 blocker gate recording Docker/native capability evidence — **0.2.0 does not ship while any blocker is skipped**. Store compatibility with 0.1.7: **compatible, no migration** (no persisted-shape change; `docs/migration.md` `0.1.7 → 0.2.0` section). Exit gate green: npm test core + script gates (incl. phase20-freeze done-phase), `sdk:ready` exit 0, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.0, Docker daemon + native netns protected evidence; evidence in `scripts/phase20-baseline.json` `exitGate`. Rollback = restore the 0.1.7 manifests/tag — but rollback restores the three defects, so hosts should disable resume side effects and work-tool execution at their own boundary if rollback is unavoidable.
+
+```bash
+# Operator prerequisites recorded: clean tree at the v0.2.0 tag candidate, GPG key, npm OIDC publisher.
+npm test                                        # core + workspace suites + all script gates
+npm run security:threat-suites                  # phase8-11 + phase20 public-entry conformance
+npm run sdk:ready                               # typecheck, lint, format, test, coverage, pack, release:gate
+node scripts/release.mjs gate --version 0.2.0   # plain reviewed additive gate, 0 breaking deltas
+npm run pack:dry-run                            # twice; diff reports — deterministic
+npm audit --audit-level=moderate
+npm run release:check -- --version 0.2.0 --report /tmp/prism-0.2.0-preflight.json
+npm run release:publish -- --version 0.2.0 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.2.0-dry-run.json
+#   run the dry-run twice and diff the reports: deterministic, byte-identical
+```
+
+Protected evidence (never a passing skip): `docker info` + digest-pinned image (e.g. `PRISM_TEST_DOCKER_SANDBOX=1 PRISM_TEST_DOCKER_BIN=/usr/bin/docker PRISM_TEST_DOCKER_IMAGE=ubuntu@sha256:... npm test -w @arnilo/prism-coding-security -- --test-name-pattern "protected Docker"`) and native netns capability (`unshare --net` / `--net --map-root-user` must succeed; T9 native capability test runs, not skips). The sandbox-browser workflow fails loudly when this evidence is missing.
+
+### 0.1.7 publish handoff (plan 019 Task 6)
+
+**Decision: GO when the operator prerequisites below are recorded.** 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 (plain compat gate at 0.1.7 passed with 0 breaking declaration deltas; the baseline text was regenerated with `--update-baseline` for the version literal only, no `--allow-break` anywhere; freeze manifest `scripts/phase19-freeze-manifest.json` machine-checks each task's diff stayed inside its allowed files). Shipped: (1) **prompt-cache telemetry surface** — dependency-free `createCacheTelemetry()` aggregator in core, host-activated, per-provider/model request counts + aggregate hit rate + cache-read/write token totals + estimated savings, bounded cardinality (cap 256 distinct keys, `__overflow__` bucket), token counters/rates only (never prompt content, cache keys, or identity), O(1) `record()`; (2) **model-router selection policies** — additive `ModelRouterSelectionPolicy` on `createModelRouter` (default ordered behavior byte-identical) with the reference `createCostLatencySelection` ranking by `ModelCost` then in-memory latency EMA fed from `recordOutcome({ latencyMs })`, permutation-only reorder of already-allowed candidates, misbehavior fails closed `ERR_PRISM_MODEL_ROUTER_POLICY`; (3) **async AgUiProjection closeout** — plan 009 Task 15 surface verified with evidence (`asyncHooks: {verified: true, gapFound: false}` in `scripts/phase19-baseline.json`), no new code; (4) **`prism providers add <name>` scaffold** — new CLI subcommand generating an OpenAI-compatible provider package (manifest, provider via `createOpenAICompatibleProvider`, starter models, cache helpers, offline conformance test, docs stub) with npm-name/traversal/symlink-escape validation and placeholders only — never secrets; scaffold output is host-chosen and never auto-registered. Store compatibility with 0.1.6: **compatible, no migration** (additive-only; no persisted-shape change; `docs/migration.md` gains no entries). Exit gate green: npm test core + script gates (incl. phase19-freeze done-phase), `sdk:ready` exit 0, audit 0 moderate, pack dry-run 50/50 twice byte-identical, budget/benchmark gates green; evidence in `scripts/phase19-baseline.json` `exitGate`. Rollback = restore the 0.1.6 manifests/tag.
+
+```bash
+# Operator prerequisites recorded: clean tree at the v0.1.7 tag candidate, GPG key, npm OIDC publisher.
+npm test                                        # core + workspace suites + all script gates
+npm run sdk:ready                               # typecheck, lint, format, test, pack, release:gate
+node scripts/release.mjs gate --version 0.1.7   # plain additive gate, 0 breaking deltas
+npm run pack:dry-run                            # twice; diff reports — deterministic
+npm audit --audit-level=moderate
+npm run release:check -- --version 0.1.7 --report /tmp/prism-0.1.7-preflight.json
+npm run release:publish -- --version 0.1.7 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.1.7-dry-run.json
+#   run the dry-run twice and diff the reports: deterministic, byte-identical
+
+# Sign the release on the clean tagged tree (operator GPG key):
+git tag -s v0.1.7 -m "Prism 0.1.7 — performance and DX (additive)"
+git verify-tag v0.1.7
+git push origin v0.1.7        # tag push triggers release.yml publish job (provenance, attestations)
+
+# Real publication never bypasses the gates: release.mjs refuses
+# --allow-dirty/--allow-untagged without --dry-run.
+```
+
 ### 0.1.6 publish handoff (plan 018 Task 7)
 
 **Decision: GO when the operator prerequisites below are recorded.** Release **0.1.6** (plan 018) is the coding-agent capability-closeouts patch on the frozen 0.1.x line — **additive-only** vs 0.1.5 (plain compat gate at 0.1.6 passed with 0 breaking declaration deltas; the baseline text was regenerated with `--update-baseline` for the version literal only, no `--allow-break` anywhere). Five demand-gated closeouts shipped, each flipped to `demanded` by named demand evidence (operator `arn` for native-sandbox/doc-reader/delete-glob/checkpoint-bodies, user `Clay` for acp-session-store) before its task landed; the demand-gate registry (`scripts/phase18-freeze-manifest.json`) machine-checks demanded ⇒ implemented, deferred ⇒ untouched. Shipped: (1) **durable ACP session store** — `@arnilo/prism-ag-ui` `AcpSessionStore` host seam (`save`/`loadAll`/`evict`), persisted `{sessionId, ownership, modeId, configValues, cwd, additionalDirectories, updatedAt}`, lazy ownership-scoped restore, fail-closed drops, absent seam = 0.1.5 behavior; (2) **network-free native sandbox** — `createNativeSandbox` in `@arnilo/prism-coding-security` (fresh netns per command via the OS `unshare` binary, chained ulimits with `|| exit 126`, argv-only exec, cwd containment, process-group kill, env allow-list, Linux-only fail-closed); (3) **bounded PDF/Office document reader** — new optional package `@arnilo/prism-document-reader` (the 50th manifest, graph 49 → 50) with optional `pdf-parse`/`mammoth` peers fail-closed at creation, magic-byte gating, null fall-through, caps + redaction at the adapter boundary; (4) **recursive delete + brace-expanding glob** — per-call `recursive: true` with fan-out cap and symlink-unlink-not-follow, host-selected/per-call `braceExpansion` bounded to 128 alternatives / 4096 expanded bytes, fail-closed on overflow/malformed braces; (5) **checkpoint persistence for loaded-skill bodies** — opt-in `includeSkillBodies` on run + resume options (names-only stays default, 0.1.3 shapes byte-identical), ≤64 bodies / ≤256-char names / ≤262144-byte bodies / ≤1 MiB total, `maxStateBytes` refusal, redacted at rest, registry-independent resume render. Store compatibility with 0.1.5: **compatible, no migration** (additive-only; no persisted-shape change; `docs/migration.md` gains no entries). Exit gate green: npm test core 1,433/1,433 + 190 script gates (incl. phase18-freeze done-phase), `sdk:ready` exit 0, audit 0 moderate, pack dry-run 50/50 twice byte-identical, budget/benchmark gates green; evidence in `scripts/phase18-baseline.json` `exitGate`. Rollback = restore the 0.1.5 manifests/tag.

package/docs/work-tools.md

@@ -106,6 +106,28 @@ Mutation tools (`*_mail_draft_send`, `*_draft_*`) create an in-adapter draft and
 
 Call `begin({ identity, key, op })` **before** the external effect. After it succeeds, call `complete`, `fail`, or `markUnknown` with the returned claim token and version. The connector effect stays outside the database transaction, so this is claim-before-effect/deduplication—not exactly-once delivery. Claims default to 15 minutes (hard 60 minutes); expired claims transition to `unknown`; attempts default to 3 (hard 5). Stored rows contain no request body, token, raw provider response, or unrestricted payload.
 
+## Subprocess environment isolation (0.2.0, plan 020 Task 3)
+
+`createCliRunner` never inherits the host environment. The child process receives only:
+
+1. **Fixed platform base** — allow-listed locale/system keys copied from the host: `PATH`, `LANG`, `LC_ALL`, `TZ`, `SYSTEMROOT`/`SystemRoot`, `TEMP`, `TMP`, `PATHEXT`, `COMSPEC`. Nothing else from `process.env` crosses the boundary, so unrelated ambient variables (e.g. `PRISM_PROOF_SECRET`) cannot reach the CLI. Additions to the list are deliberate one-line allow-list changes.
+2. **Explicit host env** — non-secret values passed via the `env` option (e.g. `{ LANG: "C.UTF-8" }`).
+3. **Late-bound per-identity token env** — the `tokenProvider` result, merged per call; never argv, never model context.
+4. **Forced reserved controls** — `HOME` is always the isolated `configDir` and `CLIMICROSOFT365_DISABLETELEMETRY` is always `"1"`; neither the explicit map nor the token layer can override them (any attempt fails closed with `ERR_PRISM_WORK_ENV` before spawn).
+
+Environment maps are validated before spawn: NUL-free, `[A-Za-z_][A-Za-z0-9_]*` names, string values, no case-insensitive duplicate or reserved keys (Windows canonicalizes PATH/system key casing so Node's first-lexicographic-key behavior cannot select an attacker-controlled duplicate), and fixed caps of 64 names / 64 KiB total (`ERR_PRISM_WORK_LIMIT`).
+
+### Host-pinned absolute paths
+
+`binary` and `configDir` must be **absolute** paths (`path.isAbsolute`); empty, relative, or NUL-containing values are rejected at construction with `ERR_PRISM_WORK_BINARY` / `ERR_PRISM_WORK_CONFIG` before any spawn.
+
+### Migration (0.1.7 → 0.2.0)
+
+- Any host env your CLI needed beyond the fixed base must move into the explicit `env` map (non-secret) or the per-identity token layer (secrets).
+- Relative `binary`/`configDir` values now fail at construction; resolve them to absolute paths.
+- Per-call `runOpts.env` keys colliding case-insensitively with `HOME` or the telemetry-disable control now fail closed instead of being silently overridden.
+- Output capture is linear: chunks are accumulated in an array with one final `Buffer.concat`, and the process is killed/rejected before bytes beyond the stdout/stderr caps are retained.
+
 ## Limits
 
 | Resource | Default / hard |
@@ -126,7 +148,8 @@ Approved mutations require core-derived `context.idempotencyKey` and a configure
 - Connector tokens (0.0.14): an optional `tokenProvider` resolves a per-identity access token into an env var per call — never argv, never model context. A missing/expired/revoked/cross-identity/wrong-tenant token fails the call closed before any exec. Refresh is late-bound and single-flighted per account (no refresh storm under reconnect). Build one with `createOAuthWorkTokenProvider()` from `@arnilo/prism-credentials-node`.
 - External mail recipients fail closed unless `externalRecipients.allow` returns true.
 - Anonymous / `anyone` sharing denied.
-- CLI stdout/stderr capped; NDJSON page streams strictly parsed and page-capped; process killed on timeout/abort/overflow.
+- CLI stdout/stderr capped (linear chunk capture, killed/rejected before bytes beyond the cap are retained); NDJSON page streams strictly parsed and page-capped; process killed on timeout/abort/overflow.
+- Subprocess environment isolated (0.2.0): fixed allow-listed base + explicit `env` + late-bound token env; `HOME`/telemetry controls forced; reserved/duplicate/NUL/over-cap env and non-absolute binary/configDir fail before spawn. See [Subprocess environment isolation](#subprocess-environment-isolation-020-plan-020-task-3).
 
 ## Related
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -143,7 +143,7 @@
     "build": "npm run build:core && npm run build --workspaces --if-present",
     "typecheck": "npm run build && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
     "sweep:unused": "node scripts/sweep-unused.mjs",
-    "test": "npm run build && node --test dist/__tests__/*.test.js && node --test scripts/release-gate.test.mjs scripts/tooling-gate.test.mjs scripts/budget-gate.test.mjs scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase11-freeze.test.mjs scripts/phase12-freeze.test.mjs scripts/phase13-freeze.test.mjs scripts/phase14-freeze.test.mjs scripts/phase15-freeze.test.mjs scripts/phase16-freeze.test.mjs scripts/phase17-freeze.test.mjs scripts/phase18-freeze.test.mjs scripts/benchmark-0.1.0.test.mjs scripts/sweep-unused.test.mjs scripts/e2e-enterprise-journey.test.mjs scripts/e2e-coding-journey.test.mjs && npm run test --workspaces --if-present",
+    "test": "npm run build && node --test dist/__tests__/*.test.js && node --test scripts/release-gate.test.mjs scripts/tooling-gate.test.mjs scripts/budget-gate.test.mjs scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase11-freeze.test.mjs scripts/phase12-freeze.test.mjs scripts/phase13-freeze.test.mjs scripts/phase14-freeze.test.mjs scripts/phase15-freeze.test.mjs scripts/phase16-freeze.test.mjs scripts/phase17-freeze.test.mjs scripts/phase18-freeze.test.mjs scripts/phase19-freeze.test.mjs scripts/phase20-freeze.test.mjs scripts/benchmark-0.1.0.test.mjs scripts/sweep-unused.test.mjs scripts/e2e-enterprise-journey.test.mjs scripts/e2e-coding-journey.test.mjs && npm run test --workspaces --if-present",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=60 --test-coverage-functions=70 --test-coverage-branches=75 --test-coverage-exclude='**/__tests__/**' --test-coverage-exclude='**/node_modules/**' --test-coverage-exclude='**/scripts/**' --test-coverage-exclude='**/packages/**' --test-coverage-exclude='**/examples/**' dist/__tests__/*.test.js && node scripts/coverage-summary.mjs",
     "coverage:summary": "node scripts/coverage-summary.mjs",
     "lint": "biome lint .",
@@ -156,7 +156,7 @@
     "release:publish": "node scripts/release.mjs publish",
     "sdk:ready": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run test:coverage && npm run pack:dry-run && npm run release:gate",
     "release:gate": "node scripts/release.mjs gate",
-    "security:threat-suites": "node --test scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs"
+    "security:threat-suites": "node --test scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase20-security.test.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.5",

package/templates/provider/CHANGELOG.md.tmpl

@@ -0,0 +1,5 @@
+# Changelog
+
+## __PRISM_VERSION__ — initial scaffold
+
+- Generated by `prism providers add __PROVIDER_ID__` (OpenAI-compatible provider package).

package/templates/provider/README.md.tmpl

@@ -0,0 +1,41 @@
+# __PACKAGE_NAME__
+
+__PROVIDER_ID__ provider package for Prism (OpenAI-compatible Chat Completions).
+
+## Quick start
+
+```bash
+npm install __PACKAGE_NAME__ @arnilo/prism
+```
+
+Wire the provider and models into your Prism host. The package registers an
+`api_key` auth method; hosts resolve the credential value — typically from the
+`__ENV_KEY__` environment variable:
+
+```ts
+import { createResolver } from "@arnilo/prism";
+import { create__PROVIDER_PASCAL__ProviderPackage } from "__PACKAGE_NAME__";
+
+const resolver = createResolver();
+resolver.registerProviderPackage(
+  create__PROVIDER_PASCAL__ProviderPackage({
+    apiKey: () => process.env.__ENV_KEY__,
+  }),
+);
+```
+
+## Models
+
+Starter catalog in `src/models.ts` (`__MODEL_ID__`). Replace with
+docs-verified model metadata (limits, costs, cache behavior) before publishing.
+
+## Conformance
+
+`npm test` builds the package and runs the offline conformance suite wired to
+`@arnilo/prism/testing/provider-conformance` (stream shape, tool-call delta
+reconstruction, header ownership, secret-leak redaction, serialized content
+coverage).
+
+## Docs
+
+See `docs/providers/__PROVIDER_ID__.md`.

package/templates/provider/docs/providers/NAME.md.tmpl

@@ -0,0 +1,61 @@
+# __PROVIDER_ID__ provider
+
+> Scaffold stub — replace with docs-verified provider documentation before publishing.
+
+## What it does
+
+`__PACKAGE_NAME__` is an OpenAI-compatible provider package for Prism
+(chat-completions style). It builds on `createOpenAICompatibleProvider` from
+`@arnilo/prism/providers/openai-compatible`.
+
+## When to use it
+
+Use it for OpenAI-compatible endpoints that follow the Chat Completions
+convention. Skip it for providers with bespoke serialization or auth.
+
+## Inputs / request
+
+- Base URL: `__BASE_URL__` (`--base-url` at scaffold time).
+- Auth: `api_key` auth method; hosts resolve the credential value (e.g. from
+  `__ENV_KEY__`).
+
+## Outputs / response / events
+
+Standard `ProviderEvent` stream: `content_delta`, `done` (with usage), or
+`error`. Tool calls arrive as deltas and are reconstructed by the host.
+
+## Request/response example
+
+```ts
+import { createResolver } from "@arnilo/prism";
+import { create__PROVIDER_PASCAL__ProviderPackage } from "__PACKAGE_NAME__";
+
+const resolver = createResolver();
+resolver.registerProviderPackage(
+  create__PROVIDER_PASCAL__ProviderPackage({ apiKey: () => process.env.__ENV_KEY__ }),
+);
+```
+
+## Implementation example
+
+`src/provider.ts` calls `createOpenAICompatibleProvider` with the scaffolded
+base URL, api key, and `doneUsage: true`. Model metadata lives in `src/models.ts`;
+cache-hint mapping helpers live in `src/cache.ts`.
+
+## Extension and configuration notes
+
+- Override `baseUrl`, `id`, `models`, `apiKey`, and `fetch` per provider
+  package/instance.
+- Cache behavior is scaffolded as `cache: { kind: "implicit" }` — confirm
+  against the provider's actual caching before relying on it.
+
+## Security and performance notes
+
+- API keys are host-resolved credentials; generated code stores no secrets.
+- Cache keys are identifiers only, sanitized via shared core helpers.
+
+## Related APIs
+
+- [OpenAI-compatible provider base](../../providers/openai-compatible.md)
+- [Provider conformance](../../provider-conformance.md)
+- [Provider layer](../../provider-layer.md)

package/templates/provider/package.json.tmpl

@@ -0,0 +1,49 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "__PRISM_VERSION__",
+  "description": "__PROVIDER_ID__ provider package for Prism.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/**/*.map",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/__tests__/*.test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@arnilo/prism": "__PRISM_VERSION__"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "prism",
+    "provider",
+    "__PROVIDER_ID__",
+    "agent",
+    "llm"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/provider/src/cache.ts.tmpl

@@ -0,0 +1,20 @@
+import type { ModelConfig, ProviderRequestOptions } from "@arnilo/prism";
+import { mapCacheRetention, sanitizeCacheKey } from "@arnilo/prism";
+
+/** OpenAI-compatible `prompt_cache_key` accepted length cap. */
+export const __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+
+export function __PROVIDER_ID__PromptCacheKey(options: ProviderRequestOptions | undefined): string | undefined {
+  // Sanitize + clamp via the shared core helper so cache keys cannot carry
+  // disallowed characters or exceed the provider limit. Cache keys are
+  // session/customer identifiers only, never credentials.
+  return sanitizeCacheKey(options?.cacheKey ?? options?.sessionId, __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH);
+}
+
+/** Retention mapping via the shared core helper; `"short"`/`"long"` only when the model supports it. */
+export function __PROVIDER_ID__PromptCacheRetention(
+  retention: ProviderRequestOptions["cacheRetention"] | undefined,
+  model: ModelConfig,
+): "short" | "long" | undefined {
+  return mapCacheRetention(retention, model);
+}

package/templates/provider/src/index.ts.tmpl

@@ -0,0 +1,33 @@
+import { type CredentialValueSource, defineProviderPackage, type ModelConfig, type ProviderPackage } from "@arnilo/prism";
+import { __PROVIDER_ID__Models } from "./models.js";
+import { create__PROVIDER_PASCAL__Provider } from "./provider.js";
+
+export interface __PROVIDER_PASCAL__ProviderPackageOptions {
+  readonly apiKey?: CredentialValueSource;
+  readonly fetch?: typeof fetch;
+  readonly baseUrl?: string;
+  readonly id?: string;
+  readonly models?: readonly ModelConfig[];
+}
+
+export function create__PROVIDER_PASCAL__ProviderPackage(options: __PROVIDER_PASCAL__ProviderPackageOptions = {}): ProviderPackage {
+  const providerId = options.id ?? "__PROVIDER_ID__";
+  return defineProviderPackage({
+    name: "__PACKAGE_NAME__",
+    description: "__PROVIDER_ID__ provider package for Prism.",
+    docs: { links: ["docs/providers/__PROVIDER_ID__.md"] },
+    setup(api) {
+      api.registerProvider(create__PROVIDER_PASCAL__Provider(options));
+      for (const model of options.models ?? __PROVIDER_ID__Models) api.registerModel({ ...model, provider: providerId });
+      api.registerAuthMethod({ kind: "api_key", provider: providerId, credentialName: "apiKey" });
+    },
+  });
+}
+
+export { __PROVIDER_ID__Models, type __PROVIDER_PASCAL__ModelConfig } from "./models.js";
+export { create__PROVIDER_PASCAL__Provider, __PROVIDER_UPPER___DEFAULT_BASE_URL, type __PROVIDER_PASCAL__ProviderOptions } from "./provider.js";
+export {
+  __PROVIDER_ID__PromptCacheKey,
+  __PROVIDER_ID__PromptCacheRetention,
+  __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH,
+} from "./cache.js";

package/templates/provider/src/models.ts.tmpl

@@ -0,0 +1,16 @@
+import type { ModelConfig } from "@arnilo/prism";
+
+/** Starter catalog for __PROVIDER_ID__: replace with docs-verified model metadata. */
+export interface __PROVIDER_PASCAL__ModelConfig extends Omit<ModelConfig, "provider"> {
+  readonly provider: "__PROVIDER_ID__";
+}
+
+export const __PROVIDER_ID__Models: readonly __PROVIDER_PASCAL__ModelConfig[] = [
+  {
+    provider: "__PROVIDER_ID__",
+    model: "__MODEL_ID__",
+    limits: { contextWindow: 128_000 },
+    cost: { input: 1, output: 2, cacheRead: 0.5, unit: "per_million_tokens" },
+    cache: { kind: "implicit" },
+  },
+];

package/templates/provider/src/provider.ts.tmpl

@@ -0,0 +1,23 @@
+import type { AIProvider, CredentialValueSource } from "@arnilo/prism";
+import { createOpenAICompatibleProvider } from "@arnilo/prism/providers/openai-compatible";
+
+/** Default Chat Completions base URL for __PROVIDER_ID__ (override per provider docs). */
+export const __PROVIDER_UPPER___DEFAULT_BASE_URL = "__BASE_URL__";
+
+export interface __PROVIDER_PASCAL__ProviderOptions {
+  readonly id?: string;
+  readonly baseUrl?: string;
+  readonly apiKey?: CredentialValueSource;
+  readonly fetch?: typeof fetch;
+}
+
+export function create__PROVIDER_PASCAL__Provider(options: __PROVIDER_PASCAL__ProviderOptions = {}): AIProvider {
+  return createOpenAICompatibleProvider({
+    id: options.id ?? "__PROVIDER_ID__",
+    baseUrl: (options.baseUrl ?? __PROVIDER_UPPER___DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    apiKey: options.apiKey,
+    fetch: options.fetch,
+    doneUsage: true,
+    requestFailedPrefix: "__PROVIDER_PASCAL__ request failed",
+  });
+}

package/templates/provider/src/tests/provider.test.ts.tmpl

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ProviderRequest } from "@arnilo/prism";
+import {
+  assertNoSecretLeak,
+  assertProviderOwnedHeadersWin,
+  assertProviderStreamConforms,
+  assertSerializedRequestCoversContent,
+  assertToolCallDeltasReconstruct,
+} from "@arnilo/prism/testing/provider-conformance";
+import { create__PROVIDER_PASCAL__Provider } from "../index.js";
+import { __PROVIDER_ID__Models } from "../models.js";
+
+const request: ProviderRequest = {
+  model: __PROVIDER_ID__Models[0],
+  messages: [
+    { role: "system", content: [{ type: "text", text: "developer instructions" }] },
+    { role: "user", content: [{ type: "text", text: "hi" }] },
+  ],
+  tools: [{ name: "lookup", parameters: { type: "object" }, execute: () => ({ toolCallId: "call_1", name: "lookup", content: [] }) }],
+};
+
+const API_KEY = "fake-__PROVIDER_ID__-key";
+
+describe("__PROVIDER_ID__ provider scaffold", () => {
+  it("streams text, usage, and done; owns its headers; leaks no secrets", async () => {
+    let captured: RequestInit | undefined;
+    const provider = create__PROVIDER_PASCAL__Provider({
+      apiKey: API_KEY,
+      fetch: (async (_input, init) => {
+        captured = init;
+        return ok(
+          sse([
+            { id: "chatcmpl-1", object: "chat.completion.chunk", choices: [{ index: 0, delta: { role: "assistant", content: "hi" } }] },
+            {
+              id: "chatcmpl-1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: {} }],
+              usage: { prompt_tokens: 5, completion_tokens: 2, total_tokens: 7 },
+            },
+          ]),
+        );
+      }) as typeof fetch,
+    });
+    const events = await assertProviderStreamConforms({
+      provider,
+      request: {
+        ...request,
+        options: {
+          ...request.options,
+          headers: { authorization: "Bearer caller-key", "content-type": "text/plain", "x-caller": "kept" },
+        },
+      },
+      expect: { text: "hi", usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } },
+    });
+    assertNoSecretLeak(events, [API_KEY]);
+    const headers = new Headers(captured?.headers);
+    assertProviderOwnedHeadersWin(headers, {
+      owned: { authorization: `Bearer ${API_KEY}`, "content-type": "application/json" },
+      caller: { authorization: "Bearer caller-key", "content-type": "text/plain", "x-caller": "kept" },
+    });
+  });
+
+  it("serializes request content and reconstructs tool-call deltas", async () => {
+    let body: unknown;
+    const provider = create__PROVIDER_PASCAL__Provider({
+      apiKey: API_KEY,
+      fetch: (async (_input, init) => {
+        body = JSON.parse(String(init?.body));
+        return ok(
+          sse([
+            {
+              id: "c1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: "call_1", function: { name: "lookup", arguments: "" } }] } }],
+            },
+            {
+              id: "c1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { tool_calls: [{ index: 0, function: { arguments: '{"q":"x"}' } }] } }],
+            },
+          ]),
+        );
+      }) as typeof fetch,
+    });
+    const events = await assertProviderStreamConforms({ provider, request });
+    assertToolCallDeltasReconstruct(events, [{ index: 0, id: "call_1", name: "lookup", arguments: { q: "x" } }]);
+    assertSerializedRequestCoversContent(request, body);
+  });
+});
+
+function ok(body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, { status: 200 });
+}
+
+function sse(events: readonly object[]): ReadableStream<Uint8Array> {
+  const text = `${events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join("")}data: [DONE]\n\n`;
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(text));
+      controller.close();
+    },
+  });
+}

package/templates/provider/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}