@animalabs/agent-framework 0.31.0 → 0.33.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/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/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.