@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/agent.ts

@@ -1,3 +1,5 @@
+import { NOTICE_TAG } from './notice-tags.js';
+import { heartbeatToolAlias } from './heartbeat/heartbeat.js';
 import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, ThinkingBindingEntry, YieldingStream } from '@animalabs/membrane';
 import { isAbortedResponse } from '@animalabs/membrane';
 import type { CacheWireReceipt, KvUnifiedRequestHooks } from './kv-unified-wire.js';
@@ -97,10 +99,15 @@ export interface StartStreamResult {
   /** The compile's `thinkingRecordedAfter`, when it gave one: a reply stored at or below it predates the branch's
    *  thinking-binding record, so the provider may drop its thinking with no strip having missed. */
   thinkingRecordedAfter?: number;
+  /** The key (`branchKey`) of the branch the compile read, when its provenance names one. */
+  thinkingBranch?: string;
   /** Tells the context manager what the stream's later rounds carried after the compiled messages, every round so
    *  far in sent order, with this request's head (context-manager's `noteRequestSent`). Present only where the
    *  model binds its thinking and the context manager keeps a record it can be told of. */
   noteRequestSent?: (rows: readonly SentRow[]) => boolean;
+  /** The stored bodies the request's compile carried, by each body's first message id (its provenance's raw bodies).
+   *  Absent when the compile reports no provenance. */
+  carriedBodies?: ReadonlySet<MessageId>;
 }
 import type {
   ContextManager,
@@ -112,6 +119,7 @@ import type {
   MessageId,
   MessageMetadata,
   RequestIdentity,
+  ThinkingStrip,
 } from '@animalabs/context-manager';
 import type {
   AgentConfig,
@@ -257,8 +265,7 @@ export function resolveAutoContinue(config: AgentConfig): { maxConsecutive: numb
   return { maxConsecutive: max };
 }
 
-/** A branch's key in Agent.unsentSince: its id and when it was created. */
-function branchKey(branch: { readonly id: string; readonly created: number }): string {
+export function branchKey(branch: { readonly id: string; readonly created: number }): string {
   return `${branch.id}\u0000${branch.created}`;
 }
 
@@ -493,7 +500,13 @@ export class Agent {
     if (this.allowedTools === 'all') {
       return true;
     }
-    return this.allowedTools.includes(toolName);
+    if (this.allowedTools.includes(toolName)) return true;
+    // A heartbeat tool is one tool under either prefix: the framework's
+    // `heartbeat--x` and heartbeat-mcpl's `mcpl--heartbeat--x`, which an
+    // allowedTools written for the server names. Only one of them is ever
+    // offered, since the framework refuses the server beside its heartbeat.
+    const alias = heartbeatToolAlias(toolName);
+    return alias !== undefined && this.allowedTools.includes(alias);
   }
 
   /**
@@ -1176,8 +1189,9 @@ export class Agent {
     // Tolerates partial context-manager doubles (tests build Agents over
     // stubs). Without a watermark, a reader that looks for one takes its own
     // side: the coalescer counts the message as read, and the framework's
-    // unreadNoticesForPrimary counts it as unread. A deferred write's wake
-    // reads the answered watermark instead (deferredWriteDone).
+    // unreadNoticesForPrimary counts it as unread. A wake for a deferred
+    // write or a stored message reads the answered watermark instead
+    // (deferredWriteDone, storedMessageDone).
     this.consumedWatermark = this.pendingWatermark();
     this.watermarkMarks++;
     this.shownWatermark = this.consumedWatermark;
@@ -1225,6 +1239,21 @@ export class Agent {
     this.watermarkMarks++;
   }
 
+  /**
+   * The branch now (`branchKey`) and its head, as `pendingWatermark` reads it: a message stored on that branch later
+   * has a larger sequence. Sequences are numbered per branch, so one compares with another only on the same branch.
+   */
+  branchHead(): { branch: string; sequence: number } | undefined {
+    const head = this.pendingWatermark();
+    const cm = this.contextManager as Partial<ContextManager>;
+    if (!head || typeof cm.currentBranchRef !== 'function') return undefined;
+    try {
+      return { branch: branchKey(cm.currentBranchRef()), sequence: head.sequence };
+    } catch {
+      return undefined;
+    }
+  }
+
   /** The watermark a successful compile will establish (taken before, applied after). */
   private pendingWatermark(): { branch: string; sequence: number } | null {
     const cm = this.contextManager as Partial<ContextManager>;
@@ -1313,6 +1342,15 @@ export class Agent {
    */
   onCompiledToSend?: (messages: readonly unknown[]) => void;
 
+  /**
+   * A host's hook, called with each committing compile's `thinkingStrip` (never a dry run's) and the key of the
+   * branch it read (`branchKey`), as the compile returns, whether or not its request is then sent, since the
+   * context manager's binding record takes the strip either way. One that throws is logged. The framework sets it
+   * at the agent's first stream unless a host has set one, so a host's own observer stands in for the framework's,
+   * whose `[reasoning]` line for the agent then isn't told.
+   */
+  onThinkingStrip?: (strip: ThinkingStrip, branch: string) => void;
+
   /**
    * The newest content of `namespace` among this agent's rows stored since
    * its last compile built to send (unsentSince), and whether every part of
@@ -1516,6 +1554,13 @@ export class Agent {
       throw error;
     }
     if (watermark) this.applyCompileWatermark(watermark, marksBefore);
+    if (!opts?.dryRun && result.thinkingStrip && this.onThinkingStrip) {
+      try {
+        this.onThinkingStrip(result.thinkingStrip, result.provenance ? branchKey(result.provenance.branch) : '');
+      } catch (err) {
+        console.error(`[agent] ${this.name}: the host's thinking-strip observer failed:`, err);
+      }
+    }
     return result;
   }
 
@@ -2064,10 +2109,10 @@ export class Agent {
     // ran. The stream driver collects it on that stream's terminal event, or
     // at the loop's end when the iterator closed without one, while the
     // stream still owns the agent. This clear is for the records no driver
-    // collects: a dropped turn's, whose stream no driver iterates; one whose
-    // stream's terminal came after another stream took the agent; or a
-    // cancel after the stream's complete event. A fresh stream must not
-    // inherit one and read its own later error as a deliberate stop.
+    // collects: a cancel of a stream no driver iterates; one whose stream's
+    // terminal came after another stream took the agent; or a cancel after
+    // the stream's complete event. A fresh stream must not inherit one and
+    // read its own later error as a deliberate stop.
     this._pendingCancel = undefined;
     this._inferenceStartedAt = Date.now();
     this.lastStreamInputTokens = 0;
@@ -2146,7 +2191,11 @@ export class Agent {
       // Read against the messages the stream sends, which membrane's report indexes (RoundReport's coordinates).
       placeDrops: (entries) => placeThinkingDrops(entries, request.messages, compiled),
       ...this.requestNotes(binding, compiled),
+      ...(compiled.provenance
+        ? { carriedBodies: new Set(compiled.provenance.messages.flatMap((m) => m.kind === 'raw' ? m.bodies.map((b) => b.messageId) : [])) }
+        : {}),
       ...(compiled.recordedAfter !== undefined ? { thinkingRecordedAfter: compiled.recordedAfter } : {}),
+      ...(compiled.provenance ? { thinkingBranch: branchKey(compiled.provenance.branch) } : {}),
       ...(kvEnabled
         ? {
             takeKvSubmission: () => kvQueue.shift(),
@@ -2261,12 +2310,24 @@ export class Agent {
    * one is still ahead; otherwise the next start drops it. `reason` is
    * provenance for the framework's inference:aborted trace and marker
    * metadata (e.g. 'zombie_reclaim', 'subagent_cancel'); it never reaches
-   * the provider.
+   * the provider. When the stream's cancel() throws, the throw goes on to
+   * the caller, and the agent still holds the stream, its cancel record as
+   * it was before the call.
    */
   cancelStream(reason?: string): void {
     if ('stream' in this._state && this._state.stream) {
+      // A cancel that throws leaves the stream going and the agent holding
+      // it, so this call's record is taken back, leaving any earlier one: a
+      // later end of that stream, an `error` the provider reports included,
+      // is not read as this stop's.
+      const earlier = this._pendingCancel;
       this._pendingCancel = { reason };
-      this._state.stream.cancel();
+      try {
+        this._state.stream.cancel();
+      } catch (error) {
+        this._pendingCancel = earlier;
+        throw error;
+      }
     } else {
       this._stopWithoutStream = { reason };
     }
@@ -2338,7 +2399,9 @@ export class Agent {
     }
 
     const injectedText = systemInjections.map((block) =>
-      block.type === 'text' ? block.text : `[${block.type} block not shown: the system prompt carries text only.]`);
+      block.type === 'text'
+        ? block.text
+        : `[${NOTICE_TAG.blockNotShown}: ${/^[aeiou]/i.test(block.type) ? 'an' : 'a'} ${block.type} block; the system prompt carries text only.]`);
 
     return this.systemPrompt + '\n' + injectedText.join('\n');
   }
@@ -2442,6 +2505,7 @@ export class Agent {
           id: block.id,
           name: block.name,
           input: block.input,
+          ...(block.unparseableInput !== undefined ? { unparseableInput: block.unparseableInput } : {}),
         });
       } else if (block.type === 'text') {
         speechContent.push(block);

package/src/api/mcp-server-core.ts

@@ -12,7 +12,7 @@
  */
 
 import WebSocket from 'ws';
-import { createInterface } from 'node:readline';
+import { escapeLineSeparators, readLines } from '../line-reader.js';
 import type { ApiRequest, ApiResponse, ApiEvent } from './types.js';
 
 // ============================================================================
@@ -86,18 +86,7 @@ export class McpServer {
     // Connect to WebSocket API
     await this.connectWs();
 
-    // Set up stdio interface
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-      terminal: false,
-    });
-
-    rl.on('line', (line) => {
-      this.handleInput(line);
-    });
-
-    rl.on('close', () => {
+    readLines(process.stdin, (line) => this.handleInput(line), () => {
       this.close();
       process.exit(0);
     });
@@ -667,7 +656,7 @@ export class McpServer {
   }
 
   private send(message: JsonRpcResponse | JsonRpcNotification): void {
-    process.stdout.write(JSON.stringify(message) + '\n');
+    process.stdout.write(escapeLineSeparators(JSON.stringify(message)) + '\n');
   }
 
   close(): void {

package/src/api/server.ts

@@ -489,9 +489,13 @@ export class ApiServer {
     if (!params.participant || !params.content) {
       throw new Error('participant and content are required');
     }
-    // ApiModule stores the message as one text block, which context-manager
-    // refuses unless its text is a string, so content that isn't text is
-    // refused here, where the caller hears it, rather than at dispatch.
+    // ApiModule stores the participant as a name, and the message as one text
+    // block, which context-manager refuses unless its text is a string. So a
+    // participant or content that isn't text is refused here, where the
+    // caller hears it, rather than at dispatch.
+    if (typeof params.participant !== 'string') {
+      throw new Error('participant must be text');
+    }
     if (typeof params.content !== 'string') {
       throw new Error('content must be text');
     }
@@ -649,7 +653,8 @@ export class ApiServer {
       throw new Error('agentName is required');
     }
 
-    const result = this.framework.undoLastTurn(params.agentName);
+    const { settled, ...result } = this.framework.undoLastTurn(params.agentName);
+    await settled;
 
     if (result.undone) {
       this.broadcast('branch:switched', {
@@ -667,7 +672,8 @@ export class ApiServer {
       throw new Error('agentName is required');
     }
 
-    const result = this.framework.redo(params.agentName);
+    const { settled, ...result } = this.framework.redo(params.agentName);
+    await settled;
 
     if (result.redone) {
       this.broadcast('branch:switched', {

package/src/auto-continue.ts

@@ -5,6 +5,8 @@
  * row the next turn reads.
  */
 
+import { NOTICE_TAG } from './notice-tags.js';
+
 /** The reason on a continuation's wake (InferenceRequest.reason). */
 export const AUTO_CONTINUE_REASON = 'auto-continue';
 
@@ -21,8 +23,9 @@ export const AUTO_CONTINUE_STOP_REASONS: ReadonlySet<string> = new Set(['end_tur
  * one shared message slot), says another turn starts, says how to stop
  * (`stop`, an imperative such as "call skip_reply") and that anything written
  * without it is sent as usual, and, on the last continuation of a run, that
- * the agent waits for the next event after it. When the last turn's closing
- * words were held because that turn had already sent, it says so. Short,
+ * the agent waits for the next event after it. When some or all of the last
+ * turn's closing words were held because a send that turn may already have
+ * posted where they were going, it says so. Short,
  * neutral and event-shaped on purpose: it rides as a system row in the
  * window, where instruction blocks about output have tripped classifiers,
  * and wording that reads as a lapse or a budget invites a published reply.
@@ -32,11 +35,15 @@ export function autoContinueNotice(opts: {
   stop: string;
   last: boolean;
   heldAfterSend?: boolean;
+  /** The run began with a heartbeat's turn, whose plain speech is held as drafts. */
+  heartbeat?: boolean;
 }): string {
-  return `[continue] ${opts.agentName}, another turn starts now.` +
+  return `[${NOTICE_TAG.continue}] ${opts.agentName}, another turn starts now.` +
     (opts.heldAfterSend
-      ? ' Your closing words last turn were held, not sent: that turn had already sent with a send tool.'
+      ? ' Some or all of your closing words last turn were held, not sent: a send that turn may already have posted where they were going.'
       : '') +
-    ` If you're done, ${opts.stop}; anything you write without it is sent as usual.` +
+    (opts.heartbeat
+      ? ` If you're done, ${opts.stop}; plain words you write without it and with no destination are held as drafts, as on the heartbeat's turn, and an explicit send reaches a channel.`
+      : ` If you're done, ${opts.stop}; anything you write without it is sent as usual.`) +
     (opts.last ? ' This is the last continuation in a row: after this turn you wait for the next event either way.' : '');
 }

package/src/code-execution/isolate/runner.ts

@@ -4,11 +4,13 @@
  * which ends with it, so nothing a script held stays after it.
  *
  * Every frame from the child is decoded and checked before the parent acts on
- * it, since the child is untrusted. A frame that breaks the protocol, a child
- * that exits without saying how the script ended, or one that doesn't stop
- * when asked, ends the run as crashed. A tool call goes to `onToolCall`, the
- * bridge to the framework's dispatcher, and its outcome goes into the run's
- * call record at dispatch, as running until it's answered.
+ * it, since the child is untrusted. A frame that breaks the protocol, or a
+ * child that exits without saying how the script ended when no stop was
+ * asked, ends the run as crashed. One that doesn't stop when asked is ended
+ * once the stop's grace has passed, and the run ends stopped, marked short.
+ * A tool call goes to `onToolCall`, the bridge to the framework's dispatcher,
+ * and its outcome goes into the run's call record at dispatch, as running
+ * until it's answered.
  *
  * What the host holds for a script is bounded: at most MAX_CALLS_IN_FLIGHT of
  * its calls wait for answers at once, and at most MAX_CALLS_IN_FLIGHT are out

package/src/code-execution/isolate/scripts.ts

@@ -26,6 +26,7 @@
  * dispatcher a script's calls go through, and how to wake an agent.
  */
 
+import { NOTICE_TAG } from '../../notice-tags.js';
 import { ChildCapacity, ScriptRun, type CallAnswer, type Ending, type ScriptRunOptions, type ToolAnswer } from './runner.js';
 import type { CallSummary } from './calls.js';
 import type { OutputBounds, OutputWindow } from './output.js';
@@ -478,10 +479,10 @@ function leftEndingText(scriptId: string, ending: Ending): string {
       : ending.how === 'stopped'
         ? ending.why ? `was stopped: ${ending.why}` : 'was stopped at its limit'
         : 'ended';
-  return `[script ${scriptId}] Your script ${how}. {"action": "wait", "script_id": "${scriptId}"} gives its result.`;
+  return `[${NOTICE_TAG.script} ${scriptId}] Your script ${how}. {"action": "wait", "script_id": "${scriptId}"} gives its result.`;
 }
 
 function wakeText(scriptId: string, payloadJson: string, n: number, max: number, ageMs: number): string {
   const minutes = Math.round(ageMs / 60_000);
-  return `[script ${scriptId}] Woke you with wake_agent(), ${minutes} min after it started (wake ${n} of ${max}): ${payloadJson}`;
+  return `[${NOTICE_TAG.script} ${scriptId}] Woke you with wake_agent(), ${minutes} min after it started (wake ${n} of ${max}): ${payloadJson}`;
 }

package/src/cut-off-round.ts

@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto';
+import type { ContentBlock, NormalizedResponse } from '@animalabs/membrane';
+
+export interface CutOffCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+  unparseableInput?: string;
+}
+
+export interface CutOffRound {
+  content: ContentBlock[];
+  start: number;
+  calls: CutOffCall[];
+  unnamed: boolean;
+  xml: boolean;
+}
+
+/**
+ * The last round of a response that ended at the output limit, when it holds
+ * calls that never ran, or, in XML tool mode, a tool-call block cut off before
+ * any call in it was named (`unnamed`). Membrane yields a round's calls only
+ * at its tool_use stop, or in XML tool mode at its `</function_calls>` stop,
+ * and the round begins after the last result that answers one of the
+ * response's calls.
+ */
+export function cutOffRound(response: NormalizedResponse): CutOffRound | undefined {
+  if (response.stopReason !== 'max_tokens') return undefined;
+  const callIds = new Set<string>();
+  let start = 0;
+  response.content.forEach((block, index) => {
+    if (block.type === 'tool_use') callIds.add(block.id);
+    else if (block.type === 'tool_result' && callIds.has(block.toolUseId)) start = index + 1;
+  });
+  const cut = response.details?.stop?.unclosedToolBlock ? cutToolBlock(response.content, start) : undefined;
+  const content = cut ?? response.content;
+  const uses = content.slice(start).filter((block): block is ContentBlock & { type: 'tool_use' } => block.type === 'tool_use');
+  const calls = uses.map(({ id, name, input, unparseableInput }) => ({
+    id, name, input,
+    ...(unparseableInput !== undefined ? { unparseableInput } : {}),
+  }));
+  const unnamed = !!cut && calls.length === 0;
+  const xml = !!cut || uses.some((block) => (block as { rawXml?: string }).rawXml !== undefined);
+  return calls.length > 0 || unnamed ? { content, start, calls, unnamed, xml } : undefined;
+}
+
+/**
+ * Membrane 0.8.0's grammar (unchanged from 0.7.2) for the anthropic-xml
+ * formatter's XML tool mode. Membrane exports two of its predicates,
+ * hasUnclosedToolBlock and endsWithPartialToolBlock, but not the grammar
+ * itself (dist/utils/tool-parser.js, INVOKE_REGEX): a block opens
+ * with `<function_calls>` and each call with `<invoke name="…">`, either tag
+ * optionally `antml:` prefixed, and a closer ends the innermost block still
+ * open. Its parser takes spans out of an unclosed block's text, which leaves
+ * that text in several text blocks: thinking, which stays with the round, a
+ * whole inner block its stop sequence didn't end, whose calls are the round's
+ * too, and results, which don't stay. Only a block's opener
+ * and each call's name head are read, nothing after a name, and a name that
+ * isn't a tool name's characters isn't taken as one: the formatter writes a
+ * stored call's name into the next request as it is.
+ */
+const OPENER = /<(antml:)?function_calls(>|[^>]*$)/g;
+const CLOSER = /<\/(antml:)?function_calls>/g;
+const NAME_HEAD = /<(antml:)?invoke\s+name=(["'])((?:(?!\2).)+)\2\s*\/?>/g;
+const TOOL_NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
+
+function cutToolBlock(content: ContentBlock[], start: number): ContentBlock[] | undefined {
+  const texts = content.map((block, index) => ({ block, index }))
+    .filter((entry): entry is { block: ContentBlock & { type: 'text' }; index: number } => entry.index >= start && entry.block.type === 'text');
+  const joined = texts.map(({ block }) => block.text).join('');
+  const tags = [
+    ...[...joined.matchAll(OPENER)].map((match) => ({ index: match.index, opens: true })),
+    ...[...joined.matchAll(CLOSER)].map((match) => ({ index: match.index, opens: false })),
+  ].sort((a, b) => a.index - b.index);
+  const open: number[] = [];
+  for (const tag of tags) {
+    if (tag.opens) open.push(tag.index);
+    else open.pop();
+  }
+  if (open.length === 0) return undefined;
+  const opener = open[0]!;
+  let at = opener;
+  const holder = texts.find(({ block }) => {
+    if (at < block.text.length) return true;
+    at -= block.text.length;
+    return false;
+  })!;
+  const blockText = joined.slice(opener);
+  const heads = [...blockText.matchAll(NAME_HEAD)].filter((head) => TOOL_NAME.test(head[3]!));
+  const calls: ContentBlock[] = heads.map((head, index) => ({
+    type: 'tool_use', id: `tool_${randomUUID()}`, name: head[3]!, input: {},
+    unparseableInput: blockText.slice(head.index, heads[index + 1]?.index),
+  }));
+  const prose: ContentBlock[] = at > 0 ? [{ type: 'text', text: holder.block.text.slice(0, at) }] : [];
+  const kept = content.slice(holder.index + 1)
+    .filter((block) => block.type === 'thinking' || block.type === 'redacted_thinking' || block.type === 'tool_use');
+  return [...content.slice(0, holder.index), ...prose, ...kept, ...calls];
+}