@pikku/core 0.12.83 → 0.12.84

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

@@ -0,0 +1,333 @@
+import { randomUUID } from 'crypto';
+export function resolveMemoryServices(agent, singletonServices) {
+    const memoryConfig = agent.memory;
+    const storage = memoryConfig?.storage
+        ? // The service is named by string in agent config, so the lookup cannot be
+            // checked — only the shape it is required to have.
+            singletonServices[memoryConfig.storage]
+        : singletonServices.agentStorage;
+    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];
+        }
+        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 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 = [];
+    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()}`,
+            role: 'system',
+            content: prompt,
+            createdAt: new Date(),
+        });
+    }
+    return contextMessages;
+}
+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) {
+            if (step.toolCalls?.length) {
+                const toolCallIds = step.toolCalls.map(() => randomUUID());
+                newMessages.push({
+                    id: randomUUID(),
+                    role: 'assistant',
+                    toolCalls: step.toolCalls.map((tc, i) => ({
+                        id: toolCallIds[i],
+                        name: tc.name,
+                        args: tc.args,
+                    })),
+                    createdAt: new Date(),
+                });
+                newMessages.push({
+                    id: randomUUID(),
+                    role: 'tool',
+                    toolResults: step.toolCalls.map((tc, i) => ({
+                        id: toolCallIds[i],
+                        name: tc.name,
+                        result: tc.result,
+                        ...(tc.error ? { error: tc.error } : {}),
+                    })),
+                    createdAt: new Date(),
+                });
+            }
+        }
+        const assistantContent = result.uiSpec != null
+            ? [
+                ...(responseText
+                    ? [{ type: 'text', text: responseText }]
+                    : []),
+                { type: 'generative-ui', spec: result.uiSpec },
+            ]
+            : responseText;
+        newMessages.push({
+            id: randomUUID(),
+            role: 'assistant',
+            content: assistantContent || undefined,
+            createdAt: new Date(),
+        });
+        await storage.saveMessages(threadId, newMessages);
+    }
+    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) {
+        if (typeof msg.content === 'string') {
+            chars += msg.content.length;
+        }
+        else {
+            for (const part of msg.content) {
+                if (part.type === 'text')
+                    chars += part.text.length;
+                else
+                    chars += 1000;
+            }
+        }
+    }
+    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();
+}
+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;
+}
+async function persistWorkingMemory(options, workingMemory) {
+    if (!options.storage)
+        return;
+    const existing = (await options.storage.getWorkingMemory(options.threadId, 'thread')) ?? {};
+    const merged = deepMergeWorkingMemory(existing, workingMemory);
+    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)}`);
+            return;
+        }
+    }
+    await options.storage.saveWorkingMemory(options.threadId, 'thread', merged);
+}
+export function createWorkingMemoryMiddleware(options) {
+    return {
+        modifyOutputStream: async (_services, { event, state }) => {
+            // A streamed step ends at its `usage` event, or at `done` for a model
+            // that reports no usage. That is the last moment the unstripped text is
+            // still reachable: it lives only in `state.rawText`, because the strip
+            // below runs before anything downstream — including the channel that
+            // accumulates what `modifyOutput` would later be handed.
+            if (event.type === 'usage' || event.type === 'done') {
+                const { workingMemory } = extractWorkingMemory(state.rawText ?? '');
+                state.rawText = '';
+                state.emittedVisibleText = '';
+                if (workingMemory) {
+                    await persistWorkingMemory(options, workingMemory);
+                }
+                return event;
+            }
+            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 }) => {
+            const { workingMemory, cleanedText } = extractWorkingMemory(text);
+            if (workingMemory) {
+                await persistWorkingMemory(options, workingMemory);
+            }
+            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/agent/agent-model-config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolves a model name to a concrete `provider/model`. Aliases come from the
+ * `models` table in pikku.config.json; a name containing `/` is already
+ * concrete. Read from the main package, not the calling addon's — which model
+ * a tier points at is the hosting app's decision.
+ */
+export declare const resolveModelAlias: (model: string) => string;
+export declare function resolveModelConfig(_agentName: string, agent: {
+    model: string;
+    temperature?: number;
+    maxSteps?: number;
+}): {
+    model: string;
+    temperature?: number;
+    maxSteps?: number;
+};

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

@@ -0,0 +1,51 @@
+// knowledge: decisions/internals/agent-model-config-stays-a-single-resolution-seam.md
+import { pikkuState } from '../../pikku-state.js';
+const isProviderQualified = (model) => model.includes('/');
+/** `PIKKU_MODEL_ALIASES=cheap:openai/gpt-5-mini,tool:anthropic/claude-sonnet-5` */
+const envAliases = () => {
+    const raw = process.env.PIKKU_MODEL_ALIASES;
+    if (!raw)
+        return {};
+    const aliases = {};
+    for (const entry of raw.split(',')) {
+        // First colon only — a model id may contain its own.
+        const separator = entry.indexOf(':');
+        if (separator === -1)
+            continue;
+        const alias = entry.slice(0, separator).trim();
+        const model = entry.slice(separator + 1).trim();
+        if (alias && model)
+            aliases[alias] = model;
+    }
+    return aliases;
+};
+/**
+ * Resolves a model name to a concrete `provider/model`. Aliases come from the
+ * `models` table in pikku.config.json; a name containing `/` is already
+ * concrete. Read from the main package, not the calling addon's — which model
+ * a tier points at is the hosting app's decision.
+ */
+export const resolveModelAlias = (model) => {
+    if (isProviderQualified(model))
+        return model;
+    const generated = pikkuState(null, 'agent', 'modelAliases');
+    const override = envAliases()[model];
+    const resolved = override ?? generated[model];
+    if (!resolved) {
+        const known = Object.keys({ ...generated, ...envAliases() }).sort();
+        throw new Error(`Unknown model alias '${model}'. ` +
+            (known.length
+                ? `Known aliases: ${known.join(', ')}. `
+                : `No aliases are configured. `) +
+            `Add it to the "models" table in pikku.config.json, or name a ` +
+            `provider-qualified model such as 'openai/gpt-5-mini'.`);
+    }
+    return resolved;
+};
+export function resolveModelConfig(_agentName, agent) {
+    return {
+        model: resolveModelAlias(agent.model),
+        temperature: agent.temperature,
+        maxSteps: agent.maxSteps,
+    };
+}

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

@@ -0,0 +1,117 @@
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { CoreAgent, AgentInput, AgentToolDef, AgentMessage, AgentStreamChannel, PikkuAgentMiddlewareHooks, SessionScope } from './agent.types.js';
+import type { AgentRunnerParams } from '../../services/agent-runner-service.js';
+import { PikkuError } from '../../errors/error-handler.js';
+import type { SessionService } from '../../services/user-session-service.js';
+export type RunAgentParams = {
+    sessionService?: SessionService<CoreUserSession>;
+    /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
+    getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>;
+    /** Ephemeral owner identity minted for a sessionless request; never client-supplied, never reused across requests. */
+    anonymousOwnerResourceId?: string;
+};
+export declare function resolveSessionPrincipal(params: RunAgentParams, sessionScope: SessionScope | undefined): string | undefined;
+export declare function resolveOwnerResourceId(params: RunAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
+export declare function assertResourcePrincipalOwner(params: RunAgentParams, sessionScope: SessionScope | undefined, storedResourceId: string, kind: 'thread' | 'run'): void;
+export declare function agentSessionScope(agentName: string): SessionScope;
+export declare function assertResourceOwner(ownerResourceId: string, storedResourceId: string, kind: 'thread' | 'run'): void;
+export declare function sessionPrincipals(session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): string[];
+export declare function isOwnedByPrincipal(storedResourceId: string, principal: string): boolean;
+export declare function threadOwnerConstraint(session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): string[];
+export declare function canAccessThread(storedResourceId: string, session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): boolean;
+export type StreamAgentOptions = {
+    requiresToolApproval?: 'all' | 'explicit' | false;
+    onRunCreated?: (runId: string) => void;
+};
+export declare const APPROVAL_REQUIRED: unique symbol;
+/**
+ * In-process brand proving a credential request was produced by pikku itself and
+ * not by tool output an attacker can influence. Never serialized — a value that
+ * has crossed a JSON boundary has lost the brand and is treated as untrusted.
+ */
+export declare const CREDENTIAL_REQUIRED: unique symbol;
+export declare class ToolApprovalRequired extends PikkuError {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    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 declare class ToolCredentialRequired extends PikkuError {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly credentialName: string;
+    readonly credentialType: 'oauth2' | 'apikey';
+    readonly connectUrl?: string;
+    constructor(toolCallId: string, toolName: string, args: unknown, credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
+}
+export interface AddonCredentialRequirement {
+    credentialName: string;
+    displayName: string;
+    addonNamespace: string;
+    type: 'wire';
+    oauth2: boolean;
+}
+export declare function getAddonCredentialRequirements(toolNames: string[]): AddonCredentialRequirement[];
+export type StreamContext = {
+    channel: AgentStreamChannel;
+    options?: StreamAgentOptions;
+    delegateState?: {
+        delegated: boolean;
+    };
+};
+export declare const resolveAgent: (agentName: string) => {
+    agent: CoreAgent;
+    packageName: string | null;
+    resolvedName: string;
+};
+export declare function assertAgentAuthorized(agent: CoreAgent, params: RunAgentParams, packageName: string | null): Promise<void>;
+export declare function buildInstructions(agentName: string, packageName: string | null): Promise<string>;
+export type ScopedChannel = AgentStreamChannel & {
+    approvals: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        reason?: string;
+        runId: string;
+    }>;
+};
+export declare function createScopedChannel(parent: AgentStreamChannel, agentName: string, session: string): ScopedChannel;
+export declare function buildSubAgentRunInput(message: string, threadId: string, resourceId: string, parentContext?: string): {
+    message: string;
+    threadId: string;
+    resourceId: string;
+    context?: string;
+};
+export declare function buildToolDefs(params: RunAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, agentMiddlewares?: PikkuAgentMiddlewareHooks[], agentMode?: 'delegate' | 'supervise', parentContext?: string): Promise<{
+    tools: AgentToolDef[];
+    missingRpcs: string[];
+}>;
+export declare function prepareAgentRun(agentName: string, input: AgentInput, params: RunAgentParams, agentSessionMap: Map<string, string>, streamContext?: StreamContext): Promise<{
+    agent: CoreAgent;
+    packageName: string | null;
+    resolvedName: string;
+    agentRunner: import("../../services/agent-runner-service.js").AgentRunnerService;
+    storage: import("../../index.js").AgentStorageService | undefined;
+    memoryConfig: import("./agent.types.js").AgentMemoryConfig | undefined;
+    threadId: string;
+    userMessage: AgentMessage;
+    runnerParams: AgentRunnerParams;
+    maxSteps: number;
+    missingRpcs: string[];
+    workingMemoryJsonSchema: any;
+    workingMemorySchemaName: string | null;
+}>;