@theoremjs/agents 0.3.4-next.508.geda6db0 → 0.3.4-next.524.g5000023

package/esm/src/guardrails/detect-at.d.ts

@@ -13,6 +13,10 @@ interface Detection {
     text?: string;
     /** Every match, each named for its detector. */
     hits: GuardrailHit[];
+    /** Why a host's `find` failed, for the builder only: it reaches `guardrail.errorInternal`. */
+    errorInternal?: string;
+    /** The same failure in the kernel's words only, with no text from the host: what the trace stores. */
+    errorSummary?: string;
 }
 declare function stronger(left: DetectOutcome, right: DetectOutcome | 'ignore'): DetectOutcome;
 /**
@@ -92,7 +96,7 @@ declare function storedHostSpans(text: string, detect?: ResolvedDetect): RedactS
 interface BoundaryReader {
     /** The text to let through, or `''` once a match blocks: the caller reads `found().action`. */
     read(text: string): string;
-    found(): Pick<Detection, 'action' | 'hits'>;
+    found(): Pick<Detection, 'action' | 'hits' | 'errorInternal' | 'errorSummary'>;
 }
 /** A reader for everything crossing `boundary` in one request. */
 declare function boundaryReader(boundary: Boundary, detect: ResolvedDetect): BoundaryReader;
@@ -100,6 +104,6 @@ declare function boundaryReader(boundary: Boundary, detect: ResolvedDetect): Bou
  * The guardrail event for what was found at a boundary, or `undefined` when nothing matched.
  * `stage` is the boundary's own unless the text was read as it streamed.
  */
-declare function detectEvent(boundary: Boundary, found: Pick<Detection, 'action' | 'hits'>, provenance?: Provenance, stage?: GuardrailStage): GuardrailEvent | undefined;
+declare function detectEvent(boundary: Boundary, found: Pick<Detection, 'action' | 'hits' | 'errorInternal' | 'errorSummary'>, provenance?: Provenance, stage?: GuardrailStage): GuardrailEvent | undefined;
 export type { BoundaryReader, Detection, DetectOutcome, DetectScope, Release, StoredSides, StreamRead, Stretch, };
 export { boundaryReader, detectAt, detectEvent, detectorsAt, detectReads, detectRelease, hostAt, isScoped, leakScopeOf, redactDetectors, scopeOf, storedHostSpans, storedSpans, stronger, };

package/esm/src/guardrails/detect-at.js

@@ -7,6 +7,7 @@ import { actionAt, DETECTORS, detects, } from './detectors.js';
 import { boundaryNote } from './egress.js';
 import { notePattern, SYSTEM_BOUNDARY } from './egress-patterns.js';
 import { imageLeakSpans, linkLeakSpans } from './egress-urls.js';
+import { describeError } from './error.js';
 import { CANARY_HIT, hitFromSpan, promptEchoHit } from './hits.js';
 import { injectionSpans } from './injection.js';
 import { promptEchoRanges } from './prompt-echo.js';
@@ -15,6 +16,14 @@ import { sensitiveSpans } from './sensitive.js';
 import { SENSITIVE_GROUPS } from './sensitive-groups.js';
 import { directives, mergedRanges } from './tool-directives.js';
 import { ownToolsWithout, toolLeakSpans } from './tool-leak.js';
+function failureText(failures) {
+    if (failures.length === 0)
+        return {};
+    return {
+        errorInternal: failures.map(({ errorInternal }) => errorInternal).join('\n'),
+        errorSummary: failures.map(({ errorSummary }) => errorSummary).join('\n'),
+    };
+}
 const STRENGTH = ['allow', 'flag', 'redact', 'block'];
 function stronger(left, right) {
     if (right === 'ignore')
@@ -138,22 +147,35 @@ function hitOf(detector, text, span) {
 function leavesImages(detector, boundary, detect) {
     return detector === 'ungiven_links' && detect.ungiven_images[boundary] !== 'ignore';
 }
+/** A thrown value's type: a name of letters only, else `Error`, so no host text gets through. */
+function thrownType(err) {
+    const name = err instanceof Error ? err.name : typeof err;
+    return /^[A-Za-z]{1,64}$/.test(name) ? name : 'Error';
+}
 /** What a host's `find` matched in `text`, or how it failed. */
 function foundBy(find, text, boundary) {
     try {
         const spans = find(text, boundary ? { boundary } : {});
+        // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const said = 'find returned no list of stretches inside the text';
+        const outside = { signal: 'find_result', reason: said, summary: said };
         if (!Array.isArray(spans))
-            return 'find_result';
+            return outside;
         const inside = spans.every(({ start, end }) => Number.isInteger(start) &&
             Number.isInteger(end) &&
             start >= 0 &&
             start < end &&
             end <= text.length);
-        return inside ? spans.map(({ start, end }) => ({ start, end, kind: 'host' })) : 'find_result';
+        return inside ? spans.map(({ start, end }) => ({ start, end, kind: 'host' })) : outside;
     }
-    catch {
+    catch (err) {
         // why: A reading that failed found nothing it can vouch for, so the text does not cross.
-        return 'find_threw';
+        const id = crypto.randomUUID().slice(0, 8);
+        return {
+            signal: 'find_threw',
+            reason: `find threw: ${describeError(err)} (error ${id})`,
+            summary: `find threw ${thrownType(err)} (error ${id})`,
+        };
     }
 }
 function hostReader(host, boundary, chosen) {
@@ -168,7 +190,11 @@ function hostReader(host, boundary, chosen) {
             if (!host.find)
                 return matched;
             const found = foundBy(host.find, text, boundary);
-            return typeof found === 'string' ? found : [...matched, ...found];
+            if (!Array.isArray(found)) {
+                const by = `Host detector '${host.id}'`;
+                return { ...found, reason: `${by} ${found.reason}`, summary: `${by} ${found.summary}` };
+            }
+            return [...matched, ...found];
         },
         hit: (text, span) => ({ ...hitFromSpan(text, span, rule, 'high'), label: host.label }),
     };
@@ -211,11 +237,13 @@ function failedHit({ rule, label }, signal) {
 function detectAt(text, boundary, detect, scope = NO_SCOPE) {
     const hits = [];
     const redact = [];
+    const failures = [];
     let action = 'allow';
     for (const reader of readersAt(boundary, detect, scope)) {
         const spans = reader.spans(text);
-        if (typeof spans === 'string') {
-            hits.push(failedHit(reader, spans));
+        if (!Array.isArray(spans)) {
+            hits.push(failedHit(reader, spans.signal));
+            failures.push({ errorInternal: spans.reason, errorSummary: spans.summary });
             action = 'block';
             continue;
         }
@@ -228,8 +256,9 @@ function detectAt(text, boundary, detect, scope = NO_SCOPE) {
                 redact.push(span);
         action = stronger(action, reader.chosen);
     }
-    if (action === 'block')
-        return { action, hits };
+    if (action === 'block') {
+        return { action, hits, ...failureText(failures) };
+    }
     if (redact.length === 0)
         return { action, text, hits };
     const replaced = applySpans(text, redact);
@@ -247,7 +276,7 @@ function leftAfterRedact(replaced, boundary, detect, scope, detectors) {
         if (chosen === 'flag')
             return false;
         const left = spans(replaced);
-        return !left || left.length > 0;
+        return !Array.isArray(left) || left.length > 0;
     });
 }
 /** The detectors that read `boundary`: every one not set to `ignore`. */
@@ -281,16 +310,21 @@ function detectReads(boundaries, detect, scope) {
  */
 function detectRelease(window, { from, to, settled }, boundary, detect, { detectors, scope }) {
     const failed = [];
+    const failures = [];
     const found = readersAt(boundary, detect, scope, detectors).flatMap((reader) => {
         const spans = reader.spans(window);
-        if (typeof spans === 'string')
-            failed.push(failedHit(reader, spans));
-        return (typeof spans === 'string' ? [] : spans)
+        if (!Array.isArray(spans)) {
+            failed.push(failedHit(reader, spans.signal));
+            failures.push({ errorInternal: spans.reason, errorSummary: spans.summary });
+            return [];
+        }
+        return spans
             .filter((span) => span.end > from && span.start < to)
             .map((span) => ({ span, rule: reader.rule, label: reader.label, chosen: reader.chosen }));
     });
-    if (failed.length > 0)
-        return { action: 'block', hits: failed, taken: 0 };
+    if (failed.length > 0) {
+        return { action: 'block', hits: failed, taken: 0, ...failureText(failures) };
+    }
     const hitOf = ({ span, rule, label }) => ({
         ...hitFromSpan(window, span, rule, 'high'),
         ...(label === undefined ? {} : { label }),
@@ -353,24 +387,31 @@ function storedHostSpans(text, detect) {
         if (!host.find || !text)
             return matched;
         const found = foundBy(host.find, text);
-        return typeof found === 'string'
-            ? [{ start: 0, end: text.length, kind: 'host' }]
-            : [...matched, ...found];
+        return Array.isArray(found)
+            ? [...matched, ...found]
+            : [{ start: 0, end: text.length, kind: 'host' }];
     });
 }
 /** A reader for everything crossing `boundary` in one request. */
 function boundaryReader(boundary, detect) {
     const hits = [];
+    const failures = [];
     let action = 'allow';
     return {
         read(text) {
             const detected = detectAt(text, boundary, detect);
             for (const hit of detected.hits)
                 hits.push(hit);
+            if (detected.errorInternal && detected.errorSummary) {
+                failures.push({
+                    errorInternal: detected.errorInternal,
+                    errorSummary: detected.errorSummary,
+                });
+            }
             action = stronger(action, detected.action);
             return detected.text ?? '';
         },
-        found: () => ({ action, hits }),
+        found: () => ({ action, hits, ...failureText(failures) }),
     };
 }
 const TOOL_STAGE = Object.fromEntries(TOOL_BOUNDARIES.map((boundary) => [
@@ -413,6 +454,10 @@ function detectEvent(boundary, found, provenance, stage = BOUNDARY_STAGE[boundar
         action: found.action,
         hits: found.hits,
         ...(provenance ? { provenance } : {}),
+        ...(found.action === 'block' && found.errorInternal
+            ? { errorInternal: found.errorInternal }
+            : {}),
+        ...(found.action === 'block' && found.errorSummary ? { errorSummary: found.errorSummary } : {}),
     };
 }
 export { boundaryReader, detectAt, detectEvent, detectorsAt, detectReads, detectRelease, hostAt, isScoped, leakScopeOf, redactDetectors, scopeOf, storedHostSpans, storedSpans, stronger, };

package/esm/src/guardrails/detect-reply.d.ts

@@ -26,7 +26,7 @@ interface ReplyRead {
     blocked?: GuardrailHit[];
 }
 /** A JSON value read at `boundary`, with each match in a string replaced, or what stops it crossing. */
-declare function readValue(value: unknown, boundary: Boundary, detect: ResolvedDetect, scope?: DetectScope): Pick<Detection, 'action' | 'hits'> & {
+declare function readValue(value: unknown, boundary: Boundary, detect: ResolvedDetect, scope?: DetectScope): Pick<Detection, 'action' | 'hits' | 'errorInternal' | 'errorSummary'> & {
     value?: unknown;
 };
 /**

package/esm/src/guardrails/detect-reply.js

@@ -23,8 +23,11 @@ function readValue(value, boundary, detect, scope = {}) {
         return { action: 'block', hits: [{ rule: EGRESS_RULES.unscannable, severity: 'high' }] };
     }
     const found = detectAt(scan.text, boundary, detect, scope);
-    if (found.action !== 'redact')
-        return { action: found.action, hits: found.hits, value };
+    if (found.action !== 'redact') {
+        const { errorInternal, errorSummary } = found;
+        const why = errorInternal && errorSummary ? { errorInternal, errorSummary } : {};
+        return { action: found.action, hits: found.hits, value, ...why };
+    }
     const redacted = mapStrings(value, (leaf) => detectAt(leaf, boundary, detect, scope).text ?? '');
     const left = detectAt(textForScan(redacted).text, boundary, detect, scope).action;
     // why: A match in a key, or one that runs across values, has no string to replace: it does not cross.

package/esm/src/guardrails/egress-compiler.js

@@ -25,7 +25,7 @@ import { JS, NFA } from 'refa';
 import { analyse } from 'scslre';
 import { EGRESS_PATTERNS } from './egress-patterns.js';
 import { TheoremError } from './error.js';
-import { MAX_PATTERNS, PATTERN_COMPILER_VERSION, patternProblem, patternSources, } from './host-patterns.js';
+import { PATTERN_COMPILER_VERSION, patternProblem, patternSources, } from './host-patterns.js';
 const MAX_CHAR = 0xffff;
 /**
  * A bounded repeat longer than this is read as unbounded: the hold cannot
@@ -355,9 +355,6 @@ function slowPatternProblem(source, flags = '') {
  * backreference to text that varies).
  */
 function compilePatterns(patterns) {
-    if (patterns.length > MAX_PATTERNS) {
-        throw patternError(`${patterns.length} patterns; a detector takes at most ${MAX_PATTERNS}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    }
     patterns.forEach((pattern, index) => {
         const problem = patternProblem(`patterns[${index}]`, pattern);
         if (problem !== undefined)

package/esm/src/guardrails/error.d.ts

@@ -16,7 +16,7 @@ declare function kindOfHttpStatus(status: number): ErrorKind;
 declare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): string;
 /** Pass the profile's `labels`, or the profile's wording is skipped. */
 declare function publicError(err: unknown, labels?: LabelOverrides): string;
-/** Raw diagnostic for hosts, traces, and logs; never shown to end users. */
+/** Raw diagnostic for hosts, traces, and logs; never shown to end users. Each cause that says something new follows on its own line. */
 declare function describeError(err: unknown): string;
 type ProducedError = TurnEventOf<'error'> & {
     errorInternal: string;

package/esm/src/guardrails/error.js

@@ -61,8 +61,7 @@ function errorCopyText(copy, labels) {
 function publicError(err, labels) {
     return wording(errorKind(err), err instanceof TheoremError ? err.copy : undefined, labels);
 }
-/** Raw diagnostic for hosts, traces, and logs; never shown to end users. */
-function describeError(err) {
+function messageOf(err) {
     if (typeof err === 'string') {
         return err;
     }
@@ -71,6 +70,24 @@ function describeError(err) {
     }
     return String(err);
 }
+/** Raw diagnostic for hosts, traces, and logs; never shown to end users. Each cause that says something new follows on its own line. */
+function describeError(err) {
+    const lines = [messageOf(err)];
+    const seen = new Set([err]);
+    let said = messageOf(err);
+    let cause = err instanceof Error ? err.cause : undefined;
+    while (cause !== undefined && cause !== null && !seen.has(cause)) {
+        seen.add(cause);
+        const message = messageOf(cause);
+        if (message !== said) {
+            const name = cause instanceof Error && cause.name !== 'Error' ? `${cause.name}: ` : '';
+            lines.push(`caused by: ${name}${message}`);
+            said = message;
+        }
+        cause = cause instanceof Error ? cause.cause : undefined;
+    }
+    return lines.join('\n');
+}
 /** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */
 function toErrorEvent(err) {
     return {

package/esm/src/guardrails/event-schemas.d.ts

@@ -95,6 +95,11 @@ export interface GuardrailEvent {
     provenance?: Provenance;
     /** The block verdict's `errorInternal`: builder-only, stripped by `forClient`. */
     errorInternal?: string;
+    /**
+     * A failed host detector's `errorInternal` in the kernel's words only, with the same error id:
+     * what the trace stores. Builder-only, stripped by `forClient`.
+     */
+    errorSummary?: string;
 }
 /** The schema a guardrail event parses against. */
 export declare const guardrailEventSchema: z.ZodType<GuardrailEvent>;

package/esm/src/guardrails/event-schemas.js

@@ -42,6 +42,7 @@ const guardrailEvent = z.object({
     hits: z.array(guardrailHit),
     provenance: provenance.optional(),
     errorInternal: z.string().optional(),
+    errorSummary: z.string().optional(),
 });
 true;
 /** The schema a guardrail event parses against. */

package/esm/src/guardrails/host-patterns.d.ts

@@ -59,9 +59,6 @@ interface HostMatcher {
 }
 /** Bumped whenever the compiled table's layout or meaning changes. */
 declare const PATTERN_COMPILER_VERSION = 3;
-/** The most patterns one detector takes, and the longest each may be once written as a regular expression. */
-declare const MAX_PATTERNS = 64;
-declare const MAX_PATTERN_LENGTH = 1024;
 /** The patterns as a compiled table records them. */
 declare function patternSources(patterns: readonly HostPattern[]): PatternSource[];
 /** What is wrong with one pattern, or `undefined` when it runs. */
@@ -82,4 +79,4 @@ declare function listsPatterns(detect: unknown): boolean;
 /** `patterns`, valid, ready to run. */
 declare function matchersOf(patterns: readonly HostPattern[]): readonly HostMatcher[];
 export type { AutomatonData, CompiledPatterns, HostMatcher, HostPattern, PatternSource };
-export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, matchersOf, PATTERN_COMPILER_VERSION, patternListProblem, patternProblem, patternSources, patternsProblem, };
+export { listsPatterns, matchersOf, PATTERN_COMPILER_VERSION, patternListProblem, patternProblem, patternSources, patternsProblem, };

package/esm/src/guardrails/host-patterns.js

@@ -2,9 +2,6 @@
 // `detectors.ts` can read a host's patterns without a cycle.
 /** Bumped whenever the compiled table's layout or meaning changes. */
 const PATTERN_COMPILER_VERSION = 3;
-/** The most patterns one detector takes, and the longest each may be once written as a regular expression. */
-const MAX_PATTERNS = 64;
-const MAX_PATTERN_LENGTH = 1024;
 const PATTERN_FLAGS = 'imsu';
 /** A letter, digit, or underscore in any script: what a word may not touch on either side. */
 const WORD_UNIT = '[\\p{L}\\p{N}_]';
@@ -79,9 +76,6 @@ function patternProblem(path, pattern) {
     if (shape !== undefined)
         return shape;
     const { source, flags } = patternSource(pattern);
-    if (source.length > MAX_PATTERN_LENGTH) {
-        return `${path} is ${source.length} characters as a regular expression; the most is ${MAX_PATTERN_LENGTH}`;
-    }
     let regex;
     try {
         // why: this only checks that the pattern parses and tests it on the empty text; a pattern that
@@ -134,9 +128,6 @@ function patternsProblem(path, patterns, compiled) {
 function patternListProblem(path, patterns) {
     if (!Array.isArray(patterns))
         return `${path}.patterns must be a list`;
-    if (patterns.length > MAX_PATTERNS) {
-        return `${path}.patterns lists ${patterns.length} patterns; the most is ${MAX_PATTERNS}`;
-    }
     const names = new Set();
     for (const [index, pattern] of patterns.entries()) {
         const at = `${path}.patterns[${index}]`;
@@ -170,4 +161,4 @@ function matchersOf(patterns) {
     }
     return matchers;
 }
-export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, matchersOf, PATTERN_COMPILER_VERSION, patternListProblem, patternProblem, patternSources, patternsProblem, };
+export { listsPatterns, matchersOf, PATTERN_COMPILER_VERSION, patternListProblem, patternProblem, patternSources, patternsProblem, };

package/esm/src/guardrails/mod.d.ts

@@ -25,7 +25,7 @@ export { errorCopiesSchema, errorKindSchema, guardrailEventSchema } from './even
 export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent, } from './events.js';
 export { hitFromSpan, projectGuardrailEvent, } from './hits.js';
 export type { CompiledPatterns, HostPattern } from './host-patterns.js';
-export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, patternListProblem, } from './host-patterns.js';
+export { listsPatterns, patternListProblem, } from './host-patterns.js';
 export { injectionSpans } from './injection.js';
 export type { ClientLabelKey, LabelKey, LabelOverrides, LabelParams } from './labels.js';
 export { CLIENT_LABEL_KEYS, LABEL_KEYS, labelCatalogRows, labelDefault, labelText, overrideLabels, resetLabels, validateLabelOverrides, } from './labels.js';

package/esm/src/guardrails/mod.js

@@ -16,7 +16,7 @@ export { describeError, ERROR_KINDS, errorKind, isAbortError, isTimeoutError, ki
 export { errorCopiesSchema, errorKindSchema, guardrailEventSchema } from './event-schemas.js';
 export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent, } from './events.js';
 export { hitFromSpan, projectGuardrailEvent, } from './hits.js';
-export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, patternListProblem, } from './host-patterns.js';
+export { listsPatterns, patternListProblem, } from './host-patterns.js';
 export { injectionSpans } from './injection.js';
 export { CLIENT_LABEL_KEYS, LABEL_KEYS, labelCatalogRows, labelDefault, labelText, overrideLabels, resetLabels, validateLabelOverrides, } from './labels.js';
 export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from './live-outbound-gate.js';

package/esm/src/guardrails/sanitize.d.ts

@@ -19,7 +19,7 @@ declare function sanitizeProjectId(id: string | undefined): string | undefined;
  */
 declare function sanitizeHistory(history: TurnHistoryMessage[], reader: BoundaryReader): TurnHistoryMessage[];
 /** The error a turn ends on when a detector set to `block` matched at `boundary`. */
-declare function requestRefused(boundary: Boundary): TheoremError;
+declare function requestRefused(boundary: Boundary, reason?: string): TheoremError;
 /** A turn request read at each boundary it crosses. */
 interface SanitizedTurnRequest {
     request: NormalizedTurnRequest;

package/esm/src/guardrails/sanitize.js

@@ -91,9 +91,10 @@ function sanitizeHistory(history, reader) {
     });
 }
 /** The error a turn ends on when a detector set to `block` matched at `boundary`. */
-function requestRefused(boundary) {
+function requestRefused(boundary, reason) {
+    const why = reason ? `: ${reason}` : '';
     // labels-exempt: developer contract / internal diagnostic — the user's wording is `detect.blocked`
-    return new TheoremError('input', `guardrails.detect blocked the request at ${boundary}`, {
+    return new TheoremError('input', `guardrails.detect blocked the request at ${boundary}${why}`, {
         copy: { key: 'detect.blocked' },
     });
 }
@@ -125,7 +126,7 @@ function sanitizeTurnRequestWithEvents(req, profile) {
         if (event)
             events.push(guardrailTurnEvent(event));
         if (found.action === 'block')
-            refusal ??= requestRefused(boundary);
+            refusal ??= requestRefused(boundary, found.errorInternal);
     }
     events.push(...told.events.map(guardrailTurnEvent));
     if (told.blocked)

package/esm/src/host/client-turn.js

@@ -33,11 +33,19 @@ function stripErrorInternal(event) {
     const { errorInternal: _internal, ...rest } = event;
     return rest;
 }
+function stripCompactionInternal(event) {
+    if (event.type !== 'compaction' || event.failure?.errorInternal === undefined) {
+        return event;
+    }
+    const { errorInternal: _internal, ...failure } = event.failure;
+    return { ...event, failure };
+}
 function stripGuardrailInternal(event) {
-    if (event.type !== 'guardrail' || !event.guardrail?.errorInternal) {
+    if (event.type !== 'guardrail' ||
+        !(event.guardrail?.errorInternal || event.guardrail?.errorSummary)) {
         return event;
     }
-    const { errorInternal: _internal, ...guardrail } = event.guardrail;
+    const { errorInternal: _internal, errorSummary: _summary, ...guardrail } = event.guardrail;
     return { ...event, guardrail };
 }
 function stripEvidenceRaw(event) {
@@ -54,7 +62,7 @@ function stripEvidenceRaw(event) {
 function forClient(event, options) {
     let out = options?.reader === 'builder'
         ? builderWording(event)
-        : stripGuardrailInternal(stripErrorInternal(event));
+        : stripCompactionInternal(stripGuardrailInternal(stripErrorInternal(event)));
     if (!options?.includeEvidenceRaw) {
         out = stripEvidenceRaw(out);
     }

package/esm/src/kernel/engine/runner/gates.js

@@ -153,7 +153,8 @@ function updateFlowForRetry(flow, state, profile, nextReq, reason) {
     flow.currentReq = nextReq;
     const safe = sanitizeTurnRequest(nextReq, profile);
     if (profile.type === 'text') {
-        // why: The conversation is already in turn history: the repair is its next user message.
+        // why: The repair is the turn's next user message, and the retry reads this turn alone.
+        state.turnOnly = true;
         const before = state.currentHistory.length;
         appendUserInput(state, resolveInputParts(profile, { ...safe, input: { repair: safe.input?.repair } }));
         for (const message of state.currentHistory.slice(before))

package/esm/src/kernel/engine/runner/mod.js

@@ -1,5 +1,5 @@
 import { canaryNote, contextNote, profileCanary, userDataNote, } from '../../../guardrails/canary.js';
-import { isAbortError, TheoremError, throwIfAborted, withPublicLabels, } from '../../../guardrails/error.js';
+import { describeError, errorKind, isAbortError, TheoremError, throwIfAborted, withPublicLabels, } from '../../../guardrails/error.js';
 import { projectGuardrailTurnEvent } from '../../../guardrails/events.js';
 import { labelText } from '../../../guardrails/labels.js';
 import { sanitizeTurnRequestWithEvents } from '../../../guardrails/sanitize.js';
@@ -22,7 +22,7 @@ import { sumEventTokens, sumTurnTokens } from '../usage.js';
 import { runAttemptsWithValidation } from './gates.js';
 import { createAgentCaller, NESTED_THROWS, turnError } from './nested.js';
 import { applyTurnStage } from './stages.js';
-import { openTurnState } from './state.js';
+import { cutConversation, openTurnState, } from './state.js';
 import { shouldSkipStreamEvent } from './stream.js';
 function projectForObs(event, policy) {
     return projectGuardrailTurnEvent(event, policy?.include.guardrailMatchPreview ?? false);
@@ -105,10 +105,10 @@ async function runCompactor(args) {
     }
     catch (err) {
         throwIfAborted(args.signal);
-        const error = err instanceof TheoremError ? err.kind : 'internal';
+        const error = errorKind(err);
         if (NESTED_THROWS.has(error))
             throw err;
-        return { droppedMedia, failure: { error } };
+        return { droppedMedia, failure: { error, errorInternal: describeError(err) } };
     }
     throwIfAborted(args.signal);
     const tokens = sumEventTokens(events);
@@ -122,7 +122,11 @@ async function runCompactor(args) {
     if (stop !== 'completed' || error) {
         return {
             droppedMedia,
-            failure: { ...(stop ? { stop } : {}), ...(error ? { error } : {}) },
+            failure: {
+                ...(stop ? { stop } : {}),
+                ...(error ? { error } : {}),
+                ...(reported?.errorInternal ? { errorInternal: reported.errorInternal } : {}),
+            },
             ...usage,
         };
     }
@@ -163,6 +167,9 @@ function compactionOutcome(result, messagesBefore) {
         dropped_media: result.droppedMedia,
         ...(result.failure?.stop ? { failure_stop: result.failure.stop } : {}),
         ...(result.failure?.error ? { failure_error: result.failure.error } : {}),
+        ...(result.failure?.errorInternal
+            ? { failure_reason: traceContent(result.failure.errorInternal) }
+            : {}),
         ...(result.failure?.empty ? { failure_empty: true } : {}),
         ...(result.failure?.unreadable ? { failure_unreadable: true } : {}),
         ...(result.summary === undefined ? {} : { summary: traceContent(result.summary) }),
@@ -274,6 +281,7 @@ async function* emitTurn(args) {
     const done = turnDoneOf({
         stop: state.lastStop ?? { kind: 'completed' },
         ...(state.providerState &&
+            !cutConversation(state) &&
             !('providerContinuation' in profile && profile.providerContinuation?.history === 'stateless') &&
             (!state.lastStop || ['completed', 'tool', 'gate'].includes(state.lastStop.kind))
             ? { providerState: state.providerState }

package/esm/src/kernel/engine/runner/state.d.ts

@@ -23,6 +23,10 @@ interface StepExecutionState {
     agents?: AgentCaller;
     trace: TurnTraceState;
     currentHistory: TurnHistoryMessage[];
+    /** Where this turn begins in `currentHistory`: what came before is the conversation the host passed. */
+    turnStart: number;
+    /** Set by a retry: from then on the model reads this turn only, from `turnStart`. */
+    turnOnly?: boolean;
     stepCount: number;
     /** Model calls sent again this turn under the profile's resumption (`executeResumedStep`). */
     resumes: number;
@@ -106,5 +110,9 @@ declare function openTurnState(args: {
     allEmittedEvents?: TurnEvent[];
     agents?: AgentCaller;
 }): StepExecutionState;
+/** The history the next model call reads: this turn alone once a retry has cut it. */
+declare function modelHistory(state: StepExecutionState): TurnHistoryMessage[];
+/** Whether the turn's checkpoint covers less than the conversation the host keeps. */
+declare function cutConversation(state: StepExecutionState): boolean;
 export type { AttemptFlowState, PendingItemFix, StepExecutionState, TurnTraceState };
-export { appendUserInput, openTurnState, recordStepEvent };
+export { appendUserInput, cutConversation, modelHistory, openTurnState, recordStepEvent };

package/esm/src/kernel/engine/runner/state.js

@@ -28,6 +28,7 @@ function openTurnState(args) {
         tools: args.tools,
         trace: args.trace,
         currentHistory: [...(generation.history ?? [])],
+        turnStart: generation.history?.length ?? 0,
         stepCount: 0,
         resumes: 0,
         toolResults: [],
@@ -49,4 +50,12 @@ function openTurnState(args) {
     }
     return state;
 }
-export { appendUserInput, openTurnState, recordStepEvent };
+/** The history the next model call reads: this turn alone once a retry has cut it. */
+function modelHistory(state) {
+    return state.turnOnly ? state.currentHistory.slice(state.turnStart) : state.currentHistory;
+}
+/** Whether the turn's checkpoint covers less than the conversation the host keeps. */
+function cutConversation(state) {
+    return state.turnOnly === true && state.turnStart > 0;
+}
+export { appendUserInput, cutConversation, modelHistory, openTurnState, recordStepEvent };

package/esm/src/kernel/engine/runner/steps.js

@@ -21,7 +21,7 @@ import { findLast } from '../../util/find-last.js';
 import { startToolTrace } from '../tool-trace.js';
 import { startCallTrace } from '../turn-trace.js';
 import { applyStageInjects, recordReply } from './stages.js';
-import { recordStepEvent } from './state.js';
+import { modelHistory, recordStepEvent } from './state.js';
 import { inStep, runSideBySide, stepOrder } from './step-order.js';
 import { isWithheldOnBlock, StructuredDrafts, yieldProviderEvents, } from './stream.js';
 import { callTokensEvent, observeCallEvent, startCallUsage } from './usage.js';
@@ -30,7 +30,7 @@ function isStepLimitReached(step, maxSteps) {
 }
 /** The step's generation: the turn's history so far, and no tools when the step must answer. */
 function generationForProviderStep(generation, state, answerOnly) {
-    const forStep = { ...generation, history: state.currentHistory };
+    const forStep = { ...generation, history: modelHistory(state) };
     if (!answerOnly)
         return forStep;
     return { ...forStep, builtins: [], tools: { ...generation.tools, wire: [] } };
@@ -63,7 +63,7 @@ function holdModelCall(calls, tool) {
 /** The step's request, with what it gives the model noted on `state`, and its call's usage and trace. */
 function startProviderCall(generation, system, state, answerOnly, labels) {
     const usage = startCallUsage(system.text, {
-        history: state.currentHistory,
+        history: modelHistory(state),
         input: generation.input,
     });
     state.lastCall = usage;

package/esm/src/kernel/engine/turn-trace.js

@@ -1,4 +1,4 @@
-import { errorKind } from '../../guardrails/error.js';
+import { describeError, errorKind } from '../../guardrails/error.js';
 import { traceBytes, traceContent, traceJson, } from '../../observability/trace-span.js';
 import { historyMessageParts } from '../interaction-parts.js';
 import { isFailedStopKind } from '../stop.js';
@@ -278,6 +278,7 @@ function guardrailAttributes(guardrail) {
         hits: guardrail.hits.map((hit) => ({
             rule: hit.rule,
             severity: hit.severity,
+            ...optional('signal', hit.signal),
             ...(hit.span ? { start: hit.span.start, end: hit.span.end } : {}),
             ...optional('match', hit.match),
             ...optional('label', hit.label),
@@ -285,6 +286,7 @@ function guardrailAttributes(guardrail) {
         })),
         ...(guardrail.provenance ? { provenance: { ...guardrail.provenance } } : {}),
         ...(guardrail.errorInternal ? { error: traceContent(guardrail.errorInternal) } : {}),
+        ...optional('error_summary', guardrail.errorSummary),
     };
 }
 /** What a stream check looked at, for its pass record. */
@@ -597,7 +599,7 @@ function errorName(err) {
 function recordException(span, err) {
     span.event('exception', {
         'exception.type': errorName(err),
-        'exception.message': traceContent(err instanceof Error ? err.message : String(err)),
+        'exception.message': traceContent(describeError(err)),
         ...(err instanceof Error && err.stack
             ? { 'exception.stacktrace': traceContent(err.stack) }
             : {}),

package/esm/src/kernel/protocols/runtime.js

@@ -1,4 +1,4 @@
-import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
+import { describeError, kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { retryTransient, waitDefault } from '../../providers/shared/retry.js';
 import { readSseChunks } from '../../providers/shared/sse.js';
@@ -374,7 +374,7 @@ function failureEvent(error) {
         type: 'error',
         errorKind: error.kind,
         // invariant: `error` is the person's wording, added from the profile's labels; the upstream text is internal.
-        errorInternal: error.message,
+        errorInternal: describeError(error),
         ...(error.copy ? { errorCopy: error.copy } : {}),
     };
 }

package/esm/src/kernel/provider-runtime.js

@@ -128,11 +128,14 @@ function diagnosticError(error, clean) {
         return new DOMException(message, error.name);
     if (isAbortError(error))
         return new DOMException(message, 'AbortError');
+    const cause = error instanceof Error && error.cause !== undefined
+        ? { cause: diagnosticError(error.cause, clean) }
+        : {};
     const result = error instanceof TheoremError
-        ? new TheoremError(error.kind, message, { copy: diagnosticCopy(error.copy, clean) })
+        ? new TheoremError(error.kind, message, { copy: diagnosticCopy(error.copy, clean), ...cause })
         : error instanceof TypeError
-            ? new TypeError(message)
-            : new Error(message);
+            ? new TypeError(message, cause)
+            : new Error(message, cause);
     if (isRecord(error) && typeof error.status === 'number')
         Object.assign(result, { status: error.status });
     return result;

package/esm/src/kernel/registry/profiles.js

@@ -1,6 +1,6 @@
 import { TOOL_BOUNDARIES } from '../../guardrails/boundaries.js';
 import { detectProblem } from '../../guardrails/detectors.js';
-import { TheoremError } from '../../guardrails/error.js';
+import { errorKind, TheoremError } from '../../guardrails/error.js';
 import { labelText, validateLabelOverrides } from '../../guardrails/labels.js';
 import { BLOCKED_REPLY_ON_BLOCK, } from '../../guardrails/types.js';
 import { resolveObservabilityPolicy } from '../../observability/resolve-policy.js';
@@ -332,7 +332,7 @@ function assertObservability(profileId, spec) {
             throw err;
         }
         const message = err instanceof Error ? err.message : String(err);
-        throw new TheoremError('config', `Profile ${profileId}: ${message}`);
+        throw new TheoremError(errorKind(err), `Profile ${profileId}: ${message}`, { cause: err });
     }
 }
 function assertIdentitySystem(input) {

package/esm/src/kernel/schema.js

@@ -798,6 +798,22 @@ export const EXTRA_FIELDS = {
         ...field("'page'", 'Who answers a call to a function tool. With page, the page the agent is on returns the output, and the tool has no handler.', ['page']),
         unset: 'Its handler',
     },
+    'registerTool.maxResponseBytes': {
+        ...field('number', 'The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with response_too_large.'),
+        unset: 'No limit',
+    },
+    'registerTool.session': {
+        ...field('McpSessionLimits', "How long and how many of an MCP tool's server sessions the kernel keeps."),
+        unset: 'No limits',
+    },
+    'registerTool.session.idleMs': {
+        ...field('number', 'How long a session may sit unused before the next call opens a new one, in milliseconds.'),
+        unset: 'No limit',
+    },
+    'registerTool.session.max': {
+        ...field('number', 'The most sessions the tool keeps open; past it the least recently used is dropped.'),
+        unset: 'No limit',
+    },
     'registerTool.maxCallsPerTurn': {
         ...field('number', 'How many times one turn of the calling agent may run this tool.'),
         unset: 'As many as its steps allow',

package/esm/src/kernel/tools/execute.js

@@ -742,7 +742,9 @@ async function* settleBodyOutcome(args) {
         provisional: { outputRaw: outcome.outputRaw, modelResult: outcome.modelResult },
         sources: tool.sources,
         ...(tool.type !== 'function' && tool.images
-            ? { images: (output) => fetchToolImages(tool.images, output, ctx) }
+            ? {
+                images: (output) => fetchToolImages(tool.images, output, ctx, tool.imageLimits),
+            }
             : {}),
         labels: tool.labels,
         reproject: makeReproject((v) => parseToolOutput(tool.output, v), 

package/esm/src/kernel/tools/image-fetch.d.ts

@@ -1,14 +1,12 @@
 import type { InteractionPart, ToolWarning } from '../turn-events.js';
-import type { ToolContext } from './types.js';
-/** The most pictures one call hands the model. */
-export declare const MAX_TOOL_IMAGES = 4;
+import type { ToolContext, ToolImageLimits } from './types.js';
 /**
  * The pictures a tool's `images(output)` names, fetched through the profile's network policy (every
  * hop, redirects included, no tool credentials) and handed to the model as image parts. A picture
  * that is not an https address, blocked, slow, too big or not an image is left out and reported in
  * one `images_unfetched` warning: the call itself stays whole. `urls` are the ones fetched.
  */
-export declare function fetchToolImages(images: (output: never) => string[], output: unknown, ctx: ToolContext): Promise<{
+export declare function fetchToolImages(images: (output: never) => string[], output: unknown, ctx: ToolContext, limits?: ToolImageLimits): Promise<{
     parts: InteractionPart[];
     urls: string[];
     warning?: ToolWarning;

package/esm/src/kernel/tools/image-fetch.js

@@ -1,17 +1,9 @@
 import { fetchGuarded } from '../../guardrails/network.js';
 import { bytesToBase64 } from '../util/base64.js';
 import { toolNetworkPolicy } from './events.js';
-/** The most pictures one call hands the model. */
-export const MAX_TOOL_IMAGES = 4;
-/** The largest picture fetched; a larger one is left out, not cut. */
-const MAX_TOOL_IMAGE_BYTES = 5 * 1024 * 1024;
-/** The most one call hands the model in all, so pictures cannot crowd a request past a provider's limit. */
-const MAX_TOOL_IMAGES_TOTAL_BYTES = 10 * 1024 * 1024;
-/** How long each picture may take, so a slow host cannot hold the call. */
-const IMAGE_FETCH_TIMEOUT_MS = 15_000;
 const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
-/** The body, read up to `maxBytes`; `undefined` when it runs past. */
-async function readCappedBytes(response, maxBytes) {
+/** The body, read up to `maxBytes` when set; `undefined` when it runs past. */
+async function readCappedBytes(response, maxBytes = Number.POSITIVE_INFINITY) {
     const declared = Number(response.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
         await response.body?.cancel().catch(() => { });
@@ -41,9 +33,15 @@ async function readCappedBytes(response, maxBytes) {
     }
     return bytes;
 }
-async function fetchOne(url, ctx) {
-    const timeout = AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS);
-    const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+/** The call's signal, joined by the picture's own timeout when the tool sets one. */
+function fetchSignal(ctx, timeoutMs) {
+    if (timeoutMs === undefined)
+        return ctx.signal;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+}
+async function fetchOne(url, ctx, limits) {
+    const signal = fetchSignal(ctx, limits.timeoutMs);
     const response = await fetchGuarded(url, { method: 'GET', headers: { Accept: 'image/*' }, signal }, {
         policy: toolNetworkPolicy(ctx),
         followRedirects: true,
@@ -56,9 +54,9 @@ async function fetchOne(url, ctx) {
         await response.body?.cancel().catch(() => { });
         throw new Error(`not a png, jpeg, gif or webp image (${mimeType || 'no type'})`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
-    const bytes = await readCappedBytes(response, MAX_TOOL_IMAGE_BYTES);
+    const bytes = await readCappedBytes(response, limits.bytes);
     if (!bytes)
-        throw new Error(`larger than ${MAX_TOOL_IMAGE_BYTES} bytes`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`larger than ${limits.bytes} bytes`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     return { type: 'image', mimeType, data: bytesToBase64(bytes) };
 }
 /** `url` when it is an absolute https address; otherwise the reason it is not. */
@@ -80,7 +78,7 @@ function httpsAddress(url) {
  * that is not an https address, blocked, slow, too big or not an image is left out and reported in
  * one `images_unfetched` warning: the call itself stays whole. `urls` are the ones fetched.
  */
-export async function fetchToolImages(images, output, ctx) {
+export async function fetchToolImages(images, output, ctx, limits = {}) {
     const reasons = [];
     const named = [];
     try {
@@ -100,8 +98,9 @@ export async function fetchToolImages(images, output, ctx) {
             warning: unfetched([`the images hook threw: ${String(err)}`]), // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         };
     }
-    const wanted = named.slice(0, MAX_TOOL_IMAGES);
-    const settled = await Promise.allSettled(wanted.map((url) => fetchOne(url, ctx)));
+    const wanted = named.slice(0, limits.count);
+    const settled = await Promise.allSettled(wanted.map((url) => fetchOne(url, ctx, limits)));
+    const totalBytes = limits.totalBytes ?? Number.POSITIVE_INFINITY;
     const parts = [];
     const urls = [];
     let total = 0;
@@ -113,8 +112,8 @@ export async function fetchToolImages(images, output, ctx) {
             return;
         }
         const size = 'data' in result.value ? result.value.data.length : 0;
-        if (total + size > MAX_TOOL_IMAGES_TOTAL_BYTES) {
-            reasons.push(`${new URL(url).hostname}: past the ${MAX_TOOL_IMAGES_TOTAL_BYTES} byte total`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        if (total + size > totalBytes) {
+            reasons.push(`${new URL(url).hostname}: past the ${totalBytes} byte total`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             return;
         }
         total += size;

package/esm/src/kernel/tools/mcp-sessions.d.ts

@@ -2,14 +2,19 @@
  * Sessions for MCP servers that refuse a call without one. A session is a cache, not state: it
  * lives in memory on one tool registry, is never persisted, and losing it costs one reopen.
  */
+import type { McpSessionLimits } from './types.js';
 export type McpSession = {
     id: string;
     protocolVersion: string;
 };
+/** The tool a session is used for, and that tool's own `session` limits. */
+export interface McpSessionUse extends McpSessionLimits {
+    tool: string;
+}
 export interface McpSessionCache {
-    get(key: string): McpSession | undefined;
+    get(key: string, use: McpSessionUse): McpSession | undefined;
     /** Parallel callers for one key share a single `open`. */
-    open(key: string, open: () => Promise<McpSession>): Promise<McpSession>;
+    open(key: string, use: McpSessionUse, open: () => Promise<McpSession>): Promise<McpSession>;
     /** Only drops the session if it's still `id`, so a late expiry can't evict a newer one. */
     drop(key: string, id: string): void;
     clear(): void;

package/esm/src/kernel/tools/mcp-sessions.js

@@ -2,38 +2,47 @@
  * Sessions for MCP servers that refuse a call without one. A session is a cache, not state: it
  * lives in memory on one tool registry, is never persisted, and losing it costs one reopen.
  */
-const MAX_SESSIONS = 256;
-const IDLE_MS = 30 * 60 * 1000;
 // why: The spec allows visible ASCII only; the cap keeps a server from bloating every later request.
 const SESSION_ID = /^[\x21-\x7E]{1,256}$/;
 export function createMcpSessionCache(now = Date.now) {
     const sessions = new Map();
     const pending = new Map();
+    /** Drops the tool's least recently used sessions past its `max`. */
+    const trim = ({ tool, max }) => {
+        if (max === undefined)
+            return;
+        let held = [...sessions.values()].filter((entry) => entry.tool === tool).length;
+        for (const [key, entry] of sessions) {
+            if (held <= max)
+                break;
+            if (entry.tool !== tool)
+                continue;
+            sessions.delete(key);
+            held--;
+        }
+    };
     return {
-        get(key) {
+        get(key, use) {
             const entry = sessions.get(key);
             if (!entry)
                 return undefined;
             sessions.delete(key);
-            if (now() - entry.usedAt > IDLE_MS)
+            if (use.idleMs !== undefined && now() - entry.usedAt > use.idleMs)
                 return undefined;
             // why: Re-inserting keeps the map in least-recently-used order for eviction.
-            sessions.set(key, { ...entry, usedAt: now() });
+            sessions.set(key, { ...entry, usedAt: now(), tool: use.tool });
+            trim(use);
             return { id: entry.id, protocolVersion: entry.protocolVersion };
         },
-        open(key, open) {
+        open(key, use, open) {
             const inFlight = pending.get(key);
             if (inFlight)
                 return inFlight;
             const opening = open()
                 .then((session) => {
                 sessions.delete(key);
-                sessions.set(key, { ...session, usedAt: now() });
-                for (const oldest of sessions.keys()) {
-                    if (sessions.size <= MAX_SESSIONS)
-                        break;
-                    sessions.delete(oldest);
-                }
+                sessions.set(key, { ...session, usedAt: now(), tool: use.tool });
+                trim(use);
                 return session;
             })
                 .finally(() => pending.delete(key));

package/esm/src/kernel/tools/registry.js

@@ -63,17 +63,38 @@ function assertTimeout(name, timeoutMs) {
         return;
     throw new TheoremError('config', `Tool "${name}" timeoutMs needs a finite number of ms above 0`);
 }
+/** A count or size limit is a whole number above 0. */
+function assertWhole(name, field, value) {
+    if (value === undefined || (Number.isInteger(value) && value > 0))
+        return;
+    throw new TheoremError('config', `Tool "${name}" ${field} needs a whole number above 0`);
+}
+/** What a remote tool may set on how much it reads: its body, and the pictures it names. */
+function assertReadLimits(def) {
+    assertWhole(def.name, 'maxResponseBytes', def.maxResponseBytes);
+    const images = def.imageLimits;
+    if (!images)
+        return;
+    assertWhole(def.name, 'imageLimits.count', images.count);
+    assertWhole(def.name, 'imageLimits.bytes', images.bytes);
+    assertWhole(def.name, 'imageLimits.totalBytes', images.totalBytes);
+    assertTimeout(def.name, images.timeoutMs);
+}
 function normalizeHttp(def) {
     assertFixedEndpointOrigin(def.endpoint);
     assertAuthService(def.name, def.auth);
     assertQueryParam(def.name, def.auth, def.mapping?.queryParams);
     assertLimit(def.name, def.limit);
     assertTimeout(def.name, def.timeoutMs);
+    assertReadLimits(def);
     return { ...def, type: 'http', ...schemasFromZod(def) };
 }
 function normalizeMcp(def) {
     assertAuthService(def.name, def.auth);
     assertQueryParam(def.name, def.auth);
+    assertReadLimits(def);
+    assertWhole(def.name, 'session.idleMs', def.session?.idleMs);
+    assertWhole(def.name, 'session.max', def.session?.max);
     return { ...def, type: 'mcp', ...schemasFromZod(def) };
 }
 function normalizeFunction(def) {

package/esm/src/kernel/tools/remote.d.ts

@@ -96,8 +96,6 @@ export declare function refusedCredentialOutcome(tool: {
     name: string;
     auth?: ToolAuthConfig;
 }, refusal: CredentialRefusal | undefined, carried: boolean, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, ToolBodyOutcome | undefined>;
-/** The most of a tool's response body the kernel reads; past it the call fails instead of exhausting the host's memory. */
-export declare const MAX_TOOL_RESPONSE_BYTES: number;
 /** Every string in `value` with the credential replaced. */
 export declare function omitSecret(value: unknown, secret: string): unknown;
 /** A failure's message and details with the credential replaced. */

package/esm/src/kernel/tools/remote.js

@@ -391,12 +391,10 @@ function* thrownOutcome(err, checks) {
     return failureOutcome({ code: 'network_error', kind: 'network', message: messageOf(err) }, false);
 }
 const OMIT_CREDENTIAL = '[omitted - credential]';
-/** The most of a tool's response body the kernel reads; past it the call fails instead of exhausting the host's memory. */
-export const MAX_TOOL_RESPONSE_BYTES = 4 * 1024 * 1024;
 /** The most of an error or unparseable body quoted back in a failure message. */
 const MAX_QUOTED_BODY_CHARS = 2000;
-/** A body's text as it arrives, up to `maxBytes`; returns `false` when it runs past, with the rest left unread. */
-async function* cappedPieces(response, maxBytes) {
+/** A body's text as it arrives, up to `maxBytes` when set; returns `false` when it runs past, with the rest left unread. */
+async function* cappedPieces(response, maxBytes = Number.POSITIVE_INFINITY) {
     const declared = Number(response.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
         await response.body?.cancel().catch(() => { });
@@ -427,8 +425,8 @@ async function* cappedPieces(response, maxBytes) {
         yield rest;
     return true;
 }
-/** A body, read up to `maxBytes`; `undefined` when it runs past, with the rest left unread. */
-async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
+/** A body, read up to `maxBytes` when set; `undefined` when it runs past, with the rest left unread. */
+async function readCappedText(response, maxBytes) {
     const pieces = cappedPieces(response, maxBytes);
     let text = '';
     for (;;) {
@@ -443,8 +441,8 @@ async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
  * shows: the last `secret.length - 1` characters wait for the next piece, so one split across
  * pieces is whole when it is replaced. Drafts that ran before the body ran past its cap stay sent.
  */
-async function* readCappedTextShowing(response, shown, secret) {
-    const pieces = cappedPieces(response, MAX_TOOL_RESPONSE_BYTES);
+async function* readCappedTextShowing(response, shown, secret, maxBytes) {
+    const pieces = cappedPieces(response, maxBytes);
     const hold = secret ? secret.length - 1 : 0;
     let text = '';
     let pending = '';
@@ -471,12 +469,12 @@ async function* readCappedTextShowing(response, shown, secret) {
 function quotedBody(text) {
     return text.length > MAX_QUOTED_BODY_CHARS ? `${text.slice(0, MAX_QUOTED_BODY_CHARS)}…` : text;
 }
-/** The failure for a body past MAX_TOOL_RESPONSE_BYTES. */
-function tooLargeFailure(host) {
+/** The failure for a body past the tool's `maxResponseBytes`. */
+function tooLargeFailure(host, maxBytes) {
     return {
         code: 'response_too_large',
         kind: 'bad_response',
-        message: `Response from ${host} is larger than ${MAX_TOOL_RESPONSE_BYTES} bytes`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        message: `Response from ${host} is larger than ${maxBytes} bytes`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     };
 }
 /** The text with the credential replaced. */
@@ -568,10 +566,10 @@ function isDraftable(response) {
     return type === '' || type.startsWith('text/') || /[/+]json\b/.test(type);
 }
 /** An HTTP tool's body; a successful text body shows as drafts while it arrives, any other reads whole. */
-async function* readHttpBody(response, shown, secret) {
+async function* readHttpBody(response, shown, secret, maxBytes) {
     if (!shown || !isDraftable(response))
-        return await readCappedText(response);
-    return yield* readCappedTextShowing(response, shown, secret);
+        return await readCappedText(response, maxBytes);
+    return yield* readCappedTextShowing(response, shown, secret, maxBytes);
 }
 async function* sendHttpRequest(tool, targetUrl, body, { authHeaders, secret }, ctx, base, span, shown) {
     const checks = requestChecks(span);
@@ -597,9 +595,10 @@ async function* sendHttpRequest(tool, targetUrl, body, { authHeaders, secret },
             resolveHost: ctx.resolveHost,
             onCheck: checks.onCheck,
         }));
-        const text = yield* readHttpBody(response, shown, secret);
-        if (text === undefined)
-            return failureOutcome(tooLargeFailure(targetUrl.hostname), false);
+        const text = yield* readHttpBody(response, shown, secret, tool.maxResponseBytes);
+        if (text === undefined) {
+            return failureOutcome(tooLargeFailure(targetUrl.hostname, tool.maxResponseBytes), false);
+        }
         if (!response.ok) {
             const refused = yield* refusedCredentialOutcome(tool, credentialRefusal(response), secret !== undefined, ctx, base);
             if (refused)
@@ -747,9 +746,10 @@ async function fetchMcpProtocolAttempt(transport, rpcId, mcpToolName, input, pro
         resolveHost: transport.resolveHost,
         onCheck: transport.onCheck,
     });
-    const text = await readCappedText(response);
+    const text = await readCappedText(response, transport.maxResponseBytes);
     if (text === undefined) {
-        return { kind: 'failure', failure: tooLargeFailure(new URL(transport.url).hostname) };
+        const host = new URL(transport.url).hostname;
+        return { kind: 'failure', failure: tooLargeFailure(host, transport.maxResponseBytes) };
     }
     if (!response.ok) {
         const sessionSent = SESSION_HEADER in transport.originBoundHeaders;
@@ -854,9 +854,10 @@ async function openMcpSession(transport) {
             clientInfo: { name: 'theorem', version: '1' },
         },
     }, { 'Mcp-Method': 'initialize' });
-    const text = await readCappedText(response);
+    const text = await readCappedText(response, transport.maxResponseBytes);
     if (text === undefined) {
-        throw new McpSessionFailure(tooLargeFailure(new URL(transport.url).hostname));
+        const host = new URL(transport.url).hostname;
+        throw new McpSessionFailure(tooLargeFailure(host, transport.maxResponseBytes));
     }
     if (!response.ok) {
         throw sessionFailure(`mcp_session_http_${response.status}`, `MCP server refused to open a session: HTTP ${response.status}: ${quotedBody(text)}`);
@@ -886,7 +887,7 @@ async function negotiateInSession(transport, rpcId, mcpToolName, input, sessions
     for (let attempt = 0; attempt < 2; attempt++) {
         if (!session) {
             try {
-                session = await sessions.cache.open(sessions.key, () => openMcpSession(transport));
+                session = await sessions.cache.open(sessions.key, sessions.use, () => openMcpSession(transport));
             }
             catch (err) {
                 if (err instanceof McpSessionFailure)
@@ -1090,13 +1091,16 @@ async function* sendMcpRequest(tool, url, input, { authHeaders, secret }, ctx, b
             resolveHost: ctx.resolveHost,
             signal: ctx.signal,
             onCheck: checks.onCheck,
+            ...(tool.maxResponseBytes === undefined ? {} : { maxResponseBytes: tool.maxResponseBytes }),
         };
         const key = await mcpSessionKey(url.href, transport.originBoundHeaders);
-        const cached = sessions.get(key);
+        const use = { tool: tool.name, ...tool.session };
+        const cached = sessions.get(key, use);
         const first = cached
             ? await negotiateInSession(transport, base.callId, tool.mcpToolName, input, {
                 cache: sessions,
                 key,
+                use,
                 cached,
             })
             : await negotiateMcpRpc(transport, base.callId, tool.mcpToolName, input);
@@ -1104,6 +1108,7 @@ async function* sendMcpRequest(tool, url, input, { authHeaders, secret }, ctx, b
             ? await negotiateInSession(transport, base.callId, tool.mcpToolName, input, {
                 cache: sessions,
                 key,
+                use,
             })
             : first;
         const refused = yield* refusedCredentialOutcome(tool, negotiated.refusal, secret !== undefined, ctx, base);

package/esm/src/kernel/tools/types.d.ts

@@ -163,12 +163,25 @@ export interface ToolOutputHooks<TOut = unknown> {
 /** For a tool whose result names pictures by address; function tools return the bytes themselves as `parts`. */
 export interface ToolImageHooks<TOut = unknown> {
     /**
-     * The https addresses of pictures in `output` the model should see, at most `MAX_TOOL_IMAGES`
-     * of them. After the result passes the output guard, the kernel fetches each one through the
-     * profile's network policy, without the tool's credentials, and hands the model the image as a
-     * part; one it cannot fetch is an `images_unfetched` warning, never a failed call.
+     * The https addresses of pictures in `output` the model should see. After the result passes the
+     * output guard, the kernel fetches each one through the profile's network policy, without the
+     * tool's credentials, and hands the model the image as a part; one it cannot fetch is an
+     * `images_unfetched` warning, never a failed call.
      */
     images?: (output: TOut) => string[];
+    /** How many of those pictures the kernel fetches, how large, and how slowly. Left out, there is no limit. */
+    imageLimits?: ToolImageLimits;
+}
+/** Each limit left out is no limit. A picture past one is left out, not cut. */
+export interface ToolImageLimits {
+    /** The most pictures one call hands the model; the first ones named are kept. */
+    count?: number;
+    /** The largest picture fetched. */
+    bytes?: number;
+    /** The most one call hands the model in all. */
+    totalBytes?: number;
+    /** How long each picture may take. */
+    timeoutMs?: number;
 }
 export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
     type: 'function';
@@ -226,6 +239,8 @@ export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, To
     };
     /** The service's own limit for one key; the kernel keeps this tool's requests within it. */
     limit?: HttpToolLimit;
+    /** The most of a response body the kernel reads; past it the call fails `response_too_large`. Left out, there is no limit. */
+    maxResponseBytes?: number;
     /**
      * How long the service may take to answer, its body read included. Past it the call
      * fails `timeout` and frees its place in the limit. Left out, a call waits as long as
@@ -246,6 +261,17 @@ export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, Too
     mcpToolName: string;
     headers?: Record<string, string>;
     auth?: ToolAuthConfig;
+    /** The most of a response body the kernel reads; past it the call fails `response_too_large`. Left out, there is no limit. */
+    maxResponseBytes?: number;
+    /** How long and how many of this tool's server sessions the kernel keeps. Left out, there is no limit. */
+    session?: McpSessionLimits;
+}
+/** The sessions an MCP tool keeps: each field left out is no limit. */
+export interface McpSessionLimits {
+    /** How long a session may sit unused before the next call opens a new one, in milliseconds. */
+    idleMs?: number;
+    /** The most sessions the tool keeps open; past it the least recently used is dropped. */
+    max?: number;
 }
 /**
  * What an agent tool call carries: the text, and whatever else the called

package/esm/src/kernel/turn-events.d.ts

@@ -520,6 +520,8 @@ export interface CompactionFailure {
     stop?: TurnStopKind;
     /** The error it reported, when it reported one. */
     error?: ErrorKind;
+    /** Why it failed, for the builder only: `forClient` strips it for a visitor. */
+    errorInternal?: string;
     /** It completed without a summary. */
     empty?: true;
     /** Nothing in `toCompact` was left for it to read, so it did not run. */

package/esm/src/kernel/turn-events.js

@@ -333,6 +333,7 @@ true;
 const compactionFailure = z.object({
     stop: z.enum(TURN_STOP_KINDS).optional(),
     error: errorKindSchema.optional(),
+    errorInternal: z.string().optional(),
     empty: z.literal(true).optional(),
     unreadable: z.literal(true).optional(),
 });

package/esm/src/observability/trace-catalog.js

@@ -646,6 +646,7 @@ const HITS = fields('error', 'Hits', 'Each rule that matched.', {
         open: true,
     },
     severity: attr('error', 'Severity', 'text', 'How serious the rule says a match is.', SEVERITY_OPTIONS),
+    signal: attr('error', 'Signal', 'text', "What made a `tool_instructions` match one, or how a host detector's `find` failed: `find_threw` or `find_result`."),
     start: attr('error', 'From', 'number', 'Where the match starts in the checked text.'),
     end: attr('error', 'To', 'number', 'Where the match ends in the checked text.'),
     match: attr('error', 'Match', 'text', 'The matched text, exact. Kept only when the profile records match previews.'),
@@ -680,6 +681,7 @@ const TRACE_EVENTS = {
                 depth: attr('tool', 'Hops', 'number', "Tool calls between the user's turn and this text: 1 for a direct call, more through another agent."),
             }),
             error: attr('error', 'Detail', 'content', "The guardrail's internal reason."),
+            error_summary: attr('error', 'Failure', 'text', "Which host detector failed, how, and its error id, in the kernel's words only. The host stream's reason ends with the same id."),
         },
     },
     'theorem.attempt.retry': {
@@ -718,6 +720,7 @@ const TRACE_EVENTS = {
             dropped_media: attr('messages', 'Media left out', 'number', 'Media the compactor does not take, left out of what it read.'),
             failure_stop: attr('agent', 'Compactor stop', 'text', 'How the failed compactor stopped.', STOP_KINDS),
             failure_error: attr('agent', 'Compactor error', 'text', 'The error the compactor failed with.', ERROR_KIND_OPTIONS),
+            failure_reason: attr('agent', 'Compactor reason', 'content', 'Why the compactor failed, in its own words.'),
             failure_empty: attr('agent', 'Empty summary', 'boolean', 'The compactor replied with nothing.'),
             failure_unreadable: attr('agent', 'Nothing to read', 'boolean', 'Everything to compact was media the compactor does not take, so it did not run.'),
             summary: attr('messages', 'Summary', 'content', 'The summary that replaced them.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.508.geda6db0",
+  "version": "0.3.4-next.524.g5000023",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",