@animalabs/agent-framework 0.26.2 → 0.28.0

package/src/api/server.ts

@@ -518,8 +518,7 @@ export class ApiServer {
     const contextManager = agent.getContextManager();
     // A dry run: listed, never sent, so it persists no fold resolutions and
     // queues none of the compression its fold plan calls for (see
-    // Agent.compileWithInjections for what a dry run still leaves, and for
-    // context-manager#160's thinking binding).
+    // Agent.compileWithInjections for what a dry run still leaves).
     const { messages } = await contextManager.compile(undefined, undefined, { dryRun: true });
 
     const limit = params?.limit ?? 50;
@@ -650,7 +649,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', {
@@ -668,7 +668,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

@@ -0,0 +1,43 @@
+/**
+ * autoContinue (AgentConfig.autoContinue, docs/auto-continue.md): a turn the
+ * model ends itself is followed by another, unless it ended on a skip. This
+ * module holds what doesn't need the framework: which ends continue, and the
+ * row the next turn reads.
+ */
+
+/** The reason on a continuation's wake (InferenceRequest.reason). */
+export const AUTO_CONTINUE_REASON = 'auto-continue';
+
+/**
+ * Stop reasons of a turn the model ended itself. The others don't continue:
+ * a refusal has its own handling (retries, rewind, the reaction), a
+ * `max_tokens` end was cut off rather than chosen, and `no_progress` and
+ * `round_limit` are the stall guard's verdict that the turn wasn't moving.
+ */
+export const AUTO_CONTINUE_STOP_REASONS: ReadonlySet<string> = new Set(['end_turn', 'stop_sequence']);
+
+/**
+ * The row a continuation's turn reads. It names the agent (residents read
+ * 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 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.
+ */
+export function autoContinueNotice(opts: {
+  agentName: string;
+  stop: string;
+  last: boolean;
+  heldAfterSend?: boolean;
+}): string {
+  return `[continue] ${opts.agentName}, another turn starts now.` +
+    (opts.heldAfterSend
+      ? ' 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.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/scripts.ts

@@ -46,6 +46,10 @@ export interface ScriptCallContext {
   watch?: ScriptWatch;
   /** The call watching the script now, if one is: a result that ends the turn ends it at that call's return. Without it, `watch`. */
   watching?(): ScriptWatch | undefined;
+  /** The turn the script's run call was made in, when one was: the turn its words were written in, which a later turn's wait doesn't change. */
+  startTurnId?: number;
+  /** What its agent had read when the run call started the script (the host's consumed watermark), given at run: what the script's words were written having read, which a later round's wait doesn't change. */
+  startReadThrough?: { branch: string; sequence: number } | null;
 }
 
 export interface ScriptsHost {
@@ -113,7 +117,7 @@ interface Script {
   /** The code it runs. */
   code: string;
   run: ScriptRun;
-  context: { origin?: unknown };
+  context: { origin?: unknown; startReadThrough?: { branch: string; sequence: number } | null };
   /** The turn its run call was made in, when one was: its agent's turns end it by that. */
   turnId: number | undefined;
   startedAt: number;
@@ -176,7 +180,7 @@ export class AgentScripts {
     agentName: string,
     code: string,
     askedMs?: number,
-    options: { origin?: unknown; watch?: ScriptWatch } = {},
+    options: { origin?: unknown; watch?: ScriptWatch; startReadThrough?: { branch: string; sequence: number } | null } = {},
   ): Promise<ScriptReturn> {
     // Listed first, so a module whose tool list throws refuses the run with nothing taken.
     let tools: readonly PreludeTool[];
@@ -202,7 +206,10 @@ export class AgentScripts {
       agentName,
       code,
       run: null as unknown as ScriptRun,
-      context: options.origin === undefined ? {} : { origin: options.origin },
+      context: {
+        ...(options.origin === undefined ? {} : { origin: options.origin }),
+        ...(options.startReadThrough === undefined ? {} : { startReadThrough: options.startReadThrough }),
+      },
       turnId: options.watch?.turnId,
       startedAt: Date.now(),
       endedAt: null,
@@ -231,6 +238,7 @@ export class AgentScripts {
           ...script.context,
           ...(script.watch ? { watch: script.watch } : {}),
           watching: () => script.watch ?? undefined,
+          ...(script.turnId !== undefined ? { startTurnId: script.turnId } : {}),
         }),
       onWake: (payload, n) => this.wake(script, payload, n),
       onEnd: (ending) => this.ended(script, ending),

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];
+}