@pikku/core 0.11.1 → 0.12.0

package/dist/utils.js

@@ -1,6 +1,3 @@
-// TODO: WireServices probably needs it's own type
-// but is an issue for the future and will be tackled
-// with dependency injection
 export const closeWireServices = async (logger, wireServices) => {
     await Promise.all(Object.values(wireServices).map(async (service) => {
         if (service?.close) {
@@ -28,6 +25,21 @@ export const isSerializable = (data) => {
         data instanceof Float32Array ||
         data instanceof Float64Array);
 };
+export const getTagGroups = (tagGroups, tag) => {
+    const results = [];
+    const exact = tagGroups[tag];
+    if (exact)
+        results.push(exact);
+    let colonIdx = tag.lastIndexOf(':');
+    while (colonIdx !== -1) {
+        const parent = tag.slice(0, colonIdx);
+        const group = tagGroups[parent];
+        if (group)
+            results.push(group);
+        colonIdx = parent.lastIndexOf(':');
+    }
+    return results;
+};
 const EMPTY_ARRAY = Object.freeze([]);
 export const freezeDedupe = (arr) => {
     if (!arr || arr.length === 0)
@@ -45,3 +57,48 @@ export const freezeDedupe = (arr) => {
     }
     return Object.freeze(out);
 };
+/**
+ * Stop a single service by calling its stop method if it exists
+ */
+const stopService = async (logger, name, service) => {
+    const stop = service?.stop;
+    if (stop) {
+        logger.info(`Stopping singleton service: ${name}`);
+        try {
+            await stop.call(service);
+        }
+        catch (e) {
+            logger.error(`Error stopping service ${name}:`, e);
+        }
+    }
+};
+/**
+ * Stop all singleton services, including external package services.
+ * External package services are stopped first, then the parent services.
+ *
+ * @param singletonServices - The parent singleton services to stop
+ */
+export const stopSingletonServices = async (singletonServices) => {
+    const logger = singletonServices.logger;
+    // First, stop all external package singleton services
+    if (globalThis.pikkuState) {
+        for (const [packageName, packageState] of globalThis.pikkuState) {
+            // Skip main package - we handle it separately
+            if (packageName === '__main__')
+                continue;
+            const packageServices = packageState.package?.singletonServices;
+            if (packageServices) {
+                logger.info(`Stopping singleton services for package: ${packageName}`);
+                for (const [name, service] of Object.entries(packageServices)) {
+                    await stopService(logger, `${packageName}/${name}`, service);
+                }
+                // Clear the cached services
+                packageState.package.singletonServices = null;
+            }
+        }
+    }
+    // Then stop the parent singleton services
+    for (const [name, service] of Object.entries(singletonServices)) {
+        await stopService(logger, name, service);
+    }
+};

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+export declare function formatVersionedId(baseName: string, version: number): string;
+export declare function parseVersionedId(id: string): {
+    baseName: string;
+    version: number | null;
+};
+export declare function isVersionedId(id: string): boolean;

package/dist/version.js

@@ -0,0 +1,19 @@
+const VERSION_SEPARATOR = '@v';
+export function formatVersionedId(baseName, version) {
+    return `${baseName}${VERSION_SEPARATOR}${version}`;
+}
+export function parseVersionedId(id) {
+    const idx = id.lastIndexOf(VERSION_SEPARATOR);
+    if (idx === -1) {
+        return { baseName: id, version: null };
+    }
+    const versionStr = id.slice(idx + VERSION_SEPARATOR.length);
+    const version = Number(versionStr);
+    if (!Number.isInteger(version) || version < 1) {
+        return { baseName: id, version: null };
+    }
+    return { baseName: id.slice(0, idx), version };
+}
+export function isVersionedId(id) {
+    return parseVersionedId(id).version !== null;
+}

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

@@ -0,0 +1,29 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { CoreAIAgent, AIAgentMemoryConfig, AIAgentInput, AIMessage } from './ai-agent.types.js';
+import type { AIStorageService } from '../../services/ai-storage-service.js';
+import type { Logger } from '../../services/logger.js';
+import type { SchemaService } from '../../services/schema-service.js';
+export declare function resolveMemoryServices(agent: CoreAIAgent, singletonServices: CoreSingletonServices): {
+    storage: AIStorageService | undefined;
+};
+export declare function deepMergeWorkingMemory(existing: Record<string, unknown>, updates: Record<string, unknown>): Record<string, unknown>;
+export declare function buildWorkingMemoryPrompt(currentState: Record<string, unknown> | null, jsonSchema?: Record<string, unknown>): string;
+export declare function loadContextMessages(memoryConfig: AIAgentMemoryConfig | undefined, storage: AIStorageService | undefined, input: AIAgentInput, workingMemoryJsonSchema?: Record<string, unknown>): Promise<AIMessage[]>;
+export declare function saveMessages(storage: AIStorageService | undefined, threadId: string, resourceId: string, memoryConfig: AIAgentMemoryConfig | undefined, userMessage: AIMessage, result: {
+    text: string;
+    steps: {
+        toolCalls?: {
+            name: string;
+            args: Record<string, unknown>;
+            result: string;
+        }[];
+    }[];
+}, options?: {
+    workingMemoryJsonSchema?: Record<string, unknown>;
+    workingMemorySchemaName?: string | null;
+    logger?: Logger;
+    schemaService?: SchemaService;
+}): Promise<string>;
+export declare function trimMessages(messages: AIMessage[], maxTokenBudget?: number): AIMessage[];
+export declare function parseWorkingMemory(text: string): Record<string, unknown> | null;
+export declare function stripWorkingMemoryTags(text: string): string;

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

@@ -0,0 +1,199 @@
+import { randomUUID } from 'crypto';
+export function resolveMemoryServices(agent, singletonServices) {
+    const memoryConfig = agent.memory;
+    const storage = memoryConfig?.storage
+        ? singletonServices[memoryConfig.storage]
+        : singletonServices.aiStorage;
+    return { storage };
+}
+export function deepMergeWorkingMemory(existing, updates) {
+    const result = { ...existing };
+    for (const key of Object.keys(updates)) {
+        const value = updates[key];
+        if (value === null) {
+            delete result[key];
+        }
+        else if (typeof value === 'object' &&
+            !Array.isArray(value) &&
+            typeof result[key] === 'object' &&
+            result[key] !== null &&
+            !Array.isArray(result[key])) {
+            result[key] = deepMergeWorkingMemory(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function buildWorkingMemoryPrompt(currentState, jsonSchema) {
+    const parts = [];
+    if (jsonSchema?.properties) {
+        const props = jsonSchema.properties;
+        const fieldLines = Object.entries(props).map(([name, def]) => {
+            const type = def.type ?? 'unknown';
+            const desc = def.description ? ` - ${def.description}` : '';
+            return `  - ${name} (${type})${desc}`;
+        });
+        if (fieldLines.length > 0) {
+            parts.push(`Working memory fields:\n${fieldLines.join('\n')}`);
+        }
+    }
+    if (currentState && Object.keys(currentState).length > 0) {
+        parts.push(`Current working memory:\n${JSON.stringify(currentState)}`);
+    }
+    else {
+        parts.push('Current working memory: (empty)');
+    }
+    parts.push('When you learn new information, output a partial JSON update in <working_memory> tags. ' +
+        'Only include changed fields. Set a field to null to delete it.');
+    return parts.join('\n\n');
+}
+export async function loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema) {
+    const contextMessages = [];
+    if (memoryConfig?.workingMemory && storage) {
+        const workingMem = await storage.getWorkingMemory(input.threadId, 'thread');
+        const prompt = buildWorkingMemoryPrompt(workingMem, workingMemoryJsonSchema);
+        contextMessages.push({
+            id: `wm-${randomUUID()}`,
+            role: 'system',
+            content: prompt,
+            createdAt: new Date(),
+        });
+    }
+    return contextMessages;
+}
+export async function saveMessages(storage, threadId, resourceId, memoryConfig, userMessage, result, options) {
+    let responseText = result.text;
+    if (storage) {
+        const newMessages = [userMessage];
+        for (const step of result.steps) {
+            if (step.toolCalls?.length) {
+                newMessages.push({
+                    id: randomUUID(),
+                    role: 'assistant',
+                    toolCalls: step.toolCalls.map((tc) => ({
+                        id: randomUUID(),
+                        name: tc.name,
+                        args: tc.args,
+                    })),
+                    createdAt: new Date(),
+                });
+                newMessages.push({
+                    id: randomUUID(),
+                    role: 'tool',
+                    toolResults: step.toolCalls.map((tc) => ({
+                        id: randomUUID(),
+                        name: tc.name,
+                        result: tc.result,
+                    })),
+                    createdAt: new Date(),
+                });
+            }
+        }
+        newMessages.push({
+            id: randomUUID(),
+            role: 'assistant',
+            content: responseText,
+            createdAt: new Date(),
+        });
+        await storage.saveMessages(threadId, newMessages);
+        if (memoryConfig?.workingMemory) {
+            const parsed = parseWorkingMemory(responseText);
+            if (parsed) {
+                const existing = (await storage.getWorkingMemory(threadId, 'thread')) ?? {};
+                const merged = deepMergeWorkingMemory(existing, parsed);
+                if (options?.schemaService && options?.workingMemorySchemaName) {
+                    try {
+                        await options.schemaService.validateSchema(options.workingMemorySchemaName, merged);
+                    }
+                    catch (err) {
+                        options.logger?.warn(`Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                await storage.saveWorkingMemory(threadId, 'thread', merged);
+                responseText = stripWorkingMemoryTags(responseText);
+            }
+        }
+    }
+    return responseText;
+}
+export function trimMessages(messages, maxTokenBudget = 100000) {
+    const sanitized = sanitizeToolMessages(messages);
+    let estimatedTokens = 0;
+    const result = [];
+    for (let i = sanitized.length - 1; i >= 0; i--) {
+        const msg = sanitized[i];
+        const msgTokens = estimateTokens(msg);
+        if (estimatedTokens + msgTokens > maxTokenBudget && result.length > 0) {
+            break;
+        }
+        estimatedTokens += msgTokens;
+        result.unshift(msg);
+    }
+    if (result.length > 0 &&
+        result[0].role !== 'user' &&
+        result[0].role !== 'system') {
+        const firstUserIdx = result.findIndex((m) => m.role === 'user' || m.role === 'system');
+        if (firstUserIdx > 0) {
+            return result.slice(firstUserIdx);
+        }
+    }
+    return result;
+}
+function sanitizeToolMessages(messages) {
+    const result = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role === 'assistant' && msg.toolCalls?.length) {
+            const next = messages[i + 1];
+            if (!next || next.role !== 'tool' || !next.toolResults?.length) {
+                if (msg.content) {
+                    result.push({ ...msg, toolCalls: undefined });
+                }
+                continue;
+            }
+            const toolCallIds = new Set(msg.toolCalls.map((tc) => tc.id));
+            const resultIds = new Set(next.toolResults.map((tr) => tr.id));
+            const allMatched = [...toolCallIds].every((id) => resultIds.has(id));
+            if (!allMatched) {
+                if (msg.content) {
+                    result.push({ ...msg, toolCalls: undefined });
+                }
+                result.push({
+                    ...next,
+                    toolResults: next.toolResults.filter((tr) => !toolCallIds.has(tr.id)) ||
+                        undefined,
+                });
+                i++;
+                continue;
+            }
+        }
+        result.push(msg);
+    }
+    return result.filter((m) => m.role !== 'tool' || (m.toolResults && m.toolResults.length > 0));
+}
+function estimateTokens(msg) {
+    let chars = 0;
+    if (msg.content)
+        chars += msg.content.length;
+    if (msg.toolCalls)
+        chars += JSON.stringify(msg.toolCalls).length;
+    if (msg.toolResults)
+        chars += JSON.stringify(msg.toolResults).length;
+    return Math.ceil(chars / 4);
+}
+export function parseWorkingMemory(text) {
+    const match = text.match(/<working_memory>([\s\S]*?)<\/working_memory>/);
+    if (!match)
+        return null;
+    try {
+        return JSON.parse(match[1].trim());
+    }
+    catch {
+        return null;
+    }
+}
+export function stripWorkingMemoryTags(text) {
+    return text.replace(/<working_memory>[\s\S]*?<\/working_memory>/g, '').trim();
+}

package/dist/wirings/ai-agent/ai-agent-model-config.d.ts

@@ -0,0 +1,9 @@
+export declare function resolveModelConfig(agentName: string, agent: {
+    model: string;
+    temperature?: number;
+    maxSteps?: number;
+}): {
+    model: string;
+    temperature?: number;
+    maxSteps?: number;
+};

package/dist/wirings/ai-agent/ai-agent-model-config.js

@@ -0,0 +1,36 @@
+import { pikkuState } from '../../pikku-state.js';
+export function resolveModelConfig(agentName, agent) {
+    let config = {};
+    try {
+        config = pikkuState(null, 'models', 'config') ?? {};
+    }
+    catch { }
+    const models = config.models ?? {};
+    const defaults = config.agentDefaults;
+    const agentOverride = config.agentOverrides?.[agentName];
+    let rawModel = agentOverride?.model ?? agent.model;
+    let aliasTemperature;
+    let aliasMaxSteps;
+    if (!rawModel.includes('/')) {
+        const entry = models[rawModel];
+        if (!entry)
+            throw new Error(`Unknown model alias '${rawModel}'.`);
+        if (typeof entry === 'string') {
+            rawModel = entry;
+        }
+        else {
+            rawModel = entry.model;
+            aliasTemperature = entry.temperature;
+            aliasMaxSteps = entry.maxSteps;
+        }
+    }
+    const temperature = agentOverride?.temperature ??
+        aliasTemperature ??
+        defaults?.temperature ??
+        agent.temperature;
+    const maxSteps = agentOverride?.maxSteps ??
+        aliasMaxSteps ??
+        defaults?.maxSteps ??
+        agent.maxSteps;
+    return { model: rawModel, temperature, maxSteps };
+}

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

@@ -0,0 +1,60 @@
+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 { 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;
+};
+export declare class ToolApprovalRequired extends PikkuError {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly reason?: string;
+    readonly displayToolName?: string;
+    readonly displayArgs?: unknown;
+    readonly agentRunId?: string;
+    constructor(toolCallId: string, toolName: string, args: unknown, reason?: string, displayToolName?: string, displayArgs?: unknown, agentRunId?: string);
+}
+export type StreamContext = {
+    channel: AIStreamChannel;
+    options?: StreamAIAgentOptions;
+};
+export declare const resolveAgent: (agentName: string) => {
+    agent: CoreAIAgent;
+    packageName: string | null;
+    resolvedName: string;
+};
+export declare function buildInstructions(agentName: string, packageName: string | null): string;
+export type ScopedChannel = AIStreamChannel & {
+    approval: {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        runId: string;
+    } | 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): {
+    tools: AIAgentToolDef[];
+    missingRpcs: string[];
+};
+export declare function prepareAgentRun(agentName: string, input: AIAgentInput, params: RunAIAgentParams, agentSessionMap: Map<string, string>, streamContext?: StreamContext): Promise<{
+    agent: CoreAIAgent;
+    packageName: string | null;
+    resolvedName: string;
+    agentRunner: import("../../services/ai-agent-runner-service.js").AIAgentRunnerService;
+    storage: import("../../services/ai-storage-service.js").AIStorageService | undefined;
+    memoryConfig: import("./ai-agent.types.js").AIAgentMemoryConfig | undefined;
+    threadId: string;
+    userMessage: AIMessage;
+    runnerParams: AIAgentRunnerParams;
+    missingRpcs: string[];
+    workingMemoryJsonSchema: any;
+    workingMemorySchemaName: string | null;
+}>;