@pikku/core 0.12.79 → 0.12.80

package/dist/types/core.types.d.ts

@@ -233,6 +233,11 @@ export interface CoreUserSession {
      * Populated by whoever builds the session — core reads them, never fetches.
      */
     scopes?: string[];
+    /**
+     * Restricts the session to functions declared `readonly`. The function runner
+     * throws `ReadonlySessionError` for anything else.
+     */
+    readonly?: boolean;
 }
 /**
  * Kept structural so core stays independent of any one auth package —
@@ -299,12 +304,17 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      */
     auth?: () => Promise<AuthInstance>;
 }
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
 } & Partial<{
     wireType: PikkuWiringTypes;
     wireId: string;
+    /**
+     * A logger scoped to this invocation, when a host attaches one. Core never
+     * sets it; services that log fall back to the singleton logger.
+     */
+    logger: Logger;
     /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
     traceId: string;
     functionId: string;

package/dist/types/state.types.d.ts

@@ -63,7 +63,7 @@ export interface PikkuPackageState {
         meta: HTTPWiringsMeta;
     };
     channel: {
-        channels: Map<string, CoreChannel<any, any>>;
+        channels: Map<string, CoreChannel<any, any, any, any, any>>;
         meta: ChannelsMeta;
     };
     scheduler: {

package/dist/wirings/actor-flow/run-conversation.js

@@ -70,12 +70,7 @@ function actorInstructions(persona, task) {
             : '',
         `Your goal in this conversation: ${task}.`,
         `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
-        // Every call the actor makes wants a schema'd object back, and a gateway
-        // that cannot take a JSON *schema* degrades to OpenAI's `json_object`
-        // mode — which refuses the request outright unless the word "json" appears
-        // somewhere in the prompt. Saying it once here covers all three call sites
-        // (turn, approvals, verdict), since each builds on these instructions, and
-        // it costs nothing on providers that never needed telling.
+        // knowledge: decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md
         `Reply with json matching the schema you are given, and nothing else.`,
     ]
         .filter(Boolean)

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

@@ -0,0 +1,15 @@
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { SessionService } from '../../services/user-session-service.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { PikkuRPC } from '../rpc/rpc-types.js';
+export type AgentRPCOptions = {
+    sessionService?: SessionService<CoreUserSession>;
+};
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export declare const createAgentRPC: (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC["agent"];

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

@@ -0,0 +1,53 @@
+import { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
+import { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+import { wrapChannelWithAGUI } from './ai-agent-agui.js';
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export const createAgentRPC = (wire, options) => {
+    const params = () => ({
+        sessionService: options.sessionService,
+        getCredential: wire.getCredential?.bind(wire),
+    });
+    const streamingChannel = () => {
+        const channel = wire.channel;
+        if (!channel)
+            throw new Error('No channel available for streaming');
+        return channel;
+    };
+    /** `run` and `approve` return the same shape; only the call differs. */
+    const asRunResult = (result) => ({
+        runId: result.runId,
+        result: result.object ?? result.text,
+        usage: result.usage,
+        ...(result.status === 'suspended' && {
+            status: 'suspended',
+            pendingApprovals: result.pendingApprovals,
+        }),
+    });
+    return {
+        run: async (agentName, input) => asRunResult(await runAIAgent(agentName, input, params())),
+        stream: async (agentName, input, streamOptions) => {
+            let currentRunId;
+            await streamAIAgent(agentName, input, wrapChannelWithAGUI(streamingChannel(), {
+                threadId: input.threadId,
+                getRunId: () => currentRunId,
+            }), params(), undefined, {
+                ...streamOptions,
+                onRunCreated: (runId) => {
+                    currentRunId = runId;
+                    streamOptions?.onRunCreated?.(runId);
+                },
+            });
+        },
+        resume: async (runId, input, streamOptions) => {
+            await resumeAIAgent({ runId, ...input }, wrapChannelWithAGUI(streamingChannel(), { runId }), params(), streamOptions);
+        },
+        interrupt: async (runId, reason) => interruptAIAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: options.sessionService }),
+        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAIAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
+    };
+};

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

@@ -296,11 +296,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     });
                     break;
                 }
-                // AG-UI has no event for speech, so it travels as CUSTOM like the other
-                // pikku-specific ones. Dropping it instead — which is what this did —
-                // means a voice agent reached over HTTP is inaudible: `voiceOutput`
-                // synthesizes every sentence, the provider bills for it, and nothing
-                // gets past the mapper.
+                // knowledge: decisions/internals/agent-speech-travels-as-a-custom-agui-event.md
                 case 'audio-delta': {
                     send({
                         type: 'CUSTOM',

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

@@ -2,7 +2,9 @@ import { randomUUID } from 'crypto';
 export function resolveMemoryServices(agent, singletonServices) {
     const memoryConfig = agent.memory;
     const storage = memoryConfig?.storage
-        ? singletonServices[memoryConfig.storage]
+        ? // The service is named by string in agent config, so the lookup cannot be
+            // checked — only the shape it is required to have.
+            singletonServices[memoryConfig.storage]
         : singletonServices.aiStorage;
     return { storage };
 }

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

@@ -1,5 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions, runPermissions } from '../../permissions.js';
+import { checkAuthPermissions, runPermissions, } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { ForbiddenError } from '../../errors/errors.js';
 import { verifyScopes } from '../../scopes.js';
@@ -648,10 +648,7 @@ 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.
+        // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
         await awaitPendingInterruptNote(threadId);
         messages = await storage.getMessages(threadId, {
             lastN: memoryConfig?.lastMessages ?? 20,
@@ -660,10 +657,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
     const userContent = input.attachments?.length
         ? [
-            // Omitted when there is nothing to say. An attachment on its own is a
-            // real turn — a spoken one carries audio and no text at all — and an
-            // empty text part alongside it is a part providers are entitled to
-            // reject, for a caller who never wrote one.
+            // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
             ...(input.message
                 ? [{ type: 'text', text: input.message }]
                 : []),

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

@@ -3,6 +3,7 @@ import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolv
 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 { applyInputMiddleware, describeApprovals, notifyAfterStep, toAccumulatedStep, } from './ai-agent-turn.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
@@ -75,25 +76,13 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
     ];
     // 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) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, {
+        messages: runnerParams.messages,
+        instructions: runnerParams.instructions,
+    }, sharedNotes);
     runnerParams.messages = modifiedMessages;
     runnerParams.instructions = modifiedInstructions;
-    // History records what the model was asked, which for a spoken turn is the
-    // transcript rather than the base64 audio that arrived — see the same note on
-    // the streaming path. Identity-checked, because a middleware may legitimately
-    // replace the message list with something unrelated to this turn.
+    // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
     const lastModified = modifiedMessages[modifiedMessages.length - 1];
     const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
@@ -105,10 +94,7 @@ 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.
+    // knowledge: decisions/internals/a-non-streaming-agent-run-registers-with-airunstate-too.md
     const interruptHandle = registerInterruptibleRun(runId);
     runnerParams.abortSignal = interruptHandle.signal;
     runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
@@ -136,44 +122,13 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             lastStepResult = stepResult;
             totalUsage.inputTokens += stepResult.usage.inputTokens;
             totalUsage.outputTokens += stepResult.usage.outputTokens;
-            for (const mw of aiMiddlewares) {
-                if (mw.afterStep) {
-                    await mw.afterStep(singletonServices, {
-                        stepNumber: step,
-                        text: stepResult.text,
-                        toolCalls: stepResult.toolCalls,
-                        toolResults: stepResult.toolResults,
-                        usage: stepResult.usage,
-                        finishReason: stepResult.finishReason,
-                    });
-                }
-            }
-            accumulatedSteps.push({
-                usage: stepResult.usage,
-                toolCalls: stepResult.toolCalls.map((tc) => {
-                    const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
-                    return {
-                        name: tc.toolName,
-                        args: tc.args,
-                        result: typeof tr?.result === 'string'
-                            ? tr.result
-                            : JSON.stringify(tr?.result ?? ''),
-                    };
-                }),
-            });
+            await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult);
+            accumulatedSteps.push(toAccumulatedStep(stepResult));
             if (stepResult.toolCalls.length === 0)
                 break;
             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);
-                    if (toolDef?.approvalDescriptionFn && !approval.reason) {
-                        try {
-                            approval.reason = await toolDef.approvalDescriptionFn(approval.args);
-                        }
-                        catch { }
-                    }
-                }
+                await describeApprovals(approvalsNeeded, runnerParams.tools);
                 const pendingApprovals = approvalsNeeded.map((a) => a.agentRunId
                     ? {
                         type: 'agent-call',
@@ -270,10 +225,7 @@ 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.
+        // knowledge: decisions/internals/an-agent-interrupt-is-not-a-failure.md
         const interruption = interruptHandle.interruption;
         if (interruption || isAbortError(error)) {
             await aiRunState.updateRun(runId, { status: 'interrupted' });
@@ -331,8 +283,18 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
     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 savedPendingApprovals = [...(run.pendingApprovals ?? [])];
+    // The read above is not a claim — concurrent resumes all see the same pending
+    // list. `resolveApproval` is the claim, and only the caller it returns true
+    // for may run the tool.
+    const claimedIds = new Set();
     for (const { toolCallId, approved } of approvals) {
-        await aiRunState.resolveApproval(toolCallId, approved ? 'approved' : 'denied');
+        const claimed = await aiRunState.resolveApproval(toolCallId, approved ? 'approved' : 'denied');
+        if (claimed) {
+            claimedIds.add(toolCallId);
+        }
+    }
+    if (approvals.length > 0 && claimedIds.size === 0) {
+        throw new Error(`Approvals for run ${runId} were already resolved by another caller`);
     }
     const { tools } = await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, undefined, agent.aiMiddleware ?? []);
     const toolCallMessages = [];
@@ -340,6 +302,8 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         if (pending.type !== 'tool-call')
             continue;
         const toolCallId = pending.toolCallId;
+        if (!claimedIds.has(toolCallId))
+            continue;
         let resultStr;
         if (rejectedIds.has(toolCallId)) {
             resultStr =
@@ -427,19 +391,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
     ];
     // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
     const sharedNotes = {};
-    let modifiedMessages = trimmedMessages;
-    let modifiedInstructions = instructions;
-    for (const mw of aiMiddlewares) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, { messages: trimmedMessages, instructions: instructions }, sharedNotes);
     const { tools: resumeTools } = await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, undefined, aiMiddlewares);
     const resolved = resolveModelConfig(resolvedName, agent);
     const maxSteps = resolved.maxSteps ?? 10;
@@ -472,44 +424,13 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             lastStepResult = stepResult;
             totalUsage.inputTokens += stepResult.usage.inputTokens;
             totalUsage.outputTokens += stepResult.usage.outputTokens;
-            for (const mw of aiMiddlewares) {
-                if (mw.afterStep) {
-                    await mw.afterStep(singletonServices, {
-                        stepNumber: step,
-                        text: stepResult.text,
-                        toolCalls: stepResult.toolCalls,
-                        toolResults: stepResult.toolResults,
-                        usage: stepResult.usage,
-                        finishReason: stepResult.finishReason,
-                    });
-                }
-            }
-            accumulatedSteps.push({
-                usage: stepResult.usage,
-                toolCalls: stepResult.toolCalls.map((tc) => {
-                    const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
-                    return {
-                        name: tc.toolName,
-                        args: tc.args,
-                        result: typeof tr?.result === 'string'
-                            ? tr.result
-                            : JSON.stringify(tr?.result ?? ''),
-                    };
-                }),
-            });
+            await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult);
+            accumulatedSteps.push(toAccumulatedStep(stepResult));
             if (stepResult.toolCalls.length === 0)
                 break;
             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);
-                    if (toolDef?.approvalDescriptionFn && !approval.reason) {
-                        try {
-                            approval.reason = await toolDef.approvalDescriptionFn(approval.args);
-                        }
-                        catch { }
-                    }
-                }
+                await describeApprovals(approvalsNeeded, runnerParams.tools);
                 const pendingApprovals = approvalsNeeded.map((a) => a.agentRunId
                     ? {
                         type: 'agent-call',

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

@@ -1,4 +1,5 @@
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
+import { applyInputMiddleware } from './ai-agent-turn.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
 import { SPOKEN_TRANSCRIPT } from './voice-input.js';
@@ -414,36 +415,18 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     ];
     // 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) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, {
+        messages: runnerParams.messages,
+        instructions: runnerParams.instructions,
+    }, sharedNotes);
     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.
+    // knowledge: decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md
     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.
+    // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
     const lastModified = modifiedMessages[modifiedMessages.length - 1];
     const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
@@ -508,10 +491,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         : persistingChannel;
     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.
+        // knowledge: decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md
         send: (event) => {
             if (event.type === 'tool-result' &&
                 event.result !== null &&
@@ -559,11 +539,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             return persistingChannel.fullText;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, runId);
-        // 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.
+        // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
         await outputChannel.send({ type: 'done' });
         channel.close();
         return persistingChannel.fullText;
@@ -650,12 +626,7 @@ export async function interruptAIAgent(input, params) {
     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).
+    // knowledge: decisions/internals/an-agent-run-owned-by-another-instance-says-so.md
     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.');
@@ -681,7 +652,13 @@ export async function resumeAIAgent(input, channel, params, options) {
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
     await assertAgentAuthorized(agent, params, packageName);
-    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
+    // The read above is not a claim — concurrent resumes all see the same pending
+    // approval. `resolveApproval` is the claim, and the loser must not go on to
+    // run the tool a second time.
+    const claimed = await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
+    if (!claimed) {
+        throw new Error(`Approval for toolCallId ${input.toolCallId} was already resolved by another caller`);
+    }
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
@@ -865,23 +842,8 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     ];
     // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
     const sharedNotes = {};
-    let modifiedMessages = trimmedMessages;
-    let modifiedInstructions = instructions;
-    for (const mw of aiMiddlewares) {
-        if (mw.modifyInput) {
-            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 { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, { messages: trimmedMessages, instructions: instructions }, sharedNotes);
+    // knowledge: decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md
     const interruptHandle = registerInterruptibleRun(run.runId);
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
@@ -961,10 +923,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             return;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, run.runId);
-        // 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.
+        // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
         await wrappedChannel.send({ type: 'done' });
         channel.close();
     }

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

@@ -0,0 +1,56 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { PikkuAIMiddlewareHooks } from './ai-agent.types.js';
+/** Exactly what `modifyInput` accepts and returns, taken from the hook itself. */
+type TurnInput = Pick<Parameters<NonNullable<PikkuAIMiddlewareHooks['modifyInput']>>[1], 'messages' | 'instructions'>;
+/**
+ * Run every `modifyInput` hook in order, threading each result into the next.
+ *
+ * Shared by the four places a turn starts — first turn and resume, on both the
+ * streaming and non-streaming paths. `sharedNotes` is one bag per run that the
+ * caller keeps, because hooks use it to pass things forward (`voiceInput`
+ * leaves the transcript there for `voiceOutput`).
+ */
+export declare const applyInputMiddleware: (aiMiddlewares: PikkuAIMiddlewareHooks[], singletonServices: CoreSingletonServices, input: TurnInput, sharedNotes: Record<string, unknown>) => Promise<TurnInput>;
+/** The step fields both agent paths hand to `afterStep`, taken from the hook. */
+type StepResult = Omit<Parameters<NonNullable<PikkuAIMiddlewareHooks['afterStep']>>[1], 'stepNumber'>;
+/**
+ * Notify every `afterStep` hook. The payload is the step verbatim plus its
+ * ordinal — a hook that wants the run's totals accumulates them itself.
+ */
+export declare const notifyAfterStep: (aiMiddlewares: PikkuAIMiddlewareHooks[], singletonServices: CoreSingletonServices, stepNumber: number, stepResult: StepResult) => Promise<void>;
+/**
+ * The step shape kept on the run: each tool call paired with its result.
+ *
+ * A result is stringified unless it already is a string, because this is what
+ * gets persisted and read back as history — an object there is unreadable.
+ */
+export declare const toAccumulatedStep: (stepResult: StepResult) => {
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    toolCalls: {
+        name: string;
+        args: Record<string, unknown>;
+        result: string;
+    }[];
+};
+type PendingApproval = {
+    toolName: string;
+    args: unknown;
+    reason?: string;
+};
+type ToolDef = {
+    name: string;
+    approvalDescriptionFn?: (args: any) => Promise<string> | string;
+};
+/**
+ * Fill in each approval's human-readable reason from the tool's own
+ * `approvalDescriptionFn`, where it did not supply one.
+ *
+ * A description that throws is swallowed: the approval still has to be raised,
+ * and a gate that disappears because its label failed to render is the worst
+ * available outcome.
+ */
+export declare const describeApprovals: (approvals: PendingApproval[], tools: ToolDef[]) => Promise<void>;
+export {};