@pikku/core 0.12.83 → 0.12.86

package/dist/wirings/{ai-agent/ai-agent.types.d.ts → agent/agent.types.d.ts}

@@ -1,10 +1,11 @@
 import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
-import type { AIProviderOptions } from '../../services/ai-agent-runner-service.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
+import type { PermissionMetadata } from '../../function/function-meta.types.js';
+import type { AIProviderOptions } from '../../services/agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
 import type { ApprovalPolicy } from '../channel/channel-rpc.js';
-export interface AIThread {
+export interface AgentThread {
     id: string;
     resourceId: string;
     title?: string;
@@ -12,7 +13,7 @@ export interface AIThread {
     createdAt: Date;
     updatedAt: Date;
 }
-export type AIContentPart = {
+export type AgentContentPart = {
     type: 'text';
     text: string;
 } | {
@@ -34,12 +35,12 @@ export type AIContentPart = {
     type: 'generative-ui';
     spec: unknown;
 };
-export interface AIToolCall {
+export interface AgentToolCall {
     id: string;
     name: string;
     args: Record<string, unknown>;
 }
-export interface AIToolResult {
+export interface AgentToolResult {
     id: string;
     name: string;
     result: string;
@@ -51,12 +52,12 @@ export interface AIToolResult {
      */
     error?: string;
 }
-export interface AIMessage {
+export interface AgentMessage {
     id: string;
     role: 'system' | 'user' | 'assistant' | 'tool';
-    content?: string | AIContentPart[];
-    toolCalls?: AIToolCall[];
-    toolResults?: AIToolResult[];
+    content?: string | AgentContentPart[];
+    toolCalls?: AgentToolCall[];
+    toolResults?: AgentToolResult[];
     reasoningContent?: string;
     /**
      * Set on an assistant message whose generation was cut short by
@@ -77,7 +78,7 @@ export interface AIMessage {
     undelivered?: boolean;
     createdAt: Date;
 }
-export interface AIAgentStep {
+export interface AgentStep {
     usage: {
         inputTokens: number;
         outputTokens: number;
@@ -90,18 +91,18 @@ export interface AIAgentStep {
         error?: string;
     }[];
 }
-export interface AIAgentInputAttachment {
+export interface AgentInputAttachment {
     type: 'image' | 'file';
     data?: string;
     url?: string;
     mediaType?: string;
     filename?: string;
 }
-export interface AIAgentInput {
+export interface AgentInput {
     message: string;
     threadId: string;
     resourceId: string;
-    attachments?: AIAgentInputAttachment[];
+    attachments?: AgentInputAttachment[];
     model?: string;
     temperature?: number;
     /** Structured context injected into the system instructions for this request.
@@ -109,12 +110,12 @@ export interface AIAgentInput {
      *  so the agent can call tools without asking the user for identifiers. */
     context?: string;
 }
-export interface AIAgentOutput {
+export interface AgentOutput {
     runId: string;
     text: string;
     object?: unknown;
     threadId: string;
-    steps: AIAgentStep[];
+    steps: AgentStep[];
     usage: {
         inputTokens: number;
         outputTokens: number;
@@ -147,7 +148,7 @@ export type SessionScope = 'user' | 'org';
  * written by whoever runs the server it executes on. A capability runs on
  * someone else's machine, so it requires the field instead.
  */
-export interface AIAgentToolDef extends Partial<ApprovalPolicy> {
+export interface AgentToolDef extends Partial<ApprovalPolicy> {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
@@ -168,9 +169,9 @@ export interface AIAgentToolDef extends Partial<ApprovalPolicy> {
      */
     forwardsApproval?: boolean;
 }
-export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
+export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
     modifyInput?: (services: Services, ctx: {
-        messages: AIMessage[];
+        messages: AgentMessage[];
         instructions: string;
         /**
          * Notes about this run that every middleware can read and write, as
@@ -190,15 +191,15 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
          */
         shared: Record<string, unknown>;
     }) => Promise<{
-        messages: AIMessage[];
+        messages: AgentMessage[];
         instructions: string;
     }> | {
-        messages: AIMessage[];
+        messages: AgentMessage[];
         instructions: string;
     };
     modifyOutputStream?: (services: Services, ctx: {
-        event: AIStreamEvent;
-        allEvents: readonly AIStreamEvent[];
+        event: AgentStreamEvent;
+        allEvents: readonly AgentStreamEvent[];
         /** Private to this middleware, for this run. Cross-middleware facts go in `shared`. */
         state: State;
         /** Per-run notes shared with every middleware — see {@link modifyInput}. */
@@ -217,14 +218,14 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
          * it matters — and a hook that emits must make sure anything still
          * outstanding has landed before it lets `done` through.
          */
-        emit: (event: AIStreamEvent) => Promise<void>;
+        emit: (event: AgentStreamEvent) => Promise<void>;
         /**
          * Aborts when the run is interrupted. Pass it to any provider call the
          * hook makes: work started for a reply the user has already talked over
          * is billed but never heard.
          */
         signal?: AbortSignal;
-    }) => Promise<AIStreamEvent | AIStreamEvent[] | null> | AIStreamEvent | AIStreamEvent[] | null;
+    }) => Promise<AgentStreamEvent | AgentStreamEvent[] | null> | AgentStreamEvent | AgentStreamEvent[] | null;
     /**
      * The last chance to rewrite what the run produced, before it is persisted
      * and returned.
@@ -242,20 +243,20 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
      */
     modifyOutput?: (services: Services, ctx: {
         text: string;
-        messages: AIMessage[];
+        messages: AgentMessage[];
         usage: {
             inputTokens: number;
             outputTokens: number;
         };
-        toolCalls: NonNullable<AIAgentStep['toolCalls']>;
+        toolCalls: NonNullable<AgentStep['toolCalls']>;
     }) => Promise<{
         text: string;
-        messages: AIMessage[];
-        toolCalls?: NonNullable<AIAgentStep['toolCalls']>;
+        messages: AgentMessage[];
+        toolCalls?: NonNullable<AgentStep['toolCalls']>;
     }> | {
         text: string;
-        messages: AIMessage[];
-        toolCalls?: NonNullable<AIAgentStep['toolCalls']>;
+        messages: AgentMessage[];
+        toolCalls?: NonNullable<AgentStep['toolCalls']>;
     };
     beforeToolCall?: (services: Services, ctx: {
         toolName: string;
@@ -301,17 +302,17 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
     onError?: (services: Services, ctx: {
         error: Error;
         stepNumber: number;
-        messages: AIMessage[];
+        messages: AgentMessage[];
     }) => Promise<void> | void;
 }
-export type AIAgentMemoryConfig = {
+export type AgentMemoryConfig = {
     storage?: string;
     vector?: string;
     embedder?: string;
     lastMessages?: number;
     workingMemory?: unknown;
 };
-export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string, Scorer extends string = string> = {
+export type CoreAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string, Scorer extends string = string> = {
     name: string;
     description: string;
     summary?: string;
@@ -348,7 +349,7 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
      */
     scorers?: Scorer[];
     agentMode?: 'delegate' | 'supervise';
-    memory?: AIAgentMemoryConfig;
+    memory?: AgentMemoryConfig;
     maxSteps?: number;
     toolChoice?: 'auto' | 'required' | 'none';
     /**
@@ -366,15 +367,15 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     tags?: string[];
     prepareStep?: (ctx: {
         stepNumber: number;
-        messages: AIMessage[];
-        tools: AIAgentToolDef[];
+        messages: AgentMessage[];
+        tools: AgentToolDef[];
         toolChoice: 'auto' | 'required' | 'none';
         model: string;
         stop: () => void;
     }) => void | Promise<void>;
     middleware?: PikkuMiddleware[];
     channelMiddleware?: CorePikkuChannelMiddleware<any, any>[];
-    aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[];
+    agentMiddleware?: PikkuAgentMiddlewareHooks<any, any>[];
     /**
      * Whether a session is required to run this agent. Defaults to `false`, since
      * agents are commonly invoked from an already-authenticated `pikkuFunc` or
@@ -389,12 +390,12 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
      * which OR together, a scope can only narrow access.
      *
      * Narrowed to the generated `ScopeId` union in a project's own
-     * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+     * `#pikku/scopes`, so an undeclared scope is a compile error.
      */
     scopes?: Scope[];
     permissions?: CorePermissionGroup<PikkuPermission>;
 };
-export type AIStreamEvent = {
+export type AgentStreamEvent = {
     type: 'step-start';
     stepNumber: number;
     agent?: string;
@@ -529,7 +530,7 @@ export type AIStreamEvent = {
 } | {
     type: 'done';
 };
-export interface AIStreamChannel extends PikkuChannel<unknown, AIStreamEvent> {
+export interface AgentStreamChannel extends PikkuChannel<unknown, AgentStreamEvent> {
 }
 export type PendingApproval = {
     type: 'tool-call';
@@ -602,14 +603,14 @@ export interface AgentRunService {
         owners?: string[];
         limit?: number;
         offset?: number;
-    }): Promise<AIThread[]>;
-    getThread(threadId: string): Promise<AIThread | null>;
-    getThreadMessages(threadId: string): Promise<AIMessage[]>;
+    }): Promise<AgentThread[]>;
+    getThread(threadId: string): Promise<AgentThread | null>;
+    getThreadMessages(threadId: string): Promise<AgentMessage[]>;
     getThreadRuns(threadId: string): Promise<AgentRunRow[]>;
     deleteThread(threadId: string): Promise<boolean>;
     getDistinctAgentNames(): Promise<string[]>;
 }
-export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' | 'tools' | 'agents' | 'workflows' | 'middleware' | 'channelMiddleware' | 'aiMiddleware' | 'permissions'> & {
+export type AgentsMeta = Record<string, Omit<CoreAgent, 'input' | 'output' | 'tools' | 'agents' | 'workflows' | 'middleware' | 'channelMiddleware' | 'agentMiddleware' | 'permissions'> & {
     tools?: string[];
     agents?: string[];
     workflows?: string[];
@@ -618,7 +619,7 @@ export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' |
     workingMemorySchema: string | null;
     middleware?: MiddlewareMetadata[];
     channelMiddleware?: MiddlewareMetadata[];
-    aiMiddleware?: MiddlewareMetadata[];
+    agentMiddleware?: MiddlewareMetadata[];
     permissions?: PermissionMetadata[];
     sourceFile?: string;
     exportedName?: string;

package/dist/wirings/agent/agent.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './agent-helpers.js';
+export { wrapChannelWithAGUI } from './agent-agui.js';
+export { runAgent, resumeAgentSync } from './agent-runner.js';
+export { resolveModelAlias } from './agent-model-config.js';
+export { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
+export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
+export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, type VoiceOutputState, } from './voice-output.js';
+export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js';
+export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, } from './agent-interrupt.js';
+export { type RunAgentParams, type StreamAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';
+export { addAgent } from './agent-registry.js';
+export type { AgentInput, AgentsMeta, AgentMemoryConfig, AgentStep, AgentContentPart, AgentRunRow, AgentRunService, AgentRunState, AgentMessage, AgentStreamChannel, AgentStreamEvent, AgentThread, CoreAgent, PendingApproval, PikkuAgentMiddlewareHooks, } from './agent.types.js';

package/dist/wirings/agent/index.js

@@ -0,0 +1,10 @@
+export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './agent-helpers.js';
+export { wrapChannelWithAGUI } from './agent-agui.js';
+export { runAgent, resumeAgentSync } from './agent-runner.js';
+export { resolveModelAlias } from './agent-model-config.js';
+export { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
+export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
+export { voiceOutput, unspeakableScripts, voiceForText, } from './voice-output.js';
+export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js';
+export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';
+export { addAgent } from './agent-registry.js';

package/dist/wirings/{ai-agent → agent}/voice-input.d.ts

@@ -58,7 +58,7 @@ export declare const voiceInput: (config?: {
     language?: string;
     model?: string;
     allowedAudioHosts?: string[];
-}) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<Record<string, unknown>, import("../../types/core.types.js").CoreSingletonServices<{
+}) => import("./agent.types.js").PikkuAgentMiddlewareHooks<Record<string, unknown>, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {
         requireAllowedHosts?: boolean;

package/dist/wirings/{ai-agent → agent}/voice-input.js

@@ -1,4 +1,4 @@
-import { pikkuAIMiddleware } from '../../types/core.types.js';
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js';
 import { safeFetch } from '../../utils/safe-fetch.js';
 function base64ToUint8Array(base64) {
     const binary = atob(base64);
@@ -78,10 +78,10 @@ export const SPOKEN_TURN = 'voice:spokenTurn';
  * bubble followed by an answer to a question they cannot see.
  */
 export const SPOKEN_TRANSCRIPT = 'voice:transcript';
-export const voiceInput = (config) => pikkuAIMiddleware({
+export const voiceInput = (config) => pikkuAgentMiddleware({
     modifyInput: async (services, { messages, instructions, shared }) => {
-        const aiAgentRunner = services.aiAgentRunner;
-        if (!aiAgentRunner?.transcribe)
+        const agentRunner = services.agentRunner;
+        if (!agentRunner?.transcribe)
             return { messages, instructions };
         const last = messages[messages.length - 1];
         const parts = last?.role === 'user' && typeof last.content !== 'string'
@@ -110,7 +110,7 @@ export const voiceInput = (config) => pikkuAIMiddleware({
             if (audioData.byteLength > MAX_AUDIO_SIZE) {
                 throw new Error('Audio file exceeds maximum size');
             }
-            const result = await aiAgentRunner.transcribe({
+            const result = await agentRunner.transcribe({
                 model: config.model,
                 audio: audioData,
                 ...(config.language

package/dist/wirings/{ai-agent → agent}/voice-output.d.ts

@@ -1,4 +1,4 @@
-type VoiceOutputState = {
+export type VoiceOutputState = {
     textBuffer?: string;
     /**
      * The audio emitted so far, as a chain.
@@ -74,7 +74,7 @@ export declare const voiceOutput: (config?: {
      * meant to be heard.
      */
     always?: boolean;
-}) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<VoiceOutputState, import("../../types/core.types.js").CoreSingletonServices<{
+}) => import("./agent.types.js").PikkuAgentMiddlewareHooks<VoiceOutputState, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {
         requireAllowedHosts?: boolean;
@@ -83,4 +83,3 @@ export declare const voiceOutput: (config?: {
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;
-export {};

package/dist/wirings/{ai-agent → agent}/voice-output.js

@@ -1,4 +1,4 @@
-import { pikkuAIMiddleware } from '../../types/core.types.js';
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js';
 import { SPOKEN_TURN } from './voice-input.js';
 function bufferToBase64(data) {
     let binary = '';
@@ -81,8 +81,8 @@ export const voiceForText = (text, speakable, fallback) => {
     }
     return fallback;
 };
-async function synthesizeAudio(aiAgentRunner, input) {
-    const result = await aiAgentRunner.generateSpeech?.({
+async function synthesizeAudio(agentRunner, input) {
+    const result = await agentRunner.generateSpeech?.({
         model: input.model,
         text: input.text,
         voice: input.voice,
@@ -93,17 +93,17 @@ async function synthesizeAudio(aiAgentRunner, input) {
         abortSignal: input.abortSignal,
     });
     if (!result) {
-        throw new Error('voiceOutput requires an aiAgentRunner with generateSpeech support');
+        throw new Error('voiceOutput requires an agentRunner with generateSpeech support');
     }
     return {
         bytes: result.audio.uint8Array,
         format: result.audio.format || input.format || 'pcm16',
     };
 }
-export const voiceOutput = (config) => pikkuAIMiddleware({
+export const voiceOutput = (config) => pikkuAgentMiddleware({
     modifyOutputStream: async (services, { event, state, shared, emit, signal }) => {
-        const { aiAgentRunner, logger } = services;
-        if (!aiAgentRunner?.generateSpeech)
+        const { agentRunner, logger } = services;
+        if (!agentRunner?.generateSpeech)
             return event;
         // knowledge: decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md
         if (!config?.always && shared[SPOKEN_TURN] === false)
@@ -140,7 +140,7 @@ export const voiceOutput = (config) => pikkuAIMiddleware({
             // Settled into a value rather than left as a rejectable promise: it
             // sits unobserved until the chain reaches it, and an unhandled
             // rejection in that window would take the process down.
-            const synthesis = synthesizeAudio(aiAgentRunner, {
+            const synthesis = synthesizeAudio(agentRunner, {
                 model: config.model,
                 text,
                 voice,

package/dist/wirings/{ai-scorer/ai-scorer-grade.d.ts → agent-scorer/agent-scorer-grade.d.ts}

@@ -1,4 +1,4 @@
-import type { ScoreJob, ScorerOutput } from './ai-scorer.types.js';
+import type { ScoreJob, ScorerOutput } from './agent-scorer.types.js';
 /**
  * Grade one run with one scorer.
  *
@@ -11,8 +11,8 @@ import type { ScoreJob, ScorerOutput } from './ai-scorer.types.js';
  * runs against servers that may have no run-state adapter at all.
  */
 export declare const gradeRun: (job: ScoreJob, services: {
-    aiAgentRunner?: unknown;
-    aiRunState?: {
+    agentRunner?: unknown;
+    agentRunState?: {
         saveScore: (score: {
             runId: string;
             scorerName: string;

package/dist/wirings/{ai-scorer/ai-scorer-grade.js → agent-scorer/agent-scorer-grade.js}

@@ -1,5 +1,5 @@
-import { runJudge } from './ai-scorer-judge.js';
-import { resolveAIScorer } from './ai-scorer-registry.js';
+import { runJudge } from './agent-scorer-judge.js';
+import { resolveAgentScorer } from './agent-scorer-registry.js';
 /**
  * Grade one run with one scorer.
  *
@@ -13,15 +13,15 @@ import { resolveAIScorer } from './ai-scorer-registry.js';
  */
 export const gradeRun = async (job, services, options) => {
     const { scorerName, ...input } = job;
-    const scorer = resolveAIScorer(scorerName);
+    const scorer = resolveAgentScorer(scorerName);
     const result = scorer.score
         ? await scorer.score(input, services)
-        : await runJudge(scorer, input, services.aiAgentRunner);
+        : await runJudge(scorer, input, services.agentRunner);
     if (options.persist) {
-        if (!services.aiRunState) {
+        if (!services.agentRunState) {
             throw new Error(`AI run state service not initialized: cannot record the '${scorerName}' grade of run ${job.runId}`);
         }
-        await services.aiRunState.saveScore({
+        await services.agentRunState.saveScore({
             runId: job.runId,
             scorerName,
             score: result.score,

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

@@ -0,0 +1,30 @@
+import type { AgentRunnerService } from '../../services/agent-runner-service.js';
+import type { PikkuAgentScorer, ScorerInput, ScorerJudgeConfig, ScorerOutput } from './agent-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.
+ *
+ * The tool calls are shown because without them a judge cannot tell a fact from
+ * a fabrication. Grading a todo agent that had just listed the user's todos
+ * correctly, a judge given only the answer called it "a plausible-looking list"
+ * that "offers no real access to your actual list, making it effectively a
+ * guess", and scored 0.2 what it scored 1 on other runs — right by its rubric,
+ * on the evidence it was given, and wrong about the run. An agent that answers
+ * from a tool and one that invents the same sentence are indistinguishable in
+ * the output alone; they differ only in what the run did to get there.
+ *
+ * How much of that to show is `judge.toolCalls`, and the default stops at the
+ * names: the 0.2 was the judge doubting the run had any access, and a name
+ * settles that without handing a third-party model the rows.
+ */
+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: PikkuAgentScorer<any>, input: ScorerInput, agentRunner: AgentRunnerService | undefined) => Promise<ScorerOutput>;

package/dist/wirings/{ai-scorer/ai-scorer-judge.js → agent-scorer/agent-scorer-judge.js}

@@ -1,4 +1,4 @@
-import { randomUUID } from '../ai-agent/ai-agent-utils.js';
+import { randomUUID } from '../agent/agent-utils.js';
 const JUDGE_OUTPUT_SCHEMA = {
     type: 'object',
     properties: {
@@ -16,11 +16,59 @@ const JUDGE_OUTPUT_SCHEMA = {
     required: ['score', 'reason'],
     additionalProperties: false,
 };
+/**
+ * The default disclosure: which tools ran and which failed, and nothing about
+ * what went in or came back. A judge that can see a run reached `listTodos`
+ * can tell a retrieved list from an invented one, which is the whole of what
+ * the trajectory is needed for — the rows themselves it does not need, and an
+ * error string is a tool's own words about the caller's data, so it is
+ * summarised rather than quoted.
+ */
+const describeToolCallName = (call) => `- ${call.name}${call.error ? ' (failed)' : ''}`;
+/** Everything about a call, for a judge that grades against what came back. */
+const describeToolCall = (call) => {
+    const outcome = call.error
+        ? `failed: ${call.error}`
+        : `returned ${formatToolValue(call.result)}`;
+    return `- ${call.name}(${formatToolValue(call.args)}) ${outcome}`;
+};
+/**
+ * A tool's arguments and result are arbitrary JSON, and some of it is large —
+ * a listing, a document, a page of search results. Truncating keeps a single
+ * fat call from crowding the answer out of the judge's context; what survives
+ * is the head, which is where the shape of a value is.
+ */
+const TOOL_VALUE_LIMIT = 500;
+const formatToolValue = (value) => {
+    if (value === undefined) {
+        return 'nothing';
+    }
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    if (text === undefined) {
+        return 'nothing';
+    }
+    return text.length > TOOL_VALUE_LIMIT
+        ? `${text.slice(0, TOOL_VALUE_LIMIT)}… (truncated)`
+        : text;
+};
 /**
  * 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.
+ *
+ * The tool calls are shown because without them a judge cannot tell a fact from
+ * a fabrication. Grading a todo agent that had just listed the user's todos
+ * correctly, a judge given only the answer called it "a plausible-looking list"
+ * that "offers no real access to your actual list, making it effectively a
+ * guess", and scored 0.2 what it scored 1 on other runs — right by its rubric,
+ * on the evidence it was given, and wrong about the run. An agent that answers
+ * from a tool and one that invents the same sentence are indistinguishable in
+ * the output alone; they differ only in what the run did to get there.
+ *
+ * How much of that to show is `judge.toolCalls`, and the default stops at the
+ * names: the 0.2 was the judge doubting the run had any access, and a name
+ * settles that without handing a third-party model the rows.
  */
 export const buildJudgePrompt = (judge, input) => {
     if (judge.prompt)
@@ -30,6 +78,10 @@ export const buildJudgePrompt = (judge, input) => {
         sections.push(`Reference answer:\n${input.reference}`);
     }
     sections.push(`Assistant answered:\n${input.output}`);
+    if (judge.toolCalls !== 'off' && input.toolCalls.length > 0) {
+        const describe = judge.toolCalls === 'full' ? describeToolCall : describeToolCallName;
+        sections.push(`Tools the assistant ran:\n${input.toolCalls.map(describe).join('\n')}`);
+    }
     sections.push(judge.goal);
     sections.push('Respond with a score 0..1 and a brief reason.');
     return sections.join('\n\n');
@@ -51,13 +103,13 @@ const normalizeScore = (scorerName, value) => {
  * A judge has no tools, which is the one case where an output schema is
  * reliably honoured.
  */
-export const runJudge = async (scorer, input, aiAgentRunner) => {
+export const runJudge = async (scorer, input, agentRunner) => {
     const judge = scorer.judge;
     if (!judge) {
         throw new Error(`Scorer '${scorer.name}' is not a judge`);
     }
-    if (!aiAgentRunner) {
-        throw new Error(`Judge '${scorer.name}' needs an AI provider, but no aiAgentRunner is registered in this process. ` +
+    if (!agentRunner) {
+        throw new Error(`Judge '${scorer.name}' needs an AI provider, but no agentRunner is registered in this process. ` +
             `A worker deployed apart from the API has to register one to run the slow scoring lane.`);
     }
     if (scorer.requiresReference && input.reference === undefined) {
@@ -71,7 +123,7 @@ export const runJudge = async (scorer, input, aiAgentRunner) => {
             createdAt: new Date(),
         },
     ];
-    const result = await aiAgentRunner.run({
+    const result = await agentRunner.run({
         model: judge.model,
         instructions: judge.goal,
         messages,

package/dist/wirings/{ai-scorer/ai-scorer-live.d.ts → agent-scorer/agent-scorer-live.d.ts}

@@ -1,5 +1,5 @@
 import type { CoreSingletonServices } from '../../types/core.types.js';
-import { type ScorerInput } from './ai-scorer.types.js';
+import { type ScorerInput } from './agent-scorer.types.js';
 /**
  * Grade one finished run on live traffic.
  *

package/dist/wirings/{ai-scorer/ai-scorer-live.js → agent-scorer/agent-scorer-live.js}

@@ -1,6 +1,6 @@
-import { scorersForAgent } from './ai-scorer-registry.js';
-import { isSampled } from './ai-scorer-sampling.js';
-import { SCORER_LANE_QUEUES } from './ai-scorer.types.js';
+import { scorersForAgent } from './agent-scorer-registry.js';
+import { isSampled } from './agent-scorer-sampling.js';
+import { SCORER_LANE_QUEUES } from './agent-scorer.types.js';
 /**
  * Grade one finished run on live traffic.
  *

package/dist/wirings/{ai-scorer/ai-scorer-registry.d.ts → agent-scorer/agent-scorer-registry.d.ts}

@@ -1,12 +1,12 @@
-import type { PikkuAIScorer } from './ai-scorer.types.js';
-export declare const addAIScorer: (scorerName: string, scorer: PikkuAIScorer<any>, packageName?: string | null) => void;
-export declare const getAIScorers: () => Map<string, PikkuAIScorer>;
-export declare const getAIScorersMeta: () => import("./ai-scorer.types.js").ScorerMeta;
+import type { PikkuAgentScorer } from './agent-scorer.types.js';
+export declare const addAgentScorer: (scorerName: string, scorer: PikkuAgentScorer<any>, packageName?: string | null) => void;
+export declare const getAgentScorers: () => Map<string, PikkuAgentScorer>;
+export declare const getAgentScorersMeta: () => import("./agent-scorer.types.js").ScorerMeta;
 /**
  * Resolve a scorer by name across every registered package, the way an agent's
  * tools are resolved: a scorer declared in an addon is nameable by an app agent.
  */
-export declare const resolveAIScorer: (scorerName: string) => PikkuAIScorer<any>;
+export declare const resolveAgentScorer: (scorerName: string) => PikkuAgentScorer<any>;
 /**
  * The scorers an agent asked to be graded by.
  *
@@ -15,4 +15,4 @@ export declare const resolveAIScorer: (scorerName: string) => PikkuAIScorer<any>
  */
 export declare const scorersForAgent: (agentName: string, logger?: {
     warn: (message: string) => void;
-}) => PikkuAIScorer<any>[];
+}) => PikkuAgentScorer<any>[];