@pikku/core 0.12.83 → 0.12.84

package/dist/wirings/agent/agent-agui.d.ts

@@ -0,0 +1,79 @@
+import type { AgentStreamChannel } from './agent.types.js';
+type AGUIEvent = {
+    type: 'TEXT_MESSAGE_START';
+    messageId: string;
+} | {
+    type: 'TEXT_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'TEXT_MESSAGE_END';
+    messageId: string;
+} | {
+    type: 'TOOL_CALL_START';
+    toolCallId: string;
+    toolCallName: string;
+} | {
+    type: 'TOOL_CALL_ARGS';
+    toolCallId: string;
+    delta: string;
+} | {
+    type: 'TOOL_CALL_END';
+    toolCallId: string;
+    toolCallName: string;
+} | {
+    type: 'TOOL_CALL_RESULT';
+    messageId: string;
+    toolCallId: string;
+    role: 'tool';
+    content: string;
+} | {
+    type: 'THINKING_START';
+} | {
+    type: 'THINKING_TEXT_MESSAGE_START';
+    messageId: string;
+} | {
+    type: 'THINKING_TEXT_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'THINKING_TEXT_MESSAGE_END';
+    messageId: string;
+} | {
+    type: 'THINKING_END';
+} | {
+    type: 'RUN_STARTED';
+    threadId: string;
+    runId: string;
+} | {
+    type: 'RUN_FINISHED';
+    threadId: string;
+    runId: string;
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+} | {
+    type: 'RUN_ERROR';
+    message: string;
+    code?: string;
+} | {
+    type: 'STEP_STARTED';
+    stepName: string;
+} | {
+    type: 'STEP_FINISHED';
+    stepName: string;
+} | {
+    type: 'CUSTOM';
+    name: string;
+    value: unknown;
+};
+export type { AGUIEvent };
+export type AGUIChannelOptions = {
+    threadId?: string;
+    runId?: string;
+    getRunId?: () => string | undefined;
+};
+export declare function wrapChannelWithAGUI(inner: AgentStreamChannel, options?: AGUIChannelOptions): AgentStreamChannel;

package/dist/wirings/agent/agent-agui.js

@@ -0,0 +1,327 @@
+import { randomUUID } from './agent-utils.js';
+function resultToString(result) {
+    if (typeof result === 'string')
+        return result;
+    try {
+        return JSON.stringify(result, (_key, val) => typeof val === 'bigint' ? val.toString() : val);
+    }
+    catch {
+        return String(result);
+    }
+}
+export function wrapChannelWithAGUI(inner, options) {
+    const threadId = options?.threadId ?? randomUUID();
+    let runId = options?.runId ?? null;
+    function resolveRunId() {
+        if (!runId) {
+            runId = options?.getRunId?.() ?? randomUUID();
+        }
+        return runId;
+    }
+    let textMessageId = null;
+    let thinkingMessageId = null;
+    let openStepName = null;
+    let stepSeq = 0;
+    let runStartedSent = false;
+    let terminal = false;
+    let sawUsage = false;
+    let usageModel;
+    const usageTotals = { input: 0, output: 0 };
+    function send(event) {
+        if (!runStartedSent) {
+            runStartedSent = true;
+            inner.send({
+                type: 'RUN_STARTED',
+                threadId,
+                runId: resolveRunId(),
+            });
+        }
+        inner.send(event);
+    }
+    function endTextMessage() {
+        if (textMessageId) {
+            send({ type: 'TEXT_MESSAGE_END', messageId: textMessageId });
+            textMessageId = null;
+        }
+    }
+    function endThinkingMessage() {
+        if (thinkingMessageId) {
+            send({ type: 'THINKING_TEXT_MESSAGE_END', messageId: thinkingMessageId });
+            send({ type: 'THINKING_END' });
+            thinkingMessageId = null;
+        }
+    }
+    function endStep() {
+        if (openStepName) {
+            send({ type: 'STEP_FINISHED', stepName: openStepName });
+            openStepName = null;
+        }
+    }
+    function ensureTextMessage() {
+        if (!textMessageId) {
+            textMessageId = randomUUID();
+            send({ type: 'TEXT_MESSAGE_START', messageId: textMessageId });
+        }
+        return textMessageId;
+    }
+    function ensureThinkingMessage() {
+        if (!thinkingMessageId) {
+            thinkingMessageId = randomUUID();
+            send({ type: 'THINKING_START' });
+            send({
+                type: 'THINKING_TEXT_MESSAGE_START',
+                messageId: thinkingMessageId,
+            });
+        }
+        return thinkingMessageId;
+    }
+    function finishRun() {
+        endTextMessage();
+        endThinkingMessage();
+        endStep();
+        send({
+            type: 'RUN_FINISHED',
+            threadId,
+            runId: resolveRunId(),
+            ...(usageModel ? { model: usageModel } : {}),
+            ...(sawUsage
+                ? {
+                    usage: {
+                        promptTokens: usageTotals.input,
+                        completionTokens: usageTotals.output,
+                        totalTokens: usageTotals.input + usageTotals.output,
+                    },
+                }
+                : {}),
+        });
+        terminal = true;
+    }
+    return {
+        channelId: inner.channelId,
+        openingData: inner.openingData,
+        get state() {
+            return inner.state;
+        },
+        setState: (s) => inner.setState(s),
+        getState: () => inner.getState(),
+        clearState: () => inner.clearState(),
+        // Delegated: the wrapper is a view over the same connection, so a peer
+        // reachable from the channel underneath is reachable from here too.
+        remote: (funcName, data) => inner.remote(funcName, data),
+        sendBinary: (data) => inner.sendBinary(data),
+        close: () => inner.close(),
+        send: (event) => {
+            if (terminal)
+                return;
+            switch (event.type) {
+                case 'text-delta': {
+                    endThinkingMessage();
+                    const id = ensureTextMessage();
+                    send({
+                        type: 'TEXT_MESSAGE_CONTENT',
+                        messageId: id,
+                        delta: event.text,
+                    });
+                    break;
+                }
+                case 'reasoning-delta': {
+                    endTextMessage();
+                    const id = ensureThinkingMessage();
+                    send({
+                        type: 'THINKING_TEXT_MESSAGE_CONTENT',
+                        messageId: id,
+                        delta: event.text,
+                    });
+                    break;
+                }
+                case 'tool-call': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'TOOL_CALL_START',
+                        toolCallId: event.toolCallId,
+                        toolCallName: event.toolName,
+                    });
+                    send({
+                        type: 'TOOL_CALL_ARGS',
+                        toolCallId: event.toolCallId,
+                        delta: resultToString(event.args) || '{}',
+                    });
+                    send({
+                        type: 'TOOL_CALL_END',
+                        toolCallId: event.toolCallId,
+                        toolCallName: event.toolName,
+                    });
+                    break;
+                }
+                case 'tool-result': {
+                    send({
+                        type: 'TOOL_CALL_RESULT',
+                        messageId: randomUUID(),
+                        toolCallId: event.toolCallId,
+                        role: 'tool',
+                        content: resultToString(event.result),
+                    });
+                    break;
+                }
+                case 'usage': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    sawUsage = true;
+                    usageTotals.input += event.tokens.input;
+                    usageTotals.output += event.tokens.output;
+                    if (event.model)
+                        usageModel = event.model;
+                    break;
+                }
+                case 'error': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    send({ type: 'RUN_ERROR', message: event.message });
+                    terminal = true;
+                    break;
+                }
+                case 'done': {
+                    finishRun();
+                    break;
+                }
+                case 'step-start': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    stepSeq += 1;
+                    openStepName = `${event.agent ?? 'step'}#${stepSeq}`;
+                    send({ type: 'STEP_STARTED', stepName: openStepName });
+                    break;
+                }
+                case 'approval-request': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:approval-request',
+                        value: {
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            reason: event.reason,
+                            runId: event.runId,
+                            agent: event.agent,
+                            session: event.session,
+                        },
+                    });
+                    break;
+                }
+                case 'credential-request': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:credential-request',
+                        value: {
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            credentialName: event.credentialName,
+                            credentialType: event.credentialType,
+                            connectUrl: event.connectUrl,
+                            runId: event.runId,
+                            agent: event.agent,
+                            session: event.session,
+                        },
+                    });
+                    break;
+                }
+                case 'generative-ui': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:generative-ui',
+                        value: { spec: event.spec },
+                    });
+                    break;
+                }
+                case 'data': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:data',
+                        value: { name: event.name, data: event.data },
+                    });
+                    break;
+                }
+                case 'agent-call': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:agent-call',
+                        value: {
+                            agentName: event.agentName,
+                            session: event.session,
+                            input: event.input,
+                        },
+                    });
+                    break;
+                }
+                case 'agent-result': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:agent-result',
+                        value: {
+                            agentName: event.agentName,
+                            session: event.session,
+                            result: event.result,
+                        },
+                    });
+                    break;
+                }
+                case 'suspended': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:suspended',
+                        value: { reason: event.reason, missingRpcs: event.missingRpcs },
+                    });
+                    break;
+                }
+                case 'interrupted': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:interrupted',
+                        value: {
+                            runId: event.runId,
+                            text: event.text,
+                            reason: event.reason,
+                        },
+                    });
+                    break;
+                }
+                // knowledge: decisions/internals/agent-speech-travels-as-a-custom-agui-event.md
+                case 'audio-delta': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:audio-delta',
+                        value: {
+                            data: event.data,
+                            format: event.format,
+                            ...(event.text === undefined ? {} : { text: event.text }),
+                        },
+                    });
+                    break;
+                }
+                case 'audio-done': {
+                    send({ type: 'CUSTOM', name: 'pikku:audio-done', value: {} });
+                    break;
+                }
+                case 'transcript': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:transcript',
+                        value: { text: event.text },
+                    });
+                    break;
+                }
+            }
+        },
+    };
+}

package/dist/wirings/agent/agent-finalize.d.ts

@@ -0,0 +1,58 @@
+import type { AgentStep, AgentMessage, PikkuAgentMiddlewareHooks } from './agent.types.js';
+import type { AgentRunStateService } from '../../services/agent-run-state-service.js';
+export type RunUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    model?: string;
+};
+/**
+ * Everything a finished run produced, after all middleware has had its say.
+ *
+ * One snapshot feeds persistence and anything that grades the run, so that what
+ * a scorer is shown is exactly what was stored — including the redactions.
+ */
+export type FinalizedRun = {
+    runId: string;
+    agentName: string;
+    threadId: string;
+    resourceId?: string;
+    /** The prompt the run answered — what a scorer grades the answer against. */
+    input: string;
+    text: string;
+    steps: AgentStep[];
+    usage: RunUsage;
+};
+/**
+ * The prompt a run answered: the most recent user turn, which is what the model
+ * was last asked. On a resumed run the earlier turns are context, not the ask.
+ */
+export declare const lastUserMessageText: (messages: AgentMessage[]) => string;
+/**
+ * Run the `modifyOutput` chain over a finished non-streaming run.
+ *
+ * Reverse order, matching the input chain: the middleware registered first
+ * wraps the others, so it sees the output last.
+ */
+export declare const applyOutputMiddleware: (agentMiddlewares: PikkuAgentMiddlewareHooks[], singletonServices: any, input: {
+    text: string;
+    messages: AgentMessage[];
+    steps: AgentStep[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}) => Promise<{
+    text: string;
+    messages: AgentMessage[];
+    steps: AgentStep[];
+}>;
+/**
+ * The one place a run ends successfully.
+ *
+ * Every path that completes a run — streamed, non-streamed, and resumed after a
+ * tool approval — goes through here, so that anything terminal is reachable
+ * from all of them and cannot be reordered by a middleware author. Nothing here
+ * may rewrite the run: by this point the output middleware has resolved and, on
+ * the streaming path, the client already has the reply.
+ */
+export declare const finalizeAgentRun: (agentRunState: AgentRunStateService, run: FinalizedRun) => Promise<void>;

package/dist/wirings/agent/agent-finalize.js

@@ -0,0 +1,138 @@
+import { pikkuState } from '../../pikku-state.js';
+import { scoreFinishedRun } from '../agent-scorer/agent-scorer-live.js';
+import { recordScoreSnapshot } from '../agent-scorer/agent-scorer-snapshots.js';
+/**
+ * The prompt a run answered: the most recent user turn, which is what the model
+ * was last asked. On a resumed run the earlier turns are context, not the ask.
+ */
+export const lastUserMessageText = (messages) => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message?.role !== 'user')
+            continue;
+        if (typeof message.content === 'string')
+            return message.content;
+        if (Array.isArray(message.content)) {
+            return message.content
+                .filter((part) => part.type === 'text')
+                .map((part) => part.text)
+                .join('\n');
+        }
+    }
+    return '';
+};
+const flattenToolCalls = (steps) => steps.flatMap((step) => step.toolCalls ?? []);
+/**
+ * Push a rewritten flat tool-call list back onto the steps it came from,
+ * preserving the step boundaries. A hook that adds or drops calls would make
+ * the boundaries meaningless, so a length change collapses them into the last
+ * step rather than silently mis-attributing calls to the wrong step.
+ */
+const distributeToolCalls = (steps, toolCalls) => {
+    if (toolCalls.length !== flattenToolCalls(steps).length) {
+        return steps.map((step, index) => ({
+            ...step,
+            toolCalls: index === steps.length - 1 ? toolCalls : [],
+        }));
+    }
+    let cursor = 0;
+    return steps.map((step) => {
+        if (!step.toolCalls)
+            return step;
+        const next = toolCalls.slice(cursor, cursor + step.toolCalls.length);
+        cursor += step.toolCalls.length;
+        return { ...step, toolCalls: next };
+    });
+};
+/**
+ * Run the `modifyOutput` chain over a finished non-streaming run.
+ *
+ * Reverse order, matching the input chain: the middleware registered first
+ * wraps the others, so it sees the output last.
+ */
+export const applyOutputMiddleware = async (agentMiddlewares, singletonServices, input) => {
+    let text = input.text;
+    let messages = input.messages;
+    let steps = input.steps;
+    let toolCalls = flattenToolCalls(steps);
+    for (let i = agentMiddlewares.length - 1; i >= 0; i--) {
+        const mw = agentMiddlewares[i];
+        if (!mw.modifyOutput)
+            continue;
+        const result = await mw.modifyOutput(singletonServices, {
+            text,
+            messages,
+            usage: {
+                inputTokens: input.usage.inputTokens,
+                outputTokens: input.usage.outputTokens,
+            },
+            toolCalls,
+        });
+        text = result.text;
+        messages = result.messages;
+        if (result.toolCalls) {
+            toolCalls = result.toolCalls;
+            steps = distributeToolCalls(steps, toolCalls);
+        }
+    }
+    return { text, messages, steps };
+};
+/**
+ * The one place a run ends successfully.
+ *
+ * Every path that completes a run — streamed, non-streamed, and resumed after a
+ * tool approval — goes through here, so that anything terminal is reachable
+ * from all of them and cannot be reordered by a middleware author. Nothing here
+ * may rewrite the run: by this point the output middleware has resolved and, on
+ * the streaming path, the client already has the reply.
+ */
+export const finalizeAgentRun = async (agentRunState, run) => {
+    await agentRunState.updateRun(run.runId, {
+        status: 'completed',
+        ...(run.usage.model
+            ? {
+                usage: {
+                    inputTokens: run.usage.inputTokens,
+                    outputTokens: run.usage.outputTokens,
+                    model: run.usage.model,
+                },
+            }
+            : {}),
+    });
+    // Read rather than `getSingletonServices()`: a process that never registered
+    // them grades nothing, which is not an error at the point a run has already
+    // succeeded.
+    const services = pikkuState(null, 'package', 'singletonServices');
+    if (!services)
+        return;
+    const snapshot = {
+        runId: run.runId,
+        agentName: run.agentName,
+        threadId: run.threadId,
+        ...(run.resourceId !== undefined ? { resourceId: run.resourceId } : {}),
+        input: run.input,
+        output: run.text,
+        toolCalls: run.steps.flatMap((step) => (step.toolCalls ?? []).map((call) => ({
+            name: call.name,
+            args: call.args,
+            result: call.result,
+            ...(call.error !== undefined ? { error: call.error } : {}),
+        }))),
+        usage: {
+            inputTokens: run.usage.inputTokens,
+            outputTokens: run.usage.outputTokens,
+            ...(run.usage.model !== undefined ? { model: run.usage.model } : {}),
+        },
+    };
+    // The same object a scenario grades, so an asserted score and a sampled one
+    // are the same measurement. A no-op unless a dev server turned retention on.
+    recordScoreSnapshot(snapshot);
+    // Best-effort and last: the client already has its answer, so a grading
+    // failure must not surface as a failed run.
+    try {
+        await scoreFinishedRun(snapshot, services);
+    }
+    catch (error) {
+        services.logger?.error(`[pikku] Live scoring failed for run ${run.runId}`, error);
+    }
+};

package/dist/wirings/agent/agent-helpers.d.ts

@@ -0,0 +1,35 @@
+import type { AgentInterruptResult } from './agent-interrupt.js';
+export declare function agent<TAgentMap extends Record<string, {
+    output: any;
+}>>(agentName: string & keyof TAgentMap): {
+    func: (services: any, data: any, wire: any) => Promise<any>;
+};
+export declare function agentStream<TAgentMap extends Record<string, {
+    output: any;
+}>>(agentName?: string & keyof TAgentMap): {
+    func: (services: any, data: any, wire: any) => Promise<void>;
+};
+export declare function agentResume(): {
+    func: (services: any, data: {
+        runId: string;
+        toolCallId: string;
+        approved: boolean;
+    }, wire: any) => Promise<void>;
+};
+export declare function agentInterrupt(): {
+    func: (services: any, data: {
+        runId: string;
+        reason?: 'speech' | 'user' | 'timeout';
+    }, wire: any) => Promise<AgentInterruptResult>;
+};
+export declare function agentApprove<TAgentMap extends Record<string, {
+    output: any;
+}>>(_agentName: string & keyof TAgentMap): {
+    func: (services: any, data: {
+        runId: string;
+        approvals: {
+            toolCallId: string;
+            approved: boolean;
+        }[];
+    }, wire: any) => Promise<any>;
+};

package/dist/wirings/agent/agent-helpers.js

@@ -0,0 +1,47 @@
+export function agent(agentName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.agent.run(agentName, data);
+        },
+    };
+}
+export function agentStream(agentName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            if (agentName) {
+                await rpc.agent.stream(agentName, data);
+            }
+            else {
+                const { agentName: name, ...rest } = data;
+                if (!name) {
+                    throw new Error('agentStream requires an agentName either as a parameter or in the input data');
+                }
+                await rpc.agent.stream(name, rest);
+            }
+        },
+    };
+}
+export function agentResume() {
+    return {
+        func: async (_services, data, { rpc }) => {
+            await rpc.agent.resume(data.runId, {
+                toolCallId: data.toolCallId,
+                approved: data.approved,
+            });
+        },
+    };
+}
+export function agentInterrupt() {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.agent.interrupt(data.runId, data.reason);
+        },
+    };
+}
+export function agentApprove(_agentName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.agent.approve(data.runId, data.approvals);
+        },
+    };
+}