@pikku/core 0.12.1 → 0.12.3

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

@@ -3,7 +3,6 @@ import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel
 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 = '';
@@ -57,6 +56,7 @@ function createPersistingChannel(parent, storage, threadId) {
         },
         flush: flushStep,
         close: () => parent.close(),
+        sendBinary: (data) => parent.sendBinary(data),
         send: (event) => {
             if (storage) {
                 switch (event.type) {
@@ -180,31 +180,52 @@ async function runStreamStepLoop(params) {
         }
         if (stepResult.toolCalls.length === 0)
             break;
-        const approvalNeeded = checkForApproval(stepResult, runnerParams.tools, runId);
-        if (approvalNeeded) {
-            return { outcome: 'approval', approval: approvalNeeded };
+        const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools, runId);
+        if (approvalsNeeded.length > 0) {
+            // For each approval, call approvalDescriptionFn if available
+            for (const approval of approvalsNeeded) {
+                const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
+                if (toolDef?.approvalDescriptionFn && !approval.reason) {
+                    try {
+                        approval.reason = await toolDef.approvalDescriptionFn(approval.args);
+                    }
+                    catch {
+                        // If description generation fails, continue without it
+                    }
+                }
+            }
+            return { outcome: 'approval', approvals: approvalsNeeded };
         }
         appendStepMessages(runnerParams, stepResult);
     }
     return { outcome: 'done' };
 }
-function checkForApproval(stepResult, tools, runId) {
+export function checkForApprovals(stepResult, tools, runId) {
+    const approvals = [];
     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);
+            approvals.push(new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args));
+            continue;
         }
         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);
+            if (r.subApprovals?.length) {
+                for (const sub of r.subApprovals) {
+                    approvals.push(new ToolApprovalRequired(sub.toolCallId, r.toolName, r.args, undefined, sub.toolName, sub.args, r.agentRunId));
+                }
+            }
+            else {
+                approvals.push(new ToolApprovalRequired(tc.toolCallId, r.toolName, r.args, r.reason, r.displayToolName, r.displayArgs, r.agentRunId));
+            }
         }
     }
-    return null;
+    return approvals;
 }
-function appendStepMessages(runnerParams, stepResult) {
+export function appendStepMessages(runnerParams, stepResult) {
     const assistantMsg = {
         id: randomUUID(),
         role: 'assistant',
@@ -233,10 +254,10 @@ function appendStepMessages(runnerParams, stepResult) {
         runnerParams.messages.push(toolMsg);
     }
 }
-function handleApproval(err, runId, channel, aiRunState, persistingChannel) {
+function handleApprovals(approvals, runId, channel, aiRunState, persistingChannel) {
     return (async () => {
         await persistingChannel.flush();
-        const pendingApproval = err.agentRunId
+        const pendingApprovals = approvals.map((err) => err.agentRunId
             ? {
                 type: 'agent-call',
                 toolCallId: err.toolCallId,
@@ -250,40 +271,32 @@ function handleApproval(err, runId, channel, aiRunState, persistingChannel) {
                 toolCallId: err.toolCallId,
                 toolName: err.toolName,
                 args: err.args,
-            };
+            });
         await aiRunState.updateRun(runId, {
             status: 'suspended',
             suspendReason: 'approval',
-            pendingApprovals: [pendingApproval],
+            pendingApprovals,
         });
-        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);
+        for (const err of approvals) {
+            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 normalizedInput = input;
     const streamContext = { channel, options };
+    // delegateState is attached after prepareAgentRun resolves the agent config
     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;
@@ -304,7 +317,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         });
         channel.send({ type: 'suspended', reason: 'rpc-missing', missingRpcs });
         channel.send({ type: 'done' });
-        return;
+        return '';
     }
     const aiMiddlewares = agent.aiMiddleware ?? [];
     let modifiedMessages = runnerParams.messages;
@@ -345,8 +358,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');
@@ -361,7 +381,28 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel }, singletonServices, allChannelMiddleware).channel
         : channel;
-    const persistingChannel = createPersistingChannel(wrappedChannel, storage, threadId);
+    // In delegate mode (default), suppress parent's text from reaching the client
+    // AFTER a sub-agent has been called. If the parent responds directly (no delegation),
+    // its text goes through normally. Sub-agent text bypasses this path entirely
+    // (goes through subChannel → channel directly).
+    const isDelegateMode = agent.agentMode !== 'supervise' && meta.agents?.length;
+    const delegateState = { delegated: false };
+    if (isDelegateMode) {
+        streamContext.delegateState = delegateState;
+    }
+    const outputChannel = isDelegateMode
+        ? {
+            ...wrappedChannel,
+            send: (event) => {
+                if (delegateState.delegated &&
+                    (event.type === 'text-delta' || event.type === 'reasoning-delta'))
+                    return;
+                wrappedChannel.send(event);
+            },
+            delegateState,
+        }
+        : wrappedChannel;
+    const persistingChannel = createPersistingChannel(outputChannel, storage, threadId);
     try {
         const loopResult = await runStreamStepLoop({
             agent,
@@ -374,12 +415,13 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             aiMiddlewares,
         });
         if (loopResult.outcome === 'approval') {
-            await handleApproval(loopResult.approval, runId, channel, aiRunState, persistingChannel);
-            return;
+            await handleApprovals(loopResult.approvals, runId, channel, aiRunState, persistingChannel);
+            return persistingChannel.fullText;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, runId);
         channel.send({ type: 'done' });
         channel.close();
+        return persistingChannel.fullText;
     }
     catch (err) {
         for (const mw of aiMiddlewares) {
@@ -396,13 +438,17 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 }
             }
         }
-        await aiRunState.updateRun(runId, { status: 'failed' });
+        await aiRunState.updateRun(runId, {
+            status: 'failed',
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
         channel.send({
             type: 'error',
             message: err instanceof Error ? err.message : String(err),
         });
         channel.send({ type: 'done' });
         channel.close();
+        return persistingChannel.fullText;
     }
 }
 export async function resumeAIAgent(input, channel, params, options) {
@@ -431,7 +477,7 @@ export async function resumeAIAgent(input, channel, params, options) {
         if (pending.type === 'agent-call') {
             await aiRunState.updateRun(pending.agentRunId, { status: 'failed' });
         }
-        const denialResult = 'Tool call was not approved by the user';
+        const denialResult = 'The user explicitly declined this action. Inform them that it was declined and do not retry.';
         if (storage) {
             await storage.saveMessages(run.threadId, [
                 {
@@ -450,6 +496,15 @@ export async function resumeAIAgent(input, channel, params, options) {
                 },
             ]);
         }
+        // Check remaining pending approvals
+        const updatedRun = await aiRunState.getRun(run.runId);
+        const remaining = updatedRun?.pendingApprovals ?? [];
+        if (remaining.length > 0) {
+            // Still waiting for more approvals - don't continue step loop
+            channel.send({ type: 'done' });
+            channel.close();
+            return;
+        }
         await aiRunState.updateRun(run.runId, { status: 'running' });
         await continueAfterToolResult(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, channel, params, aiRunState, options);
         return;
@@ -459,7 +514,8 @@ export async function resumeAIAgent(input, channel, params, options) {
         if (!subRun) {
             throw new Error(`Sub-agent run not found: ${pending.agentRunId}`);
         }
-        const subPending = subRun.pendingApprovals?.[0];
+        const subPending = subRun.pendingApprovals?.find((p) => p.toolCallId === input.toolCallId) ??
+            subRun.pendingApprovals?.[0];
         if (!subPending) {
             throw new Error(`No pending approval on sub-agent run ${pending.agentRunId}`);
         }
@@ -504,18 +560,20 @@ export async function resumeAIAgent(input, channel, params, options) {
             options: { ...options, requiresToolApproval: false },
         };
         const aiMiddlewaresForResume = agent.aiMiddleware ?? [];
-        const { tools } = buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, aiMiddlewaresForResume);
+        const { tools } = await 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;
         let toolResult;
+        let isError = false;
         try {
             toolResult = await matchingTool.execute(toolArgs);
         }
         catch (execErr) {
             toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`;
+            isError = true;
         }
         const resultStr = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
         if (storage) {
@@ -539,8 +597,18 @@ export async function resumeAIAgent(input, channel, params, options) {
             toolCallId: input.toolCallId,
             toolName: pending.toolName,
             result: toolResult,
+            ...(isError ? { isError: true } : {}),
         });
     }
+    // Check remaining pending approvals after processing this one
+    const updatedRun = await aiRunState.getRun(run.runId);
+    const remaining = updatedRun?.pendingApprovals ?? [];
+    if (remaining.length > 0) {
+        // Still waiting for more approvals - don't continue step loop
+        channel.send({ type: 'done' });
+        channel.close();
+        return;
+    }
     await aiRunState.updateRun(run.runId, { status: 'running' });
     await continueAfterToolResult(run, agent, packageName, resolvedName, storage, memoryConfig, agentRunner, channel, params, aiRunState, options);
 }
@@ -560,7 +628,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     const contextMessages = await loadContextMessages(memoryConfig, storage, { message: '', threadId: run.threadId, resourceId: run.resourceId }, workingMemoryJsonSchema);
     const allMessages = [...contextMessages, ...messages];
     const trimmedMessages = trimMessages(allMessages);
-    const instructions = buildInstructions(resolvedName, packageName);
+    const instructions = await buildInstructions(resolvedName, packageName);
     const aiMiddlewares = agent.aiMiddleware ?? [];
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
@@ -586,8 +654,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}`, {
@@ -602,7 +677,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         : channel;
     const persistingChannel = createPersistingChannel(wrappedChannel, storage, run.threadId);
     const streamContext = { channel, options };
-    const resumeTools = buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, aiMiddlewares).tools;
+    const resumeTools = (await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, aiMiddlewares)).tools;
     const resolved = resolveModelConfig(resolvedName, agent);
     const maxSteps = resolved.maxSteps ?? 10;
     const runnerParams = {
@@ -629,7 +704,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             aiMiddlewares,
         });
         if (loopResult.outcome === 'approval') {
-            await handleApproval(loopResult.approval, run.runId, channel, aiRunState, persistingChannel);
+            await handleApprovals(loopResult.approvals, run.runId, channel, aiRunState, persistingChannel);
             return;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, run.threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, run.runId);
@@ -651,7 +726,10 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
                 }
             }
         }
-        await aiRunState.updateRun(run.runId, { status: 'failed' });
+        await aiRunState.updateRun(run.runId, {
+            status: 'failed',
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
         channel.send({
             type: 'error',
             message: err instanceof Error ? err.message : String(err),

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

@@ -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,20 @@ 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[];
+    model?: string;
+    temperature?: number;
 }
 export interface AIAgentOutput {
     runId: string;
@@ -54,6 +79,14 @@ export interface AIAgentOutput {
         inputTokens: number;
         outputTokens: number;
     };
+    status?: 'completed' | 'suspended';
+    pendingApprovals?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        reason?: string;
+        runId: string;
+    }>;
 }
 export interface AIAgentToolDef {
     name: string;
@@ -61,6 +94,7 @@ export interface AIAgentToolDef {
     inputSchema: Record<string, unknown>;
     execute: (input: unknown) => Promise<unknown>;
     needsApproval?: boolean;
+    approvalDescriptionFn?: (input: unknown) => Promise<string>;
 }
 export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
     modifyInput?: (services: Services, ctx: {
@@ -77,7 +111,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[];
@@ -154,13 +188,14 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     temperature?: number;
     tools?: unknown[];
     agents?: unknown[];
+    agentMode?: 'delegate' | 'supervise';
     memory?: AIAgentMemoryConfig;
     maxSteps?: number;
     toolChoice?: 'auto' | 'required' | 'none';
+    dynamicWorkflows?: 'read' | 'always' | 'ask';
     input?: unknown;
     output?: unknown;
     tags?: string[];
-    protocol?: 'ui-message-stream';
     prepareStep?: (ctx: {
         stepNumber: number;
         messages: AIMessage[];
@@ -235,6 +270,22 @@ 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: 'workflow-created';
+    workflowName: string;
+    graph: any;
+    agent?: string;
+    session?: string;
 } | {
     type: 'suspended';
     reason: 'rpc-missing';
@@ -263,6 +314,7 @@ export interface AgentRunState {
     threadId: string;
     resourceId: string;
     status: 'running' | 'suspended' | 'completed' | 'failed';
+    errorMessage?: string;
     suspendReason?: 'approval' | 'rpc-missing';
     missingRpcs?: string[];
     pendingApprovals?: PendingApproval[];
@@ -280,6 +332,7 @@ export interface AgentRunRow {
     threadId: string;
     resourceId: string;
     status: string;
+    errorMessage?: string;
     suspendReason?: string;
     missingRpcs?: string[];
     usageInputTokens: number;
@@ -310,4 +363,5 @@ export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' |
     channelMiddleware?: MiddlewareMetadata[];
     aiMiddleware?: MiddlewareMetadata[];
     permissions?: PermissionMetadata[];
+    dynamicWorkflows?: 'read' | 'always' | 'ask';
 }>;

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

@@ -1,7 +1,6 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
-export { runAIAgent } from './ai-agent-runner.js';
+export { runAIAgent, resumeAIAgentSync } 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 { AIAgentInput, 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';

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

@@ -1,6 +1,5 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
-export { runAIAgent } from './ai-agent-runner.js';
+export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { createAssistantUIChannel, parseAssistantUIInput, } from './ai-agent-assistant-ui.js';
 export { ToolApprovalRequired, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';

package/dist/wirings/channel/channel-handler.d.ts

@@ -1,4 +1,7 @@
 import type { CoreServices, CoreUserSession } from '../../types/core.types.js';
-import type { CoreChannel, PikkuChannelHandler } from './channel.types.js';
+import type { BinaryData, CoreChannel, PikkuChannelHandler } from './channel.types.js';
 import type { SessionService } from '../../services/user-session-service.js';
-export declare const processMessageHandlers: (services: CoreServices, channelConfig: CoreChannel<any, any>, channelHandler: PikkuChannelHandler, userSession?: SessionService<CoreUserSession>) => (rawData: any) => Promise<unknown>;
+export declare const processMessageHandlers: (services: CoreServices, channelConfig: CoreChannel<any, any>, channelHandler: PikkuChannelHandler, userSession?: SessionService<CoreUserSession>) => {
+    onMessage: (rawData: unknown) => Promise<unknown>;
+    onBinaryMessage: ((data: BinaryData) => Promise<BinaryData | void>) | undefined;
+};

package/dist/wirings/channel/channel-handler.js

@@ -48,7 +48,9 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;
         }
-        const { pikkuFuncId, middleware: routeInheritedMiddleware, permissions: inheritedPermissions, } = getRouteMeta(channelConfig.name, routingProperty, routerValue);
+        const routeMeta = getRouteMeta(channelConfig.name, routingProperty, routerValue);
+        const { packageName, middleware: routeInheritedMiddleware, permissions: inheritedPermissions, } = routeMeta;
+        const pikkuFuncId = routeMeta.pikkuFuncId;
         // Get wire middleware: channel-level middleware + message-specific middleware
         const channelWireMiddleware = channelConfig.middleware || [];
         // Check if onMessage is a wrapper object vs direct function config:
@@ -83,15 +85,17 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             wireChannelMiddleware: wireChannelMiddleware,
             inheritedPermissions,
             wirePermissions,
+            coerceDataFromSchema: true,
             tags: channelConfig.tags,
             sessionService: userSession,
             wire: {
                 channel: channelHandler.getChannel(),
                 ...(userSession && createMiddlewareSessionWireProps(userSession)),
             },
+            packageName,
         });
     };
-    return async (rawData) => {
+    const onMessage = async (rawData) => {
         let result;
         let processed = false;
         // Route-specific handling
@@ -134,4 +138,14 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
         }
         return result;
     };
+    const onBinaryMessage = channelConfig.onBinaryMessage
+        ? async (data) => {
+            if (!validateAuth(requiresSession, userSession?.get(), channelConfig)) {
+                logger.error(`Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for binary message`);
+                return;
+            }
+            return channelConfig.onBinaryMessage(services, data, channelHandler.getChannel());
+        }
+        : undefined;
+    return { onMessage, onBinaryMessage };
 };

package/dist/wirings/channel/channel-middleware-runner.js

@@ -68,6 +68,7 @@ export function wrapChannelWithMiddleware(wire, services, middlewares) {
         channel: {
             ...channel,
             send: ((data) => dispatch(0, data)),
+            sendBinary: channel.sendBinary,
         },
     };
 }

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

@@ -1,6 +1,6 @@
-import type { PikkuError } from '../../errors/error-handler.js';
 import type { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+export type BinaryData = ArrayBuffer | Uint8Array;
 export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (services: Services, event: Event, next: (event: Event | Event[] | null) => Promise<void> | void) => Promise<void> | void;
 export type CorePikkuChannelMiddlewareFactory<In = any, Services = any, Event = unknown> = (input: In) => CorePikkuChannelMiddleware<Services, Event>;
 import type { CorePermissionGroup, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
@@ -18,6 +18,7 @@ export type RunChannelParams<ChannelData> = {
 };
 export interface ChannelMessageMeta {
     pikkuFuncId: string;
+    packageName?: string;
     summary?: string;
     description?: string;
     errors?: string[];
@@ -36,6 +37,7 @@ export interface ChannelMeta {
     disconnect: ChannelMessageMeta | null;
     message: ChannelMessageMeta | null;
     messageWirings: Record<string, Record<string, ChannelMessageMeta>>;
+    binary?: boolean | null;
     summary?: string;
     description?: string;
     errors?: string[];
@@ -67,23 +69,21 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
     channelMiddleware?: Array<CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory>;
     permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: boolean;
-    docs?: Partial<{
-        description: string;
-        response: string;
-        errors: Array<typeof PikkuError>;
-        tags: string[];
-    }>;
+    binary?: boolean | null;
+    onBinaryMessage?: (services: any, data: BinaryData, channel: PikkuChannel<ChannelData, any>) => Promise<BinaryData | void> | BinaryData | void;
     tags?: string[];
 };
 export interface PikkuChannel<OpeningData, out Out> {
     channelId: string;
     openingData: OpeningData;
     send(data: Out, isBinary?: boolean): Promise<void> | void;
+    sendBinary(data: BinaryData): Promise<void> | void;
     close(): Promise<void> | void;
     state: 'initial' | 'open' | 'closed';
 }
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
     send(message: Out, isBinary?: boolean): Promise<void> | void;
+    sendBinary(data: BinaryData): Promise<void> | void;
     getChannel(): PikkuChannel<OpeningData, Out>;
 }
 export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (channelId: string, channelName: string, openingData: OpeningData) => PikkuChannelHandler<OpeningData, Out>;

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

@@ -6,5 +6,5 @@ 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 { ChannelsMeta, CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, ChannelMessageMeta, ChannelMeta, 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';