@theoremjs/agents 0.3.4-next.522.g9e684cd → 0.3.4-next.524.g5000023

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/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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.522.g9e684cd",
+  "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",