@pikku/core 0.12.79 → 0.12.82

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

@@ -1,4 +1,6 @@
+import { finalizeAgentRun, lastUserMessageText, } from './ai-agent-finalize.js';
 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';
@@ -17,6 +19,9 @@ function createPersistingChannel(parent, storage, threadId, logger) {
         inputTokens: 0,
         outputTokens: 0,
     };
+    // Survives the per-step flush below, which clears its own buffers: the run
+    // record needs every call the run made, not just the last step's.
+    const runToolCalls = [];
     const flushStep = async (opts) => {
         if (!storage)
             return;
@@ -62,6 +67,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
             });
         });
     };
+    const runToolCallIndex = new Map();
     const channel = {
         channelId: parent.channelId,
         openingData: parent.openingData,
@@ -74,6 +80,9 @@ function createPersistingChannel(parent, storage, threadId, logger) {
         get totalUsage() {
             return totalUsage;
         },
+        get runToolCalls() {
+            return runToolCalls;
+        },
         flush: flushStep,
         close: () => parent.close(),
         sendBinary: (data) => parent.sendBinary(data),
@@ -83,6 +92,26 @@ function createPersistingChannel(parent, storage, threadId, logger) {
             // report the fragment it got through even with persistence turned off.
             if (event.type === 'text-delta')
                 fullText += event.text;
+            if (event.type === 'tool-call') {
+                runToolCallIndex.set(event.toolCallId, runToolCalls.length);
+                runToolCalls.push({
+                    name: event.toolName,
+                    args: event.args,
+                    result: '',
+                });
+            }
+            if (event.type === 'tool-result') {
+                const index = runToolCallIndex.get(event.toolCallId);
+                const result = typeof event.result === 'string'
+                    ? event.result
+                    : JSON.stringify(event.result);
+                const call = index === undefined ? undefined : runToolCalls[index];
+                if (call) {
+                    call.result = result;
+                    if (event.error)
+                        call.error = event.error;
+                }
+            }
             if (storage) {
                 switch (event.type) {
                     case 'text-delta':
@@ -102,6 +131,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
                             result: typeof event.result === 'string'
                                 ? event.result
                                 : JSON.stringify(event.result),
+                            ...(event.error ? { error: event.error } : {}),
                         });
                         break;
                     case 'generative-ui':
@@ -128,36 +158,49 @@ function createPersistingChannel(parent, storage, threadId, logger) {
     };
     return channel;
 }
-async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, messages, aiRunState, runId) {
-    const usage = persistingChannel.totalUsage;
-    let outputText = persistingChannel.fullText;
-    let outputMessages = messages;
-    for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
-        const mw = aiMiddlewares[i];
-        if (mw.modifyOutput) {
-            const result = await mw.modifyOutput(singletonServices, {
-                text: outputText,
-                messages: outputMessages,
-                usage: {
-                    inputTokens: usage.inputTokens,
-                    outputTokens: usage.outputTokens,
-                },
-            });
-            outputText = result.text;
-            outputMessages = result.messages;
-        }
-    }
-    await aiRunState.updateRun(runId, {
-        status: 'completed',
-        ...(usage.model
-            ? {
-                usage: {
-                    inputTokens: usage.inputTokens,
-                    outputTokens: usage.outputTokens,
-                    model: usage.model,
-                },
-            }
-            : {}),
+/**
+ * Agents already warned about, so a per-request hook does not become a
+ * per-request log line.
+ */
+const warnedUnstreamedOutputHooks = new Set();
+/**
+ * `modifyOutput` does not run on a streamed run at all. Nothing here could act
+ * on what it returns — the text has already reached the client, and
+ * `createPersistingChannel` flushes each step to storage as it goes, so by the
+ * time the run ends the transcript is already written.
+ *
+ * Rewriting on this path belongs to `modifyOutputStream`, which genuinely
+ * works: the stream middleware wraps the persisting channel, so what is stored
+ * and accumulated is already what the client was sent. A middleware that
+ * rewrites in `modifyOutput` only — a redaction hook, typically — is therefore
+ * silently ineffective when the agent is streamed, and is told so once.
+ */
+const warnUnstreamedOutputHooks = (agentName, aiMiddlewares, logger) => {
+    if (warnedUnstreamedOutputHooks.has(agentName))
+        return;
+    const unstreamed = aiMiddlewares.some((mw) => mw.modifyOutput && !mw.modifyOutputStream);
+    if (!unstreamed)
+        return;
+    warnedUnstreamedOutputHooks.add(agentName);
+    logger?.warn(`Agent '${agentName}' has AI middleware with modifyOutput but no modifyOutputStream — modifyOutput does not apply to streamed runs. Implement modifyOutputStream to affect a streamed reply.`);
+};
+async function postStreamCleanup(persistingChannel, aiRunState, runId, run) {
+    await finalizeAgentRun(aiRunState, {
+        runId,
+        agentName: run.agentName,
+        threadId: run.threadId,
+        resourceId: run.resourceId,
+        input: run.input,
+        // Already what the client received: the stream middleware wraps the
+        // persisting channel, so both were accumulated post-rewrite.
+        text: persistingChannel.fullText,
+        steps: [
+            {
+                usage: persistingChannel.totalUsage,
+                toolCalls: persistingChannel.runToolCalls,
+            },
+        ],
+        usage: persistingChannel.totalUsage,
     });
 }
 async function runStreamStepLoop(params) {
@@ -414,36 +457,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({
@@ -465,6 +490,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     if (storage) {
         await storage.saveMessages(threadId, [persistedUserMessage]);
     }
+    warnUnstreamedOutputHooks(agentName, aiMiddlewares, singletonServices.logger);
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
         .map((mw) => {
@@ -508,10 +534,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 &&
@@ -558,12 +581,13 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             await handleCredentialRequests(loopResult.credentialRequests, runId, channel, aiRunState, persistingChannel);
             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.
+        await postStreamCleanup(persistingChannel, aiRunState, runId, {
+            agentName,
+            threadId,
+            resourceId: input.resourceId,
+            input: lastUserMessageText(runnerParams.messages),
+        });
+        // 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 +674,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 +700,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;
@@ -789,18 +814,19 @@ export async function resumeAIAgent(input, channel, params, options) {
         }
         const toolArgs = typeof pending.args === 'string' ? JSON.parse(pending.args) : pending.args;
         let toolResult;
-        let isError = false;
+        let toolError;
         try {
             toolResult = await matchingTool.execute(toolArgs);
         }
         catch (execErr) {
             if (execErr?.payload?.error === 'missing_credential') {
                 toolResult = execErr.payload;
+                toolError = 'missing_credential';
             }
             else {
-                toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`;
+                toolError = execErr instanceof Error ? execErr.message : String(execErr);
+                toolResult = `Error: ${toolError}`;
             }
-            isError = true;
         }
         const resultStr = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
         if (storage) {
@@ -824,7 +850,7 @@ export async function resumeAIAgent(input, channel, params, options) {
             toolCallId: input.toolCallId,
             toolName: pending.toolName,
             result: toolResult,
-            ...(isError ? { isError: true } : {}),
+            ...(toolError ? { error: toolError } : {}),
         });
     }
     const updatedRun = await aiRunState.getRun(run.runId);
@@ -865,24 +891,10 @@ 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);
+    warnUnstreamedOutputHooks(run.agentName, aiMiddlewares, singletonServices.logger);
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
         .map((mw) => {
@@ -960,11 +972,11 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             await handleCredentialRequests(loopResult.credentialRequests, run.runId, channel, aiRunState, persistingChannel);
             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.
+        await postStreamCleanup(persistingChannel, aiRunState, run.runId, {
+            ...run,
+            input: lastUserMessageText(runnerParams.messages),
+        });
+        // 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,57 @@
+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: {
+        error?: string | undefined;
+        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 {};

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

@@ -0,0 +1,82 @@
+/**
+ * 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 const applyInputMiddleware = async (aiMiddlewares, singletonServices, input, sharedNotes) => {
+    let { messages, instructions } = input;
+    for (const mw of aiMiddlewares) {
+        if (!mw.modifyInput)
+            continue;
+        const result = await mw.modifyInput(singletonServices, {
+            messages,
+            instructions,
+            shared: sharedNotes,
+        });
+        messages = result.messages;
+        instructions = result.instructions;
+    }
+    return { messages, instructions };
+};
+/**
+ * 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 const notifyAfterStep = async (aiMiddlewares, singletonServices, stepNumber, stepResult) => {
+    for (const mw of aiMiddlewares) {
+        if (!mw.afterStep)
+            continue;
+        await mw.afterStep(singletonServices, {
+            stepNumber,
+            text: stepResult.text,
+            toolCalls: stepResult.toolCalls,
+            toolResults: stepResult.toolResults,
+            usage: stepResult.usage,
+            finishReason: stepResult.finishReason,
+        });
+    }
+};
+/**
+ * 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 const toAccumulatedStep = (stepResult) => ({
+    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 ?? ''),
+            ...(tr?.error ? { error: tr.error } : {}),
+        };
+    }),
+});
+/**
+ * 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 const describeApprovals = async (approvals, tools) => {
+    for (const approval of approvals) {
+        if (approval.reason)
+            continue;
+        const toolDef = tools.find((t) => t.name === approval.toolName);
+        if (!toolDef?.approvalDescriptionFn)
+            continue;
+        try {
+            approval.reason = await toolDef.approvalDescriptionFn(approval.args);
+        }
+        catch { }
+    }
+};

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

@@ -43,6 +43,13 @@ export interface AIToolResult {
     id: string;
     name: string;
     result: string;
+    /**
+     * Set when the tool threw rather than returned. Carried separately from
+     * `result`, which is a rendered string by the time it is persisted — a tool
+     * may legitimately return text beginning `Error:`, so the prefix cannot be
+     * read as a failure signal.
+     */
+    error?: string;
 }
 export interface AIMessage {
     id: string;
@@ -79,6 +86,8 @@ export interface AIAgentStep {
         name: string;
         args: Record<string, unknown>;
         result: string;
+        /** The failure message, when the tool threw rather than returned. */
+        error?: string;
     }[];
 }
 export interface AIAgentInputAttachment {
@@ -216,6 +225,21 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
          */
         signal?: AbortSignal;
     }) => Promise<AIStreamEvent | AIStreamEvent[] | null> | AIStreamEvent | AIStreamEvent[] | null;
+    /**
+     * The last chance to rewrite what the run produced, before it is persisted
+     * and returned.
+     *
+     * It does **not** run on a streamed run: there the text has already reached
+     * the client and each step is flushed to storage as it goes, so nothing could
+     * act on what this returned. Use {@link modifyOutputStream} to rewrite a
+     * streamed reply — a middleware that implements only this one is warned about
+     * when an agent it is attached to streams.
+     *
+     * `toolCalls` is here so a redaction pass covers the whole run record rather
+     * than just the visible answer: the tool arguments and results are persisted
+     * and handed to anything that grades the run, and scrubbing the reply alone
+     * leaves them untouched.
+     */
     modifyOutput?: (services: Services, ctx: {
         text: string;
         messages: AIMessage[];
@@ -223,12 +247,15 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
             inputTokens: number;
             outputTokens: number;
         };
+        toolCalls: NonNullable<AIAgentStep['toolCalls']>;
     }) => Promise<{
         text: string;
         messages: AIMessage[];
+        toolCalls?: NonNullable<AIAgentStep['toolCalls']>;
     }> | {
         text: string;
         messages: AIMessage[];
+        toolCalls?: NonNullable<AIAgentStep['toolCalls']>;
     };
     beforeToolCall?: (services: Services, ctx: {
         toolName: string;
@@ -262,6 +289,8 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
             toolCallId: string;
             toolName: string;
             result: unknown;
+            /** Set when the tool threw rather than returned. */
+            error?: string;
         }[];
         usage: {
             inputTokens: number;
@@ -282,7 +311,7 @@ export type AIAgentMemoryConfig = {
     lastMessages?: number;
     workingMemory?: unknown;
 };
-export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string> = {
+export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string, Scorer extends string = string> = {
     name: string;
     description: string;
     summary?: string;
@@ -308,6 +337,16 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     tools?: unknown[];
     agents?: unknown[];
     workflows?: unknown[];
+    /**
+     * Grades this agent's finished runs on live traffic, named by the generated
+     * `ScorerName` union rather than by `ref()` — a scorer is not a function, so
+     * there is nothing in the function map for a ref to resolve against.
+     *
+     * A reference-based judge listed here is never sampled: live traffic has no
+     * answer key. Scenarios name scorers directly and may grade with scorers an
+     * agent does not ship with.
+     */
+    scorers?: Scorer[];
     agentMode?: 'delegate' | 'supervise';
     memory?: AIAgentMemoryConfig;
     maxSteps?: number;
@@ -382,6 +421,12 @@ export type AIStreamEvent = {
     toolCallId: string;
     toolName: string;
     result: unknown;
+    /**
+     * The failure message, set when the tool threw rather than returned.
+     * Carried explicitly because a tool may legitimately return text that
+     * reads like an error, so `result` cannot be matched on to tell.
+     */
+    error?: string;
     agent?: string;
     session?: string;
 } | {
@@ -400,7 +445,7 @@ export type AIStreamEvent = {
     toolName: string;
     args: unknown;
     reason?: string;
-    runId?: string;
+    runId: string;
     agent?: string;
     session?: string;
 } | {

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

@@ -1,11 +1,12 @@
 export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './ai-agent-helpers.js';
-export { wrapChannelWithAGUI, type AGUIEvent } from './ai-agent-agui.js';
+export { wrapChannelWithAGUI } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
+export { resolveModelAlias } from './ai-agent-model-config.js';
 export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
-export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
+export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } 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';
+export { AgentInterruptedError, signalRunInterrupt, } from './ai-agent-interrupt.js';
+export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, } from './ai-agent-interrupt.js';
+export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './ai-agent-prepare.js';
+export { addAIAgent, } from './ai-agent-registry.js';
+export type { AIAgentInput, 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,9 +1,10 @@
 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 { resolveModelAlias } from './ai-agent-model-config.js';
 export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
-export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
+export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } 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';
+export { AgentInterruptedError, signalRunInterrupt, } from './ai-agent-interrupt.js';
+export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './ai-agent-prepare.js';
+export { addAIAgent, } from './ai-agent-registry.js';

package/dist/wirings/ai-agent/voice-input.js

@@ -135,12 +135,7 @@ export const voiceInput = (config) => pikkuAIMiddleware({
         // to send, and a message with no content is not a question.
         if (updatedContent.length === 0)
             throw new NoSpeechDetectedError();
-        // Only when something was actually heard. A turn can carry audio that all
-        // reads as non-speech and still have content — an image with a silent
-        // caption clip — which leaves nothing above to throw. Recording `''` here
-        // would send a transcript event saying the user said nothing, and a client
-        // that tells "not transcribed yet" from "transcribed" by the key being
-        // absent would render the turn as an empty bubble rather than a pending one.
+        // knowledge: decisions/internals/an-empty-transcript-is-not-recorded.md
         if (heard.length > 0) {
             shared[SPOKEN_TRANSCRIPT] = heard.join(' ');
         }