@pikku/core 0.12.80 → 0.12.83

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

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

@@ -0,0 +1,92 @@
+import { randomUUID } from '../ai-agent/ai-agent-utils.js';
+const JUDGE_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        score: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: 'How well the answer meets the rubric. 1 is best.',
+        },
+        reason: {
+            type: 'string',
+            description: 'One or two sentences explaining the score.',
+        },
+    },
+    required: ['score', 'reason'],
+    additionalProperties: false,
+};
+/**
+ * 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 const buildJudgePrompt = (judge, input) => {
+    if (judge.prompt)
+        return judge.prompt(input);
+    const sections = [`User asked:\n${input.input}`];
+    if (input.reference !== undefined) {
+        sections.push(`Reference answer:\n${input.reference}`);
+    }
+    sections.push(`Assistant answered:\n${input.output}`);
+    sections.push(judge.goal);
+    sections.push('Respond with a score 0..1 and a brief reason.');
+    return sections.join('\n\n');
+};
+/**
+ * Clamp rather than reject: a model that answers 1.2 has still made a legible
+ * judgement, and failing the job would lose it. A non-number has not.
+ */
+const normalizeScore = (scorerName, value) => {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new Error(`Judge '${scorerName}' returned a non-numeric score: ${JSON.stringify(value)}`);
+    }
+    return Math.min(1, Math.max(0, value));
+};
+/**
+ * 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 const runJudge = async (scorer, input, aiAgentRunner) => {
+    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. ` +
+            `A worker deployed apart from the API has to register one to run the slow scoring lane.`);
+    }
+    if (scorer.requiresReference && input.reference === undefined) {
+        throw new Error(`Judge '${scorer.name}' grades against a reference answer, but none was supplied`);
+    }
+    const messages = [
+        {
+            id: randomUUID(),
+            role: 'user',
+            content: buildJudgePrompt(judge, input),
+            createdAt: new Date(),
+        },
+    ];
+    const result = await aiAgentRunner.run({
+        model: judge.model,
+        instructions: judge.goal,
+        messages,
+        tools: [],
+        maxSteps: 1,
+        toolChoice: 'none',
+        outputSchema: JUDGE_OUTPUT_SCHEMA,
+    });
+    const object = (result.object ?? {});
+    return {
+        score: normalizeScore(scorer.name, object.score),
+        ...(typeof object.reason === 'string' ? { reason: object.reason } : {}),
+        metadata: {
+            judgeModel: judge.model,
+            judgeTokens: result.usage.inputTokens + result.usage.outputTokens,
+        },
+    };
+};

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

@@ -0,0 +1,15 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import { type ScorerInput } from './ai-scorer.types.js';
+/**
+ * Grade one finished run on live traffic.
+ *
+ * Called as the terminal step of `finalizeAgentRun`, so it is structurally last
+ * — a developer cannot register anything after it, and cannot reorder it. It is
+ * also strictly best-effort: the client already has its answer, so nothing here
+ * may fail the run.
+ */
+export declare const scoreFinishedRun: (run: ScorerInput, services: Pick<CoreSingletonServices, "logger"> & {
+    queueService?: {
+        add: (queueName: string, data: unknown) => Promise<any>;
+    };
+}) => Promise<void>;

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

@@ -0,0 +1,38 @@
+import { scorersForAgent } from './ai-scorer-registry.js';
+import { isSampled } from './ai-scorer-sampling.js';
+import { SCORER_LANE_QUEUES } from './ai-scorer.types.js';
+/**
+ * Grade one finished run on live traffic.
+ *
+ * Called as the terminal step of `finalizeAgentRun`, so it is structurally last
+ * — a developer cannot register anything after it, and cannot reorder it. It is
+ * also strictly best-effort: the client already has its answer, so nothing here
+ * may fail the run.
+ */
+export const scoreFinishedRun = async (run, services) => {
+    const scorers = scorersForAgent(run.agentName, services.logger).filter(
+    // A reference-based judge grades against an answer key, and live traffic
+    // has none.
+    (scorer) => !scorer.requiresReference);
+    if (scorers.length === 0)
+        return;
+    if (!services.queueService) {
+        services.logger?.warn(`[pikku] Agent '${run.agentName}' declares scorers but no queue service is registered — skipping live scoring`);
+        return;
+    }
+    const sampled = scorers.filter((scorer) => isSampled(run.runId, scorer.name, scorer.sampleRate));
+    // One message per scorer, so each gets its own retry, isolation and lane.
+    await Promise.all(sampled.map(async (scorer) => {
+        try {
+            await services.queueService.add(SCORER_LANE_QUEUES[scorer.lane], {
+                ...run,
+                scorerName: scorer.name,
+                // No reference: a live run has no answer key.
+                reference: undefined,
+            });
+        }
+        catch (error) {
+            services.logger?.error(`[pikku] Failed to enqueue the '${scorer.name}' grade of run ${run.runId}`, { error });
+        }
+    }));
+};

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

@@ -0,0 +1,18 @@
+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;
+/**
+ * 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>;
+/**
+ * The scorers an agent asked to be graded by.
+ *
+ * A name that resolves to nothing is warned about rather than thrown: a missing
+ * scorer must not take down a run that has already answered the user.
+ */
+export declare const scorersForAgent: (agentName: string, logger?: {
+    warn: (message: string) => void;
+}) => PikkuAIScorer<any>[];

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

@@ -0,0 +1,46 @@
+import { pikkuState } from '../../pikku-state.js';
+export const addAIScorer = (scorerName, scorer, packageName = null) => {
+    const scorersMeta = pikkuState(packageName, 'agent', 'scorersMeta');
+    if (!scorersMeta[scorerName]) {
+        console.warn(`[pikku] Skipping AI scorer '${scorerName}' — metadata not found. Scorers must be declared in a *.scorer.ts file.`);
+        return;
+    }
+    const scorers = pikkuState(packageName, 'agent', 'scorers');
+    if (scorers.has(scorerName)) {
+        throw new Error(`AI scorer already exists: ${scorerName}`);
+    }
+    scorers.set(scorerName, scorer);
+};
+export const getAIScorers = () => pikkuState(null, 'agent', 'scorers');
+export const getAIScorersMeta = () => pikkuState(null, 'agent', 'scorersMeta');
+/**
+ * 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 const resolveAIScorer = (scorerName) => {
+    const scorer = pikkuState(null, 'agent', 'scorers').get(scorerName);
+    if (!scorer) {
+        throw new Error(`AI scorer not found: ${scorerName}`);
+    }
+    return scorer;
+};
+/**
+ * The scorers an agent asked to be graded by.
+ *
+ * A name that resolves to nothing is warned about rather than thrown: a missing
+ * scorer must not take down a run that has already answered the user.
+ */
+export const scorersForAgent = (agentName, logger) => {
+    const agent = pikkuState(null, 'agent', 'agents').get(agentName);
+    const names = agent?.scorers ?? [];
+    const scorers = [];
+    for (const name of names) {
+        const scorer = pikkuState(null, 'agent', 'scorers').get(name);
+        if (!scorer) {
+            logger?.warn(`[pikku] Agent '${agentName}' names scorer '${name}', which is not registered — skipping it`);
+            continue;
+        }
+        scorers.push(scorer);
+    }
+    return scorers;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Decide whether one run is in a scorer's sample.
+ *
+ * Deterministic on `(runId, scorerName)` rather than random, so re-running the
+ * decision — a retried job, a replayed run, a test — always lands the same way,
+ * and so two scorers at the same rate do not sample the same runs.
+ */
+export declare const isSampled: (runId: string, scorerName: string, sampleRate: number) => boolean;

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

@@ -0,0 +1,31 @@
+/**
+ * Decide whether one run is in a scorer's sample.
+ *
+ * Deterministic on `(runId, scorerName)` rather than random, so re-running the
+ * decision — a retried job, a replayed run, a test — always lands the same way,
+ * and so two scorers at the same rate do not sample the same runs.
+ */
+export const isSampled = (runId, scorerName, sampleRate) => {
+    if (sampleRate >= 1)
+        return true;
+    if (sampleRate <= 0)
+        return false;
+    const key = `${scorerName}:${runId}`;
+    // FNV-1a: no crypto dependency, and stable across processes and platforms,
+    // which a language-level string hash is not guaranteed to be.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        hash ^= key.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    // FNV-1a alone leaves its high bits barely moved between keys that differ
+    // only in their last characters — sequential run ids being exactly that —
+    // which biases the fraction actually sampled well away from the rate asked
+    // for. MurmurHash3's finalizer spreads the low bits back over the whole word.
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x85ebca6b) >>> 0;
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 0xc2b2ae35) >>> 0;
+    hash ^= hash >>> 16;
+    return (hash >>> 0) / 0x100000000 < sampleRate;
+};

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

@@ -0,0 +1,10 @@
+import type { ScorerInput } from './ai-scorer.types.js';
+/**
+ * Start retaining snapshots. Called where the scenario grading RPC is
+ * registered, so the buffer exists in exactly the processes that can read it —
+ * a development server — and never in a deployed bundle.
+ */
+export declare const enableScoreSnapshots: (maxRuns?: number) => void;
+export declare const recordScoreSnapshot: (run: ScorerInput) => void;
+export declare const getScoreSnapshot: (runId: string) => ScorerInput | undefined;
+export declare const resetScoreSnapshots: () => void;

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

@@ -0,0 +1,40 @@
+/**
+ * The last few finished runs, held so a scenario can grade one.
+ *
+ * A scenario cannot rebuild a `ScorerInput` from storage: the run record holds
+ * status and usage, and the prompt, answer and tool calls are spread across the
+ * thread's messages, where the boundary of a single run is not recoverable. So
+ * the runtime keeps the snapshot it already took at finalize — which is also
+ * what makes a scenario's grade comparable to a live one, since both grade the
+ * identical object, redactions included.
+ *
+ * Off unless something turns it on, and bounded when it is. A process that
+ * grades no scenarios holds nothing, and one that does cannot accumulate run
+ * content without limit.
+ */
+const snapshots = new Map();
+let limit = 0;
+/**
+ * Start retaining snapshots. Called where the scenario grading RPC is
+ * registered, so the buffer exists in exactly the processes that can read it —
+ * a development server — and never in a deployed bundle.
+ */
+export const enableScoreSnapshots = (maxRuns = 50) => {
+    limit = maxRuns;
+};
+export const recordScoreSnapshot = (run) => {
+    if (limit === 0)
+        return;
+    snapshots.set(run.runId, run);
+    while (snapshots.size > limit) {
+        const oldest = snapshots.keys().next().value;
+        if (oldest === undefined)
+            break;
+        snapshots.delete(oldest);
+    }
+};
+export const getScoreSnapshot = (runId) => snapshots.get(runId);
+export const resetScoreSnapshots = () => {
+    snapshots.clear();
+    limit = 0;
+};

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

@@ -0,0 +1,15 @@
+import { type ScoreJob } from './ai-scorer.types.js';
+/**
+ * The one worker behind both lanes: it resolves the scorer by name and grades.
+ * The lane a job arrived on decides nothing except how long it may take.
+ */
+export declare function pikkuAIScoreWorkerFunc(_services: Record<string, unknown>, job: ScoreJob): Promise<void>;
+/**
+ * Bind the two lane queues to the shared worker.
+ *
+ * Registered programmatically rather than emitted into the user's bootstrap:
+ * `wireQueueWorker` warns and returns for a name codegen produced no metadata
+ * for, so the metadata is synthesised here alongside the registration. This
+ * mirrors how workflows wire their own queues.
+ */
+export declare const wireAIScorerQueueWorkers: () => void;

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

@@ -0,0 +1,58 @@
+import { pikkuState } from '../../pikku-state.js';
+import { addFunction } from '../../function/function-runner.js';
+import { wireQueueWorker } from '../queue/queue-runner.js';
+import { gradeRun } from './ai-scorer-grade.js';
+import { SCORER_LANE_QUEUES } from './ai-scorer.types.js';
+/**
+ * The one worker behind both lanes: it resolves the scorer by name and grades.
+ * The lane a job arrived on decides nothing except how long it may take.
+ */
+export async function pikkuAIScoreWorkerFunc(_services, job) {
+    const services = pikkuState(null, 'package', 'singletonServices');
+    if (!services) {
+        throw new Error(`Singleton services not initialized: cannot run the '${job.scorerName}' grade of run ${job.runId}`);
+    }
+    await gradeRun(job, services, { persist: true });
+}
+const SCORE_WORKER_FUNC_ID = 'pikkuAIScoreWorker';
+/**
+ * Bind the two lane queues to the shared worker.
+ *
+ * Registered programmatically rather than emitted into the user's bootstrap:
+ * `wireQueueWorker` warns and returns for a name codegen produced no metadata
+ * for, so the metadata is synthesised here alongside the registration. This
+ * mirrors how workflows wire their own queues.
+ */
+export const wireAIScorerQueueWorkers = () => {
+    // No scorers means no lanes: a deployment that grades nothing should not be
+    // left holding two queues nothing ever writes to.
+    if (pikkuState(null, 'agent', 'scorers').size === 0)
+        return;
+    const functions = pikkuState(null, 'function', 'functions');
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    const queueMeta = pikkuState(null, 'queue', 'meta');
+    if (!functions.has(SCORE_WORKER_FUNC_ID)) {
+        addFunction(SCORE_WORKER_FUNC_ID, { func: pikkuAIScoreWorkerFunc });
+    }
+    if (!functionsMeta[SCORE_WORKER_FUNC_ID]) {
+        functionsMeta[SCORE_WORKER_FUNC_ID] = {
+            pikkuFuncId: SCORE_WORKER_FUNC_ID,
+            sessionless: true,
+            functionType: 'helper',
+            inputSchemaName: null,
+            outputSchemaName: null,
+        };
+    }
+    for (const queueName of Object.values(SCORER_LANE_QUEUES)) {
+        if (!queueMeta[queueName]) {
+            queueMeta[queueName] = {
+                pikkuFuncId: SCORE_WORKER_FUNC_ID,
+                name: queueName,
+            };
+        }
+        wireQueueWorker({
+            name: queueName,
+            func: { func: pikkuAIScoreWorkerFunc },
+        });
+    }
+};

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

@@ -0,0 +1,39 @@
+import type { PikkuAIScorer, ScorerInput, ScorerOutput } from './ai-scorer.types.js';
+/**
+ * A heuristic scorer: pure code over the finished run, no model call, so it
+ * grades on the fast lane.
+ */
+export declare const pikkuAIScorer: <Services = any>(config: {
+    name: string;
+    description: string;
+    /** 0..1 fraction of live runs to grade. Defaults to all of them. */
+    sampleRate?: number;
+    /**
+     * Grades against a known-correct answer. Such a scorer is test-only — live
+     * traffic has no answer key, so the runtime never samples it.
+     */
+    requiresReference?: boolean;
+    score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>;
+}) => PikkuAIScorer<Services>;
+/**
+ * An LLM-judge scorer: the runtime makes the model call and forces a structured
+ * `{ score, reason }`, so a judge is a rubric rather than a prompt to parse.
+ *
+ * The rubric field is `goal`, matching `pikkuAIAgent`'s prompt vocabulary — a
+ * judge is a degenerate agent, and should use the same word for the same thing.
+ * `prompt` is the escape hatch for non-standard framing.
+ */
+export declare const pikkuAIJudge: <Services = any>(config: {
+    name: string;
+    description: string;
+    /** 0..1 fraction of live runs to grade. Defaults to all of them. */
+    sampleRate?: number;
+    /**
+     * Grades against a known-correct answer. Such a judge is test-only — live
+     * traffic has no answer key, so the runtime never samples it.
+     */
+    requiresReference?: boolean;
+    model: string;
+    goal: string;
+    prompt?: (input: ScorerInput) => string;
+}) => PikkuAIScorer<Services>;

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

@@ -0,0 +1,40 @@
+const assertSampleRate = (name, sampleRate) => {
+    if (sampleRate === undefined)
+        return 1;
+    if (sampleRate < 0 || sampleRate > 1) {
+        throw new Error(`Scorer '${name}' has a sampleRate of ${sampleRate} — it is a fraction of live runs to grade, so it must be between 0 and 1`);
+    }
+    return sampleRate;
+};
+/**
+ * A heuristic scorer: pure code over the finished run, no model call, so it
+ * grades on the fast lane.
+ */
+export const pikkuAIScorer = (config) => ({
+    name: config.name,
+    description: config.description,
+    lane: 'fast',
+    sampleRate: assertSampleRate(config.name, config.sampleRate),
+    requiresReference: config.requiresReference ?? false,
+    score: config.score,
+});
+/**
+ * An LLM-judge scorer: the runtime makes the model call and forces a structured
+ * `{ score, reason }`, so a judge is a rubric rather than a prompt to parse.
+ *
+ * The rubric field is `goal`, matching `pikkuAIAgent`'s prompt vocabulary — a
+ * judge is a degenerate agent, and should use the same word for the same thing.
+ * `prompt` is the escape hatch for non-standard framing.
+ */
+export const pikkuAIJudge = (config) => ({
+    name: config.name,
+    description: config.description,
+    lane: 'slow',
+    sampleRate: assertSampleRate(config.name, config.sampleRate),
+    requiresReference: config.requiresReference ?? false,
+    judge: {
+        model: config.model,
+        goal: config.goal,
+        ...(config.prompt ? { prompt: config.prompt } : {}),
+    },
+});

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

@@ -0,0 +1,90 @@
+/**
+ * What a scorer is shown about a finished run.
+ *
+ * One snapshot, taken after the output middleware has resolved, so a scorer and
+ * the persisted run record see the same thing — including the redactions.
+ */
+export interface ScorerInput {
+    runId: string;
+    agentName: string;
+    threadId?: string;
+    resourceId?: string;
+    /** The user prompt the run answered. */
+    input: string;
+    /** The agent's final text answer. */
+    output: string;
+    /**
+     * The known-correct answer. Supplied by a scenario for a reference-based
+     * judge; never set on live traffic, which has no answer key.
+     */
+    reference?: string;
+    toolCalls: {
+        name: string;
+        args: unknown;
+        result?: unknown;
+        error?: string;
+    }[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        model?: string;
+    };
+}
+export interface ScorerOutput {
+    /** 0..1, so grades are comparable across scorers. */
+    score: number;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The queue a scorer's jobs go to. Two lanes exist only so a flood of slow
+ * LLM-judge jobs cannot starve the cheap heuristic ones; within a lane it is
+ * plain FIFO.
+ */
+export type ScorerLane = 'fast' | 'slow';
+export declare const SCORER_LANE_QUEUES: Record<ScorerLane, string>;
+/**
+ * A judge's model call. Present only on a scorer built with `pikkuAIJudge`;
+ * `score` is present only on one built with `pikkuAIScorer`. Exactly one of the
+ * two is set, which is what the two constructors exist to guarantee.
+ */
+export type ScorerJudgeConfig = {
+    model: string;
+    goal: string;
+    prompt?: (input: ScorerInput) => string;
+};
+export type PikkuAIScorer<Services = any> = {
+    name: string;
+    description: string;
+    lane: ScorerLane;
+    /** 0..1 fraction of live runs to grade. */
+    sampleRate: number;
+    /**
+     * Grades against a known-correct answer, so it is test-only: live traffic has
+     * no answer key and the runtime never samples it.
+     */
+    requiresReference: boolean;
+    score?: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>;
+    judge?: ScorerJudgeConfig;
+};
+export type ScorerMeta = Record<string, {
+    name: string;
+    description: string;
+    lane: ScorerLane;
+    sampleRate: number;
+    requiresReference: boolean;
+    sourceFile?: string;
+    exportedName?: string;
+}>;
+/** A single scorer's job on a lane queue. */
+export type ScoreJob = ScorerInput & {
+    scorerName: string;
+};
+export type AIRunScore = {
+    runId: string;
+    scorerName: string;
+    score: number;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+};

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

@@ -0,0 +1,4 @@
+export const SCORER_LANE_QUEUES = {
+    fast: 'ai-score-fast',
+    slow: 'ai-score-slow',
+};

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

@@ -0,0 +1,6 @@
+export { pikkuAIScorer, pikkuAIJudge } from './ai-scorer.js';
+export { addAIScorer, getAIScorers, getAIScorersMeta, } from './ai-scorer-registry.js';
+export { gradeRun } from './ai-scorer-grade.js';
+export { enableScoreSnapshots, getScoreSnapshot, } from './ai-scorer-snapshots.js';
+export { wireAIScorerQueueWorkers, } from './ai-scorer-worker.js';
+export type { AIRunScore, PikkuAIScorer, ScoreJob, ScorerInput, ScorerJudgeConfig, ScorerLane, ScorerMeta, ScorerOutput, } from './ai-scorer.types.js';

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

@@ -0,0 +1,5 @@
+export { pikkuAIScorer, pikkuAIJudge } from './ai-scorer.js';
+export { addAIScorer, getAIScorers, getAIScorersMeta, } from './ai-scorer-registry.js';
+export { gradeRun } from './ai-scorer-grade.js';
+export { enableScoreSnapshots, getScoreSnapshot, } from './ai-scorer-snapshots.js';
+export { wireAIScorerQueueWorkers, } from './ai-scorer-worker.js';

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

@@ -1,13 +1,12 @@
-export { wireChannel, openChannel } from './channel-runner.js';
-export { addChannelMiddleware, combineChannelMiddleware, wrapChannelWithMiddleware, } from './channel-middleware-runner.js';
+export { wireChannel } from './channel-runner.js';
+export { addChannelMiddleware, combineChannelMiddleware, } from './channel-middleware-runner.js';
 export { logChannels } from './log-channels.js';
 export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js';
 export type { EventHubService } from './eventhub-service.js';
 export { ChannelStore } from './channel-store.js';
 export type { Channel } from './channel-store.js';
 export { EventHubStore } from './eventhub-store.js';
-export type { BinaryData, ChannelsMeta, CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, ChannelMessageMeta, ChannelMeta, ChannelRemote, PikkuChannel, PikkuChannelHandlerFactory, } from './channel.types.js';
+export type { BinaryData, ChannelsMeta, CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, ChannelMessageMeta, ChannelMeta, PikkuChannel, PikkuChannelHandlerFactory, } from './channel.types.js';
 export { defineChannelRoutes } from './define-channel-routes.js';
-export { CHANNEL_RPC_PENDING, CHANNEL_RPC_REQUEST, CHANNEL_RPC_RESPONSE, ChannelDeploymentService, ChannelRPCError, ChannelRPCRegistry, createChannelRPCResponder, createChannelRPCInputValidator, createChannelRPCResultValidator, isChannelRPCPending, isChannelRPCRequest, isChannelRPCResponse, resolveCapability, unsupportedChannelRemote, } from './channel-rpc.js';
-export type { ApprovalPolicy, ApprovalRequester, Capabilities, Capability, CapabilityDef, CapabilityHandler, ChannelRPCPending, ChannelRPCRequest, ChannelRPCResponse, ChannelRPCValidator, } from './channel-rpc.js';
-export { channelRemote, getChannelHostRPC, handleChannelRPCResponse, releaseChannelHostRPC, } from './channel-host-rpc.js';
+export { ChannelDeploymentService, ChannelRPCError, ChannelRPCRegistry, unsupportedChannelRemote, } from './channel-rpc.js';
+export type { ApprovalPolicy, ApprovalRequester, Capabilities, Capability, CapabilityHandler, ChannelRPCPending, ChannelRPCRequest, ChannelRPCResponse, ChannelRPCValidator, } from './channel-rpc.js';