@theoremjs/agents 0.3.4-next.522.g9e684cd → 0.3.4-next.528.g44c76f9

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

@@ -15,6 +15,8 @@ interface Detection {
     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;
 /**
@@ -94,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' | 'errorInternal'>;
+    found(): Pick<Detection, 'action' | 'hits' | 'errorInternal' | 'errorSummary'>;
 }
 /** A reader for everything crossing `boundary` in one request. */
 declare function boundaryReader(boundary: Boundary, detect: ResolvedDetect): BoundaryReader;
@@ -102,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' | 'errorInternal'>, 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

@@ -16,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')
@@ -139,15 +147,18 @@ 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 } : {});
-        const outside = {
-            signal: 'find_result',
-            // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            reason: 'find returned no list of stretches inside the text',
-        };
+        // 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 outside;
         const inside = spans.every(({ start, end }) => Number.isInteger(start) &&
@@ -159,7 +170,12 @@ function foundBy(find, text, boundary) {
     }
     catch (err) {
         // why: A reading that failed found nothing it can vouch for, so the text does not cross.
-        return { signal: 'find_threw', reason: `find threw: ${describeError(err)}` };
+        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) {
@@ -174,8 +190,10 @@ function hostReader(host, boundary, chosen) {
             if (!host.find)
                 return matched;
             const found = foundBy(host.find, text, boundary);
-            if (!Array.isArray(found))
-                return { ...found, reason: `Host detector '${host.id}' ${found.reason}` };
+            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 }),
@@ -219,13 +237,13 @@ function failedHit({ rule, label }, signal) {
 function detectAt(text, boundary, detect, scope = NO_SCOPE) {
     const hits = [];
     const redact = [];
-    const reasons = [];
+    const failures = [];
     let action = 'allow';
     for (const reader of readersAt(boundary, detect, scope)) {
         const spans = reader.spans(text);
         if (!Array.isArray(spans)) {
             hits.push(failedHit(reader, spans.signal));
-            reasons.push(spans.reason);
+            failures.push({ errorInternal: spans.reason, errorSummary: spans.summary });
             action = 'block';
             continue;
         }
@@ -239,7 +257,7 @@ function detectAt(text, boundary, detect, scope = NO_SCOPE) {
         action = stronger(action, reader.chosen);
     }
     if (action === 'block') {
-        return { action, hits, ...(reasons.length ? { errorInternal: reasons.join('\n') } : {}) };
+        return { action, hits, ...failureText(failures) };
     }
     if (redact.length === 0)
         return { action, text, hits };
@@ -292,12 +310,12 @@ function detectReads(boundaries, detect, scope) {
  */
 function detectRelease(window, { from, to, settled }, boundary, detect, { detectors, scope }) {
     const failed = [];
-    const reasons = [];
+    const failures = [];
     const found = readersAt(boundary, detect, scope, detectors).flatMap((reader) => {
         const spans = reader.spans(window);
         if (!Array.isArray(spans)) {
             failed.push(failedHit(reader, spans.signal));
-            reasons.push(spans.reason);
+            failures.push({ errorInternal: spans.reason, errorSummary: spans.summary });
             return [];
         }
         return spans
@@ -305,7 +323,7 @@ function detectRelease(window, { from, to, settled }, boundary, detect, { detect
             .map((span) => ({ span, rule: reader.rule, label: reader.label, chosen: reader.chosen }));
     });
     if (failed.length > 0) {
-        return { action: 'block', hits: failed, taken: 0, errorInternal: reasons.join('\n') };
+        return { action: 'block', hits: failed, taken: 0, ...failureText(failures) };
     }
     const hitOf = ({ span, rule, label }) => ({
         ...hitFromSpan(window, span, rule, 'high'),
@@ -377,23 +395,23 @@ function storedHostSpans(text, detect) {
 /** A reader for everything crossing `boundary` in one request. */
 function boundaryReader(boundary, detect) {
     const hits = [];
-    const reasons = [];
+    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)
-                reasons.push(detected.errorInternal);
+            if (detected.errorInternal && detected.errorSummary) {
+                failures.push({
+                    errorInternal: detected.errorInternal,
+                    errorSummary: detected.errorSummary,
+                });
+            }
             action = stronger(action, detected.action);
             return detected.text ?? '';
         },
-        found: () => ({
-            action,
-            hits,
-            ...(reasons.length ? { errorInternal: reasons.join('\n') } : {}),
-        }),
+        found: () => ({ action, hits, ...failureText(failures) }),
     };
 }
 const TOOL_STAGE = Object.fromEntries(TOOL_BOUNDARIES.map((boundary) => [
@@ -439,6 +457,7 @@ function detectEvent(boundary, found, provenance, stage = BOUNDARY_STAGE[boundar
         ...(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' | 'errorInternal'> & {
+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

@@ -24,7 +24,8 @@ function readValue(value, boundary, detect, scope = {}) {
     }
     const found = detectAt(scan.text, boundary, detect, scope);
     if (found.action !== 'redact') {
-        const why = found.errorInternal ? { errorInternal: found.errorInternal } : {};
+        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 ?? '');

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

@@ -18,6 +18,10 @@ declare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): stri
 declare function publicError(err: unknown, labels?: LabelOverrides): string;
 /** 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;
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+declare function networkError(err: unknown): unknown;
+/** `send`, with a failed send or body read named as `networkError` names it. */
+declare function sendOrNetworkError(send: typeof fetch, ...args: Parameters<typeof fetch>): Promise<Response>;
 type ProducedError = TurnEventOf<'error'> & {
     errorInternal: string;
 };
@@ -28,4 +32,4 @@ declare function withPublicLabels(event: TurnEvent, labels?: LabelOverrides): Tu
 export type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';
 export { ERROR_KINDS } from './theorem-error.js';
 export type { ProducedError };
-export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, networkError, publicError, sendOrNetworkError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

package/esm/src/guardrails/error.js

@@ -88,6 +88,49 @@ function describeError(err) {
     }
     return lines.join('\n');
 }
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+function networkError(err) {
+    if (err instanceof TheoremError || isAbortError(err) || isTimeoutError(err)) {
+        return err;
+    }
+    return new TheoremError('network', describeError(err), { cause: err });
+}
+/** `response` with a body whose read that fails is named as `networkError` names it. */
+function bodyOrNetworkError(response) {
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done)
+                    controller.close();
+                else
+                    controller.enqueue(next.value);
+            }
+            catch (err) {
+                controller.error(networkError(err));
+            }
+        },
+        cancel: (reason) => reader.cancel(reason),
+    }, { highWaterMark: 0 });
+    const named = new Response(body, response);
+    Object.defineProperties(named, {
+        url: { value: response.url },
+        redirected: { value: response.redirected },
+    });
+    return named;
+}
+/** `send`, with a failed send or body read named as `networkError` names it. */
+async function sendOrNetworkError(send, ...args) {
+    try {
+        return bodyOrNetworkError(await send(...args));
+    }
+    catch (err) {
+        throw networkError(err);
+    }
+}
 /** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */
 function toErrorEvent(err) {
     return {
@@ -112,4 +155,4 @@ function withPublicLabels(event, labels) {
     return event;
 }
 export { ERROR_KINDS } from './theorem-error.js';
-export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, networkError, publicError, sendOrNetworkError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

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/network.js

@@ -1,4 +1,4 @@
-import { TheoremError } from './error.js';
+import { sendOrNetworkError, TheoremError } from './error.js';
 /**
  * IPv4 ranges refused outright:
  * - Loopback: 127.0.0.0/8
@@ -265,7 +265,7 @@ export async function fetchGuarded(url, init, options) {
                 sent.set(name, value);
             }
         }
-        const response = await fetchFn(target.href, {
+        const response = await sendOrNetworkError(fetchFn, target.href, {
             ...init,
             method,
             headers: sent,
@@ -305,7 +305,7 @@ export function dnsOverHttpsResolver(options) {
         const url = new URL(options.endpoint);
         url.searchParams.set('name', hostname);
         url.searchParams.set('type', String(type));
-        const response = await fetchFn(url.href, {
+        const response = await sendOrNetworkError(fetchFn, url.href, {
             headers: { accept: 'application/dns-json' },
             ...(signal ? { signal } : {}),
         });

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

@@ -41,10 +41,11 @@ function stripCompactionInternal(event) {
     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) {

package/esm/src/kernel/engine/decision.d.ts

@@ -5,16 +5,26 @@ import type { KernelRegistry } from '../registry/kernel-registry.js';
 import type { DecisionProfile, DecisionRequest, DecisionResult } from '../types.js';
 /** Each decision failure code, and the error kind it reads as. */
 declare const DECISION_ERROR_KINDS: {
+    readonly invalid_config: "config";
     readonly invalid_request: "request";
+    readonly invalid_input: "input";
+    readonly not_allowed: "action";
     readonly authentication: "auth";
     readonly permission: "auth";
     readonly rate_limited: "rate_limit";
+    readonly busy: "busy";
+    readonly unsupported: "unsupported";
     readonly unavailable: "unavailable";
     readonly network: "network";
     readonly timeout: "timeout";
     readonly cancelled: "cancelled";
     readonly malformed_response: "bad_response";
+    readonly refused: "safety";
+    readonly blocked: "blocked";
     readonly disclosure_blocked: "blocked";
+    readonly declined: "declined";
+    readonly failed: "failed";
+    readonly internal: "internal";
 };
 /**
  * A normalized native-decision failure; response bodies are deliberately omitted. What the

package/esm/src/kernel/engine/decision.js

@@ -1,4 +1,4 @@
-import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { errorKind, TheoremError, throwIfAborted } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { traceJson } from '../../observability/trace-span.js';
 import { guardedCall } from '../provider-runtime.js';
@@ -8,16 +8,47 @@ import { tracedCall } from './call-trace.js';
 import { referencedAssets } from './decision-references.js';
 /** Each decision failure code, and the error kind it reads as. */
 const DECISION_ERROR_KINDS = {
+    invalid_config: 'config',
     invalid_request: 'request',
+    invalid_input: 'input',
+    not_allowed: 'action',
     authentication: 'auth',
     permission: 'auth',
     rate_limited: 'rate_limit',
+    busy: 'busy',
+    unsupported: 'unsupported',
     unavailable: 'unavailable',
     network: 'network',
     timeout: 'timeout',
     cancelled: 'cancelled',
     malformed_response: 'bad_response',
+    refused: 'safety',
+    blocked: 'blocked',
     disclosure_blocked: 'blocked',
+    declined: 'declined',
+    failed: 'failed',
+    internal: 'internal',
+};
+/** Each kind's code: a thrown failure keeps its kind. */
+const DECISION_CODES = {
+    config: 'invalid_config',
+    request: 'invalid_request',
+    input: 'invalid_input',
+    action: 'not_allowed',
+    auth: 'authentication',
+    rate_limit: 'rate_limited',
+    busy: 'busy',
+    unsupported: 'unsupported',
+    unavailable: 'unavailable',
+    bad_response: 'malformed_response',
+    network: 'network',
+    timeout: 'timeout',
+    safety: 'refused',
+    blocked: 'blocked',
+    declined: 'declined',
+    failed: 'failed',
+    cancelled: 'cancelled',
+    internal: 'internal',
 };
 /**
  * A normalized native-decision failure; response bodies are deliberately omitted. What the
@@ -363,25 +394,10 @@ function recordResult(root, result) {
 function decisionProviderError(error) {
     if (error instanceof DecisionError)
         return error;
-    const kind = error instanceof TheoremError
-        ? error.kind
-        : error instanceof TypeError
-            ? 'network'
-            : 'bad_response';
-    const codes = {
-        auth: 'authentication',
-        rate_limit: 'rate_limited',
-        network: 'network',
-        busy: 'unavailable',
-        unavailable: 'unavailable',
-        timeout: 'timeout',
-        cancelled: 'cancelled',
-        request: 'invalid_request',
-        unsupported: 'invalid_request',
-    };
+    const kind = errorKind(error);
     const code = kind === 'auth' && isRecord(error) && error.status === 403
         ? 'permission'
-        : (codes[kind] ?? 'malformed_response');
+        : DECISION_CODES[kind];
     return new DecisionError(code, 
     // why: A framework failure's message holds no response body, and says what stopped the decision.
     error instanceof TheoremError ? error.message : labelText('provider.decision_failed'), isRecord(error) && typeof error.status === 'number' ? error.status : undefined, { cause: error });

package/esm/src/kernel/engine/turn-trace.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. */

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

@@ -1,7 +1,7 @@
 import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { jsonObjectSchema } from '../json.js';
-import { operationUnavailable, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, } from './operation.js';
+import { operationBroken, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, } from './operation.js';
 class ReplayedOperation {
     outcome;
     constructor(outcome) {
@@ -41,7 +41,7 @@ class CoordinatedExecution {
         if (result.kind === 'running' || result.kind === 'uncertain')
             throw uncertainError();
         if (result.kind !== 'acquired' || typeof result.claimToken !== 'string' || !result.claimToken)
-            throw operationUnavailable();
+            throw operationBroken("The tool coordinator's begin returned no claim"); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         this.claim = { ...operation, claimToken: result.claimToken };
         throwIfAborted(this.signal);
         return this.claim;
@@ -64,7 +64,7 @@ class CoordinatedExecution {
             return undefined;
         }
         if (!this.terminal)
-            throw operationUnavailable();
+            throw operationBroken('The tool run ended with no terminal event'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         const { modelResult, outputRaw, failure, awaiting, denied, callNotStarted, aborted, pendingInject, } = settlement;
         const effects = this.claim ? (failure ? 'unknown' : 'completed') : 'not_started';
         const outcome = {
@@ -96,7 +96,7 @@ class CoordinatedExecution {
         if (saved.event.tool.operationId !== operationId ||
             saved.event.tool.callId !== callId ||
             saved.event.tool.name !== toolId)
-            throw operationUnavailable();
+            throw operationBroken("The tool coordinator's saved outcome is another operation's"); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         this.committed = true;
         return saved;
     }
@@ -122,7 +122,7 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
         throw uncertainError();
     if (existing?.kind === 'settled') {
         if (!authorizeReplay)
-            throw operationUnavailable();
+            throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         const saved = execution.replay(new ReplayedOperation(existing.outcome));
         await authorizeReplay(saved);
         throwIfAborted(signal);
@@ -146,7 +146,7 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
     catch (error) {
         if (error instanceof ReplayedOperation) {
             if (!authorizeReplay)
-                throw operationUnavailable();
+                throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             const saved = execution.replay(error);
             await authorizeReplay(saved);
             yield saved.event;

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

@@ -16,7 +16,7 @@ import { dispatchToolBody, failedActivity, failedActivityOf, failureEvent, messa
 import { HandlerEvents } from './handler-events.js';
 import { fetchToolImages } from './image-fetch.js';
 import { formatToolFailureForModel, formatToolResult, frameToolFailure } from './model-text.js';
-import { operationUnavailable, operationWireValue } from './operation.js';
+import { operationBroken, operationWireValue } from './operation.js';
 import { checkPermission, gateDetails, isGateResumeDenied, isGateResumeGranted, isResumeContinuation, } from './permission.js';
 import { executeHttpTool, executeMcpTool, failureWithoutSecret, modelResultFromOutput, omitSecret, outcomeFromUnauth, parseToolOutput, refusedCredentialOutcome, resolveToolAuth, withMedia, } from './remote.js';
 import { extractLoadedIds, profileToolAllow, profileToolsSpec, promoteLoadedTools, } from './resolve.js';
@@ -467,13 +467,14 @@ async function* receivePageAnswer(tool, ctx, claim, base) {
     const execution = ctx.pageExecution;
     if (tool.answeredBy !== 'page' || !execution)
         return ctx;
-    if (!claim?.invocation)
-        throw operationUnavailable();
+    if (!claim?.invocation) {
+        throw new TheoremError('config', `Page tool '${tool.name}' needs a tool execution coordinator (execution)`);
+    }
     const argumentsForPage = jsonObjectSchema.parse(operationWireValue(claim.invocation.preparedInput));
     const dispatch = await execution.dispatch(claim, ctx.signal);
     throwIfAborted(ctx.signal);
     if (!dispatch.grantId)
-        throw operationUnavailable();
+        throw operationBroken('The page dispatch returned no grantId'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     yield toolEvent(base, {
         phase: 'dispatch',
         grantId: dispatch.grantId,

package/esm/src/kernel/tools/memory-execution.js

@@ -1,4 +1,5 @@
-import { operationUnavailable, } from './operation.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { operationBroken, } from './operation.js';
 /** How many operations a memory coordinator tracks before it refuses new ones. */
 const DEFAULT_MEMORY_EXECUTION_LIMIT = 256;
 /**
@@ -23,6 +24,8 @@ export function createMemoryToolExecution(options = {}) {
         const record = records.get(keyOf(claim));
         return record?.state === 'running' && record.claimToken === claim.claimToken;
     };
+    const full = () => new TheoremError('config', `The memory tool coordinator holds its maxOperations of ${limit}`);
+    const notHeld = () => operationBroken('The memory tool coordinator holds no running claim for this token'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     return {
         lookup: (operation) => Promise.resolve(known(operation)),
         begin: (operation) => {
@@ -30,28 +33,29 @@ export function createMemoryToolExecution(options = {}) {
             if (earlier)
                 return Promise.resolve(earlier);
             if (records.size >= limit)
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(full());
             const claimToken = crypto.randomUUID();
             records.set(keyOf(operation), { state: 'running', claimToken });
             return Promise.resolve({ kind: 'acquired', claimToken });
         },
         settle: (claim, outcome) => {
             if (!holds(claim))
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(notHeld());
             records.set(keyOf(claim), { state: 'settled', outcome });
             return Promise.resolve();
         },
         settleNotStarted: (operation, outcome) => {
-            if (records.has(keyOf(operation)))
-                return Promise.reject(operationUnavailable());
+            if (records.has(keyOf(operation))) {
+                return Promise.reject(operationBroken('The memory tool coordinator already has a record for this operation'));
+            }
             if (records.size >= limit)
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(full());
             records.set(keyOf(operation), { state: 'settled', outcome });
             return Promise.resolve();
         },
         markUncertain: (claim) => {
             if (!holds(claim))
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(notHeld());
             records.set(keyOf(claim), { state: 'uncertain' });
             return Promise.resolve();
         },

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

@@ -67,7 +67,8 @@ export interface ToolExecutionCoordinator {
     settleNotStarted(operation: ToolOperationIdentity, outcome: ToolOperationOutcome): Promise<void>;
     markUncertain(claim: ToolOperationClaim, reason: ToolOperationUncertainty): Promise<void>;
 }
-export declare function operationUnavailable(): TheoremError;
+/** A coordinator, a page dispatch or the kernel broke the tool-operation contract. */
+export declare function operationBroken(reason: string): TheoremError;
 export declare function toolInvocationHash(value: unknown): Promise<string>;
 export declare const toolOperationOutcomeSchema: z.ZodType<ToolOperationOutcome>;
 export declare function operationWireValue(value: unknown): JsonValue;

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { publicError, TheoremError } from '../../guardrails/error.js';
+import { TheoremError } from '../../guardrails/error.js';
 import { errorKindSchema, guardrailHit, provenance } from '../../guardrails/event-schemas.js';
 import { jsonObjectSchema, jsonValueSchema } from '../json.js';
 import { interactionPartSchema, TURN_EVENT_SCHEMAS, turnHistoryMessageSchema, } from '../turn-events.js';
@@ -7,10 +7,9 @@ export const savedToolInvocationSchema = z.strictObject({
     accepted: jsonObjectSchema,
     preparedInput: jsonValueSchema,
 });
-export function operationUnavailable() {
-    const error = new TheoremError('unavailable', '');
-    error.message = publicError(error);
-    return error;
+/** A coordinator, a page dispatch or the kernel broke the tool-operation contract. */
+export function operationBroken(reason) {
+    return new TheoremError('internal', reason);
 }
 export async function toolInvocationHash(value) {
     const ordered = (item) => {
@@ -78,20 +77,23 @@ export function operationWireValue(value) {
         if (!item || typeof item !== 'object')
             return item;
         if (ancestors.has(item))
-            throw operationUnavailable();
+            throw operationBroken('Tool operation value has a cycle'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         const prototype = Object.getPrototypeOf(item);
         if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null) {
-            throw operationUnavailable();
+            throw operationBroken('Tool operation value holds an object that is not plain data'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (Object.hasOwn(item, '__proto__')) {
+            throw operationBroken('Tool operation value has an own __proto__ key'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
-        if (Object.hasOwn(item, '__proto__'))
-            throw operationUnavailable();
         ancestors.add(item);
         try {
             if (Array.isArray(item))
                 return item.map(normalize);
             const entries = Object.entries(Object.getOwnPropertyDescriptors(item));
-            if (entries.some(([, descriptor]) => descriptor.get || descriptor.set))
-                throw operationUnavailable();
+            const accessor = entries.find(([, descriptor]) => descriptor.get || descriptor.set);
+            if (accessor) {
+                throw operationBroken(`Tool operation value has a getter or setter at '${accessor[0]}'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
             return Object.fromEntries(entries
                 .filter(([, descriptor]) => descriptor.enumerable && descriptor.value !== undefined)
                 .map(([key, descriptor]) => [key, normalize(descriptor.value)]));

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

@@ -382,13 +382,20 @@ async function* remoteAuthAndPreBody(args) {
         ...(authRes.audience ? { audience: authRes.audience } : {}),
     };
 }
+/** A thrown request's code: a kind with a code of its own, else `request_failed`. */
+const THROWN_CODES = {
+    network: 'network_error',
+    cancelled: 'cancelled',
+    timeout: 'timeout',
+};
 function* thrownOutcome(err, checks) {
     if (errorKind(err) === 'blocked') {
         const blocked = networkBlockedEvent();
         checks.record(blocked);
         return failureOutcome(yield* networkBlocked(err, blocked), false);
     }
-    return failureOutcome({ code: 'network_error', kind: 'network', message: messageOf(err) }, false);
+    const kind = errorKind(err);
+    return failureOutcome({ code: THROWN_CODES[kind] ?? 'request_failed', kind, message: messageOf(err) }, false);
 }
 const OMIT_CREDENTIAL = '[omitted - credential]';
 /** The most of an error or unparseable body quoted back in a failure message. */

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': {

package/esm/src/providers/shared/retry.js

@@ -1,5 +1,4 @@
-import { TheoremError } from '../../guardrails/error.js';
-import { networkError } from './upstream-tap.js';
+import { networkError, TheoremError } from '../../guardrails/error.js';
 const BACKOFF_MS = [1000, 2000, 4000, 8000];
 /** All the waiting one call may do between tries; a wait that would pass it sends the last answer back. */
 export const WAIT_BUDGET_MS = 5000;

package/esm/src/providers/shared/upstream-tap.d.ts

@@ -3,6 +3,4 @@ export declare function tapeHeaderValue(key: string, value: string): string;
 export declare function tapeHeaders(headers?: HeadersInit): Record<string, string>;
 export declare function throwRow(err: unknown): Record<string, unknown>;
 export declare function tapFetch(tap: ModelRequest['tapUpstream'], send?: typeof fetch, keySlot?: KeySlot): typeof fetch;
-/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
-export declare function networkError(err: unknown): unknown;
 export declare function networkFetch(send?: typeof fetch): typeof fetch;

package/esm/src/providers/shared/upstream-tap.js

@@ -1,4 +1,4 @@
-import { describeError, isAbortError, isTimeoutError, TheoremError, } from '../../guardrails/error.js';
+import { sendOrNetworkError } from '../../guardrails/error.js';
 const SECRET_HEADER = /key|auth|cookie|secret|token/i;
 export function tapeHeaderValue(key, value) {
     if (SECRET_HEADER.test(key)) {
@@ -66,20 +66,6 @@ export function tapFetch(tap, send = fetch, keySlot) {
         }
     };
 }
-/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
-export function networkError(err) {
-    if (err instanceof TheoremError || isAbortError(err) || isTimeoutError(err)) {
-        return err;
-    }
-    return new TheoremError('network', describeError(err), { cause: err });
-}
 export function networkFetch(send = fetch) {
-    return async (url, init) => {
-        try {
-            return await send(url, init);
-        }
-        catch (err) {
-            throw networkError(err);
-        }
-    };
+    return (url, init) => sendOrNetworkError(send, url, init);
 }

package/package.json

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