@animalabs/agent-framework 0.24.0 → 0.25.0

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-guard.ts

@@ -86,10 +86,11 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
 /**
  * What a withheld result's stub keeps of it: the fields of its data that its
  * tool marked as saying what it acted on (ToolResult.keepWhenWithheld), in
- * the order marked, serialized as a stored result is. Past the inline cap
- * 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
+ * the order marked, serialized as a stored result is. Past `maxChars`, the
+ * 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
  * 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.
  */
@@ -109,7 +110,7 @@ export function keptWhenWithheld(result: CompletedToolCall['result'], maxChars:
   // Never half a surrogate pair: the stub goes to the provider as text, so
   // the cut can be one character short of the cap.
   const head = safeSlice(whole, 0, maxChars);
-  return `${head} [cut at the inline cap: ${head.length} of these fields' ${whole.length} ` +
+  return `${head} [cut: ${head.length} of these fields' ${whole.length} ` +
     'characters; the whole result is where this note says]';
 }
 
@@ -313,15 +314,16 @@ export class ToolResultGuard {
       : JSON.parse(json);
   }
 
-  /** `inlineCap` is the cap the caller stored `content` under; what a stub
-   *  keeps of a withheld result is cut at it too. */
+  /** `keptCap` is where what a stub keeps of a withheld result is cut: the
+   *  cap the caller stored `content` under, less the stub's notice room where
+   *  its message's bound sets it (toolResultShare, tool-image-ledger.ts). */
   storeResults(
     content: ContentBlock[],
     wireResults: ToolResult[],
     originals: CompletedToolCall[],
     metadata: MessageMetadata | undefined,
-    /** The cap the results were stored under: what a stub keeps is cut there too. */
-    inlineCap: number | undefined,
+    /** Where what a stub keeps is cut. */
+    keptCap: number | undefined,
   ): MessageId {
     if (!this.enabled) return this.cm.addMessage('user', content, metadata);
     if (this.pending) {
@@ -355,7 +357,7 @@ export class ToolResultGuard {
     const kept = new Map<number, string>();
     for (const [index, block] of content.entries()) {
       const result = block.type === 'tool_result' ? results.get(block.toolUseId) : undefined;
-      const text = result ? keptWhenWithheld(result, inlineCap) : undefined;
+      const text = result ? keptWhenWithheld(result, keptCap) : undefined;
       if (text !== undefined) kept.set(index, text);
     }
     // Compression hold (CM >= 0.12): placed BEFORE onNewMessage fires, so no

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,13 +115,17 @@ 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);
 }
 
 /** Bounded copy of an arbitrary string with the standard truncation notice,
- *  cut at the cap as a tool result's stored copy is (toolResultCutAt), so it
+ *  cut at the cap where a tool result's stored copy is cut at that cap
+ *  (toolResultCutAt), so it
  *  never ends in part of a slot. Each of its callers' readers sees this
  *  very text, never the images behind a placeholder, so nothing past the cut
  *  is kept for save_recent_image's index (#403). The framework stores a tool
@@ -127,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/tune-out/coordinator.ts

@@ -290,9 +290,9 @@ export class TuneOutCoordinator {
       startedAtSequence: this.hooks.currentSequence(),
       ...(expiresAtMs !== undefined ? { expiresAtMs } : {}),
     };
-    // A tune-out can end in the registry without cancel (a send into the
-    // channel or a close sets its state there), leaving its timers armed:
-    // clear them, so none of them acts on this one.
+    // A tune-out that ended in the registry without this coordinator's
+    // cancel would have left its timers armed: clear them, so none of them
+    // acts on this one.
     this.clearTimers(serverId, channelId);
     this.channelRegistry.enterTuneOut(serverId, channelId, params, source);
     this.armExpiry(serverId, channelId, params);

package/src/types/agent.ts

@@ -218,6 +218,34 @@ export interface AgentConfig {
    * content-free system receipt is stored instead. Default false.
    */
   toolWrapperProseGuard?: boolean;
+
+  /**
+   * Clock rows (off when left out): when a boundary of this interval on the
+   * agent's local wall clock (counted from local midnight, in the
+   * framework's `timeZone`) has passed since the last clock row, the window
+   * takes one more — `Clock: 10:50 Europe/Berlin (UTC+02:00)`, with the date
+   * when the day has changed — before the next thing it takes: an incoming
+   * event, a turn's start, or, mid-turn, after a tool round's results, where
+   * it also joins the live stream. Only the latest boundary is written, and
+   * a window that holds no clock row yet takes one at the next of these. A
+   * clock reads the boundary's time where its tick would have stood, else
+   * the time it is written (after a tool's results, say), so it never
+   * reads earlier than a row before it. A clock wakes no one. See
+   * src/clock-rows.ts.
+   *
+   * - A stream that can't carry injected messages (membrane's XML prefill
+   *   path) takes no mid-turn clock: the next event or turn start writes it.
+   * - On some models a clock after a tool's results drops the loop's
+   *   earlier thinking from the request, as any message heard while acting
+   *   does there: at most once an interval.
+   * - Residents share one window, so every resident reads the clock rows any
+   *   of them writes, a resident with no `clock` of its own included. Each
+   *   writes one when a boundary of its own interval has passed since the
+   *   window's last clock, whichever resident wrote that. The subconscious
+   *   takes none of its own: it reads the residents' through its merged
+   *   view.
+   */
+  clock?: import('../clock-rows.js').ClockConfig;
 }
 
 /** The intentionally small set of agent settings that may change in-process. */

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,9 +276,13 @@ 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. For a call from a running
+   * 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,
+   * or a save_recent_image in the round counted it by its share: then each
+   * result of the round takes an equal share of that bound, and one past its
+   * share spills. For a call from a running
    * code_execution script it is the longest result that reaches the script
    * whole whatever its characters, from the script's memory: the script
    * takes an answer of up to a third of its memoryMaxBytes, in which a

package/src/types/framework.ts

@@ -117,9 +117,10 @@ export interface FrameworkConfig {
   subconscious?: import('../tune-out/tools.js').SubconsciousConfig;
 
   /**
-   * IANA zone used only when rendering wall-clock times for the agent.
-   * Stored/protocol timestamps remain epoch/UTC. Defaults to AGENT_TIMEZONE,
-   * then the process zone.
+   * IANA zone of the agent's wall clock: it renders wall-clock times for the
+   * agent, and it sets where clock rows' boundaries fall (AgentConfig.clock,
+   * counted from local midnight here). Stored/protocol timestamps remain
+   * epoch/UTC. Defaults to AGENT_TIMEZONE, then the process zone.
    */
   timeZone?: string;
 
@@ -247,7 +248,9 @@ export interface FrameworkConfig {
    * takes precedence over this for that agent; the EFFECTIVE cap for every
    * source is min(desired, strategy bound) — desired values above the
    * strategy-derived bound (maxMessageTokens * 4) are hard-clamped to it,
-   * with the clamp reported via agent_settings get.
+   * with the clamp reported via agent_settings get. For an ordinary resident
+   * the bound is the smallest among the agents that read the shared slot,
+   * reported as clamped by `reader-bound` when another reader's sets it.
    */
   toolResultInlineMaxChars?: number;