@pikku/core 0.12.1 → 0.12.3

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

@@ -1,8 +1,11 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { pikkuState, getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
-import { runPikkuFunc } from '../../function/function-runner.js';
+import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from 'crypto';
+import { streamAIAgent } from './ai-agent-stream.js';
+import { runAIAgent } from './ai-agent-runner.js';
+import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
+import { buildDynamicWorkflowInstructions, buildWorkflowTools } from './agent-dynamic-workflow.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 export class ToolApprovalRequired extends PikkuError {
@@ -33,7 +36,7 @@ export const resolveAgent = (agentName) => {
     if (colonIndex !== -1) {
         const namespace = agentName.substring(0, colonIndex);
         const localName = agentName.substring(colonIndex + 1);
-        const addons = pikkuState(null, 'rpc', 'addons');
+        const addons = pikkuState(null, 'addons', 'packages');
         const pkgConfig = addons.get(namespace);
         if (pkgConfig) {
             const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(localName);
@@ -48,41 +51,47 @@ export const resolveAgent = (agentName) => {
     }
     throw new Error(`AI agent not found: ${agentName}`);
 };
-export function buildInstructions(agentName, packageName) {
+export async function buildInstructions(agentName, packageName) {
     const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
-    const instructions = meta?.instructions ?? '';
-    const baseInstructions = Array.isArray(instructions)
-        ? instructions.join('\n')
-        : instructions;
-    return meta?.agents?.length
-        ? baseInstructions +
+    const rawInstructions = meta?.instructions ?? '';
+    let instructions = Array.isArray(rawInstructions)
+        ? rawInstructions.join('\n')
+        : rawInstructions;
+    if (meta?.agents?.length) {
+        instructions +=
             '\n\nWhen calling a sub-agent, provide a short session name that describes the task. ' +
-            'Use the same session name to continue a previous conversation with that agent. ' +
-            'Use a new session name for a new independent task.'
-        : baseInstructions;
+                'Use the same session name to continue a previous conversation with that agent. ' +
+                'Use a new session name for a new independent task. ' +
+                'When a request involves multiple actions for the same domain, combine them into a single sub-agent call rather than making separate calls.';
+    }
+    if (meta?.dynamicWorkflows && meta.tools?.length) {
+        instructions += buildDynamicWorkflowInstructions(meta.tools, meta.dynamicWorkflows);
+    }
+    return instructions;
 }
 export function createScopedChannel(parent, agentName, session) {
-    let capturedApproval = null;
+    const capturedApprovals = [];
     return {
         channelId: `${parent.channelId}:${agentName}:${session}`,
         openingData: parent.openingData,
         get state() {
             return parent.state;
         },
-        get approval() {
-            return capturedApproval;
+        get approvals() {
+            return capturedApprovals;
         },
         close: () => { },
+        sendBinary: (data) => parent.sendBinary(data),
         send: (event) => {
             if (event.type === 'done')
                 return;
             if (event.type === 'approval-request') {
-                capturedApproval = {
+                capturedApprovals.push({
                     toolCallId: event.toolCallId,
                     toolName: event.toolName,
                     args: event.args,
                     runId: event.runId,
-                };
+                });
                 return;
             }
             if (event.type === 'step-start' ||
@@ -91,7 +100,8 @@ export function createScopedChannel(parent, agentName, session) {
                 event.type === 'tool-call' ||
                 event.type === 'tool-result' ||
                 event.type === 'usage' ||
-                event.type === 'error') {
+                event.type === 'error' ||
+                event.type === 'workflow-created') {
                 parent.send({ ...event, agent: agentName, session });
             }
             else {
@@ -100,7 +110,7 @@ export function createScopedChannel(parent, agentName, session) {
         },
     };
 }
-export function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares) {
+export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode) {
     const singletonServices = getSingletonServices();
     const tools = [];
     const missingRpcs = [];
@@ -111,16 +121,34 @@ export function buildToolDefs(params, agentSessionMap, resourceId, agentName, pa
     const metaTools = meta.tools;
     const metaAgents = meta.agents;
     if (metaTools?.length) {
-        const functionMeta = pikkuState(null, 'function', 'meta');
-        const schemas = pikkuState(null, 'misc', 'schemas');
         for (const toolName of metaTools) {
-            const rpcMeta = pikkuState(null, 'rpc', 'meta');
-            const pikkuFuncId = rpcMeta[toolName];
-            if (!pikkuFuncId) {
+            let fnMeta;
+            let resolvedPkg = null;
+            let schemas;
+            const resolved = toolName.includes(':')
+                ? resolveNamespace(toolName)
+                : null;
+            let pikkuFuncId;
+            if (resolved) {
+                resolvedPkg = resolved.package;
+                pikkuFuncId = resolved.function;
+                fnMeta = pikkuState(resolvedPkg, 'function', 'meta')[pikkuFuncId];
+                schemas = pikkuState(resolvedPkg, 'misc', 'schemas');
+            }
+            else {
+                const rpcMeta = pikkuState(null, 'rpc', 'meta');
+                pikkuFuncId = rpcMeta[toolName];
+                if (!pikkuFuncId) {
+                    missingRpcs.push(toolName);
+                    continue;
+                }
+                fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
+                schemas = pikkuState(null, 'misc', 'schemas');
+            }
+            if (!fnMeta) {
                 missingRpcs.push(toolName);
                 continue;
             }
-            const fnMeta = functionMeta[pikkuFuncId];
             const inputSchemaName = fnMeta?.inputSchemaName;
             let inputSchema = inputSchemaName
                 ? schemas.get(inputSchemaName)
@@ -132,23 +160,38 @@ export function buildToolDefs(params, agentSessionMap, resourceId, agentName, pa
                 inputSchema = { type: 'object', properties: {} };
             }
             const needsApproval = approvalPolicy === 'all' ||
-                (approvalPolicy === 'explicit' && fnMeta?.requiresApproval);
+                (approvalPolicy === 'explicit' && fnMeta?.approvalRequired);
+            // Build approvalDescriptionFn if the function has an approvalDescription configured
+            let approvalDescriptionFn;
+            if (needsApproval && pikkuFuncId) {
+                const funcConfig = pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId);
+                if (funcConfig?.approvalDescription) {
+                    const descFn = funcConfig.approvalDescription;
+                    const capturedPkg = resolvedPkg;
+                    approvalDescriptionFn = async (input) => {
+                        let services = singletonServices;
+                        if (capturedPkg) {
+                            const pkgServices = pikkuState(capturedPkg, 'package', 'singletonServices');
+                            if (pkgServices) {
+                                services = pkgServices;
+                            }
+                        }
+                        return descFn(services, input);
+                    };
+                }
+            }
             tools.push({
-                name: pikkuFuncId,
+                name: toolName.replaceAll(':', '__'),
                 description: fnMeta?.description || fnMeta?.title || toolName,
                 inputSchema,
                 needsApproval: needsApproval || undefined,
+                approvalDescriptionFn,
                 execute: async (toolInput) => {
                     const wire = params.sessionService
                         ? { ...createMiddlewareSessionWireProps(params.sessionService) }
                         : {};
-                    return runPikkuFunc('agent', `tool:${pikkuFuncId}`, pikkuFuncId, {
-                        singletonServices,
-                        createWireServices: getCreateWireServices(),
-                        data: () => toolInput,
-                        wire,
-                        sessionService: params.sessionService,
-                    });
+                    const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
+                    return rpcService.rpc(toolName, toolInput);
                 },
             });
         }
@@ -180,11 +223,14 @@ export function buildToolDefs(params, agentSessionMap, resourceId, agentName, pa
                     const sessionKey = `${subAgentName}::${session}`;
                     let threadId = agentSessionMap.get(sessionKey);
                     if (!threadId) {
-                        threadId = `${subAgentName}-${session}-${Date.now()}`;
+                        threadId = randomUUID();
                         agentSessionMap.set(sessionKey, threadId);
                     }
                     if (streamContext) {
-                        const { streamAIAgent } = await import('./ai-agent-stream.js');
+                        const isDelegate = agentMode !== 'supervise';
+                        if (isDelegate && streamContext.delegateState) {
+                            streamContext.delegateState.delegated = true;
+                        }
                         const { channel } = streamContext;
                         channel.send({
                             type: 'agent-call',
@@ -193,32 +239,48 @@ export function buildToolDefs(params, agentSessionMap, resourceId, agentName, pa
                             input: message,
                         });
                         const subChannel = createScopedChannel(channel, subAgentName, session);
-                        await streamAIAgent(subAgentName, { message, threadId, resourceId }, subChannel, params, agentSessionMap, streamContext.options);
-                        if (subChannel.approval) {
+                        // In supervise mode, suppress sub-agent text from reaching the client.
+                        // Approvals still flow through normally.
+                        const effectiveChannel = isDelegate
+                            ? subChannel
+                            : {
+                                ...subChannel,
+                                send: (event) => {
+                                    if (event.type === 'text-delta' ||
+                                        event.type === 'reasoning-delta')
+                                        return;
+                                    subChannel.send(event);
+                                },
+                            };
+                        const resultText = await streamAIAgent(subAgentName, { message, threadId, resourceId }, effectiveChannel, params, agentSessionMap, streamContext.options);
+                        if (subChannel.approvals.length > 0) {
                             return {
                                 __approvalRequired: true,
                                 toolName: subAgentName,
                                 args: toolInput,
-                                displayToolName: subChannel.approval.toolName,
-                                displayArgs: subChannel.approval.args,
-                                agentRunId: subChannel.approval.runId,
+                                agentRunId: subChannel.approvals[0].runId,
+                                subApprovals: subChannel.approvals,
                             };
                         }
                         channel.send({
                             type: 'agent-result',
                             agentName: subAgentName,
                             session,
-                            result: null,
+                            result: resultText,
                         });
-                        return null;
+                        return resultText;
                     }
-                    const { runAIAgent } = await import('./ai-agent-runner.js');
+                    // No stream context: sub-agent runs non-streaming
                     const result = await runAIAgent(subAgentName, { message, threadId, resourceId }, params, agentSessionMap);
                     return result.object ?? result.text;
                 },
             });
         }
     }
+    if (meta.dynamicWorkflows) {
+        const workflowTools = buildWorkflowTools(agentName, packageName, meta.tools ?? [], meta.dynamicWorkflows, streamContext, params.sessionService);
+        tools.push(...workflowTools);
+    }
     const hasToolHooks = aiMiddlewares?.some((mw) => mw.beforeToolCall || mw.afterToolCall);
     if (hasToolHooks) {
         for (const tool of tools) {
@@ -279,6 +341,15 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     if (!agentRunner) {
         throw new Error('AIAgentRunnerService not available in singletonServices');
     }
+    if (agent.dynamicWorkflows && singletonServices.workflowService) {
+        const persisted = await singletonServices.workflowService.getAIGeneratedWorkflows(resolvedName);
+        const allMeta = pikkuState(null, 'workflows', 'meta');
+        for (const wf of persisted) {
+            if (!allMeta[wf.workflowName]) {
+                allMeta[wf.workflowName] = wf.graph;
+            }
+        }
+    }
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const threadId = input.threadId;
@@ -307,18 +378,40 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
         });
     }
     const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
+    const userContent = input.attachments?.length
+        ? [
+            { type: 'text', text: input.message },
+            ...input.attachments.map((a) => ({
+                type: a.type,
+                data: a.data,
+                url: a.url,
+                mediaType: a.mediaType,
+                ...(a.filename ? { filename: a.filename } : {}),
+            })),
+        ]
+        : input.message;
     const userMessage = {
         id: randomUUID(),
         role: 'user',
-        content: input.message,
+        content: userContent,
         createdAt: new Date(),
     };
     const allMessages = [...contextMessages, ...messages, userMessage];
     const trimmedMessages = trimMessages(allMessages);
     const aiMiddlewares = agent.aiMiddleware ?? [];
-    const { tools, missingRpcs } = buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares);
-    const instructions = buildInstructions(resolvedName, packageName);
+    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode);
+    const instructions = await buildInstructions(resolvedName, packageName);
     const resolved = resolveModelConfig(resolvedName, agent);
+    // Per-request overrides
+    if (input.model) {
+        resolved.model = resolveModelConfig(resolvedName, {
+            ...agent,
+            model: input.model,
+        }).model;
+    }
+    if (input.temperature !== undefined) {
+        resolved.temperature = input.temperature;
+    }
     const maxSteps = resolved.maxSteps ?? 10;
     const runnerParams = {
         model: resolved.model,

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

@@ -1,3 +1,7 @@
 import type { AIAgentInput, AIAgentOutput } from './ai-agent.types.js';
 import { type RunAIAgentParams } from './ai-agent-prepare.js';
 export declare function runAIAgent(agentName: string, input: AIAgentInput, params: RunAIAgentParams, agentSessionMap?: Map<string, string>): Promise<AIAgentOutput>;
+export declare function resumeAIAgentSync(runId: string, approvals: {
+    toolCallId: string;
+    approved: boolean;
+}[], params: RunAIAgentParams, expectedAgentName?: string): Promise<AIAgentOutput>;