@arnilo/prism 0.0.4 → 0.0.6

package/dist/testing/persistence-schema.js

@@ -1,9 +1,10 @@
+import { createHash } from "node:crypto";
 // ponytail: dialect-neutral persistence schema model and migration contracts for
 // SQLite/PostgreSQL adapter packages (Plan 056 Task 1). SQL stays package-local;
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 1;
+export const PERSISTENCE_SCHEMA_VERSION = 3;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -107,7 +108,7 @@ export function createPersistenceSchemaModel() {
                     { name: "run_id", type: "text", nullable: true },
                     { name: "timestamp", type: "timestamp" },
                     { name: "kind", type: "text" },
-                    { name: "schema_version", type: "integer" },
+                    { name: "schema_version", type: "integer", nullable: true },
                     { name: "message", type: "json", nullable: true },
                     { name: "event", type: "json", nullable: true },
                     { name: "model", type: "json", nullable: true },
@@ -156,7 +157,6 @@ export function createPersistenceSchemaModel() {
                     ...TENANT_COLUMNS,
                     { name: "metadata", type: "json", nullable: true },
                 ],
-                uniqueKeys: [["tenant_id", "idempotency_key"]],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
             {
@@ -210,6 +210,9 @@ export function createPersistenceSchemaModel() {
                     { name: "session_id", type: "text" },
                     { name: "run_id", type: "text", nullable: true },
                     { name: "entry_id", type: "text", nullable: true },
+                    { name: "scope", type: "text", defaultValue: "'run_total'" },
+                    { name: "turn", type: "integer", nullable: true },
+                    { name: "attempt", type: "integer", nullable: true },
                     { name: "usage", type: "json" },
                     { name: "recorded_at", type: "timestamp" },
                     ...TENANT_COLUMNS,
@@ -217,6 +220,28 @@ export function createPersistenceSchemaModel() {
                 ],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
+            {
+                name: "prism_run_feedback",
+                primaryKey: ["id"],
+                columns: [
+                    { name: "id", type: "text" },
+                    { name: "run_id", type: "text" },
+                    { name: "session_id", type: "text" },
+                    { name: "trace_id", type: "text", nullable: true },
+                    { name: "rating", type: "number", nullable: true },
+                    { name: "comment", type: "text", nullable: true },
+                    { name: "tags", type: "json" },
+                    { name: "scorer_ids", type: "json" },
+                    { name: "evaluation_ids", type: "json" },
+                    { name: "created_at", type: "timestamp" },
+                    { name: "created_by", type: "text", nullable: true },
+                    { name: "tenant_id", type: "text", tenantScoped: true },
+                    { name: "account_id", type: "text", nullable: true, tenantScoped: true },
+                    { name: "user_id", type: "text", nullable: true, tenantScoped: true },
+                    { name: "metadata", type: "json", nullable: true },
+                ],
+                foreignKeys: [{ columns: ["run_id"], referencesTable: "prism_runs", referencesColumns: ["id"] }],
+            },
             {
                 name: "prism_retention_policies",
                 primaryKey: ["id"],
@@ -258,7 +283,7 @@ export function createPersistenceSchemaModel() {
             { name: "prism_session_entries_session_run_ts_idx", table: "prism_session_entries", columns: ["session_id", "run_id", "timestamp"], purpose: "run-scoped entry listing" },
             { name: "prism_session_entries_session_ts_id_idx", table: "prism_session_entries", columns: ["session_id", "timestamp", "id"], purpose: "cursor pagination without full scans" },
             { name: "prism_session_entries_session_id_idx", table: "prism_session_entries", columns: ["session_id", "id"], purpose: "append parent validation and recursive branch reads" },
-            { name: "prism_session_append_idempotency_unique", table: "prism_session_append_idempotency", columns: ["session_id", "expected_parent_id", "idempotency_key"], unique: true, purpose: "append retry deduplication" },
+            { name: "prism_session_append_idempotency_unique", table: "prism_session_append_idempotency", columns: ["session_id", "expected_parent_id", "idempotency_key"], purpose: "append retry deduplication (primary key enforces uniqueness)" },
             { name: "prism_runs_session_started_idx", table: "prism_runs", columns: ["session_id", "started_at", "id"], purpose: "run history pagination" },
             { name: "prism_runs_branch_started_idx", table: "prism_runs", columns: ["branch_id", "started_at", "id"], purpose: "branch-scoped runs" },
             { name: "prism_runs_tenant_idempotency_unique", table: "prism_runs", columns: ["tenant_id", "idempotency_key"], unique: true, purpose: "run-level idempotency deduplication per tenant" },
@@ -268,18 +293,45 @@ export function createPersistenceSchemaModel() {
             { name: "prism_tool_calls_run_started_idx", table: "prism_tool_calls", columns: ["run_id", "started_at"], purpose: "run tool-call listing" },
             { name: "prism_usage_run_recorded_idx", table: "prism_usage", columns: ["run_id", "recorded_at", "id"], purpose: "run usage pagination" },
             { name: "prism_usage_session_recorded_idx", table: "prism_usage", columns: ["session_id", "recorded_at"], purpose: "usage aggregation" },
+            { name: "prism_usage_session_scope_recorded_idx", table: "prism_usage", columns: ["session_id", "scope", "recorded_at"], purpose: "scope-safe usage aggregation" },
+            { name: "prism_run_feedback_owner_created_idx", table: "prism_run_feedback", columns: ["tenant_id", "account_id", "user_id", "created_at", "id"], purpose: "ownership-scoped feedback pagination" },
+            { name: "prism_run_feedback_run_created_idx", table: "prism_run_feedback", columns: ["run_id", "created_at", "id"], purpose: "run feedback lookup" },
+            { name: "prism_run_feedback_trace_created_idx", table: "prism_run_feedback", columns: ["trace_id", "created_at", "id"], purpose: "trace feedback lookup" },
             { name: "prism_agent_definitions_name_version_idx", table: "prism_agent_definitions", columns: ["name", "version"], purpose: "definition lookup" },
-            { name: "prism_migrations_name_version_idx", table: "prism_migrations", columns: ["name", "version"], unique: true, purpose: "applied-migration uniqueness" },
+            { name: "prism_migrations_name_version_idx", table: "prism_migrations", columns: ["name", "version"], purpose: "applied-migration lookup (table constraint enforces uniqueness)" },
         ],
     };
 }
+function migrationStep(version, name, description) {
+    const model = createPersistenceSchemaModel();
+    const content = version === 1
+        ? {
+            tables: model.tables
+                .filter((table) => table.name !== "prism_run_feedback")
+                .map((table) => table.name === "prism_usage"
+                ? { ...table, columns: table.columns.filter((column) => !["scope", "turn", "attempt"].includes(column.name)) }
+                : table),
+            indexes: model.indexes.filter((index) => !index.name.startsWith("prism_usage_session_scope_") && !index.name.startsWith("prism_run_feedback_")),
+        }
+        : version === 2
+            ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+            : { tables: ["prism_run_feedback"], indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name) };
+    return {
+        version,
+        name,
+        description,
+        checksum: createHash("sha256").update(JSON.stringify({ version, name, content })).digest("hex"),
+    };
+}
 /** Canonical migration contract for production adapters. */
 export function createPersistenceMigrationContract() {
     return {
         targetSchemaVersion: PERSISTENCE_SCHEMA_VERSION,
         appliedMigrationsTable: "prism_migrations",
         steps: [
-            { version: 1, name: "001_init", description: "Create core session, branch, entry, idempotency, run, ledger, and migration tables." },
+            migrationStep(1, "001_init", "Create core session, branch, entry, idempotency, run, ledger, and migration tables."),
+            migrationStep(2, "002_usage_scope", "Distinguish provider-turn usage from aggregate run totals."),
+            migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",
@@ -294,6 +346,7 @@ export function getPersistencePaginationCursors() {
         { table: "prism_agent_events", columns: ["session_id", "timestamp", "id"], supportsOrder: ["asc", "desc"], purpose: "session event stream" },
         { table: "prism_usage", columns: ["run_id", "recorded_at", "id"], supportsOrder: ["asc", "desc"], purpose: "run usage totals" },
         { table: "prism_tool_calls", columns: ["run_id", "started_at"], supportsOrder: ["asc", "desc"], purpose: "run tool-call listing" },
+        { table: "prism_run_feedback", columns: ["tenant_id", "account_id", "user_id", "created_at", "id"], supportsOrder: ["asc", "desc"], purpose: "owned feedback listing" },
     ];
 }
 /** Build a tenant-scoped unique key column list for adapter DDL. */
@@ -326,7 +379,7 @@ export function assertPersistenceSchemaModel(model) {
         throw new Error("Runs table must include tenant-scoped tenant_id");
     }
     const indexTables = new Set(model.indexes.map((index) => index.table));
-    for (const requiredIndex of ["prism_session_append_idempotency", "prism_session_entries", "prism_agent_events", "prism_runs"]) {
+    for (const requiredIndex of ["prism_session_append_idempotency", "prism_session_entries", "prism_agent_events", "prism_runs", "prism_run_feedback"]) {
         if (!indexTables.has(requiredIndex)) {
             throw new Error(`Persistence schema missing indexes for ${requiredIndex}`);
         }
@@ -357,6 +410,8 @@ export function assertPersistenceMigrationContract(contract) {
             throw new Error(`Migration steps must be strictly increasing; ${step.name} is out of order`);
         if (names.has(step.name))
             throw new Error(`Duplicate migration step name: ${step.name}`);
+        if (!/^[a-f0-9]{64}$/.test(step.checksum))
+            throw new Error(`Migration step ${step.name} must have a SHA-256 checksum`);
         names.add(step.name);
         previous = step.version;
     }
@@ -364,6 +419,101 @@ export function assertPersistenceMigrationContract(contract) {
         throw new Error(`Last migration step version ${previous} must equal targetSchemaVersion ${contract.targetSchemaVersion}`);
     }
 }
+function schemaKey(columns) {
+    return columns.join("\u0000");
+}
+function normalizedDefault(value) {
+    return value?.trim().toLowerCase().replace(/::[a-z_ ]+$/, "");
+}
+function compatibleColumnType(dialect, actual, expected) {
+    const type = actual.trim().toUpperCase();
+    if (dialect === "sqlite") {
+        if (expected === "integer" || expected === "boolean")
+            return type === "INTEGER";
+        if (expected === "number")
+            return type === "REAL";
+        return type === "TEXT";
+    }
+    if (expected === "integer")
+        return type === "INTEGER";
+    if (expected === "boolean")
+        return type === "BOOLEAN";
+    if (expected === "number")
+        return type === "DOUBLE PRECISION";
+    return type === "TEXT";
+}
+/** Compare bounded dialect catalog output against every required schema-v3 detail. */
+export function assertPersistenceSchemaShape(shape, dialect, model = createPersistenceSchemaModel()) {
+    assertPersistenceSchemaModel(model);
+    const actualTables = new Map(shape.tables.map((table) => [table.name, table]));
+    for (const expected of model.tables) {
+        const actual = actualTables.get(expected.name);
+        if (!actual)
+            throw new Error(`Persistence schema missing table ${expected.name}`);
+        if (actual.columns.length !== expected.columns.length)
+            throw new Error(`Persistence schema table ${expected.name} has unexpected columns`);
+        const actualColumns = new Map(actual.columns.map((column) => [column.name, column]));
+        for (const column of expected.columns) {
+            const found = actualColumns.get(column.name);
+            if (!found)
+                throw new Error(`Persistence schema table ${expected.name} missing column ${column.name}`);
+            if (!compatibleColumnType(dialect, found.type, column.type)) {
+                throw new Error(`Persistence schema column ${expected.name}.${column.name} has incompatible type`);
+            }
+            if (found.nullable !== (column.nullable === true)) {
+                throw new Error(`Persistence schema column ${expected.name}.${column.name} has incompatible nullability`);
+            }
+            if (normalizedDefault(found.defaultValue) !== normalizedDefault(column.defaultValue)) {
+                throw new Error(`Persistence schema column ${expected.name}.${column.name} has incompatible default`);
+            }
+        }
+        if (schemaKey(actual.primaryKey) !== schemaKey(expected.primaryKey)) {
+            throw new Error(`Persistence schema table ${expected.name} has incompatible primary key`);
+        }
+        const unique = new Set(actual.uniqueKeys.map(schemaKey));
+        for (const key of expected.uniqueKeys ?? []) {
+            if (!unique.has(schemaKey(key)) && schemaKey(actual.primaryKey) !== schemaKey(key)) {
+                throw new Error(`Persistence schema table ${expected.name} missing unique key (${key.join(", ")})`);
+            }
+        }
+        const foreign = new Set(actual.foreignKeys.map((key) => `${schemaKey(key.columns)}>${key.referencesTable}:${schemaKey(key.referencesColumns)}`));
+        for (const key of expected.foreignKeys ?? []) {
+            if (!foreign.has(`${schemaKey(key.columns)}>${key.referencesTable}:${schemaKey(key.referencesColumns)}`)) {
+                throw new Error(`Persistence schema table ${expected.name} missing foreign key (${key.columns.join(", ")})`);
+            }
+        }
+    }
+    const actualIndexes = new Map(shape.indexes.map((index) => [index.name, index]));
+    for (const expected of model.indexes) {
+        const actual = actualIndexes.get(expected.name);
+        if (!actual)
+            throw new Error(`Persistence schema missing required index ${expected.name}`);
+        if (actual.table !== expected.table || schemaKey(actual.columns) !== schemaKey(expected.columns) || actual.unique !== (expected.unique === true)) {
+            throw new Error(`Persistence schema index ${expected.name} has incompatible definition`);
+        }
+    }
+}
+/** Reject altered migration history before any new DDL or runtime write. */
+export function assertAppliedPersistenceMigrations(contract, applied) {
+    assertPersistenceMigrationContract(contract);
+    if (applied.length > contract.steps.length)
+        throw new Error("Migration history has unknown rows");
+    const legacyChecksums = applied.some((row) => row.checksum === null);
+    if (legacyChecksums && (applied.length !== contract.steps.length || !applied.every((row) => row.checksum === null))) {
+        throw new Error("Migration history has incomplete legacy checksums");
+    }
+    for (let index = 0; index < applied.length; index++) {
+        const row = applied[index];
+        const expected = contract.steps[index];
+        if (row.name !== expected.name || row.version !== String(expected.version)) {
+            throw new Error(`Migration history row ${index} does not match ${expected.name}`);
+        }
+        if (!legacyChecksums && row.checksum !== expected.checksum) {
+            throw new Error(`Migration history checksum mismatch for ${expected.name}`);
+        }
+    }
+    return { legacyChecksums };
+}
 /**
  * Assert a dialect-local adapter exposes the canonical table and index names.
  * Adapters pass the table/index names their migration runner created.
@@ -393,23 +543,17 @@ export function assertParameterizedQuery(sql, boundValues) {
 }
 /** Simulate migration up + reopen: applied steps must match the contract in order. */
 export function assertMigrationUpAndReopen(contract, appliedAfterUp, appliedAfterReopen) {
-    assertPersistenceMigrationContract(contract);
-    if (appliedAfterUp.length !== contract.steps.length) {
-        throw new Error("Migration up did not apply every contract step");
-    }
-    for (let i = 0; i < contract.steps.length; i++) {
-        const step = contract.steps[i];
-        const row = appliedAfterUp[i];
-        if (row.name !== step.name || row.version !== String(step.version)) {
-            throw new Error(`Applied migration row ${i} does not match contract step ${step.name}`);
-        }
+    const first = assertAppliedPersistenceMigrations(contract, appliedAfterUp);
+    if (appliedAfterUp.length !== contract.steps.length || first.legacyChecksums) {
+        throw new Error("Migration up did not apply every checksummed contract step");
     }
-    if (appliedAfterReopen.length !== appliedAfterUp.length) {
-        throw new Error("Reopened adapter must not re-apply migrations; applied row count changed");
+    const second = assertAppliedPersistenceMigrations(contract, appliedAfterReopen);
+    if (second.legacyChecksums || appliedAfterReopen.length !== appliedAfterUp.length) {
+        throw new Error("Reopened adapter migration history diverged");
     }
-    for (let i = 0; i < appliedAfterUp.length; i++) {
-        if (appliedAfterReopen[i].name !== appliedAfterUp[i].name) {
-            throw new Error("Reopened adapter migration history diverged");
+    for (let index = 0; index < appliedAfterUp.length; index++) {
+        if (appliedAfterReopen[index].checksum !== appliedAfterUp[index].checksum) {
+            throw new Error("Reopened adapter migration checksums diverged");
         }
     }
 }

package/dist/testing/run-ledger-conformance.js

@@ -71,6 +71,9 @@ export async function assertRunLedgerConforms(fixture, options = {}) {
         id: "usage-1",
         sessionId,
         runId,
+        scope: "provider_turn",
+        turn: 1,
+        attempt: 2,
         usage: { inputTokens: 3, outputTokens: 5, totalTokens: 8 },
         recordedAt: "2026-01-01T00:00:01.000Z",
         ...scope,
@@ -114,8 +117,11 @@ export async function assertRunLedgerConforms(fixture, options = {}) {
     }
     if (fixture.readUsage) {
         const usageRows = await fixture.readUsage();
-        if (!usageRows.some((row) => row.id === "usage-1")) {
+        const storedUsage = usageRows.find((row) => row.id === "usage-1");
+        if (!storedUsage)
             throw new Error("RunLedger must persist UsageRecord rows");
+        if (storedUsage.scope !== "provider_turn" || storedUsage.turn !== 1 || storedUsage.attempt !== 2) {
+            throw new Error("RunLedger must preserve UsageRecord scope, turn, and attempt");
         }
     }
     if (options.exerciseTenantIsolation && fixture.readRuns) {

package/dist/thinking.d.ts

@@ -0,0 +1,42 @@
+import type { JsonObject, ModelConfig, ProviderRequestOptions } from "./contracts.js";
+/**
+ * Portable thinking / reasoning effort levels shared across first-party providers.
+ * Model-dependent legality (which values a given model accepts) stays provider-owned.
+ */
+export declare const THINKING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/**
+ * Compat mapping families used by ≥2 packages, or explicit no-op for host-owned adapters.
+ * Provider packages keep unique escape hatches (budgets, keep/all, tool_stream) local.
+ */
+export type ThinkingCompatFamily = "openai_reasoning" | "reasoning_effort" | "thinking_type" | "noop";
+export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;
+/**
+ * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
+ * strings pass through as opaque effort values for forward-compatible provider fields.
+ */
+export declare function normalizeThinkingLevel(level: string): ThinkingLevel | string | undefined;
+/**
+ * Build the `ProviderRequestOptions.compat` patch for a shared thinking level.
+ * Does not invent a second options tree — providers keep reading official fields from `compat`.
+ */
+export declare function thinkingCompatFor(family: ThinkingCompatFamily, level: ThinkingLevel | string): JsonObject;
+/**
+ * Merge a shared thinking level into `providerOptions.compat` for the given family.
+ * Per-turn patches win over prior compat via {@link mergeProviderRequestOptions}.
+ */
+export declare function applyThinkingLevel(options: ProviderRequestOptions | undefined, level: ThinkingLevel | string, family?: ThinkingCompatFamily): ProviderRequestOptions;
+/**
+ * Best-effort family inference from model metadata without a second options tree.
+ * Prefer an explicit family in hosts/use-case workers when the provider is known.
+ *
+ * Heuristics (ordered):
+ * 1. Existing `compat.thinking` object → `thinking_type`
+ * 2. Existing `compat.reasoning` → `openai_reasoning`
+ * 3. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 4. Provider id starting with `openai` → `openai_reasoning`
+ * 5. Provider id `neuralwatt` → `reasoning_effort`
+ * 6. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 7. Else `noop`
+ */
+export declare function thinkingFamilyForModel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): ThinkingCompatFamily;

package/dist/thinking.js

@@ -0,0 +1,92 @@
+import { mergeProviderRequestOptions } from "./provider-request-policy.js";
+/**
+ * Portable thinking / reasoning effort levels shared across first-party providers.
+ * Model-dependent legality (which values a given model accepts) stays provider-owned.
+ */
+export const THINKING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS.includes(value);
+}
+/**
+ * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
+ * strings pass through as opaque effort values for forward-compatible provider fields.
+ */
+export function normalizeThinkingLevel(level) {
+    const normalized = level.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    return isThinkingLevel(normalized) ? normalized : normalized;
+}
+/**
+ * Build the `ProviderRequestOptions.compat` patch for a shared thinking level.
+ * Does not invent a second options tree — providers keep reading official fields from `compat`.
+ */
+export function thinkingCompatFor(family, level) {
+    const normalized = typeof level === "string" ? normalizeThinkingLevel(level) : level;
+    if (!normalized || family === "noop")
+        return {};
+    switch (family) {
+        case "openai_reasoning":
+            return { reasoning: { effort: normalized } };
+        case "reasoning_effort":
+            return { reasoning_effort: normalized };
+        case "thinking_type":
+            return { thinking: { type: normalized === "none" ? "disabled" : "enabled" } };
+        default: {
+            const _exhaustive = family;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Merge a shared thinking level into `providerOptions.compat` for the given family.
+ * Per-turn patches win over prior compat via {@link mergeProviderRequestOptions}.
+ */
+export function applyThinkingLevel(options, level, family = "reasoning_effort") {
+    const normalized = normalizeThinkingLevel(String(level));
+    if (!normalized || family === "noop")
+        return options ?? {};
+    const patch = thinkingCompatFor(family, normalized);
+    if (family === "openai_reasoning" && options?.compat?.reasoning && typeof options.compat.reasoning === "object" && !Array.isArray(options.compat.reasoning)) {
+        return mergeProviderRequestOptions(options, {
+            compat: {
+                reasoning: {
+                    ...options.compat.reasoning,
+                    ...patch.reasoning,
+                },
+            },
+        });
+    }
+    return mergeProviderRequestOptions(options, { compat: patch });
+}
+/**
+ * Best-effort family inference from model metadata without a second options tree.
+ * Prefer an explicit family in hosts/use-case workers when the provider is known.
+ *
+ * Heuristics (ordered):
+ * 1. Existing `compat.thinking` object → `thinking_type`
+ * 2. Existing `compat.reasoning` → `openai_reasoning`
+ * 3. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 4. Provider id starting with `openai` → `openai_reasoning`
+ * 5. Provider id `neuralwatt` → `reasoning_effort`
+ * 6. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 7. Else `noop`
+ */
+export function thinkingFamilyForModel(model) {
+    const compat = model.compat ?? {};
+    if (compat.thinking != null && typeof compat.thinking === "object")
+        return "thinking_type";
+    if (compat.reasoning != null)
+        return "openai_reasoning";
+    if (compat.reasoning_effort != null)
+        return "reasoning_effort";
+    const provider = model.provider.trim().toLowerCase();
+    if (provider === "openai" || provider.startsWith("openai"))
+        return "openai_reasoning";
+    if (provider === "neuralwatt")
+        return "reasoning_effort";
+    if (model.capabilities?.reasoning)
+        return "reasoning_effort";
+    return "noop";
+}
+//# sourceMappingURL=thinking.js.map

package/dist/tools.js

@@ -1,4 +1,5 @@
 import { isJsonObject } from "./config.js";
+import { createId } from "./ids.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
 import { assertPermission } from "./security.js";
@@ -149,9 +150,7 @@ async function blocked(call, context, reason, error, options, startedAt) {
 function toErrorInfo(value, secrets) {
     return typeof value === "string" ? errorToErrorInfo(value, secrets) : redactSecrets(value, secrets);
 }
-function randomId(prefix) {
-    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
-}
+const randomId = createId;
 function appendToolCallRecord(options, status, call, startedAt, fields) {
     if (!options.ledger)
         return undefined;

package/dist/use-case-model.d.ts

@@ -0,0 +1,63 @@
+import type { ModelConfig, ProviderRequestOptions } from "./contracts.js";
+/**
+ * Host binding for a non-session LLM job (observational memory, LLM compaction,
+ * declarative agents, evals, etc.). Omitting `model` means "use the session model"
+ * when a session fallback is supplied to {@link resolveUseCaseModel}.
+ *
+ * Workers must not write `model_change` session entries; they resolve a model for
+ * their own provider calls only.
+ */
+export interface UseCaseModelBinding {
+    /** Explicit use-case model. When omitted, {@link resolveUseCaseModel} falls back to `sessionModel`. */
+    readonly model?: ModelConfig;
+    /**
+     * Optional provider id hint for docs / credential routing.
+     * When `model` is set, `model.provider` is authoritative.
+     */
+    readonly provider?: string;
+    readonly providerOptions?: ProviderRequestOptions;
+    /** Portable thinking level; packages map via `applyThinkingLevel` into `compat`. */
+    readonly thinkingLevel?: string;
+    /**
+     * When true, do not fall back to `sessionModel` — leave resolution empty if
+     * `model` is omitted (preserves historical explicit-worker `missing_model` behavior).
+     */
+    readonly requireExplicitModel?: boolean;
+}
+export interface ResolveUseCaseModelInput {
+    /** Explicit use-case model (or `binding.model`). */
+    readonly configured?: ModelConfig;
+    /** Active session / agent model used when `configured` is omitted. */
+    readonly sessionModel?: ModelConfig;
+    /** When true, skip session fallback (OM `missing_model` escape hatch). */
+    readonly requireExplicitModel?: boolean;
+    readonly providerOptions?: ProviderRequestOptions;
+    readonly thinkingLevel?: string;
+}
+export interface ResolvedUseCaseModel {
+    readonly model: ModelConfig;
+    /** Whether the model came from the use-case binding or session fallback. */
+    readonly source: "configured" | "session";
+    readonly providerOptions?: ProviderRequestOptions;
+    readonly thinkingLevel?: string;
+}
+/**
+ * Resolve the model for a non-session LLM job.
+ *
+ * Precedence:
+ * 1. `configured` → `source: "configured"`
+ * 2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+ * 3. Else `undefined` (caller skips / throws per package policy)
+ *
+ * O(1); no network. Does not mutate session history.
+ */
+export declare function resolveUseCaseModel(input: ResolveUseCaseModelInput): ResolvedUseCaseModel | undefined;
+/**
+ * Resolve from a {@link UseCaseModelBinding} plus optional session fallback.
+ */
+export declare function resolveUseCaseModelBinding(binding: UseCaseModelBinding | undefined, sessionModel?: ModelConfig): ResolvedUseCaseModel | undefined;
+/**
+ * Provider id for credential requests: always the **resolved** model's provider.
+ * Optional `binding.provider` is only a hint when no model resolved yet.
+ */
+export declare function useCaseCredentialProviderId(resolved: ResolvedUseCaseModel | undefined, binding?: Pick<UseCaseModelBinding, "provider">): string | undefined;

package/dist/use-case-model.js

@@ -0,0 +1,52 @@
+/**
+ * Resolve the model for a non-session LLM job.
+ *
+ * Precedence:
+ * 1. `configured` → `source: "configured"`
+ * 2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+ * 3. Else `undefined` (caller skips / throws per package policy)
+ *
+ * O(1); no network. Does not mutate session history.
+ */
+export function resolveUseCaseModel(input) {
+    const { providerOptions, thinkingLevel } = input;
+    if (input.configured) {
+        return {
+            model: input.configured,
+            source: "configured",
+            providerOptions,
+            thinkingLevel,
+        };
+    }
+    if (input.requireExplicitModel)
+        return undefined;
+    if (input.sessionModel) {
+        return {
+            model: input.sessionModel,
+            source: "session",
+            providerOptions,
+            thinkingLevel,
+        };
+    }
+    return undefined;
+}
+/**
+ * Resolve from a {@link UseCaseModelBinding} plus optional session fallback.
+ */
+export function resolveUseCaseModelBinding(binding, sessionModel) {
+    return resolveUseCaseModel({
+        configured: binding?.model,
+        sessionModel,
+        requireExplicitModel: binding?.requireExplicitModel,
+        providerOptions: binding?.providerOptions,
+        thinkingLevel: binding?.thinkingLevel,
+    });
+}
+/**
+ * Provider id for credential requests: always the **resolved** model's provider.
+ * Optional `binding.provider` is only a hint when no model resolved yet.
+ */
+export function useCaseCredentialProviderId(resolved, binding) {
+    return resolved?.model.provider ?? binding?.provider;
+}
+//# sourceMappingURL=use-case-model.js.map