@animalabs/agent-framework 0.26.2 → 0.28.0

package/src/modules/workspace/types.ts

@@ -20,25 +20,45 @@ export interface MountConfig {
    * Where the mount's tools get what they read (default: 'chronicle').
    * - 'chronicle': the workspace keeps the mount's files in its store, where
    *   writes and edits land first, and takes in disk's changes under the
-   *   three-way rule as its listings, searches, syncs and scans reach them.
-   *   A read of a path the store doesn't hold takes in a new file there;
-   *   otherwise it reads the store's copy.
-   * - 'direct': for a checkout an agent reads, not one it changes. Every
-   *   read, listing and search is disk's own copy as it is when it runs,
-   *   and none of its files go into the store. No scan or watcher
+   *   three-way rule as `read`, listings, searches, syncs and scans reach
+   *   them. Its tools read the store's copy.
+   * - 'direct': for a checkout, such as a git one, whose history is its
+   *   own. Every read, listing and search is disk's own copy as it is when
+   *   it runs, and none of its files go into the store. No scan or watcher
    *   runs, so no call waits behind one, and `sync`, `materialize` and the
-   *   watch settings have nothing to act on. Only with `mode: 'read-only'`,
-   *   and not with `watch` other than 'never', `watchDebounceMs`,
-   *   `watchRootPollMs`, a `wakeOnChange` that would wake (true, or a
-   *   non-empty list) or `autoMaterialize: true`: each of those would never
-   *   act, and the workspace refuses the mount. Its `ignore`
+   *   watch settings have nothing to act on. Not with `watch` other than
+   *   'never', `watchDebounceMs`, `watchRootPollMs`, a `wakeOnChange` that
+   *   would wake (true, or a non-empty list) or `autoMaterialize: true`:
+   *   each of those would never act, and the workspace refuses the mount.
+   *   Writable, as any mount with no `mode` is, its `write`, `edit`,
+   *   `edit_many` and `delete` land on disk when they answer, or don't
+   *   happen: a file is staged beside itself in `.workspace-staged-<id>` and
+   *   renamed over itself, keeping its mode, so no reader sees half of it;
+   *   an edit is applied to disk's text as it is now, and again on top of a
+   *   change another writer makes meanwhile; and `edit_many` checks every
+   *   edit before writing its files one by one, naming each file's outcome
+   *   if a write fails partway. A file with other hard links gets a file of
+   *   its own at its path, and the others keep the old text; a file this
+   *   process may not write is refused. Nothing is synced, so a power loss
+   *   can lose a write its answer called landed. An undo or other move of
+   *   the store's head leaves the files as they are, and at the agent's next
+   *   start the framework tells it once that writes from turns its history
+   *   no longer holds are still on disk. Where each agent's latest write
+   *   lies is saved at a clean stop, in a record no branch switch rewinds,
+   *   so a restart on another branch still tells it, and after a crash a
+   *   move away from the writes since then isn't told. The framework's own
+   *   files, its
+   *   tool-result spills, saved payloads and fetched references, never go to
+   *   a mount configured direct. Its `ignore`
    *   has a default (see there). Paths, links, its `include`, other mounts'
    *   directories, size limits and the walk cap hold as on a 'chronicle'
-   *   mount. Its tools read beneath whatever directory is at its
-   *   root, with no check against the one a 'chronicle' run of it last
-   *   agreed with. Where that root now lies elsewhere than the last start
-   *   placed it, each call nests in it, as a start would now, every mount
-   *   configured beneath its path, where that path leads beneath its root,
+   *   mount. Its tools read and write beneath whatever directory is at its
+   *   root when each call starts, with no check against the one a
+   *   'chronicle' run of it last agreed with, so a root repointed through a
+   *   link is read and written where it leads now. Where that root now lies
+   *   elsewhere than the last start placed it, each call nests in it, as a
+   *   start would now, every mount
+   *   configured on or beneath its path, where that path leads beneath its root,
    *   and every other mount whose root, as that start placed it, lies
    *   beneath where its root lies now, or whose configured path lies
    *   beneath a directory that start found there. A mount configured
@@ -52,7 +72,10 @@ export interface MountConfig {
    * them pending, or an intent the workspace can't read, which may hold one
    * of those. They stay in view, and the workspace says so on stderr and
    * through the framework's ops alerts, naming them and the ways to start it
-   * direct. It runs unwatched, and walks by the direct kind's default
+   * direct. Until a start finds none held, it takes no writes, edits or
+   * deletions, so what's held only shrinks: a `sync` of a held path takes
+   * disk's copy, and a `materialize` naming the mount writes the store's.
+   * It runs unwatched, and walks by the direct kind's default
    * ignore list where its config names none; `ls` without a path, and
    * `status`, give its `backend` as 'chronicle' and that list. A mount that
    * ran direct and runs as 'chronicle' again takes in what disk changed
@@ -78,10 +101,32 @@ export interface MountConfig {
   /** Poll interval in ms for checking watched root identity changes (default: 2000) */
   watchRootPollMs?: number;
   /**
-   * Simple ignore patterns (NOT full gitignore syntax). Supported forms:
-   * - Exact name match: ".git", "node_modules"
-   * - Directory glob: "node_modules/**" (anything under node_modules)
-   * - Extension glob: "*.pyc" (any file ending in .pyc)
+   * Patterns in these of gitignore's forms, each covering the files
+   * gitignore's reading of it covers, with three differences: names compare
+   * exactly, as git's do with `core.ignorecase` off (its default folds case
+   * on macOS and Windows); "?" matches one character where git's matches
+   * one byte, so the two differ on names outside ASCII; and on a mount that
+   * follows links, a link to a directory counts as a directory, where git
+   * reads every link as a file:
+   * - A name, matched at any depth: ".git", "node_modules". Within a name,
+   *   "*" matches any run of characters and "?" any one: "*.pyc",
+   *   "npm-debug.log*".
+   * - A trailing "/" matches only a directory: "build/" covers every
+   *   directory named build, with what lies beneath it, and no file of that
+   *   name.
+   * - A leading or inner "/" makes a path from the mount's root: "/dist"
+   *   covers only the root's dist, and "a/b" only the root's a/b.
+   * - "**" as the first segment, before one name, matches that name at any
+   *   depth, as the name alone does; with a trailing "/**" as well, it reads
+   *   as the name with a trailing "/".
+   * - A trailing "/**" covers a directory from the root and what lies
+   *   beneath it: "node_modules/**" covers only the root's node_modules, and
+   *   no file of that name.
+   * The module refuses, when it's built, a pattern of any other form, such as
+   * a leading "!" or "#", a "[", a "\", a trailing space, "**" anywhere
+   * else, or an empty, "." or ".." segment, naming the pattern and why. A
+   * "?" can stand for a "[" or "\" in a name.
+   *
    * A sync without a path and the watcher pass over what the list covers,
    * and over entries with an editor's swap or backup file name whatever it
    * says, a directory with what lies beneath it: `.name.swp` and `.name.swx`
@@ -101,13 +146,17 @@ export interface MountConfig {
   ignore?: string[];
   /**
    * The files this mount holds, when it holds only some of what is under its
-   * path: the same pattern forms as `ignore`, read for files. A name or an
-   * extension glob covers a file by its own name, at any depth, and a directory
-   * glob (`dir/**`) covers what lies beneath that directory, and not a file
-   * named like it. Unlike `ignore`, a pattern that matches a directory's name
-   * covers nothing beneath it, since each file is covered by its own name:
-   * `["gate.json"]` holds every file named `gate.json`, and no other file
-   * beneath a directory of that name. A subtree is named with `dir/**`.
+   * path: patterns in `ignore`'s forms, read for files, and a `[` read as
+   * itself, so `[id].tsx` names that file. A pattern that matches
+   * only directories, with a trailing `/` or `/**`, covers what lies beneath a
+   * directory it matches: `fixtures/` every file beneath a directory named
+   * fixtures, at any depth, and `docs/**` or `/docs/` every file beneath the
+   * root's docs. Any other pattern covers a file by its own name, at any
+   * depth, or by its path from the root (`/gate.json`, `src/*.ts`). Unlike
+   * `ignore`, such a pattern covers nothing beneath a directory it matches,
+   * since each file is covered by its own name or path: `["gate.json"]` holds
+   * every file named `gate.json`, and no other file beneath a directory of
+   * that name.
    *
    * It's the mount's boundary for content: no workspace path reads, stores,
    * serves or writes back a file it doesn't cover, and no tool lists,
@@ -176,31 +225,62 @@ export interface MountConfig {
    * A path in a nested mount's directory is that mount's, whatever this
    * include covers: every tool gives the answer that names the mount holding
    * it and the path to use there. Through a link a mount follows, a place in
-   * that directory is named only where it's a directory, or a file that
-   * mount's own include covers with no file on its way, and is otherwise
-   * refused as leaving the mount. On a mount that doesn't follow links, a
-   * link on a path's way is refused, as on any such mount (followSymlinks).
-   * A nested mount's root is placed where disk has it at each start, and its
-   * directory is matched by spelling, so four cases fall outside this, as
-   * for any nested mount, and a fifth on a direct one: on a disk that folds
-   * names, a mount configured
-   * through a link that spells a directory otherwise than disk does isn't
-   * found nested, and this mount holds its files as its own; on such a disk,
-   * a path through a link that spells a nested mount's directory otherwise
-   * than that mount's configured path does, whether the link or the
-   * configured path is the one spelled otherwise than disk, isn't found to
-   * lead there, and this mount reads, lists, searches and writes there as
-   * its own, creating files too, though a walk from its root passes over the
-   * directory; on such a disk, a place in a nested mount's directory that a
-   * link does lead to is judged by that mount's include, and named, in the
-   * spelling the link's target gives, so a refusal can name a file disk
-   * spells outside that include, or leave a covered one unnamed; and a
-   * nested mount whose root moves while running, as `acceptRoot` takes,
-   * stays placed where it was until the next start; and where a direct
-   * mount's root is repointed between a read's parse and its open, a race
-   * left to whoever writes the disk, a mount nested in it by its
-   * directories alone, since its real root holds that root, can have the
-   * read serve a path in its directory.
+   * that directory is named only where it's a directory, or a file covered,
+   * with no file on its way, by that mount's own include and by the include
+   * of each other nested mount whose directory may hold it, from the
+   * innermost out to the first that surely holds it, and is otherwise
+   * refused as leaving the mount. A listing, or a pass, names a file there
+   * only where those includes cover it. On a mount that doesn't follow
+   * links, a link on a path's way is refused, as on any such mount
+   * (followSymlinks).
+   * Every check compares a path with a nested mount's directory level by
+   * level, as any disk may compare names: in either Unicode normalization
+   * form and in any case, as fully as a disk that folds names may compare
+   * them, at every level, whatever the disk does there, and reading nothing
+   * from the disk to do so. Start places each root the same way, so a mount
+   * configured through a link, or in a spelling, other than disk's is found
+   * nested. So a path, a walk or the workspace's history that names the
+   * directory in any spelling a disk may take for it reaches that mount,
+   * whether or not the directory is on disk yet, and so does a link whose
+   * target spells it otherwise. Where a link leads into the directory, the
+   * place beneath it is judged, and named, as disk spells it. A path that names the directory itself keeps what lies
+   * beneath as given, since that is the nested mount's to name. Where a disk
+   * keeps apart two names the comparison joins, it errs toward the nested
+   * mount, in where start places a mount as in every check: a name in
+   * another case, on a disk that tells case apart; a name in the other
+   * normalization form, on a disk that keeps the forms apart; and a name the
+   * comparison folds with it that a disk keeps apart, such as `ss` beside a
+   * nested `ß`, or one that differs from it only by a default-ignorable code
+   * point, such as a soft hyphen, on a disk that keeps those. Such a
+   * directory, or file, is no mount's, and every tool that names it is
+   * refused as a path that may lie in the nested mount, with the two
+   * spellings the workspace can't tell apart, and, for a link, where it
+   * leads, when that lies in this mount. The answer gives a step for each
+   * thing the caller may have meant: that mount's path to use; for a new
+   * file of this mount's, a path outside both spellings; and for one already
+   * there, whoever runs the workspace renaming one of the two spellings.
+   * Where start placed the nested mount only by a guess, comparing the real
+   * roots, as for two mounts' roots configured in spellings it can't tell
+   * apart, a path there is a guess too, however exactly it matches, and the
+   * answer names that directory as the path spells it, with the nested
+   * directory's spelling only in the step for a new file, names no host
+   * path, and asks for the configuration to be checked. Three cases fall
+   * outside this, as for any nested mount, and a fourth on a direct one: on a
+   * disk whose folding goes past the comparison's, which joins names that
+   * differ only by default-ignorable code points, in normalization form or in
+   * case, in full case folding, as Linux's casefold does, a name the
+   * comparison keeps apart can reach the directory; a second path to the
+   * directory that isn't a link, such as a bind mount, isn't found to lead
+   * there, though a walk passes over it, knowing each nested root by which
+   * directory it is; a nested mount whose root moves while running, as
+   * `acceptRoot` takes, stays placed where it was until the next start, but
+   * for the calls of a direct mount whose root has moved and on or beneath
+   * whose path it's configured, which place it where it lies; and where a
+   * direct mount's root is repointed between a read's parse and its open, or
+   * a write's parse and its staging, a race left to whoever writes the disk,
+   * a mount nested in it by its directories alone, since its real root holds
+   * that root, can have the read serve a path in its directory, or the write
+   * land there.
    *
    * Text the host registers for a path (`registerGeneratedTextFile`) is
    * served there whatever the include says, since it isn't one of the
@@ -214,12 +294,8 @@ export interface MountConfig {
    * include covers it.
    *
    * Left out, the mount holds everything under its path. Given, it's a list
-   * of at least one string, each a name, an `*.ext` glob or a `dir/**` glob,
-   * whose directory may be nested (`a/b/**`). The module refuses a pattern
-   * with a `/` that isn't such a glob, a `*` anywhere but a leading `*.` or
-   * that trailing `/**`, an empty, `.` or `..` segment, and, where `\` is the
-   * platform's separator, a `\`. Any other pattern is a file name, matched
-   * literally, so `[id].tsx` names the file of that name.
+   * of at least one pattern, and the module refuses one `ignore` would
+   * refuse but for a `[`.
    */
   include?: string[];
   /**
@@ -290,7 +366,8 @@ export interface MountConfig {
   /**
    * If true, writes/edits/deletes via the module's tools materialize to the
    * filesystem immediately (not just into Chronicle tree state). Required for
-   * any mount shared across agents as a communication channel — without it,
+   * any store-backed mount shared across agents as a communication channel (a
+   * direct mount's writes reach disk without it, and it's refused there) — without it,
    * another agent's watcher on the same directory sees nothing. The watcher
    * suppresses its own echoes, so this doesn't cause self-wake loops.
    */

package/src/modules/workspace/watcher.ts

@@ -126,10 +126,15 @@ export class MountWatcher {
       // another mount's directory, the mount's ignore list and editors' swap
       // and backup files. chokidar 4
       // compares a string given here with the whole absolute path, so the
-      // list itself would match nothing.
-      ignored: (path: string) => {
+      // list itself would match nothing. It asks without stats before it
+      // stats a path, asking again with them before it watches the path, and
+      // when a path it watches is removed. So where it gives no kind, no
+      // directory-only pattern matches: a directory one matches never passed
+      // the check with its stats, so it is never watched, and its removal
+      // never reported.
+      ignored: (path: string, stats?: Stats) => {
         const relative = this.toRelative(path);
-        return relative !== null && passedOverAt(relative, ignore, this.others) !== undefined;
+        return relative !== null && passedOverAt(relative, ignore, this.others, stats?.isDirectory() ?? false) !== undefined;
       },
       // Its filter for editors' files tested the whole path, so a directory
       // with a dot in its name hid every `*.swp` beneath it, and the walk

package/src/prose-drafts.ts

@@ -2,8 +2,9 @@
  * Held prose drafts: a resident's plain speech that was not sent.
  *
  * Plain speech is held back for reasons that are right in themselves: an
- * explicit send in the same round suppresses the round's prose (so a "sent
- * it" postscript is not posted twice), a turn may have no destination, and a
+ * explicit send suppresses plain speech aimed where it may have posted, in
+ * its round and the turn's later ones (so a "sent it" postscript is not
+ * posted twice), a turn may have no destination, and a
  * malformed or unresolvable routing prefix bounces. Before drafts, the held words were
  * kept only as a count (or, in explicit mode, as one in-memory latest-wins
  * clipboard): the law was right, and the penalty was amnesia. A draft keeps
@@ -53,7 +54,7 @@ export const PROSE_DRAFT_RECORD_TYPE = 'framework/prose-draft';
 
 /** Why words were held instead of sent. */
 export type DraftReason =
-  /** An explicit send in the same round suppressed the round's plain speech. */
+  /** An explicit send in its turn may have posted where the speech was going. */
   | 'explicit-send'
   /** The speech had no destination (no route this turn, or a failed envelope). */
   | 'no-destination'

package/src/reasoning-loss-notice.ts

@@ -0,0 +1,62 @@
+import { safeSlice } from './safe-slice.js';
+
+export type ReasoningLossCause = 'tools' | 'system' | 'model';
+
+export type ReasoningLossAnchor = { text: string } | { toolCall: string };
+
+export interface ReasoningLossNoticeInput {
+  agentName: string;
+  scope:
+    | { kind: 'all'; through?: ReasoningLossAnchor; thisTurn: boolean }
+    | { kind: 'some'; count: number; first?: ReasoningLossAnchor; unplaced?: boolean; thisTurn: boolean };
+  causes: readonly ReasoningLossCause[];
+}
+
+const ANCHOR_CHARS = 80;
+
+const CAUSE_WORDS: Record<ReasoningLossCause, string> = {
+  tools: 'your tools changed',
+  system: 'your system prompt changed',
+  model: 'your model changed',
+};
+const CAUSE_ORDER: readonly ReasoningLossCause[] = ['tools', 'system', 'model'];
+
+export function reasoningLossNotice(input: ReasoningLossNoticeInput): string {
+  const causes = CAUSE_ORDER.filter((c) => input.causes.includes(c)).map((c) => CAUSE_WORDS[c]);
+  const because = causes.length > 0 ? `, because ${joinAnd(causes)}` : '';
+  const scope = input.scope;
+  let lost: string;
+  let reread: string;
+  if (scope.kind === 'all') {
+    const through = scope.through ? anchorWords(scope.through) : undefined;
+    const among = scope.thisTurn ? ", this turn's earlier steps among them," : '';
+    lost = through
+      ? `The reasoning behind your replies up to the one ${through}${among} is no longer in your context${because}.`
+      : `The reasoning behind your earlier replies${among} is no longer in your context${because}.`;
+    reread = 'Re-read before relying on an earlier decision.';
+  } else {
+    const one = scope.count === 1 && !scope.unplaced;
+    const replies = scope.unplaced
+      ? `at least ${scope.count} of your replies`
+      : one ? 'one of your replies' : `${scope.count} of your replies`;
+    const named = scope.first && !scope.unplaced ? anchorWords(scope.first) : undefined;
+    const first = named ? (one ? `, the one ${named}` : `, the first being the one ${named}`) : '';
+    const among = scope.thisTurn ? (one ? ', an earlier step of this turn' : ", this turn's earlier steps among them") : '';
+    lost = `Some of your earlier reasoning is no longer in your context: the reasoning behind ${replies}${first}${among}${because}.`;
+    reread = named ? 'Re-read before relying on a decision made since then.' : 'Re-read before relying on an earlier decision.';
+  }
+  return `[reasoning] ${input.agentName}: ${lost} Their words are still here. ${reread}`;
+}
+
+function anchorWords(anchor: ReasoningLossAnchor): string | undefined {
+  if ('toolCall' in anchor) return anchor.toolCall ? `that called \`${anchor.toolCall}\`` : undefined;
+  const text = anchor.text.replace(/\s+/g, ' ').trim();
+  if (!text) return undefined;
+  const clipped = text.length > ANCHOR_CHARS ? `${safeSlice(text, 0, ANCHOR_CHARS).trimEnd()}…` : text;
+  return `beginning "${clipped}"`;
+}
+
+function joinAnd(parts: readonly string[]): string {
+  if (parts.length <= 1) return parts.join('');
+  return `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+}

package/src/reasoning-loss.ts

@@ -0,0 +1,120 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import type { MessageId, ThinkingStrip } from '@animalabs/context-manager';
+import { ThinkingLossIncidents, type PlacedDrop } from './thinking-drops.js';
+import {
+  reasoningLossNotice,
+  type ReasoningLossAnchor,
+  type ReasoningLossCause,
+} from './reasoning-loss-notice.js';
+
+export interface StoredReplyReader {
+  getMessage(id: MessageId): { sequence: number; content: readonly ContentBlock[] } | null;
+}
+
+export interface ReasoningLossTurn {
+  start?: { branch: string; sequence: number };
+}
+
+const HEAD_CAUSES: Partial<Record<NonNullable<ThinkingStrip['changed']>[number], ReasoningLossCause>> = {
+  tools: 'tools',
+  system: 'system',
+  model: 'model',
+};
+
+export class ReasoningLossTeller {
+  private readonly told = new Map<string, Map<string, Set<MessageId>>>();
+  private readonly drops = new ThinkingLossIncidents();
+
+  forStrip(
+    agentName: string,
+    branch: string,
+    strip: ThinkingStrip,
+    turn: ReasoningLossTurn,
+    store: StoredReplyReader,
+  ): string | undefined {
+    const told = this.toldFor(agentName, branch);
+    const taken = strip.newly
+      .map((id) => ({ id, sequence: store.getMessage(id)?.sequence }))
+      .sort((a, b) => (a.sequence ?? Infinity) - (b.sequence ?? Infinity));
+    const replies = taken.filter((r) => !told.has(r.id));
+    if (replies.length === 0) return undefined;
+    const thisTurn = replies.some((r) => isThisTurn(r.sequence, branch, turn));
+    if (strip.cause === 'head') {
+      const causes = (strip.changed ?? [])
+        .map((c) => HEAD_CAUSES[c])
+        .filter((c): c is ReasoningLossCause => c !== undefined);
+      const newest = taken.filter((r) => r.sequence !== undefined).at(-1);
+      const through = newest ? anchorOf(store.getMessage(newest.id)?.content) : undefined;
+      const amongThisTurn = taken.some((r) => isThisTurn(r.sequence, branch, turn));
+      for (const r of replies) told.add(r.id);
+      return reasoningLossNotice({ agentName, scope: { kind: 'all', ...(through ? { through } : {}), thisTurn: amongThisTurn }, causes });
+    }
+    if (strip.cause !== 'first' && !taken.some((r) => isThisTurn(r.sequence, branch, turn))) return undefined;
+    const first = anchorOf(store.getMessage(replies[0]!.id)?.content);
+    for (const r of replies) told.add(r.id);
+    return reasoningLossNotice({
+      agentName,
+      scope: { kind: 'some', count: replies.length, ...(first ? { first } : {}), thisTurn },
+      causes: [],
+    });
+  }
+
+  forDrops(
+    agentName: string,
+    branch: string,
+    placed: readonly PlacedDrop[],
+    turn: ReasoningLossTurn,
+    store: StoredReplyReader,
+  ): string | undefined {
+    const replies = new Map<MessageId, number>();
+    const rounds = new Set<number>();
+    let blocks = 0;
+    for (const drop of placed) {
+      if (drop.kind === 'unplaced') continue;
+      blocks++;
+      if (drop.kind === 'round') rounds.add(drop.round);
+      else for (const body of drop.bodies) replies.set(body.messageId, body.sequence);
+    }
+    const unplaced = blocks < placed.length;
+    const count = replies.size + rounds.size;
+    const ordered = [...replies].sort((a, b) => a[1] - b[1]);
+    const thisTurn = rounds.size > 0 || ordered.some(([, sequence]) => isThisTurn(sequence, branch, turn));
+    const first = ordered.length > 0 && !unplaced ? anchorOf(store.getMessage(ordered[0]![0])?.content) : undefined;
+    if (this.drops.observe(agentName, blocks, branch) === undefined) return undefined;
+    const told = this.toldFor(agentName, branch);
+    for (const id of replies.keys()) told.add(id);
+    return reasoningLossNotice({
+      agentName,
+      scope: { kind: 'some', count, ...(first ? { first } : {}), ...(unplaced ? { unplaced: true } : {}), thisTurn },
+      causes: [],
+    });
+  }
+
+  forget(agentName: string): void {
+    this.told.delete(agentName);
+    this.drops.forget(agentName);
+  }
+
+  private toldFor(agentName: string, branch: string): Set<MessageId> {
+    let branches = this.told.get(agentName);
+    if (!branches) this.told.set(agentName, (branches = new Map()));
+    let told = branches.get(branch);
+    if (!told) branches.set(branch, (told = new Set()));
+    return told;
+  }
+}
+
+function isThisTurn(sequence: number | undefined, branch: string, turn: ReasoningLossTurn): boolean {
+  return sequence !== undefined && turn.start?.branch === branch && sequence > turn.start.sequence;
+}
+
+function anchorOf(content: readonly ContentBlock[] | undefined): ReasoningLossAnchor | undefined {
+  if (!content) return undefined;
+  for (const block of content) {
+    if (block.type === 'text' && typeof block.text === 'string' && block.text.trim() !== '') return { text: block.text };
+  }
+  for (const block of content) {
+    if (block.type === 'tool_use' && typeof block.name === 'string' && block.name !== '') return { toolCall: block.name };
+  }
+  return undefined;
+}

package/src/send-tools.ts

@@ -2,8 +2,9 @@
  * Tools whose call delivers the resident's message to a channel or person,
  * by bare name (an MCPL server's `<prefix>--` stripped). The framework reads
  * a call of one as an explicit send that silences the round's auto-routed
- * prose; the history module's semantic index reads its message argument as
- * what the resident wrote to someone, whether or not it was delivered.
+ * prose where it may have posted; the history module's semantic index reads
+ * its message argument as what the resident wrote to someone, whether or not
+ * it was delivered.
  */
 export const SEND_TOOLS = new Set(['channel_publish', 'send_message', 'reply_message', 'send_dm']);