@arnilo/prism 0.7.0 → 0.9.0

package/dist/providers/transport.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject } from "../contracts.js";
+import type { JsonObject, ProviderFailureClass } from "../contracts.js";
 export declare const DEFAULT_MAX_EVENT_BYTES = 262144;
 export declare const DEFAULT_MAX_BUFFER_BYTES = 524288;
 export declare const DEFAULT_MAX_RESPONSE_BODY_BYTES = 65536;
@@ -15,6 +15,8 @@ export interface SseEvent {
     readonly comments?: readonly string[];
 }
 export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta" | "response_body_shape";
+/** Maps already-captured provider transport evidence to advisory outcome metadata. */
+export declare function classifyProviderFailure(error: unknown): ProviderFailureClass;
 export declare class ProviderTransportError extends Error {
     readonly code: ProviderTransportErrorCode;
     readonly limitBytes?: number;

package/dist/providers/transport.js

@@ -3,6 +3,22 @@ export const DEFAULT_MAX_EVENT_BYTES = 262_144;
 export const DEFAULT_MAX_BUFFER_BYTES = 524_288;
 export const DEFAULT_MAX_RESPONSE_BODY_BYTES = 65_536;
 export const DEFAULT_MAX_ARGUMENT_BYTES = 262_144;
+const QUOTA_BODY = /quota|usage[\s_-]*limit|insufficient[\s_-]*(?:quota|credit|balance)|billing[\s_-]*(?:limit|quota)/i;
+const TRANSIENT_NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT"]);
+/** Maps already-captured provider transport evidence to advisory outcome metadata. */
+export function classifyProviderFailure(error) {
+    const status = readHttpStatus(error);
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return QUOTA_BODY.test(errorMessage(error)) ? "quota" : "rate_limited";
+    if (status !== undefined)
+        return status >= 500 ? "transient" : status >= 400 ? "permanent" : "unknown";
+    const cause = readField(error, "cause");
+    if (isTransientNetworkCode(readField(error, "code")) || isTransientNetworkCode(readField(cause, "code")))
+        return "transient";
+    return "unknown";
+}
 export class ProviderTransportError extends Error {
     code;
     limitBytes;
@@ -22,8 +38,28 @@ export function httpStatusError(prefix, response, bodyText) {
     const hint = parseRetryAfterMs(response.headers.get("retry-after"));
     if (hint !== undefined)
         error.retryAfterMs = hint;
+    Object.defineProperty(error, "failureClass", { value: classifyProviderFailure(error), enumerable: true });
     return error;
 }
+function readHttpStatus(error) {
+    for (const key of ["code", "status", "statusCode"]) {
+        const value = readField(error, key);
+        const status = typeof value === "number" ? value : typeof value === "string" && /^\d{3}$/.test(value) ? Number(value) : undefined;
+        if (status !== undefined && status >= 100 && status <= 599)
+            return status;
+    }
+    return undefined;
+}
+function readField(error, key) {
+    return error && typeof error === "object" && key in error ? error[key] : undefined;
+}
+function isTransientNetworkCode(value) {
+    return typeof value === "string" && TRANSIENT_NETWORK_CODES.has(value.toUpperCase());
+}
+function errorMessage(error) {
+    const cause = readField(error, "cause");
+    return [readField(error, "message"), readField(cause, "message")].filter((value) => typeof value === "string").join(" ");
+}
 /** Parse a `Retry-After` header (delay-seconds or HTTP-date) into milliseconds. */
 export function parseRetryAfterMs(value, now = Date.now()) {
     if (!value)

package/dist/redaction.js

@@ -167,19 +167,22 @@ export function errorToErrorInfo(error, secrets = []) {
     const code = readErrorCode(error);
     const retry = readRetryAfterMs(error);
     const retryAfter = retry !== undefined ? { retryAfterMs: retry } : {};
+    const failureClass = readProviderFailureClass(error);
+    const failure = failureClass === undefined ? {} : { failureClass };
     if (error instanceof Error) {
         return {
             name: error.name,
             message: redactSecrets(error.message, secrets),
             code,
+            ...failure,
             ...retryAfter,
             cause: error.cause ? redactSecrets(String(error.cause), secrets) : undefined,
         };
     }
     if (error && typeof error === "object" && "message" in error) {
-        return { message: redactSecrets(String(error.message), secrets), code, ...retryAfter };
+        return { message: redactSecrets(String(error.message), secrets), code, ...failure, ...retryAfter };
     }
-    return { message: redactSecrets(String(error), secrets), code, ...retryAfter };
+    return { message: redactSecrets(String(error), secrets), code, ...failure, ...retryAfter };
 }
 function readErrorCode(error) {
     if (!error || typeof error !== "object" || !("code" in error))
@@ -193,4 +196,17 @@ function readRetryAfterMs(error) {
     const value = error.retryAfterMs;
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
+function readProviderFailureClass(error) {
+    if (!error || typeof error !== "object" || !("failureClass" in error))
+        return undefined;
+    const value = error.failureClass;
+    return value === "quota" ||
+        value === "auth" ||
+        value === "rate_limited" ||
+        value === "transient" ||
+        value === "permanent" ||
+        value === "unknown"
+        ? value
+        : undefined;
+}
 //# sourceMappingURL=redaction.js.map

package/dist/run-bundle.d.ts

@@ -0,0 +1,89 @@
+import type { Agent, AgentSessionConfig, GuardrailStage, RunOptions } from "./contracts.js";
+/** Report format revision. Any shape change bumps this so pinned digests cannot compare across formats. */
+export declare const RUN_BUNDLE_SCHEMA_VERSION = 1;
+/** Inspectable projection of the inputs a run actually resolves to. Frozen JSON, safe to persist and diff. */
+export interface RunBundleSnapshot {
+    readonly schemaVersion: number;
+    /** `sha256:<64 hex>` over the canonicalized, redacted snapshot (this field excluded). */
+    readonly digest: string;
+    /** `agentFingerprint()` of the same agent/revision: the durable-resume identity behind this snapshot. */
+    readonly fingerprint: string;
+    readonly agent: {
+        readonly id: string;
+        readonly definitionRevision: string | null;
+    };
+    readonly systemPrompt: {
+        readonly disabled: boolean;
+        /** Digest of `AgentConfig.instructions`; the body never leaves the process. */
+        readonly instructionsDigest: string | null;
+        readonly contributions: readonly {
+            readonly id: string;
+            readonly mode: string | null;
+            readonly source: string | null;
+            readonly digest: string;
+        }[];
+    };
+    readonly skills: readonly {
+        readonly name: string;
+        readonly instructionsDigest: string | null;
+        readonly toolNames: readonly string[];
+    }[];
+    /** Effective tool set: `run.toolNames` narrowing already applied, schemas reduced to digests. */
+    readonly tools: readonly {
+        readonly name: string;
+        readonly schemaDigest: string;
+        readonly exclusive: boolean;
+        readonly effect: string | null;
+    }[];
+    readonly activeSkills: readonly string[] | null;
+    readonly guardrails: readonly {
+        readonly name: string;
+        readonly stage: GuardrailStage;
+        readonly revision: string | null;
+    }[];
+    readonly loop: {
+        readonly strategy: string;
+        readonly revision: string | null;
+    };
+    readonly thinkingLevel: string | null;
+    readonly limits: Readonly<import("./contracts.js").ResolvedRunLimits>;
+    /** Host-shaped JSON as configured (`true`/`false`/options); `null` when unset. */
+    readonly attentionCompiler: unknown;
+    readonly model: {
+        readonly provider: string | null;
+        readonly model: string | null;
+    };
+    readonly requestPolicies: readonly string[];
+    /** Kinds only — never a connection string, path, or credential. */
+    readonly storage: {
+        readonly sessionStore: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+        readonly checkpoints: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+        readonly effectStore: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+        readonly memory: {
+            readonly kind: string;
+            readonly durable: boolean;
+        };
+    };
+}
+export interface RunBundleSnapshotInput {
+    readonly agent: Agent;
+    /** Session-level inputs (store, leaf, cache TTL) that change what the run reads and writes. */
+    readonly config?: AgentSessionConfig;
+    readonly run?: RunOptions;
+    /** Optional memory store instance; only its kind/durability label is read, never its contents. */
+    readonly memory?: unknown;
+}
+/**
+ * Snapshots the effective run bundle: synchronous, in-memory, zero network and zero store reads.
+ * The counterpart of `agentFingerprint` for humans — same inputs, named fields, one stable digest to pin.
+ */
+export declare function snapshotRunBundle(input: RunBundleSnapshotInput): RunBundleSnapshot;

package/dist/run-bundle.js

@@ -0,0 +1,150 @@
+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";
+import { selectRunTools } from "./tools.js";
+/** Report format revision. Any shape change bumps this so pinned digests cannot compare across formats. */
+export const RUN_BUNDLE_SCHEMA_VERSION = 1;
+/** Bounded by construction; a bundle larger than this is a host bug, not a snapshot to retain. */
+const MAX_RUN_BUNDLE_BYTES = 512 * 1024;
+/**
+ * Snapshots the effective run bundle: synchronous, in-memory, zero network and zero store reads.
+ * The counterpart of `agentFingerprint` for humans — same inputs, named fields, one stable digest to pin.
+ */
+export function snapshotRunBundle(input) {
+    const config = input.agent.config;
+    const run = input.run;
+    const redactor = run?.redactor ?? config.redactor;
+    const definitionRevision = run?.runState?.definitionRevision ?? config.runState?.definitionRevision ?? null;
+    const tools = selectRunTools(listTools(config.tools), run?.toolNames).tools;
+    const skills = listSkills(config.skills, run?.skills);
+    const model = run?.model ?? config.model;
+    const effectiveLoop = run?.loop ?? config.loop;
+    const systemPrompt = run?.systemPrompt ?? config.systemPrompt;
+    const policies = run?.providerRequestPolicies ?? config.providerRequestPolicies;
+    const snapshot = {
+        schemaVersion: RUN_BUNDLE_SCHEMA_VERSION,
+        fingerprint: agentFingerprint(input.agent, definitionRevision ?? ""),
+        agent: { id: agentId(input.agent), definitionRevision },
+        systemPrompt: {
+            disabled: systemPrompt === false,
+            instructionsDigest: hashText(config.instructions),
+            contributions: systemPrompt === false || systemPrompt === undefined
+                ? []
+                : (Array.isArray(systemPrompt) ? systemPrompt : [systemPrompt]).map((contribution) => ({
+                    id: contribution.id,
+                    mode: contribution.mode ?? null,
+                    source: contribution.source ?? null,
+                    digest: hashText(contribution.text) ?? "",
+                })),
+        },
+        skills: skills.map((skill) => ({
+            name: skill.name,
+            instructionsDigest: hashText(skill.instructions),
+            toolNames: skill.toolNames ?? [],
+        })),
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            schemaDigest: hashJson(canonicalizeJsonSchema(tool.parameters ?? { type: "object" })),
+            exclusive: tool.exclusive === true,
+            effect: tool.effect === undefined ? null : typeof tool.effect === "function" ? "classifier" : tool.effect.kind,
+        })),
+        activeSkills: run?.activeSkills ?? null,
+        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),
+        attentionCompiler: run?.attentionCompiler ?? config.attentionCompiler ?? null,
+        model: {
+            provider: typeof model === "string" ? (config.provider?.id ?? null) : (model?.provider ?? null),
+            model: typeof model === "string" ? model : (model?.model ?? null),
+        },
+        requestPolicies: policies === undefined ? [] : (Array.isArray(policies) ? policies : [policies]).map((policy) => policy.name),
+        storage: {
+            sessionStore: kindOf(describeStorage(input.config?.store ?? config.store, undefined)),
+            checkpoints: kindOf(describeStorage(undefined, (run?.runState ?? config.runState)?.checkpoints)),
+            effectStore: kindOf(describeStorage(run?.effectStore ?? config.effectStore, undefined)),
+            memory: kindOf(describeStorage(input.memory, undefined)),
+        },
+    };
+    const redacted = redactStrings(snapshot, redactor);
+    const bundle = deepFreeze({ ...redacted, digest: hashJson(canonicalizeJsonSchema(redacted)) });
+    const bytes = Buffer.byteLength(JSON.stringify(bundle), "utf8");
+    if (bytes > MAX_RUN_BUNDLE_BYTES) {
+        throw new TypeError(`Run bundle snapshot exceeds ${MAX_RUN_BUNDLE_BYTES} bytes`);
+    }
+    return bundle;
+}
+/** Keeps a store label a label: a declared `kind` that is really a connection string or path becomes `custom`. */
+function kindOf(described) {
+    const raw = described.kind.toLowerCase();
+    return { kind: /^[a-z0-9_.-]{1,64}$/.test(raw) ? raw : "custom", durable: described.durable };
+}
+function agentId(agent) {
+    return agent.config.id ?? agent.config.name ?? "agent";
+}
+function listTools(tools) {
+    if (!tools)
+        return [];
+    return "list" in tools ? tools.list() : tools;
+}
+function listSkills(skills, runSkills) {
+    const listed = !skills ? [] : "list" in skills ? skills.list() : skills;
+    const byName = new Map(listed.map((skill) => [skill.name, skill]));
+    for (const skill of runSkills ?? [])
+        byName.set(skill.name, skill);
+    return [...byName.values()];
+}
+function guardrailRows(configGuardrails, runGuardrails) {
+    const rows = [];
+    for (const guardrails of [configGuardrails, runGuardrails]) {
+        if (!guardrails)
+            continue;
+        for (const stage of ["input", "output", "tool_input", "tool_output"]) {
+            const key = stage === "tool_input" ? "toolInput" : stage === "tool_output" ? "toolOutput" : stage;
+            for (const guardrail of guardrails[key] ?? []) {
+                rows.push({ name: guardrail.name, stage, revision: guardrail.revision ?? null });
+            }
+        }
+    }
+    return rows;
+}
+function loopIdentity(loop) {
+    if (typeof loop === "object" && loop && "strategy" in loop) {
+        return { strategy: loop.strategy, revision: BUILT_IN_LOOP_REVISIONS[loop.strategy] ?? null };
+    }
+    return {
+        strategy: loop?.name ?? "single-shot",
+        revision: loop?.revision ?? BUILT_IN_LOOP_REVISIONS["single-shot"] ?? null,
+    };
+}
+/** `sha256:<64 hex>` over UTF-8 text — the same convention as `hashPromptBody` in `@arnilo/prism-core`. */
+function hashText(text) {
+    if (text === undefined)
+        return null;
+    return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+function hashJson(value) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex")}`;
+}
+/** Redacts every string field so a pinned snapshot can never carry a secret. */
+function redactStrings(value, redactor) {
+    if (typeof value === "string")
+        return redactor ? redactor.redact(value) : value;
+    if (!value || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => redactStrings(item, redactor));
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactStrings(item, redactor)]));
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreeze(item);
+    }
+    return value;
+}
+//# sourceMappingURL=run-bundle.js.map

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>;