@pikku/core 0.12.84 → 0.12.86

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

@@ -1,728 +0,0 @@
-import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions, runPermissions, } from '../../permissions.js';
-import { AIProviderNotConfiguredError } from '../../errors/errors.js';
-import { ForbiddenError } from '../../errors/errors.js';
-import { verifyScopes } from '../../scopes.js';
-import { pikkuState, getSingletonServices } from '../../pikku-state.js';
-import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
-import { randomUUID } from './ai-agent-utils.js';
-import { awaitPendingInterruptNote } from './ai-agent-interrupt.js';
-import { streamAIAgent } from './ai-agent-stream.js';
-import { runAIAgent } from './ai-agent-runner.js';
-import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
-import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js';
-import { resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
-import { resolveModelConfig } from './ai-agent-model-config.js';
-export function resolveSessionPrincipal(params, sessionScope) {
-    const session = params.sessionService?.get();
-    if ((sessionScope ?? 'user') === 'org') {
-        if (!session?.orgId) {
-            throw new ForbiddenError('This agent is org-scoped but the session has no organization');
-        }
-        return session.orgId;
-    }
-    return session?.userId;
-}
-export function resolveOwnerResourceId(params, sessionScope, requestedResourceId) {
-    const principal = resolveSessionPrincipal(params, sessionScope);
-    if (!principal) {
-        params.anonymousOwnerResourceId ??= `anon-${randomUUID()}`;
-        return params.anonymousOwnerResourceId;
-    }
-    if (requestedResourceId === principal ||
-        requestedResourceId.startsWith(`${principal}:`)) {
-        return requestedResourceId;
-    }
-    return `${principal}:${requestedResourceId}`;
-}
-export function assertResourcePrincipalOwner(params, sessionScope, storedResourceId, kind) {
-    const principal = resolveSessionPrincipal(params, sessionScope);
-    if (!principal || !isOwnedByPrincipal(storedResourceId, principal)) {
-        throw new ForbiddenError(`Not authorized to access this ${kind}`);
-    }
-}
-export function agentSessionScope(agentName) {
-    return resolveAgent(agentName).agent.sessionScope ?? 'user';
-}
-export function assertResourceOwner(ownerResourceId, storedResourceId, kind) {
-    if (storedResourceId !== ownerResourceId) {
-        throw new ForbiddenError(`Not authorized to access this ${kind}`);
-    }
-}
-export function sessionPrincipals(session) {
-    return [session?.userId, session?.orgId].filter((principal) => Boolean(principal));
-}
-export function isOwnedByPrincipal(storedResourceId, principal) {
-    return (storedResourceId === principal ||
-        storedResourceId.startsWith(`${principal}:`));
-}
-export function threadOwnerConstraint(session) {
-    return sessionPrincipals(session);
-}
-export function canAccessThread(storedResourceId, session) {
-    const principals = sessionPrincipals(session);
-    if (principals.length === 0)
-        return false;
-    return principals.some((principal) => isOwnedByPrincipal(storedResourceId, principal));
-}
-export const APPROVAL_REQUIRED = Symbol('pikku.ai.approvalRequired');
-/**
- * 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 const CREDENTIAL_REQUIRED = Symbol('pikku.ai.credentialRequired');
-export class ToolApprovalRequired extends PikkuError {
-    toolCallId;
-    toolName;
-    args;
-    reason;
-    displayToolName;
-    displayArgs;
-    agentRunId;
-    constructor(toolCallId, toolName, args, reason, displayToolName, displayArgs, agentRunId) {
-        super(`Tool '${displayToolName ?? toolName}' requires approval`);
-        this.toolCallId = toolCallId;
-        this.toolName = toolName;
-        this.args = args;
-        this.reason = reason;
-        this.displayToolName = displayToolName;
-        this.displayArgs = displayArgs;
-        this.agentRunId = agentRunId;
-    }
-}
-export class ToolCredentialRequired extends PikkuError {
-    toolCallId;
-    toolName;
-    args;
-    credentialName;
-    credentialType;
-    connectUrl;
-    constructor(toolCallId, toolName, args, credentialName, credentialType, connectUrl) {
-        super(`Tool '${toolName}' requires credential '${credentialName}'`);
-        this.toolCallId = toolCallId;
-        this.toolName = toolName;
-        this.args = args;
-        this.credentialName = credentialName;
-        this.credentialType = credentialType;
-        this.connectUrl = connectUrl;
-    }
-}
-export function getAddonCredentialRequirements(toolNames) {
-    const requirements = new Map();
-    for (const toolName of toolNames) {
-        if (!toolName.includes(':'))
-            continue;
-        const resolved = resolveNamespace(toolName);
-        if (!resolved)
-            continue;
-        const credsMeta = pikkuState(resolved.package, 'package', 'credentialsMeta');
-        if (!credsMeta)
-            continue;
-        for (const [name, meta] of Object.entries(credsMeta)) {
-            if (meta.type === 'wire' && meta.oauth2 && !requirements.has(name)) {
-                requirements.set(name, {
-                    credentialName: name,
-                    displayName: meta.displayName ?? name,
-                    addonNamespace: toolName.split(':')[0],
-                    type: 'wire',
-                    oauth2: true,
-                });
-            }
-        }
-    }
-    return [...requirements.values()];
-}
-export const resolveAgent = (agentName) => {
-    if (!agentName) {
-        console.error('[resolveAgent] agentName is undefined/null! Stack:', new Error().stack);
-        throw new Error('resolveAgent called with undefined agentName');
-    }
-    const mainAgent = pikkuState(null, 'agent', 'agents').get(agentName);
-    if (mainAgent) {
-        return { agent: mainAgent, packageName: null, resolvedName: agentName };
-    }
-    const colonIndex = agentName.indexOf(':');
-    if (colonIndex !== -1) {
-        const namespace = agentName.substring(0, colonIndex);
-        const localName = agentName.substring(colonIndex + 1);
-        const addons = pikkuState(null, 'addons', 'packages');
-        const pkgConfig = addons.get(namespace);
-        if (pkgConfig) {
-            const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(localName);
-            if (extAgent) {
-                return {
-                    agent: extAgent,
-                    packageName: pkgConfig.package,
-                    resolvedName: localName,
-                };
-            }
-        }
-    }
-    throw new Error(`AI agent not found: ${agentName}`);
-};
-export async function assertAgentAuthorized(agent, params, packageName) {
-    const session = params.sessionService
-        ? await params.sessionService.get()
-        : undefined;
-    if (agent.auth === true && !session) {
-        throw new ForbiddenError('Authentication required');
-    }
-    verifyScopes(agent.scopes, session);
-    const singletonServices = getSingletonServices();
-    const wire = params.sessionService
-        ? createMiddlewareSessionWireProps(params.sessionService)
-        : { session: undefined };
-    await runPermissions({
-        funcPermissions: agent.permissions,
-        services: singletonServices,
-        wire: wire,
-        data: {},
-        packageName,
-        label: 'agent',
-    });
-}
-export async function buildInstructions(agentName, packageName) {
-    const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
-    const parts = [];
-    if (meta?.role)
-        parts.push(meta.role);
-    if (meta?.personality)
-        parts.push(meta.personality);
-    if (meta?.goal)
-        parts.push(meta.goal);
-    let instructions = parts.join('\n\n');
-    if (meta?.tools?.length || meta?.workflows?.length) {
-        instructions +=
-            '\n\nTool usage rules:\n' +
-                '- Act immediately with the information given. Do NOT ask clarifying questions unless a required field is truly missing.\n' +
-                '- Only use fields defined in your tool schemas. Never mention or ask for fields that do not exist.\n' +
-                '- Never fill optional fields with placeholder or zero values. Omit them entirely unless the user provides a real value.\n' +
-                '- Never stuff unrelated information into the wrong field.\n' +
-                '- Keep responses concise.';
-    }
-    if (meta?.agents?.length) {
-        instructions +=
-            '\n\nWhen calling a sub-agent, provide a short session name that describes the task. ' +
-                'Use the same session name to continue a previous conversation with that agent. ' +
-                'Use a new session name for a new independent task. ' +
-                'When a request involves multiple actions for the same domain, combine them into a single sub-agent call rather than making separate calls.';
-    }
-    return instructions;
-}
-export function createScopedChannel(parent, agentName, session) {
-    const capturedApprovals = [];
-    return {
-        channelId: `${parent.channelId}:${agentName}:${session}`,
-        openingData: parent.openingData,
-        get state() {
-            return parent.state;
-        },
-        get approvals() {
-            return capturedApprovals;
-        },
-        close: () => { },
-        sendBinary: (data) => parent.sendBinary(data),
-        send: (event) => {
-            if (event.type === 'done')
-                return;
-            if (event.type === 'approval-request') {
-                capturedApprovals.push({
-                    toolCallId: event.toolCallId,
-                    toolName: event.toolName,
-                    args: event.args,
-                    ...(event.reason !== undefined ? { reason: event.reason } : {}),
-                    runId: event.runId,
-                });
-                return;
-            }
-            if (event.type === 'step-start' ||
-                event.type === 'text-delta' ||
-                event.type === 'reasoning-delta' ||
-                event.type === 'tool-call' ||
-                event.type === 'tool-result' ||
-                event.type === 'usage' ||
-                event.type === 'error') {
-                parent.send({ ...event, agent: agentName, session });
-            }
-            else {
-                parent.send(event);
-            }
-        },
-        setState: (s) => parent.setState(s),
-        getState: () => parent.getState(),
-        clearState: () => parent.clearState(),
-        remote: (funcName, data) => parent.remote(funcName, data),
-    };
-}
-export function buildSubAgentRunInput(message, threadId, resourceId, parentContext) {
-    return { message, threadId, resourceId, context: parentContext };
-}
-export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode, parentContext) {
-    const singletonServices = getSingletonServices();
-    const tools = [];
-    const missingRpcs = [];
-    const approvalPolicy = streamContext?.options?.requiresToolApproval ?? 'explicit';
-    const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
-    if (!meta)
-        return { tools, missingRpcs };
-    /**
-     * A tool's description is what the model is told it does, and the main thing
-     * it chooses between tools on. It does not survive into the meta registered at
-     * boot: `description` is classed as a verbose field, so the bundled copy has
-     * it stripped and `fnMeta.description` is always undefined — every tool was
-     * being offered under its own bare name regardless of what its author wrote.
-     *
-     * `getFunctionsMeta` reads the verbose file and falls back to the minimal one,
-     * recovering the authored description wherever the generated `.pikku`
-     * directory is readable. Where it is not — no `metaService`, or a deployment
-     * shipping only the stripped copy — tools fall back to their name, which is
-     * what they did before this lookup existed.
-     */
-    const describedFunctions = await singletonServices.metaService
-        ?.getFunctionsMeta()
-        .catch(() => undefined);
-    const session = params.sessionService
-        ? await params.sessionService.get()
-        : null;
-    const metaTools = meta.tools;
-    const metaAgents = meta.agents;
-    if (metaTools?.length) {
-        for (const toolName of metaTools) {
-            let fnMeta;
-            let resolvedPkg = null;
-            let schemas;
-            const resolved = toolName.includes(':')
-                ? resolveNamespace(toolName)
-                : null;
-            let pikkuFuncId;
-            if (resolved) {
-                resolvedPkg = resolved.package;
-                pikkuFuncId = resolved.function;
-                fnMeta = pikkuState(resolvedPkg, 'function', 'meta')[pikkuFuncId];
-                schemas = pikkuState(resolvedPkg, 'misc', 'schemas');
-            }
-            else {
-                const rpcMeta = pikkuState(null, 'rpc', 'meta');
-                pikkuFuncId = rpcMeta[toolName];
-                if (!pikkuFuncId) {
-                    missingRpcs.push(toolName);
-                    continue;
-                }
-                fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
-                schemas = pikkuState(null, 'misc', 'schemas');
-            }
-            if (!fnMeta) {
-                missingRpcs.push(toolName);
-                continue;
-            }
-            if (fnMeta.permissions?.length) {
-                if (!session)
-                    continue;
-                const funcConfig = pikkuFuncId
-                    ? pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId)
-                    : undefined;
-                const allowed = await checkAuthPermissions(funcConfig?.permissions, session, singletonServices, resolvedPkg);
-                if (!allowed)
-                    continue;
-            }
-            const inputSchemaName = fnMeta?.inputSchemaName;
-            let inputSchema = inputSchemaName
-                ? schemas.get(inputSchemaName)
-                : undefined;
-            if (!inputSchema ||
-                (typeof inputSchema === 'object' &&
-                    inputSchema.type === 'object' &&
-                    !inputSchema.properties)) {
-                inputSchema = { type: 'object', properties: {} };
-            }
-            const needsApproval = approvalPolicy === 'all' ||
-                (approvalPolicy === 'explicit' && fnMeta?.approvalRequired);
-            let approvalDescriptionFn;
-            if (needsApproval && pikkuFuncId) {
-                const funcConfig = pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId);
-                if (funcConfig?.approvalDescription) {
-                    const descFn = funcConfig.approvalDescription;
-                    const capturedPkg = resolvedPkg;
-                    const capturedAddonConfig = resolved?.addonConfig;
-                    const capturedNamespace = toolName.includes(':')
-                        ? toolName.slice(0, toolName.indexOf(':'))
-                        : null;
-                    approvalDescriptionFn = async (input) => {
-                        let services = singletonServices;
-                        if (capturedPkg) {
-                            const addonInstance = capturedNamespace
-                                ? {
-                                    namespace: capturedNamespace,
-                                    secretOverrides: capturedAddonConfig?.secretOverrides,
-                                    variableOverrides: capturedAddonConfig?.variableOverrides,
-                                    credentialOverrides: capturedAddonConfig?.credentialOverrides,
-                                    secretGrants: capturedAddonConfig?.secretGrants,
-                                    credentialGrants: capturedAddonConfig?.credentialGrants,
-                                    globalSecrets: capturedAddonConfig?.globalSecrets,
-                                    globalCredentials: capturedAddonConfig?.globalCredentials,
-                                }
-                                : undefined;
-                            services = await getOrCreatePackageSingletonServices(capturedPkg, singletonServices, addonInstance);
-                        }
-                        return descFn(services, input);
-                    };
-                }
-            }
-            tools.push({
-                name: toolName.replaceAll('@', '_').replaceAll(':', '__'),
-                description: describedFunctions?.[pikkuFuncId]?.description ||
-                    fnMeta?.description ||
-                    toolName,
-                inputSchema,
-                needsApproval: needsApproval || undefined,
-                approvalDescriptionFn,
-                readonly: fnMeta?.readonly || undefined,
-                execute: async (toolInput) => {
-                    const wire = params.sessionService
-                        ? { ...createMiddlewareSessionWireProps(params.sessionService) }
-                        : {};
-                    const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
-                    return rpcService.rpc(toolName, toolInput);
-                },
-            });
-        }
-    }
-    if (metaAgents?.length) {
-        const allAgentsMeta = pikkuState(null, 'agent', 'agentsMeta');
-        for (const subAgentName of metaAgents) {
-            const subMeta = allAgentsMeta[subAgentName];
-            if (!subMeta) {
-                singletonServices.logger.warn(`Sub-agent '${subAgentName}' not found in agent registry`);
-                continue;
-            }
-            if (subMeta.permissions?.length) {
-                if (!session)
-                    continue;
-                const subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName);
-                const allowed = await checkAuthPermissions(subAgent?.permissions, session, singletonServices);
-                if (!allowed)
-                    continue;
-            }
-            tools.push({
-                name: subAgentName,
-                description: subMeta.description,
-                forwardsApproval: true,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        message: { type: 'string' },
-                        session: {
-                            type: 'string',
-                            description: 'Short session label for thread continuity',
-                        },
-                    },
-                    required: ['message', 'session'],
-                },
-                execute: async (toolInput) => {
-                    const { message, session } = toolInput;
-                    const sessionKey = `${subAgentName}::${session}`;
-                    let threadId = agentSessionMap.get(sessionKey);
-                    if (!threadId) {
-                        threadId = randomUUID();
-                        agentSessionMap.set(sessionKey, threadId);
-                    }
-                    if (streamContext) {
-                        const isDelegate = agentMode !== 'supervise';
-                        if (isDelegate && streamContext.delegateState) {
-                            streamContext.delegateState.delegated = true;
-                        }
-                        const { channel } = streamContext;
-                        channel.send({
-                            type: 'agent-call',
-                            agentName: subAgentName,
-                            session,
-                            input: message,
-                        });
-                        const subChannel = createScopedChannel(channel, subAgentName, session);
-                        const effectiveChannel = isDelegate
-                            ? subChannel
-                            : {
-                                ...subChannel,
-                                send: (event) => {
-                                    if (event.type === 'text-delta' ||
-                                        event.type === 'reasoning-delta')
-                                        return;
-                                    subChannel.send(event);
-                                },
-                            };
-                        const resultText = await streamAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
-                        if (subChannel.approvals.length > 0) {
-                            return {
-                                [APPROVAL_REQUIRED]: true,
-                                __approvalRequired: true,
-                                toolName: subAgentName,
-                                args: toolInput,
-                                agentRunId: subChannel.approvals[0].runId,
-                                subApprovals: subChannel.approvals,
-                            };
-                        }
-                        channel.send({
-                            type: 'agent-result',
-                            agentName: subAgentName,
-                            session,
-                            result: resultText,
-                        });
-                        return resultText;
-                    }
-                    const result = await runAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), params, agentSessionMap);
-                    if (result.status === 'suspended' &&
-                        result.pendingApprovals?.length) {
-                        return {
-                            [APPROVAL_REQUIRED]: true,
-                            __approvalRequired: true,
-                            toolName: subAgentName,
-                            args: toolInput,
-                            agentRunId: result.runId,
-                            subApprovals: result.pendingApprovals.map((a) => ({
-                                toolCallId: a.toolCallId,
-                                toolName: a.toolName,
-                                args: a.args,
-                                reason: a.reason,
-                                runId: a.runId,
-                            })),
-                        };
-                    }
-                    return result.object ?? result.text;
-                },
-            });
-        }
-    }
-    const metaWorkflows = meta.workflows;
-    if (metaWorkflows?.length) {
-        const workflowMetaMap = pikkuState(null, 'workflows', 'meta');
-        const functionMeta = pikkuState(null, 'function', 'meta');
-        const schemas = pikkuState(null, 'misc', 'schemas');
-        for (const workflowName of metaWorkflows) {
-            const wfMeta = workflowMetaMap[workflowName];
-            if (!wfMeta) {
-                missingRpcs.push(workflowName);
-                continue;
-            }
-            const inputSchemaName = wfMeta.pikkuFuncId
-                ? functionMeta[wfMeta.pikkuFuncId]?.inputSchemaName
-                : undefined;
-            let inputSchema = inputSchemaName
-                ? schemas.get(inputSchemaName)
-                : undefined;
-            if (!inputSchema ||
-                (typeof inputSchema === 'object' &&
-                    inputSchema.type === 'object' &&
-                    !inputSchema.properties)) {
-                inputSchema = { type: 'object', properties: {} };
-            }
-            tools.push({
-                name: workflowName,
-                description: wfMeta.description || workflowName,
-                inputSchema,
-                execute: async (toolInput) => {
-                    const workflowService = singletonServices.workflowService;
-                    if (!workflowService) {
-                        throw new Error(`workflowService is not configured — cannot run workflow tool '${workflowName}'`);
-                    }
-                    const wire = params.sessionService
-                        ? { ...createMiddlewareSessionWireProps(params.sessionService) }
-                        : {};
-                    const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
-                    return workflowService.runToCompletion(workflowName, toolInput, rpcService, { wire: { type: 'internal' } });
-                },
-            });
-        }
-    }
-    for (const tool of tools) {
-        const originalExecute = tool.execute;
-        tool.execute = async (toolInput) => {
-            try {
-                return await originalExecute(toolInput);
-            }
-            catch (err) {
-                if (err?.payload?.error === 'missing_credential') {
-                    return {
-                        [CREDENTIAL_REQUIRED]: true,
-                        __credentialRequired: true,
-                        ...err.payload,
-                    };
-                }
-                singletonServices.logger.error(`AI agent tool '${tool.name}' threw during execute()`, err);
-                throw err;
-            }
-        };
-    }
-    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;
-                    if (err?.payload?.error === 'missing_credential')
-                        throw 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 = getSingletonServices();
-    const { agent, packageName, resolvedName } = resolveAgent(agentName);
-    await assertAgentAuthorized(agent, params, packageName);
-    let agentRunner = singletonServices.aiAgentRunner;
-    if (!agentRunner) {
-        throw new AIProviderNotConfiguredError();
-    }
-    if (params.getCredential && agentRunner.withApiKey) {
-        const aiCredential = await params.getCredential('AI_API_KEY');
-        if (aiCredential?.apiKey?.trim()) {
-            agentRunner = agentRunner.withApiKey(aiCredential.apiKey);
-        }
-    }
-    const { storage } = resolveMemoryServices(agent, singletonServices);
-    const memoryConfig = agent.memory;
-    const threadId = input.threadId;
-    const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
-    const meta = agentsMeta[resolvedName];
-    const outputSchemaName = meta?.outputSchema;
-    const outputSchema = outputSchemaName
-        ? pikkuState(packageName, 'misc', 'schemas').get(outputSchemaName)
-        : undefined;
-    const workingMemorySchemaName = meta?.workingMemorySchema ?? null;
-    const workingMemoryJsonSchema = workingMemorySchemaName
-        ? pikkuState(packageName, 'misc', 'schemas').get(workingMemorySchemaName)
-        : undefined;
-    if (storage) {
-        let thread = null;
-        try {
-            thread = await storage.getThread(threadId);
-        }
-        catch {
-            thread = null;
-        }
-        if (thread) {
-            assertResourceOwner(input.resourceId, thread.resourceId, 'thread');
-        }
-        else {
-            await storage.createThread(input.resourceId, { threadId });
-        }
-    }
-    let messages = [];
-    if (storage) {
-        // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
-        await awaitPendingInterruptNote(threadId);
-        messages = await storage.getMessages(threadId, {
-            lastN: memoryConfig?.lastMessages ?? 20,
-        });
-    }
-    const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
-    const userContent = input.attachments?.length
-        ? [
-            // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
-            ...(input.message
-                ? [{ type: 'text', text: input.message }]
-                : []),
-            ...input.attachments.map((a) => ({
-                type: a.type,
-                data: a.data,
-                url: a.url,
-                mediaType: a.mediaType,
-                ...(a.filename ? { filename: a.filename } : {}),
-            })),
-        ]
-        : input.message;
-    const userMessage = {
-        id: randomUUID(),
-        role: 'user',
-        content: userContent,
-        createdAt: new Date(),
-    };
-    const allMessages = [...contextMessages, ...messages, userMessage];
-    const trimmedMessages = trimMessages(allMessages);
-    const aiMiddlewares = agent.aiMiddleware ?? [];
-    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode, input.context);
-    let instructions = await buildInstructions(resolvedName, packageName);
-    if (input.context) {
-        instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;
-    }
-    const resolved = resolveModelConfig(resolvedName, agent);
-    if (input.model) {
-        resolved.model = resolveModelConfig(resolvedName, {
-            ...agent,
-            model: input.model,
-        }).model;
-    }
-    if (input.temperature !== undefined) {
-        resolved.temperature = input.temperature;
-    }
-    const maxSteps = resolved.maxSteps ?? 10;
-    const runnerParams = {
-        model: resolved.model,
-        temperature: resolved.temperature,
-        instructions,
-        messages: trimmedMessages,
-        tools,
-        maxSteps: 1,
-        toolChoice: agent.toolChoice ?? 'auto',
-        providerOptions: agent.providerOptions,
-        outputSchema,
-    };
-    return {
-        agent,
-        packageName,
-        resolvedName,
-        agentRunner,
-        storage,
-        memoryConfig,
-        threadId,
-        userMessage,
-        runnerParams,
-        maxSteps,
-        missingRpcs,
-        workingMemoryJsonSchema,
-        workingMemorySchemaName,
-    };
-}