@pikku/core 0.12.0 → 0.12.1

package/dist/types/state.types.d.ts

@@ -1,16 +1,16 @@
-import { PikkuError, ErrorDetails } from '../errors/error-handler.js';
-import { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
-import { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js';
-import { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types.js';
-import { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js';
-import { HTTPMethod, CoreHTTPFunctionWiring, HTTPWiringsMeta } from '../wirings/http/http.types.js';
-import { CoreMCPResource, MCPResourceMeta, MCPToolMeta, CoreMCPPrompt, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
-import { CoreAIAgent, AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js';
-import { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
-import { CoreScheduledTask, ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js';
-import { CoreWorkflow, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
-import { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
-import { FunctionsMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
+import type { PikkuError, ErrorDetails } from '../errors/error-handler.js';
+import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
+import type { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js';
+import type { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types.js';
+import type { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js';
+import type { HTTPMethod, CoreHTTPFunctionWiring, HTTPWiringsMeta } from '../wirings/http/http.types.js';
+import type { CoreMCPResource, MCPResourceMeta, MCPToolMeta, CoreMCPPrompt, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
+import type { CoreAIAgent, AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js';
+import type { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
+import type { CoreScheduledTask, ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js';
+import type { CoreWorkflow, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
+import type { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
+import type { FunctionsMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
 /**
  * State structure for an individual package
@@ -27,9 +27,11 @@ export interface PikkuPackageState {
             path: string;
         }>;
         /** Maps namespace aliases to package config (e.g., 'ext' -> { package: '@pikku/...', rpcEndpoint: '...' }) */
-        externalPackages: Map<string, {
+        addons: Map<string, {
             package: string;
             rpcEndpoint?: string;
+            auth?: boolean;
+            tags?: string[];
         }>;
     };
     http: {
@@ -113,7 +115,7 @@ export interface PikkuPackageState {
         } | null;
     };
     package: {
-        /** Service factory functions for external packages */
+        /** Service factory functions for addon packages */
         factories: {
             createConfig?: CreateConfig<CoreConfig>;
             createSingletonServices?: CreateSingletonServices<CoreConfig, CoreSingletonServices>;

package/dist/utils.d.ts

@@ -1,14 +1,14 @@
-import { Logger } from './services/logger.js';
-import { CoreSingletonServices, WireServices } from './types/core.types.js';
+import type { Logger } from './services/logger.js';
+import type { WireServices } from './types/core.types.js';
 export declare const closeWireServices: (logger: Logger, wireServices: WireServices) => Promise<void>;
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
 export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string) => T[];
 export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];
 /**
- * Stop all singleton services, including external package services.
- * External package services are stopped first, then the parent services.
+ * Stop all singleton services, including addon package services.
+ * Addon package services are stopped first, then the parent services.
  *
  * @param singletonServices - The parent singleton services to stop
  */
-export declare const stopSingletonServices: (singletonServices: CoreSingletonServices) => Promise<void>;
+export declare const stopSingletonServices: () => Promise<void>;

package/dist/utils.js

@@ -1,3 +1,4 @@
+import { getSingletonServices, getAllPackageStates } from './pikku-state.js';
 export const closeWireServices = async (logger, wireServices) => {
     await Promise.all(Object.values(wireServices).map(async (service) => {
         if (service?.close) {
@@ -10,9 +11,9 @@ export const closeWireServices = async (logger, wireServices) => {
         }
     }));
 };
-export const createWeakUID = () => {
-    return Date.now().toString(36) + Math.random().toString(36).substring(2, 10);
-};
+const _uidPrefix = Date.now().toString(36);
+let _uidCounter = 0;
+export const createWeakUID = () => `${_uidPrefix}-${++_uidCounter}`;
 export const isSerializable = (data) => {
     return !(typeof data === 'string' ||
         data instanceof ArrayBuffer ||
@@ -73,16 +74,18 @@ const stopService = async (logger, name, service) => {
     }
 };
 /**
- * Stop all singleton services, including external package services.
- * External package services are stopped first, then the parent services.
+ * Stop all singleton services, including addon package services.
+ * Addon package services are stopped first, then the parent services.
  *
  * @param singletonServices - The parent singleton services to stop
  */
-export const stopSingletonServices = async (singletonServices) => {
+export const stopSingletonServices = async () => {
+    const singletonServices = getSingletonServices();
     const logger = singletonServices.logger;
-    // First, stop all external package singleton services
-    if (globalThis.pikkuState) {
-        for (const [packageName, packageState] of globalThis.pikkuState) {
+    // First, stop all addon package singleton services
+    const stateMap = getAllPackageStates();
+    if (stateMap.size > 0) {
+        for (const [packageName, packageState] of stateMap) {
             // Skip main package - we handle it separately
             if (packageName === '__main__')
                 continue;

package/dist/wirings/ai-agent/ai-agent-assistant-ui.d.ts

@@ -0,0 +1,5 @@
+import type { AIStreamChannel, AIAgentInput } from './ai-agent.types.js';
+export declare function createAssistantUIChannel(parent: AIStreamChannel): AIStreamChannel;
+export declare function parseAssistantUIInput(input: Record<string, unknown>, defaults?: {
+    resourceId?: string;
+}): AIAgentInput;

package/dist/wirings/ai-agent/ai-agent-assistant-ui.js

@@ -0,0 +1,146 @@
+import { randomUUID } from 'crypto';
+export function createAssistantUIChannel(parent) {
+    const messageId = randomUUID();
+    let started = false;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let pendingToolResults = [];
+    let hasToolCalls = false;
+    let hasPendingApproval = false;
+    const sendChunk = (chunk) => {
+        parent.send(chunk);
+    };
+    const ensureStarted = () => {
+        if (!started) {
+            started = true;
+            sendChunk({ type: 'start', messageId });
+        }
+    };
+    const flushToolResults = () => {
+        for (const chunk of pendingToolResults) {
+            sendChunk(chunk);
+        }
+        pendingToolResults = [];
+    };
+    return {
+        channelId: parent.channelId,
+        openingData: parent.openingData,
+        get state() {
+            return parent.state;
+        },
+        close: () => parent.close(),
+        send: (event) => {
+            switch (event.type) {
+                case 'text-delta':
+                    ensureStarted();
+                    sendChunk({ type: 'text-delta', textDelta: event.text });
+                    break;
+                case 'reasoning-delta':
+                    ensureStarted();
+                    sendChunk({ type: 'reasoning-delta', delta: event.text });
+                    break;
+                case 'tool-call':
+                    ensureStarted();
+                    hasToolCalls = true;
+                    sendChunk({
+                        type: 'tool-call-start',
+                        id: event.toolCallId,
+                        toolCallId: event.toolCallId,
+                        toolName: event.toolName,
+                    });
+                    sendChunk({
+                        type: 'tool-call-delta',
+                        argsText: typeof event.args === 'string'
+                            ? event.args
+                            : JSON.stringify(event.args),
+                    });
+                    sendChunk({ type: 'tool-call-end' });
+                    break;
+                case 'tool-result':
+                    ensureStarted();
+                    pendingToolResults.push({
+                        type: 'tool-result',
+                        toolCallId: event.toolCallId,
+                        result: event.result,
+                    });
+                    break;
+                case 'agent-call':
+                case 'agent-result':
+                    break;
+                case 'usage': {
+                    ensureStarted();
+                    totalInputTokens += event.tokens.input;
+                    totalOutputTokens += event.tokens.output;
+                    const hasPending = pendingToolResults.length > 0;
+                    sendChunk({
+                        type: 'finish-step',
+                        finishReason: hasToolCalls ? 'tool-calls' : 'stop',
+                        usage: {
+                            promptTokens: event.tokens.input,
+                            completionTokens: event.tokens.output,
+                        },
+                        isContinued: hasPending,
+                    });
+                    flushToolResults();
+                    hasToolCalls = false;
+                    break;
+                }
+                case 'error':
+                    ensureStarted();
+                    sendChunk({ type: 'error', errorText: event.message });
+                    break;
+                case 'approval-request':
+                    ensureStarted();
+                    hasPendingApproval = true;
+                    sendChunk({ type: 'data-approval-request', data: event });
+                    break;
+                case 'suspended':
+                    ensureStarted();
+                    sendChunk({ type: 'data-suspended', data: event });
+                    break;
+                case 'done':
+                    ensureStarted();
+                    flushToolResults();
+                    sendChunk({
+                        type: 'finish',
+                        finishReason: hasPendingApproval ? 'tool-calls' : 'stop',
+                        usage: {
+                            promptTokens: totalInputTokens,
+                            completionTokens: totalOutputTokens,
+                        },
+                    });
+                    parent.send('[DONE]');
+                    parent.close();
+                    break;
+            }
+        },
+    };
+}
+export function parseAssistantUIInput(input, defaults) {
+    const messages = input.messages;
+    if (!messages || !Array.isArray(messages) || messages.length === 0) {
+        throw new Error('assistant-ui input must contain a non-empty messages array');
+    }
+    const lastUserMessage = [...messages].reverse().find((m) => m.role === 'user');
+    if (!lastUserMessage) {
+        throw new Error('No user message found in assistant-ui input');
+    }
+    let messageText;
+    if (typeof lastUserMessage.content === 'string') {
+        messageText = lastUserMessage.content;
+    }
+    else if (Array.isArray(lastUserMessage.parts)) {
+        const textPart = lastUserMessage.parts.find((p) => p.type === 'text');
+        messageText = textPart ? String(textPart.text) : '';
+    }
+    else if (Array.isArray(lastUserMessage.content)) {
+        const textPart = lastUserMessage.content.find((p) => p.type === 'text');
+        messageText = textPart ? String(textPart.text) : '';
+    }
+    else {
+        messageText = '';
+    }
+    const threadId = input.threadId ?? input.id ?? randomUUID();
+    const resourceId = defaults?.resourceId ?? 'default';
+    return { message: messageText, threadId, resourceId };
+}

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

@@ -0,0 +1,28 @@
+export declare function agent<TAgentMap extends Record<string, {
+    output: any;
+}>>(agentName: string & keyof TAgentMap): {
+    func: (services: any, data: any, wire: any) => Promise<any>;
+};
+export declare function agentStream<TAgentMap extends Record<string, {
+    output: any;
+}>>(agentName?: string & keyof TAgentMap): {
+    func: (services: any, data: any, wire: any) => Promise<void>;
+};
+export declare function agentResume(): {
+    func: (services: any, data: {
+        runId: string;
+        toolCallId: string;
+        approved: boolean;
+    }, wire: any) => Promise<void>;
+};
+export declare function agentApprove<TAgentMap extends Record<string, {
+    output: any;
+}>>(_agentName: string & keyof TAgentMap): {
+    func: (services: any, data: {
+        runId: string;
+        approvals: {
+            toolCallId: string;
+            approved: boolean;
+        }[];
+    }, wire: any) => Promise<any>;
+};

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

@@ -0,0 +1,40 @@
+export function agent(agentName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.agent.run(agentName, data);
+        },
+    };
+}
+export function agentStream(agentName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            if (agentName) {
+                await rpc.agent.stream(agentName, data);
+            }
+            else {
+                const { agentName: name, ...rest } = data;
+                if (!name) {
+                    throw new Error('agentStream requires an agentName either as a parameter or in the input data');
+                }
+                await rpc.agent.stream(name, rest);
+            }
+        },
+    };
+}
+export function agentResume() {
+    return {
+        func: async (_services, data, { rpc }) => {
+            await rpc.agent.resume(data.runId, {
+                toolCallId: data.toolCallId,
+                approved: data.approved,
+            });
+        },
+    };
+}
+export function agentApprove(_agentName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.agent.approve(data.runId, data.approvals);
+        },
+    };
+}

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

@@ -1,12 +1,10 @@
-import { type CoreSingletonServices, type CoreServices, type CoreUserSession, type CreateWireServices } from '../../types/core.types.js';
-import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel } from './ai-agent.types.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel, PikkuAIMiddlewareHooks } from './ai-agent.types.js';
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { SessionService } from '../../services/user-session-service.js';
 export type RunAIAgentParams = {
-    singletonServices: CoreSingletonServices;
     sessionService?: SessionService<CoreUserSession>;
-    createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession>;
 };
 export type StreamAIAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
@@ -40,7 +38,7 @@ export type ScopedChannel = AIStreamChannel & {
     } | null;
 };
 export declare function createScopedChannel(parent: AIStreamChannel, agentName: string, session: string): ScopedChannel;
-export declare function buildToolDefs(singletonServices: CoreSingletonServices, params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext): {
+export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[]): {
     tools: AIAgentToolDef[];
     missingRpcs: string[];
 };
@@ -54,6 +52,7 @@ export declare function prepareAgentRun(agentName: string, input: AIAgentInput,
     threadId: string;
     userMessage: AIMessage;
     runnerParams: AIAgentRunnerParams;
+    maxSteps: number;
     missingRpcs: string[];
     workingMemoryJsonSchema: any;
     workingMemorySchemaName: string | null;

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

@@ -1,5 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { pikkuState } from '../../pikku-state.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';
@@ -33,8 +33,8 @@ export const resolveAgent = (agentName) => {
     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);
+        const addons = pikkuState(null, 'rpc', 'addons');
+        const pkgConfig = addons.get(namespace);
         if (pkgConfig) {
             const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(localName);
             if (extAgent) {
@@ -85,7 +85,8 @@ export function createScopedChannel(parent, agentName, session) {
                 };
                 return;
             }
-            if (event.type === 'text-delta' ||
+            if (event.type === 'step-start' ||
+                event.type === 'text-delta' ||
                 event.type === 'reasoning-delta' ||
                 event.type === 'tool-call' ||
                 event.type === 'tool-result' ||
@@ -99,7 +100,8 @@ export function createScopedChannel(parent, agentName, session) {
         },
     };
 }
-export function buildToolDefs(singletonServices, params, agentSessionMap, resourceId, agentName, packageName, streamContext) {
+export function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares) {
+    const singletonServices = getSingletonServices();
     const tools = [];
     const missingRpcs = [];
     const approvalPolicy = streamContext?.options?.requiresToolApproval ?? 'explicit';
@@ -131,38 +133,18 @@ export function buildToolDefs(singletonServices, params, agentSessionMap, resour
             }
             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,
+                needsApproval: needsApproval || undefined,
                 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,
+                        createWireServices: getCreateWireServices(),
                         data: () => toolInput,
                         wire,
                         sessionService: params.sessionService,
@@ -237,10 +219,61 @@ export function buildToolDefs(singletonServices, params, agentSessionMap, resour
             });
         }
     }
+    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 } = params;
+    const singletonServices = getSingletonServices();
     const { agent, packageName, resolvedName } = resolveAgent(agentName);
     const agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
@@ -282,16 +315,18 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     };
     const allMessages = [...contextMessages, ...messages, userMessage];
     const trimmedMessages = trimMessages(allMessages);
-    const { tools, missingRpcs } = buildToolDefs(singletonServices, params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext);
+    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: resolved.maxSteps ?? 10,
+        maxSteps: 1,
         toolChoice: agent.toolChoice ?? 'auto',
         outputSchema,
     };
@@ -305,6 +340,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
         threadId,
         userMessage,
         runnerParams,
+        maxSteps,
         missingRpcs,
         workingMemoryJsonSchema,
         workingMemorySchemaName,

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

@@ -1,5 +1,5 @@
 import type { CoreAIAgent } from './ai-agent.types.js';
-import { AIRunStateService } from '../../services/ai-run-state-service.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;