@pikku/core 0.12.80 → 0.12.82

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

package/dist/wirings/ai-scorer/ai-scorer-grade.js

@@ -0,0 +1,33 @@
+import { runJudge } from './ai-scorer-judge.js';
+import { resolveAIScorer } from './ai-scorer-registry.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 const gradeRun = async (job, services, options) => {
+    const { scorerName, ...input } = job;
+    const scorer = resolveAIScorer(scorerName);
+    const result = scorer.score
+        ? await scorer.score(input, services)
+        : await runJudge(scorer, input, services.aiAgentRunner);
+    if (options.persist) {
+        if (!services.aiRunState) {
+            throw new Error(`AI run state service not initialized: cannot record the '${scorerName}' grade of run ${job.runId}`);
+        }
+        await services.aiRunState.saveScore({
+            runId: job.runId,
+            scorerName,
+            score: result.score,
+            ...(result.reason !== undefined ? { reason: result.reason } : {}),
+            ...(result.metadata !== undefined ? { metadata: result.metadata } : {}),
+        });
+    }
+    return result;
+};

package/dist/wirings/ai-scorer/ai-scorer-judge.d.ts

@@ -0,0 +1,17 @@
+import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js';
+import type { PikkuAIScorer, ScorerInput, ScorerJudgeConfig, ScorerOutput } from './ai-scorer.types.js';
+/**
+ * The message a judge grades when its scorer supplies no `prompt`.
+ *
+ * A reference-based judge is shown the answer key; a reference-free one is not,
+ * and grades the answer on its own merits.
+ */
+export declare const buildJudgePrompt: (judge: ScorerJudgeConfig, input: ScorerInput) => string;
+/**
+ * Run an LLM judge and force the `{ score, reason }` contract, so a scorer
+ * author writes a rubric rather than a parser.
+ *
+ * A judge has no tools, which is the one case where an output schema is
+ * reliably honoured.
+ */
+export declare const runJudge: (scorer: PikkuAIScorer<any>, input: ScorerInput, aiAgentRunner: AIAgentRunnerService | undefined) => Promise<ScorerOutput>;