@pikku/core 0.12.80 → 0.12.83

package/dist/wirings/ai-agent/ai-agent-model-config.js

@@ -1,7 +1,50 @@
 // knowledge: decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md
+import { pikkuState } from '../../pikku-state.js';
+const isProviderQualified = (model) => model.includes('/');
+/** `PIKKU_MODEL_ALIASES=cheap:openai/gpt-5-mini,tool:anthropic/claude-sonnet-5` */
+const envAliases = () => {
+    const raw = process.env.PIKKU_MODEL_ALIASES;
+    if (!raw)
+        return {};
+    const aliases = {};
+    for (const entry of raw.split(',')) {
+        // First colon only — a model id may contain its own.
+        const separator = entry.indexOf(':');
+        if (separator === -1)
+            continue;
+        const alias = entry.slice(0, separator).trim();
+        const model = entry.slice(separator + 1).trim();
+        if (alias && model)
+            aliases[alias] = model;
+    }
+    return aliases;
+};
+/**
+ * Resolves a model name to a concrete `provider/model`. Aliases come from the
+ * `models` table in pikku.config.json; a name containing `/` is already
+ * concrete. Read from the main package, not the calling addon's — which model
+ * a tier points at is the hosting app's decision.
+ */
+export const resolveModelAlias = (model) => {
+    if (isProviderQualified(model))
+        return model;
+    const generated = pikkuState(null, 'agent', 'modelAliases');
+    const override = envAliases()[model];
+    const resolved = override ?? generated[model];
+    if (!resolved) {
+        const known = Object.keys({ ...generated, ...envAliases() }).sort();
+        throw new Error(`Unknown model alias '${model}'. ` +
+            (known.length
+                ? `Known aliases: ${known.join(', ')}. `
+                : `No aliases are configured. `) +
+            `Add it to the "models" table in pikku.config.json, or name a ` +
+            `provider-qualified model such as 'openai/gpt-5-mini'.`);
+    }
+    return resolved;
+};
 export function resolveModelConfig(_agentName, agent) {
     return {
-        model: agent.model,
+        model: resolveModelAlias(agent.model),
         temperature: agent.temperature,
         maxSteps: agent.maxSteps,
     };

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

@@ -357,6 +357,10 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     secretOverrides: capturedAddonConfig?.secretOverrides,
                                     variableOverrides: capturedAddonConfig?.variableOverrides,
                                     credentialOverrides: capturedAddonConfig?.credentialOverrides,
+                                    secretGrants: capturedAddonConfig?.secretGrants,
+                                    credentialGrants: capturedAddonConfig?.credentialGrants,
+                                    globalSecrets: capturedAddonConfig?.globalSecrets,
+                                    globalCredentials: capturedAddonConfig?.globalCredentials,
                                 }
                                 : undefined;
                             services = await getOrCreatePackageSingletonServices(capturedPkg, singletonServices, addonInstance);

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

@@ -4,6 +4,7 @@ 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 { applyOutputMiddleware, finalizeAgentRun, lastUserMessageText, } from './ai-agent-finalize.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
@@ -192,27 +193,25 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             text: finalText,
             steps: accumulatedSteps,
         };
-        let outputText = finalText;
-        let outputMessages = runnerParams.messages;
-        for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
-            const mw = aiMiddlewares[i];
-            if (mw.modifyOutput) {
-                const modResult = await mw.modifyOutput(singletonServices, {
-                    text: outputText,
-                    messages: outputMessages,
-                    usage: totalUsage,
-                });
-                outputText = modResult.text;
-                outputMessages = modResult.messages;
-            }
-        }
+        const { text: outputText, steps: outputSteps } = await applyOutputMiddleware(aiMiddlewares, singletonServices, {
+            text: finalText,
+            messages: runnerParams.messages,
+            steps: result.steps,
+            usage: totalUsage,
+        });
         await saveMessages(storage, threadId, input.resourceId, memoryConfig, persistedUserMessage, {
-            ...result,
             text: outputText,
+            steps: outputSteps,
             uiSpec: structuredOutput.uiSpec,
         });
-        await aiRunState.updateRun(runId, {
-            status: 'completed',
+        await finalizeAgentRun(aiRunState, {
+            runId,
+            agentName,
+            threadId,
+            resourceId: input.resourceId,
+            input: lastUserMessageText(runnerParams.messages),
+            text: outputText,
+            steps: outputSteps,
             usage: { ...totalUsage, model: agent.model },
         });
         return {
@@ -220,7 +219,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             text: outputText,
             object: finalObject,
             threadId,
-            steps: accumulatedSteps,
+            steps: outputSteps,
             usage: totalUsage,
         };
     }
@@ -305,6 +304,7 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         if (!claimedIds.has(toolCallId))
             continue;
         let resultStr;
+        let toolError;
         if (rejectedIds.has(toolCallId)) {
             resultStr =
                 'The user explicitly declined this action. Inform them that it was declined and do not retry.';
@@ -330,7 +330,8 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
                     resultStr = JSON.stringify(err.payload);
                 }
                 else {
-                    resultStr = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                    toolError = err instanceof Error ? err.message : String(err);
+                    resultStr = `Error: ${toolError}`;
                 }
             }
         }
@@ -344,6 +345,7 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
                 ? JSON.parse(pending.args)
                 : pending.args,
             result: resultStr,
+            ...(toolError ? { error: toolError } : {}),
         });
     }
     if (storage && toolCallMessages.length > 0) {
@@ -361,9 +363,23 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         ]);
     }
     await aiRunState.updateRun(runId, { status: 'running' });
-    return continueAfterToolResultSync(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, params, aiRunState);
+    return continueAfterToolResultSync(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, params, aiRunState, 
+    // The approved tools were executed here, before the model was re-entered,
+    // so they belong to the run's step record — otherwise a tool that failed
+    // after approval leaves no trace on the run at all.
+    toolCallMessages.length > 0
+        ? {
+            usage: { inputTokens: 0, outputTokens: 0 },
+            toolCalls: toolCallMessages.map((tc) => ({
+                name: tc.toolName,
+                args: (tc.args ?? {}),
+                result: tc.result,
+                ...(tc.error ? { error: tc.error } : {}),
+            })),
+        }
+        : undefined);
 }
-async function continueAfterToolResultSync(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, params, aiRunState) {
+async function continueAfterToolResultSync(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, params, aiRunState, resumedToolStep) {
     const singletonServices = getSingletonServices();
     const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
     const meta = agentsMeta[resolvedName];
@@ -416,6 +432,11 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
     runnerParams.abortSignal = interruptHandle.signal;
     runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
     try {
+        // Kept out of `accumulatedSteps` deliberately: that array drives
+        // `saveMessages`, and the approved tool's messages were already written to
+        // the thread before the model was re-entered. It belongs to the run's step
+        // record, not to persistence.
+        const withResumedStep = (steps) => resumedToolStep ? [resumedToolStep, ...steps] : steps;
         const accumulatedSteps = [];
         const totalUsage = { inputTokens: 0, outputTokens: 0 };
         let lastStepResult = null;
@@ -475,7 +496,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                     runId: run.runId,
                     text: suspendedText,
                     threadId: run.threadId,
-                    steps: accumulatedSteps,
+                    steps: withResumedStep(accumulatedSteps),
                     usage: totalUsage,
                     status: 'suspended',
                     pendingApprovals: approvalsNeeded.map((a) => ({
@@ -495,26 +516,26 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             text: finalText,
             steps: accumulatedSteps,
         };
-        let outputText = finalText;
-        let outputMessages = runnerParams.messages;
-        for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
-            const mw = aiMiddlewares[i];
-            if (mw.modifyOutput) {
-                const modResult = await mw.modifyOutput(singletonServices, {
-                    text: outputText,
-                    messages: outputMessages,
-                    usage: totalUsage,
-                });
-                outputText = modResult.text;
-                outputMessages = modResult.messages;
-            }
-        }
+        const { text: outputText, steps: outputSteps } = await applyOutputMiddleware(aiMiddlewares, singletonServices, {
+            text: finalText,
+            messages: runnerParams.messages,
+            steps: withResumedStep(result.steps),
+            usage: totalUsage,
+        });
         await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, {
-            ...result,
             text: outputText,
+            // The approved tool's messages were written before the model was
+            // re-entered, so only the steps this leg generated are persisted here.
+            steps: accumulatedSteps,
         });
-        await aiRunState.updateRun(run.runId, {
-            status: 'completed',
+        await finalizeAgentRun(aiRunState, {
+            runId: run.runId,
+            agentName: resolvedName,
+            threadId: run.threadId,
+            resourceId: run.resourceId,
+            input: lastUserMessageText(runnerParams.messages),
+            text: outputText,
+            steps: outputSteps,
             usage: { ...totalUsage, model: agent.model },
         });
         return {
@@ -522,7 +543,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             text: outputText,
             object: finalObject,
             threadId: run.threadId,
-            steps: accumulatedSteps,
+            steps: outputSteps,
             usage: totalUsage,
         };
     }

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

@@ -1,3 +1,4 @@
+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';
@@ -18,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;
@@ -63,6 +67,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
             });
         });
     };
+    const runToolCallIndex = new Map();
     const channel = {
         channelId: parent.channelId,
         openingData: parent.openingData,
@@ -75,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),
@@ -84,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':
@@ -103,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':
@@ -129,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) {
@@ -448,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) => {
@@ -538,7 +581,12 @@ 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);
+        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();
@@ -766,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) {
@@ -801,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);
@@ -845,6 +894,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     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) => {
@@ -922,7 +972,10 @@ 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);
+        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

@@ -30,6 +30,7 @@ export declare const toAccumulatedStep: (stepResult: StepResult) => {
         outputTokens: number;
     };
     toolCalls: {
+        error?: string | undefined;
         name: string;
         args: Record<string, unknown>;
         result: string;

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

@@ -55,6 +55,7 @@ export const toAccumulatedStep = (stepResult) => ({
             result: typeof tr?.result === 'string'
                 ? tr.result
                 : JSON.stringify(tr?.result ?? ''),
+            ...(tr?.error ? { error: tr.error } : {}),
         };
     }),
 });

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;
 } | {

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-scorer/ai-scorer-grade.d.ts

@@ -0,0 +1,26 @@
+import type { ScoreJob, ScorerOutput } from './ai-scorer.types.js';
+/**
+ * Grade one run with one scorer.
+ *
+ * The single path both callers take — the lane worker on live traffic and the
+ * scenario grading RPC — so a scenario's grade is the same computation the
+ * production sampler would have made, not an approximation of it.
+ *
+ * Persisting is optional because the two callers differ on it: a live grade is
+ * only useful once recorded, while a scenario asserts on the returned value and
+ * runs against servers that may have no run-state adapter at all.
+ */
+export declare const gradeRun: (job: ScoreJob, services: {
+    aiAgentRunner?: unknown;
+    aiRunState?: {
+        saveScore: (score: {
+            runId: string;
+            scorerName: string;
+            score: number;
+            reason?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<void>;
+    };
+}, options: {
+    persist: boolean;
+}) => Promise<ScorerOutput>;