@animalabs/agent-framework 0.24.0 → 0.25.0

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

@@ -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
@@ -1841,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'],
@@ -1863,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' },
           },
@@ -2284,9 +2295,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 +3687,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 +3737,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 +4108,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 +4133,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 +4416,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 },
@@ -4578,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) {
@@ -4613,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;
@@ -4661,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);
@@ -5882,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
@@ -5916,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
@@ -5964,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/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));
 }