@animalabs/agent-framework 0.26.2 → 0.28.0

package/src/tool-result-guard.ts

@@ -4,10 +4,19 @@ import type { ContextManager, MessageId, MessageMetadata } from '@animalabs/cont
 import type { ContentBlock, NormalizedMessage, ToolResult } from '@animalabs/membrane';
 import type { CompletedToolCall } from './types/index.js';
 import { ensureStateRegistered } from './module-registry.js';
-import { rfc005TextOf, toolResultDataToHistoryString } from './tool-result-history.js';
+import { classifyBlock } from './mcpl/references.js';
+import { resultClaimsOf, rfc005TextOf, toolResultDataToHistoryString } from './tool-result-history.js';
 import { safeSlice } from './safe-slice.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
+export type WithheldNoticeKind = 'ran' | 'refused' | 'error';
+const GUARD_NOTICES: Record<WithheldNoticeKind, string> = {
+  ran: TOOL_RESULT_GUARD_NOTICE,
+  refused: "Tool result withheld by the guard. The tool didn't run.",
+  error: "Tool result withheld by the guard. The call returned an error, and this notice can't say whether the tool ran.",
+};
+const noticeKind = (result: CompletedToolCall['result'] | undefined): WithheldNoticeKind =>
+  result?.refused === true ? 'refused' : result?.isError === true ? 'error' : 'ran';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
 /** Where a withheld result's original went: a workspace path; the path a
@@ -53,9 +62,12 @@ export interface WithheldHost {
 }
 
 /**
- * The stub a withheld result settles to: #159's neutral notice, then where
- * the original is, then, when its tool marked any, the fields kept from its
- * result (`kept`, from keptWhenWithheld). It names no refusal and no
+ * The stub a withheld result settles to: #159's neutral notice for its
+ * `kind` (a result that isn't an error, a refused call's, or another error's),
+ * then where the original is, then, for an error whose original is in a file
+ * known written, a line telling the agent to read it, then, when its tool
+ * marked any, the fields kept from its result (`kept`, from
+ * keptWhenWithheld). It names no refusal and no
  * category (#159 keeps those in operational logs), so reading the rest back
  * is the agent's deliberate choice (agent-framework #277). The place holds
  * the result as stored, which for one over the inline cap is its capped
@@ -66,7 +78,7 @@ export interface WithheldHost {
  * save failed is still queued in memory, and a restart before its retry
  * loses it.
  */
-export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string): string {
+export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string, kind: WithheldNoticeKind = 'ran'): string {
   const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
   const keptIn = (only: string) => auditDurable
     ? `is kept ${only}in ${audit}`
@@ -79,8 +91,10 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
       : spill.error === undefined
         ? `Its result is in workspace file ${spill.path}.`
         : `Writing its result to workspace file ${spill.path} failed, so it ${keptIn('only ')}.`;
+  const readable = kind === 'error' && !!spill && 'path' in spill && spill.error === undefined && !spill.unfinished;
+  const readFirst = readable ? ' Read it before calling again.' : '';
   const fields = kept === undefined ? '' : ` Kept from its result: ${kept}`;
-  return `${TOOL_RESULT_GUARD_NOTICE} ${place}${fields}`;
+  return `${GUARD_NOTICES[kind]} ${place}${readFirst}${fields}`;
 }
 
 /**
@@ -90,7 +104,9 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
  * inline cap or less (storeResults' keptCap), they're cut, with a note that
  * says so and where the whole result is, since a later field can then be cut
  * away entirely. Undefined when it keeps nothing, as for a failed result
- * (agent-framework #277). A write's file
+ * (agent-framework #277), one whose claims can't be read whole
+ * (resultClaimsOf), or one whose data is MCP's embedded resource, whose
+ * fields can't be kept apart from its contents or its uri. A write's file
  * list is evidence of what it did, rarely what drew a refusal, and keeping it
  * is what shows a clobbered file when the receipt is withheld.
  */
@@ -99,13 +115,23 @@ export function keptWhenWithheld(result: CompletedToolCall['result'], maxChars:
   if (!result.success || result.isError || !keys?.length || !data || typeof data !== 'object' || Array.isArray(data)) {
     return undefined;
   }
+  // MCP's embedded resource is its contents: shown as text, it's the very
+  // body the guard withheld, and a field picked out of it, such as
+  // `resource`, is data that shows its uri. So it keeps nothing.
+  if (classifyBlock(data).kind === 'embedded') return undefined;
   const fields = data as Record<string, unknown>;
   const kept = Object.fromEntries(keys.filter((key) => Object.hasOwn(fields, key)).map((key) => [key, fields[key]]));
   if (Object.keys(kept).length === 0) return undefined;
   // Data that RFC-005 shows as text, such as a reference's stub, keeps that
   // text: picked out of it, a kept uri would lose the type that makes it a
   // reference, and be written out of the stub that hides it.
-  const whole = rfc005TextOf(fields) ?? toolResultDataToHistoryString(kept);
+  // The kept fields are shown as the whole result claims (resultClaimsOf), so
+  // a never elsewhere in it still withholds a kept link's uri. Where a value
+  // stops that walk, such as a getter that throws, which the audit's JSON
+  // doesn't read, what the rest claims is unknown, and nothing is kept.
+  const claims = resultClaimsOf(fields);
+  if (claims === null) return undefined;
+  const whole = rfc005TextOf(fields) ?? toolResultDataToHistoryString(kept, undefined, { claims });
   if (!maxChars || whole.length <= maxChars) return whole;
   // Never half a surrogate pair: the stub goes to the provider as text, so
   // the cut can be one character short of the cap.
@@ -127,6 +153,7 @@ interface PendingBatch {
   /** What each result's stub keeps if the batch is withheld, by its index in
    *  content: the fields its tool marked (keptWhenWithheld). */
   kept: Map<number, string>;
+  notices: Map<string, WithheldNoticeKind>;
 }
 
 interface AuditOperation {
@@ -235,7 +262,7 @@ export class ToolResultGuard {
         if (block.type === 'image') images += 1;
         else chars += JSON.stringify(block).length;
       }
-      chars -= TOOL_RESULT_GUARD_NOTICE.length;
+      chars -= GUARD_NOTICES[pending.notices.get(result.toolUseId) ?? 'ran'].length;
     }
     return Math.max(0, Math.ceil(chars / 4) + images * 1600);
   }
@@ -348,12 +375,13 @@ export class ToolResultGuard {
       // with a placeholder if the audit cannot become durable below.
       console.error(`[tool-result-guard] agent=${this.agentName} staged audit write queued:`, error);
     }
+    const results = new Map(originals.map((call) => [call.id, call.result]));
+    const notices = new Map([...results].map(([id, result]) => [id, noticeKind(result)]));
     const withheld: ContentBlock[] = content.map((block) => block.type === 'tool_result'
-      ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError }
+      ? { type: 'tool_result', toolUseId: block.toolUseId, content: GUARD_NOTICES[notices.get(block.toolUseId) ?? 'ran'], isError: block.isError }
       : block);
     // What each stub keeps if the batch is withheld, matched to its tool's
     // result by tool use id, keyed by index as the stubs and files are.
-    const results = new Map(originals.map((call) => [call.id, call.result]));
     const kept = new Map<number, string>();
     for (const [index, block] of content.entries()) {
       const result = block.type === 'tool_result' ? results.get(block.toolUseId) : undefined;
@@ -366,7 +394,7 @@ export class ToolResultGuard {
     // which is correct since a reopened guard has no pending batch.
     const messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
     this.pending = { id, messageId, content, withheld, wireResults,
-      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept };
+      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept, notices };
     // Durability barrier: the audit must reach Chronicle's chain heads before
     // the originals can go to a provider. On a failed sync the batch fails
     // CLOSED: the placeholders go on the wire instead (the turn continues,
@@ -393,7 +421,7 @@ export class ToolResultGuard {
     if (pending.durable) { pending.submitted = true; return results; }
     const ids = new Set(pending.wireResults.map((result) => result.toolUseId));
     return results.map((result) => ids.has(result.toolUseId)
-      ? { ...result, content: TOOL_RESULT_GUARD_NOTICE } : result);
+      ? { ...result, content: GUARD_NOTICES[pending.notices.get(result.toolUseId) ?? 'ran'] } : result);
   }
 
   /** The stream carrying this batch ended without a clean round (abort or
@@ -500,7 +528,7 @@ export class ToolResultGuard {
   /**
    * Turn a withheld batch's notices into stubs that say where each original
    * is (agent-framework #277): written to the workspace when it has a
-   * writable mount without an include to take it, else kept in the audit
+   * writable mount without an include, not configured direct, to take it, else kept in the audit
    * record. A stub also keeps the file
    * lists its tool marked. Its own unedited placeholder is
    * the only thing it edits: an operator's later edit, removal or rollback
@@ -590,7 +618,7 @@ export class ToolResultGuard {
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
-          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index)) }
+          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index), pending.notices.get(block.toolUseId)) }
           : block);
         try {
           this.append({
@@ -599,8 +627,8 @@ export class ToolResultGuard {
               if (block.type !== 'tool_result') return [];
               if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
               const spill = spills.get(index) ?? null;
-              // No file was written: no writable mount without an include,
-              // or the framework was stopping.
+              // No file was written: no writable mount without an include
+              // that isn't configured direct, or the framework was stopping.
               if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
               if ('skipped' in spill) return [{ toolUseId: block.toolUseId, skipped: spill.skipped }];
               return [{ toolUseId: block.toolUseId, path: spill.path,