@pikku/core 0.12.72 → 0.12.74

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

@@ -3,8 +3,9 @@ import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.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 +16,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 +38,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 +53,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 +77,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 +123,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 +160,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 +194,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 +216,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 +224,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 +244,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 +356,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 +379,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();
@@ -450,6 +435,12 @@ 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]);
     }
@@ -464,6 +455,10 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 event,
                 allEvents,
                 state,
+                // 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 +484,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 +497,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 +512,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 +526,6 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             streamChannel: outputChannel,
             persistingChannel,
             channel,
-            runId,
             aiMiddlewares,
         });
         if (loopResult.outcome === 'approval') {
@@ -547,11 +537,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 +578,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 +593,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 +652,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 +698,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 +805,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;
@@ -798,6 +853,11 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             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 +869,10 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
                 event,
                 allEvents,
                 state,
+                // 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 +908,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 +924,6 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             streamChannel: wrappedChannel,
             persistingChannel,
             channel,
-            runId: run.runId,
             aiMiddlewares,
         });
         if (loopResult.outcome === 'approval') {
@@ -869,10 +935,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 +971,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 +985,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         channel.send({ type: 'done' });
         channel.close();
     }
+    finally {
+        interruptHandle.release();
+    }
 }

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

@@ -1,7 +1,9 @@
 import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { AIProviderOptions } from '../../services/ai-agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
+import type { ApprovalPolicy } from '../channel/channel-rpc.js';
 export interface AIThread {
     id: string;
     resourceId: string;
@@ -49,6 +51,23 @@ export interface AIMessage {
     toolCalls?: AIToolCall[];
     toolResults?: AIToolResult[];
     reasoningContent?: string;
+    /**
+     * Set on an assistant message whose generation was cut short by
+     * an interrupt — the text is a mid-sentence fragment, not a reply.
+     * Carried into the next turn's context so the model can see it said only
+     * this much before being talked over, and decide for itself whether to
+     * resume, restate or move on. Storage that drops unknown fields loses the
+     * marker but keeps the fragment, which degrades to a truncated reply.
+     */
+    interrupted?: boolean;
+    /**
+     * Set on a tool message whose result arrived after the run was interrupted,
+     * so the model never got to describe it. The work happened; only the reply
+     * about it was lost. It is ordinary thread context on the next turn — the
+     * model raises it unprompted ("that deploy did go through") rather than the
+     * result being silently dropped or replayed as a fresh tool call.
+     */
+    undelivered?: boolean;
     createdAt: Date;
 }
 export interface AIAgentStep {
@@ -113,13 +132,24 @@ export interface AIAgentOutput {
  * another user's or org's threads.
  */
 export type SessionScope = 'user' | 'org';
-export interface AIAgentToolDef {
+/**
+ * `ApprovalPolicy` is shared with channel capabilities, but `Partial` here:
+ * absent `needsApproval` means "do not ask", which is safe because a tool is
+ * written by whoever runs the server it executes on. A capability runs on
+ * someone else's machine, so it requires the field instead.
+ */
+export interface AIAgentToolDef extends Partial<ApprovalPolicy> {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
     execute: (input: unknown) => Promise<unknown>;
-    needsApproval?: boolean;
-    approvalDescriptionFn?: (input: unknown) => Promise<string>;
+    /**
+     * Mirrors the pikku function's `readonly` flag. A read that gets interrupted
+     * is discarded rather than reported: nothing changed, and by the next turn
+     * the data may be stale anyway — re-reading is cheaper than explaining a
+     * result the user never asked to hear about.
+     */
+    readonly?: boolean;
     /**
      * Set only by the framework on sub-agent delegating tools. Such a tool may
      * legitimately return an `__approvalRequired` marker to forward a nested
@@ -144,6 +174,27 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
         event: AIStreamEvent;
         allEvents: readonly AIStreamEvent[];
         state: State;
+        /**
+         * Push an event into the stream *after* this call has returned.
+         *
+         * Returning events blocks the stream until the hook resolves, which is
+         * right for anything derived from the event and wrong for anything slow.
+         * Speech is the motivating case: awaiting a text-to-speech call before
+         * returning the text delta stalls the reader at every full stop and
+         * serialises synthesis behind playback. Return the text immediately,
+         * start the slow work, and `emit` its result when it lands.
+         *
+         * Ordering among emitted events is the caller's problem — chain them if
+         * it matters — and a hook that emits must make sure anything still
+         * outstanding has landed before it lets `done` through.
+         */
+        emit: (event: AIStreamEvent) => Promise<void>;
+        /**
+         * Aborts when the run is interrupted. Pass it to any provider call the
+         * hook makes: work started for a reply the user has already talked over
+         * is billed but never heard.
+         */
+        signal?: AbortSignal;
     }) => Promise<AIStreamEvent | AIStreamEvent[] | null> | AIStreamEvent | AIStreamEvent[] | null;
     modifyOutput?: (services: Services, ctx: {
         text: string;
@@ -216,8 +267,19 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     description: string;
     summary?: string;
     errors?: string[];
+    /**
+     * The three fields below are the system prompt. `buildInstructions` joins
+     * whichever are set with a blank line, always in this order — role, then
+     * personality, then goal — and appends the tool-usage rules if the agent has
+     * tools. Nothing checks them against each other: the split is there to keep a
+     * prompt legible, and text put in the wrong one still reaches the model.
+     *
+     * Who the agent is. 'You are a support engineer triaging inbound bugs.'
+     */
     role?: string;
+    /** How it should sound: tone, vocabulary, how much it says at a time. */
     personality?: string;
+    /** What it is for — the only one of the three that is required. */
     goal: string;
     model: string;
     temperature?: number;
@@ -230,6 +292,16 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     memory?: AIAgentMemoryConfig;
     maxSteps?: number;
     toolChoice?: 'auto' | 'required' | 'none';
+    /**
+     * Per-provider model settings, keyed by provider id and passed through
+     * untouched — for anything only one vendor offers, which the fields above
+     * deliberately do not try to unify.
+     *
+     * `{ openai: { reasoningEffort: 'minimal' } }` is the one that matters for
+     * voice: on gpt-5-mini it measured 0.9s to first token against 2.5s at the
+     * default, and a spoken reply is waited through rather than skimmed.
+     */
+    providerOptions?: AIProviderOptions;
     input?: unknown;
     output?: unknown;
     tags?: string[];
@@ -361,6 +433,14 @@ export type AIStreamEvent = {
     type: 'suspended';
     reason: 'rpc-missing';
     missingRpcs: string[];
+} | {
+    type: 'interrupted';
+    runId: string;
+    /** The truncated assistant text at the moment generation stopped. */
+    text: string;
+    reason: 'speech' | 'user' | 'timeout';
+    agent?: string;
+    session?: string;
 } | {
     type: 'done';
 };
@@ -392,7 +472,7 @@ export interface AgentRunState {
     agentName: string;
     threadId: string;
     resourceId: string;
-    status: 'running' | 'suspended' | 'completed' | 'failed';
+    status: 'running' | 'suspended' | 'completed' | 'failed' | 'interrupted';
     errorMessage?: string;
     suspendReason?: 'approval' | 'credential' | 'rpc-missing';
     missingRpcs?: string[];

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

@@ -1,9 +1,11 @@
-export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './ai-agent-helpers.js';
 export { wrapChannelWithAGUI, type AGUIEvent } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
-export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { voiceInput } from './voice-input.js';
-export { voiceOutput } from './voice-output.js';
+export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, } from './voice-input.js';
+export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, } from './voice-output.js';
+export { AgentInterruptedError, awaitPendingInterruptNote, getInFlightTools, isAbortError, isRunInterruptible, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
+export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, OrphanedToolResult, } from './ai-agent-interrupt.js';
 export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';
 export type { AIAgentInput, AIAgentInputAttachment, AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AIContentPart, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';

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

@@ -1,8 +1,9 @@
-export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './ai-agent-helpers.js';
 export { wrapChannelWithAGUI } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
-export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { voiceInput } from './voice-input.js';
-export { voiceOutput } from './voice-output.js';
+export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, } from './voice-input.js';
+export { voiceOutput, unspeakableScripts, voiceForText, } from './voice-output.js';
+export { AgentInterruptedError, awaitPendingInterruptNote, getInFlightTools, isAbortError, isRunInterruptible, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';