@animalabs/agent-framework 0.24.1 → 0.25.0

package/src/framework.ts

@@ -157,6 +157,7 @@ import { bounded, renderList, renderReturn, VALUE_CHARS } from './code-execution
 import { splitProseRuns, withoutRoundsProse } from './prose-segments.js';
 import { cumulativeDelta } from './usage-accounting.js';
 import { stampThinkingTokenEstimates } from './thinking-token-stamp.js';
+import { contentAsStored, nameAsStored } from './text-as-stored.js';
 
 /** An MCPL tool call refused because its server isn't in the registry: one
  *  closed for good, one removed, or one whose connect failed without
@@ -929,7 +930,8 @@ function describeDeferredWrite(msg: { id: string; participant: string; content:
 function isInjectableMidTurn(msg: { participant: string; content: ContentBlock[] }, agentName: string): boolean {
   // Exact, as membrane's role test is: only a participant equal to the
   // request's assistantParticipant (Agent's name) renders as the assistant.
-  return msg.participant !== agentName
+  // It's the name as sent, which the boundary takes as the store keeps it.
+  return nameAsStored(msg.participant) !== agentName
     && !msg.content.some((b) => b.type === 'tool_use' || b.type === 'tool_result');
 }
 
@@ -1252,6 +1254,12 @@ function isTurnContinuation(reason: string): boolean {
   return reason === 'context_budget_restart' || reason === 'tool_results_ready'
     || reason === 'tool_result_guard_retry';
 }
+
+/** Wake sources the framework generates for itself (bounce wakes,
+ *  continuations, retries, unsticks, admission requeues). A wake from any
+ *  other source — a channel message, a heartbeat or other server event, a
+ *  gate flush, a timer, an operator nudge — is a cause of its own. */
+const FRAMEWORK_WAKE_SOURCES = new Set(['framework', 'scheduler']);
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
@@ -12145,11 +12153,14 @@ export class AgentFramework {
             // 0.5.x, and from 0.6.0 declares it can't carry them, so none are
             // collected for it. Each goes as its participant and content
             // alone: a stored row's metadata is the host's record, not input
-            // for membrane.
+            // for membrane. Each goes with its name and text as the store
+            // keeps them, whether it's a heard message, rendered or not, or a
+            // notice the boundary made: this is where they leave for the
+            // request.
             currentState.stream.provideToolResults(
               agent.toolResultGuard.submissionResults(membraneResults),
               midTurnInjections.length > 0
-                ? { injectedMessages: midTurnInjections.map(({ participant, content }) => ({ participant, content })) }
+                ? { injectedMessages: midTurnInjections.map(({ participant, content }) => ({ participant: nameAsStored(participant), content: contentAsStored(content) })) }
                 : undefined,
             );
             // RFC-006 §3.3: consumption is determined at assembly, and this
@@ -14458,6 +14469,16 @@ export class AgentFramework {
       // requests[0] in that mixed batch bypassed the turn lock because a
       // restart existed, then treated the continuation as a fresh turn.
       const trigger = budgetRestart ?? requests[0];
+      // The bounce-wake cap (bounceProse) stops a bounce → wake → bounce loop
+      // that nothing else feeds. A turn with a cause of its own is not that
+      // loop, so the count starts again. Otherwise only a delivered prose
+      // envelope reset it, and a resident that recovers from bounces with a
+      // send tool kept the count for good: every later bounce, a reply to a
+      // fresh message included, appended its notice without a wake.
+      // (Optional chaining: prototype-built harnesses leave the map unset.)
+      if (requests.some((r) => !FRAMEWORK_WAKE_SOURCES.has(r.source))) {
+        this.proseBounceStreaks?.delete(agentName);
+      }
       // Route this turn's auto-published speech to the channel that triggered
       // it (item-3 redux). A batched wake may carry several triggering channels
       // (messages arrived in >1 channel while the agent was busy/idle):
@@ -16634,7 +16655,9 @@ export class AgentFramework {
     }
   }
 
-  /** Cap on consecutive bounce-triggered wakes (notices still append after). */
+  /** Cap on consecutive bounce-triggered wakes (notices still append after).
+   *  The count resets on a delivered prose envelope, and when a turn starts
+   *  with a cause of its own (processInferenceRequests). */
   private static readonly PROSE_BOUNCE_WAKE_CAP = 2;
 
   /**
@@ -20631,7 +20654,7 @@ export class AgentFramework {
     tc: CompletedToolCall,
     maxChars: number | undefined,
   ): { text: string; shown: ShownRanges | null } {
-    if (tc.result.isError) return { text: tc.result.error ?? 'Unknown error', shown: null };
+    if (tc.result.isError) return { text: (tc.result.error ?? 'Unknown error').toWellFormed(), shown: null };
     const ledger = this.toolImageLedgerFor(agentName);
     let blocks = null as HistoryBlockSpan[] | null;
     const text = nonErrorResultText(tc.result, undefined, {
@@ -21185,7 +21208,8 @@ export class AgentFramework {
       if (b.type === 'text') {
         // A text that isn't a string shows as the converters' placeholder,
         // rather than sending the whole array to the JSON fallback.
-        let text = typeof b.text === 'string' ? b.text : NON_STRING_TEXT_PLACEHOLDER;
+        // Well formed, as the stored copy's text is (nonErrorResultText).
+        let text = typeof b.text === 'string' ? b.text.toWellFormed() : NON_STRING_TEXT_PLACEHOLDER;
         if (maxChars && text.length > maxChars) {
           text = text.slice(0, toolResultCutAt(text, maxChars))
             + '\n\n[truncated — original was ' + text.length + ' chars'

package/src/mcpl/references.ts

@@ -434,7 +434,10 @@ export function unfetchableReason(record: ReferenceRecord, nowMs = Date.now()):
 /**
  * RFC-005 treatment for one MCPL wire block, for the model-visible text
  * lanes. Returns a replacement string, or null when the block should keep
- * its existing (inline/text) handling.
+ * its existing (inline/text) handling. A reference's stub carries text taken
+ * from the block's own fields, so it's made well formed (a lone UTF-16
+ * surrogate becomes U+FFFD), as the context store would make it: a tool
+ * result's copies then carry the same text (#695).
  */
 export function referenceStubOrNull(block: unknown, provenance?: string, serverId?: string): string | null {
   const c = classifyBlock(block);
@@ -442,7 +445,7 @@ export function referenceStubOrNull(block: unknown, provenance?: string, serverI
     case 'text': return null;
     case 'inline':
       return c.contradiction ? INLINE_WITHHELD_TEXT : null;
-    case 'reference': return buildReferenceStub(c.testimony, provenance, serverId);
+    case 'reference': return buildReferenceStub(c.testimony, provenance, serverId).toWellFormed();
     case 'invalid': return c.shown;
   }
 }

package/src/modules/workspace/index.ts

@@ -1851,11 +1851,12 @@ export class WorkspaceModule implements Module {
       },
       {
         name: 'glob',
-        description: 'Find files matching a glob pattern, checked against disk first; each match carries its state, as ls describes.' + globDirect,
+        description: 'Find files matching a glob pattern, checked against disk first; each match carries its state, as ls describes. '
+          + 'The pattern is relative to path (or to each mount\'s root). In the mount its first segment names, it is read mount-prefixed instead, like the paths it returns, within path if one is given; in every other mount, as written.' + globDirect,
         inputSchema: {
           type: 'object' as const,
           properties: {
-            pattern: { type: 'string', description: 'Glob pattern (e.g., "**/*.ts")' },
+            pattern: { type: 'string', description: 'Glob pattern, relative (e.g., "**/*.ts") or mount-prefixed (e.g., "project/src/**/*.ts")' },
             path: { type: 'string', description: 'Directory to search in (mount-prefixed, optional)' },
           },
           required: ['pattern'],
@@ -1873,7 +1874,7 @@ export class WorkspaceModule implements Module {
           properties: {
             pattern: { type: 'string', description: 'Regular expression pattern' },
             path: { type: 'string', description: 'File or directory to search (mount-prefixed, optional)' },
-            glob: { type: 'string', description: 'Glob pattern to filter files' },
+            glob: { type: 'string', description: 'Glob pattern to filter files, relative to the mount root (e.g., "src/**/*.ts"); in the mount its first segment names, read mount-prefixed (e.g., "project/src/**/*.ts"), and in every other mount, as written' },
             contextBefore: { type: 'integer', description: 'Context lines before match' },
             contextAfter: { type: 'integer', description: 'Context lines after match' },
           },
@@ -4616,11 +4617,23 @@ export class WorkspaceModule implements Module {
 
     // Every match lies beneath the pattern's literal directory, so the walk
     // starts there: past the walk's cap, a walk of the whole scope can stop
-    // before it gets there.
+    // before it gets there. In the mount a pattern's first segment names, the
+    // pattern is read mount-prefixed (prefixedGlob), from its rest's directory
+    // within `path`.
     const patternDir = literalDirOf(input.pattern);
     for (const { mount, relativePath } of mountsToSearch) {
-      const start = await this.walkStart(mount, relativePath, patternDir);
-      const matched = (path: string) => regex.test(relativePath ? path.slice(relativePath.length + 1) : path);
+      const prefixed = prefixedGlob(input.pattern, mount.config.name);
+      let start: string;
+      let matched: (path: string) => boolean;
+      if (prefixed) {
+        const dir = deeperOf(relativePath, prefixed.dir);
+        if (dir === null) continue;
+        start = await this.walkStart(mount, relativePath, dir === relativePath ? '' : dir.slice(relativePath ? relativePath.length + 1 : 0));
+        matched = (path: string) => prefixed.regex.test(path);
+      } else {
+        start = await this.walkStart(mount, relativePath, patternDir);
+        matched = (path: string) => regex.test(relativePath ? path.slice(relativePath.length + 1) : path);
+      }
       const listing = await this.listingOf(mount, start, true, matched);
       for (const { path, ...view } of listing.files) matches.push({ path: `${mount.config.name}/${path}`, ...view });
       for (const region of listing.incomplete) {
@@ -4651,7 +4664,8 @@ export class WorkspaceModule implements Module {
     const fileGlob = input.glob ? globToRegex(input.glob) : null;
     // The filter matches mount-relative paths, so every file it lets through
     // lies beneath its literal directory, and the walk starts at the deeper of
-    // that and `path`.
+    // that and `path`. In the mount a filter's first segment names, its
+    // mount-prefixed reading takes the filter's place (below).
     const filterDir = input.glob ? literalDirOf(input.glob) : '';
     const contextBefore = input.contextBefore ?? 0;
     const contextAfter = input.contextAfter ?? 0;
@@ -4699,16 +4713,21 @@ export class WorkspaceModule implements Module {
         incomplete.push({ path: `${mount.config.name}/${relativePath}`, reason: this.otherMountNote(mount.config.name, relativePath, 'list', moved) });
         continue;
       }
-      // A `path` and a filter whose directories don't overlap leave no file
-      // the filter can let through, so nothing is searched.
-      const deeper = deeperOf(relativePath, filterDir);
+      // In the mount a filter's first segment names, the filter is read
+      // mount-prefixed (prefixedGlob), from its rest's directory. A `path` and
+      // a filter whose directories don't overlap leave no file the filter can
+      // let through, so nothing is searched.
+      const prefixed = input.glob ? prefixedGlob(input.glob, mount.config.name) : null;
+      const deeper = deeperOf(relativePath, prefixed ? prefixed.dir : filterDir);
       if (deeper === null) continue;
       const start = await this.walkStart(mount, relativePath, deeper === relativePath ? '' : deeper.slice(relativePath ? relativePath.length + 1 : 0));
       const searched = (text: GrepText): void => {
         const matches = search(text.text);
         if (matches.length > 0) results.push({ file: text.file, ...(text.state !== undefined ? { state: text.state } : {}), version: text.version, matches });
       };
-      const kept = (path: string): boolean => fileGlob === null || fileGlob.test(path);
+      const kept = prefixed
+        ? (path: string): boolean => prefixed.regex.test(path)
+        : (path: string): boolean => fileGlob === null || fileGlob.test(path);
       const found = mount.direct
         ? await this.textsFromDisk(mount, relativePath, root, start, kept, searched)
         : await this.textsFromStore(mount, relativePath, start, kept, searched);
@@ -5920,6 +5939,28 @@ function inputProblem(
   return null;
 }
 
+/**
+ * A glob's reading in the mount its first segment names, in place of the
+ * pattern as written there. Every path the tools take and return is
+ * mount-prefixed, so `notes/diary/*.md` is the natural way to write a
+ * pattern, and tested as written against a mount-relative path it could
+ * never match — a glob answered "no matches" for files that were there.
+ * `regex` matches the rest of the pattern against the mount-relative path,
+ * and `dir` is the rest's literal directory (literalDirOf), from the mount's
+ * root. A pattern that names another mount, or none, has no such reading
+ * (null), and is read as written, relative to the search root. So in a mount
+ * holding a directory named like itself, `work/z/*.ts` names the mount's own
+ * `z`, and `work/work/z/*.ts`, as the tools show it, names the directory's.
+ * The rest's brace groups are the pattern's, so a pattern globToRegex took
+ * doesn't throw here.
+ */
+function prefixedGlob(pattern: string, mountName: string): { regex: RegExp; dir: string } | null {
+  const slash = pattern.indexOf('/');
+  if (slash <= 0 || pattern.slice(0, slash) !== mountName) return null;
+  const rest = pattern.slice(slash + 1);
+  return { regex: globToRegex(rest), dir: literalDirOf(rest) };
+}
+
 /**
  * Convert a glob pattern to a RegExp. Throws, naming the pattern, for a brace
  * group it can't read: a "{" that never closes, a group inside another, or a
@@ -5954,9 +5995,14 @@ function globToRegex(pattern: string): RegExp {
       if (!group.includes(',')) {
         throw new Error(braceRefusal(pattern, 'has a "{" group with no ","; a group needs two or more alternatives, separated by ","'));
       }
-      const alternatives = group.split(',');
-      regex += '(?:' + alternatives.map(a => globPartToRegex(a)).join('|') + ')';
-      i = closeIdx + 1;
+      // A `/` right after the group goes into each alternative, as `{a,b}/x`
+      // and `{a/,b/}x` name the same paths, so an alternative's own `**`
+      // meets it and reads as a `**/` does, as in the group's expansion:
+      // `{src/**,lib}/*.ts` is `src/**/*.ts` or `lib/*.ts`.
+      const slash = pattern[closeIdx + 1] === '/';
+      const alternatives = group.split(',').map((alternative) => (slash ? alternative + '/' : alternative));
+      regex += '(?:' + alternatives.map(globPartToRegex).join('|') + ')';
+      i = closeIdx + (slash ? 2 : 1);
       continue;
     }
     // Accumulate non-brace characters, convert as a chunk
@@ -6002,11 +6048,19 @@ function braceRefusal(pattern: string, problem: string): string {
   return `glob pattern ${JSON.stringify(pattern)} ${problem}. To match a "{" in a name, put "?" in its place.`;
 }
 
+// What each glob token becomes. A `**/` at the start of a path segment matches
+// zero or more whole directories, so `src/**/*.ts` also matches `src/main.ts`;
+// any other `**` matches any run of characters.
+const GLOB_TOKENS: Record<string, string> = { '**/': '(?:.*/)?', '**': '.*', '*': '[^/]*', '?': '[^/]' };
+
+// One part of a pattern, between brace groups or inside one. Whether a `**/`
+// at its start starts a path segment depends on what comes before it in the
+// path, which after a brace group is whichever alternative matched: so it
+// reads as GLOB_TOKENS' `**/` where the path so far is empty or ends with a
+// `/`, as in `{src/,lib/}**/`, and otherwise as any run of characters and
+// then a directory, as in `draft{s,ing}**/`.
+const PART_START_GLOBSTAR = '(?:(?<=^|/)(?:.*/)?|(?<!^|/).*/)';
 function globPartToRegex(part: string): string {
-  return part
-    .replace(/[.+^$()|[\]\\]/g, '\\$&')
-    .replace(/\*\*/g, '__DOUBLESTAR__')
-    .replace(/\*/g, '[^/]*')
-    .replace(/__DOUBLESTAR__/g, '.*')
-    .replace(/\?/g, '[^/]');
+  return part.replace(/(?<=^|\/)\*\*\/|\*\*|[*?]|[.+^$()|[\]\\]/g, (m, offset: number) =>
+    m === '**/' && offset === 0 ? PART_START_GLOBSTAR : GLOB_TOKENS[m] ?? `\\${m}`);
 }

package/src/modules/workspace/types.ts

@@ -259,8 +259,12 @@ export interface MountConfig {
    * `glob`, `grep`) take up to it from their scope's start every time:
    * `glob`'s is the directory its pattern's segments before the first
    * wildcard name beneath its `path`, and `grep`'s the deeper of its `path`
-   * and its `glob` filter's directory, as far as disk lists each segment
-   * with that spelling as a directory, not a link. Each directory's listing
+   * and its `glob` filter's directory. For a pattern or filter whose first
+   * segment names the mount, either tool starts at the deeper of its `path`
+   * and the directory the rest names from the mount's root, and walks
+   * nothing where neither holds the other. Either way, the walk descends as
+   * far as disk lists each segment with that spelling as a directory, not a
+   * link. Each directory's listing
    * is read whole, so a deletion is seen wherever the walk lists, whatever
    * it took.
    *

package/src/text-as-stored.ts

@@ -0,0 +1,73 @@
+/**
+ * A request carries only text the context store would keep. Apart from the
+ * agent's own configuration, such as its name and system prompt, what a
+ * request compiles comes from the store, which writes a lone UTF-16
+ * surrogate as U+FFFD, and a provider refuses a request carrying one (#695).
+ * Two things reach a request without the store, and each is made well formed
+ * where it leaves for it: context injections, as an Agent compiles them into
+ * a request, and the copies a tool boundary injects into the live round, as
+ * they go to the stream.
+ */
+
+import type { ContentBlock } from '@animalabs/membrane';
+import type { ContextInjection } from '@animalabs/context-manager';
+
+/** A value with every string in it as the context store keeps it, through
+ *  arrays and plain objects. Keys, and objects that aren't plain, pass as
+ *  they are: content blocks are plain JSON data. Whatever is already well
+ *  formed keeps its identity. */
+function stringsAsStored<T>(value: T): T {
+  if (typeof value === 'string') return (value.isWellFormed() ? value : value.toWellFormed()) as T;
+  if (Array.isArray(value)) {
+    const out = value.map(stringsAsStored);
+    return (out.every((v, i) => v === value[i]) ? value : out) as T;
+  }
+  if (value !== null && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return value;
+    let changed = false;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      const s = stringsAsStored(v);
+      if (s !== v) changed = true;
+      out[k] = s;
+    }
+    return (changed ? out : value) as T;
+  }
+  return value;
+}
+
+/** Content with every string in it well formed, as the context store keeps
+ *  a text block's text or an image's link. */
+export function contentAsStored(content: ContentBlock[]): ContentBlock[] {
+  return stringsAsStored(content);
+}
+
+/** A sender's name as the context store keeps it, and as a tool boundary
+ *  sends it: a lone UTF-16 surrogate becomes U+FFFD. A name that isn't a
+ *  string, from an untyped module, passes as it did: thrown here, inside the
+ *  boundary, it would keep the round's results from the stream, where it
+ *  would otherwise fail at the next compile. */
+export function nameAsStored(participant: string): string {
+  return typeof participant === 'string' ? participant.toWellFormed() : participant;
+}
+
+/** Injections with their text as the context store would keep it: each one's
+ *  content, and its namespace, which context-manager writes into a beforeUser
+ *  or afterUser injection's participant name by its text form. A namespace
+ *  that isn't a string, which MCPL §10.4 doesn't allow but the hook
+ *  orchestrator keeps when it can be read as text, is taken by that form.
+ *  They're scoped to a conversation before this, by the namespace as given,
+ *  since channel ids are compared as given. One that's already well formed
+ *  keeps its identity. */
+export function injectionsAsStored(injections: ContextInjection[] | undefined): ContextInjection[] | undefined {
+  return injections?.map((inj) => {
+    const ns: unknown = inj.namespace;
+    const named = typeof ns === 'string' || ns === undefined || ns === null ? ns : String(ns);
+    const namespace = typeof named === 'string' && !named.isWellFormed() ? named.toWellFormed() : ns;
+    const content = contentAsStored(inj.content);
+    return namespace === ns && content.every((b, i) => b === inj.content[i])
+      ? inj
+      : { ...inj, namespace: namespace as string, content };
+  });
+}

package/src/tool-presentation.ts

@@ -85,7 +85,8 @@ function quotedList(names: string[], conjunction: 'and' | 'or' = 'and', quote: (
 
 /**
  * Every problem that keeps a document from being used, each by where it is;
- * none for a usable one. A defaults file (`descriptionsOnly`) may set
+ * none for a usable one. An object with no keys never reaches this:
+ * parseDocument() reads it as the empty document first. A defaults file (`descriptionsOnly`) may set
  * descriptions only, since visibility is the resident's to choose.
  */
 function documentProblems(doc: unknown, descriptionsOnly: boolean): string[] {
@@ -125,6 +126,12 @@ function parseDocument(raw: string, descriptionsOnly: boolean): PresentationDocu
   let doc: unknown;
   try { doc = JSON.parse(raw); }
   catch (error) { throw new PresentationFileError([`it isn't valid JSON: ${errorMessage(error)}`]); }
+  // An object with no keys carries no settings, so it's the empty document,
+  // as a missing resident file is: it's what an operator writes by hand to
+  // start one. A missing defaults file is still reported, by read().
+  // A 0-byte file isn't JSON and still refuses, since the store's
+  // temp-and-rename never writes one: that's what a lost file looks like.
+  if (doc && typeof doc === 'object' && !Array.isArray(doc) && Object.keys(doc).length === 0) return { version: 1, tools: {} };
   const problems = documentProblems(doc, descriptionsOnly);
   if (problems.length) throw new PresentationFileError(problems);
   return doc as PresentationDocument;

package/src/tool-result-history.ts

@@ -9,12 +9,14 @@
  * `maxChars` slice and re-introduces, one turn deferred, exactly the silent
  * hallucination this feature exists to kill.
  *
- * For MCP-shaped content arrays, this helper keeps text blocks verbatim and
+ * For MCP-shaped content arrays, this helper keeps text blocks verbatim,
+ * apart from a lone UTF-16 surrogate, which becomes U+FFFD (#695), and
  * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
- * For anything else it falls back to JSON, written by RFC-005's rules at
- * every depth (historyJson): a reference is shown as its stub wherever it
- * sits in the data, so its uri never reaches history, and inline data that
- * claims a uri or a disposition is withheld.
+ * A string is already text and is kept as it is. For anything else it falls
+ * back to JSON, written by RFC-005's rules at every depth (historyJson): a
+ * reference is shown as its stub wherever it sits in the data, so its uri
+ * never reaches history, and inline data that claims a uri or a disposition
+ * is withheld.
  */
 
 import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './mcpl/references.js';
@@ -72,9 +74,19 @@ export function toolResultDataToHistoryString(
   options?: HistorySerializeOptions,
 ): string {
   const fromArray = tryHistoryStringFromContentArray(data, options);
+  // A string is the text the tool means to say, kept as it is: JSON would
+  // quote it and escape every newline, so a multi-line result would reach
+  // the model, a script and its spill file as one escaped line. Kept well
+  // formed: a lone UTF-16 surrogate, which JSON escaped, isn't text, a
+  // provider can refuse a request that carries one, and UTF-8 can't store
+  // it in a spill file, so it reads as U+FFFD.
   // JSON leaves out undefined, a function and a symbol: a result with no data
   // is stored as no text, as an empty content array is.
-  const str = fromArray ?? historyJson(data) ?? '';
+  // RFC-005 shows only objects otherwise (shownInHistory), so a string has
+  // nothing for historyJson to stub or withhold.
+  const str = fromArray
+    ?? (typeof data === 'string' ? data.toWellFormed() : historyJson(data))
+    ?? '';
   return maxChars ? truncateForHistory(str, maxChars) : str;
 }
 
@@ -86,6 +98,14 @@ export function toolResultDataToHistoryString(
  *
  * Each field is read once: the direct Agent API passes its caller's own
  * result here, unchecked, and a getter needn't answer the same way twice.
+ *
+ * Each text a tool result's copies carry is made well formed where it's
+ * taken from the result: a lone UTF-16 surrogate becomes U+FFFD, as the
+ * context store makes it when it writes, so the copy sent to membrane and the
+ * copy stored carry the same text (#695). Other data goes through JSON,
+ * which escapes a lone half. toWellFormed() keeps the length,
+ * so the cut, the spans and the slots are computed from the well-formed text
+ * as before; a cut at a lone high half no longer steps back over it.
  */
 export function nonErrorResultText(
   result: { data?: unknown; error?: string },
@@ -95,7 +115,10 @@ export function nonErrorResultText(
   const data = result.data;
   if (data === undefined || data === null) {
     const error = result.error;
-    if (typeof error === 'string' && error) return maxChars ? truncateForHistory(error, maxChars) : error;
+    if (typeof error === 'string' && error) {
+      const text = error.toWellFormed();
+      return maxChars ? truncateForHistory(text, maxChars) : text;
+    }
   }
   return toolResultDataToHistoryString(data, maxChars, options);
 }
@@ -128,7 +151,9 @@ function tryHistoryStringFromContentArray(data: unknown, options?: HistorySerial
     if (b.type === 'text') {
       // A text that isn't a string shows as the converters' placeholder,
       // rather than sending the whole array to the JSON fallback.
-      parts.push({ kind: 'text', text: typeof b.text === 'string' ? b.text : NON_STRING_TEXT_PLACEHOLDER });
+      // Read once: a direct Agent API result is unchecked.
+      const text = b.text;
+      parts.push({ kind: 'text', text: typeof text === 'string' ? text.toWellFormed() : NON_STRING_TEXT_PLACEHOLDER });
     } else if (isInlineContradiction(b)) {
       // RFC-005 vector 2: checked before the data branch so inline data
       // claiming bulk disposition is withheld, not rendered.

package/src/types/events.ts

@@ -186,7 +186,13 @@ export interface ModuleEvent {
 export interface ToolResult {
   /** Whether the tool succeeded */
   success: boolean;
-  /** Result data (if success) */
+  /**
+   * Result data (if success). The model reads a string as that text, an MCP
+   * content array whose every block the framework knows as those blocks, and
+   * anything else as JSON, where RFC-005 shows a reference as its stub and
+   * withholds inline data that claims a uri or a disposition. With no data,
+   * it reads the result's error text, if any.
+   */
   data?: unknown;
   /** Error message (if failure) */
   error?: string;
@@ -270,7 +276,7 @@ export interface ToolCall {
   /**
    * How long this call's result may be and still reach its caller whole,
    * measured as the framework stores it: an error's text, or a success's data
-   * as JSON (a content array as its text). For a model's call it is the
+   * as JSON (a string or a content array as its text). For a model's call it is the
    * agent's inline cap, past which the framework spills the result to a
    * workspace file and sends a preview. A result that long is stored whole
    * unless its round's results together pass the readers' per-message bound,