@pikku/core 0.12.72 → 0.12.74

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

@@ -6,118 +6,72 @@ import { verifyScopes } from '../../scopes.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from './ai-agent-utils.js';
+import { awaitPendingInterruptNote } from './ai-agent-interrupt.js';
 import { streamAIAgent } from './ai-agent-stream.js';
 import { runAIAgent } from './ai-agent-runner.js';
 import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
 import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
-/**
- * The ownership key for a thread/run: the trusted principal (the authenticated
- * `session.userId` for `'user'` scope, or `session.orgId` for `'org'` scope)
- * composed with the client-supplied `resourceId` as a sub-partition —
- * `principal:resourceId`. Because the principal is always the prefix, a client
- * `resourceId` can sub-divide within the caller's own boundary but can never
- * widen access to another user's or org's threads.
- *
- * Idempotent: a value that is already within the caller's namespace (top-level
- * re-entry, sub-agent recursion, or resume, which all pass an already-composite
- * `resourceId`) is returned unchanged rather than double-composed.
- *
- * `'org'` scope with no session org throws {@link ForbiddenError} — falling back
- * to a bare/shared key would leak across organizations. Sessionless `'user'`
- * wirings have no trusted principal and fall back to the requested `resourceId`
- * as a best-effort partition key.
- */
-export function resolveOwnerResourceId(params, sessionScope, requestedResourceId) {
+export function resolveSessionPrincipal(params, sessionScope) {
     const session = params.sessionService?.get();
-    let principal;
     if ((sessionScope ?? 'user') === 'org') {
         if (!session?.orgId) {
             throw new ForbiddenError('This agent is org-scoped but the session has no organization');
         }
-        principal = session.orgId;
+        return session.orgId;
     }
-    else {
-        principal = session?.userId;
+    return session?.userId;
+}
+export function resolveOwnerResourceId(params, sessionScope, requestedResourceId) {
+    const principal = resolveSessionPrincipal(params, sessionScope);
+    if (!principal) {
+        params.anonymousOwnerResourceId ??= `anon-${randomUUID()}`;
+        return params.anonymousOwnerResourceId;
     }
-    if (!principal)
-        return requestedResourceId;
     if (requestedResourceId === principal ||
         requestedResourceId.startsWith(`${principal}:`)) {
         return requestedResourceId;
     }
     return `${principal}:${requestedResourceId}`;
 }
-/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export function assertResourcePrincipalOwner(params, sessionScope, storedResourceId, kind) {
+    const principal = resolveSessionPrincipal(params, sessionScope);
+    if (!principal || !isOwnedByPrincipal(storedResourceId, principal)) {
+        throw new ForbiddenError(`Not authorized to access this ${kind}`);
+    }
+}
 export function agentSessionScope(agentName) {
     return resolveAgent(agentName).agent.sessionScope ?? 'user';
 }
-/**
- * Enforce that a stored thread/run belongs to the caller's owner resource,
- * throwing {@link ForbiddenError} (without echoing the id, to avoid an
- * existence oracle) on a mismatch.
- */
 export function assertResourceOwner(ownerResourceId, storedResourceId, kind) {
     if (storedResourceId !== ownerResourceId) {
         throw new ForbiddenError(`Not authorized to access this ${kind}`);
     }
 }
-/** A session's trusted principals, in the order they may be read as. */
 export function sessionPrincipals(session) {
     return [session?.userId, session?.orgId].filter((principal) => Boolean(principal));
 }
-/**
- * Whether `storedResourceId` belongs to `principal` under the composition
- * {@link resolveOwnerResourceId} performs — either the bare principal or one of
- * its `principal:` sub-partitions. The `:` is required so that `alice` does not
- * match a `alice-evil:…` lookalike.
- */
 export function isOwnedByPrincipal(storedResourceId, principal) {
     return (storedResourceId === principal ||
         storedResourceId.startsWith(`${principal}:`));
 }
-/**
- * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
- *
- * Returns `undefined` — not `[]` — for a session with no principal, because an
- * empty list means "match nothing" whereas a sessionless deployment (agent
- * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
- * rather than at each call site stops it from being re-derived inconsistently.
- */
 export function threadOwnerConstraint(session) {
-    const principals = sessionPrincipals(session);
-    return principals.length > 0 ? principals : undefined;
+    return sessionPrincipals(session);
 }
-/**
- * Whether a stored thread/run may be read by the caller. Shaped as a predicate
- * so it can back a `pikkuPermission` — authorization belongs in a function's
- * `permissions` field, never in its body.
- *
- * Unlike {@link assertResourceOwner}, which compares against a single composed
- * owner key on the run path, this guards the thread-management reads where the
- * caller supplies only a `threadId` — so ownership has to be derived from the
- * session rather than from the request.
- *
- * A session with no principal means the deployment opted out of authorization
- * (agent `no-auth`), so there is no ownership model to enforce and access is not
- * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
- * bare resourceId.
- */
 export function canAccessThread(storedResourceId, session) {
     const principals = sessionPrincipals(session);
     if (principals.length === 0)
-        return true;
+        return false;
     return principals.some((principal) => isOwnedByPrincipal(storedResourceId, principal));
 }
+export const APPROVAL_REQUIRED = Symbol('pikku.ai.approvalRequired');
 /**
- * Non-forgeable brand for the sub-agent approval marker. Only framework code
- * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
- * sub-agent's LLM-shaped `result.object` — plain JSON — cannot carry a Symbol,
- * so `checkForApprovals` trusts the brand rather than the `__approvalRequired`
- * string key to decide an approval must be surfaced.
+ * In-process brand proving a credential request was produced by pikku itself and
+ * not by tool output an attacker can influence. Never serialized — a value that
+ * has crossed a JSON boundary has lost the brand and is treated as untrusted.
  */
-export const APPROVAL_REQUIRED = Symbol('pikku.ai.approvalRequired');
+export const CREDENTIAL_REQUIRED = Symbol('pikku.ai.credentialRequired');
 export class ToolApprovalRequired extends PikkuError {
     toolCallId;
     toolName;
@@ -154,10 +108,6 @@ export class ToolCredentialRequired extends PikkuError {
         this.connectUrl = connectUrl;
     }
 }
-/**
- * Given a list of tool names (e.g. ["oauth-api:getProfile"]),
- * returns the wire OAuth credentials required by their addons.
- */
 export function getAddonCredentialRequirements(toolNames) {
     const requirements = new Map();
     for (const toolName of toolNames) {
@@ -211,26 +161,6 @@ export const resolveAgent = (agentName) => {
     }
     throw new Error(`AI agent not found: ${agentName}`);
 };
-/**
- * Enforces an agent's own authorization before it runs: session presence
- * (`auth`), then `scopes`, then `permissions`.
- *
- * The ordering mirrors the function runner — scopes are an AND gate checked
- * first, so they can only ever narrow access, and a missing scope short-circuits
- * before any permission function does I/O.
- *
- * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
- * required only when `auth: true` is set explicitly. An agent is normally
- * reached from a function that has already enforced its own auth, and agents are
- * also run from genuinely sessionless contexts (crons, queue workers), so
- * requiring a session by default would reject those without adding a meaningful
- * gate. `scopes` and `permissions` are always enforced when declared.
- *
- * Globals are evaluated here too (via {@link runPermissions}) rather than being
- * assumed to have already run: an agent is reachable from entry points that do
- * not go through the function runner, and re-evaluating an AND gate of
- * side-effect-free predicates is idempotent.
- */
 export async function assertAgentAuthorized(agent, params, packageName) {
     const session = params.sessionService
         ? await params.sessionService.get()
@@ -322,31 +252,13 @@ export function createScopedChannel(parent, agentName, session) {
         setState: (s) => parent.setState(s),
         getState: () => parent.getState(),
         clearState: () => parent.clearState(),
+        remote: (funcName, data) => parent.remote(funcName, data),
     };
 }
-/**
- * Build the run input for a delegated sub-agent.
- *
- * `context` is the PARENT run's identifier block (the "Current context" text
- * with organizationId, project/stage ids). A sub-agent's tool-call schema only
- * carries { message, session }, so unless the sub-agent inherits the parent's
- * context it never sees the authoritative ids — it depends on the model
- * re-typing them into `message`, which weak models botch, causing
- * schema/permission rejections and retry loops. Forwarding it here is the
- * regression this seam guards.
- */
 export function buildSubAgentRunInput(message, threadId, resourceId, parentContext) {
     return { message, threadId, resourceId, context: parentContext };
 }
-export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode, 
-// The parent run's `context` (the "Current context" identifier block). A
-// delegated sub-agent's tool-call input schema only carries { message,
-// session }, so without inheriting this the sub-agent never sees the
-// authoritative ids (organizationId, project/stage ids) — it depends on the
-// model re-typing them into `message`, which weak models botch, causing
-// schema/permission rejections and retry loops. Forward it so the sub-agent
-// gets the same context block in its instructions.
-parentContext) {
+export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode, parentContext) {
     const singletonServices = getSingletonServices();
     const tools = [];
     const missingRpcs = [];
@@ -354,7 +266,22 @@ parentContext) {
     const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
     if (!meta)
         return { tools, missingRpcs };
-    // Get session for permission filtering
+    /**
+     * A tool's description is what the model is told it does, and the main thing
+     * it chooses between tools on. It does not survive into the meta registered at
+     * boot: `description` is classed as a verbose field, so the bundled copy has
+     * it stripped and `fnMeta.description` is always undefined — every tool was
+     * being offered under its own bare name regardless of what its author wrote.
+     *
+     * `getFunctionsMeta` reads the verbose file and falls back to the minimal one,
+     * recovering the authored description wherever the generated `.pikku`
+     * directory is readable. Where it is not — no `metaService`, or a deployment
+     * shipping only the stripped copy — tools fall back to their name, which is
+     * what they did before this lookup existed.
+     */
+    const describedFunctions = await singletonServices.metaService
+        ?.getFunctionsMeta()
+        .catch(() => undefined);
     const session = params.sessionService
         ? await params.sessionService.get()
         : null;
@@ -389,10 +316,6 @@ parentContext) {
                 missingRpcs.push(toolName);
                 continue;
             }
-            // Filter out tools the user doesn't have auth for. The `pikkuAuth` brand
-            // only survives on the live permission objects in the function config, so
-            // the check reads those rather than the metadata (whose by-name registry
-            // is never populated, which would let every gated tool through).
             if (fnMeta.permissions?.length) {
                 if (!session)
                     continue;
@@ -415,7 +338,6 @@ parentContext) {
             }
             const needsApproval = approvalPolicy === 'all' ||
                 (approvalPolicy === 'explicit' && fnMeta?.approvalRequired);
-            // Build approvalDescriptionFn if the function has an approvalDescription configured
             let approvalDescriptionFn;
             if (needsApproval && pikkuFuncId) {
                 const funcConfig = pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId);
@@ -445,10 +367,13 @@ parentContext) {
             }
             tools.push({
                 name: toolName.replaceAll('@', '_').replaceAll(':', '__'),
-                description: fnMeta?.description || fnMeta?.title || toolName,
+                description: describedFunctions?.[pikkuFuncId]?.description ||
+                    fnMeta?.description ||
+                    toolName,
                 inputSchema,
                 needsApproval: needsApproval || undefined,
                 approvalDescriptionFn,
+                readonly: fnMeta?.readonly || undefined,
                 execute: async (toolInput) => {
                     const wire = params.sessionService
                         ? { ...createMiddlewareSessionWireProps(params.sessionService) }
@@ -467,8 +392,6 @@ parentContext) {
                 singletonServices.logger.warn(`Sub-agent '${subAgentName}' not found in agent registry`);
                 continue;
             }
-            // Filter out sub-agents the user doesn't have auth for, reading the live
-            // agent config for the same reason the tool path does.
             if (subMeta.permissions?.length) {
                 if (!session)
                     continue;
@@ -513,8 +436,6 @@ parentContext) {
                             input: message,
                         });
                         const subChannel = createScopedChannel(channel, subAgentName, session);
-                        // In supervise mode, suppress sub-agent text from reaching the client.
-                        // Approvals still flow through normally.
                         const effectiveChannel = isDelegate
                             ? subChannel
                             : {
@@ -545,7 +466,6 @@ parentContext) {
                         });
                         return resultText;
                     }
-                    // No stream context: sub-agent runs non-streaming
                     const result = await runAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), params, agentSessionMap);
                     if (result.status === 'suspended' &&
                         result.pendingApprovals?.length) {
@@ -610,11 +530,6 @@ parentContext) {
             });
         }
     }
-    // A tool's execute() can throw (bad input, RPC failure, DB error, ...). The AI
-    // SDK catches that at the tool-call boundary and turns it into a conversational
-    // "tool error" reply — without this, the exception never reaches pikku's own
-    // logger, so a failing tool is undiagnosable server-side. Log unconditionally,
-    // even when no aiMiddleware afterToolCall hook is registered to see it.
     for (const tool of tools) {
         const originalExecute = tool.execute;
         tool.execute = async (toolInput) => {
@@ -622,6 +537,13 @@ parentContext) {
                 return await originalExecute(toolInput);
             }
             catch (err) {
+                if (err?.payload?.error === 'missing_credential') {
+                    return {
+                        [CREDENTIAL_REQUIRED]: true,
+                        __credentialRequired: true,
+                        ...err.payload,
+                    };
+                }
                 singletonServices.logger.error(`AI agent tool '${tool.name}' threw during execute()`, err);
                 throw err;
             }
@@ -726,6 +648,11 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     }
     let messages = [];
     if (storage) {
+        // A tool whose run was interrupted may still be writing its result to this
+        // thread. In voice the next turn lands within a second or two, so without
+        // this the model would load context that is missing the very thing it is
+        // about to be asked about.
+        await awaitPendingInterruptNote(threadId);
         messages = await storage.getMessages(threadId, {
             lastN: memoryConfig?.lastMessages ?? 20,
         });
@@ -758,7 +685,6 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
         instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;
     }
     const resolved = resolveModelConfig(resolvedName, agent);
-    // Per-request overrides
     if (input.model) {
         resolved.model = resolveModelConfig(resolvedName, {
             ...agent,
@@ -777,6 +703,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
         tools,
         maxSteps: 1,
         toolChoice: agent.toolChoice ?? 'auto',
+        providerOptions: agent.providerOptions,
         outputSchema,
     };
     return {

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

@@ -1,10 +1,11 @@
 import type { CoreAIAgent } from './ai-agent.types.js';
 import type { AIRunStateService } from '../../services/ai-run-state-service.js';
+import { type RunAIAgentParams } from './ai-agent-prepare.js';
 export declare const addAIAgent: (agentName: string, agent: CoreAIAgent<any, any>, packageName?: string | null) => void;
 export declare function approveAIAgent(aiRunState: AIRunStateService, runId: string, approvals: {
     toolCallId: string;
     approved: boolean;
-}[], expectedAgentName?: string): Promise<{
+}[], expectedAgentName?: string, params?: RunAIAgentParams): Promise<{
     status: 'resumed' | 'suspended';
     runId: string;
     approved: string[];

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

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../pikku-state.js';
+import { agentSessionScope, assertAgentAuthorized, assertResourcePrincipalOwner, resolveAgent, } from './ai-agent-prepare.js';
 export const addAIAgent = (agentName, agent, packageName = null) => {
     const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
     const agentMeta = agentsMeta[agentName];
@@ -12,17 +13,20 @@ export const addAIAgent = (agentName, agent, packageName = null) => {
     }
     agents.set(agentName, agent);
 };
-export async function approveAIAgent(aiRunState, runId, approvals, expectedAgentName) {
+export async function approveAIAgent(aiRunState, runId, approvals, expectedAgentName, params = {}) {
     if (!aiRunState)
         throw new Error('AIRunStateService not available');
     const run = await aiRunState.getRun(runId);
     if (!run)
         throw new Error('Run not found: ' + runId);
+    assertResourcePrincipalOwner(params, agentSessionScope(run.agentName), run.resourceId, 'run');
     if (expectedAgentName && run.agentName !== expectedAgentName) {
         throw new Error(`Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
     }
     if (run.status !== 'suspended')
         throw new Error('Run is not suspended: ' + run.status);
+    const { agent, packageName } = resolveAgent(run.agentName);
+    await assertAgentAuthorized(agent, params, packageName);
     const approvedIds = new Set(approvals.filter((a) => a.approved).map((a) => a.toolCallId));
     const rejectedIds = new Set(approvals.filter((a) => !a.approved).map((a) => a.toolCallId));
     const remaining = (run.pendingApprovals ?? []).filter((p) => !approvedIds.has(p.toolCallId) && !rejectedIds.has(p.toolCallId));

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

@@ -1,6 +1,7 @@
 import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourcePrincipalOwner, assertAgentAuthorized, } from './ai-agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
+import { AgentInterruptedError, isAbortError, persistOrphanedToolResults, registerInterruptibleRun, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
@@ -95,6 +96,13 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
         createdAt: new Date(),
         updatedAt: new Date(),
     });
+    // Registered on the same terms as `streamAIAgent`. A run created here is
+    // visible to `interruptAIAgent` through `aiRunState` either way, so skipping
+    // this would leave that call finding the run, passing the ownership check and
+    // then failing to stop it — reported as if it were running on another host.
+    const interruptHandle = registerInterruptibleRun(runId);
+    runnerParams.abortSignal = interruptHandle.signal;
+    runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
     try {
         const accumulatedSteps = [];
         const totalUsage = { inputTokens: 0, outputTokens: 0 };
@@ -146,7 +154,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             });
             if (stepResult.toolCalls.length === 0)
                 break;
-            const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools, runId);
+            const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools);
             if (approvalsNeeded.length > 0) {
                 for (const approval of approvalsNeeded) {
                     const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
@@ -154,9 +162,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                         try {
                             approval.reason = await toolDef.approvalDescriptionFn(approval.args);
                         }
-                        catch {
-                            // If description generation fails, continue without it
-                        }
+                        catch { }
                     }
                 }
                 const pendingApprovals = approvalsNeeded.map((a) => a.agentRunId
@@ -255,6 +261,18 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
         };
     }
     catch (error) {
+        // An interrupt is not a failure, so it skips the `onError` hooks and never
+        // becomes an `errorMessage`. Unlike the streaming path there is no partial
+        // reply to hand back — nothing was delivered — so the caller gets a typed
+        // throw it can tell apart from a provider outage instead of a result.
+        const interruption = interruptHandle.interruption;
+        if (interruption || isAbortError(error)) {
+            await aiRunState.updateRun(runId, { status: 'interrupted' });
+            if (storage) {
+                trackInterruptNote(threadId, persistOrphanedToolResults(interruptHandle, storage, threadId));
+            }
+            throw new AgentInterruptedError(runId, interruption ?? { reason: 'user' });
+        }
         for (const mw of aiMiddlewares) {
             if (mw.onError) {
                 try {
@@ -264,9 +282,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                         messages: runnerParams.messages,
                     });
                 }
-                catch {
-                    // onError hooks must not affect error flow
-                }
+                catch { }
             }
         }
         await aiRunState.updateRun(runId, {
@@ -275,6 +291,9 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
         });
         throw error;
     }
+    finally {
+        interruptHandle.release();
+    }
 }
 export async function resumeAIAgentSync(runId, approvals, params, expectedAgentName) {
     const singletonServices = getSingletonServices();
@@ -285,7 +304,7 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
     const run = await aiRunState.getRun(runId);
     if (!run)
         throw new Error(`No run found for runId ${runId}`);
-    assertResourceOwner(resolveOwnerResourceId(params, agentSessionScope(run.agentName), run.resourceId), run.resourceId, 'run');
+    assertResourcePrincipalOwner(params, agentSessionScope(run.agentName), run.resourceId, 'run');
     if (expectedAgentName && run.agentName !== expectedAgentName) {
         throw new Error(`Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
     }
@@ -293,9 +312,6 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         throw new Error(`Run ${runId} is not suspended (status: ${run.status})`);
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
-    // Resuming re-runs the agent, so it re-runs the agent's gate. 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);
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
@@ -328,7 +344,6 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
             const rawArgs = typeof pending.args === 'string'
                 ? JSON.parse(pending.args)
                 : pending.args;
-            // Strip null values recursively — LLMs send null for optional fields but Zod expects undefined
             const toolArgs = stripNulls(rawArgs) ?? {};
             try {
                 const toolResult = await matchingTool.execute(toolArgs);
@@ -424,11 +439,18 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
         tools: resumeTools,
         maxSteps: 1,
         toolChoice: (agent.toolChoice ?? 'auto'),
+        providerOptions: agent.providerOptions,
         outputSchema: meta?.outputSchema
             ? pikkuState(packageName, 'misc', 'schemas').get(meta.outputSchema)
             : undefined,
         agentId: run.agentName,
     };
+    // A resumed run keeps its original runId, so the handle registered for the
+    // first leg is long gone — an approval that kicks off more generation has to
+    // be interruptible on its own terms.
+    const interruptHandle = registerInterruptibleRun(run.runId);
+    runnerParams.abortSignal = interruptHandle.signal;
+    runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
     try {
         const accumulatedSteps = [];
         const totalUsage = { inputTokens: 0, outputTokens: 0 };
@@ -465,7 +487,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             });
             if (stepResult.toolCalls.length === 0)
                 break;
-            const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools, run.runId);
+            const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools);
             if (approvalsNeeded.length > 0) {
                 for (const approval of approvalsNeeded) {
                     const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
@@ -473,9 +495,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                         try {
                             approval.reason = await toolDef.approvalDescriptionFn(approval.args);
                         }
-                        catch {
-                            // ignore
-                        }
+                        catch { }
                     }
                 }
                 const pendingApprovals = approvalsNeeded.map((a) => a.agentRunId
@@ -574,6 +594,14 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
         };
     }
     catch (error) {
+        const interruption = interruptHandle.interruption;
+        if (interruption || isAbortError(error)) {
+            await aiRunState.updateRun(run.runId, { status: 'interrupted' });
+            if (storage) {
+                trackInterruptNote(run.threadId, persistOrphanedToolResults(interruptHandle, storage, run.threadId));
+            }
+            throw new AgentInterruptedError(run.runId, interruption ?? { reason: 'user' });
+        }
         for (const mw of aiMiddlewares) {
             if (mw.onError) {
                 try {
@@ -583,9 +611,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                         messages: runnerParams.messages,
                     });
                 }
-                catch {
-                    // ignore
-                }
+                catch { }
             }
         }
         await aiRunState.updateRun(run.runId, {
@@ -594,4 +620,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
         });
         throw error;
     }
+    finally {
+        interruptHandle.release();
+    }
 }

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;