@arnilo/prism 0.8.0 → 0.10.0

package/dist/testing/agent-event-source-conformance.js

@@ -28,14 +28,53 @@ export async function assertAgentEventSourceConforms(factory) {
     const final = await source.page({ ...input, after: secondPage.items[0].cursor, limit: 10 });
     equal(final.items.at(-1)?.record.id, terminal.id, "terminal page must include its terminal event");
     equal(final.terminal, true, "terminal event must close only after prior events are delivered");
+    // A limit death delivers its attribution before the run's outcome: the breach and budget records
+    // are not terminal, the `error` that follows them is.
+    const breached = { ...input, runId: "run-limit" };
+    await source.append(event("event-limit-before", "turn_started", breached, "2026-01-01T00:00:04.000Z"));
+    const beforeLimitItem = (await source.page({ ...breached, limit: 1 })).items[0];
+    if (!beforeLimitItem)
+        throw new Error("limit-death precondition missing");
+    const beforeLimit = beforeLimitItem.cursor;
+    await source.append(event("event-limit", "run_limit_exceeded", breached, "2026-01-01T00:00:05.000Z"));
+    await source.append(event("event-attr", "budget_exhausted", breached, "2026-01-01T00:00:06.000Z"));
+    const breachPage = await source.page({ ...breached, after: beforeLimit, limit: 10 });
+    equal(breachPage.items.length, 2, "the breach and its attribution must page together");
+    equal(breachPage.terminal, false, "a limit breach must not close the stream; the run's error follows");
+    await source.append(event("event-limit-error", "error", breached, "2026-01-01T00:00:07.000Z"));
+    const deadPage = await source.page({ ...breached, after: beforeLimit, limit: 10 });
+    equal(deadPage.terminal, true, "the error after a limit breach closes the stream");
+    const death = source.subscribe(breached)[Symbol.asyncIterator]();
+    const delivered = [];
+    for (;;) {
+        const next = await death.next();
+        if (next.done)
+            break;
+        delivered.push(next.value.record.type);
+    }
+    equal(delivered.join(","), "turn_started,run_limit_exceeded,budget_exhausted,error", "a subscriber must read the breach and its attribution before the stream ends");
     await rejects(() => source.page({ ...input, ownership: { ...ownership, tenantId: "tenant-b" }, after: page.nextCursor }), "foreign cursor must fail closed");
     await rejects(() => source.append({ ...event("event-unredacted", "turn_started", input), redacted: false }), "unredacted append must fail");
     await rejects(() => source.page({ ...input, limit: 0 }), "invalid page limit must fail");
 }
 function event(id, type, input, timestamp = "2026-01-01T00:00:00.000Z") {
+    const scoped = { sessionId: input.sessionId, runId: input.runId };
     const event = type === "turn_started"
-        ? { type, sessionId: input.sessionId, runId: input.runId, turn: 1 }
-        : { type, sessionId: input.sessionId, runId: input.runId };
+        ? { type, ...scoped, turn: 1 }
+        : type === "run_limit_exceeded"
+            ? { type, ...scoped, breach: { limit: "maxTurns", maximum: 1, observed: 2 } }
+            : type === "budget_exhausted"
+                ? {
+                    type,
+                    ...scoped,
+                    limit: "maxTurns",
+                    consumed: { turns: 2, inputTokens: 0, providerAttempts: 1, requestBytes: 0 },
+                    closestOtherAxes: [],
+                    recentToolCalls: [],
+                }
+                : type === "error"
+                    ? { type, ...scoped, error: { message: "run limit exceeded" } }
+                    : { type, ...scoped };
     return { id, ...input.ownership, sessionId: input.sessionId, runId: input.runId, type, timestamp, event, redacted: true };
 }
 function equal(actual, expected, message) {

package/dist/testing/prefix-stability-conformance.d.ts

@@ -0,0 +1,59 @@
+import type { AgentConfig, Skill } from "../contracts.js";
+export interface PrefixStabilityConformanceOptions {
+    /**
+     * The host's own agent config, minus `provider`, `providerSource`, and `skills`:
+     * the runner installs its fixture provider and fixture skill registry so the
+     * scenario is deterministic and comparable across hosts.
+     */
+    readonly host: Omit<AgentConfig, "provider" | "providerSource" | "skills">;
+    /** Two distinct skills: the fixture loads `[0]` on the first turn and `[1]` on the second. */
+    readonly skills: readonly [Skill, Skill];
+    /** Minimum shared byte-prefix fraction between consecutive requests. Default `0.95`. */
+    readonly minContinuity?: number;
+    /**
+     * Which fraction gates the run: `"providerPrefix"` (default, today's behavior) asserts the
+     * provider-visible prefix; `"cacheablePrefix"` asserts the same measurement with tail segments
+     * removed, so a body-heavy or eager host is not failed for the tail it deliberately re-sends.
+     */
+    readonly assertOn?: "providerPrefix" | "cacheablePrefix";
+    /** Turn inputs; defaults are fixed strings so runs are comparable across hosts. */
+    readonly inputs?: readonly [string, string];
+    /**
+     * How many request pairs may break below `minContinuity` (default `0`, today's behavior). Use
+     * `1` for an assembly that folds or evicts exactly one boundary — an attention-compiler fold,
+     * a compaction, a budget eviction. More resets than declared fail, and fewer fail too: the
+     * fixture was supposed to invalidate the prefix, so a run that never did cannot pass vacuously.
+     */
+    readonly allowedResets?: number;
+}
+export interface PrefixStabilityConformanceResult {
+    /** Provider requests captured by the fixture (two per turn: skill load, then completion). */
+    readonly requests: number;
+    /** Lowest shared-prefix fraction observed across consecutive captured requests. */
+    readonly minContinuity: number;
+    /**
+     * The same lowest fraction with the session's tail segments removed from both requests of each
+     * pair — the provider-visible prefix the cache can actually keep paying for. Equals
+     * `minContinuity` when no captured request carried a tail segment.
+     */
+    readonly cacheableContinuity: number;
+    /**
+     * 1-based indexes of the captured requests whose asserted prefix broke below `minContinuity`
+     * (the later request of each pair), in ascending order — where the assembly invalidated the
+     * prefix instead of appending. Empty when every gap stayed above the minimum.
+     */
+    readonly resets: readonly number[];
+}
+/**
+ * Drive a real session through two staggered skill loads and assert that each
+ * provider request keeps a byte-identical leading prefix (messages **and** tool
+ * schemas) with its predecessor. Progressive disclosure appends a loaded body
+ * after the stable prefix, so the shared prefix stays intact; a host that
+ * rewrites the context block, the skill catalog, or any leading message per
+ * request fails with the offending request pair and the measured fraction.
+ * Reports both the provider-visible fraction and the same fraction with the
+ * session's tail segments removed; `assertOn` picks which one gates the run.
+ * A gap below the minimum is collected as a reset instead of failing in the
+ * loop, so `allowedResets` can permit the one boundary an assembly folds at.
+ */
+export declare function runPrefixStabilityConformance(options: PrefixStabilityConformanceOptions): Promise<PrefixStabilityConformanceResult>;

package/dist/testing/prefix-stability-conformance.js

@@ -0,0 +1,172 @@
+// ponytail: dependency-free conformance runner for prompt-cache prefix stability.
+// The runner owns the fixture provider (network-free, deterministic) and fixture
+// skills; everything else in `host` is the caller's production assembly — system
+// prompt, context providers, prompt builder, middleware, disclosure settings.
+// Throws plain Error; no test runner, no network, no credentials.
+import assert from "node:assert/strict";
+import { createAgent } from "../agent-session/create-agent.js";
+import { providerDone, providerThinkingDelta, toolCallContent } from "../provider-events.js";
+import { createLoadSkillTool } from "../skill-load.js";
+import { createSkillRegistry } from "../skills.js";
+/**
+ * Drive a real session through two staggered skill loads and assert that each
+ * provider request keeps a byte-identical leading prefix (messages **and** tool
+ * schemas) with its predecessor. Progressive disclosure appends a loaded body
+ * after the stable prefix, so the shared prefix stays intact; a host that
+ * rewrites the context block, the skill catalog, or any leading message per
+ * request fails with the offending request pair and the measured fraction.
+ * Reports both the provider-visible fraction and the same fraction with the
+ * session's tail segments removed; `assertOn` picks which one gates the run.
+ * A gap below the minimum is collected as a reset instead of failing in the
+ * loop, so `allowedResets` can permit the one boundary an assembly folds at.
+ */
+export async function runPrefixStabilityConformance(options) {
+    const { host, skills } = options;
+    const minContinuity = options.minContinuity ?? 0.95;
+    const [first, second] = skills;
+    assert.notEqual(first.name, second.name, "prefix stability conformance needs two distinct skills");
+    const bodies = [];
+    for (const skill of skills) {
+        const instructions = skill.instructions;
+        assert.ok(typeof instructions === "string" && instructions.length > 0, `prefix stability conformance skill ${skill.name} needs non-empty instructions`);
+        bodies.push(instructions);
+    }
+    const requests = [];
+    const registry = createSkillRegistry([...skills]);
+    const hostTools = host.tools && "list" in host.tools ? host.tools.list() : (host.tools ?? []);
+    const agent = createAgent({
+        ...host,
+        skills: registry,
+        tools: [...hostTools, createLoadSkillTool({ registry })],
+        provider: fixtureProvider(requests, [first.name, second.name], host.attentionCompiler === true || typeof host.attentionCompiler === "object"),
+    });
+    const session = agent.createSession();
+    const [firstInput, secondInput] = options.inputs ?? ["Prefix stability turn one", "Prefix stability turn two"];
+    const runOptions = { activeSkills: [first.name, second.name], limits: { maxToolRounds: 1 } };
+    await session.run(firstInput, runOptions);
+    await session.run(secondInput, runOptions);
+    assert.equal(requests.length, 4, `prefix stability conformance expected 4 provider requests (2 per staggered turn), captured ${requests.length}`);
+    // The session's own map holds the exact `Message` objects `appendTailSegment` allocated, so the
+    // classification is exact rather than a heuristic over host-authored content. (`tailSegments` is
+    // runtime-session state, not part of the public `AgentSession` contract, hence the narrow above.)
+    const isTail = tailClassifier(session.tailSegments);
+    const captured = requests.map((request) => measureRequest(request, isTail));
+    // Guard against a vacuous pass: both bodies must have been disclosed by the end.
+    const last = captured.at(-1)?.providerPrefix ?? "";
+    for (const [index, skill] of skills.entries()) {
+        assert.ok(last.includes(bodies[index] ?? ""), `prefix stability conformance: skill ${skill.name} body never reached the provider request — progressive disclosure did not expand it`);
+    }
+    const assertOn = options.assertOn ?? "providerPrefix";
+    const allowedResets = options.allowedResets ?? 0;
+    assert.ok(Number.isSafeInteger(allowedResets) && allowedResets >= 0, "prefix stability conformance allowedResets must be a non-negative safe integer");
+    let observed = 1;
+    let cacheableObserved = 1;
+    let previous = captured.at(0) ?? { providerPrefix: "", cacheablePrefix: "" };
+    // Collect every gap first: an allowed reset must not be hidden by a later assert, and the
+    // vacuity check needs the whole list to prove the fixture folded exactly as declared.
+    const gaps = [];
+    for (let index = 1; index < captured.length; index += 1) {
+        const next = captured[index] ?? previous;
+        const fraction = sharedPrefixFraction(previous.providerPrefix, next.providerPrefix);
+        const cacheableFraction = sharedPrefixFraction(previous.cacheablePrefix, next.cacheablePrefix);
+        observed = Math.min(observed, fraction);
+        cacheableObserved = Math.min(cacheableObserved, cacheableFraction);
+        const measured = assertOn === "cacheablePrefix" ? cacheableFraction : fraction;
+        if (measured < minContinuity)
+            gaps.push({ request: index + 1, fraction, cacheableFraction });
+        previous = next;
+    }
+    const resets = gaps.map((gap) => gap.request);
+    const measuredLabel = assertOn === "cacheablePrefix" ? "previous cacheable prefix (tail segments excluded)" : "previous provider prefix";
+    const minimum = (minContinuity * 100).toFixed(1);
+    const observedResets = `resets ${formatResets(resets)} of ${captured.length - 1} request pairs`;
+    const firstGap = gaps[0];
+    if (firstGap !== undefined && gaps.length > allowedResets) {
+        const measured = assertOn === "cacheablePrefix" ? firstGap.cacheableFraction : firstGap.fraction;
+        assert.fail(`prefix stability conformance: request ${firstGap.request - 1} → ${firstGap.request} kept ${(measured * 100).toFixed(1)}% of the ${measuredLabel} ` +
+            `(minimum ${minimum}%), and ${gaps.length} pair(s) broke below it (${observedResets}, allowedResets ${allowedResets}). ` +
+            "Late skill bodies must append after the stable prefix; recomposed context, an in-place skill-catalog rewrite, or any leading-message mutation invalidates it. " +
+            "Pass allowedResets for the fold, compaction, or eviction the assembly performs per run, or fix the assembly so every other gap stays byte-stable.");
+    }
+    if (gaps.length < allowedResets) {
+        assert.fail(`prefix stability conformance: allowedResets is ${allowedResets} but only ${gaps.length} pair(s) broke below the minimum (${minimum}% of the ${measuredLabel}); ${observedResets}. ` +
+            "The fixture was supposed to invalidate the prefix at those boundaries — drop allowedResets for an append-only assembly, or check the fold trigger or eviction condition actually fired.");
+    }
+    return { requests: captured.length, minContinuity: observed, cacheableContinuity: cacheableObserved, resets };
+}
+/**
+ * Deterministic reasoning block the fixture provider emits before each skill load when the host
+ * runs an attention compiler. Sized to be a real fraction of the request so the compiler's
+ * thinking stage (`thinkingKeepTurns`) has something to strip and the resulting fold is visible
+ * in the measured prefix.
+ */
+const FIXTURE_THINKING = "Prefix-stability fixture reasoning: the harness measures a byte-shared provider prefix, so this block exists only to give the attention-compiler thinking stage deterministic content to strip. ".repeat(17);
+/**
+ * Fixture provider: turn 1 loads `skillNames[0]`, turn 2 loads `skillNames[1]`, everything else
+ * completes. With `reasoning` (the host runs an attention compiler) each skill-load round also
+ * carries a thinking block, so the compiler's thinking stage has real content to fold.
+ */
+function fixtureProvider(requests, skillNames, reasoning) {
+    let call = 0;
+    return {
+        id: "prefix-stability-fixture",
+        async *generate(request) {
+            requests.push(request);
+            const index = call;
+            call += 1;
+            const skillName = skillNames[index >> 1];
+            if (index % 2 === 0 && skillName !== undefined) {
+                if (reasoning)
+                    yield providerThinkingDelta(FIXTURE_THINKING);
+                yield { type: "tool_call", call: toolCallContent(`prefix-stability-${index}`, "load_skill", { name: skillName }) };
+                return;
+            }
+            yield providerDone();
+        },
+    };
+}
+/**
+ * Classifies a captured message as a tail segment: by object identity first (the default builder
+ * passes the session's own `Message` objects through), then by serialized equality for builders
+ * that clone messages. Takes the pre-serialized fragment so each message is serialized once.
+ */
+function tailClassifier(tailSegments) {
+    const identities = new Set(tailSegments.values());
+    const values = new Set([...identities].map((message) => JSON.stringify(message)));
+    return (message, fragment) => identities.has(message) || values.has(fragment);
+}
+/**
+ * Provider-visible payload only — messages plus the tool schema fields sent on the wire — measured
+ * twice: whole, and with tail segments dropped. One JSON fragment per message/tool so a structural
+ * array boundary never reads as a byte divergence: an appended message list stays an exact prefix
+ * of the next request.
+ */
+function measureRequest(request, isTail) {
+    const toolParts = (request.tools ?? []).map((tool) => JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters }));
+    const providerParts = [...toolParts];
+    const cacheableParts = [...toolParts];
+    for (const message of request.messages) {
+        const fragment = JSON.stringify(message);
+        providerParts.push(fragment);
+        if (!isTail(message, fragment))
+            cacheableParts.push(fragment);
+    }
+    return { providerPrefix: providerParts.join("\n"), cacheablePrefix: cacheableParts.join("\n") };
+}
+/** Bracket form for reset lists, e.g. `[3]` or `[3, 4]`. */
+function formatResets(resets) {
+    return `[${resets.join(", ")}]`;
+}
+/** Byte-shared prefix as a fraction of the previous request, so a shrink is a cache miss. */
+function sharedPrefixFraction(previous, next) {
+    const before = Buffer.from(previous, "utf8");
+    const after = Buffer.from(next, "utf8");
+    if (before.length === 0)
+        return 1;
+    const limit = Math.min(before.length, after.length);
+    let shared = 0;
+    while (shared < limit && before[shared] === after[shared])
+        shared += 1;
+    return shared / before.length;
+}
+//# sourceMappingURL=prefix-stability-conformance.js.map

package/dist/testing/session-store-conformance.d.ts

@@ -11,8 +11,9 @@ export interface SessionStoreConformanceOptions {
      */
     readonly exerciseReadBranchPath?: boolean;
     /**
-     * When true, exercises optional `searchSessions` (empty page, limit cap,
-     * invalid limit/query rejection via `resolveSessionSearchQuery` semantics).
+     * When true, exercises optional `searchSessions`: invalid limit/query/kind rejection via
+     * `resolveSessionSearchQuery` semantics, empty page, limit cap, a written-message query
+     * round-trip (`entryId`/`runId`/`turn`/`snippet`), the `kind` filter, and ownership bounds.
      * Skipped when the store does not implement `searchSessions`.
      */
     readonly exerciseSearchSessions?: boolean;

package/dist/testing/session-store-conformance.js

@@ -113,6 +113,54 @@ async function assertSessionStoreSearchSessions(store) {
     await reject(() => search({ limit: Number.NaN }), (error) => error instanceof TypeError, "searchSessions must reject NaN limit");
     await reject(() => search({ limit: HARD_MAX_SESSION_SEARCH_LIMIT + 1 }), (error) => error instanceof TypeError, "searchSessions must reject oversize limit");
     await reject(() => search({ query: "x".repeat(HARD_MAX_SESSION_SEARCH_QUERY_BYTES + 1) }), (error) => error instanceof TypeError, "searchSessions must reject oversize query string");
+    await reject(() => search({ kind: "not-an-entry-kind" }), (error) => error instanceof TypeError, "searchSessions must reject an unknown kind");
+    // Query round-trip: a written message must be findable and the hit must point at it.
+    const searchSessionId = "conformance-search";
+    const token = "zzconformancesearchtoken";
+    const matchedEntry = {
+        id: "conformance-search-entry",
+        sessionId: searchSessionId,
+        timestamp: "2026-01-01T00:00:05.000Z",
+        kind: "message",
+        runId: "conformance-run",
+        message: { role: "user", content: [{ type: "text", text: `${token} body text` }] },
+    };
+    await store.append(matchedEntry);
+    const found = await search({ query: token, limit: 5 });
+    const hit = found.items.find((item) => item.sessionId === searchSessionId);
+    if (!hit) {
+        throw new Error("searchSessions must find a session by matching message text");
+    }
+    if (hit.entryId !== matchedEntry.id) {
+        throw new Error(`searchSessions must point at the matched entry; got ${String(hit.entryId)}`);
+    }
+    if (hit.runId !== matchedEntry.runId) {
+        throw new Error("searchSessions must carry the matched entry runId");
+    }
+    if (typeof hit.snippet !== "string" || !hit.snippet.includes(token)) {
+        throw new Error("searchSessions snippet must contain the matched text");
+    }
+    if (!Number.isSafeInteger(hit.turn) || hit.turn < 1) {
+        throw new Error("searchSessions must carry a 1-based matched-entry turn index");
+    }
+    const annotationOnly = await search({ query: token, kind: "summary", limit: 5 });
+    if (annotationOnly.items.some((item) => item.sessionId === searchSessionId)) {
+        throw new Error("searchSessions kind filter must exclude non-matching entry kinds");
+    }
+    // One hit per session: a second matching entry must not add a second row for the same session.
+    await store.append({
+        id: "conformance-search-entry-2",
+        parentId: matchedEntry.id,
+        sessionId: searchSessionId,
+        timestamp: "2026-01-01T00:00:06.000Z",
+        kind: "summary",
+        summary: `${token} recap`,
+    });
+    const deduped = await search({ query: token, limit: 5 });
+    const sessionHits = deduped.items.filter((item) => item.sessionId === searchSessionId);
+    if (sessionHits.length !== 1) {
+        throw new Error(`searchSessions must return one hit per session; got ${sessionHits.length}`);
+    }
     const empty = await search(resolveSessionSearchQuery({
         workspaceRoot: "__prism_conformance_empty__",
         limit: 5,

package/dist/tools.d.ts

@@ -58,6 +58,11 @@ export declare function createToolRegistry(tools?: readonly ToolDefinition[], op
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 /** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
 export declare const HARD_RUN_TOOL_NAMES = 1024;
+/** Restrictive clamp: keep listed order; names outside the grant are dropped (not thrown). */
+export declare function clampTurnToolNames(listed: readonly ToolDefinition[], requested: readonly string[]): {
+    readonly tools: readonly ToolDefinition[];
+    readonly dropped: readonly string[];
+};
 /**
  * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
  * Fresh unknown names fail closed; resume drops names the current registry no longer has.

package/dist/tools.js

@@ -1,5 +1,5 @@
 import { isJsonObject } from "./config.js";
-import { GuardrailError, runGuardrails } from "./guardrails.js";
+import { GuardrailError, guardrailRefusalText, runGuardrails } from "./guardrails.js";
 import { assertIdentityActive, assertIdentityMatchesOwnership, ownershipFromIdentity } from "./identity.js";
 import { createId } from "./ids.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
@@ -61,15 +61,15 @@ export function filterTools(tools, filter) {
 /** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
 export const HARD_RUN_TOOL_NAMES = 1024;
 const MAX_RUN_TOOL_NAME_CHARS = 256;
-function assertRunToolNames(names) {
+function assertRunToolNames(names, label = "RunOptions.toolNames") {
     if (names.length > HARD_RUN_TOOL_NAMES) {
-        throw new TypeError(`RunOptions.toolNames exceeds ${HARD_RUN_TOOL_NAMES} entries`);
+        throw new TypeError(`${label} exceeds ${HARD_RUN_TOOL_NAMES} entries`);
     }
     const out = [];
     const seen = new Set();
     for (const name of names) {
         if (typeof name !== "string" || name.length === 0 || name.length > MAX_RUN_TOOL_NAME_CHARS) {
-            throw new TypeError(`RunOptions.toolNames entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
+            throw new TypeError(`${label} entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
         }
         if (!seen.has(name)) {
             seen.add(name);
@@ -78,6 +78,14 @@ function assertRunToolNames(names) {
     }
     return out;
 }
+/** Restrictive clamp: keep listed order; names outside the grant are dropped (not thrown). */
+export function clampTurnToolNames(listed, requested) {
+    const names = assertRunToolNames(requested, "toolNarrowing");
+    const grant = new Set(listed.map((tool) => tool.name));
+    const dropped = names.filter((name) => !grant.has(name));
+    const allow = names.filter((name) => grant.has(name));
+    return { tools: allow.length === 0 ? [] : filterTools(listed, { allow }), dropped };
+}
 /**
  * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
  * Fresh unknown names fail closed; resume drops names the current registry no longer has.
@@ -125,7 +133,7 @@ export async function dispatchToolCall(options) {
     if (inputGuards.terminal) {
         if (inputGuards.terminal.action !== "block")
             throw new GuardrailError(inputGuards.terminal);
-        return blocked(mediatedCall, options.context, "guardrail_blocked", { message: "Tool call blocked by guardrail" }, options, startedAt);
+        return blocked(mediatedCall, options.context, "guardrail_blocked", { message: guardrailBlockMessage(inputGuards.terminal) }, options, startedAt);
     }
     const tool = options.registry.get(mediatedCall.name);
     const postcheck = await checkCall(mediatedCall, options, startedAt);
@@ -232,7 +240,7 @@ export async function dispatchToolCall(options) {
                 throw new GuardrailError(outputGuards.terminal);
             if (effect)
                 return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
-            return blocked(mediatedCall, context, "guardrail_blocked", { message: "Tool result blocked by guardrail" }, options, startedAt);
+            return blocked(mediatedCall, context, "guardrail_blocked", { message: guardrailBlockMessage(outputGuards.terminal) }, options, startedAt);
         }
         if (effect && mediatedResult.error)
             return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
@@ -442,6 +450,13 @@ function isSuspended(error) {
 function isLoopStateError(error) {
     return typeof error?.code === "string" && error.code.startsWith("ERR_PRISM_LOOP_");
 }
+/**
+ * Plan 104 T3/T4: the model-visible refusal line for a terminal guardrail decision. `guardrailRefusalText`
+ * names a compiled pack rule (bounded, redacted); any other guardrail keeps the neutral stage text.
+ */
+function guardrailBlockMessage(record) {
+    return (guardrailRefusalText(record) ?? (record.stage === "tool_output" ? "Tool result blocked by guardrail" : "Tool call blocked by guardrail"));
+}
 function isDelegationSuspended(error) {
     return error?.code === "ERR_PRISM_DELEGATION_SUSPENDED";
 }

package/dist/usage-estimation.d.ts

@@ -0,0 +1,29 @@
+/** Model-family chars/token tables and the family text estimator (plan 091 Task 1).
+ *
+ * Pure and O(text length): no network, no I/O, no content retention. These are
+ * heuristics, not tokenizers — harnesses universally approximate. Reported usage
+ * always wins; estimates exist so missing usage is never shown as zero.
+ *
+ * Ratio provenance: `openai` is calibrated against `o200k_base` counts on the
+ * in-repo fixtures (`src/__tests__/usage-estimation.test.ts`); the other families
+ * use their published tokenizer guidance ranges and are intentionally rounded
+ * toward over-counting, because an overestimated context meter is safe while an
+ * underestimated one under-compacts. `unknown` is the most conservative table so
+ * an unidentified model can never look smaller than a known one.
+ */
+import type { ModelFamily, TokenEstimateConfidence } from "./contracts-core/usage.js";
+/** Row of {@link MODEL_FAMILY_TOKENS}: prose chars per token, chat-template
+ *  tokens added once per message, and the confidence label for the table. */
+export interface ModelFamilyTokens {
+    readonly charsPerToken: number;
+    readonly perMessageOverhead: number;
+    readonly confidence: TokenEstimateConfidence;
+}
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+export declare const MODEL_FAMILY_TOKENS: Readonly<Record<ModelFamily, ModelFamilyTokens>>;
+/** Resolve a model id (e.g. `"claude-sonnet-4.5"`), provider id, or family name
+ *  to a table key. Unmatched input is `"unknown"` — never a throw. */
+export declare function resolveModelFamily(model?: string): ModelFamily;
+/** Estimate tokens for one flattened text under a family's ratios. The message
+ *  level (`estimateMessageTokens`) owns per-message overhead; this is text-only. */
+export declare function estimateTextTokensForFamily(text: string, modelFamily?: string): number;

package/dist/usage-estimation.js

@@ -0,0 +1,79 @@
+/** CJK ideographs/kana/hangul tokenize near 1.5 chars/token in modern family tokenizers. */
+const CJK_CHARS_PER_TOKEN = 1.5;
+/** Fenced code tokenizes worse than prose: code ratio = prose ratio * this factor. */
+const CODE_RATIO_FACTOR = 0.88;
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+export const MODEL_FAMILY_TOKENS = {
+    anthropic: { charsPerToken: 3.7, perMessageOverhead: 4, confidence: "medium" },
+    openai: { charsPerToken: 5.0, perMessageOverhead: 3, confidence: "medium" },
+    google: { charsPerToken: 3.9, perMessageOverhead: 4, confidence: "medium" },
+    deepseek: { charsPerToken: 3.8, perMessageOverhead: 4, confidence: "medium" },
+    "openrouter-generic": { charsPerToken: 4.4, perMessageOverhead: 4, confidence: "medium" },
+    mistral: { charsPerToken: 3.9, perMessageOverhead: 3, confidence: "medium" },
+    unknown: { charsPerToken: 3.5, perMessageOverhead: 6, confidence: "low" },
+};
+/** Model-id patterns per family. Family names themselves also resolve (see `resolveModelFamily`). */
+const FAMILY_PATTERNS = [
+    ["anthropic", /claude|anthropic/i],
+    ["openai", /gpt-|openai|chatgpt|codex|^o[1-9]/i],
+    ["google", /gemini|gemma|palm|google/i],
+    ["deepseek", /deepseek/i],
+    ["mistral", /mistral|mixtral|codestral|magistral|devstral|pixtral|ministral/i],
+    ["openrouter-generic", /openrouter/i],
+];
+/** Resolve a model id (e.g. `"claude-sonnet-4.5"`), provider id, or family name
+ *  to a table key. Unmatched input is `"unknown"` — never a throw. */
+export function resolveModelFamily(model) {
+    if (typeof model !== "string")
+        return "unknown";
+    const id = model.trim();
+    if (id in MODEL_FAMILY_TOKENS)
+        return id;
+    for (const [family, pattern] of FAMILY_PATTERNS) {
+        if (pattern.test(id))
+            return family;
+    }
+    return "unknown";
+}
+/** Estimate tokens for one flattened text under a family's ratios. The message
+ *  level (`estimateMessageTokens`) owns per-message overhead; this is text-only. */
+export function estimateTextTokensForFamily(text, modelFamily) {
+    const { charsPerToken } = MODEL_FAMILY_TOKENS[resolveModelFamily(modelFamily)];
+    let cjk = 0;
+    for (let index = 0; index < text.length;) {
+        const codePoint = text.codePointAt(index) ?? 0; // unreachable 0: index < length; avoids a non-null assertion
+        if (isCjkCodePoint(codePoint))
+            cjk += 1;
+        index += codePoint > 0xffff ? 2 : 1;
+    }
+    const code = fencedChars(text);
+    const other = Math.max(0, text.length - cjk - code);
+    return Math.ceil(cjk / CJK_CHARS_PER_TOKEN + code / (charsPerToken * CODE_RATIO_FACTOR) + other / charsPerToken);
+}
+/** Length of the characters enclosed by ``` fence pairs (unclosed fence runs to the end). */
+function fencedChars(text) {
+    let total = 0;
+    let index = text.indexOf("```");
+    while (index !== -1) {
+        const end = text.indexOf("```", index + 3);
+        if (end === -1) {
+            total += text.length - index;
+            break;
+        }
+        total += end + 3 - index;
+        index = text.indexOf("```", end + 3);
+    }
+    return total;
+}
+/** Han, kana, hangul, CJK punctuation/fullwidth, and ext-B+ ideograph ranges. */
+function isCjkCodePoint(codePoint) {
+    return ((codePoint >= 0x3000 && codePoint <= 0x303f) ||
+        (codePoint >= 0x3040 && codePoint <= 0x30ff) ||
+        (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7af) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xff00 && codePoint <= 0xffef) ||
+        (codePoint >= 0x20000 && codePoint <= 0x2fa1f));
+}
+//# sourceMappingURL=usage-estimation.js.map