@animalabs/agent-framework 0.23.3 → 0.24.1

package/src/tool-result-guard.ts

@@ -18,7 +18,7 @@ export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
  *  left the stub's branch when the file would have been committed
  *  (`branch_changed`), or because the batch used its deadline before this
  *  write could start (`batch_deadline`); or null when no file is written at all (no writable
- *  workspace, or the host is stopping). */
+ *  mount without an include, or the host is stopping). */
 export type WithheldSpill =
   | { path: string; error?: string; unfinished?: true }
   | { skipped: 'workspace_unanswered' | 'branch_changed' | 'batch_deadline' }
@@ -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
@@ -497,8 +499,9 @@ 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 a writable mount
-   * takes it, else kept in the audit record. A stub also keeps the file
+   * 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
+   * 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
    * stands.
@@ -596,8 +599,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 workspace, or the framework
-              // was stopping.
+              // No file was written: no writable mount without an include,
+              // 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,

package/src/tool-result-history.ts

@@ -49,7 +49,7 @@ export interface HistorySerializeOptions {
 
 /**
  * House-safe default inline cap (chars) for tool results, error results, and
- * background-script wake payloads (issue #89: a resident should never eat a
+ * script wake payloads (issue #89: a resident should never eat a
  * 42k blob they didn't ask for). Durable per-residence value comes from
  * `FrameworkConfig.toolResultInlineMaxChars`; a per-agent value from
  * agent_settings `tool_result_inline_max_chars`.
@@ -101,7 +101,8 @@ export function nonErrorResultText(
 }
 
 /** 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

package/src/tune-out/coordinator.ts

@@ -37,6 +37,37 @@ const WAKE_COALESCE_MS = 2_000;
 /** How long after an end time whose cancel threw the cancel is tried again. */
 const EXPIRY_RETRY_MS = 60_000;
 
+/** Ends a backlog line cut to fit in one of the residents' messages. */
+const CUT_MARK = " [cut to fit; the whole message is in the channel's history]";
+
+/**
+ * tune_out's refusal of a channel already tuned out: its settings, then what
+ * its transport is now where the repeat tried to open it again (`transport`,
+ * from the framework's dispatch), then how to change the settings.
+ */
+export function alreadyTunedOutText(channelId: string, p: TuneOutParams, transport?: string): string {
+  // A duration so long its end is past what a Date can hold has no time to show.
+  const expires = p.expiresAtMs !== undefined ? new Date(p.expiresAtMs) : undefined;
+  const until = expires && Number.isFinite(expires.getTime())
+    ? `, until ${expires.toISOString().replace(/\.\d+Z$/, 'Z')}`
+    : '';
+  // A thrown error's words may end without a stop.
+  const now = transport === undefined ? '' : /[.!?]$/.test(transport) ? `${transport} ` : `${transport}. `;
+  return `Nothing changed${transport !== undefined ? ' in the tune-out' : ''}: ${JSON.stringify(channelId)} is already `
+    + `tuned out, with cadenceSeconds ${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. `
+    + now
+    + 'To change those, cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call '
+    + 'tune_out again with the new settings.';
+}
+
+/** The first `length` code units of `text`, one fewer where the last would be
+ *  the first half of a surrogate pair. */
+function prefixOf(text: string, length: number): string {
+  const cut = text.slice(0, Math.max(0, length));
+  const last = cut.charCodeAt(cut.length - 1);
+  return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}
+
 /** What a thrown value says, without throwing: an Error's message, or the
  *  value as text, which String() can't give for an object with no prototype. */
 function thrownReason(error: unknown): string {
@@ -63,6 +94,20 @@ export interface TuneOutFrameworkHooks {
   primaryName: () => string | null;
   /** Read the primary's stored messages (shared slot, unfiltered). */
   getStoredMessages: () => StoredMessage[];
+  /**
+   * Messages admitted for the primary but not yet in its store (deferred
+   * while a turn was alive), oldest first. A cancel reads them too, so a
+   * message held mid-turn is in the backlog it belongs to (#232 gap 7).
+   */
+  getDeferredMessages?: () => Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'>>;
+  /**
+   * The most characters of text every reader of the residents' shared slot
+   * is shown whole in one message: the smallest of their strategies'
+   * per-message caps (`maxMessageTokens`) at four characters a token, or
+   * undefined when none has such a cap. A cancel's dump is one message in
+   * that slot, so it holds as many backlog lines as fit.
+   */
+  residentMessageChars?: () => number | undefined;
   /** Current chronicle head sequence (window anchor for new epochs). */
   currentSequence: () => number;
   /** Move the subconscious window anchor (never forward past active epochs). */
@@ -178,7 +223,7 @@ export class TuneOutCoordinator {
     channelId: string,
     opts: { cadenceSeconds?: number; backlogCap?: number; maxWakes?: number; durationSeconds?: number },
     source: string,
-  ): { ok: true; params: TuneOutParams } | { ok: false; error: string } {
+  ): { ok: true; params: TuneOutParams } | { ok: false; error: string; alreadyTunedOut?: true } {
     if (!this.hooks.subconsciousName()) {
       return {
         ok: false,
@@ -197,21 +242,7 @@ export class TuneOutCoordinator {
       };
     }
     const current = this.channelRegistry.getTuneOutState(serverId, channelId);
-    if (current) {
-      const p = current.params;
-      // A duration so long its end is past what a Date can hold has no time to show.
-      const expires = p.expiresAtMs !== undefined ? new Date(p.expiresAtMs) : undefined;
-      const until = expires && Number.isFinite(expires.getTime())
-        ? `, until ${expires.toISOString().replace(/\.\d+Z$/, 'Z')}`
-        : '';
-      return {
-        ok: false,
-        error: `Nothing changed: ${JSON.stringify(channelId)} is already tuned out, with cadenceSeconds `
-          + `${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. To change those, `
-          + 'cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call tune_out '
-          + 'again with the new settings.',
-      };
-    }
+    if (current) return { ok: false, error: alreadyTunedOutText(channelId, current.params), alreadyTunedOut: true };
     // A tool's input reaches here as the model wrote it, and the store can't
     // keep a NaN or an Infinity: its append would throw after the registry
     // had marked the channel tuned out. So each option is read as a number
@@ -259,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);
@@ -302,35 +333,106 @@ export class TuneOutCoordinator {
     this.clearTimers(serverId, channelId);
     this.divertedSinceInvocation.delete(this.key(serverId, channelId));
 
-    // Backlog: every message stamped with this epoch, oldest first.
+    // Backlog: every message held under this epoch. The stored ones come in
+    // store order, then those still in the deferred queue (held mid-turn,
+    // not yet written), oldest first. That's arrival order, except when a
+    // held message stays queued while a later one is stored: a store write
+    // refused at a turn-start flush leaves it queued, and that turn's
+    // assembly can then store later coalesced messages directly.
     const epochId = ended.params.epochId;
-    const backlog = this.hooks.getStoredMessages().filter(
-      (m) => (m.metadata as { tuneOut?: { epochId?: string } } | undefined)?.tuneOut?.epochId === epochId,
-    );
-    const cap = ended.params.backlogCap;
-    const shown = cap > 0 ? backlog.slice(-cap) : [];
-    const truncated = backlog.length - shown.length;
-
-    const lines = shown.map((m) => {
-      const author = (m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant;
+    const ofEpoch = (m: Pick<StoredMessage, 'metadata'>): boolean =>
+      (m.metadata as { tuneOut?: { epochId?: string } } | undefined)?.tuneOut?.epochId === epochId;
+    const held = (this.hooks.getDeferredMessages?.() ?? []).filter(ofEpoch);
+    const backlog: Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'>> = [
+      ...this.hooks.getStoredMessages().filter(ofEpoch),
+      ...held,
+    ];
+    // Whole messages: a cap below one shows none, where slice(-0.5) would
+    // start at 0 and take them all.
+    const cap = Math.floor(ended.params.backlogCap);
+    const authorOf = (m: Pick<StoredMessage, 'participant' | 'metadata'>): string =>
+      (m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant;
+    const lineOf = (m: Pick<StoredMessage, 'participant' | 'content' | 'metadata'>): string => {
       const text = m.content
         .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
         .map((b) => b.text)
         .join('\n');
-      return `${author}: ${text}`;
-    });
-    const attrs = [
-      `channel="${channelId}"`,
-      `messages=${backlog.length}`,
-      ...(truncated > 0 ? [`truncated=${truncated} (oldest; fetch_history covers the rest)`] : []),
+      return `${authorOf(m)}: ${text}`;
+    };
+    const lifecycle = `[Tune-out: ${channelId} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
+    const render = (lines: string[], truncated: number): string => {
+      const attrs = [
+        `channel="${channelId}"`,
+        `messages=${backlog.length}`,
+        ...(truncated > 0 ? [`truncated=${truncated} (oldest; fetch_history covers the rest)`] : []),
+      ];
+      return `${lifecycle}\n\n<tuned-out-backlog ${attrs.join(' ')}>\n${lines.join('\n')}\n</tuned-out-backlog>`;
+    };
+
+    // The dump is one message in the residents' shared slot, so each
+    // resident's strategy cuts it as it cuts any message past its per-message
+    // cap: context-manager's AutobiographicalStrategy (which connectome-host's
+    // FrontdeskStrategy extends) and WindowedPassthroughStrategy count a text
+    // block at a token per four characters, rounded up, and keep a message's
+    // first cap × 4 characters. Cut there, the dump would lose its newest
+    // lines, which would still count as shown. So it holds the newest lines
+    // that fit whole in the smallest such room, and those it leaves out, the
+    // oldest, count as truncated along with those above backlogCap, so the
+    // report is told of them. A newest message too long to fit alone is shown
+    // cut to the room left and marked, so the residents still get its head,
+    // as they would from a row of its own. When no line fits, whole or cut,
+    // the dump shows none; if the room is too small for even that, the
+    // residents' strategies cut its frame, the header and tags.
+    let shown = cap > 0 ? backlog.slice(-cap) : [];
+    let lines = shown.map(lineOf);
+    let newestCut = false;
+    const room = this.hooks.residentMessageChars?.();
+    if (room !== undefined && render(lines, backlog.length - shown.length).length > room) {
+      // The dump's length with no line, for the count that showing k lines
+      // leaves out: truncated= takes that count's digits, and goes at 0. With
+      // the newest k lines whole, the dump is that and the lines, with a
+      // newline between each two. While a message is left out, each line kept
+      // makes it longer, and they don't all fit, so the fit keeps lines from
+      // the newest while the next one fits.
+      const frameShowing = (k: number): number => render([], backlog.length - k).length;
+      let used = 0;
+      let kept = 0;
+      while (kept < lines.length) {
+        const next = used + lines[lines.length - 1 - kept]!.length + (kept > 0 ? 1 : 0);
+        if (frameShowing(kept + 1) + next > room) break;
+        used = next;
+        kept++;
+      }
+      // What of the newest line's text fits beside the frame and the mark. A
+      // cut shows some of it or none: a room under one character, or one
+      // that would split a surrogate pair, leaves the head empty.
+      const head = prefixOf(lines.at(-1) ?? '', room - frameShowing(1) - CUT_MARK.length);
+      if (kept === 0 && head !== '') {
+        lines = [head + CUT_MARK];
+        shown = shown.slice(-1);
+        newestCut = true;
+      } else {
+        lines = lines.slice(lines.length - kept);
+        shown = shown.slice(shown.length - kept);
+      }
+    }
+    const truncated = backlog.length - shown.length;
+    // The held messages the dump leaves out, the oldest of them. The
+    // subconscious's report covers what the dump leaves out, but its view
+    // holds stored rows only, so these go to it with its notice below. So does
+    // a held message the dump shows but can't give whole: one whose image or
+    // audio its text lines drop, or the newest, cut to fit.
+    const heldLeftOut = held.slice(0, Math.max(0, held.length - shown.length));
+    const heldForReport = [
+      ...heldLeftOut,
+      ...held.slice(heldLeftOut.length).filter((m) =>
+        m.content.some((b) => b.type !== 'text') || (newestCut && m === shown[0])),
     ];
-    const dump =
-      `<tuned-out-backlog ${attrs.join(' ')}>\n${lines.join('\n')}\n</tuned-out-backlog>`;
 
     // Host-framed system artifacts — never voiced as anyone.
     this.hooks.addMessage(
       'user',
-      [{ type: 'text', text: `[Tune-out: ${channelId} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]\n\n${dump}` }],
+      [{ type: 'text', text: render(lines, truncated) }],
       { system: true, kind: 'tune-out-cancel', channelId, epochId },
     );
     // The subconscious's own words, under its own name, verbatim.
@@ -346,20 +448,39 @@ export class TuneOutCoordinator {
     if (primary) {
       this.hooks.requestInference(primary, `tune-out cancelled (${reason})`, 'tune-out');
     }
-    // The subconscious gets one cancel turn of its own (unless it initiated
-    // the cancel — its note already carries its words): the issue's cancel
-    // shape is dump + a report from the subconscious, and when the cap
-    // truncated the raw dump, its summary is what covers the tail.
-    if (source !== 'subconscious' && subName) {
+    // The subconscious gets one cancel turn of its own: the issue's cancel
+    // shape is dump + a report from the subconscious, and when the dump left
+    // messages out, its summary is what covers them. The held messages the
+    // dump can't give the resident whole follow the notice, each a row of its
+    // own with its own content, as its view can't have them until they're
+    // stored. A cancel the subconscious makes itself gets the notice and the
+    // turn when some do, since it wrote its note before it could see them,
+    // and when it wrote no note and the dump left any message out, since
+    // nothing else then covers it. Otherwise its note speaks for what it saw.
+    const selfCancel = source === 'subconscious';
+    if (subName && (!selfCancel || heldForReport.length > 0 || (!subconsciousNote && truncated > 0))) {
       const truncNote = truncated > 0
-        ? ` ${truncated} of ${backlog.length} diverted messages were above the cap and not delivered raw.`
+        ? ` ${truncated} of ${backlog.length} diverted messages, the oldest, weren't delivered raw to the resident.`
+        : '';
+      const heldNote = heldForReport.length > 0
+        ? ` Still held at the cancel, so your view may not have them yet: the ${heldForReport.length} message${heldForReport.length === 1 ? '' : 's'} after this one.`
         : '';
       this.hooks.addMessage(
         'user',
-        [{ type: 'text', text: `[Tune-out cancelled: ${channelId} — ${reason}.${truncNote}]` }],
+        [{ type: 'text', text: `[Tune-out cancelled: ${channelId} — ${reason}.${truncNote}${heldNote}]` }],
         { system: true, kind: 'tune-out-cancel-report', channelId },
         subName,
       );
+      // Each held message is a row of its own, so a per-message cap cuts each
+      // one on its own, its author's label included, not the batch's newest.
+      for (const m of heldForReport) {
+        this.hooks.addMessage(
+          'user',
+          [{ type: 'text', text: `${authorOf(m)}:` }, ...m.content],
+          { system: true, kind: 'tune-out-cancel-held', channelId },
+          subName,
+        );
+      }
       this.hooks.requestInference(subName, `tune-out cancelled: ${channelId}`, 'tune-out');
     }
     this.hooks.emitTrace({ type: 'tune-out:cancelled', serverId, channelId, epochId, reason, wakeCount: ended.wakeCount });

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. */
@@ -371,6 +399,10 @@ export interface InferenceRequest {
    *  all of them without materializing content, the turn has no cause left
    *  and does not run. */
   coalescingBatchSubjects?: string[];
+  /** Host-owned: this wake's sole cause is reading this deferred write, a
+   *  coalesced render placed in its agent's queue (wakeToRead). Once the
+   *  agent has read the write, or it was removed, the wake starts no turn. */
+  readsDeferredWrite?: string;
   agentName: string;
   reason: string;
   source: string;
@@ -386,12 +418,6 @@ export interface InferenceRequest {
    * ephemeral run's (a subagent's), which takes no global fallback.
    */
   channelId?: string;
-  /**
-   * Host-owned: the MCPL server whose message set `channelId`. A turn's
-   * replies to that channel go out through this server only. Unset where the
-   * wake's channel came from no one server's message.
-   */
-  serverId?: string;
   /**
    * True when the triggering message explicitly addressed the agent (mention,
    * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake

package/src/types/events.ts

@@ -193,11 +193,32 @@ export interface ToolResult {
   /** Whether this was an error (for LLM) */
   isError?: boolean;
   /**
-   * An MCP tool's `structuredContent`: its machine-readable result, beside
-   * `data`, which is the content view. Present exactly when the server sent
-   * one, so `false`, `0` and `null` are values here, not absence. Programs
-   * read it (scripts get it in their result object); the model sees content,
-   * and sees this rendered as JSON only when the content carries no text.
+   * The dispatcher refused the call before it opened, RFC-007's refusal, so
+   * nothing ran and the call certainly had no effect. Only the dispatcher's
+   * path, the model's calls and a script's, sets it: the caller may not use
+   * the tool (allowedTools), a `skip_reply` wake was refused, the call's MCPL
+   * server is absent or still connecting, the host's policy for that server
+   * denies the tool, or a fork reached outside its channel. RFC-007's
+   * lifecycle refuses the call from the same place, so observers see no
+   * events for it. A check made after the call opened, such as a module's
+   * answer for a name it has no tool for or arguments that don't fit a
+   * schema, is a failure whose text says nothing was done, as is an MCPL
+   * request that couldn't be written. A programmatic call (`executeToolCall`,
+   * `ModuleContext.callTool`) opens no RFC-007 call, so it's never refused:
+   * the allowedTools check answers it with a failure saying the call didn't
+   * run, and the other checks it gets, such as the module registry's, answer
+   * as they do once a call has opened. A module's result never carries it. A script's call refused so reaches the script as an
+   * Error, where any other failure is a result with `isError`.
+   */
+  refused?: boolean;
+  /**
+   * The result's machine-readable form, beside `data`. Programs read it: a
+   * script gets it in its result object, and a host in the tool result
+   * event. The model never reads this field: it sees the value only where an
+   * MCP conversion put it in the content as JSON, which happens only when the
+   * server sent no text. An MCP tool's is its `structuredContent`, present
+   * exactly when the server sent one, so `false`, `0` and `null` are values
+   * here, not absence. Any other tool can set one too.
    */
   structured?: unknown;
   /**
@@ -237,15 +258,51 @@ export interface ToolCall {
    * The turn the call was made in, the same id as that turn's
    * `SpeechContext.turnId`. Set by the framework dispatch layer, beside
    * `callerAgentName`: a model's call carries the turn whose stream made it, a
-   * foreground script's inner call the turn of the code_execution call whose
-   * script is running when the call arrives, and a utility run its `utils`
-   * call's. A background script runs apart from any turn, so its calls carry
-   * none. Ids increase, so a later turn's is larger, and they're unique only
+   * script's call the turn of the code_execution call watching the script when
+   * the call reaches the host, and a utility run its `utils` call's. A script left
+   * running, which no call watches, runs apart from any turn, so its calls
+   * carry none. Ids increase, so a later turn's is larger, and they're unique only
    * within one run of the process. A call made with `executeToolCall` or a
    * module's `callTool` skips that layer and carries whatever turn its caller
    * put on the call, usually none.
    */
   callerTurnId?: number;
+  /**
+   * 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
+   * 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,
+   * 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
+   * character of the result takes at most six bytes (a control character,
+   * escaped as `\u0000`), so the figure is that third, less the 80 bytes of a
+   * text answer's envelope, over six: 7,456,527 at the default 128 MiB. On
+   * Node, past about 1.5 GiB, the host's longest string bounds it instead.
+   * A result with a `structured` value reaches a script as its content's
+   * blocks as they are, beside that value as JSON, and the figure counts
+   * neither the value nor what the blocks carry past their text, such as each
+   * further block's keys or an image's data, so a tool that returns one
+   * leaves room for them; and a result nested past 2,000 levels, or whose parse
+   * needs more of the script's memory than is free, doesn't reach the script
+   * whatever its length. A result that doesn't reach it is answered
+   * ResultTooLarge, the call having taken effect. Nothing is cut or saved to
+   * a file. A tool that pages or budgets its answer can stay under it. The
+   * framework sets it on a model's, a script's and the operator's puppet's
+   * call to a module, a utility run through `utils` included. A call
+   * made in process with ModuleContext.callTool or executeToolCall carries
+   * what its caller put on it, as the puppet's does; the framework's own
+   * read_image tool passes a model's call to the workspace without it; and a
+   * utility run through `utils` carries what its `utils` call carried.
+   * Without it, a module holds its answer to a bound of its own, if any: the
+   * workspace's is the house default, 24,000.
+   */
+  resultMaxChars?: number;
 }
 
 // ============================================================================