@animalabs/agent-framework 0.22.2 → 0.22.3

package/README.md

@@ -333,6 +333,8 @@ framework.abortInference('assistant', 'user requested stop');
 
 The non-streaming path uses `AbortSignal` forwarded to `membrane.stream()`, which returns an `AbortedResponse` with partial content. The streaming path cancels the `YieldingStream` directly.
 
+A turn whose stream is cancelled this way, or by `agent.cancelStream()`, ends as a stop, whether the stream reports the cancel as `aborted`, as an `error`, or by just closing: one `inference:aborted` carrying the caller's reason (`user` when none was given), a `[turn-interrupted]` note in the agent's context, and never `inference:exhausted`, which is for failed inferences. A stream that membrane aborts on its own, at a deadline or on an error (reason `timeout` or `error`), is a failed inference. `stop()` and an operator's quiesce abandon end a turn as a stop too, with their own reasons, `shutdown` and `quiesce_abandoned`, and write no note. A stopped stream still writes its inference-log row, with `success: false`.
+
 ## API Server
 
 WebSocket server for external clients (UIs, scripts, other agents).
@@ -355,7 +357,7 @@ persists across restarts; `resume` gates on a fresh per-agent feasibility
 preview of the current runtime settings (`force` overrides).
 
 ```typescript
-await framework.quiesce({ reason: 'refold', timeoutMs: 120_000, abandon: false });
+await framework.quiesce({ reason: 'refold', timeoutMs: 120_000, abandon: false });  // throws QuiesceBlockedError if the deferred writes can't reach disk
 await framework.maintenanceTick();   // drain quarantine / advance merges
 await framework.resume();            // throws ResumeBlockedError if the layout won't compile
 ```

package/dist/src/agent.d.ts

@@ -20,6 +20,18 @@ export interface StartStreamResult {
 }
 import type { ContextManager, TokenBudget, ContextInjection, CompileResult, MessageMetadata } from '@animalabs/context-manager';
 import type { AgentConfig, AgentState, SameRoundThinkTextPolicy, SameRoundThinkTextPolicySource, ToolCallId, ToolCall, ToolResult, ToolDefinition, AgentInfo, InferenceResult, InferenceOptions, AgentRuntimeSettingsPatch, AgentRuntimeSettingsSnapshot, AgentRuntimeSettingsOverrides } from './types/index.js';
+/**
+ * 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 declare function assertAgentSwitches(config: AgentConfig): void;
 /**
  * An agent wraps a context manager and manages inference state.
  */
@@ -333,16 +345,30 @@ export declare class Agent {
     private settleRuntimeSettingsTransition;
     /**
      * 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.
      */
     private consumedWatermark;
+    /** 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). */
+    private watermarkMarks;
     getConsumedWatermark(): {
         branch: string;
         sequence: number;
     } | null;
-    /** 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(): void;
+    /**
+     * 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).
+     */
+    private applyCompileWatermark;
     /** The watermark a successful compile will establish (taken before, applied after). */
     private pendingWatermark;
     /** A committing compile, as for a request that is sent: the context
@@ -386,9 +412,12 @@ export declare 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
@@ -401,6 +430,15 @@ export declare class Agent {
      * for them around its call.
      */
     buildActivationRequest(availableTools: ToolDefinition[], injections?: ContextInjection[], budget?: TokenBudget, compressionTools?: ToolDefinition[], options?: ActivationRequestOptions): Promise<NormalizedRequest>;
+    /**
+     * 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 (buildActivationRequest) and the
+     * direct API's (runInferenceWithInjections), so a setting reaches both or
+     * neither.
+     */
+    private requestSettings;
     /** Stored silent-tick rows, memoized on the store's cached message array
      * (ContextManager returns the same array until the store changes). */
     private silentTickIndex;
@@ -417,9 +455,10 @@ export declare class Agent {
     private failOpenKvSubmissions;
     /**
      * 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: ToolCall[], stream: YieldingStream): void;
+    enterWaitingForTools(calls: ToolCall[], stream: YieldingStream, supportsInjectedMessages?: boolean): void;
     /**
      * Add an assistant response to context.
      * Called by framework when stream completes.
@@ -429,10 +468,31 @@ export declare class Agent {
      * Transition back to streaming state after tool results are provided.
      */
     setStreaming(stream: YieldingStream): void;
-    /**
-     * Cancel any active stream and reset to idle.
-     */
-    cancelStream(): void;
+    /** 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. */
+    private _pendingCancel;
+    /**
+     * 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. `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(reason?: string): void;
+    /** 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(): {
+        reason?: string;
+    } | undefined;
     /**
      * Check if agent has pending tool calls.
      */
@@ -450,7 +510,12 @@ export declare class Agent {
      */
     getContextManager(): 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.
      */
     private buildSystemPrompt;
     abortInference(reason?: string): {

package/dist/src/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/src/agent.js

@@ -1,6 +1,7 @@
 import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import { ToolResultGuard } from './tool-result-guard.js';
+import { assertBooleanSetting, holdsSettings } from './config-checks.js';
 import { indexSilentTickRows, separateSilentHeartbeatTicks, silentHeartbeatSeparatorTurn, } from './silent-heartbeat.js';
 import { nonErrorResultText, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
 function stableHash(value) {
@@ -18,6 +19,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 +185,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 +195,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 +793,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 +858,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 +896,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 +957,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 +1030,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 +1049,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
@@ -1087,15 +1140,28 @@ export class Agent {
         return {
             messages: this.toolResultGuard.prepareRequest(messages),
             system: this.buildSystemPrompt(systemInjections),
+            tools: availableTools.length > 0 ? availableTools : undefined,
+            ...this.requestSettings(),
+            ...(kvUnified ? { cacheMarkers: 'cm-owned' } : {}),
+        };
+    }
+    /**
+     * 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 (buildActivationRequest) 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 }),
@@ -1147,6 +1213,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
@@ -1237,9 +1312,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 +1325,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 +1361,39 @@ 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;
     /**
-     * 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. `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') {
-            this._state.stream.cancel();
-        }
-        else if (this._state.status === 'waiting_for_tools' && this._state.stream) {
+    cancelStream(reason) {
+        if ('stream' in this._state && this._state.stream) {
+            this._pendingCancel = { reason };
             this._state.stream.cancel();
         }
         this._state = { status: 'idle' };
     }
+    /** 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 +1422,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 +1442,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;