@animalabs/agent-framework 0.32.0 → 0.34.0

package/src/send-tools.ts

@@ -1,12 +1,45 @@
 /**
- * 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 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.
+ * Tools whose call carries the resident's words, by bare name (an MCPL
+ * server's `<prefix>--` stripped); edit_message's words are the new text of a
+ * message it sent. The framework reads a call of a `silences` one as an
+ * explicit send that silences the round's auto-routed prose where it may have
+ * posted; the history module reads the words of any of them as what the
+ * resident wrote to someone, whether or not it was delivered. With prose
+ * routing disabled the resident speaks through these.
  */
-export const SEND_TOOLS = new Set(['channel_publish', 'send_message', 'reply_message', 'send_dm']);
+const SPEECH_TOOLS: ReadonlyMap<string, { words: readonly string[]; silences: boolean }> = new Map([
+  // channel_publish still takes `text` from older callers.
+  ['channel_publish', { words: ['content', 'text'], silences: true }],
+  // telegram-mcpl's send_message takes `message`.
+  ['send_message', { words: ['content', 'message', 'text'], silences: true }],
+  ['reply_message', { words: ['content', 'text'], silences: true }],
+  ['send_dm', { words: ['content', 'text'], silences: true }],
+  // telegram-mcpl's reply, file send, scheduled send and poll.
+  ['reply_to_message', { words: ['text'], silences: true }],
+  ['send_file', { words: ['caption'], silences: false }],
+  ['send_scheduled_message', { words: ['message'], silences: false }],
+  ['create_poll', { words: ['question'], silences: false }],
+  // telegram-mcpl's edit_message takes `new_text`.
+  ['edit_message', { words: ['content', 'new_text', 'text'], silences: false }],
+  // slack-mcpl's upload_file posts `comment` with the file; its `content` is
+  // the file.
+  ['upload_file', { words: ['comment'], silences: false }],
+  // Eidoverse's say and whisper take `text`.
+  ['say', { words: ['text'], silences: true }],
+  ['whisper', { words: ['text'], silences: true }],
+]);
+
+export const SILENCING_SENDS = new Set([...SPEECH_TOOLS].filter(([, tool]) => tool.silences).map(([name]) => name));
 
 /** Strip the `server--` MCPL prefix from a tool name. */
 export const bareToolName = (n: string): string => n.split('--').pop()!;
+
+export function speechOf(name: unknown, input: unknown): { tool: string; words: string } | undefined {
+  if (typeof name !== 'string' || typeof input !== 'object' || input === null) return undefined;
+  const tool = bareToolName(name);
+  const row = SPEECH_TOOLS.get(tool);
+  if (!row) return undefined;
+  const args = input as Record<string, unknown>;
+  const words = row.words.map((arg) => args[arg]).find((value) => value !== undefined && value !== null);
+  return typeof words === 'string' && words.trim().length > 0 ? { tool, words } : undefined;
+}

package/src/sent-rows.ts

@@ -152,7 +152,7 @@ export function roundRows(
  * the two alike (read from the provider on 2026-10-23: Haiku 5.5 with the drop control, on an enforcing API-key
  * organization and on a subscription account, reported no drop for either, and dropped both replies' blocks when an
  * earlier user message changed). The store's own fields beside them, such as
- * `toolName`, don't reach the provider on membrane's native path, the only one noted (membrane 0.8.0's XML
+ * `toolName`, don't reach the provider on membrane's native path, the only one noted (membrane 0.8.0's and 0.9.0's XML
  * formatter reads `toolName`, and an XML stream is never noted).
  */
 function normalizedResult(block: ContentBlock): unknown {

package/src/stored-injections.ts

@@ -14,8 +14,8 @@
  * a start stored whose compile then didn't record) has the same content,
  * every part of it, and the compile
  * then renders
- * it from the store like any message, where it stays. While the window is
- * held (AgentFramework's slotHeldFrom), `compile()` places it instead. Being a
+ * it from the store like any message, where it stays. While the host is
+ * quiesced, `compile()` places it instead. Being a
  * message, it's history to the strategy: capped by its per-message bound,
  * sharded, selected by the budget and folded like any other.
  *

package/src/stored-removal.ts

@@ -50,13 +50,14 @@ export function locateMessageIndices(
 
 /**
  * Inclusive slot range of the body-group run containing `index` (the slot
- * itself when it is not sharded). Delegates to the store's own
- * `alignToBodyGroups` edge walk — one contiguity assumption, not two.
+ * itself when it is not sharded), and the ids of its rows in store order.
+ * Delegates to the store's own `alignToBodyGroups` edge walk — one
+ * contiguity assumption, not two.
  */
 export function bodyGroupRun(
   cm: SurgeryReadableCm,
   index: number,
-): { from: number; to: number; fromId: string; toId: string; group: boolean } {
+): { from: number; to: number; fromId: string; toId: string; group: boolean; ids: MessageId[] } {
   const win = cm.getMessageWindow(index, 1, { alignToBodyGroups: true, resolveBlobs: false });
   const from = win.startIndex;
   const to = win.startIndex + win.messages.length - 1;
@@ -66,6 +67,7 @@ export function bodyGroupRun(
     fromId: String(win.messages[0].id),
     toId: String(win.messages[win.messages.length - 1].id),
     group: win.messages[0].bodyGroupId !== undefined,
+    ids: win.messages.map((m) => String(m.id) as MessageId),
   };
 }
 
@@ -90,23 +92,45 @@ export function removeStoredMessages(cm: Removals, first: StoredLike, last: Stor
  * Remove one stored message by its id, with the rest of its body when it's
  * in one: a module or a coalescer removes a message it added by the id
  * `addMessage` returned, which for a long message stored in shards is its
- * first shard's.
+ * first shard's. Returns the ids of every row it removed, in store order:
+ * the id given for a message outside any body, each shard's for a body, so
+ * a caller can take them out of the windows of the other agents that held
+ * them (#291).
  */
-export function removeStoredMessage(cm: ContextManager, id: MessageId): void {
+export function removeStoredMessage(cm: ContextManager, id: MessageId): MessageId[] {
   const message = cm.getMessage(id) as StoredLike | null;
   if (!message?.bodyGroupId) {
     cm.removeMessage(id);
-    return;
+    return [id];
   }
   // Found in blob-free windows: a full read of the branch would inflate every
   // attachment on it, once for each message a sweep removes.
   const index = locateMessageIndex(cm, String(id));
   if (index < 0) {
     cm.removeMessage(id);
-    return;
+    return [id];
   }
   const run = bodyGroupRun(cm, index);
   cm.removeMessages(run.fromId as MessageId, run.toId as MessageId);
+  return run.ids;
+}
+
+/**
+ * The ids of the stored messages `firstId`..`lastId` (inclusive, in store
+ * order, every shard of a body), read before a removal of that interval so
+ * the caller knows what it took. Both ends are found tail-first and the
+ * rows between them read in one blob-free window. Empty when either end is
+ * not on the active branch; the ends may be given in either order.
+ */
+export function storedIdsBetween(cm: SurgeryReadableCm, firstId: string, lastId: string): MessageId[] {
+  const found = locateMessageIndices(cm, new Set([firstId, lastId]));
+  const first = found.get(firstId);
+  const last = found.get(lastId);
+  if (!first || !last) return [];
+  const from = Math.min(first.index, last.index);
+  const to = Math.max(first.index, last.index);
+  const { messages } = cm.getMessageWindow(from, to - from + 1, { resolveBlobs: false });
+  return messages.map((m) => String(m.id) as MessageId);
 }
 
 /** removeStoredMessages for an interval known by its ids. */

package/src/supplied-text.ts

@@ -5,7 +5,7 @@
  * a line that reads as the framework's own.
  */
 
-import { CONTEXT_MANAGER_TAGS, MEMBRANE_TAGS, NOTICE_TAG } from './notice-tags.js';
+import { CONTEXT_MANAGER_TAGS, FORMER_NOTICE_TAGS, MEMBRANE_TAGS, NOTICE_TAG } from './notice-tags.js';
 
 /** Every form of line break a reader might take for one: CR LF, CR, LF,
  *  vertical tab, form feed, NEL, and the Unicode line and paragraph separators. */
@@ -27,14 +27,14 @@ const SKIPPED = `[\\s\\p{Cc}${INVISIBLE}]`;
 const tagWord = (word: string): string =>
   [...word].map((c) => (/[\\^$.*+?()[\]{}|/]/.test(c) ? `\\${c}` : c)).join(`${SKIPPED}*`);
 const NOTICE_OPENING = new RegExp(
-  `\\[(?=${SKIPPED}*(?:${[...Object.values(NOTICE_TAG), ...CONTEXT_MANAGER_TAGS, ...MEMBRANE_TAGS].map((tag) => tag.split(' ').map(tagWord).join(`${SKIPPED}+`)).join('|')})(?![\\p{L}\\p{N}]))`,
+  `\\[(?=${SKIPPED}*(?:${[...Object.values(NOTICE_TAG), ...FORMER_NOTICE_TAGS, ...CONTEXT_MANAGER_TAGS, ...MEMBRANE_TAGS].map((tag) => tag.split(' ').map(tagWord).join(`${SKIPPED}+`)).join('|')})(?![\\p{L}\\p{N}]))`,
   'giu',
 );
 
 /**
  * Texts read as one string, joined by line breaks, with a backslash put
  * before the bracket of each opening of a listed tag (NOTICE_TAG,
- * CONTEXT_MANAGER_TAGS, MEMBRANE_TAGS) that hasn't one before it in its own
+ * FORMER_NOTICE_TAGS, CONTEXT_MANAGER_TAGS, MEMBRANE_TAGS) that hasn't one before it in its own
  * text. A text `marks` says false of is read and never changed.
  *
  * Every opening, not only one that starts a line: membrane's XML formatter

package/src/thinking-drops.ts

@@ -34,6 +34,8 @@ export interface StreamThinkingDrops {
   place: (entries: readonly ThinkingBindingEntry[]) => PlacedDrop[];
   recordedAfter?: number;
   branch?: string;
+  /** `StartStreamResult`'s `noteThinkingDropped`. */
+  noteDropped?: (messageIds: readonly MessageId[]) => boolean;
 }
 
 /** A signed block's identity on the wire: a thinking block's signature, a redacted block's data. */

package/src/tool-presentation.ts

@@ -3,6 +3,7 @@ import { constants, fchmodSync, closeSync, fstatSync, lstatSync, openSync, readS
 import { closestNames } from './closest-names.js';
 import { boundedErrorMessage, errorMessage } from './error-message.js';
 import type { ToolDefinition, ToolResult } from './types/events.js';
+import { appendAll } from './append-all.js';
 
 export interface ToolPresentationConfig {
   /** Absolute path to shared editable JSON. Missing file means no overrides. */
@@ -36,6 +37,8 @@ const MAX_DESCRIPTION_CHARS = 32768;
 const protectedNames = new Set(['set_tool_visibility', 'set_tool_description', 'workspace--read', 'toolsets--open', 'toolsets--act', 'toolsets--look', 'toolsets--close']);
 export const isPresentationTool = (name: string): boolean => name === 'set_tool_visibility' || name === 'set_tool_description';
 const hash = (value: string): string => createHash('sha256').update(value).digest('hex');
+/** The catalogue's line layout, folded into its revision so a line reference saved under an earlier layout reads as stale. Raise it with any change to where the catalogue's lines fall. */
+const CATALOGUE_LAYOUT = 2;
 
 /**
  * A presentation or defaults file this host can't use. Each problem is a
@@ -61,9 +64,9 @@ const characters = (text: string): number => [...text].length;
 /** A text's first `n` characters, never splitting a code point. */
 const firstCharacters = (text: string, n: number): string => [...text].slice(0, n).join('');
 
-/** A name as a message quotes it: whole up to 60 characters, and past that cut, with its length, since a file can hold a key of any size. */
-function quoted(name: string): string {
-  return characters(name) <= 60 ? JSON.stringify(name) : `${JSON.stringify(firstCharacters(name, 57))}... (${count(characters(name))} characters)`;
+/** A text as a message quotes it: whole up to `limit` characters, and past that cut, with its length, since a file can hold a key, and a tool a description, of any size. */
+function quoted(name: string, limit = 60): string {
+  return characters(name) <= limit ? JSON.stringify(name) : `${JSON.stringify(firstCharacters(name, limit - 3))}... (${count(characters(name))} characters)`;
 }
 
 /** A file's problem as a message quotes it: its own clauses whole, and anything else bounded, since nobody wrote that text for its reader. */
@@ -246,7 +249,7 @@ export class ToolPresentation {
       return {name:tool.name,source:sources.get(tool.name) ?? 'Unattributed',visible:override?.visible ?? true,originalDescription:tool.description,description,descriptionSource,inputSchema:structuredClone(tool.inputSchema)};
     });
     const available = tools.map((tool,i) => ({...structuredClone(tool),description:entries[i].description}));
-    return {revision:hash(JSON.stringify({raw,entries,diagnostics})),source:this.config.path,cataloguePath:this.config.cataloguePath,diagnostics,available,
+    return {revision:hash(JSON.stringify({layout:CATALOGUE_LAYOUT,raw,entries,diagnostics})),source:this.config.path,cataloguePath:this.config.cataloguePath,diagnostics,available,
       advertised:available.filter((_,i)=>entries[i].visible),entries};
   }
   edit(tool: string, input: unknown, available: ToolDefinition[]): ToolResult {
@@ -336,7 +339,7 @@ export class ToolPresentation {
     const name = args.name as string;
     if (!available.some((t) => t.name === name)) {
       const near = closestNames(name, available.map((t) => t.name));
-      throw new PresentationRefusal(`Nothing was changed: no tool named ${quoted(name)} is available to you.${near.length ? ` Did you mean ${quotedList(near, 'or', JSON.stringify)}?` : ''}`
+      throw new PresentationRefusal(`Nothing was changed: you have no tool named ${quoted(name)} right now, shown or hidden.${near.length ? ` Did you mean ${quotedList(near, 'or', JSON.stringify)}?` : ''}`
         + ` Copy the exact name from your tool catalogue's index, workspace--read {"path":${JSON.stringify(this.config.cataloguePath)},"limit":140}, reading on with "offset" if the index runs past that.`);
     }
     if (field === 'description' && typeof args.description === 'string' && characters(args.description) > MAX_DESCRIPTION_CHARS)
@@ -346,6 +349,11 @@ export class ToolPresentation {
     return name;
   }
 }
+const SUMMARY_CHARACTERS = 200;
+function summaryOf(description: string): string {
+  const first = description.split(/\r\n|[\n\v\f\r\x85\u2028\u2029]/).find(line => line.trim() !== '');
+  return first === undefined ? '' : `: ${quoted(first, SUMMARY_CHARACTERS)}`;
+}
 export function renderCatalogue(snapshot: PresentationSnapshot): string {
   const groups = new Map<string, PresentationSnapshot['entries']>();
   for (const entry of snapshot.entries) {
@@ -360,12 +368,22 @@ export function renderCatalogue(snapshot: PresentationSnapshot): string {
     'Visible = not hidden by you: in your tool list, unless the host keeps it in its "settings" toolset or a server\'s tab (toolsets--look shows those). Hidden = moved into the "settings" toolset, or its MCPL server\'s tab: toolsets--look shows it, toolsets--act calls it once that toolset is open.',
     'These are your visibility choices, not fixed primary/secondary rankings.',
     'Copy exact names from the index; similar-sounding names may not exist.',
+    'Index by source: line N.',
     'Show a hidden tool: set_tool_visibility {"name":"EXACT_NAME","visible":true}.',
     `Read details: workspace--read {"path":${JSON.stringify(snapshot.cataloguePath)},"offset":LINE,"limit":LINES}.`,
     'Line references below belong to this revision; reread the index after changes.', '',
   ];
+  const indexLineAt = lines.indexOf('Index by source: line N.');
   // One line each: a quoted parse error can hold the file's own line breaks.
   for (const diagnostic of snapshot.diagnostics) lines.push('Diagnostic: '+diagnostic.replace(/\r\n|\r|\n/g, '\\n'));
+  const hidden = snapshot.entries.filter(e => !e.visible);
+  const hiddenAt = new Map<string, number>();
+  if (hidden.length) {
+    lines.push(`## Hidden (${hidden.length})`, '');
+    for (const entry of hidden) {hiddenAt.set(entry.name, lines.length); lines.push('');}
+    lines.push('');
+  }
+  lines[indexLineAt] = `Index by source: line ${lines.length + 1}.`;
   lines.push('## Index by source', '');
   const index = new Map<string, number>();
   for (const [source, entries] of groups) {
@@ -378,11 +396,18 @@ export function renderCatalogue(snapshot: PresentationSnapshot): string {
     lines.push(`### ${source}`, '');
     for (const entry of entries) {
       const start = lines.length + 1;
-      lines.push(`#### ${entry.name} (${entry.visible?'visible':'hidden'})`, '',
-        ...entry.description.split('\n'), '', `Description from: ${entry.descriptionSource ?? 'installed component'}`, '', `Schema: ${JSON.stringify(entry.inputSchema)}`);
-      if(entry.description!==entry.originalDescription) lines.push('', 'Original description:', ...entry.originalDescription.split('\n'));
+      lines.push(`#### ${entry.name} (${entry.visible?'visible':'hidden'})`, '');
+      appendAll(lines, entry.description.split('\n'));
+      lines.push('', `Description from: ${entry.descriptionSource ?? 'installed component'}`, '', `Schema: ${JSON.stringify(entry.inputSchema)}`);
+      if(entry.description!==entry.originalDescription) {
+        lines.push('', 'Original description:');
+        appendAll(lines, entry.originalDescription.split('\n'));
+      }
       lines.push('');
-      lines[index.get(entry.name)!] = `- [${entry.visible?'visible':'hidden'}] ${entry.name} — details: offset ${start}, limit ${lines.length-start+1}`;
+      const details = `details: offset ${start}, limit ${lines.length-start+1}`;
+      lines[index.get(entry.name)!] = `- [${entry.visible?'visible':'hidden'}] ${entry.name} — ${details}`;
+      const at = hiddenAt.get(entry.name);
+      if (at !== undefined) lines[at] = `- ${entry.name} (${entry.source})${summaryOf(entry.description)} — ${details}`;
     }
   }
   return lines.join('\n');

package/src/tool-result-guard.ts

@@ -7,6 +7,7 @@ import { ensureStateRegistered } from './module-registry.js';
 import { classifyBlock } from './mcpl/references.js';
 import { resultClaimsOf, rfc005TextOf, toolResultDataToHistoryString } from './tool-result-history.js';
 import { safeSlice } from './safe-slice.js';
+import { asOwnRow, presentLandedThenRethrow } from './dendrite/audience.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
 export type WithheldNoticeKind = 'ran' | 'refused' | 'error';
@@ -195,6 +196,16 @@ export class ToolResultGuard {
 
   get enabled(): boolean { return this.override ?? this.configured; }
   setHost(host: WithheldHost | undefined): void { this.host = host; }
+
+  /** Where the results message is told of once stored (the agent's own-row sink, Agent.setOwnRowSink). */
+  private ownRowSink?: (ids: readonly MessageId[]) => void;
+  /**
+   * Install where storeResults tells of the results message it stores, once
+   * the add has returned (the presentation index presents it in the agent's
+   * window then, #291), or take it off with undefined. An idempotent retry
+   * of a batch already staged stores nothing and tells nothing.
+   */
+  setOwnRowSink(sink: ((ids: readonly MessageId[]) => void) | undefined): void { this.ownRowSink = sink; }
   /** Settles once every annotation started so far has finished: each of
    *  those stubs has been edited to say where its original is, or its edit
    *  failed and waits in the storage queue, retried in order until it lands
@@ -343,7 +354,9 @@ export class ToolResultGuard {
 
   /** `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). */
+   *  its message's bound sets it (toolResultShare, tool-image-ledger.ts).
+   *  The results are the agent's own row, stamped so (asOwnRow) on top of
+   *  the caller's `metadata`, guarded or not. */
   storeResults(
     content: ContentBlock[],
     wireResults: ToolResult[],
@@ -352,7 +365,17 @@ export class ToolResultGuard {
     /** Where what a stub keeps is cut. */
     keptCap: number | undefined,
   ): MessageId {
-    if (!this.enabled) return this.cm.addMessage('user', content, metadata);
+    metadata = asOwnRow(metadata, this.agentName);
+    if (!this.enabled) {
+      let id: MessageId;
+      try {
+        id = this.cm.addMessage('user', content, metadata);
+      } catch (error) {
+        presentLandedThenRethrow(error, this.agentName, this.ownRowSink, (row) => this.cm.getMessage(row) !== null);
+      }
+      this.ownRowSink?.([id]);
+      return id;
+    }
     if (this.pending) {
       // Idempotent for the same not-yet-submitted batch: a caller that
       // retries after a failure between staging and submission (e.g. a
@@ -392,9 +415,19 @@ export class ToolResultGuard {
     // chunk is ever summarized from the placeholder; released after the
     // settlement edit. Holds are in-memory only — a reopened manager has none,
     // which is correct since a reopened guard has no pending batch.
-    const messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
+    // A write that throws with rows of it stored presents them, as one that
+    // returned would be, and throws on with no batch pending, as before.
+    let messageId: MessageId;
+    try {
+      messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
+    } catch (error) {
+      presentLandedThenRethrow(error, this.agentName, this.ownRowSink, (row) => this.cm.getMessage(row) !== null);
+    }
     this.pending = { id, messageId, content, withheld, wireResults,
       branch: this.cm.currentBranch().name, submitted: false, durable: false, kept, notices };
+    // Told before the durability barrier below, so the sync that makes the
+    // audit durable carries the row's presentation too.
+    this.ownRowSink?.([messageId]);
     // Durability barrier: the audit must reach Chronicle's chain heads before
     // the originals can go to a provider. On a failed sync the batch fails
     // CLOSED: the placeholders go on the wire instead (the turn continues,
@@ -575,8 +608,9 @@ export class ToolResultGuard {
         let deadlineSpent = false;
         for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
-          // Once the store has left the batch's branch (a rollback, an undo, a
-          // host's switch), write no more. This result and every later one is
+          // Once the store has left the batch's branch (a rollback, a
+          // suppression, a host's switch; an undo moves no branch), write no
+          // more. This result and every later one is
           // skipped, and its original stays in the audit record. Nothing
           // yields from here to the edit's own branch check, so while the
           // store is away the stub stays as it is. A write already under way
@@ -606,8 +640,8 @@ export class ToolResultGuard {
           // Declined where it would have committed, since the workspace had
           // left the batch's branch. Nothing was written, and no more are, as
           // for the results the branch check above stops. If the branch is
-          // back by the edit, as after an undo and a redo, the stubs of this
-          // result and the later ones name the audit record.
+          // back by the edit, as after a host's switch away and back, the stubs
+          // of this result and the later ones name the audit record.
           if (spill && 'skipped' in spill && spill.skipped === 'branch_changed') branchLeft = true;
           // A batch that used its deadline is said once, here, where the
           // batch is known; the host returns the skip without a line.