@arnilo/prism 0.8.0 → 0.9.0

package/dist/middleware.js

@@ -1,4 +1,45 @@
 import { errorToErrorInfo } from "./redaction.js";
+/** Host answered with a malformed deterministic turn. Fails the run closed — never falls through. */
+export class DeterministicTurnError extends Error {
+    code = "ERR_PRISM_DETERMINISTIC_TURN";
+    constructor(message) {
+        super(message);
+        this.name = "DeterministicTurnError";
+    }
+}
+/** Provenance ids stay ids: bounded, no whitespace or separators outside the id alphabet. */
+const DETERMINISTIC_MIDDLEWARE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+// Assistant-visible blocks only: a deterministic answer cannot smuggle tool execution/authority.
+const DETERMINISTIC_BLOCK_TYPES = new Set(["text", "image", "audio", "file", "document", "video", "thinking"]);
+/**
+ * Validate a host deterministic answer at the trust boundary: non-empty assistant-visible content and
+ * mandatory bounded provenance. Throws instead of degrading to a provider call.
+ */
+export function validateDeterministicTurnAnswer(value) {
+    if (typeof value !== "object" || value === null)
+        throw new DeterministicTurnError("answer must be an object");
+    const answer = value;
+    if (!Array.isArray(answer.content) || answer.content.length === 0) {
+        throw new DeterministicTurnError("answer.content must be a non-empty content block array");
+    }
+    for (const block of answer.content) {
+        const type = block?.type;
+        if (typeof block !== "object" || block === null || typeof type !== "string" || !DETERMINISTIC_BLOCK_TYPES.has(type)) {
+            throw new DeterministicTurnError("answer.content blocks must be assistant-visible content blocks (text, image, audio, file, document, video, thinking)");
+        }
+        if (type === "text" && typeof block.text !== "string") {
+            throw new DeterministicTurnError("answer.content text blocks require a string text");
+        }
+        if (type === "thinking" && typeof block.text !== "string") {
+            throw new DeterministicTurnError("answer.content thinking blocks require a string text");
+        }
+    }
+    const middleware = answer.provenance?.middleware;
+    if (typeof middleware !== "string" || !DETERMINISTIC_MIDDLEWARE_ID.test(middleware)) {
+        throw new DeterministicTurnError("answer.provenance.middleware must be a bounded id (1-64 chars: letters, digits, . _ : -)");
+    }
+    return { content: answer.content, provenance: { middleware } };
+}
 function middlewareError(error, hook, secrets) {
     return { type: "extension_error", extension: `middleware:${hook}`, error: errorToErrorInfo(error, secrets) };
 }

package/dist/node/session-store-jsonl.js

@@ -1,6 +1,7 @@
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, SessionSearchUnsupportedError, } from "../contracts.js";
+import { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, } from "../contracts.js";
+import { searchLinearSessions } from "../session-stores.js";
 import { isNodeErrorCode } from "./config.js";
 export function createJsonlSessionStore(pathOrOptions) {
     const options = typeof pathOrOptions === "string" ? { path: pathOrOptions, createDirectory: true } : pathOrOptions;
@@ -50,8 +51,22 @@ export function createJsonlSessionStore(pathOrOptions) {
         async get(id) {
             return findEntry(path, id);
         },
-        async searchSessions() {
-            throw new SessionSearchUnsupportedError("JSONL session store does not support searchSessions");
+        async searchSessions(query) {
+            // ponytail: no index - every search reads and parses the file (O(corpus) time and memory), the
+            // recommended indexed paths are the SQLite/Postgres adapters. Corrupt lines are quarantined
+            // exactly as in list()/get(), and the contract linear caps bound entries/text scanned.
+            const { entries } = await readJsonlSessionEntries(path);
+            const bySession = new Map();
+            const leafBySession = new Map();
+            for (const entry of entries) {
+                const sessionEntries = bySession.get(entry.sessionId);
+                if (sessionEntries)
+                    sessionEntries.push(entry);
+                else
+                    bySession.set(entry.sessionId, [entry]);
+                leafBySession.set(entry.sessionId, entry.id);
+            }
+            return searchLinearSessions(bySession, leafBySession, query);
         },
     };
 }

package/dist/observability.js

@@ -1,9 +1,15 @@
+import { createHash } from "node:crypto";
 export function createProviderTurnMetadata(request, providerId, fields = {}) {
+    const names = (request.tools ?? []).map((tool) => tool.name);
     return {
         providerId,
         model: request.model,
         requestId: readRequestId(request),
         ...fields,
+        tools: {
+            count: names.length,
+            idsHash: `sha256:${createHash("sha256").update(JSON.stringify(names), "utf8").digest("hex")}`,
+        },
     };
 }
 export function readProviderHttpStatus(error) {

package/dist/provider-events.d.ts

@@ -1,4 +1,4 @@
-import type { ContentBlock, JsonObject, ProviderEvent, ToolCallContent, ToolCallDeltaContent, Usage } from "./contracts.js";
+import type { ContentBlock, JsonObject, ProviderEvent, ProviderStopReason, ToolCallContent, ToolCallDeltaContent, Usage } from "./contracts.js";
 export declare function providerTextDelta(text: string): ProviderEvent;
 export declare function providerThinkingDelta(text: string, signature?: string): ProviderEvent;
 export declare function providerContentDelta(content: ContentBlock): ProviderEvent;
@@ -13,7 +13,13 @@ export declare function providerToolCallDeltaContent(delta: Omit<ToolCallDeltaCo
 export declare function providerContinuationRequired(cursor: string, reason?: string): ProviderEvent;
 export declare function reconstructToolCallDeltas(events: readonly ProviderEvent[]): readonly ToolCallContent[];
 export declare function providerUsage(usage: Usage): ProviderEvent;
-export declare function providerDone(usage?: Usage): ProviderEvent;
+/**
+ * Map a native provider stop/finish reason onto the closed taxonomy. A missing, non-string, or
+ * unmapped value returns `"unknown"` rather than throwing, so a new wire value can never fail a
+ * run (plan 087 T1).
+ */
+export declare function mapProviderStopReason(native: string | null | undefined): ProviderStopReason;
+export declare function providerDone(usage?: Usage, stopReason?: ProviderStopReason): ProviderEvent;
 export declare function providerError(error: unknown, secrets?: readonly (string | undefined)[]): Extract<ProviderEvent, {
     type: "error";
 }>;

package/dist/provider-events.js

@@ -46,8 +46,66 @@ export function reconstructToolCallDeltas(events) {
 export function providerUsage(usage) {
     return { type: "usage", usage };
 }
-export function providerDone(usage) {
-    return { type: "done", usage };
+/**
+ * One shared native → taxonomy table (plan 087 T1). Every adapter routes its wire reason
+ * through `mapProviderStopReason`, so hosts switch on one closed union instead of per-provider
+ * strings. Keys are lowercased wire values; `unknown` never appears here — it is the fallback.
+ */
+const PROVIDER_STOP_REASONS = Object.freeze({
+    // OpenAI Chat Completions (`finish_reason`) and generic OpenAI-compatible routes.
+    stop: "end_turn",
+    length: "max_output_tokens",
+    tool_calls: "tool_calls",
+    function_call: "tool_calls",
+    content_filter: "content_filter",
+    // Messages-style `stop_reason` routes and Bedrock Converse (`stopReason`).
+    end_turn: "end_turn",
+    stop_sequence: "end_turn",
+    pause_turn: "end_turn",
+    tool_use: "tool_calls",
+    max_tokens: "max_output_tokens",
+    refusal: "content_filter",
+    // Google generateContent (`finishReason`).
+    safety: "content_filter",
+    recitation: "content_filter",
+    blocklist: "content_filter",
+    prohibited_content: "content_filter",
+    spii: "content_filter",
+    image_safety: "content_filter",
+    language: "content_filter",
+    malformed_function_call: "provider_error",
+    unexpected_tool_call: "provider_error",
+    // OpenAI Responses (status / `incomplete_details.reason`).
+    completed: "end_turn",
+    failed: "provider_error",
+    cancelled: "abort",
+    canceled: "abort",
+    // Bedrock Converse guarded routes.
+    content_filtered: "content_filter",
+    guardrail_intervened: "content_filter",
+    malformed_model_output: "provider_error",
+    malformed_tool_use: "provider_error",
+    // AI SDK unified finish reasons (hyphenated).
+    "content-filter": "content_filter",
+    "tool-calls": "tool_calls",
+    error: "provider_error",
+    other: "unknown",
+    unknown: "unknown",
+    abort: "abort",
+    aborted: "abort",
+});
+/**
+ * Map a native provider stop/finish reason onto the closed taxonomy. A missing, non-string, or
+ * unmapped value returns `"unknown"` rather than throwing, so a new wire value can never fail a
+ * run (plan 087 T1).
+ */
+export function mapProviderStopReason(native) {
+    if (typeof native !== "string")
+        return "unknown";
+    return PROVIDER_STOP_REASONS[native.trim().toLowerCase()] ?? "unknown";
+}
+export function providerDone(usage, stopReason) {
+    return { type: "done", usage, ...(stopReason === undefined ? {} : { stopReason }) };
 }
 export function providerError(error, secrets = []) {
     const info = errorToErrorInfo(error, secrets);

package/dist/providers/openai-compatible.js

@@ -1,5 +1,5 @@
 import { resolveCredentialValue } from "../credentials.js";
-import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
+import { mapProviderStopReason, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
 import { assertStructuredOutputRequestSupported } from "../structured-output.js";
 import { trimTrailingSlashes } from "../trim-trailing-slashes.js";
 import { applyOpenAIChatStructuredOutput, assertOpenAIChatMessage, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
@@ -13,6 +13,7 @@ export async function* openAIChatEvents(body, options = {}) {
     let usage;
     let sawDoneMarker = false;
     let sawFinishReason = false;
+    let finishReason;
     for await (const sseEvent of readSseEvents(body, { signal: options.signal })) {
         if (options.onComment && sseEvent.comments?.length) {
             for (const text of sseEvent.comments) {
@@ -43,8 +44,10 @@ export async function* openAIChatEvents(body, options = {}) {
             yield providerUsage(mapped);
         }
         for (const choice of parsed.choices ?? []) {
-            if (choice.finish_reason)
+            if (choice.finish_reason) {
                 sawFinishReason = true;
+                finishReason = choice.finish_reason;
+            }
             const delta = choice.delta ?? {};
             if (typeof delta.content === "string" && delta.content)
                 yield providerTextDelta(delta.content);
@@ -83,7 +86,7 @@ export async function* openAIChatEvents(body, options = {}) {
     for (const call of tools.values()) {
         yield providerToolCall(toolCallFromArgumentsText(call.id, call.name, call.argumentsText));
     }
-    yield providerDone((options.strictCompletion ?? true) || options.doneUsage ? usage : undefined);
+    yield providerDone((options.strictCompletion ?? true) || options.doneUsage ? usage : undefined, finishReason === undefined ? undefined : mapProviderStopReason(finishReason));
 }
 export function createOpenAICompatibleProvider(options) {
     const providerId = options.id ?? "openai-compatible";

package/dist/run-bundle.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { agentFingerprint, BUILT_IN_LOOP_REVISIONS } from "./agent-run-state.js";
+import { describeGuardrailPacks } from "./guardrails.js";
 import { describeStorage } from "./host-composition.js";
 import { canonicalizeJsonSchema } from "./providers/schema.js";
 import { resolveRunLimits } from "./run-limits.js";
@@ -51,7 +52,7 @@ export function snapshotRunBundle(input) {
             effect: tool.effect === undefined ? null : typeof tool.effect === "function" ? "classifier" : tool.effect.kind,
         })),
         activeSkills: run?.activeSkills ?? null,
-        guardrails: guardrailRows(config.guardrails, run?.guardrails),
+        guardrails: [...guardrailRows(config.guardrails, run?.guardrails), ...describeGuardrailPacks(input.config?.guardrailPacks)],
         loop: loopIdentity(effectiveLoop),
         thinkingLevel: run?.thinkingLevel ?? config.thinkingLevel ?? null,
         limits: resolveRunLimits(config.limits, run?.limits),

package/dist/run-limits.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedRunLimits, RunLimitBreach, RunLimitCounters, RunLimitName, RunLimits, Usage } from "./contracts.js";
+import type { BudgetAxisUsage, BudgetConsumedCounters, ResolvedRunLimits, RunLimitBreach, RunLimitCounters, RunLimitName, RunLimits, ToolCallSummary, Usage } from "./contracts.js";
 export declare const DEFAULT_RUN_LIMITS: Readonly<{
     maxTurns: 16;
     maxProviderAttempts: 24;
@@ -51,3 +51,13 @@ export declare class RunLimitTracker {
     private exceed;
 }
 export declare function createRunLimitTracker(limits: RunLimits | undefined, options?: RunLimitTrackerOptions): RunLimitTracker;
+/**
+ * Build the `budget_exhausted` payload (plan 087 T2): which axis fired, the counters a host reads
+ * first, the closest other axes, and the last dispatched tool calls (hashes only).
+ */
+export declare function describeBudgetExhaustion(tracker: RunLimitTracker, breach: RunLimitBreach, recentToolCalls: readonly ToolCallSummary[]): {
+    limit: RunLimitName;
+    consumed: BudgetConsumedCounters;
+    closestOtherAxes: BudgetAxisUsage[];
+    recentToolCalls: ToolCallSummary[];
+};

package/dist/run-limits.js

@@ -263,4 +263,50 @@ export class RunLimitTracker {
 export function createRunLimitTracker(limits, options) {
     return new RunLimitTracker(resolveRunLimits(undefined, limits), options);
 }
+/** Product axes reported as "how close was everything else" (plan 087 T2). Request/response bytes
+ *  stay out: their caps are per-frame, so a run-lifetime ratio would be meaningless. */
+const ATTRIBUTION_AXES = [
+    { axis: "maxTurns", counter: "turns" },
+    { axis: "maxProviderAttempts", counter: "providerAttempts" },
+    { axis: "maxToolRounds", counter: "toolRounds" },
+    { axis: "maxToolCalls", counter: "toolCalls" },
+    { axis: "maxWallTimeMs", counter: "wallTimeMs" },
+    { axis: "maxInputTokens", counter: "inputTokens" },
+    { axis: "maxOutputTokens", counter: "outputTokens" },
+    { axis: "maxTotalTokens", counter: "totalTokens" },
+    { axis: "maxCost", counter: "cost" },
+];
+const CLOSEST_AXIS_COUNT = 3;
+function axisCap(limits, axis) {
+    if (axis === "maxCost")
+        return limits.maxCost?.amount;
+    const value = limits[axis];
+    return typeof value === "number" ? value : null;
+}
+/**
+ * Build the `budget_exhausted` payload (plan 087 T2): which axis fired, the counters a host reads
+ * first, the closest other axes, and the last dispatched tool calls (hashes only).
+ */
+export function describeBudgetExhaustion(tracker, breach, recentToolCalls) {
+    const counters = tracker.snapshot();
+    const closestOtherAxes = ATTRIBUTION_AXES.filter(({ axis }) => axis !== breach.limit)
+        .flatMap(({ axis, counter }) => {
+        const cap = axisCap(tracker.limits, axis);
+        return typeof cap === "number" && cap > 0 ? [{ axis, cap, used: counters[counter] }] : [];
+    })
+        .map(({ axis, cap, used }) => ({ axis, usedRatio: Math.round(Math.min(1, used / cap) * 10_000) / 10_000 }))
+        .sort((a, b) => b.usedRatio - a.usedRatio)
+        .slice(0, CLOSEST_AXIS_COUNT);
+    return {
+        limit: breach.limit,
+        consumed: {
+            turns: counters.turns,
+            inputTokens: counters.inputTokens,
+            providerAttempts: counters.providerAttempts,
+            requestBytes: counters.requestBytes,
+        },
+        closestOtherAxes,
+        recentToolCalls: [...recentToolCalls],
+    };
+}
 //# sourceMappingURL=run-limits.js.map

package/dist/session-stores.d.ts

@@ -1,4 +1,4 @@
-import { type BranchReader, type Message, type SessionBranchRead, type SessionEntry, type SessionStore } from "./contracts.js";
+import { type BranchReader, type Message, type PersistencePage, type SessionBranchRead, type SessionEntry, type SessionSearchHit, type SessionSearchQuery, type SessionStore } from "./contracts.js";
 export interface CreateSessionEntryOptions extends Omit<SessionEntry, "id" | "timestamp"> {
     readonly id?: string;
     readonly timestamp?: string;
@@ -40,4 +40,15 @@ export interface CreateMemorySessionStoreOptions {
         readonly maxLinearBytes?: number;
     };
 }
+/** Resolved bounds for the capped linear session scan. */
+export interface LinearSearchCaps {
+    readonly sessions: number;
+    readonly entries: number;
+    readonly bytes: number;
+}
 export declare function createMemorySessionStore(initialEntries?: readonly SessionEntry[], options?: CreateMemorySessionStoreOptions): SessionStore;
+/**
+ * Shared linear (unindexed) session search over already-grouped entries: the memory store's default
+ * mode and the JSONL store's implementation. `caps` defaults to the contract linear caps.
+ */
+export declare function searchLinearSessions(bySession: Map<string, SessionEntry[]>, leafBySession: Map<string, string>, query: SessionSearchQuery, caps?: LinearSearchCaps): PersistencePage<SessionSearchHit>;

package/dist/session-stores.js

@@ -133,7 +133,7 @@ export function createMemorySessionStore(initialEntries = [], options = {}) {
         async searchSessions(query) {
             if (mode === "unsupported")
                 throw new SessionSearchUnsupportedError();
-            return searchMemorySessionsLinear(bySession, leafBySession, query, searchCaps);
+            return searchLinearSessions(bySession, leafBySession, query, searchCaps);
         },
     };
     function add(entry, options) {
@@ -175,7 +175,11 @@ export function createMemorySessionStore(initialEntries = [], options = {}) {
         leafBySession.set(entry.sessionId, entry.id);
     }
 }
-function searchMemorySessionsLinear(bySession, leafBySession, query, caps) {
+/**
+ * Shared linear (unindexed) session search over already-grouped entries: the memory store's default
+ * mode and the JSONL store's implementation. `caps` defaults to the contract linear caps.
+ */
+export function searchLinearSessions(bySession, leafBySession, query, caps = resolveLinearSearchCaps(undefined)) {
     const q = resolveSessionSearchQuery(query);
     q.signal?.throwIfAborted();
     let sessionsScanned = 0;
@@ -203,13 +207,20 @@ function searchMemorySessionsLinear(bySession, leafBySession, query, caps) {
         let matchedQuery = false;
         let matchedProvider = false;
         let matchedModel = false;
+        let matchedKind = false;
+        let matchedEntry;
         let snippetSource;
+        let turn = 0;
         for (const entry of entries) {
             if (entriesScanned >= caps.entries)
                 break;
             if (bytesScanned >= caps.bytes)
                 break;
             entriesScanned += 1;
+            turn += 1;
+            const kindMatches = q.kind === undefined || q.kind.includes(entry.kind);
+            if (kindMatches)
+                matchedKind = true;
             const text = entrySearchText(entry);
             bytesScanned += utf8Bytes(text) + utf8Bytes(entry.label) + utf8Bytes(entry.summary);
             if (entry.timestamp > updatedAt)
@@ -234,11 +245,12 @@ function searchMemorySessionsLinear(bySession, leafBySession, query, caps) {
                 matchedLabel = true;
             if (q.summary && entry.summary?.includes(q.summary))
                 matchedSummary = true;
-            if (q.query) {
+            if (q.query && kindMatches) {
                 const hay = `${entry.label ?? ""}\n${entry.summary ?? ""}\n${text}`;
                 if (hay.includes(q.query)) {
                     matchedQuery = true;
-                    snippetSource ??= entry.label ?? entry.summary ?? text;
+                    matchedEntry ??= { entry, turn };
+                    snippetSource ??= [entry.label, entry.summary, text].find((part) => part?.includes(q.query)) ?? hay;
                 }
             }
             if (q.provider && (entry.model?.provider === q.provider || metaProvider(entry) === q.provider))
@@ -260,6 +272,8 @@ function searchMemorySessionsLinear(bySession, leafBySession, query, caps) {
             continue;
         if (q.query && !matchedQuery)
             continue;
+        if (q.kind && (q.query ? matchedEntry === undefined : !matchedKind))
+            continue;
         if (q.provider && !matchedProvider)
             continue;
         if (q.model && !matchedModel)
@@ -271,6 +285,9 @@ function searchMemorySessionsLinear(bySession, leafBySession, query, caps) {
         matches.push({
             sessionId,
             leafId: leafBySession.get(sessionId),
+            entryId: matchedEntry?.entry.id,
+            runId: matchedEntry?.entry.runId,
+            turn: matchedEntry?.turn,
             updatedAt: updatedAt || undefined,
             label,
             summary,

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,30 @@
+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;
+    /** Turn inputs; defaults are fixed strings so runs are comparable across hosts. */
+    readonly inputs?: readonly [string, string];
+}
+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;
+}
+/**
+ * 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.
+ */
+export declare function runPrefixStabilityConformance(options: PrefixStabilityConformanceOptions): Promise<PrefixStabilityConformanceResult>;

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

@@ -0,0 +1,104 @@
+// 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, 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.
+ */
+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]),
+    });
+    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}`);
+    const serialized = requests.map(serializeRequest);
+    // Guard against a vacuous pass: both bodies must have been disclosed by the end.
+    const last = serialized.at(-1) ?? "";
+    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`);
+    }
+    let observed = 1;
+    let previous = serialized.at(0) ?? "";
+    for (let index = 1; index < serialized.length; index += 1) {
+        const next = serialized[index] ?? "";
+        const fraction = sharedPrefixFraction(previous, next);
+        observed = Math.min(observed, fraction);
+        assert.ok(fraction >= minContinuity, `prefix stability conformance: request ${index} → ${index + 1} kept ${(fraction * 100).toFixed(1)}% of the previous provider prefix ` +
+            `(minimum ${(minContinuity * 100).toFixed(1)}%). Late skill bodies must append after the stable prefix; ` +
+            "recomposed context, an in-place skill-catalog rewrite, or any leading-message mutation invalidates it.");
+        previous = next;
+    }
+    return { requests: serialized.length, minContinuity: observed };
+}
+/** Fixture provider: turn 1 loads `skillNames[0]`, turn 2 loads `skillNames[1]`, everything else completes. */
+function fixtureProvider(requests, skillNames) {
+    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) {
+                yield { type: "tool_call", call: toolCallContent(`prefix-stability-${index}`, "load_skill", { name: skillName }) };
+                return;
+            }
+            yield providerDone();
+        },
+    };
+}
+/** Provider-visible payload only: messages plus the tool schema fields sent on the wire. */
+function serializeRequest(request) {
+    // 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.
+    const parts = [
+        ...(request.tools ?? []).map((tool) => JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters })),
+        ...request.messages.map((message) => JSON.stringify(message)),
+    ];
+    return parts.join("\n");
+}
+/** 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;