@animalabs/agent-framework 0.32.0 → 0.33.0

package/src/modules/history/semantic.ts

@@ -15,14 +15,14 @@
  *    its creation time is the only monotonic signal). Both watermarks are
  *    kept in the module's state, which follows the store's branches, so each
  *    branch sends its own messages and summaries. A branch made at an earlier
- *    point, as an undo makes one, mints summary ids its parent already used,
- *    so a summary is keyed `sum:<id>@<created>`.
+ *    point, as a rollback makes one, mints summary ids its parent already
+ *    used, so a summary is keyed `sum:<id>@<created>`.
  *
  * What gets embedded per message: text blocks verbatim, plus the string
  * arguments of the agent's private-prose tools (think / journal / skip_reply
  * / private_note) labelled `[think] …` — that is the resident's own diary and
- * is exactly what "what did I think about X" should find. The message
- * argument of the send tools and edit_message, labelled by tool, such as
+ * is exactly what "what did I think about X" should find. The words of a
+ * speech tool's call (send-tools.ts), labelled by tool, such as
  * `[send_message] …`, since with prose routing disabled the resident speaks
  * through them.
  * tool_result payloads, other tool arguments, thinking blocks and media are
@@ -35,7 +35,7 @@
 import type { ContextManager, StoredMessage } from '@animalabs/context-manager';
 import type { ContentBlock } from '@animalabs/membrane';
 import { safeSlice } from '../../safe-slice.js';
-import { SEND_TOOLS, bareToolName } from '../../send-tools.js';
+import { speechOf } from '../../send-tools.js';
 import { storedInjectionMarkOf } from '../../stored-injections.js';
 
 export interface SemanticIndexConfig {
@@ -137,12 +137,6 @@ export interface SearchResponse {
 }
 
 const PRIVATE_PROSE_TOOLS = new Set(['think', 'journal', 'skip_reply', 'private_note']);
-/**
- * Tools whose message argument is what the resident said: the send tools,
- * and edit_message, whose argument is the new text of a message it sent.
- * With prose routing disabled the resident speaks through these.
- */
-const SPEECH_TOOLS = new Set([...SEND_TOOLS, 'edit_message']);
 
 /**
  * The semantic index service's failure, said of the service alone: it didn't
@@ -302,8 +296,10 @@ function isHit(hit: unknown): boolean {
   return isObject(hit) && typeof (hit as { id?: unknown }).id === 'string';
 }
 
+export const ERROR_MARK = ', error';
+
 /** Text to embed for one message, or '' when there is nothing worth indexing. */
-export function messageIndexText(msg: StoredMessage, includePrivateTools = true): string {
+export function messageIndexText(msg: StoredMessage, includePrivateTools = true, failed: ReadonlySet<string> = new Set()): string {
   const parts: string[] = [];
   for (const block of msg.content as ContentBlock[]) {
     if (block.type === 'text' && typeof block.text === 'string') {
@@ -313,12 +309,9 @@ export function messageIndexText(msg: StoredMessage, includePrivateTools = true)
       for (const v of Object.values(input)) {
         if (typeof v === 'string' && v.trim().length > 0) parts.push(`[${block.name}] ${v}`);
       }
-    } else if (block.type === 'tool_use' && SPEECH_TOOLS.has(bareToolName(block.name))) {
-      // Only the message: the other arguments are ids, topics and names.
-      // channel_publish still takes `text` from older callers.
-      const input = (block as { input?: { content?: unknown; text?: unknown } }).input ?? {};
-      const v = input.content ?? input.text;
-      if (typeof v === 'string' && v.trim().length > 0) parts.push(`[${bareToolName(block.name)}] ${v}`);
+    } else if (block.type === 'tool_use') {
+      const said = speechOf(block.name, (block as { input?: unknown }).input);
+      if (said) parts.push(`[${said.tool}${failed.has(block.id) ? ERROR_MARK : ''}] ${said.words}`);
     }
   }
   return parts.join('\n').trim();
@@ -705,9 +698,10 @@ export class SemanticIndexer {
           if (budget <= 0) break;
           this.editedIds.delete(id);
           const m = this.cm.getMessage(id as never);
-          // Not on the current branch (e.g. /undo after the edit): drop it,
-          // never delete — /redo brings the message back and the time walk
-          // will not revisit it. Search-time branch checks hide it meanwhile.
+          // Not on the current branch (e.g. a rollback after the edit): drop
+          // it, never delete — a switch back to the branch that holds it
+          // brings the message back and the time walk will not revisit it.
+          // Search-time branch checks hide it meanwhile.
           if (!m) continue;
           edited.push(id); budget--;
           const item = messageToItem(m, this.cfg);

package/src/modules/workspace/disk-agreement.ts

@@ -5,7 +5,7 @@
  *
  * P describes disk, and disk does not rewind with a branch switch, so P lives
  * in global chronicle records (RecordJournal) rather than branch state: after
- * an undo selects an older tree, P still says what disk holds, and a
+ * a rollback selects an older tree, P still says what disk holds, and a
  * difference reads as a store-side change, never as a disk edit. Branch-local
  * intent — tombstones, store origin, conflicts — lives in BranchIntents and
  * rewinds with the tree.

package/src/modules/workspace/index.ts

@@ -1052,6 +1052,12 @@ export class WorkspaceModule implements Module {
   /** Whether an agent's history holds a message, as the framework hands it over (useHistory). */
   private historyLookup: ((agentName: string, messageId: string) => boolean) | null = null;
 
+  /** Whether an agent's window still holds what it did after a place in the record, as the framework hands it over (useWindow). */
+  private windowLookup: ((agentName: string, afterSequence: number) => boolean) | null = null;
+
+  /** Whether a turn of an agent's is alive now, as the framework hands it over with the window lookup (useWindow). */
+  private turnLookup: ((agentName: string) => boolean) | null = null;
+
   constructor(config: WorkspaceConfig) {
     for (const mount of config.mounts) {
       const cap: unknown = mount.walkCap;
@@ -1228,8 +1234,13 @@ export class WorkspaceModule implements Module {
         carried.push(saved);
         continue;
       }
+      // An entry an earlier release saved (no `v`) doesn't say whether a
+      // turn made each write, and that release judged a position by the
+      // branch alone: so is it judged here (outsideTurn), so its head
+      // isn't taken for a later turn's.
+      const fromEarlier = saved.v === undefined;
       restored.set(saved.mount, new Map(Object.entries(saved.agents).map(([agent, head]) =>
-        [agent, { branchId: head.branchId, after: head.after, notice: head.notice ?? null }])));
+        [agent, { branchId: head.branchId, after: head.after, notice: head.notice ?? null, ...(head.outsideTurn || fromEarlier ? { outsideTurn: true as const } : {}) }])));
     }
     this.headsJournal = journal;
     this.loadedHeads = text;
@@ -1821,10 +1832,12 @@ export class WorkspaceModule implements Module {
     if (!this.headsJournal) return;
     const snapshot: DirectHeadsSnapshot = [
       ...this.carriedHeads,
-      ...[...this.directHeads].filter(([, heads]) => heads.size > 0).map(([name, heads]) => ({
+      ...[...this.directHeads].filter(([, heads]) => heads.size > 0).map(([name, heads]): DirectHeadsEntry => ({
         mount: name,
         root: resolve(this.mounts.get(name)!.config.path),
-        agents: Object.fromEntries([...heads].map(([agent, { branchId, after, notice }]) => [agent, { branchId, after, ...(notice !== null ? { notice } : {}) }])),
+        v: DIRECT_HEADS_VERSION,
+        agents: Object.fromEntries([...heads].map(([agent, { branchId, after, notice, outsideTurn }]) =>
+          [agent, { branchId, after, ...(notice !== null ? { notice } : {}), ...(outsideTurn ? { outsideTurn } : {}) }])),
       })),
     ];
     const text = canonicalHeads(snapshot);
@@ -5088,7 +5101,10 @@ export class WorkspaceModule implements Module {
    * changed meanwhile, the head moved under the call, and P is set there,
    * so the next start judges the deletion by the branch its turn was on,
    * unless the history doesn't hold P already, whose notice is owed. A write no agent
-   * made tells no one. The store's reads here come after the write landed,
+   * made tells no one. A write made while no turn of the agent's is alive (a
+   * host's executeToolCall naming it) is marked so (`outsideTurn`): no round
+   * of the agent's history made it, so the window can't say it was undone,
+   * and only the branch's position decides. The store's reads here come after the write landed,
    * so one that throws is logged and P stays, as for a history that can't
    * be read, and the write still answers that it landed.
    */
@@ -5100,12 +5116,13 @@ export class WorkspaceModule implements Module {
       if (!heads) this.directHeads.set(mount.config.name, (heads = new Map()));
       const head = heads.get(agentName);
       const branchId = store.currentBranch().id;
+      const outsideTurn = this.turnLookup?.(agentName) === false ? { outsideTurn: true as const } : {};
       if (since && since.branchId !== branchId) {
-        if (!head || this.historyHoldsWrites(agentName, head) === true) heads.set(agentName, { ...since, notice: null });
+        if (!head || this.historyHoldsWrites(agentName, head) === true) heads.set(agentName, { ...since, notice: null, ...outsideTurn });
         return;
       }
       if (head && this.historyHoldsWrites(agentName, head) !== true) return;
-      heads.set(agentName, { branchId, after: store.currentSequence(), notice: null });
+      heads.set(agentName, { branchId, after: store.currentSequence(), notice: null, ...outsideTurn });
     } catch (err) {
       console.error('[workspace] could not record a direct write\'s position:', err);
     }
@@ -5132,7 +5149,20 @@ export class WorkspaceModule implements Module {
    * leaves the next start to decide (headMoveNotice).
    */
   private historyHoldsWrites(agentName: string, head: DirectHead): boolean | null {
-    if (this.holdsPosition(head)) return true;
+    if (this.holdsPosition(head)) {
+      // The branch holds the write, but an undo on the agent's window (the
+      // framework's presentation index) moves no branch: it takes the turn
+      // that wrote out of the window, which the framework's lookup says. A
+      // write made outside any turn of the agent's has no turn to take out.
+      let held: boolean;
+      try {
+        held = head.outsideTurn === true || this.windowLookup?.(agentName, head.after) !== false;
+      } catch (err) {
+        console.error('[workspace] window lookup for the head-move notice failed:', err);
+        return null;
+      }
+      if (held) return true;
+    }
     if (head.notice === null) return false;
     try {
       return this.historyLookup?.(agentName, head.notice) === true;
@@ -5146,9 +5176,10 @@ export class WorkspaceModule implements Module {
    * Whether the store's current branch holds what came before a direct
    * write: it's the write's branch, or continues it with every fork point on
    * the way after `after`, the store's head when the write landed. A fork at
-   * exactly `after` doesn't: an undo forks at its turn's sequenceBefore,
-   * which is the head at the write when nothing was recorded in the turn
-   * before it. A missing branch or one without fork metadata holds nothing,
+   * exactly `after` doesn't: a rollback cut there (to the row the write
+   * followed) leaves the write out, as an undo's fork at its turn's
+   * sequenceBefore did before #291 (an undo moves no branch since). A
+   * missing branch or one without fork metadata holds nothing,
    * as for the materialize guard (isLinearContinuation).
    */
   private holdsPosition({ branchId, after }: DirectHead): boolean {
@@ -5201,14 +5232,31 @@ export class WorkspaceModule implements Module {
   }
 
   /**
-   * How the module asks whether an agent's history holds a message, as the
-   * framework judges its own notices (`cm.getMessage(id) !== null`): handed
-   * over once, when the module is added. Without it, no notice is held.
+   * How the module asks whether an agent's history holds a message: its
+   * record holds it, and, on a window the framework presents, no undo has
+   * taken it out of the window. Handed over once, when the module is added.
+   * Without it, no notice is held.
    */
   useHistory(lookup: (agentName: string, messageId: string) => boolean): void {
     this.historyLookup = lookup;
   }
 
+  /**
+   * How the module asks whether an agent's window still holds what the
+   * agent did after a place in the record (`afterSequence`, the store's head
+   * when it wrote a mount direct): false once an undo on its window took
+   * that turn out, though the branch still holds the write. Handed over
+   * once, by a framework with the presentation index. Without it, the
+   * branch's position alone decides. `turnAlive` says whether a turn of the
+   * agent's is alive at a write: one made outside any (a host's
+   * executeToolCall naming the agent) has no turn in the window, so the
+   * branch's position alone decides for it too.
+   */
+  useWindow(lookup: (agentName: string, afterSequence: number) => boolean, turnAlive?: (agentName: string) => boolean): void {
+    this.windowLookup = lookup;
+    this.turnLookup = turnAlive ?? null;
+  }
+
   private async handleDelete(input: DeleteInput, callerAgentName?: string): Promise<ToolResult> {
     const { mount, relativePath, path } = await this.parseFilePath(input.path).catch((error: unknown) => { throw notStored(error); });
     if (relativePath === '') return { success: false, error: didNothing('delete', namesRoot(input.path, mount.config.name)), isError: true };
@@ -6250,10 +6298,11 @@ export class WorkspaceModule implements Module {
     mount.lastMaterializedBranchId = null;
     mount.lastMaterializedSeq = 0;
 
-    // force: this path only runs after a deliberate undo/redo/branch switch
-    // on the framework's own _config mount — restoring disk to the branch
-    // state IS the operator intent, so the freshness guard yields. named:
-    // the whole tree is that deliberate scope, entries without evidence too.
+    // force: this path only runs after a deliberate branch switch, rollback
+    // or suppression on the framework's own _config mount — restoring disk
+    // to the branch state IS the operator intent, so the freshness guard
+    // yields. named: the whole tree is that deliberate scope, entries
+    // without evidence too.
     const pushed = await this.withMount(mount, () => {
       const branchId = store.currentBranch().id;
       return this.pushUnlocked(mount, store.treeList(mount.treeStateId).map((e) => e.path), { force: true, named: true, branchId });
@@ -6803,6 +6852,8 @@ interface DirectHead {
   branchId: string;
   after: number;
   notice: string | null;
+  /** Set where P was written while no turn of the agent's was alive (recordDirectWrite), or read from a record an earlier release saved, which doesn't say (loadDirectHeads): the window isn't asked of it. */
+  outsideTurn?: true;
 }
 
 /** A store position: a branch and its head. */
@@ -6811,11 +6862,20 @@ type DirectPosition = Pick<DirectHead, 'branchId' | 'after'>;
 /** The global record type directHeads is saved as: a checkpoint at a clean stop that changed it. */
 const DIRECT_HEADS_RECORD_TYPE = 'workspace/direct-heads';
 
+/**
+ * The saved entries' version: an entry this release saves carries it, and
+ * says of each position whether a turn of its agent's made it (`outsideTurn`
+ * where none did). An entry an earlier release saved has none.
+ */
+const DIRECT_HEADS_VERSION = 2;
+
 /** One mount's positions at one root (resolved, as DiskAgreement keeps a root), by agent, with N only where it's set. */
 interface DirectHeadsEntry {
   mount: string;
   root: string;
-  agents: Record<string, { branchId: string; after: number; notice?: string }>;
+  /** DIRECT_HEADS_VERSION, absent on an entry an earlier release saved. */
+  v?: typeof DIRECT_HEADS_VERSION;
+  agents: Record<string, { branchId: string; after: number; notice?: string; outsideTurn?: true }>;
 }
 
 /** directHeads as saved: an entry per mount and root its agents wrote direct under. */
@@ -6832,12 +6892,14 @@ function checkedHeads(value: unknown): DirectHeadsSnapshot {
   const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
   if (!Array.isArray(value)) throw new Error("the record isn't of the shape saved");
   for (const saved of value as unknown[]) {
-    if (!isObject(saved) || typeof saved.mount !== 'string' || typeof saved.root !== 'string' || !isObject(saved.agents)) {
+    if (!isObject(saved) || typeof saved.mount !== 'string' || typeof saved.root !== 'string' || !isObject(saved.agents)
+      || (saved.v !== undefined && saved.v !== DIRECT_HEADS_VERSION)) {
       throw new Error(`an entry isn't of the shape saved: ${JSON.stringify(saved)?.slice(0, 200)}`);
     }
     for (const [agent, head] of Object.entries(saved.agents)) {
       if (!isObject(head) || typeof head.branchId !== 'string' || typeof head.after !== 'number'
-        || (head.notice !== undefined && typeof head.notice !== 'string')) {
+        || (head.notice !== undefined && typeof head.notice !== 'string')
+        || (head.outsideTurn !== undefined && head.outsideTurn !== true)) {
         throw new Error(`agent ${JSON.stringify(agent)}'s position on mount ${JSON.stringify(saved.mount)} isn't of the shape saved`);
       }
     }
@@ -6847,9 +6909,9 @@ function checkedHeads(value: unknown): DirectHeadsSnapshot {
 
 /** A saved record's content, whatever order its mounts and agents were written in, to tell whether a save would change it. */
 function canonicalHeads(snapshot: DirectHeadsSnapshot): string {
-  return JSON.stringify(snapshot.map(({ mount, root, agents }) => [mount, root, Object.keys(agents).sort().map((agent) => {
-    const { branchId, after, notice } = agents[agent]!;
-    return [agent, branchId, after, notice ?? null];
+  return JSON.stringify(snapshot.map(({ mount, root, v, agents }) => [mount, root, v ?? null, Object.keys(agents).sort().map((agent) => {
+    const { branchId, after, notice, outsideTurn } = agents[agent]!;
+    return [agent, branchId, after, notice ?? null, outsideTurn === true];
   })]).sort((a, b) => {
     const [x, y] = [JSON.stringify(a.slice(0, 2)), JSON.stringify(b.slice(0, 2))];
     return x < y ? -1 : x > y ? 1 : 0;

package/src/notice-tags.ts

@@ -5,7 +5,13 @@
  * `[tag: …]` or `[tag …]`: text the framework didn't write is marked
  * wherever it would open with one of these (supplied-text.ts). A toolset's
  * `[server/toolset:instance]` label is built from its server's id and names
- * instead.
+ * instead, and so is a line of another agent's round as an agent that watches
+ * its slot is sent it (foreign-rounds.ts, #291): a bracket of the
+ * framework's around the tool's name, which the other agent supplied, and
+ * the call's input or the result's outcome. The line is marked as one text,
+ * so an opening of one of these tags is marked wherever it forms across it,
+ * the name included, while the framework's own words and placeholders in it
+ * stay unmarked.
  */
 export const NOTICE_TAG = {
   turnInterrupted: 'turn-interrupted',
@@ -39,6 +45,8 @@ export const NOTICE_TAG = {
   channelInvitation: 'Channel invitation',
   system: 'system',
   toolsets: 'toolsets',
+  wakeOnboarding: 'wake onboarding',
+  suppressionReview: 'suppression review',
   heartbeat: 'heartbeat',
   silentHeartbeat: 'silent heartbeat',
   heartbeatTick: 'heartbeat tick',
@@ -64,6 +72,7 @@ export const NOTICE_TAG = {
   truncated: 'truncated',
   cutToFit: 'cut to fit',
   blockNotShown: 'block not shown',
+  noText: 'no text',
 } as const;
 
 /**

package/src/operator-log.ts

@@ -1,8 +1,8 @@
 /**
  * Operator action log — a durable, append-only JSONL record of every
  * operator-initiated mutation of a live resident: branch rollbacks, message
- * suppressions, undo/redo/hide, unstick/nudge, runtime-settings changes,
- * host quiesce/resume. One file per store, next to the chronicle
+ * suppressions, branch checkouts (switchBranch), undo/redo/hide,
+ * unstick/nudge, runtime-settings changes, host quiesce/resume. One file per store, next to the chronicle
  * (`<storePath>/operator-actions.jsonl`), so it travels with backups and
  * survives host restarts the way `repair-receipts.jsonl` and
  * `watchdog-wedge.jsonl` do.
@@ -32,7 +32,7 @@ export interface OperatorRequester {
 export interface OperatorLogEntry {
   /** ISO-8601 wall-clock time of the record. */
   at: string;
-  /** Action kind, e.g. 'rollback', 'suppress', 'undo', 'hide', 'quiesce'. */
+  /** Action kind, e.g. 'rollback', 'suppress', 'checkout', 'undo-turn', 'hide', 'quiesce'. */
   kind: string;
   /** Agent the action targeted (absent for host-wide actions). */
   agent?: string;
@@ -167,6 +167,39 @@ export interface SurgeryMarksPreview {
   messagesRemoved: number;
   /** Removed messages that carry a Discord address at all. */
   addressable: number;
+  /**
+   * Of the messages removed, how many no live agent is shown (#291): no
+   * window holds them (stored and never presented to an agent, or taken out
+   * of every window since), or only windows whose view leaves them out (a
+   * row a tune-out holds, which a window written down from the record
+   * holds). Their marks tell Discord of messages no agent was being shown.
+   * A message that may be in a window that couldn't be read isn't counted,
+   * and is logged. Set only when the agent's context is presented.
+   */
+  neverPresented?: number;
+  /**
+   * For a rollback on a presented window: the rows after the target in the
+   * agent's window that the branch cut keeps in the record (stored before
+   * the write that presented the target, presented after it). They leave
+   * the window as arrived and not presented, and enter it again at the
+   * agent's next turn start, after what its window holds then; nothing at
+   * rest presents them before it (rollbackToMessage). An own row of the
+   * agent's among them re-enters at the surgery's release. The hold is in
+   * memory, so a restart before then presents them at its pass at rest.
+   * Not removed, so not counted in `messagesRemoved`, and not marked. Set
+   * only then.
+   */
+  returnedToArrivals?: number;
+  /**
+   * For a rollback on a presented window: the rows after the target in the
+   * agent's window that the write presenting the target presented too (a
+   * batch). The cut is at that write, so they stay in the window after the
+   * target. Not removed, so not counted in `messagesRemoved`, and not
+   * marked: a suppression, or, for those with a Discord message id, a hide
+   * by it, takes them out.
+   * Set only then.
+   */
+  keptInWindowAfterTarget?: number;
   emoji: string;
   scopes: Record<'addressed' | 'all', {
     count: number;