@pikku/core 0.12.72 → 0.12.77

package/dist/wirings/ai-agent/ai-agent-stream.d.ts

@@ -1,8 +1,9 @@
 import type { AIStreamChannel } from './ai-agent.types.js';
 import type { AIAgentRunnerParams, AIAgentStepResult } from '../../services/ai-agent-runner-service.js';
 import { ToolApprovalRequired, ToolCredentialRequired, type RunAIAgentParams, type StreamAIAgentOptions } from './ai-agent-prepare.js';
-export declare function checkForApprovals(stepResult: AIAgentStepResult, tools: AIAgentRunnerParams['tools'], runId: string): ToolApprovalRequired[];
-export declare function checkForCredentialRequests(stepResult: AIAgentStepResult, runId: string): ToolCredentialRequired[];
+import { type AgentInterruption, type AgentInterruptResult } from './ai-agent-interrupt.js';
+export declare function checkForApprovals(stepResult: AIAgentStepResult, tools: AIAgentRunnerParams['tools']): ToolApprovalRequired[];
+export declare function checkForCredentialRequests(stepResult: AIAgentStepResult): ToolCredentialRequired[];
 export declare function appendStepMessages(runnerParams: AIAgentRunnerParams, stepResult: AIAgentStepResult): void;
 export declare function streamAIAgent(agentName: string, input: {
     message: string;
@@ -11,6 +12,28 @@ export declare function streamAIAgent(agentName: string, input: {
     model?: string;
     temperature?: number;
 }, channel: AIStreamChannel, params: RunAIAgentParams, agentSessionMap?: Map<string, string>, options?: StreamAIAgentOptions): Promise<string>;
+/**
+ * Stop an in-flight run on behalf of a caller, after checking the run is theirs.
+ *
+ * Unlike {@link resumeAIAgent} this needs no channel: it does not continue the
+ * stream, it ends one. The `interrupted` event and the truncated message are
+ * emitted by the original {@link streamAIAgent} call on its own channel, so this
+ * can be reached over a plain RPC while the stream is held open elsewhere —
+ * which is exactly the shape a voice barge-in needs.
+ *
+ * Ownership is the whole gate, deliberately without {@link assertAgentAuthorized}.
+ * Resuming re-enters the agent and approves a tool call, so a revoked grant must
+ * block it; stopping is the opposite — if a caller's access to an agent was
+ * revoked mid-run, being able to stop their own run is harmless and arguably
+ * what you want.
+ *
+ * Returns `false` when there was nothing to stop. Racing a run that finishes on
+ * its own is the normal case in voice, so it is not an error.
+ */
+export declare function interruptAIAgent(input: {
+    runId: string;
+    reason?: AgentInterruption['reason'];
+}, params: RunAIAgentParams): Promise<AgentInterruptResult>;
 export declare function resumeAIAgent(input: {
     runId: string;
     toolCallId: string;

package/dist/wirings/ai-agent/ai-agent-stream.js

@@ -1,10 +1,12 @@
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
+import { SPOKEN_TRANSCRIPT } from './voice-input.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertResourcePrincipalOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, CREDENTIAL_REQUIRED, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
+import { getInFlightTools, isAbortError, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 function createPersistingChannel(parent, storage, threadId, logger) {
     let fullText = '';
     let stepText = '';
@@ -15,7 +17,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
         inputTokens: 0,
         outputTokens: 0,
     };
-    const flushStep = async () => {
+    const flushStep = async (opts) => {
         if (!storage)
             return;
         const text = stepText;
@@ -37,6 +39,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
                     ]
                     : text || undefined,
                 toolCalls: calls.length > 0 ? calls : undefined,
+                ...(opts?.interrupted ? { interrupted: true } : {}),
                 createdAt: new Date(),
             };
             const messages = [assistantMsg];
@@ -51,14 +54,6 @@ function createPersistingChannel(parent, storage, threadId, logger) {
             await storage.saveMessages(threadId, messages);
         }
     };
-    /**
-     * `send` is synchronous and so cannot await the flush. A rejection would have
-     * nothing to propagate to and would take the process down as an unhandled
-     * rejection — a model reusing a toolCallId, which is a primary key in AI
-     * storage, is enough to trigger it. Persistence from inside `send` is
-     * therefore best-effort: the run carries on, and the awaited `flush()` on the
-     * suspend paths still surfaces failures to its caller.
-     */
     const flushDetached = () => {
         void flushStep().catch((error) => {
             logger?.error('Failed to persist agent messages', {
@@ -83,11 +78,15 @@ function createPersistingChannel(parent, storage, threadId, logger) {
         close: () => parent.close(),
         sendBinary: (data) => parent.sendBinary(data),
         send: (event) => {
+            // Accumulated whether or not storage is configured: `fullText` is what
+            // the client was streamed, and an interrupted run has to be able to
+            // report the fragment it got through even with persistence turned off.
+            if (event.type === 'text-delta')
+                fullText += event.text;
             if (storage) {
                 switch (event.type) {
                     case 'text-delta':
                         stepText += event.text;
-                        fullText += event.text;
                         break;
                     case 'tool-call':
                         stepToolCalls.push({
@@ -125,6 +124,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
         setState: (s) => parent.setState(s),
         getState: () => parent.getState(),
         clearState: () => parent.clearState(),
+        remote: (funcName, data) => parent.remote(funcName, data),
     };
     return channel;
 }
@@ -161,7 +161,7 @@ async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServ
     });
 }
 async function runStreamStepLoop(params) {
-    const { agent, runnerParams, maxSteps, agentRunner, streamChannel, channel, runId, aiMiddlewares, } = params;
+    const { agent, runnerParams, maxSteps, agentRunner, streamChannel, channel, aiMiddlewares, } = params;
     const singletonServices = getSingletonServices();
     for (let step = 0; step < maxSteps; step++) {
         if (agent.prepareStep) {
@@ -195,25 +195,21 @@ async function runStreamStepLoop(params) {
         }
         if (stepResult.toolCalls.length === 0)
             break;
-        const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools, runId);
+        const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools);
         if (approvalsNeeded.length > 0) {
-            // For each approval, call approvalDescriptionFn if available
             for (const approval of approvalsNeeded) {
                 const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
                 if (toolDef?.approvalDescriptionFn && !approval.reason) {
                     try {
                         approval.reason = await toolDef.approvalDescriptionFn(approval.args);
                     }
-                    catch {
-                        // If description generation fails, continue without it
-                    }
+                    catch { }
                 }
             }
             return { outcome: 'approval', approvals: approvalsNeeded };
         }
-        const credentialRequests = checkForCredentialRequests(stepResult, runId);
+        const credentialRequests = checkForCredentialRequests(stepResult);
         if (credentialRequests.length > 0) {
-            // Append step messages so the tool result is preserved for resume
             appendStepMessages(runnerParams, stepResult);
             return { outcome: 'credential', credentialRequests };
         }
@@ -221,7 +217,7 @@ async function runStreamStepLoop(params) {
     }
     return { outcome: 'done' };
 }
-export function checkForApprovals(stepResult, tools, runId) {
+export function checkForApprovals(stepResult, tools) {
     const approvals = [];
     for (const tc of stepResult.toolCalls) {
         const toolDef = tools.find((t) => t.name === tc.toolName);
@@ -229,12 +225,6 @@ export function checkForApprovals(stepResult, tools, runId) {
             approvals.push(new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args));
             continue;
         }
-        // The approval marker is only trusted from a framework tool declared with
-        // `forwardsApproval` (the sub-agent delegating tools) AND carrying the
-        // non-forgeable `APPROVAL_REQUIRED` Symbol brand. A plain tool's output — or
-        // a delegating tool's LLM-shaped `result.object`, which an attacker can
-        // influence — is plain JSON and can never carry the Symbol, so it can never
-        // forge an approval/suspension.
         if (!toolDef?.forwardsApproval) {
             continue;
         }
@@ -255,12 +245,13 @@ export function checkForApprovals(stepResult, tools, runId) {
     }
     return approvals;
 }
-export function checkForCredentialRequests(stepResult, runId) {
+export function checkForCredentialRequests(stepResult) {
     const requests = [];
     for (const tr of stepResult.toolResults) {
+        // knowledge: decisions/security/ai-agent-credential-requests-are-symbol-branded.md
         if (tr.result &&
             typeof tr.result === 'object' &&
-            '__credentialRequired' in tr.result) {
+            CREDENTIAL_REQUIRED in tr.result) {
             const r = tr.result;
             const tc = stepResult.toolCalls.find((t) => t.toolCallId === tr.toolCallId);
             requests.push(new ToolCredentialRequired(tr.toolCallId, tc?.toolName ?? 'unknown', tc?.args ?? {}, r.credentialName, r.credentialType, r.connectUrl));
@@ -366,10 +357,6 @@ function handleCredentialRequests(requests, runId, channel, aiRunState, persisti
             suspendReason: 'credential',
             pendingApprovals,
         });
-        // The __credentialRequired tool result is suppressed from the stream, so
-        // credential-request events (with the runId needed for /resume) are the
-        // client's signal to show Connect/Ignore buttons — mirroring how
-        // approval-request suspensions work.
         for (const req of requests) {
             channel.send({
                 type: 'credential-request',
@@ -393,7 +380,6 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         resourceId: resolveOwnerResourceId(params, agentSessionScope(agentName), input.resourceId),
     };
     const streamContext = { channel, options };
-    // delegateState is attached after prepareAgentRun resolves the agent config
     const { agent, packageName, resolvedName, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, normalizedInput, params, sessionMap, streamContext);
     runnerParams.agentId = agentName;
     const singletonServices = getSingletonServices();
@@ -426,6 +412,8 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         }),
         ...(agent.aiMiddleware ?? []),
     ];
+    // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+    const sharedNotes = {};
     let modifiedMessages = runnerParams.messages;
     let modifiedInstructions = runnerParams.instructions;
     for (const mw of aiMiddlewares) {
@@ -433,6 +421,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             const result = await mw.modifyInput(singletonServices, {
                 messages: modifiedMessages,
                 instructions: modifiedInstructions,
+                shared: sharedNotes,
             });
             modifiedMessages = result.messages;
             modifiedInstructions = result.instructions;
@@ -440,6 +429,23 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     }
     runnerParams.messages = modifiedMessages;
     runnerParams.instructions = modifiedInstructions;
+    // Sent on the raw channel, ahead of the run. A voice client sent audio and so
+    // has no idea what it said; until this arrives its own message is a blank
+    // bubble. Ahead of the run rather than alongside it because the answer starts
+    // streaming within a few hundred milliseconds, and a question that appears
+    // after its answer reads as the wrong question.
+    const transcript = sharedNotes[SPOKEN_TRANSCRIPT];
+    if (typeof transcript === 'string') {
+        channel.send({ type: 'transcript', text: transcript });
+    }
+    // What goes into thread history is what the model was actually asked. For a
+    // spoken turn that is not what arrived over the wire: the wire carried a
+    // base64 audio blob, and persisting it would write megabytes of unreadable
+    // data into the history while losing the only readable record of the turn.
+    // Identity-checked rather than assumed — a middleware is free to rewrite the
+    // message list into something with no relation to the turn.
+    const lastModified = modifiedMessages[modifiedMessages.length - 1];
+    const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
         agentName,
         threadId,
@@ -450,8 +456,14 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         updatedAt: new Date(),
     });
     options?.onRunCreated?.(runId);
+    // Registered before the first model call and released in `finally`, so the
+    // window in which an interrupt can land is exactly the window in which there
+    // is something to interrupt.
+    const interruptHandle = registerInterruptibleRun(runId);
+    runnerParams.abortSignal = interruptHandle.signal;
+    runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
     if (storage) {
-        await storage.saveMessages(threadId, [userMessage]);
+        await storage.saveMessages(threadId, [persistedUserMessage]);
     }
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
@@ -464,6 +476,11 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 event,
                 allEvents,
                 state,
+                shared: sharedNotes,
+                // Sends downstream directly, so a hook can hand back the fast event
+                // now and push the slow one when it is ready.
+                emit: next,
+                signal: interruptHandle.signal,
             });
             if (result == null)
                 return;
@@ -489,12 +506,12 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;
-    // Tool results carrying the __credentialRequired marker must never reach
-    // the client or persisted history: the run suspends with credential-request
-    // events instead (mirroring approvals), and leaving the tool call
-    // unresulted is what lets the client resume it after connecting.
     const credentialFilteredChannel = {
         ...wrappedChannel,
+        // Returns what the inner send returns. Middleware runs asynchronously, so
+        // swallowing the promise here makes every `await channel.send(...)` upstream
+        // a no-op — including the one that waits for a buffering hook to flush
+        // before the channel closes.
         send: (event) => {
             if (event.type === 'tool-result' &&
                 event.result !== null &&
@@ -502,14 +519,10 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 '__credentialRequired' in event.result) {
                 return;
             }
-            wrappedChannel.send(event);
+            return wrappedChannel.send(event);
         },
     };
-    // In delegate mode (default), suppress parent's text from reaching the client
-    // AFTER a sub-agent has been called. If the parent responds directly (no delegation),
-    // its text goes through normally. Sub-agent text bypasses this path entirely
-    // (goes through subChannel → channel directly).
-    const isDelegateMode = agent.agentMode !== 'supervise' && meta.agents?.length;
+    const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length;
     const delegateState = { delegated: false };
     if (isDelegateMode) {
         streamContext.delegateState = delegateState;
@@ -521,7 +534,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 if (delegateState.delegated &&
                     (event.type === 'text-delta' || event.type === 'reasoning-delta'))
                     return;
-                credentialFilteredChannel.send(event);
+                return credentialFilteredChannel.send(event);
             },
             delegateState,
         }
@@ -535,7 +548,6 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             streamChannel: outputChannel,
             persistingChannel,
             channel,
-            runId,
             aiMiddlewares,
         });
         if (loopResult.outcome === 'approval') {
@@ -547,11 +559,38 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             return persistingChannel.fullText;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, runId);
-        channel.send({ type: 'done' });
+        // Through the middleware rather than straight at the channel, and awaited.
+        // `done` is the only signal a stream hook gets that the reply is over, and
+        // the ones that buffer need it: `voiceOutput` speaks a trailing fragment
+        // that never reached a full stop, and waits for audio it has already paid
+        // to synthesize. Sent raw, that work is discarded by the `close()` below.
+        await outputChannel.send({ type: 'done' });
         channel.close();
         return persistingChannel.fullText;
     }
     catch (err) {
+        // An interrupt is not a failure: the truncated text is real output the user
+        // already heard part of, so it is persisted and marked rather than dropped.
+        const interruption = interruptHandle.interruption;
+        if (interruption || isAbortError(err)) {
+            await persistingChannel.flush({ interrupted: true });
+            await aiRunState.updateRun(runId, { status: 'interrupted' });
+            // Deliberately not awaited. A tool still running must not hold the stream
+            // open — the whole point of barge-in is that the agent stops now — so the
+            // note lands later and the next run on this thread waits for it instead.
+            if (storage) {
+                trackInterruptNote(threadId, persistOrphanedToolResults(interruptHandle, storage, threadId));
+            }
+            channel.send({
+                type: 'interrupted',
+                runId,
+                text: persistingChannel.fullText,
+                reason: interruption?.reason ?? 'user',
+            });
+            channel.send({ type: 'done' });
+            channel.close();
+            return persistingChannel.fullText;
+        }
         for (const mw of aiMiddlewares) {
             if (mw.onError) {
                 try {
@@ -561,9 +600,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                         messages: runnerParams.messages,
                     });
                 }
-                catch {
-                    // onError hooks must not affect error flow
-                }
+                catch { }
             }
         }
         await aiRunState.updateRun(runId, {
@@ -578,6 +615,54 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         channel.close();
         return persistingChannel.fullText;
     }
+    finally {
+        interruptHandle.release();
+    }
+}
+/**
+ * Stop an in-flight run on behalf of a caller, after checking the run is theirs.
+ *
+ * Unlike {@link resumeAIAgent} this needs no channel: it does not continue the
+ * stream, it ends one. The `interrupted` event and the truncated message are
+ * emitted by the original {@link streamAIAgent} call on its own channel, so this
+ * can be reached over a plain RPC while the stream is held open elsewhere —
+ * which is exactly the shape a voice barge-in needs.
+ *
+ * Ownership is the whole gate, deliberately without {@link assertAgentAuthorized}.
+ * Resuming re-enters the agent and approves a tool call, so a revoked grant must
+ * block it; stopping is the opposite — if a caller's access to an agent was
+ * revoked mid-run, being able to stop their own run is harmless and arguably
+ * what you want.
+ *
+ * Returns `false` when there was nothing to stop. Racing a run that finishes on
+ * its own is the normal case in voice, so it is not an error.
+ */
+export async function interruptAIAgent(input, params) {
+    const { aiRunState, logger } = getSingletonServices();
+    if (!aiRunState) {
+        throw new Error('AIRunStateService not available in singletonServices');
+    }
+    const run = await aiRunState.getRun(input.runId);
+    if (!run) {
+        throw new Error(`No run found for runId ${input.runId}`);
+    }
+    assertResourceOwner(resolveOwnerResourceId(params, agentSessionScope(run.agentName), run.resourceId), run.resourceId, 'run');
+    const stopped = signalRunInterrupt(input.runId, {
+        reason: input.reason ?? 'user',
+    });
+    // A run still marked `running` that this process cannot abort is executing on
+    // another instance. Returning a bare `false` there is indistinguishable from
+    // "it already finished", so the one deployment shape this registry does not
+    // cover fails silently — an agent that simply refuses to shut up, with nothing
+    // in the logs. Say so instead. See `signalRunInterrupt` for the fix (fan the
+    // interrupt out over eventHub so every instance tries locally).
+    if (!stopped && run.status === 'running') {
+        logger?.warn(`Could not interrupt run ${input.runId}: it is running in another process. ` +
+            'Interrupts are process-local; fan them out over eventHub to support multiple instances.');
+    }
+    // Reported after the abort so it names what is *still* running: aborting the
+    // model call does nothing to a tool already executing.
+    return { stopped, inFlightTools: getInFlightTools(input.runId) };
 }
 export async function resumeAIAgent(input, channel, params, options) {
     const singletonServices = getSingletonServices();
@@ -589,16 +674,12 @@ export async function resumeAIAgent(input, channel, params, options) {
     if (!run) {
         throw new Error(`No run found for runId ${input.runId}`);
     }
-    assertResourceOwner(resolveOwnerResourceId(params, agentSessionScope(run.agentName), run.resourceId), run.resourceId, 'run');
+    assertResourcePrincipalOwner(params, agentSessionScope(run.agentName), run.resourceId, 'run');
     const pending = run.pendingApprovals?.find((p) => p.toolCallId === input.toolCallId);
     if (!pending) {
         throw new Error(`No pending approval for toolCallId ${input.toolCallId} on run ${input.runId}`);
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
-    // Gate before resolving the approval: recording it is a persisted side
-    // effect, so an unauthorized caller must not reach it. Run ownership alone is
-    // not enough — a grant revoked while the run was suspended must stop the
-    // caller from approving its pending tool calls.
     await assertAgentAuthorized(agent, params, packageName);
     await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { storage } = resolveMemoryServices(agent, singletonServices);
@@ -639,11 +720,9 @@ export async function resumeAIAgent(input, channel, params, options) {
                 : pending.agentName,
             result: denialResult,
         });
-        // Check remaining pending approvals
         const updatedRun = await aiRunState.getRun(run.runId);
         const remaining = updatedRun?.pendingApprovals ?? [];
         if (remaining.length > 0) {
-            // Still waiting for more approvals - don't continue step loop
             channel.send({ type: 'done' });
             channel.close();
             return;
@@ -748,11 +827,9 @@ export async function resumeAIAgent(input, channel, params, options) {
             ...(isError ? { isError: true } : {}),
         });
     }
-    // Check remaining pending approvals after processing this one
     const updatedRun = await aiRunState.getRun(run.runId);
     const remaining = updatedRun?.pendingApprovals ?? [];
     if (remaining.length > 0) {
-        // Still waiting for more approvals - don't continue step loop
         channel.send({ type: 'done' });
         channel.close();
         return;
@@ -786,6 +863,8 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         }),
         ...(agent.aiMiddleware ?? []),
     ];
+    // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+    const sharedNotes = {};
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
     for (const mw of aiMiddlewares) {
@@ -793,11 +872,17 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             const result = await mw.modifyInput(singletonServices, {
                 messages: modifiedMessages,
                 instructions: modifiedInstructions,
+                shared: sharedNotes,
             });
             modifiedMessages = result.messages;
             modifiedInstructions = result.instructions;
         }
     }
+    // Resuming is as interruptible as the first turn. It is the same person
+    // listening to the same voice, and after an approval it is where most of the
+    // reply actually gets spoken — an approved delete is followed by the agent
+    // talking about it, and that is a normal thing to talk over.
+    const interruptHandle = registerInterruptibleRun(run.runId);
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
         .map((mw) => {
@@ -809,6 +894,11 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
                 event,
                 allEvents,
                 state,
+                shared: sharedNotes,
+                // Sends downstream directly, so a hook can hand back the fast event
+                // now and push the slow one when it is ready.
+                emit: next,
+                signal: interruptHandle.signal,
             });
             if (result == null)
                 return;
@@ -844,10 +934,13 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         tools: resumeTools,
         maxSteps: 1,
         toolChoice: (agent.toolChoice ?? 'auto'),
+        providerOptions: agent.providerOptions,
         outputSchema: meta?.outputSchema
             ? pikkuState(packageName, 'misc', 'schemas').get(meta.outputSchema)
             : undefined,
     };
+    runnerParams.abortSignal = interruptHandle.signal;
+    runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
     try {
         const loopResult = await runStreamStepLoop({
             agent,
@@ -857,7 +950,6 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             streamChannel: wrappedChannel,
             persistingChannel,
             channel,
-            runId: run.runId,
             aiMiddlewares,
         });
         if (loopResult.outcome === 'approval') {
@@ -869,10 +961,33 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             return;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, run.runId);
-        channel.send({ type: 'done' });
+        // Through the middleware, for the same reason as the first turn — and it
+        // matters more here. After an approval, most of what gets spoken is the
+        // agent talking about what it just did, so this is the half of the reply a
+        // dropped flush would silence.
+        await wrappedChannel.send({ type: 'done' });
         channel.close();
     }
     catch (err) {
+        // Same reasoning as the first turn: an interrupt is not a failure, and the
+        // part of the reply the user already heard is real output.
+        const interruption = interruptHandle.interruption;
+        if (interruption || isAbortError(err)) {
+            await persistingChannel.flush({ interrupted: true });
+            await aiRunState.updateRun(run.runId, { status: 'interrupted' });
+            if (storage) {
+                trackInterruptNote(run.threadId, persistOrphanedToolResults(interruptHandle, storage, run.threadId));
+            }
+            channel.send({
+                type: 'interrupted',
+                runId: run.runId,
+                text: persistingChannel.fullText,
+                reason: interruption?.reason ?? 'user',
+            });
+            channel.send({ type: 'done' });
+            channel.close();
+            return;
+        }
         for (const mw of aiMiddlewares) {
             if (mw.onError) {
                 try {
@@ -882,9 +997,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
                         messages: runnerParams.messages,
                     });
                 }
-                catch {
-                    // onError hooks must not affect error flow
-                }
+                catch { }
             }
         }
         await aiRunState.updateRun(run.runId, {
@@ -898,4 +1011,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         channel.send({ type: 'done' });
         channel.close();
     }
+    finally {
+        interruptHandle.release();
+    }
 }