@animalabs/agent-framework 0.22.2 → 0.23.0

package/dist/src/agent.js

@@ -1,7 +1,9 @@
 import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import { ToolResultGuard } from './tool-result-guard.js';
-import { indexSilentTickRows, separateSilentHeartbeatTicks, silentHeartbeatSeparatorTurn, } from './silent-heartbeat.js';
+import { assertBooleanSetting, holdsSettings } from './config-checks.js';
+import { CONTINUE_ROW, continueTurn, indexRequestOnlyRows, renderRequestOnlyRows, silentHeartbeatSeparatorTurn, tickKey, toolLoopPrompt, } from './silent-heartbeat.js';
+import { randomUUID } from 'node:crypto';
 import { nonErrorResultText, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
 function stableHash(value) {
     const encode = (item) => {
@@ -18,6 +20,32 @@ function stableHash(value) {
 const DEFAULT_CONTEXT_BUDGET_TOKENS = 100_000;
 const DEFAULT_TRANSITION_PACE_TOKENS = 16_000;
 const DEFAULT_SAME_ROUND_THINK_TEXT_POLICY = 'public';
+/**
+ * Refuse an agent config whose `promptCaching`, `toolResultGuard`,
+ * `toolWrapperProseGuard`, `thinking.enabled` or `refusalHandling.autoRewind`
+ * holds anything but true or false (assertBooleanSetting), or whose `thinking`
+ * or `refusalHandling` is anything but an object, null or false
+ * (holdsSettings). The constructor runs it first, so the rule holds wherever
+ * an Agent is built. `create()` also runs it for each of its agents before
+ * anything opens, and `createEphemeralAgent` before it reserves the name, so a
+ * refusal there leaves nothing behind. Membrane reads `thinking.enabled`, and
+ * the refusal is here because the setting is AgentConfig's.
+ */
+export function assertAgentSwitches(config) {
+    const agent = `Agent "${config.name}"`;
+    assertBooleanSetting(`${agent} promptCaching`, config.promptCaching, 'true or leaving it out marks requests for prompt caching, and false leaves the markers off, for transports that refuse them');
+    if (holdsSettings(`${agent} thinking`, config.thinking, '{ enabled: true }')) {
+        assertBooleanSetting(`${agent} thinking.enabled`, config.thinking.enabled, 'true asks the provider for extended thinking, and false or leaving it out doesn\'t');
+    }
+    if (holdsSettings(`${agent} refusalHandling`, config.refusalHandling, '{ autoRewind: true }')) {
+        assertBooleanSetting(`${agent} refusalHandling.autoRewind`, config.refusalHandling.autoRewind, 'true redacts the turn that tripped a refusal and runs again, up to maxRewinds times, ' +
+            'and false or leaving it out doesn\'t');
+    }
+    assertBooleanSetting(`${agent} toolResultGuard`, config.toolResultGuard, 'true turns on tool-output admission, with one guarded retry after a provider refusal, ' +
+        'and false or leaving it out doesn\'t');
+    assertBooleanSetting(`${agent} toolWrapperProseGuard`, config.toolWrapperProseGuard, 'true keeps a response whose whole prose is a tool-call-shaped wrapper from running or entering the agent\'s history, ' +
+        'and false or leaving it out doesn\'t');
+}
 /**
  * An agent wraps a context manager and manages inference state.
  */
@@ -158,6 +186,7 @@ export class Agent {
     contextManager;
     membrane;
     constructor(config, contextManager, membrane) {
+        assertAgentSwitches(config);
         this.name = config.name;
         this.model = config.model;
         this.systemPrompt = config.systemPrompt;
@@ -167,11 +196,11 @@ export class Agent {
         this.temperature = config.temperature;
         this.thinking = config.thinking;
         this.refusalHandling = config.refusalHandling;
-        this.toolResultGuard = new ToolResultGuard(config.name, contextManager, config.toolResultGuard);
+        this.toolResultGuard = new ToolResultGuard(config.name, contextManager, config.toolResultGuard === true);
         this.proseRouting = config.proseRouting ?? 'locus';
-        this.toolWrapperProseGuard = config.toolWrapperProseGuard ?? false;
+        this.toolWrapperProseGuard = config.toolWrapperProseGuard === true;
         this.cacheTtl = config.cacheTtl ?? '1h';
-        this.promptCaching = config.promptCaching ?? true;
+        this.promptCaching = config.promptCaching !== false;
         this.prefillUserMessage = config.prefillUserMessage;
         this.providerParams = config.providerParams;
         this.sameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
@@ -765,18 +794,40 @@ export class Agent {
     }
     /**
      * RFC-006 consumed watermark: the newest stored message at the last compile
-     * of a model request, per branch. Everything above it has never been in a
+     * of a model request, or at the last tool boundary that injected messages
+     * into a live one, per branch. Everything above it has never been in a
      * request and may still be replaced or withdrawn in place by its sender.
      */
     consumedWatermark = null;
+    /** Counts marks: a compile writes its watermark back only if no mark was
+     *  made while it ran (a tool boundary's, or another compile's). */
+    watermarkMarks = 0;
     getConsumedWatermark() {
         return this.consumedWatermark;
     }
-    /** Mark everything currently stored as consumed (boot, branch switch). */
+    /** Mark everything currently stored as consumed (the agent's creation, at
+     *  boot or later, and a tool boundary that injected messages into the live
+     *  stream). */
     markContextConsumed() {
         // Tolerates partial context-manager doubles (tests build Agents over
         // stubs): without a watermark nothing is ever treated as unread.
         this.consumedWatermark = this.pendingWatermark();
+        this.watermarkMarks++;
+    }
+    /**
+     * A finished compile's watermark, taken before it awaited. Within a branch
+     * the watermark only advances: if a mark was made while the compile ran,
+     * the compile's (older) one is applied only where it is later on that
+     * mark's branch, so a boundary's mark is never rolled back by a compile
+     * that started before it (a preview during a live turn).
+     */
+    applyCompileWatermark(watermark, marksBefore) {
+        const current = this.consumedWatermark;
+        if (this.watermarkMarks !== marksBefore && current
+            && (current.branch !== watermark.branch || current.sequence >= watermark.sequence))
+            return;
+        this.consumedWatermark = watermark;
+        this.watermarkMarks++;
     }
     /** The watermark a successful compile will establish (taken before, applied after). */
     pendingWatermark() {
@@ -808,10 +859,11 @@ export class Agent {
         // RFC-006 §3.3: consumption is determined at assembly — a compile that
         // fails assembled nothing, so the watermark moves only on success.
         const watermark = this.pendingWatermark();
+        const marksBefore = this.watermarkMarks;
         const compile = () => this.contextManager.compile(this.compileBudget(budget));
         const result = budget ? await compile() : await this.compileAtLiveBudget(compile);
         if (watermark)
-            this.consumedWatermark = watermark;
+            this.applyCompileWatermark(watermark, marksBefore);
         return result;
     }
     /**
@@ -845,10 +897,11 @@ export class Agent {
         // compression hold whose deadline has passed, which `compile` does for
         // any compile before it selects.
         const watermark = opts?.dryRun ? null : this.pendingWatermark();
+        const marksBefore = this.watermarkMarks;
         const compile = () => this.contextManager.compile(this.compileBudget(budget), injections, opts);
         const result = budget || opts?.dryRun ? await compile() : await this.compileAtLiveBudget(compile);
         if (watermark)
-            this.consumedWatermark = watermark;
+            this.applyCompileWatermark(watermark, marksBefore);
         return result;
     }
     // ==========================================================================
@@ -905,15 +958,8 @@ export class Agent {
             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,
+                ...this.requestSettings(),
             };
         };
         const request = await assemble();
@@ -985,7 +1031,12 @@ export class Agent {
         this._state.completed.push(completed);
         // If all tools done, transition to ready
         if (this._state.pending.size === 0) {
-            this._state = { status: 'ready', toolResults: this._state.completed, stream: this._state.stream };
+            this._state = {
+                status: 'ready',
+                toolResults: this._state.completed,
+                stream: this._state.stream,
+                supportsInjectedMessages: this._state.supportsInjectedMessages,
+            };
         }
     }
     /**
@@ -999,9 +1050,12 @@ export class Agent {
      * Build the membrane-normalized request that WOULD be emitted for this
      * agent's next activation, given the supplied tools and injections.
      *
-     * This is the single source of truth for request assembly, shared by the
-     * real activation path (`startStreamWithInjections`) and debug/preview
-     * tooling (`Framework.previewActivation`). It does not call the membrane.
+     * This is the single source of truth for a framework turn's request,
+     * shared by the real activation path (`startStreamWithInjections`) and
+     * debug/preview tooling (`Framework.previewActivation`). It does not call
+     * the membrane. The direct API (`runInferenceWithInjections`) assembles its
+     * own messages, system prompt and tools, and both take the agent's
+     * settings from `requestSettings()`.
      * A compile that is sent commits what the context manager commits for it
      * (fold resolutions, the compression its fold plan calls for, the consumed
      * watermark); a preview passes `options.dryRun`, so its compile commits
@@ -1013,7 +1067,7 @@ export class Agent {
      * may show a withheld stub before its place is added; the activation waits
      * for them around its call.
      */
-    async buildActivationRequest(availableTools, injections, budget, compressionTools = availableTools, options = {}) {
+    async assembleActivationRequest(availableTools, injections, budget, compressionTools = availableTools, options = {}) {
         // 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
@@ -1061,17 +1115,31 @@ export class Agent {
             (b) => !(b.type === "text" && (typeof b.text !== "string" || b.text.trim() === ""))),
         }))
             .filter((m) => m.content.length > 0);
-        // 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);
+        // Silent heartbeat ticks and replies to a [Continue] turn store no
+        // prompt row. Render each request-only turn before its response's first
+        // surviving row, so the wire formatter cannot merge the response into the
+        // previous assistant message and every later request keeps the prefix
+        // the response was minted under (see silent-heartbeat.ts for what can
+        // and cannot be matched). The request that minted the response ended 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 index = this.indexRequestOnlyRows();
+        const rendered = renderRequestOnlyRows(messages, index, this.name);
+        messages = rendered.messages;
+        // A tick opens wherever its separator isn't already rendered: on its first
+        // request, and on a restart whose compile left none of the tick's rows,
+        // so the restart's reply follows the separator, where every later compile
+        // renders it.
         const openingTick = options.silentHeartbeat !== undefined
-            && !ticks.started.has(options.silentHeartbeat.eventId);
+            && !rendered.separatedTicks.has(tickKey(options.silentHeartbeat));
+        // The [Continue] prompt this request's reply follows, read from the
+        // request itself: a new one when it ends on [Continue]; else, when it
+        // ends on tool results, the prompt of the reply that called those tools,
+        // whose tool loop this reply continues; else none. A request that ends
+        // on anything else (a message that arrived during a cooldown, say) gets
+        // a reply that follows that message and carries no prompt.
+        let continuePrompt;
         if (openingTick) {
             messages = [...messages, silentHeartbeatSeparatorTurn()];
         }
@@ -1079,47 +1147,68 @@ export class Agent {
             // 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]' }],
-                }];
+            messages = [...messages, continueTurn()];
+            continuePrompt = { turn: randomUUID(), text: CONTINUE_ROW };
         }
-        return {
+        else {
+            continuePrompt = toolLoopPrompt(messages.at(-1), index);
+        }
+        const request = {
             messages: this.toolResultGuard.prepareRequest(messages),
             system: this.buildSystemPrompt(systemInjections),
+            tools: availableTools.length > 0 ? availableTools : undefined,
+            ...this.requestSettings(),
+            ...(kvUnified ? { cacheMarkers: 'cm-owned' } : {}),
+        };
+        return { request, ...(continuePrompt ? { continuePrompt } : {}) };
+    }
+    /**
+     * The request fields that come from this agent's own settings: its model
+     * config, prompt caching and cache TTL, prefill message, provider
+     * parameters and participant name. Every request the agent sends takes
+     * them from here, a framework turn's (assembleActivationRequest) and the
+     * direct API's (runInferenceWithInjections), so a setting reaches both or
+     * neither.
+     */
+    requestSettings() {
+        return {
             config: {
                 model: this.model,
                 maxTokens: this.maxTokens,
                 ...(this.temperature !== undefined && { temperature: this.temperature }),
                 ...(this.thinking !== undefined && { thinking: this.thinking }),
             },
-            tools: availableTools.length > 0 ? availableTools : undefined,
             promptCaching: this.promptCaching,
-            ...(kvUnified ? { cacheMarkers: 'cm-owned' } : {}),
             cacheTtl: this.cacheTtl,
             ...(this.prefillUserMessage && { prefillUserMessage: this.prefillUserMessage }),
             ...(this.providerParams && { providerParams: this.providerParams }),
             assistantParticipant: this.name,
         };
     }
-    /** Stored silent-tick rows, memoized on the store's cached message array
-     * (ContextManager returns the same array until the store changes). */
-    silentTickIndex = null;
-    indexSilentHeartbeatTicks() {
-        const empty = { rows: new Map(), started: new Set() };
+    /** The request `assembleActivationRequest` builds (see there), for preview
+     * and debug tooling: what this agent's next activation would send. */
+    async buildActivationRequest(availableTools, injections, budget, compressionTools = availableTools, options = {}) {
+        return (await this.assembleActivationRequest(availableTools, injections, budget, compressionTools, options)).request;
+    }
+    /** Stored rows that follow a request-only turn, memoized on the store's
+     * cached message array (ContextManager returns the same array until the
+     * store changes). */
+    requestOnlyIndex = null;
+    indexRequestOnlyRows() {
+        const empty = { ticks: new Map(), prompts: new Map() };
         const cm = this.contextManager;
         if (typeof cm.getAllMessages !== 'function')
             return empty;
         try {
             const stored = cm.getAllMessages();
-            if (this.silentTickIndex?.source === stored)
-                return this.silentTickIndex.index;
-            const index = indexSilentTickRows(stored, this.name);
-            this.silentTickIndex = { source: stored, index };
+            if (this.requestOnlyIndex?.source === stored)
+                return this.requestOnlyIndex.index;
+            const index = indexRequestOnlyRows(stored, this.name);
+            this.requestOnlyIndex = { source: stored, index };
             return index;
         }
         catch (error) {
-            console.error(`[silent-heartbeat] ${this.name}: could not index tick rows; separators omitted:`, error);
+            console.error(`[request-only-rows] ${this.name}: could not index stored rows; request-only turns omitted:`, error);
             return empty;
         }
     }
@@ -1147,6 +1236,15 @@ export class Agent {
         // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
         this.failOpenKvSubmissions();
         this._streamId++;
+        // A pending cancel belongs to the stream that was live when cancelStream()
+        // 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.
+        this._pendingCancel = undefined;
         this._inferenceStartedAt = Date.now();
         this.lastStreamInputTokens = 0;
         // Reset the cache-inclusive counters too: a new stream must not inherit
@@ -1163,7 +1261,7 @@ export class Agent {
         // 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));
+        const { request, continuePrompt } = await this.toolResultGuard.afterAnnotations(() => this.assembleActivationRequest(availableTools, injections, budget, compressionTools, options));
         request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
         const receiptAware = this.contextManager
             .getStrategy?.();
@@ -1206,6 +1304,7 @@ export class Agent {
         return {
             stream,
             request,
+            ...(continuePrompt ? { continuePrompt } : {}),
             ...(kvEnabled
                 ? {
                     takeKvSubmission: () => kvQueue.shift(),
@@ -1237,9 +1336,10 @@ export class Agent {
     }
     /**
      * Transition to waiting_for_tools when stream yields tool calls.
-     * Called by framework's driveStream.
+     * Called by framework's driveStream, with what the stream declared about
+     * carrying injected messages with this round's results (see AgentState).
      */
-    enterWaitingForTools(calls, stream) {
+    enterWaitingForTools(calls, stream, supportsInjectedMessages) {
         const pending = new Map();
         for (const call of calls) {
             pending.set(call.id, {
@@ -1249,7 +1349,7 @@ export class Agent {
                 startedAt: Date.now(),
             });
         }
-        this._state = { status: 'waiting_for_tools', pending, completed: [], stream };
+        this._state = { status: 'waiting_for_tools', pending, completed: [], stream, supportsInjectedMessages };
     }
     /**
      * Add an assistant response to context.
@@ -1285,18 +1385,59 @@ export class Agent {
     setStreaming(stream) {
         this._state = { status: 'streaming', stream };
     }
+    /** The most recent cancelStream() of a live stream, until the stream
+     *  driver collects it on that stream's terminal event. Its presence is
+     *  the signal (a reasonless Stop is still a deliberate stop); its reason
+     *  is the caller's own word. Membrane reports every cancel() as reason
+     *  'user' — the call, not the actor — and a stream implementation may
+     *  report the cancel as `error` with no reason at all, so this record is
+     *  the only provenance a host-side cancel has. */
+    _pendingCancel;
+    /** The most recent cancelStream() made while this agent held no stream:
+     *  during a turn's hooks or compile, while it waits to retry, or while no
+     *  check of a turn is ahead at all. The framework collects it at the check
+     *  ahead of it, which ends the turn, and the next start drops one no check
+     *  collected, so a stop made while none was ahead, such as a host's
+     *  interrupt of every agent, ends nothing. */
+    _stopWithoutStream;
     /**
-     * Cancel any active stream and reset to idle.
+     * Cancel the stream this agent's state holds (streaming, waiting on its
+     * tools, or ready at a tool boundary with every result in), and reset to
+     * idle. With no stream, the stop is kept for the turn in progress, which
+     * the framework ends at its next check, before it sends anything more, if
+     * 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.
      */
-    cancelStream() {
-        if (this._state.status === 'streaming') {
+    cancelStream(reason) {
+        if ('stream' in this._state && this._state.stream) {
+            this._pendingCancel = { reason };
             this._state.stream.cancel();
         }
-        else if (this._state.status === 'waiting_for_tools' && this._state.stream) {
-            this._state.stream.cancel();
+        else {
+            this._stopWithoutStream = { reason };
         }
         this._state = { status: 'idle' };
     }
+    /** Collect (and clear) the cancelStream() made while this agent held no
+     *  stream, if one was made since the last collection. */
+    takeStopWithoutStream() {
+        const s = this._stopWithoutStream;
+        this._stopWithoutStream = undefined;
+        return s;
+    }
+    /** Collect (and clear) the cancel that ended the current stream, if this
+     *  side issued one. The stream driver calls it once, while the stream
+     *  still owns the agent, at the stream's terminal event (`aborted`
+     *  normally, `error` for implementations that report cancel() that way)
+     *  or at the loop's end when the stream closed without one. A record no
+     *  driver collects is cleared when the agent's next stream starts. */
+    takeCancel() {
+        const c = this._pendingCancel;
+        this._pendingCancel = undefined;
+        return c;
+    }
     /**
      * Check if agent has pending tool calls.
      */
@@ -1325,18 +1466,18 @@ export class Agent {
         return this.contextManager;
     }
     /**
-     * Build the effective system prompt, appending any system-position injections.
+     * Build the effective system prompt, appending any system-position
+     * injections, their blocks joined by line breaks. The system prompt is
+     * text, so a block of another type, such as an image a server or module
+     * injected there, can't go in it: a line in its place says so. The hook
+     * orchestrator tells a server's operator once per server and namespace,
+     * and the module registry tells a module's once per module and namespace.
      */
     buildSystemPrompt(systemInjections) {
         if (systemInjections.length === 0) {
             return this.systemPrompt;
         }
-        const injectedText = systemInjections
-            .filter((block) => block.type === 'text')
-            .map((block) => block.text);
-        if (injectedText.length === 0) {
-            return this.systemPrompt;
-        }
+        const injectedText = systemInjections.map((block) => block.type === 'text' ? block.text : `[${block.type} block not shown: the system prompt carries text only.]`);
         return this.systemPrompt + '\n' + injectedText.join('\n');
     }
     abortInference(reason) {
@@ -1345,10 +1486,9 @@ export class Agent {
             this._state.abortController.abort(reason);
             return { aborted: true, durationMs };
         }
-        if (this._state.status === 'streaming' ||
-            (this._state.status === 'waiting_for_tools' && this._state.stream)) {
+        if ('stream' in this._state && this._state.stream) {
             const durationMs = Date.now() - this._inferenceStartedAt;
-            this.cancelStream();
+            this.cancelStream(reason);
             return { aborted: true, durationMs };
         }
         return false;