@pikku/core 0.12.0 → 0.12.2

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

@@ -1,14 +1,19 @@
-import { pikkuState } from '../../pikku-state.js';
+import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { randomUUID } from 'crypto';
 import { parseWorkingMemory, deepMergeWorkingMemory, resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, ToolApprovalRequired, } from './ai-agent-prepare.js';
+import { createAssistantUIChannel, parseAssistantUIInput, } from './ai-agent-assistant-ui.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 function createPersistingChannel(parent, storage, threadId) {
     let fullText = '';
     let stepText = '';
     let stepToolCalls = [];
     let stepToolResults = [];
+    const totalUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+    };
     const flushStep = async () => {
         if (!storage)
             return;
@@ -47,8 +52,12 @@ function createPersistingChannel(parent, storage, threadId) {
         get fullText() {
             return fullText;
         },
+        get totalUsage() {
+            return totalUsage;
+        },
         flush: flushStep,
         close: () => parent.close(),
+        sendBinary: (data) => parent.sendBinary(data),
         send: (event) => {
             if (storage) {
                 switch (event.type) {
@@ -73,6 +82,10 @@ function createPersistingChannel(parent, storage, threadId) {
                         });
                         break;
                     case 'usage':
+                        totalUsage.inputTokens += event.tokens.input;
+                        totalUsage.outputTokens += event.tokens.output;
+                        if (event.model)
+                            totalUsage.model = event.model;
                         flushStep();
                         break;
                     case 'done':
@@ -86,6 +99,7 @@ function createPersistingChannel(parent, storage, threadId) {
     return channel;
 }
 async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, threadId, workingMemorySchemaName, messages, aiRunState, runId) {
+    const usage = persistingChannel.totalUsage;
     let outputText = persistingChannel.fullText;
     let outputMessages = messages;
     for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
@@ -94,7 +108,10 @@ async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServ
             const result = await mw.modifyOutput(singletonServices, {
                 text: outputText,
                 messages: outputMessages,
-                usage: { inputTokens: 0, outputTokens: 0 },
+                usage: {
+                    inputTokens: usage.inputTokens,
+                    outputTokens: usage.outputTokens,
+                },
             });
             outputText = result.text;
             outputMessages = result.messages;
@@ -116,13 +133,160 @@ async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServ
             await storage.saveWorkingMemory(threadId, 'thread', merged);
         }
     }
-    await aiRunState.updateRun(runId, { status: 'completed' });
+    await aiRunState.updateRun(runId, {
+        status: 'completed',
+        ...(usage.model
+            ? {
+                usage: {
+                    inputTokens: usage.inputTokens,
+                    outputTokens: usage.outputTokens,
+                    model: usage.model,
+                },
+            }
+            : {}),
+    });
+}
+async function runStreamStepLoop(params) {
+    const { agent, runnerParams, maxSteps, agentRunner, persistingChannel, channel, runId, aiMiddlewares, } = params;
+    const singletonServices = getSingletonServices();
+    for (let step = 0; step < maxSteps; step++) {
+        if (agent.prepareStep) {
+            let stopped = false;
+            await agent.prepareStep({
+                stepNumber: step,
+                messages: runnerParams.messages,
+                tools: runnerParams.tools,
+                toolChoice: runnerParams.toolChoice,
+                model: runnerParams.model,
+                stop: () => {
+                    stopped = true;
+                },
+            });
+            if (stopped)
+                break;
+        }
+        channel.send({ type: 'step-start', stepNumber: step });
+        const stepResult = await agentRunner.stream(runnerParams, persistingChannel);
+        for (const mw of aiMiddlewares) {
+            if (mw.afterStep) {
+                await mw.afterStep(singletonServices, {
+                    stepNumber: step,
+                    text: stepResult.text,
+                    toolCalls: stepResult.toolCalls,
+                    toolResults: stepResult.toolResults,
+                    usage: stepResult.usage,
+                    finishReason: stepResult.finishReason,
+                });
+            }
+        }
+        if (stepResult.toolCalls.length === 0)
+            break;
+        const approvalNeeded = checkForApproval(stepResult, runnerParams.tools, runId);
+        if (approvalNeeded) {
+            return { outcome: 'approval', approval: approvalNeeded };
+        }
+        appendStepMessages(runnerParams, stepResult);
+    }
+    return { outcome: 'done' };
+}
+function checkForApproval(stepResult, tools, runId) {
+    for (const tc of stepResult.toolCalls) {
+        const toolDef = tools.find((t) => t.name === tc.toolName);
+        if (toolDef?.needsApproval) {
+            return new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args);
+        }
+        const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
+        if (tr?.result &&
+            typeof tr.result === 'object' &&
+            '__approvalRequired' in tr.result) {
+            const r = tr.result;
+            return new ToolApprovalRequired(tc.toolCallId, r.toolName, r.args, r.reason, r.displayToolName, r.displayArgs, r.agentRunId);
+        }
+    }
+    return null;
+}
+function appendStepMessages(runnerParams, stepResult) {
+    const assistantMsg = {
+        id: randomUUID(),
+        role: 'assistant',
+        content: stepResult.text || undefined,
+        toolCalls: stepResult.toolCalls.length > 0
+            ? stepResult.toolCalls.map((tc) => ({
+                id: tc.toolCallId,
+                name: tc.toolName,
+                args: tc.args,
+            }))
+            : undefined,
+        createdAt: new Date(),
+    };
+    runnerParams.messages.push(assistantMsg);
+    if (stepResult.toolResults.length > 0) {
+        const toolMsg = {
+            id: randomUUID(),
+            role: 'tool',
+            toolResults: stepResult.toolResults.map((tr) => ({
+                id: tr.toolCallId,
+                name: tr.toolName,
+                result: typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result),
+            })),
+            createdAt: new Date(),
+        };
+        runnerParams.messages.push(toolMsg);
+    }
+}
+function handleApproval(err, runId, channel, aiRunState, persistingChannel) {
+    return (async () => {
+        await persistingChannel.flush();
+        const pendingApproval = err.agentRunId
+            ? {
+                type: 'agent-call',
+                toolCallId: err.toolCallId,
+                agentName: err.toolName,
+                agentRunId: err.agentRunId,
+                displayToolName: err.displayToolName ?? err.toolName,
+                displayArgs: err.displayArgs ?? err.args,
+            }
+            : {
+                type: 'tool-call',
+                toolCallId: err.toolCallId,
+                toolName: err.toolName,
+                args: err.args,
+            };
+        await aiRunState.updateRun(runId, {
+            status: 'suspended',
+            suspendReason: 'approval',
+            pendingApprovals: [pendingApproval],
+        });
+        const approvalEvent = {
+            type: 'approval-request',
+            toolCallId: err.toolCallId,
+            toolName: err.displayToolName ?? err.toolName,
+            args: err.displayArgs ?? err.args,
+            reason: err.reason,
+            runId,
+        };
+        channel.send(approvalEvent);
+        channel.send({ type: 'done' });
+        channel.close();
+    })();
 }
 export async function streamAIAgent(agentName, input, channel, params, agentSessionMap, options) {
     const sessionMap = agentSessionMap ?? new Map();
+    const { agent: resolvedAgentForProtocol } = resolveAgent(agentName);
+    const inputRecord = input;
+    const useUIMessageStream = resolvedAgentForProtocol.protocol === 'ui-message-stream' ||
+        Array.isArray(inputRecord.messages);
+    let normalizedInput;
+    if (useUIMessageStream) {
+        normalizedInput = parseAssistantUIInput(inputRecord);
+        channel = createAssistantUIChannel(channel);
+    }
+    else {
+        normalizedInput = input;
+    }
     const streamContext = { channel, options };
-    const { agent, packageName, resolvedName, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap, streamContext);
-    const { singletonServices } = params;
+    const { agent, packageName, resolvedName, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, normalizedInput, params, sessionMap, streamContext);
+    const singletonServices = getSingletonServices();
     const { aiRunState } = singletonServices;
     if (!aiRunState) {
         throw new Error('AIRunStateService not available in singletonServices');
@@ -131,7 +295,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         await aiRunState.createRun({
             agentName,
             threadId,
-            resourceId: input.resourceId,
+            resourceId: normalizedInput.resourceId,
             status: 'suspended',
             suspendReason: 'rpc-missing',
             missingRpcs,
@@ -161,7 +325,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     const runId = await aiRunState.createRun({
         agentName,
         threadId,
-        resourceId: input.resourceId,
+        resourceId: normalizedInput.resourceId,
         status: 'running',
         usage: { inputTokens: 0, outputTokens: 0, model: agent.model },
         createdAt: new Date(),
@@ -182,8 +346,15 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 allEvents,
                 state,
             });
-            if (result != null)
+            if (result == null)
+                return;
+            if (Array.isArray(result)) {
+                for (const r of result)
+                    await next(r);
+            }
+            else {
                 await next(result);
+            }
         };
     });
     const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
@@ -200,44 +371,38 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         : channel;
     const persistingChannel = createPersistingChannel(wrappedChannel, storage, threadId);
     try {
-        await agentRunner.stream(runnerParams, persistingChannel);
+        const loopResult = await runStreamStepLoop({
+            agent,
+            runnerParams,
+            maxSteps,
+            agentRunner,
+            persistingChannel,
+            channel,
+            runId,
+            aiMiddlewares,
+        });
+        if (loopResult.outcome === 'approval') {
+            await handleApproval(loopResult.approval, runId, channel, aiRunState, persistingChannel);
+            return;
+        }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, runId);
+        channel.send({ type: 'done' });
+        channel.close();
     }
     catch (err) {
-        if (err instanceof ToolApprovalRequired) {
-            await persistingChannel.flush();
-            const pendingApproval = err.agentRunId
-                ? {
-                    type: 'agent-call',
-                    toolCallId: err.toolCallId,
-                    agentName: err.toolName,
-                    agentRunId: err.agentRunId,
-                    displayToolName: err.displayToolName ?? err.toolName,
-                    displayArgs: err.displayArgs ?? err.args,
+        for (const mw of aiMiddlewares) {
+            if (mw.onError) {
+                try {
+                    await mw.onError(singletonServices, {
+                        error: err instanceof Error ? err : new Error(String(err)),
+                        stepNumber: -1,
+                        messages: runnerParams.messages,
+                    });
                 }
-                : {
-                    type: 'tool-call',
-                    toolCallId: err.toolCallId,
-                    toolName: err.toolName,
-                    args: err.args,
-                };
-            await aiRunState.updateRun(runId, {
-                status: 'suspended',
-                suspendReason: 'approval',
-                pendingApprovals: [pendingApproval],
-            });
-            const approvalEvent = {
-                type: 'approval-request',
-                toolCallId: err.toolCallId,
-                toolName: err.displayToolName ?? err.toolName,
-                args: err.displayArgs ?? err.args,
-                reason: err.reason,
-                runId,
-            };
-            channel.send(approvalEvent);
-            channel.send({ type: 'done' });
-            channel.close();
-            return;
+                catch {
+                    // onError hooks must not affect error flow
+                }
+            }
         }
         await aiRunState.updateRun(runId, { status: 'failed' });
         channel.send({
@@ -249,16 +414,19 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     }
 }
 export async function resumeAIAgent(input, channel, params, options) {
-    const { singletonServices } = params;
+    const singletonServices = getSingletonServices();
     const { aiRunState } = singletonServices;
     if (!aiRunState) {
         throw new Error('AIRunStateService not available in singletonServices');
     }
-    const found = await aiRunState.findRunByToolCallId(input.toolCallId);
-    if (!found) {
-        throw new Error(`No suspended run found for toolCallId ${input.toolCallId}`);
+    const run = await aiRunState.getRun(input.runId);
+    if (!run) {
+        throw new Error(`No run found for runId ${input.runId}`);
+    }
+    const pending = run.pendingApprovals?.find((p) => p.toolCallId === input.toolCallId);
+    if (!pending) {
+        throw new Error(`No pending approval for toolCallId ${input.toolCallId} on run ${input.runId}`);
     }
-    const { run, approval: pending } = found;
     await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
     const { storage } = resolveMemoryServices(agent, singletonServices);
@@ -310,7 +478,11 @@ export async function resumeAIAgent(input, channel, params, options) {
             session: 'resume',
             input: null,
         });
-        await resumeAIAgent({ toolCallId: subPending.toolCallId, approved: true }, subChannel, params, options);
+        await resumeAIAgent({
+            runId: pending.agentRunId,
+            toolCallId: subPending.toolCallId,
+            approved: true,
+        }, subChannel, params, options);
         channel.send({
             type: 'agent-result',
             agentName: subRun.agentName,
@@ -339,16 +511,16 @@ export async function resumeAIAgent(input, channel, params, options) {
             channel,
             options: { ...options, requiresToolApproval: false },
         };
-        const { tools } = buildToolDefs(singletonServices, params, new Map(), run.resourceId, resolvedName, packageName, streamContext);
+        const aiMiddlewaresForResume = agent.aiMiddleware ?? [];
+        const { tools } = buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, aiMiddlewaresForResume);
         const matchingTool = tools.find((t) => t.name === pending.toolName);
         if (!matchingTool) {
             throw new Error(`Tool "${pending.toolName}" not found in agent definition`);
         }
         const toolArgs = typeof pending.args === 'string' ? JSON.parse(pending.args) : pending.args;
-        const { toolApprovalReason: _ignored, ...cleanArgs } = toolArgs;
         let toolResult;
         try {
-            toolResult = await matchingTool.execute(cleanArgs);
+            toolResult = await matchingTool.execute(toolArgs);
         }
         catch (execErr) {
             toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`;
@@ -381,7 +553,7 @@ export async function resumeAIAgent(input, channel, params, options) {
     await continueAfterToolResult(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, channel, params, aiRunState, options);
 }
 async function continueAfterToolResult(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, channel, params, aiRunState, options) {
-    const { singletonServices } = params;
+    const singletonServices = getSingletonServices();
     const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
     const meta = agentsMeta[resolvedName];
     const workingMemorySchemaName = meta?.workingMemorySchema ?? null;
@@ -422,8 +594,15 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
                 allEvents,
                 state,
             });
-            if (result != null)
+            if (result == null)
+                return;
+            if (Array.isArray(result)) {
+                for (const r of result)
+                    await next(r);
+            }
+            else {
                 await next(result);
+            }
         };
     });
     const allChannelMiddleware = combineChannelMiddleware('agent', `stream:${run.agentName}`, {
@@ -438,59 +617,54 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         : channel;
     const persistingChannel = createPersistingChannel(wrappedChannel, storage, run.threadId);
     const streamContext = { channel, options };
-    const resumeTools = buildToolDefs(singletonServices, params, new Map(), run.resourceId, resolvedName, packageName, streamContext).tools;
+    const resumeTools = buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, aiMiddlewares).tools;
     const resolved = resolveModelConfig(resolvedName, agent);
+    const maxSteps = resolved.maxSteps ?? 10;
     const runnerParams = {
         model: resolved.model,
         temperature: resolved.temperature,
         instructions: modifiedInstructions,
         messages: modifiedMessages,
         tools: resumeTools,
-        maxSteps: resolved.maxSteps ?? 10,
+        maxSteps: 1,
         toolChoice: (agent.toolChoice ?? 'auto'),
         outputSchema: meta?.outputSchema
             ? pikkuState(packageName, 'misc', 'schemas').get(meta.outputSchema)
             : undefined,
     };
     try {
-        await agentRunner.stream(runnerParams, persistingChannel);
+        const loopResult = await runStreamStepLoop({
+            agent,
+            runnerParams,
+            maxSteps,
+            agentRunner,
+            persistingChannel,
+            channel,
+            runId: run.runId,
+            aiMiddlewares,
+        });
+        if (loopResult.outcome === 'approval') {
+            await handleApproval(loopResult.approval, run.runId, channel, aiRunState, persistingChannel);
+            return;
+        }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, run.threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, run.runId);
+        channel.send({ type: 'done' });
+        channel.close();
     }
     catch (err) {
-        if (err instanceof ToolApprovalRequired) {
-            await persistingChannel.flush();
-            const pendingApproval = err.agentRunId
-                ? {
-                    type: 'agent-call',
-                    toolCallId: err.toolCallId,
-                    agentName: err.toolName,
-                    agentRunId: err.agentRunId,
-                    displayToolName: err.displayToolName ?? err.toolName,
-                    displayArgs: err.displayArgs ?? err.args,
+        for (const mw of aiMiddlewares) {
+            if (mw.onError) {
+                try {
+                    await mw.onError(singletonServices, {
+                        error: err instanceof Error ? err : new Error(String(err)),
+                        stepNumber: -1,
+                        messages: runnerParams.messages,
+                    });
                 }
-                : {
-                    type: 'tool-call',
-                    toolCallId: err.toolCallId,
-                    toolName: err.toolName,
-                    args: err.args,
-                };
-            await aiRunState.updateRun(run.runId, {
-                status: 'suspended',
-                suspendReason: 'approval',
-                pendingApprovals: [pendingApproval],
-            });
-            const approvalEvent = {
-                type: 'approval-request',
-                toolCallId: err.toolCallId,
-                toolName: err.displayToolName ?? err.toolName,
-                args: err.displayArgs ?? err.args,
-                reason: err.reason,
-                runId: run.runId,
-            };
-            channel.send(approvalEvent);
-            channel.send({ type: 'done' });
-            channel.close();
-            return;
+                catch {
+                    // onError hooks must not affect error flow
+                }
+            }
         }
         await aiRunState.updateRun(run.runId, { status: 'failed' });
         channel.send({

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

@@ -1,5 +1,5 @@
-import { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
-import { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
 export interface AIThread {
@@ -10,6 +10,21 @@ export interface AIThread {
     createdAt: Date;
     updatedAt: Date;
 }
+export type AIContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data?: string;
+    url?: string;
+    mediaType?: string;
+} | {
+    type: 'file';
+    data?: string;
+    url?: string;
+    mediaType: string;
+    filename?: string;
+};
 export interface AIToolCall {
     id: string;
     name: string;
@@ -23,7 +38,7 @@ export interface AIToolResult {
 export interface AIMessage {
     id: string;
     role: 'system' | 'user' | 'assistant' | 'tool';
-    content?: string;
+    content?: string | AIContentPart[];
     toolCalls?: AIToolCall[];
     toolResults?: AIToolResult[];
     createdAt: Date;
@@ -39,10 +54,18 @@ export interface AIAgentStep {
         result: string;
     }[];
 }
+export interface AIAgentInputAttachment {
+    type: 'image' | 'file';
+    data?: string;
+    url?: string;
+    mediaType?: string;
+    filename?: string;
+}
 export interface AIAgentInput {
     message: string;
     threadId: string;
     resourceId: string;
+    attachments?: AIAgentInputAttachment[];
 }
 export interface AIAgentOutput {
     runId: string;
@@ -60,6 +83,7 @@ export interface AIAgentToolDef {
     description: string;
     inputSchema: Record<string, unknown>;
     execute: (input: unknown) => Promise<unknown>;
+    needsApproval?: boolean;
 }
 export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
     modifyInput?: (services: Services, ctx: {
@@ -76,7 +100,7 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
         event: AIStreamEvent;
         allEvents: readonly AIStreamEvent[];
         state: State;
-    }) => Promise<AIStreamEvent | null> | AIStreamEvent | null;
+    }) => Promise<AIStreamEvent | AIStreamEvent[] | null> | AIStreamEvent | AIStreamEvent[] | null;
     modifyOutput?: (services: Services, ctx: {
         text: string;
         messages: AIMessage[];
@@ -91,6 +115,50 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
         text: string;
         messages: AIMessage[];
     };
+    beforeToolCall?: (services: Services, ctx: {
+        toolName: string;
+        toolCallId: string;
+        args: Record<string, unknown>;
+    }) => Promise<{
+        args: Record<string, unknown>;
+    } | void> | {
+        args: Record<string, unknown>;
+    } | void;
+    afterToolCall?: (services: Services, ctx: {
+        toolName: string;
+        toolCallId: string;
+        args: Record<string, unknown>;
+        result: unknown;
+        durationMs: number;
+    }) => Promise<{
+        result: unknown;
+    } | void> | {
+        result: unknown;
+    } | void;
+    afterStep?: (services: Services, ctx: {
+        stepNumber: number;
+        text: string;
+        toolCalls: {
+            toolCallId: string;
+            toolName: string;
+            args: unknown;
+        }[];
+        toolResults: {
+            toolCallId: string;
+            toolName: string;
+            result: unknown;
+        }[];
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+        finishReason: string;
+    }) => Promise<void> | void;
+    onError?: (services: Services, ctx: {
+        error: Error;
+        stepNumber: number;
+        messages: AIMessage[];
+    }) => Promise<void> | void;
 }
 export type AIAgentMemoryConfig = {
     storage?: string;
@@ -115,12 +183,26 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     input?: unknown;
     output?: unknown;
     tags?: string[];
+    protocol?: 'ui-message-stream';
+    prepareStep?: (ctx: {
+        stepNumber: number;
+        messages: AIMessage[];
+        tools: AIAgentToolDef[];
+        toolChoice: 'auto' | 'required' | 'none';
+        model: string;
+        stop: () => void;
+    }) => void | Promise<void>;
     middleware?: PikkuMiddleware[];
     channelMiddleware?: CorePikkuChannelMiddleware<any, any>[];
     aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[];
     permissions?: CorePermissionGroup<PikkuPermission>;
 };
 export type AIStreamEvent = {
+    type: 'step-start';
+    stepNumber: number;
+    agent?: string;
+    session?: string;
+} | {
     type: 'text-delta';
     text: string;
     agent?: string;
@@ -176,6 +258,16 @@ export type AIStreamEvent = {
     message: string;
     agent?: string;
     session?: string;
+} | {
+    type: 'audio-delta';
+    data: string;
+    format: string;
+    agent?: string;
+    session?: string;
+} | {
+    type: 'audio-done';
+    agent?: string;
+    session?: string;
 } | {
     type: 'suspended';
     reason: 'rpc-missing';

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

@@ -1,5 +1,7 @@
+export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
 export { runAIAgent } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
+export { createAssistantUIChannel, parseAssistantUIInput, } from './ai-agent-assistant-ui.js';
 export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';
-export type { AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';
+export type { AIAgentInput, AIAgentInputAttachment, AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AIContentPart, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';