@pikku/core 0.12.84 → 0.12.86

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

@@ -1,333 +0,0 @@
-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.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];
-        }
-        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/ai-agent/ai-agent-model-config.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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/ai-agent/ai-agent-model-config.js

@@ -1,51 +0,0 @@
-// knowledge: decisions/internals/ai-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/ai-agent/ai-agent-prepare.d.ts

@@ -1,117 +0,0 @@
-import type { CoreUserSession } from '../../types/core.types.js';
-import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel, PikkuAIMiddlewareHooks, SessionScope } 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 = {
-    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: RunAIAgentParams, sessionScope: SessionScope | undefined): string | undefined;
-export declare function resolveOwnerResourceId(params: RunAIAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
-export declare function assertResourcePrincipalOwner(params: RunAIAgentParams, 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 StreamAIAgentOptions = {
-    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: AIStreamChannel;
-    options?: StreamAIAgentOptions;
-    delegateState?: {
-        delegated: boolean;
-    };
-};
-export declare const resolveAgent: (agentName: string) => {
-    agent: CoreAIAgent;
-    packageName: string | null;
-    resolvedName: string;
-};
-export declare function assertAgentAuthorized(agent: CoreAIAgent, params: RunAIAgentParams, packageName: string | null): Promise<void>;
-export declare function buildInstructions(agentName: string, packageName: string | null): Promise<string>;
-export type ScopedChannel = AIStreamChannel & {
-    approvals: Array<{
-        toolCallId: string;
-        toolName: string;
-        args: unknown;
-        reason?: string;
-        runId: string;
-    }>;
-};
-export declare function createScopedChannel(parent: AIStreamChannel, 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: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise', parentContext?: string): Promise<{
-    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("../../index.js").AIStorageService | undefined;
-    memoryConfig: import("./ai-agent.types.js").AIAgentMemoryConfig | undefined;
-    threadId: string;
-    userMessage: AIMessage;
-    runnerParams: AIAgentRunnerParams;
-    maxSteps: number;
-    missingRpcs: string[];
-    workingMemoryJsonSchema: any;
-    workingMemorySchemaName: string | null;
-}>;