@pikku/core 0.11.2 → 0.12.1

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

@@ -0,0 +1,348 @@
+import { PikkuError } from '../../errors/error-handler.js';
+import { pikkuState, getSingletonServices, getCreateWireServices, } 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 addons = pikkuState(null, 'rpc', 'addons');
+        const pkgConfig = addons.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 === 'step-start' ||
+                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(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares) {
+    const singletonServices = getSingletonServices();
+    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);
+            tools.push({
+                name: pikkuFuncId,
+                description: fnMeta?.description || fnMeta?.title || toolName,
+                inputSchema,
+                needsApproval: needsApproval || undefined,
+                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,
+                    });
+                },
+            });
+        }
+    }
+    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;
+                },
+            });
+        }
+    }
+    const hasToolHooks = aiMiddlewares?.some((mw) => mw.beforeToolCall || mw.afterToolCall);
+    if (hasToolHooks) {
+        for (const tool of tools) {
+            const originalExecute = tool.execute;
+            tool.execute = async (toolInput) => {
+                const toolCallId = randomUUID();
+                let args = (toolInput ?? {});
+                for (const mw of aiMiddlewares) {
+                    if (mw.beforeToolCall) {
+                        const beforeResult = await mw.beforeToolCall(singletonServices, {
+                            toolName: tool.name,
+                            toolCallId,
+                            args,
+                        });
+                        if (beforeResult && 'args' in beforeResult) {
+                            args = beforeResult.args;
+                        }
+                    }
+                }
+                const startTime = Date.now();
+                let result;
+                let execError;
+                try {
+                    result = await originalExecute(args);
+                }
+                catch (err) {
+                    execError = err;
+                    result = err instanceof Error ? err.message : String(err);
+                }
+                const durationMs = Date.now() - startTime;
+                for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
+                    const mw = aiMiddlewares[i];
+                    if (mw.afterToolCall) {
+                        const afterResult = await mw.afterToolCall(singletonServices, {
+                            toolName: tool.name,
+                            toolCallId,
+                            args,
+                            result,
+                            durationMs,
+                        });
+                        if (afterResult && 'result' in afterResult) {
+                            result = afterResult.result;
+                        }
+                    }
+                }
+                if (execError)
+                    throw execError;
+                return result;
+            };
+        }
+    }
+    return { tools, missingRpcs };
+}
+export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
+    const singletonServices = getSingletonServices();
+    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 aiMiddlewares = agent.aiMiddleware ?? [];
+    const { tools, missingRpcs } = buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares);
+    const instructions = buildInstructions(resolvedName, packageName);
+    const resolved = resolveModelConfig(resolvedName, agent);
+    const maxSteps = resolved.maxSteps ?? 10;
+    const runnerParams = {
+        model: resolved.model,
+        temperature: resolved.temperature,
+        instructions,
+        messages: trimmedMessages,
+        tools,
+        maxSteps: 1,
+        toolChoice: agent.toolChoice ?? 'auto',
+        outputSchema,
+    };
+    return {
+        agent,
+        packageName,
+        resolvedName,
+        agentRunner,
+        storage,
+        memoryConfig,
+        threadId,
+        userMessage,
+        runnerParams,
+        maxSteps,
+        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 type { 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,195 @@
+import { saveMessages } from './ai-agent-memory.js';
+import { prepareAgentRun } from './ai-agent-prepare.js';
+import { getSingletonServices } from '../../pikku-state.js';
+import { randomUUID } from 'crypto';
+export async function runAIAgent(agentName, input, params, agentSessionMap) {
+    const sessionMap = agentSessionMap ?? new Map();
+    const { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemoryJsonSchema, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
+    const singletonServices = getSingletonServices();
+    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 accumulatedSteps = [];
+        const totalUsage = { inputTokens: 0, outputTokens: 0 };
+        let lastStepResult = null;
+        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;
+            }
+            const stepResult = await agentRunner.run(runnerParams);
+            lastStepResult = stepResult;
+            totalUsage.inputTokens += stepResult.usage.inputTokens;
+            totalUsage.outputTokens += stepResult.usage.outputTokens;
+            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,
+                    });
+                }
+            }
+            accumulatedSteps.push({
+                usage: stepResult.usage,
+                toolCalls: stepResult.toolCalls.map((tc) => {
+                    const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
+                    return {
+                        name: tc.toolName,
+                        args: tc.args,
+                        result: typeof tr?.result === 'string'
+                            ? tr.result
+                            : JSON.stringify(tr?.result ?? ''),
+                    };
+                }),
+            });
+            if (stepResult.toolCalls.length === 0)
+                break;
+            const assistantMsg = {
+                id: randomUUID(),
+                role: 'assistant',
+                content: stepResult.text || undefined,
+                toolCalls: stepResult.toolCalls.map((tc) => ({
+                    id: tc.toolCallId,
+                    name: tc.toolName,
+                    args: tc.args,
+                })),
+                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);
+            }
+        }
+        const finalText = lastStepResult?.text ?? '';
+        const finalObject = lastStepResult?.object;
+        const result = {
+            text: finalText,
+            steps: accumulatedSteps,
+        };
+        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: totalUsage,
+                });
+                outputText = modResult.text;
+                outputMessages = modResult.messages;
+            }
+        }
+        await aiRunState.updateRun(runId, {
+            status: 'completed',
+            usage: { ...totalUsage, model: agent.model },
+        });
+        return {
+            runId,
+            text: outputText,
+            object: finalObject,
+            threadId,
+            steps: accumulatedSteps,
+            usage: totalUsage,
+        };
+    }
+    catch (error) {
+        for (const mw of aiMiddlewares) {
+            if (mw.onError) {
+                try {
+                    await mw.onError(singletonServices, {
+                        error: error instanceof Error ? error : new Error(String(error)),
+                        stepNumber: -1,
+                        messages: runnerParams.messages,
+                    });
+                }
+                catch {
+                    // onError hooks must not affect error flow
+                }
+            }
+        }
+        await aiRunState.updateRun(runId, {
+            status: 'failed',
+        });
+        throw error;
+    }
+}

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

@@ -0,0 +1,12 @@
+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;
+} | Record<string, unknown>, channel: AIStreamChannel, params: RunAIAgentParams, agentSessionMap?: Map<string, string>, options?: StreamAIAgentOptions): Promise<void>;
+export declare function resumeAIAgent(input: {
+    runId: string;
+    toolCallId: string;
+    approved: boolean;
+}, channel: AIStreamChannel, params: RunAIAgentParams, options?: StreamAIAgentOptions): Promise<void>;