@pikku/core 0.11.1 → 0.12.0

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

@@ -0,0 +1,312 @@
+import { PikkuError } from '../../errors/error-handler.js';
+import { pikkuState } from '../../pikku-state.js';
+import { runPikkuFunc } from '../../function/function-runner.js';
+import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
+import { randomUUID } from 'crypto';
+import { resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
+import { resolveModelConfig } from './ai-agent-model-config.js';
+export class ToolApprovalRequired extends PikkuError {
+    toolCallId;
+    toolName;
+    args;
+    reason;
+    displayToolName;
+    displayArgs;
+    agentRunId;
+    constructor(toolCallId, toolName, args, reason, displayToolName, displayArgs, agentRunId) {
+        super(`Tool '${displayToolName ?? toolName}' requires approval`);
+        this.toolCallId = toolCallId;
+        this.toolName = toolName;
+        this.args = args;
+        this.reason = reason;
+        this.displayToolName = displayToolName;
+        this.displayArgs = displayArgs;
+        this.agentRunId = agentRunId;
+    }
+}
+export const resolveAgent = (agentName) => {
+    const mainAgent = pikkuState(null, 'agent', 'agents').get(agentName);
+    if (mainAgent) {
+        return { agent: mainAgent, packageName: null, resolvedName: agentName };
+    }
+    const colonIndex = agentName.indexOf(':');
+    if (colonIndex !== -1) {
+        const namespace = agentName.substring(0, colonIndex);
+        const localName = agentName.substring(colonIndex + 1);
+        const externalPackages = pikkuState(null, 'rpc', 'externalPackages');
+        const pkgConfig = externalPackages.get(namespace);
+        if (pkgConfig) {
+            const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(localName);
+            if (extAgent) {
+                return {
+                    agent: extAgent,
+                    packageName: pkgConfig.package,
+                    resolvedName: localName,
+                };
+            }
+        }
+    }
+    throw new Error(`AI agent not found: ${agentName}`);
+};
+export 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 +
+            '\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;
+}
+export function createScopedChannel(parent, agentName, session) {
+    let capturedApproval = null;
+    return {
+        channelId: `${parent.channelId}:${agentName}:${session}`,
+        openingData: parent.openingData,
+        get state() {
+            return parent.state;
+        },
+        get approval() {
+            return capturedApproval;
+        },
+        close: () => { },
+        send: (event) => {
+            if (event.type === 'done')
+                return;
+            if (event.type === 'approval-request') {
+                capturedApproval = {
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    args: event.args,
+                    runId: event.runId,
+                };
+                return;
+            }
+            if (event.type === 'text-delta' ||
+                event.type === 'reasoning-delta' ||
+                event.type === 'tool-call' ||
+                event.type === 'tool-result' ||
+                event.type === 'usage' ||
+                event.type === 'error') {
+                parent.send({ ...event, agent: agentName, session });
+            }
+            else {
+                parent.send(event);
+            }
+        },
+    };
+}
+export function buildToolDefs(singletonServices, params, agentSessionMap, resourceId, agentName, packageName, streamContext) {
+    const tools = [];
+    const missingRpcs = [];
+    const approvalPolicy = streamContext?.options?.requiresToolApproval ?? 'explicit';
+    const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
+    if (!meta)
+        return { tools, missingRpcs };
+    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) {
+                missingRpcs.push(toolName);
+                continue;
+            }
+            const fnMeta = functionMeta[pikkuFuncId];
+            const inputSchemaName = fnMeta?.inputSchemaName;
+            let inputSchema = inputSchemaName
+                ? schemas.get(inputSchemaName)
+                : undefined;
+            if (!inputSchema ||
+                (typeof inputSchema === 'object' &&
+                    inputSchema.type === 'object' &&
+                    !inputSchema.properties)) {
+                inputSchema = { type: 'object', properties: {} };
+            }
+            const needsApproval = approvalPolicy === 'all' ||
+                (approvalPolicy === 'explicit' && fnMeta?.requiresApproval);
+            if (needsApproval) {
+                inputSchema = {
+                    ...inputSchema,
+                    properties: {
+                        ...(inputSchema.properties || {}),
+                        toolApprovalReason: {
+                            type: 'string',
+                            description: 'Brief explanation of why this action is needed',
+                        },
+                    },
+                };
+            }
+            tools.push({
+                name: pikkuFuncId,
+                description: fnMeta?.description || fnMeta?.title || toolName,
+                inputSchema,
+                execute: async (toolInput) => {
+                    if (needsApproval) {
+                        const { toolApprovalReason, ...cleanArgs } = toolInput;
+                        return {
+                            __approvalRequired: true,
+                            toolName: pikkuFuncId,
+                            args: cleanArgs,
+                            reason: toolApprovalReason,
+                        };
+                    }
+                    const wire = params.sessionService
+                        ? { ...createMiddlewareSessionWireProps(params.sessionService) }
+                        : {};
+                    return runPikkuFunc('agent', `tool:${pikkuFuncId}`, pikkuFuncId, {
+                        singletonServices,
+                        createWireServices: params.createWireServices,
+                        data: () => toolInput,
+                        wire,
+                        sessionService: params.sessionService,
+                    });
+                },
+            });
+        }
+    }
+    if (metaAgents?.length) {
+        const allAgentsMeta = pikkuState(null, 'agent', 'agentsMeta');
+        for (const subAgentName of metaAgents) {
+            const subMeta = allAgentsMeta[subAgentName];
+            if (!subMeta) {
+                singletonServices.logger.warn(`Sub-agent '${subAgentName}' not found in agent registry`);
+                continue;
+            }
+            tools.push({
+                name: subAgentName,
+                description: subMeta.description,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        message: { type: 'string' },
+                        session: {
+                            type: 'string',
+                            description: 'Short session label for thread continuity',
+                        },
+                    },
+                    required: ['message', 'session'],
+                },
+                execute: async (toolInput) => {
+                    const { message, session } = toolInput;
+                    const sessionKey = `${subAgentName}::${session}`;
+                    let threadId = agentSessionMap.get(sessionKey);
+                    if (!threadId) {
+                        threadId = `${subAgentName}-${session}-${Date.now()}`;
+                        agentSessionMap.set(sessionKey, threadId);
+                    }
+                    if (streamContext) {
+                        const { streamAIAgent } = await import('./ai-agent-stream.js');
+                        const { channel } = streamContext;
+                        channel.send({
+                            type: 'agent-call',
+                            agentName: subAgentName,
+                            session,
+                            input: message,
+                        });
+                        const subChannel = createScopedChannel(channel, subAgentName, session);
+                        await streamAIAgent(subAgentName, { message, threadId, resourceId }, subChannel, params, agentSessionMap, streamContext.options);
+                        if (subChannel.approval) {
+                            return {
+                                __approvalRequired: true,
+                                toolName: subAgentName,
+                                args: toolInput,
+                                displayToolName: subChannel.approval.toolName,
+                                displayArgs: subChannel.approval.args,
+                                agentRunId: subChannel.approval.runId,
+                            };
+                        }
+                        channel.send({
+                            type: 'agent-result',
+                            agentName: subAgentName,
+                            session,
+                            result: null,
+                        });
+                        return null;
+                    }
+                    const { runAIAgent } = await import('./ai-agent-runner.js');
+                    const result = await runAIAgent(subAgentName, { message, threadId, resourceId }, params, agentSessionMap);
+                    return result.object ?? result.text;
+                },
+            });
+        }
+    }
+    return { tools, missingRpcs };
+}
+export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
+    const { singletonServices } = params;
+    const { agent, packageName, resolvedName } = resolveAgent(agentName);
+    const agentRunner = singletonServices.aiAgentRunner;
+    if (!agentRunner) {
+        throw new Error('AIAgentRunnerService not available in singletonServices');
+    }
+    const { storage } = resolveMemoryServices(agent, singletonServices);
+    const memoryConfig = agent.memory;
+    const threadId = input.threadId;
+    const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
+    const meta = agentsMeta[resolvedName];
+    const outputSchemaName = meta?.outputSchema;
+    const outputSchema = outputSchemaName
+        ? pikkuState(packageName, 'misc', 'schemas').get(outputSchemaName)
+        : undefined;
+    const workingMemorySchemaName = meta?.workingMemorySchema ?? null;
+    const workingMemoryJsonSchema = workingMemorySchemaName
+        ? pikkuState(packageName, 'misc', 'schemas').get(workingMemorySchemaName)
+        : undefined;
+    if (storage) {
+        try {
+            await storage.getThread(threadId);
+        }
+        catch {
+            await storage.createThread(input.resourceId, { threadId });
+        }
+    }
+    let messages = [];
+    if (storage) {
+        messages = await storage.getMessages(threadId, {
+            lastN: memoryConfig?.lastMessages ?? 20,
+        });
+    }
+    const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
+    const userMessage = {
+        id: randomUUID(),
+        role: 'user',
+        content: input.message,
+        createdAt: new Date(),
+    };
+    const allMessages = [...contextMessages, ...messages, userMessage];
+    const trimmedMessages = trimMessages(allMessages);
+    const { tools, missingRpcs } = buildToolDefs(singletonServices, params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext);
+    const instructions = buildInstructions(resolvedName, packageName);
+    const resolved = resolveModelConfig(resolvedName, agent);
+    const runnerParams = {
+        model: resolved.model,
+        temperature: resolved.temperature,
+        instructions,
+        messages: trimmedMessages,
+        tools,
+        maxSteps: resolved.maxSteps ?? 10,
+        toolChoice: agent.toolChoice ?? 'auto',
+        outputSchema,
+    };
+    return {
+        agent,
+        packageName,
+        resolvedName,
+        agentRunner,
+        storage,
+        memoryConfig,
+        threadId,
+        userMessage,
+        runnerParams,
+        missingRpcs,
+        workingMemoryJsonSchema,
+        workingMemorySchemaName,
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { CoreAIAgent } from './ai-agent.types.js';
+import { AIRunStateService } from '../../services/ai-run-state-service.js';
+export declare const addAIAgent: (agentName: string, agent: CoreAIAgent<any, any>, packageName?: string | null) => void;
+export declare function approveAIAgent(aiRunState: AIRunStateService, runId: string, approvals: {
+    toolCallId: string;
+    approved: boolean;
+}[], expectedAgentName?: string): Promise<{
+    status: 'resumed' | 'suspended';
+    runId: string;
+    approved: string[];
+    rejected: string[];
+    remainingApprovals: number;
+}>;
+export declare const getAIAgents: () => Map<string, CoreAIAgent>;
+export declare const getAIAgentsMeta: () => import("./ai-agent.types.js").AIAgentMeta;

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

@@ -0,0 +1,47 @@
+import { pikkuState } from '../../pikku-state.js';
+import { PikkuMissingMetaError } from '../../errors/errors.js';
+export const addAIAgent = (agentName, agent, packageName = null) => {
+    const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
+    const agentMeta = agentsMeta[agentName];
+    if (!agentMeta) {
+        throw new PikkuMissingMetaError(`Missing generated metadata for AI agent '${agentName}'`);
+    }
+    const agents = pikkuState(packageName, 'agent', 'agents');
+    if (agents.has(agentName)) {
+        throw new Error(`AI agent already exists: ${agentName}`);
+    }
+    agents.set(agentName, agent);
+};
+export async function approveAIAgent(aiRunState, runId, approvals, expectedAgentName) {
+    if (!aiRunState)
+        throw new Error('AIRunStateService not available');
+    const run = await aiRunState.getRun(runId);
+    if (!run)
+        throw new Error('Run not found: ' + runId);
+    if (expectedAgentName && run.agentName !== expectedAgentName) {
+        throw new Error(`Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
+    }
+    if (run.status !== 'suspended')
+        throw new Error('Run is not suspended: ' + run.status);
+    const approvedIds = new Set(approvals.filter((a) => a.approved).map((a) => a.toolCallId));
+    const rejectedIds = new Set(approvals.filter((a) => !a.approved).map((a) => a.toolCallId));
+    const remaining = (run.pendingApprovals ?? []).filter((p) => !approvedIds.has(p.toolCallId) && !rejectedIds.has(p.toolCallId));
+    const hasApproved = approvedIds.size > 0;
+    await aiRunState.updateRun(runId, {
+        status: hasApproved ? 'running' : 'suspended',
+        pendingApprovals: remaining.length > 0 ? remaining : undefined,
+    });
+    return {
+        status: hasApproved ? 'resumed' : 'suspended',
+        runId,
+        approved: [...approvedIds],
+        rejected: [...rejectedIds],
+        remainingApprovals: remaining.length,
+    };
+}
+export const getAIAgents = () => {
+    return pikkuState(null, 'agent', 'agents');
+};
+export const getAIAgentsMeta = () => {
+    return pikkuState(null, 'agent', 'agentsMeta');
+};

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

@@ -0,0 +1,3 @@
+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>;

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

@@ -0,0 +1,96 @@
+import { saveMessages } from './ai-agent-memory.js';
+import { prepareAgentRun } from './ai-agent-prepare.js';
+export async function runAIAgent(agentName, input, params, agentSessionMap) {
+    const sessionMap = agentSessionMap ?? new Map();
+    const { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, missingRpcs, workingMemoryJsonSchema, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
+    const { singletonServices } = params;
+    const { aiRunState } = singletonServices;
+    if (!aiRunState) {
+        throw new Error('AIRunStateService not available in singletonServices');
+    }
+    if (missingRpcs.length > 0) {
+        const runId = await aiRunState.createRun({
+            agentName,
+            threadId,
+            resourceId: input.resourceId,
+            status: 'suspended',
+            suspendReason: 'rpc-missing',
+            missingRpcs,
+            usage: { inputTokens: 0, outputTokens: 0, model: agent.model },
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        });
+        return {
+            runId,
+            text: '',
+            threadId,
+            steps: [],
+            usage: { inputTokens: 0, outputTokens: 0 },
+        };
+    }
+    const aiMiddlewares = agent.aiMiddleware ?? [];
+    let modifiedMessages = runnerParams.messages;
+    let modifiedInstructions = runnerParams.instructions;
+    for (const mw of aiMiddlewares) {
+        if (mw.modifyInput) {
+            const result = await mw.modifyInput(singletonServices, {
+                messages: modifiedMessages,
+                instructions: modifiedInstructions,
+            });
+            modifiedMessages = result.messages;
+            modifiedInstructions = result.instructions;
+        }
+    }
+    runnerParams.messages = modifiedMessages;
+    runnerParams.instructions = modifiedInstructions;
+    const runId = await aiRunState.createRun({
+        agentName,
+        threadId,
+        resourceId: input.resourceId,
+        status: 'running',
+        usage: { inputTokens: 0, outputTokens: 0, model: agent.model },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+    });
+    try {
+        const result = await agentRunner.run(runnerParams);
+        const responseText = await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, result, {
+            workingMemoryJsonSchema,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        });
+        let outputText = responseText;
+        let outputMessages = runnerParams.messages;
+        for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
+            const mw = aiMiddlewares[i];
+            if (mw.modifyOutput) {
+                const modResult = await mw.modifyOutput(singletonServices, {
+                    text: outputText,
+                    messages: outputMessages,
+                    usage: result.usage,
+                });
+                outputText = modResult.text;
+                outputMessages = modResult.messages;
+            }
+        }
+        await aiRunState.updateRun(runId, {
+            status: 'completed',
+            usage: { ...result.usage, model: agent.model },
+        });
+        return {
+            runId,
+            text: outputText,
+            object: result.object,
+            threadId,
+            steps: result.steps,
+            usage: result.usage,
+        };
+    }
+    catch (error) {
+        await aiRunState.updateRun(runId, {
+            status: 'failed',
+        });
+        throw error;
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { AIStreamChannel } from './ai-agent.types.js';
+import { type RunAIAgentParams, type StreamAIAgentOptions } from './ai-agent-prepare.js';
+export declare function streamAIAgent(agentName: string, input: {
+    message: string;
+    threadId: string;
+    resourceId: string;
+}, channel: AIStreamChannel, params: RunAIAgentParams, agentSessionMap?: Map<string, string>, options?: StreamAIAgentOptions): Promise<void>;
+export declare function resumeAIAgent(input: {
+    toolCallId: string;
+    approved: boolean;
+}, channel: AIStreamChannel, params: RunAIAgentParams, options?: StreamAIAgentOptions): Promise<void>;