@pikku/core 0.12.19 → 0.12.21

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

@@ -3,14 +3,17 @@ import type { CoreAIAgent, AIAgentMemoryConfig, AIAgentInput, AIMessage } from '
 import type { AIStorageService } from '../../services/ai-storage-service.js';
 import type { Logger } from '../../services/logger.js';
 import type { SchemaService } from '../../services/schema-service.js';
+import type { PikkuAIMiddlewareHooks } from './ai-agent.types.js';
 export declare function resolveMemoryServices(agent: CoreAIAgent, singletonServices: CoreSingletonServices): {
     storage: AIStorageService | undefined;
 };
+export declare function isWorkingMemoryEnabled(memoryConfig: AIAgentMemoryConfig | undefined, storage: AIStorageService | undefined): boolean;
 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 | null | undefined, result: {
     text: string;
+    uiSpec?: unknown;
     steps: {
         toolCalls?: {
             name: string;
@@ -18,12 +21,28 @@ export declare function saveMessages(storage: AIStorageService | undefined, thre
             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;
+export declare function extractWorkingMemory(text: string): {
+    workingMemory: Record<string, unknown> | null;
+    cleanedText: string;
+};
+export declare function stripWorkingMemoryForStreaming(text: string): string;
+export declare function createWorkingMemoryMiddleware(options: {
+    storage?: AIStorageService;
+    threadId: string;
+    workingMemorySchemaName?: string | null;
+    logger?: Logger;
+    schemaService?: SchemaService;
+}): PikkuAIMiddlewareHooks<{
+    rawText?: string;
+    emittedVisibleText?: string;
+}>;
+export declare function getWorkingMemoryMiddleware(memoryConfig: AIAgentMemoryConfig | undefined, storage: AIStorageService | undefined, options: {
+    threadId: string;
+    workingMemorySchemaName?: string | null;
+    logger?: Logger;
+    schemaService?: SchemaService;
+}): PikkuAIMiddlewareHooks[];

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

@@ -6,9 +6,15 @@ export function resolveMemoryServices(agent, singletonServices) {
         : singletonServices.aiStorage;
     return { storage };
 }
+export function isWorkingMemoryEnabled(memoryConfig, storage) {
+    return !!memoryConfig?.workingMemory && !!storage;
+}
 export function deepMergeWorkingMemory(existing, updates) {
     const result = { ...existing };
     for (const key of Object.keys(updates)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            continue;
+        }
         const value = updates[key];
         if (value === null) {
             delete result[key];
@@ -46,13 +52,18 @@ export function buildWorkingMemoryPrompt(currentState, jsonSchema) {
         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.');
+        'Only include durable facts you have actually derived or the user has confirmed. ' +
+        'Do not output templates, placeholders, or narration. ' +
+        'Only include changed fields. Leave unknown fields untouched. 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 workingMemoryStorage = isWorkingMemoryEnabled(memoryConfig, storage)
+        ? storage
+        : undefined;
+    if (workingMemoryStorage) {
+        const workingMem = await workingMemoryStorage.getWorkingMemory(input.threadId, 'thread');
         const prompt = buildWorkingMemoryPrompt(workingMem, workingMemoryJsonSchema);
         contextMessages.push({
             id: `wm-${randomUUID()}`,
@@ -63,8 +74,10 @@ export async function loadContextMessages(memoryConfig, storage, input, workingM
     }
     return contextMessages;
 }
-export async function saveMessages(storage, threadId, resourceId, memoryConfig, userMessage, result, options) {
-    let responseText = result.text;
+export async function saveMessages(storage, threadId, resourceId, memoryConfig, userMessage, result) {
+    const responseText = memoryConfig?.workingMemory
+        ? extractWorkingMemory(result.text).cleanedText
+        : result.text;
     if (storage) {
         const newMessages = userMessage ? [userMessage] : [];
         for (const step of result.steps) {
@@ -92,30 +105,21 @@ export async function saveMessages(storage, threadId, resourceId, memoryConfig,
                 });
             }
         }
+        const assistantContent = result.uiSpec != null
+            ? [
+                ...(responseText
+                    ? [{ type: 'text', text: responseText }]
+                    : []),
+                { type: 'generative-ui', spec: result.uiSpec },
+            ]
+            : responseText;
         newMessages.push({
             id: randomUUID(),
             role: 'assistant',
-            content: responseText,
+            content: assistantContent || undefined,
             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;
 }
@@ -209,3 +213,104 @@ export function parseWorkingMemory(text) {
 export function stripWorkingMemoryTags(text) {
     return text.replace(/<working_memory>[\s\S]*?<\/working_memory>/g, '').trim();
 }
+export function extractWorkingMemory(text) {
+    const workingMemory = parseWorkingMemory(text);
+    return {
+        workingMemory,
+        cleanedText: workingMemory ? stripWorkingMemoryTags(text) : text,
+    };
+}
+function getPendingWorkingMemoryPrefixLength(text) {
+    const prefixes = ['<working_memory>', '</working_memory>'];
+    const lastLt = text.lastIndexOf('<');
+    if (lastLt === -1)
+        return 0;
+    const suffix = text.slice(lastLt);
+    for (const prefix of prefixes) {
+        if (prefix.startsWith(suffix)) {
+            return suffix.length;
+        }
+    }
+    return 0;
+}
+export function stripWorkingMemoryForStreaming(text) {
+    let output = '';
+    let cursor = 0;
+    while (cursor < text.length) {
+        const openIndex = text.indexOf('<working_memory>', cursor);
+        if (openIndex === -1) {
+            const tail = text.slice(cursor);
+            const pendingPrefixLength = getPendingWorkingMemoryPrefixLength(tail);
+            output +=
+                pendingPrefixLength > 0 ? tail.slice(0, -pendingPrefixLength) : tail;
+            return output;
+        }
+        output += text.slice(cursor, openIndex);
+        const closeIndex = text.indexOf('</working_memory>', openIndex);
+        if (closeIndex === -1) {
+            return output;
+        }
+        cursor = closeIndex + '</working_memory>'.length;
+    }
+    return output;
+}
+export function createWorkingMemoryMiddleware(options) {
+    return {
+        modifyOutputStream: async (_services, { event, state }) => {
+            if (event.type !== 'text-delta')
+                return event;
+            const rawText = `${state.rawText ?? ''}${event.text}`;
+            state.rawText = rawText;
+            const visibleText = stripWorkingMemoryForStreaming(rawText);
+            const emittedVisibleText = state.emittedVisibleText ?? '';
+            if (!visibleText.startsWith(emittedVisibleText)) {
+                state.emittedVisibleText = visibleText;
+                return { ...event, text: visibleText };
+            }
+            const delta = visibleText.slice(emittedVisibleText.length);
+            state.emittedVisibleText = visibleText;
+            if (!delta)
+                return null;
+            return { ...event, text: delta };
+        },
+        modifyOutput: async (_services, { text, messages, usage }) => {
+            const { workingMemory, cleanedText } = extractWorkingMemory(text);
+            if (workingMemory && options.storage) {
+                const existing = (await options.storage.getWorkingMemory(options.threadId, 'thread')) ?? {};
+                const merged = deepMergeWorkingMemory(existing, workingMemory);
+                let valid = true;
+                if (options.schemaService && options.workingMemorySchemaName) {
+                    try {
+                        await options.schemaService.validateSchema(options.workingMemorySchemaName, merged);
+                    }
+                    catch (err) {
+                        valid = false;
+                        options.logger?.warn(`Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                // Only persist when the merged value passes schema validation —
+                // saving invalid data would poison subsequent getWorkingMemory reads.
+                if (valid) {
+                    await options.storage.saveWorkingMemory(options.threadId, 'thread', merged);
+                }
+            }
+            return {
+                text: cleanedText,
+                messages,
+            };
+        },
+    };
+}
+export function getWorkingMemoryMiddleware(memoryConfig, storage, options) {
+    if (!isWorkingMemoryEnabled(memoryConfig, storage))
+        return [];
+    return [
+        createWorkingMemoryMiddleware({
+            storage,
+            threadId: options.threadId,
+            workingMemorySchemaName: options.workingMemorySchemaName,
+            logger: options.logger,
+            schemaService: options.schemaService,
+        }),
+    ];
+}

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

@@ -1,4 +1,13 @@
-export declare function resolveModelConfig(agentName: string, agent: {
+/**
+ * Resolves the effective model/temperature/maxSteps for an agent at runtime.
+ *
+ * Models are declared per-agent using the provider-qualified `provider/model`
+ * form (e.g. `openai/gpt-5-mini`); there is no config-level alias map. This
+ * function remains the single merge point for request-time overrides (see
+ * ai-agent-prepare's `input.model`), so callers stay decoupled from how the
+ * effective config is assembled.
+ */
+export declare function resolveModelConfig(_agentName: string, agent: {
     model: string;
     temperature?: number;
     maxSteps?: number;

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

@@ -1,36 +1,16 @@
-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 };
+/**
+ * Resolves the effective model/temperature/maxSteps for an agent at runtime.
+ *
+ * Models are declared per-agent using the provider-qualified `provider/model`
+ * form (e.g. `openai/gpt-5-mini`); there is no config-level alias map. This
+ * function remains the single merge point for request-time overrides (see
+ * ai-agent-prepare's `input.model`), so callers stay decoupled from how the
+ * effective config is assembled.
+ */
+export function resolveModelConfig(_agentName, agent) {
+    return {
+        model: agent.model,
+        temperature: agent.temperature,
+        maxSteps: agent.maxSteps,
+    };
 }

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

@@ -169,6 +169,9 @@ export function createScopedChannel(parent, agentName, session) {
                 parent.send(event);
             }
         },
+        setState: (s) => parent.setState(s),
+        getState: () => parent.getState(),
+        clearState: () => parent.clearState(),
     };
 }
 export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode) {
@@ -254,7 +257,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 }
             }
             tools.push({
-                name: toolName.replaceAll(':', '__'),
+                name: toolName.replaceAll('@', '_').replaceAll(':', '__'),
                 description: fnMeta?.description || fnMeta?.title || toolName,
                 inputSchema,
                 needsApproval: needsApproval || undefined,

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

@@ -1,4 +1,4 @@
-import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
+import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, } from './ai-agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
@@ -20,9 +20,19 @@ function stripNulls(obj) {
     return result;
 }
 import { randomUUID } from 'crypto';
+function extractStructuredAssistantOutput(object) {
+    if (!object || typeof object !== 'object') {
+        return { text: null, uiSpec: null };
+    }
+    const record = object;
+    return {
+        text: typeof record.text === 'string' ? record.text : null,
+        uiSpec: record.ui ?? null,
+    };
+}
 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 { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
     const singletonServices = getSingletonServices();
     const { aiRunState } = singletonServices;
     if (!aiRunState) {
@@ -48,7 +58,15 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             usage: { inputTokens: 0, outputTokens: 0 },
         };
     }
-    const aiMiddlewares = agent.aiMiddleware ?? [];
+    const aiMiddlewares = [
+        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+            threadId,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        }),
+        ...(agent.aiMiddleware ?? []),
+    ];
     let modifiedMessages = runnerParams.messages;
     let modifiedInstructions = runnerParams.instructions;
     for (const mw of aiMiddlewares) {
@@ -152,12 +170,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                         args: a.args,
                     });
                 const completedStepsForSave = accumulatedSteps.slice(0, -1);
-                await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, { text: '', steps: completedStepsForSave }, {
-                    workingMemoryJsonSchema,
-                    workingMemorySchemaName,
-                    logger: singletonServices.logger,
-                    schemaService: singletonServices.schema,
-                });
+                await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, { text: '', steps: completedStepsForSave });
                 if (storage) {
                     await storage.saveMessages(threadId, [
                         {
@@ -197,19 +210,14 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             }
             appendStepMessages(runnerParams, stepResult);
         }
-        const finalText = lastStepResult?.text ?? '';
         const finalObject = lastStepResult?.object;
+        const structuredOutput = extractStructuredAssistantOutput(finalObject);
+        const finalText = structuredOutput.text ?? lastStepResult?.text ?? '';
         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 outputText = finalText;
         let outputMessages = runnerParams.messages;
         for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
             const mw = aiMiddlewares[i];
@@ -223,6 +231,11 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                 outputMessages = modResult.messages;
             }
         }
+        await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, {
+            ...result,
+            text: outputText,
+            uiSpec: structuredOutput.uiSpec,
+        });
         await aiRunState.updateRun(runId, {
             status: 'completed',
             usage: { ...totalUsage, model: agent.model },
@@ -369,7 +382,15 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
     const allMessages = [...contextMessages, ...messages];
     const trimmedMessages = trimMessages(allMessages);
     const instructions = await buildInstructions(resolvedName, packageName);
-    const aiMiddlewares = agent.aiMiddleware ?? [];
+    const aiMiddlewares = [
+        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+            threadId: run.threadId,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        }),
+        ...(agent.aiMiddleware ?? []),
+    ];
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
     for (const mw of aiMiddlewares) {
@@ -463,12 +484,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                     });
                 const completedSteps = accumulatedSteps.slice(0, -1);
                 if (completedSteps.length > 0) {
-                    await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, { text: '', steps: completedSteps }, {
-                        workingMemoryJsonSchema,
-                        workingMemorySchemaName,
-                        logger: singletonServices.logger,
-                        schemaService: singletonServices.schema,
-                    });
+                    await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, { text: '', steps: completedSteps });
                 }
                 if (storage) {
                     await storage.saveMessages(run.threadId, [
@@ -515,13 +531,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             text: finalText,
             steps: accumulatedSteps,
         };
-        const responseText = await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, result, {
-            workingMemoryJsonSchema,
-            workingMemorySchemaName,
-            logger: singletonServices.logger,
-            schemaService: singletonServices.schema,
-        });
-        let outputText = responseText;
+        let outputText = finalText;
         let outputMessages = runnerParams.messages;
         for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
             const mw = aiMiddlewares[i];
@@ -535,6 +545,10 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                 outputMessages = modResult.messages;
             }
         }
+        await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, {
+            ...result,
+            text: outputText,
+        });
         await aiRunState.updateRun(run.runId, {
             status: 'completed',
             usage: { ...totalUsage, model: agent.model },