@animalabs/agent-framework 0.24.0 → 0.24.1

package/src/index.ts

@@ -10,6 +10,8 @@ export { ProcessQueueImpl } from './queue.js';
 export { ModuleRegistry } from './module-registry.js';
 export { ShutdownTimeoutError, DEFAULT_SHUTDOWN_TIMEOUT_MS } from './shutdown.js';
 export { formatZonedDateTime, formatZonedTime, isValidTimeZone, resolveTimeZone } from './timezone.js';
+export { CLOCK_ROW_KIND, resolveClockConfig } from './clock-rows.js';
+export type { ClockConfig, ClockStamp, ResolvedClockConfig } from './clock-rows.js';
 export { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK, REFUSAL_REACTION_BASELINE } from './refusal-reactions.js';
 
 // Built-in modules

package/src/mcpl/channel-registry.ts

@@ -813,6 +813,15 @@ function supersededClause(action: 'open' | 'close', now: DesiredChannelState | u
   return action === 'close' ? 'a later decision to keep it open came first' : 'a later decision to close it came first';
 }
 
+/** What ends a tune-out, for a channel tool's answer about a tuned-out
+ *  channel (`channel` as the answer shows it, quoted): its cancel, with the
+ *  backlog it delivers, and, for a close, that channel_close closes the
+ *  channel once the cancel has ended the tune-out. */
+function tunedOutPointer(tool: string, channel: string): string {
+  return `Call tune_out with channelId ${channel} and mode "cancel" for it to resume normal attention; cancelling ` +
+    'delivers the diverted backlog' + (tool === 'channel_close' ? ', and channel_close closes it after that.' : '.');
+}
+
 /** A channel tool's refusal of a tuned-out channel, whose cancel is what ends
  *  the tune-out, with the backlog it delivers. As an error result the agent
  *  reads the pointer itself; `data` names the refusal for an in-process
@@ -823,8 +832,7 @@ function tunedOutRefusal(tool: string, channelId: string): ToolResult {
     isError: true,
     error:
       `Channel "${channelId}" is tuned out: its messages go to the subconscious, and ${tool} doesn't change that. ` +
-      `Call tune_out with channelId "${channelId}" and mode "cancel" for it to resume normal attention; cancelling ` +
-      'delivers the diverted backlog.',
+      tunedOutPointer(tool, `"${channelId}"`),
     data: { refusal: 'tuned-out', channelId },
   };
 }
@@ -1336,6 +1344,12 @@ export class ChannelRegistry {
         return `Channel ${channel} was tuned out meanwhile: its messages go to the subconscious, and channel_open doesn't ` +
           `change that. Call tune_out with channelId ${channel} and mode "cancel" for it to resume normal attention.`;
       }
+      // channel_close refuses a tuned-out channel too, so calling it again
+      // isn't the way: the tune-out's cancel is, and it delivers the backlog.
+      if (action === 'close' && now === 'tuned-out') {
+        return `Channel ${channel} was tuned out meanwhile: its messages go to the subconscious, and channel_close doesn't ` +
+          `change that. ${tunedOutPointer('channel_close', channel)}`;
+      }
       // The later decision's own work settles the transport, and its call
       // says what became of it, so this says only that this call's change
       // doesn't stand.
@@ -3123,6 +3137,19 @@ export class ChannelRegistry {
     return { params: current.tuneOut, wakeCount: current.wakeCount ?? 0 };
   }
 
+  /** Every tune-out on record, whether or not its channel is registered
+   *  here yet: the decisions the lifecycle log's replay restored, and any
+   *  made since. */
+  tuneOutsOnRecord(): Array<{ serverId: string; channelId: string; params: TuneOutParams; source: string }> {
+    const found: Array<{ serverId: string; channelId: string; params: TuneOutParams; source: string }> = [];
+    for (const [key, record] of this.desiredStates) {
+      if (record.state !== 'tuned-out' || !record.tuneOut) continue;
+      const at = key.indexOf('\u0000');
+      found.push({ serverId: key.slice(0, at), channelId: key.slice(at + 1), params: record.tuneOut, source: record.source });
+    }
+    return found;
+  }
+
   /** Registered channel entries (read-only iteration for the coordinator). */
   listChannelsRaw(): Array<{ serverId: string; descriptor: ChannelDescriptor }> {
     return [...this.channels.values()].map((e) => ({
@@ -4322,8 +4349,9 @@ export class ChannelRegistry {
       source?: string;
       /** A machine close aimed at an explicitly-opened channel is refused
        *  unless the caller certifies an explicit idle lease (a configured
-       *  per-channel budget is consent to close at that budget). Module
-       *  origin only, like `source`. */
+       *  per-channel budget is consent to close at that budget). A tuned-out
+       *  channel is refused even so, since its tune-out's cancel is what
+       *  ends it. Module origin only, like `source`. */
       overrideExplicitOpen?: boolean;
     },
     origin?: ChannelToolOrigin,
@@ -4401,6 +4429,18 @@ export class ChannelRegistry {
       }
     }
 
+    // A tuned-out channel's decision is the tune-out, and a close recorded
+    // over it would end it without its cancel, so the backlog it diverted
+    // would never reach the agent. Its cancel is what ends it, as
+    // channel_open's and channel_decline's refusals of a tuned-out channel
+    // say, and the agent closes the channel after that. A module's close
+    // that certified an idle lease, which the guard above lets through, is
+    // refused too, as a refusal it stands down on rather than an error.
+    if (this.getDesiredState(entry.serverId, input.channelId) === 'tuned-out') {
+      const refusal = tunedOutRefusal('channel_close', input.channelId);
+      return isModuleOrigin ? { ...refusal, isError: false } : refusal;
+    }
+
     // A decision the log refused changed nothing, and the answer says so.
     try {
       this.setDesiredState(entry.serverId, input.channelId, 'closed', closeSource);
@@ -4598,14 +4638,20 @@ export class ChannelRegistry {
           'decline again to close it.'
         : ' If you need it closed now, call channel_close.';
     if (!stands) {
-      // channel_close closes it after all, whichever decision it was, while
-      // the channel is registered; a server that's up without the grant
-      // keeps its channels as it chooses, as the decline's refusal says.
+      // channel_close closes it after all while the channel is registered,
+      // over an open, or once a tune-out's cancel has ended the tune-out,
+      // since it refuses a tuned-out channel; a server that's up without the
+      // grant keeps its channels as it chooses, as the decline's refusal
+      // says.
       const step = after === undefined
         ? `. It isn't registered here any more, so no channel tool can reach it until it's registered here again.${serverBack}`
         : reach === 'up' && !this.directsLifecycle(entry.serverId)
           ? `, and ${this.lifecycleRefusal(entry.serverId).message}; if you need it closed, ask whoever runs this host.`
-          : `. If you still want it closed, call channel_close.${serverBack}`;
+          // channel_close refuses a tuned-out channel, so the cancel comes first.
+          : decided === 'tuned-out'
+            ? `. If you still want it closed, cancel the tune-out with tune_out mode "cancel", which delivers what it ` +
+              `diverted, and then call channel_close.${serverBack}`
+            : `. If you still want it closed, call channel_close.${serverBack}`;
       closeError = decided === 'tuned-out'
         ? `The decline is recorded, but the channel was tuned out meanwhile, and that decision stands: its messages go to ` +
           `the subconscious${step}`

package/src/mcpl/protocol-family.ts

@@ -733,7 +733,7 @@ export function serverConfigProblems(config: McplServerConfig): string[] {
   if (binding.family === 'modern') {
     if (timeout !== undefined && !(Number.isInteger(timeout) && timeout >= 1 && timeout <= MAX_TIMER_MS)) {
       problems.push(
-        `MCP server "${config.id}": requestTimeoutMs must be an integer from 1 to ${MAX_TIMER_MS} for a modern server (got ${String(timeout)}); every modern call has a deadline`,
+        `MCP server "${config.id}": requestTimeoutMs must be an integer from 1 to ${MAX_TIMER_MS} for a modern server (got ${asText(timeout)}); every modern call has a deadline`,
       );
     }
     for (const path of mcplPolicyGrants(config)) {

package/src/modules/workspace/index.ts

@@ -268,6 +268,16 @@ export interface ReadFileFromDiskOptions {
   maxBytes?: number;
 }
 
+/**
+ * Why a pass decided nothing, or null where it decided its paths. A pass gives
+ * up deciding, and reports no path, when the selected branch kept changing
+ * while it gathered, or when a sync's branch was no longer selected; it then
+ * carries no branchId, and the region it leaves incomplete says why.
+ */
+function undecidedOf(pass: PassResult): string | null {
+  return pass.branchId === undefined ? (pass.incomplete[0]?.reason ?? 'the pass decided nothing') : null;
+}
+
 function errnoOf(err: unknown): string | undefined {
   return typeof err === 'object' && err !== null && 'code' in err && typeof (err as { code?: unknown }).code === 'string'
     ? (err as { code: string }).code
@@ -2284,9 +2294,9 @@ export class WorkspaceModule implements Module {
     if (mount.direct) return this.bytesFromDisk(mount, relativePath, mountPrefixedPath, mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE);
     const store = this.getStore();
     return this.withMount(mount, async () => {
-      await this.ensureSynced(mount, relativePath);
+      const { report, undecided } = await this.ensureSynced(mount, relativePath);
       const entry = store.treeGet(mount.treeStateId, relativePath);
-      if (!entry) return { error: `File not found: ${mountPrefixedPath}` };
+      if (!entry) return { error: undecided !== null ? this.notCheckedYet(mountPrefixedPath, undecided) : this.notInWorkspace(mountPrefixedPath, report) };
       const blob = store.getBlob(entry.blobHash);
       if (!blob) return { error: `Blob not found for: ${mountPrefixedPath}` };
       return { data: blob };
@@ -3676,13 +3686,24 @@ export class WorkspaceModule implements Module {
    * path, as a file tool names the one it acts on: a path the mount passes
    * over by design is observed, as a sync naming it would observe it (#276),
    * while a path in another mount's directory is refused before this, and
-   * passed over by any pass. The caller holds the mount's turn.
+   * passed over by any pass. Answers the pass's report on the path, and why
+   * the pass decided nothing where it did (undecidedOf), which leaves disk
+   * unchecked. The caller holds the mount's turn.
    */
-  private async ensureSynced(mount: MountState, relativePath: string): Promise<PathReport | undefined> {
+  private async ensureSynced(mount: MountState, relativePath: string): Promise<{ report: PathReport | undefined; undecided: string | null }> {
     const store = this.getStore();
-    if (store.treeGet(mount.treeStateId, relativePath)) return undefined;
+    if (store.treeGet(mount.treeStateId, relativePath)) return { report: undefined, undecided: null };
     const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true });
-    return pass.reports.get(relativePath);
+    return { report: pass.reports.get(relativePath), undecided: undecidedOf(pass) };
+  }
+
+  /**
+   * Why the workspace holds no entry at a path, after a pass over it that
+   * decided nothing: disk wasn't checked, so it may have a copy, and the same
+   * call made again checks it.
+   */
+  private notCheckedYet(path: string, reason: string): string {
+    return `${this.notInWorkspace(path, { path, state: 'unverified', note: reason })} Make the same call again, which checks disk first.`;
   }
 
   /** Why the workspace holds no entry at a path, when disk explains it. */
@@ -3715,7 +3736,7 @@ export class WorkspaceModule implements Module {
     if (mount.direct) return this.bytesOnDisk(mount, relativePath, path);
     const store = this.getStore();
     return this.withMount(mount, async () => {
-      const report = await this.ensureSynced(mount, relativePath);
+      const { report } = await this.ensureSynced(mount, relativePath);
       const entry = store.treeGet(mount.treeStateId, relativePath);
       if (!entry) return { error: this.notInWorkspace(path, report) };
       const blob = store.getBlob(entry.blobHash);
@@ -4086,6 +4107,8 @@ export class WorkspaceModule implements Module {
         // As every file tool's pass does, it names the paths it acts on, so a
         // file the mount passes over by design is observed (see PassOptions.named).
         const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [...targets.values()].map((target) => target.relativePath) }, { named: true });
+        // A pass that decided nothing checked no file's disk copy.
+        const undecided = undecidedOf(pass);
         // Nothing below awaits until the commit's push.
         const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
         const hints = hintBudget();
@@ -4109,6 +4132,20 @@ export class WorkspaceModule implements Module {
           // workspace didn't hold has no older copy, so taking it in needs no
           // word.
           const subject = tool === 'edit' ? 'the edit' : editList(target.edits);
+          // A pass that decided nothing checked no copy on disk, held or not,
+          // and took nothing in, so the edits would apply to text disk may
+          // have moved past, on whichever branch is selected once it gave up.
+          // They're refused, as a call made again can check.
+          if (undecided !== null) {
+            problems.push({
+              kind: 'file',
+              edits: target.edits,
+              path: target.path,
+              text: `${target.path} couldn't be checked against disk (${undecided}), so ${subject} changed nothing. Make the same call again, which checks disk first.`,
+              whole: true,
+            });
+            continue;
+          }
           const whichCopy = (verb: string): string | null => took('modified')
             ? `Disk's copy${tool === 'edit' ? '' : ` of ${target.path}`} had changed since the workspace last agreed with it, so it was taken in first, and ${subject} ${verb} that text.`
             : report?.state === 'unverified'
@@ -4378,11 +4415,12 @@ export class WorkspaceModule implements Module {
     let committed = false;
     try {
       return await this.withMount(mount, async (): Promise<ToolResult> => {
-        const report = await this.ensureSynced(mount, relativePath);
+        const { report, undecided } = await this.ensureSynced(mount, relativePath);
         await this.settleBeforeMutation(mount, relativePath);
         const entry = store.treeGet(mount.treeStateId, relativePath);
         if (!entry) {
-          return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
+          const error = undecided !== null ? this.notCheckedYet(input.path, undecided) : this.notInWorkspace(input.path, report);
+          return { success: false, error, isError: true };
         }
 
         const { refused, note } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash },

package/src/timezone.ts

@@ -2,8 +2,10 @@
  * Agent-visible wall-clock formatting.
  *
  * Persistence and protocol timestamps should remain epoch milliseconds or UTC
- * ISO strings.  These helpers are only for presentation boundaries where a
- * timestamp is rendered into an agent's context or a tool result.
+ * ISO strings.  These helpers are for presentation boundaries where a
+ * timestamp is rendered into an agent's context or a tool result, and the
+ * zone resolveTimeZone gives also places clock rows' boundaries
+ * (clock-rows.ts).
  */
 
 export function isValidTimeZone(timeZone: string): boolean {

package/src/tool-image-ledger.ts

@@ -316,7 +316,8 @@ export interface StoredCut {
   head: string;
   /** The image slots past the cut that the stored copy re-appends after its
    *  truncation notice, in text order: the newest MAX_KEPT_IMAGE_SLOTS of
-   *  those the live copy showed. */
+   *  those the live copy showed, or under a readers' bound the newest of
+   *  those that fit it, down to none (cutStoredToolResultToFit). */
   kept: string[];
   /** How many image slots past the cut the live copy showed. */
   fell: number;
@@ -326,8 +327,10 @@ export interface StoredCut {
  * Where a tool result's text longer than `cap` is cut: by its stored copy
  * (cutStoredToolResult), by history's own truncation (truncateForHistory),
  * and by its live copy, for each text block beside an image
- * (tryNativeToolResultContent, framework.ts), so the stored copy and the live
- * copy cut alike. The text's length when it isn't longer than `cap`.
+ * (tryNativeToolResultContent, framework.ts), so at one cap the stored copy
+ * and the live copy cut alike. Under a readers' bound the stored copy's cut
+ * can come earlier (cutStoredToolResultToFit). The text's length when it
+ * isn't longer than `cap`.
  *
  * The cut is made at the cap, or before it when the cap would split a
  * surrogate pair (safeSlice's rule), and that is where the moves back are
@@ -395,9 +398,13 @@ export function cutStoredToolResult(text: string, cap: number, shown: ShownRange
 /** What a stored copy re-appends after its truncation notice: the kept
  *  slots, each on its own line so a reference stub stays parseable, under a
  *  note saying how many fell past the cut, and how many of those were left
- *  out and aren't counted. Empty when none fell past the cut. */
+ *  out and aren't counted, all of them where none fit the bound
+ *  (cutStoredToolResultToFit). Empty when none fell past the cut. */
 export function formatKeptImageSlots(cut: StoredCut): string {
   if (cut.fell === 0) return '';
+  if (cut.kept.length === 0) {
+    return `\n[${cut.fell} image slot(s) fell past the cut and are left out, and save_recent_image doesn't count them.]`;
+  }
   const leftOut = cut.fell - cut.kept.length;
   const note = leftOut === 0
     ? `${cut.fell} image slot(s) fell past the cut; kept here in order so save_recent_image still counts them:`
@@ -406,14 +413,61 @@ export function formatKeptImageSlots(cut: StoredCut): string {
   return `\n[${note}]\n${cut.kept.join('\n')}`;
 }
 
+/** The most a stored copy's truncation notice takes (spillOrTruncate,
+ *  framework.ts): the spill notice names its file twice, once in its paging
+ *  advice, and fits this on a path from a mount name of up to about seventy
+ *  characters. */
+export const TOOL_RESULT_NOTICE_ROOM = 640;
+
+/**
+ * A result's cap and bound when its message holds `n` results. A reader's
+ * strategy spends its per-message bound across the message's blocks in
+ * order, so each result takes an equal share of the readers' smallest
+ * bound, fixed before any result is cut, since its siblings may still be
+ * running when save_recent_image counts it, and its cap is at most that
+ * share. `keptCap` is where a withheld stub's kept fields are cut, leaving
+ * the stub's notice its room (tool-result-guard.ts). With no bound, each
+ * keeps the cap.
+ */
+export function toolResultShare(cap: number, bound: number | undefined, n: number): { cap: number; bound: number | undefined; keptCap: number } {
+  if (bound === undefined) return { cap, bound, keptCap: cap };
+  const share = Math.floor(bound / Math.max(1, n));
+  return { cap: Math.min(cap, share), bound: share, keptCap: Math.min(cap, Math.max(1, share - TOOL_RESULT_NOTICE_ROOM)) };
+}
+
+/**
+ * Cut a tool result's text at `cap` as cutStoredToolResult does, unless its
+ * stored copy would then pass `bound`, the most a reader's strategy keeps of
+ * it (toolResultShare): the head, room for the notice after it, and the kept
+ * slots after that (formatKeptImageSlots). A strategy cuts a longer message
+ * from its end, and with it the notice that holds the way to the rest, so
+ * there the head moves back until the copy fits. The kept slots grow as the
+ * head moves back, so the cut is found again until head and slots fit or the
+ * head is empty. Slots that alone pass the room keep the newest that fit,
+ * the rest left out and uncounted, as past MAX_KEPT_IMAGE_SLOTS. A bound
+ * under the notice's room can't hold the notice. With no bound, or where the
+ * cut at the cap already fits, the cut is cutStoredToolResult's.
+ */
+export function cutStoredToolResultToFit(text: string, cap: number, shown: ShownRanges | null, bound: number | undefined): StoredCut {
+  let cut = cutStoredToolResult(text, cap, shown);
+  if (bound === undefined || text.length <= cap) return cut;
+  const room = bound - TOOL_RESULT_NOTICE_ROOM;
+  while (cut.head.length > 0 && cut.head.length + formatKeptImageSlots(cut).length > room) {
+    cut = cutStoredToolResult(text, Math.max(0, room - formatKeptImageSlots(cut).length), shown);
+  }
+  while (cut.kept.length > 0 && formatKeptImageSlots(cut).length > room) cut = { ...cut, kept: cut.kept.slice(1) };
+  return cut;
+}
+
 /**
  * The image slots a tool result's stored copy holds: its text's, or, when the
  * text is longer than `cap`, those the cut keeps, in head and after the
- * notice (cutStoredToolResult). The notice itself holds none. For counting a
- * result before its stored copy is written, as it will count after.
+ * notice (cutStoredToolResultToFit, under the readers' `bound`). The notice
+ * itself holds none. For counting a result before its stored copy is
+ * written, as it will count after.
  */
-export function storedImageSlots(text: string, cap: number, shown: ShownRanges | null): ParsedImagePlaceholder[] {
-  const cut = cutStoredToolResult(text, cap, shown);
+export function storedImageSlots(text: string, cap: number, shown: ShownRanges | null, bound: number | undefined): ParsedImagePlaceholder[] {
+  const cut = cutStoredToolResultToFit(text, cap, shown, bound);
   return parseImagePlaceholders(cut.head + formatKeptImageSlots(cut));
 }
 

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

@@ -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

@@ -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

@@ -272,7 +272,11 @@ export interface ToolCall {
    * 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. 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;