@animalabs/agent-framework 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -48,7 +48,7 @@
   "dependencies": {
     "@animalabs/chronicle": "^0.4.0",
     "@animalabs/context-manager": "^0.14.0",
-    "@animalabs/membrane": "^0.5.78",
+    "@animalabs/membrane": "^0.5.87",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",
     "ws": "^8.18.0"

package/src/agent.ts

@@ -2,13 +2,26 @@ import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, Yiel
 import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import type { CacheWireReceipt, KvUnifiedRequestHooks } from './kv-unified-wire.js';
-import { ToolResultGuard, TOOL_RESULT_GUARD_NOTICE } from './tool-result-guard.js';
+import { ToolResultGuard } from './tool-result-guard.js';
 import {
-  toolResultDataToHistoryString,
+  indexSilentTickRows,
+  separateSilentHeartbeatTicks,
+  silentHeartbeatSeparatorTurn,
+  type SilentHeartbeatTick,
+  type SilentTickIndex,
+  type StoredRowLike,
+} from './silent-heartbeat.js';
+import {
+  nonErrorResultText,
   truncateForHistory,
   DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS,
 } from './tool-result-history.js';
 
+export interface ActivationRequestOptions {
+  /** The silent heartbeat tick this request answers, if any. */
+  silentHeartbeat?: SilentHeartbeatTick;
+}
+
 export interface StartStreamResult {
   stream: YieldingStream;
   request: NormalizedRequest;
@@ -22,6 +35,7 @@ import type {
   CompileResult,
   HotContextSettingsStatus,
   HotContextSettingsUpdate,
+  MessageMetadata,
 } from '@animalabs/context-manager';
 import type {
   AgentConfig,
@@ -656,28 +670,37 @@ export class Agent {
       this.toolResultGuard.storeResults(content, wireResults, this._state.toolResults);
     }
 
-    // Compile context (with optional injections)
-    const { messages, systemInjections } = await this.compileWithInjections(budget, injections);
-
-    // If we have pending tool results, add them
-    if (this._state.status === 'ready' && !guardedResults) {
-      const toolResultMessages = this.buildToolResultMessages(this._state.toolResults);
-      messages.push(...toolResultMessages);
-    }
-
-    const request: NormalizedRequest = {
-      messages: this.toolResultGuard.prepareRequest(messages, true),
-      system: this.buildSystemPrompt(systemInjections),
-      config: {
-        model: this.model,
-        maxTokens: this.maxTokens,
-        ...(this.temperature !== undefined && { temperature: this.temperature }),
-        ...(this.thinking !== undefined && { thinking: this.thinking }),
-      },
-      tools: tools.length > 0 ? tools : undefined,
-      ...(this.providerParams && { providerParams: this.providerParams }),
-      assistantParticipant: this.name,
+    // Compile the context (with optional injections) into a request. The
+    // guard's refusal retry is assembled the same way, afresh. It is compiled
+    // only once each withheld stub's annotation has finished, including one
+    // that began during the compile, and after a stub edit that failed has
+    // been retried; one whose store still fails is compiled as the bare
+    // notice.
+    let unguardedResults: ReturnType<Agent['buildToolResultMessages']> | undefined;
+    const assemble = async (): Promise<NormalizedRequest> => {
+      const { messages, systemInjections } = await this.toolResultGuard.afterAnnotations(
+        () => this.compileWithInjections(budget, injections));
+      // Read once, after the first compile, since results may have become
+      // ready while it ran; the refusal retry, assembled while the agent is
+      // inferring, sends the same ones.
+      unguardedResults ??= this._state.status === 'ready' && !guardedResults
+        ? this.buildToolResultMessages(this._state.toolResults) : [];
+      messages.push(...unguardedResults);
+      return {
+        messages: this.toolResultGuard.prepareRequest(messages, true),
+        system: this.buildSystemPrompt(systemInjections),
+        config: {
+          model: this.model,
+          maxTokens: this.maxTokens,
+          ...(this.temperature !== undefined && { temperature: this.temperature }),
+          ...(this.thinking !== undefined && { thinking: this.thinking }),
+        },
+        tools: tools.length > 0 ? tools : undefined,
+        ...(this.providerParams && { providerParams: this.providerParams }),
+        assistantParticipant: this.name,
+      };
     };
+    const request = await assemble();
 
     const abortController = new AbortController();
     if (options?.signal) {
@@ -690,7 +713,7 @@ export class Agent {
 
     // Set state to inferring
     this._inferenceStartedAt = Date.now();
-    const inferencePromise = this.doInference(request, abortController.signal);
+    const inferencePromise = this.doInference(request, abortController.signal, assemble);
     this._state = { status: 'inferring', promise: inferencePromise, abortController };
 
     try {
@@ -779,20 +802,27 @@ export class Agent {
    * it does not touch agent state and does not call the membrane, and
    * `ContextManager.compile` is itself side-effect-free (compression runs in
    * the background). Safe to call regardless of the agent's current status.
+   * It doesn't wait for the tool-result guard's annotations, so a preview
+   * never waits on a workspace write (rollback, undo and redo report one), and
+   * may show a withheld stub before its place is added; the activation waits
+   * for them around its call.
    */
   async buildActivationRequest(
     availableTools: ToolDefinition[],
     injections?: ContextInjection[],
-    budget?: TokenBudget
+    budget?: TokenBudget,
+    compressionTools: ToolDefinition[] = availableTools,
+    options: ActivationRequestOptions = {},
   ): Promise<NormalizedRequest> {
-    // Keep the context manager's view of the live tool surface current: the
+    // Compression may revisit hidden tools in recorded history. Keep its full
+    // definition set separate from the resident's advertised tools: the
     // autobiographical strategy must declare the same tools on its
     // summarizer/compression requests, or transcripts containing tool blocks
     // are refused by Anthropic's reasoning_extraction classifier (labclaude
     // incident, 2026-07-09). Optional chaining: older context-manager
     // versions don't have the hook.
     (this.contextManager as unknown as { setToolDefinitions?: (t: ToolDefinition[]) => void })
-      .setToolDefinitions?.(availableTools);
+      .setToolDefinitions?.(compressionTools);
 
     const strategy = (this.contextManager as unknown as { getStrategy?: () => unknown })
       .getStrategy?.() as {
@@ -837,10 +867,24 @@ export class Agent {
       }))
       .filter((m) => m.content.length > 0);
 
-    // Safety: ensure messages don't end with an assistant message.
-    // Some models reject trailing assistant messages ("prefill not supported"),
-    // and after context compression a stale assistant turn can end up last.
-    if (messages.length > 0 && messages[messages.length - 1]!.participant === this.name) {
+    // Silent heartbeat ticks store no prompt row. Render a request-only
+    // separator before each tick's first surviving row so the wire formatter
+    // cannot merge the tick into the previous assistant message (see
+    // silent-heartbeat.ts for what can and cannot be matched). This agent's
+    // own first request for a tick ends on that same turn, so the prefix it
+    // caches is the one every later compile renders. "First" is per agent: a
+    // broadcast tick shares its eventId with every resident.
+    const ticks = this.indexSilentHeartbeatTicks();
+    messages = separateSilentHeartbeatTicks(messages, ticks.rows, this.name);
+    const openingTick = options.silentHeartbeat !== undefined
+      && !ticks.started.has(options.silentHeartbeat.eventId);
+
+    if (openingTick) {
+      messages = [...messages, silentHeartbeatSeparatorTurn()];
+    } else if (messages.length > 0 && messages[messages.length - 1]!.participant === this.name) {
+      // Safety: ensure messages don't end with an assistant message.
+      // Some models reject trailing assistant messages ("prefill not supported"),
+      // and after context compression a stale assistant turn can end up last.
       messages = [...messages, {
         participant: 'user',
         content: [{ type: 'text', text: '[Continue]' }],
@@ -866,6 +910,26 @@ export class Agent {
     };
   }
 
+  /** Stored silent-tick rows, memoized on the store's cached message array
+   * (ContextManager returns the same array until the store changes). */
+  private silentTickIndex: { source: readonly unknown[]; index: SilentTickIndex } | null = null;
+
+  private indexSilentHeartbeatTicks(): SilentTickIndex {
+    const empty: SilentTickIndex = { rows: new Map(), started: new Set() };
+    const cm = this.contextManager as Partial<ContextManager>;
+    if (typeof cm.getAllMessages !== 'function') return empty;
+    try {
+      const stored = cm.getAllMessages() as unknown as readonly StoredRowLike[];
+      if (this.silentTickIndex?.source === stored) return this.silentTickIndex.index;
+      const index = indexSilentTickRows(stored, this.name);
+      this.silentTickIndex = { source: stored, index };
+      return index;
+    } catch (error) {
+      console.error(`[silent-heartbeat] ${this.name}: could not index tick rows; separators omitted:`, error);
+      return empty;
+    }
+  }
+
   /**
    * Start a yielding stream with context injections.
    * Same as startStream but passes injections through to compile.
@@ -873,7 +937,9 @@ export class Agent {
   async startStreamWithInjections(
     availableTools: ToolDefinition[],
     injections?: ContextInjection[],
-    budget?: TokenBudget
+    budget?: TokenBudget,
+    compressionTools: ToolDefinition[] = availableTools,
+    options: ActivationRequestOptions = {},
   ): Promise<StartStreamResult> {
     if (this._state.status !== 'idle') {
       throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
@@ -908,7 +974,11 @@ export class Agent {
     this.lastStreamRealInputTokens = 0;
     this.lastStreamOutputTokens = 0;
 
-    const request = await this.buildActivationRequest(availableTools, injections, budget);
+    // Compiled only once each withheld stub's annotation has finished,
+    // including one that began during the compile, and after a stub edit that
+    // failed has been retried (see afterAnnotations).
+    const request = await this.toolResultGuard.afterAnnotations(
+      () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
     request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
 
     const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
@@ -1009,7 +1079,7 @@ export class Agent {
    * Add an assistant response to context.
    * Called by framework when stream completes.
    */
-  addAssistantResponse(content: ContentBlock[]): void {
+  addAssistantResponse(content: ContentBlock[], metadata?: MessageMetadata): void {
     // A turn whose entire output is thinking blocks produced NOTHING: no
     // speech, no tool call. That is what a refusal looks like on the wire —
     // the provider returns signed thinking (often with empty text, the
@@ -1035,7 +1105,7 @@ export class Agent {
       );
       return;
     }
-    this.contextManager.addMessage(this.name, content);
+    this.contextManager.addMessage(this.name, content, metadata);
   }
 
   /**
@@ -1126,9 +1196,13 @@ export class Agent {
 
   private async doInference(
     request: NormalizedRequest,
-    signal?: AbortSignal
+    signal: AbortSignal | undefined,
+    /** Compiles the context into a request again, for the guard's retry. */
+    reassemble: () => Promise<NormalizedRequest>,
   ): Promise<InferenceResult> {
-    let response = await this.membrane.stream(request, { signal });
+    let response = signal?.aborted
+      ? { aborted: true as const, reason: 'user' as const }
+      : await this.membrane.stream(request, { signal });
     // Usage of a refused attempt abandoned by the guard; it was billed and
     // is added to the retry's usage below rather than overwritten.
     let abandonedUsage: { inputTokens: number; outputTokens: number } | undefined;
@@ -1138,12 +1212,14 @@ export class Agent {
       const ids = this.toolResultGuard.withhold('unknown');
       if (ids) {
         abandonedUsage = response.usage;
-        const withheld = new Set(ids);
-        request = { ...request, messages: request.messages.map((message) => ({
-          ...message, content: message.content.map((block) => block.type === 'tool_result' && withheld.has(block.toolUseId)
-            ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError } : block),
-        })) };
-        response = await this.membrane.stream(request, { signal });
+        // The retry is compiled afresh, like every request: once each stub's
+        // annotation has finished (agent-framework #277), and against the
+        // budget without the batch's reservation, so a stub longer than its
+        // original can't carry the request past the budget.
+        const retry = await reassemble();
+        response = signal?.aborted
+          ? { aborted: true, reason: 'user', partialUsage: response.usage }
+          : await this.membrane.stream(retry, { signal });
       }
     }
 
@@ -1224,7 +1300,7 @@ export class Agent {
       toolUseId: r.id,
       content: r.result.isError
         ? truncateForHistory(r.result.error ?? 'Unknown error', DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS)
-        : toolResultDataToHistoryString(r.result.data, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS),
+        : nonErrorResultText(r.result, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS),
       isError: r.result.isError,
     }));
 

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

@@ -10,7 +10,7 @@
  * This is a ROBUSTNESS boundary, not a security sandbox — same doctrine as
  * GateScript: the agent already has broader host access through its tools.
  * What this class guarantees is liveness: a wedged or runaway script cannot
- * hang the agent turn (cancel -> grace -> SIGKILL -> respawn) and a crashed
+ * hang the agent turn (cancel + SIGINT -> grace -> SIGKILL -> respawn) and a crashed
  * interpreter surfaces as a tool result, never as an unhandled rejection.
  */
 
@@ -65,6 +65,8 @@ export interface PyRunnerOptions {
   toolCallTimeoutMs?: number;
   /** Whole-script deadline; exceeded -> cancel, grace, kill. */
   scriptTimeoutMs?: number;
+  /** How long a script gets to stop after its deadline before the interpreter is killed (default 10s). */
+  cancelGraceMs?: number;
   /** Idle interpreter reclaim (state lost), mirroring container reclaim. */
   idleReclaimMs?: number;
   onToolCall: ScriptToolCallHandler;
@@ -76,6 +78,8 @@ const DEFAULT_TOOL_CALL_TIMEOUT_MS = 270_000;
 const DEFAULT_SCRIPT_TIMEOUT_MS = 600_000;
 const DEFAULT_IDLE_RECLAIM_MS = 300_000;
 const CANCEL_GRACE_MS = 10_000;
+/** After the deadline, SIGINT is repeated at this interval until the script reports or is killed. */
+const INTERRUPT_REPEAT_MS = 200;
 
 /** The longest delay Node's timers honour (~24.8 days); a longer one fires after ~1 ms. */
 export const MAX_TIMER_MS = 2_147_483_647;
@@ -92,6 +96,8 @@ interface PendingExec {
   resolve: (result: ExecResult) => void;
   deadlineTimer: ReturnType<typeof setTimeout> | null;
   killTimer: ReturnType<typeof setTimeout> | null;
+  /** Repeats the deadline SIGINT (see interruptChild). */
+  interruptTimer?: ReturnType<typeof setInterval>;
   settled: boolean;
   /** Set once the deadline fired: the result then says the script ran out of time. */
   deadlineMs: number | null;
@@ -101,6 +107,7 @@ export class PyRunner {
   private readonly pythonPath: string;
   private readonly toolCallTimeoutMs: number;
   private readonly scriptTimeoutMs: number;
+  private readonly cancelGraceMs: number;
   private readonly idleReclaimMs: number;
   private readonly onToolCall: ScriptToolCallHandler;
   private readonly label: string;
@@ -114,18 +121,21 @@ export class PyRunner {
   private idleTimer: ReturnType<typeof setTimeout> | null = null;
   private execCounter = 0;
   private disposed = false;
+  /** An exec has passed the busy check but is still awaiting the interpreter. */
+  private starting = false;
 
   constructor(options: PyRunnerOptions) {
     this.pythonPath = options.pythonPath ?? 'python3';
     this.toolCallTimeoutMs = options.toolCallTimeoutMs ?? DEFAULT_TOOL_CALL_TIMEOUT_MS;
     this.scriptTimeoutMs = options.scriptTimeoutMs ?? DEFAULT_SCRIPT_TIMEOUT_MS;
+    this.cancelGraceMs = options.cancelGraceMs ?? CANCEL_GRACE_MS;
     this.idleReclaimMs = options.idleReclaimMs ?? DEFAULT_IDLE_RECLAIM_MS;
     this.onToolCall = options.onToolCall;
     this.label = options.label ?? 'pytc';
   }
 
   get busy(): boolean {
-    return this.pending !== null;
+    return this.pending !== null || this.starting;
   }
 
   /**
@@ -150,7 +160,7 @@ export class PyRunner {
     if (this.disposed) {
       return { stdout: '', stderr: 'code_execution runner disposed', returnCode: 1, aborted: true };
     }
-    if (this.pending) {
+    if (this.busy) {
       return {
         stdout: '',
         stderr: 'RuntimeError: another code_execution script is already running for this agent',
@@ -160,6 +170,7 @@ export class PyRunner {
     }
     this.clearIdleTimer();
 
+    this.starting = true; // claimed before the await: a same-tick second exec must see it
     try {
       await this.ensureChild();
     } catch (err) {
@@ -171,6 +182,8 @@ export class PyRunner {
         returnCode: 1,
         aborted: true,
       };
+    } finally {
+      this.starting = false; // `pending` is set below, with no await in between
     }
 
     const execId = `e${++this.execCounter}`;
@@ -193,16 +206,26 @@ export class PyRunner {
         // Deadline: ask politely first (script sees CancelledError and its
         // exec_result still flows back), then kill on unresponsiveness.
         this.send({ op: 'cancel', id: execId, reason: 'deadline' });
+        // The cancel lands only when the script awaits. Blocking code (time.sleep, a
+        // busy loop, a blocking read) never does, so interrupt it as well: the runtime
+        // raises KeyboardInterrupt in the script's own code, or schedules the
+        // cancellation of a script that is waiting. Repeated, because a waiting script
+        // can resume into blocking code before that cancellation runs; the runtime
+        // ignores the repeats once the script was interrupted or cancelled.
+        this.interruptChild();
+        pending.interruptTimer = setInterval(() => this.interruptChild(), INTERRUPT_REPEAT_MS);
         pending.killTimer = setTimeout(() => {
           pending.deadlineMs = null; // this message already says why
           this.settlePending({
             stdout: '',
-            stderr: `script killed after exceeding ${Math.round(deadlineMs / 1000)}s deadline`,
+            stderr:
+              `script stopped: it reached its ${formatLimit(deadlineMs)} time limit and did not respond, ` +
+              'so it was killed and the interpreter restarted (variables from earlier scripts are gone)',
             returnCode: 1,
             aborted: true,
           });
           this.reclaim('deadline-kill');
-        }, CANCEL_GRACE_MS);
+        }, this.cancelGraceMs);
       }, deadlineMs);
       // A day-scale background deadline must not hold the process open.
       if (background) pending.deadlineTimer.unref?.();
@@ -299,7 +322,7 @@ export class PyRunner {
     });
 
     this.reader = createInterface({ input: child.stdout });
-    this.reader.on('line', (line) => this.handleLine(line));
+    this.reader.on('line', (line) => this.handleLine(line, child));
 
     this.childReady = new Promise<void>((resolve, reject) => {
       const onReady = () => {
@@ -333,7 +356,7 @@ export class PyRunner {
 
   private readyResolver: (() => void) | null = null;
 
-  private handleLine(line: string): void {
+  private handleLine(line: string, child: ChildProcessWithoutNullStreams): void {
     let msg: { op?: string; id?: string; name?: string; args?: unknown; stdout?: string; stderr?: string; return_code?: number };
     try {
       msg = JSON.parse(line);
@@ -358,7 +381,7 @@ export class PyRunner {
         this.onToolCall(toolName, args)
           .catch((err) => `Error: ${err instanceof Error ? err.message : String(err)}`)
           .then((result) => {
-            this.send({ op: 'tool_result', id: callId, result });
+            this.reply(child, { op: 'tool_result', id: callId, result }, `result of ${toolName} call ${callId}`);
           });
         return;
       }
@@ -376,7 +399,7 @@ export class PyRunner {
               `wake handler failed: ${err instanceof Error ? err.message : String(err)}`)
           : Promise.resolve('this script is not allowed to wake the agent');
         void refuse.then((error) => {
-          this.send({ op: 'wake_ack', id: wakeId, ...(error ? { error } : {}) });
+          this.reply(child, { op: 'wake_ack', id: wakeId, ...(error ? { error } : {}) }, `ack of wake ${wakeId}`);
         });
         return;
       }
@@ -414,10 +437,25 @@ export class PyRunner {
     }
     if (pending.deadlineTimer) clearTimeout(pending.deadlineTimer);
     if (pending.killTimer) clearTimeout(pending.killTimer);
+    if (pending.interruptTimer) clearInterval(pending.interruptTimer);
     this.pending = null;
     pending.resolve(result);
   }
 
+  /**
+   * Answer the interpreter that asked. Call and wake ids restart in every
+   * interpreter, so an answer that outlives its interpreter (the script was
+   * aborted, killed or crashed, or the interpreter reclaimed) would resolve
+   * the same id in the one that replaced it, inside another script: drop it.
+   */
+  private reply(child: ChildProcessWithoutNullStreams, msg: unknown, what: string): void {
+    if (child !== this.child) {
+      console.error(`[pytc:${this.label}] dropped late ${what}: the interpreter that asked for it is gone`);
+      return;
+    }
+    this.send(msg);
+  }
+
   private send(obj: unknown): void {
     const child = this.child;
     if (!child || child.exitCode !== null || child.killed) return;
@@ -430,6 +468,25 @@ export class PyRunner {
     }
   }
 
+  /**
+   * SIGINT the interpreter: blocking code in the running script raises
+   * KeyboardInterrupt. Not on Windows, where Node's kill() ends the process
+   * outright; there the cancel op and the kill grace remain.
+   * process.kill rather than child.kill, which would mark the child `killed`:
+   * a killed child gets no more protocol messages and is respawned on the
+   * next exec, losing the interpreter state this keeps.
+   */
+  private interruptChild(): void {
+    const child = this.child;
+    if (process.platform === 'win32' || !child || child.exitCode !== null || child.killed) return;
+    if (child.pid === undefined) return;
+    try {
+      process.kill(child.pid, 'SIGINT');
+    } catch {
+      // already gone: the exit handler settles the exec
+    }
+  }
+
   /** Kill interpreter + clean temp dir. State is lost (by design). */
   private reclaim(reason: string): void {
     if (this.child) {