@cogitator-ai/core 0.23.0 → 0.25.0

package/dist/runtime.js

@@ -1,10 +1,11 @@
 import { nanoid } from 'nanoid';
-import { getPrice } from '@cogitator-ai/models';
+import { calculateCost as calculateModelCost } from '@cogitator-ai/models';
 import { ToolRegistry } from './registry.js';
 import { createLLMBackend, parseModel } from './llm/index.js';
 import { isLLMProvider } from './llm/providers.js';
 import { createLLMBackendFromPlugin, hasLLMPlugin } from './llm/plugin.js';
 import { withLLMRetry } from './llm/retry.js';
+import { PiiMasker, withPiiMasking } from './security/pii.js';
 import { getLogger } from './logger.js';
 import { initializeMemory, initializeSandbox, initializeReflection, initializeGuardrails, initializeCostRouting, initializeSecurity, initializeContextManager, cleanupState, } from './cogitator/initializers.js';
 import { CogitatorError, ErrorCode } from '@cogitator-ai/types';
@@ -13,8 +14,12 @@ import { createSpan, getTextContent } from './cogitator/span-factory.js';
 import { executeTool, createToolMessage } from './cogitator/tool-executor.js';
 import { streamChat } from './cogitator/streaming.js';
 import { RunLimiter } from './cogitator/run-limiter.js';
-import { parseStructuredOutput, toLLMResponseFormat } from './cogitator/response-format.js';
+import { findHandoffAgent, handoffTools } from './cogitator/handoffs.js';
+import { PromptRegistry } from './cogitator/prompts.js';
+import { InMemoryRunCheckpointStore, ThreadRunCheckpointStore } from './cogitator/run-checkpoints.js';
+import { parseStructuredOutput, structuredOutputProblem, toLLMResponseFormat, } from './cogitator/response-format.js';
 import { CostEstimator } from './cost-routing/cost-estimator.js';
+import { readEnv } from './utils/env.js';
 /** Run timeout when neither the run, the agent nor `limits.defaultTimeout` sets one. */
 const DEFAULT_RUN_TIMEOUT = 120_000;
 /**
@@ -68,6 +73,9 @@ const DEFAULT_RUN_TIMEOUT = 120_000;
 export class Cogitator {
     config;
     backends = new Map();
+    processCheckpoints;
+    promptRegistry;
+    threadCheckpoints;
     /** Global tool registry shared across all runs */
     tools = new ToolRegistry();
     state = {
@@ -81,6 +89,7 @@ export class Cogitator {
     };
     costEstimator;
     initPromise;
+    memoryInit;
     runLimiter;
     /**
      * Create a new Cogitator runtime.
@@ -131,7 +140,45 @@ export class Cogitator {
      * ```
      */
     async run(agent, options) {
-        const runId = `run_${nanoid(12)}`;
+        return this.execute(agent, options);
+    }
+    /**
+     * Continue a run that paused for tool approvals (`status: 'paused'`) from its
+     * `checkpoint`. Approved calls run, declined ones answer the model with the
+     * reason, and the run goes on; calls without a decision pause it again.
+     *
+     * @example
+     * ```ts
+     * const paused = await cog.run(agent, { input: 'Refund order 42' });
+     * if (paused.status === 'paused') {
+     *   await store.save(paused.checkpoint);
+     *   // ... later, once someone approved it
+     *   const result = await cog.resume(agent, checkpoint, {
+     *     decisions: { [paused.pendingApprovals[0].toolCallId]: { approved: true } },
+     *   });
+     * }
+     * ```
+     */
+    async resume(agent, target, options = {}) {
+        if (typeof target !== 'string' && target.version !== 1) {
+            throw new CogitatorError({
+                message: `Unsupported run checkpoint version: ${String(target.version)}`,
+                code: ErrorCode.VALIDATION_ERROR,
+            });
+        }
+        const { decisions = {}, defaultDecision, userId, ...rest } = options;
+        const threadId = typeof target === 'string' ? target : target.threadId;
+        return this.execute(agent, { ...rest, input: '', threadId, ...(userId !== undefined && { userId }) }, {
+            ...(typeof target === 'string' ? {} : { checkpoint: target }),
+            decisions,
+            ...(defaultDecision && { defaultDecision }),
+            checkUser: typeof target === 'string' || userId !== undefined,
+        });
+    }
+    async execute(agent, options, resumeFrom) {
+        let checkpoint = resumeFrom?.checkpoint;
+        let prompt;
+        let runId = checkpoint?.runId ?? `run_${nanoid(12)}`;
         const threadId = options.threadId ?? `thread_${nanoid(12)}`;
         const traceId = `trace_${nanoid(16)}`;
         const startTime = Date.now();
@@ -167,69 +214,109 @@ export class Cogitator {
         try {
             releaseRunSlot = await this.acquireRunSlot(abortController.signal);
             throwIfAborted(abortController.signal);
-            options.onRunStart?.({ runId, agentId: agent.id, input: options.input, threadId });
+            if (!checkpoint) {
+                options.onRunStart?.({ runId, agentId: agent.id, input: options.input, threadId });
+            }
             const agentModel = this.resolveModel(agent);
             await this.initializeAll(agentModel);
-            const input = await buildInputWithAudio(options.input, options.audio, {
-                apiKey: this.config.llm?.providers?.openai?.apiKey ?? process.env.OPENAI_API_KEY,
-                signal: abortController.signal,
-            });
-            const runOptions = input === options.input ? options : { ...options, input };
-            const registry = new ToolRegistry();
-            registry.registerMany(this.tools.getAll());
-            if (agent.tools && agent.tools.length > 0) {
-                registry.registerMany(agent.tools);
-            }
-            let effectiveModel = agentModel;
-            let backend;
-            let model;
-            if (this.state.costRouter && this.config.costRouting?.autoSelectModel) {
-                const recommendation = await this.state.costRouter.recommendModel(input);
-                effectiveModel = `${recommendation.provider}/${recommendation.modelId}`;
-                const budgetCheck = this.state.costRouter.checkBudget(recommendation.estimatedCost);
-                if (!budgetCheck.allowed) {
-                    throw new Error(`Budget exceeded: ${budgetCheck.reason}`);
+            if (resumeFrom) {
+                checkpoint ??= (await this.runCheckpointStore().load(threadId)) ?? undefined;
+                if (!checkpoint) {
+                    throw new CogitatorError({
+                        message: `Thread ${threadId} has no paused run`,
+                        code: ErrorCode.RUN_NOT_PAUSED,
+                    });
                 }
-                backend = this.getBackend(effectiveModel, recommendation.provider);
-                model = recommendation.modelId;
-            }
-            else {
-                ({ backend, model } = this.route(effectiveModel, agent.config.provider));
-            }
-            const messages = await buildInitialMessages(agent, runOptions, threadId, this.state.memoryAdapter, this.state.contextBuilder);
-            if (this.state.injectionDetector) {
-                const injectionResult = await this.state.injectionDetector.analyze(input);
-                if (injectionResult.action === 'blocked') {
-                    const threatTypes = injectionResult.threats.map((t) => t.type).join(', ');
+                if (resumeFrom.checkUser && checkpoint.userId !== options.userId) {
                     throw new CogitatorError({
-                        message: `Prompt injection detected: ${threatTypes}`,
-                        code: ErrorCode.PROMPT_INJECTION_DETECTED,
-                        details: { threats: injectionResult.threats },
+                        message: `The paused run in thread ${threadId} belongs to another user`,
+                        code: ErrorCode.THREAD_ACCESS_DENIED,
                     });
                 }
+                runId = checkpoint.runId;
+                options = { ...options, userId: checkpoint.userId };
             }
-            if (this.state.constitutionalAI?.config.filterInput) {
-                const inputResult = await this.state.constitutionalAI.filterInput(input);
-                if (!inputResult.allowed) {
-                    throw new Error(`Input blocked: ${inputResult.blockedReason ?? 'Policy violation'}`);
+            prompt = checkpoint?.prompt;
+            if (!checkpoint && (this.config.prompts || this.promptRegistry)) {
+                const resolution = await this.prompts.resolve(agent, threadId);
+                prompt = resolution.prompt;
+                if (resolution.instructions !== agent.instructions) {
+                    agent = agent.clone({ id: agent.id, instructions: resolution.instructions });
                 }
             }
-            if (options.context) {
-                addContextToMessages(messages, options.context);
+            let active = agent;
+            if (checkpoint?.activeAgent && checkpoint.activeAgent !== agent.name) {
+                const found = findHandoffAgent(agent, checkpoint.activeAgent);
+                if (!found) {
+                    throw new CogitatorError({
+                        message: `The paused run is in agent "${checkpoint.activeAgent}", which ${agent.name} cannot hand over to`,
+                        code: ErrorCode.VALIDATION_ERROR,
+                    });
+                }
+                active = found;
+            }
+            const handoffs = [...(checkpoint?.handoffs ?? [])];
+            const buildRegistry = (owner) => {
+                const ownerRegistry = new ToolRegistry();
+                ownerRegistry.registerMany(this.tools.getAll());
+                if (owner.tools.length > 0)
+                    ownerRegistry.registerMany(owner.tools);
+                const handoff = handoffTools(owner);
+                ownerRegistry.registerMany(handoff.tools);
+                return { registry: ownerRegistry, targets: handoff.targets };
+            };
+            let { registry, targets: handoffTargets } = buildRegistry(active);
+            let effectiveModel = agentModel;
+            let routeProvider = agent.config.provider;
+            let backend;
+            let model;
+            let input;
+            let messages;
+            if (checkpoint) {
+                input = checkpoint.input;
+                effectiveModel = checkpoint.model;
+                routeProvider = checkpoint.provider;
+                ({ backend, model } = this.route(effectiveModel, routeProvider));
+                messages = [...checkpoint.messages];
             }
-            if (this.state.memoryAdapter &&
-                options.saveHistory !== false &&
-                options.useMemory !== false) {
-                const currentUserMessage = messages[messages.length - 1];
-                await saveEntry(threadId, agent.id, currentUserMessage, this.state.memoryAdapter, undefined, undefined, options.onMemoryError, options.userId);
+            else {
+                input = await buildInputWithAudio(options.input, options.audio, {
+                    apiKey: this.config.llm?.providers?.openai?.apiKey ??
+                        (options.audio?.length ? readEnv('OPENAI_API_KEY') : undefined),
+                    signal: abortController.signal,
+                });
+                const runOptions = input === options.input ? options : { ...options, input };
+                if (this.state.costRouter && this.config.costRouting?.autoSelectModel) {
+                    const recommendation = await this.state.costRouter.recommendModel(input);
+                    effectiveModel = `${recommendation.provider}/${recommendation.modelId}`;
+                    routeProvider = recommendation.provider;
+                    const budgetCheck = this.state.costRouter.checkBudget(recommendation.estimatedCost);
+                    if (!budgetCheck.allowed) {
+                        throw new Error(`Budget exceeded: ${budgetCheck.reason}`);
+                    }
+                    backend = this.getBackend(effectiveModel, recommendation.provider);
+                    model = recommendation.modelId;
+                }
+                else {
+                    ({ backend, model } = this.route(effectiveModel, agent.config.provider));
+                }
+                await this.abandonPausedRun(agent, runOptions, threadId);
+                messages = await this.prepareMessages(agent, runOptions, input, threadId);
             }
-            const allToolCalls = [];
-            let totalInputTokens = 0;
-            let totalOutputTokens = 0;
-            let iterations = 0;
+            const allToolCalls = [...(checkpoint?.toolCalls ?? [])];
+            let totalInputTokens = checkpoint?.usage.inputTokens ?? 0;
+            let totalOutputTokens = checkpoint?.usage.outputTokens ?? 0;
+            let cachedInputTokens = checkpoint?.usage.cachedInputTokens ?? 0;
+            let cacheWriteTokens = checkpoint?.usage.cacheWriteTokens ?? 0;
+            let reasoningTokens = checkpoint?.usage.reasoningTokens ?? 0;
+            const reasoningParts = [...(checkpoint?.reasoning ?? [])];
+            let reasoning = options.reasoning ?? active.config.reasoning;
+            const promptCache = this.config.llm?.promptCache ?? {};
+            let iterations = checkpoint?.iterations ?? 0;
             const maxIterations = agent.config?.maxIterations ?? 10;
-            let lastToolCallSig = '';
-            const responseFormat = toLLMResponseFormat(agent.config.responseFormat);
+            let lastToolCallSig = checkpoint?.lastToolCallSignature ?? '';
+            let pausedTurn;
+            let responseFormat = toLLMResponseFormat(active.config.responseFormat);
             const allReflections = [];
             const allActions = [];
             const agentContext = {
@@ -242,10 +329,191 @@ export class Cogitator {
                 previousActions: [],
                 availableTools: registry.getNames(),
             };
-            if (this.state.reflectionEngine && this.config.reflection?.enabled) {
+            if (!checkpoint && this.state.reflectionEngine && this.config.reflection?.enabled) {
                 await enrichMessagesWithInsights(messages, this.state.reflectionEngine, agentContext);
             }
-            while (iterations < maxIterations) {
+            const switchTo = (target, reason) => {
+                const event = {
+                    from: active.name,
+                    to: target.name,
+                    ...(typeof reason === 'string' && reason && { reason }),
+                };
+                handoffs.push(event);
+                options.onHandoff?.(event);
+                const system = messages[0];
+                const content = system?.role === 'system' &&
+                    typeof system.content === 'string' &&
+                    system.content.startsWith(active.instructions)
+                    ? target.instructions + system.content.slice(active.instructions.length)
+                    : target.instructions;
+                if (system?.role === 'system')
+                    messages[0] = { role: 'system', content };
+                else
+                    messages.unshift({ role: 'system', content });
+                spans.push(createSpan('agent.handoff', traceId, rootSpanId, Date.now(), Date.now(), { 'handoff.from': event.from, 'handoff.to': event.to }, 'ok', 'internal', options.onSpan));
+                active = target;
+                ({ registry, targets: handoffTargets } = buildRegistry(target));
+                effectiveModel = this.resolveModel(target);
+                routeProvider = target.config.provider;
+                ({ backend, model } = this.route(effectiveModel, routeProvider));
+                reasoning = options.reasoning ?? target.config.reasoning;
+                responseFormat = toLLMResponseFormat(target.config.responseFormat);
+                lastToolCallSig = '';
+            };
+            const handleToolTurn = async (toolCalls, resumed) => {
+                if (!resumed) {
+                    const currentSig = toolCalls
+                        .map((tc) => `${tc.name}:${JSON.stringify(tc.arguments)}`)
+                        .join('|');
+                    if (currentSig === lastToolCallSig) {
+                        for (const tc of toolCalls) {
+                            const errorResult = {
+                                callId: tc.id,
+                                name: tc.name,
+                                result: null,
+                                error: 'Duplicate tool call detected. Try a different approach.',
+                            };
+                            const duplicateMessage = createToolMessage(tc, errorResult);
+                            messages.push(duplicateMessage);
+                            if (this.state.memoryAdapter &&
+                                options.saveHistory !== false &&
+                                options.useMemory !== false) {
+                                await saveEntry(threadId, active.id, duplicateMessage, this.state.memoryAdapter, undefined, [errorResult], options.onMemoryError, options.userId);
+                            }
+                        }
+                        lastToolCallSig = '';
+                        return undefined;
+                    }
+                    lastToolCallSig = currentSig;
+                    for (const toolCall of toolCalls) {
+                        allToolCalls.push(toolCall);
+                        options.onToolCall?.(toolCall);
+                    }
+                }
+                const decisions = new Map(Object.entries(resumed?.decisions ?? {}));
+                const pending = [];
+                for (const toolCall of toolCalls) {
+                    const tool = registry.get(toolCall.name);
+                    if (!tool || decisions.has(toolCall.id) || !needsApproval(tool, toolCall.arguments)) {
+                        continue;
+                    }
+                    const request = {
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        arguments: toolCall.arguments,
+                        description: tool.description,
+                        ...(tool.sideEffects && { sideEffects: [...tool.sideEffects] }),
+                    };
+                    const decision = resumed?.fallback ?? (await this.decideApproval(request, options));
+                    if (decision === 'pause')
+                        pending.push(request);
+                    else
+                        decisions.set(toolCall.id, decision);
+                }
+                if (pending.length > 0) {
+                    return { toolCalls, decisions: Object.fromEntries(decisions), pending };
+                }
+                if (resumed)
+                    await this.runCheckpointStore().delete(threadId);
+                const executeToolCall = async (toolCall) => {
+                    const toolSpanStart = Date.now();
+                    const decision = decisions.get(toolCall.id);
+                    if (decision?.approved === false) {
+                        const declined = {
+                            callId: toolCall.id,
+                            name: toolCall.name,
+                            result: null,
+                            error: `The user declined this tool call${decision.reason ? `: ${decision.reason}` : ''}`,
+                        };
+                        return { toolCall, result: declined, toolSpanStart, toolSpanEnd: Date.now() };
+                    }
+                    const result = await waitForAbortable(executeTool(registry, toolCall, runId, active.id, this.state.sandboxManager, this.state.constitutionalAI, this.state.constitutionalAI?.config.filterToolCalls ?? false, () => initializeSandbox(this.config, this.state), abortController.signal, {
+                        threadId,
+                        userId: options.userId,
+                        channelType: options.channelType,
+                        channelId: options.channelId,
+                    }, decision?.approved === true), abortController.signal);
+                    const toolSpanEnd = Date.now();
+                    return { toolCall, result, toolSpanStart, toolSpanEnd };
+                };
+                const toolResults = options.parallelToolCalls
+                    ? await Promise.all(toolCalls.map(executeToolCall))
+                    : await (async () => {
+                        const results = [];
+                        for (const toolCall of toolCalls) {
+                            results.push(await executeToolCall(toolCall));
+                        }
+                        return results;
+                    })();
+                const reflectionMessages = [];
+                for (const { toolCall, result, toolSpanStart, toolSpanEnd } of toolResults) {
+                    const toolSpan = createSpan(`tool.${toolCall.name}`, traceId, rootSpanId, toolSpanStart, toolSpanEnd, {
+                        'tool.name': toolCall.name,
+                        'tool.call_id': toolCall.id,
+                        'tool.arguments': JSON.stringify(toolCall.arguments),
+                        'tool.success': !result.error,
+                        'tool.error': result.error,
+                    }, result.error ? 'error' : 'ok', 'internal', options.onSpan);
+                    spans.push(toolSpan);
+                    options.onToolResult?.(result);
+                    const toolMessage = createToolMessage(toolCall, result);
+                    messages.push(toolMessage);
+                    if (this.state.memoryAdapter &&
+                        options.saveHistory !== false &&
+                        options.useMemory !== false) {
+                        await saveEntry(threadId, active.id, toolMessage, this.state.memoryAdapter, undefined, [result], options.onMemoryError, options.userId);
+                    }
+                    const action = {
+                        type: 'tool_call',
+                        toolName: toolCall.name,
+                        input: toolCall.arguments,
+                        output: result.result,
+                        error: result.error,
+                        duration: toolSpanEnd - toolSpanStart,
+                    };
+                    allActions.push(action);
+                    const reflection = this.config.reflection;
+                    const reflectOnFailure = action.error !== undefined && !!reflection?.reflectAfterError;
+                    if (this.state.reflectionEngine &&
+                        reflection?.enabled &&
+                        (reflectOnFailure || reflection.reflectAfterToolCall)) {
+                        try {
+                            const reflectionResult = reflectOnFailure
+                                ? await this.state.reflectionEngine.reflectOnError(action, agentContext)
+                                : await this.state.reflectionEngine.reflectOnToolCall(action, agentContext);
+                            allReflections.push(reflectionResult.reflection);
+                            if (reflectionResult.shouldAdjustStrategy && reflectionResult.suggestedAction) {
+                                reflectionMessages.push({
+                                    role: 'system',
+                                    content: `Reflection: ${reflectionResult.reflection.analysis.reasoning}. Consider: ${reflectionResult.suggestedAction}`,
+                                });
+                            }
+                        }
+                        catch (reflectionError) {
+                            getLogger().warn('Reflection failed', {
+                                error: reflectionError instanceof Error
+                                    ? reflectionError.message
+                                    : String(reflectionError),
+                            });
+                        }
+                    }
+                }
+                messages.push(...reflectionMessages);
+                const handoff = toolCalls.find((call) => handoffTargets.has(call.name));
+                const target = handoff && handoffTargets.get(handoff.name);
+                if (handoff && target)
+                    switchTo(target, handoff.arguments.reason);
+                return undefined;
+            };
+            if (checkpoint && resumeFrom) {
+                pausedTurn = await handleToolTurn(checkpoint.turn.toolCalls, {
+                    decisions: { ...checkpoint.turn.decisions, ...resumeFrom.decisions },
+                    fallback: resumeFrom.defaultDecision,
+                });
+            }
+            const streaming = Boolean(options.stream && options.onToken);
+            let structuredRepaired = false;
+            while (!pausedTurn && iterations < maxIterations) {
                 throwIfAborted(abortController.signal);
                 this.assertTokenBudget(totalInputTokens + totalOutputTokens);
                 if (this.state.contextManager?.shouldCompress(messages, effectiveModel)) {
@@ -258,19 +526,21 @@ export class Cogitator {
                 agentContext.previousActions = [...allActions];
                 const llmSpanStart = Date.now();
                 let response;
-                if (options.stream && options.onToken) {
-                    response = await waitForAbortable(streamChat(backend, model, messages, registry, agent, options.onToken, abortController.signal, responseFormat), abortController.signal);
+                if (streaming && options.onToken) {
+                    response = await waitForAbortable(streamChat(backend, model, messages, registry, active, options.onToken, abortController.signal, responseFormat, { reasoning, cache: promptCache, onReasoning: options.onReasoning }), abortController.signal);
                 }
                 else {
                     response = await waitForAbortable(backend.chat({
                         model,
                         messages,
                         tools: registry.getSchemas(),
-                        temperature: agent.config.temperature,
-                        topP: agent.config.topP,
-                        maxTokens: agent.config.maxTokens,
-                        stop: agent.config.stopSequences,
+                        temperature: active.config.temperature,
+                        topP: active.config.topP,
+                        maxTokens: active.config.maxTokens,
+                        stop: active.config.stopSequences,
                         responseFormat,
+                        reasoning,
+                        cache: promptCache,
                         signal: abortController.signal,
                     }), abortController.signal);
                 }
@@ -279,11 +549,22 @@ export class Cogitator {
                     'llm.iteration': iterations,
                     'llm.input_tokens': response.usage.inputTokens,
                     'llm.output_tokens': response.usage.outputTokens,
+                    ...(response.usage.cachedInputTokens && {
+                        'llm.cached_input_tokens': response.usage.cachedInputTokens,
+                    }),
+                    ...(response.usage.reasoningTokens && {
+                        'llm.reasoning_tokens': response.usage.reasoningTokens,
+                    }),
                     'llm.finish_reason': response.finishReason,
                 }, 'ok', 'client', options.onSpan);
                 spans.push(llmSpan);
                 totalInputTokens += response.usage.inputTokens;
                 totalOutputTokens += response.usage.outputTokens;
+                cachedInputTokens += response.usage.cachedInputTokens ?? 0;
+                cacheWriteTokens += response.usage.cacheWriteTokens ?? 0;
+                reasoningTokens += response.usage.reasoningTokens ?? 0;
+                if (response.reasoning)
+                    reasoningParts.push(response.reasoning);
                 let outputContent = response.content;
                 if (this.state.constitutionalAI?.config.filterOutput) {
                     const outputResult = await this.state.constitutionalAI.filterOutput(outputContent, messages);
@@ -304,125 +585,93 @@ export class Cogitator {
                     }
                     : { role: 'assistant', content: outputContent };
                 messages.push(assistantMessage);
+                const finalAnswer = !(response.finishReason === 'tool_calls' &&
+                    response.toolCalls &&
+                    response.toolCalls.length > 0);
+                const structuredProblem = finalAnswer && !streaming && !structuredRepaired && iterations < maxIterations
+                    ? structuredOutputProblem(active.config.responseFormat, outputContent)
+                    : undefined;
+                if (structuredProblem) {
+                    structuredRepaired = true;
+                    messages.push({
+                        role: 'user',
+                        content: `Your answer does not match the required response format (${structuredProblem}). Reply again with only the corrected JSON.`,
+                    });
+                    continue;
+                }
                 if (this.state.memoryAdapter &&
                     options.saveHistory !== false &&
                     options.useMemory !== false) {
-                    await saveEntry(threadId, agent.id, assistantMessage, this.state.memoryAdapter, response.toolCalls, undefined, options.onMemoryError, options.userId);
-                }
-                if (response.finishReason === 'tool_calls' &&
-                    response.toolCalls &&
-                    response.toolCalls.length > 0) {
-                    let toolCalls = response.toolCalls;
-                    const currentSig = toolCalls
-                        .map((tc) => `${tc.name}:${JSON.stringify(tc.arguments)}`)
-                        .join('|');
-                    if (currentSig === lastToolCallSig) {
-                        for (const tc of toolCalls) {
-                            const errorResult = {
-                                callId: tc.id,
-                                name: tc.name,
-                                result: null,
-                                error: 'Duplicate tool call detected. Try a different approach.',
-                            };
-                            const duplicateMessage = createToolMessage(tc, errorResult);
-                            messages.push(duplicateMessage);
-                            if (this.state.memoryAdapter &&
-                                options.saveHistory !== false &&
-                                options.useMemory !== false) {
-                                await saveEntry(threadId, agent.id, duplicateMessage, this.state.memoryAdapter, undefined, [errorResult], options.onMemoryError, options.userId);
-                            }
-                        }
-                        lastToolCallSig = '';
-                        continue;
-                    }
-                    lastToolCallSig = currentSig;
-                    for (const toolCall of toolCalls) {
-                        allToolCalls.push(toolCall);
-                        options.onToolCall?.(toolCall);
-                    }
-                    const executeToolCall = async (toolCall) => {
-                        const toolSpanStart = Date.now();
-                        const result = await waitForAbortable(executeTool(registry, toolCall, runId, agent.id, this.state.sandboxManager, this.state.constitutionalAI, this.state.constitutionalAI?.config.filterToolCalls ?? false, () => initializeSandbox(this.config, this.state), abortController.signal, {
-                            threadId,
-                            userId: options.userId,
-                            channelType: options.channelType,
-                            channelId: options.channelId,
-                        }), abortController.signal);
-                        const toolSpanEnd = Date.now();
-                        return { toolCall, result, toolSpanStart, toolSpanEnd };
-                    };
-                    const toolResults = options.parallelToolCalls
-                        ? await Promise.all(toolCalls.map(executeToolCall))
-                        : await (async () => {
-                            const results = [];
-                            for (const toolCall of toolCalls) {
-                                results.push(await executeToolCall(toolCall));
-                            }
-                            return results;
-                        })();
-                    const reflectionMessages = [];
-                    for (const { toolCall, result, toolSpanStart, toolSpanEnd } of toolResults) {
-                        const toolSpan = createSpan(`tool.${toolCall.name}`, traceId, rootSpanId, toolSpanStart, toolSpanEnd, {
-                            'tool.name': toolCall.name,
-                            'tool.call_id': toolCall.id,
-                            'tool.arguments': JSON.stringify(toolCall.arguments),
-                            'tool.success': !result.error,
-                            'tool.error': result.error,
-                        }, result.error ? 'error' : 'ok', 'internal', options.onSpan);
-                        spans.push(toolSpan);
-                        options.onToolResult?.(result);
-                        const toolMessage = createToolMessage(toolCall, result);
-                        messages.push(toolMessage);
-                        if (this.state.memoryAdapter &&
-                            options.saveHistory !== false &&
-                            options.useMemory !== false) {
-                            await saveEntry(threadId, agent.id, toolMessage, this.state.memoryAdapter, undefined, [result], options.onMemoryError, options.userId);
-                        }
-                        const action = {
-                            type: 'tool_call',
-                            toolName: toolCall.name,
-                            input: toolCall.arguments,
-                            output: result.result,
-                            error: result.error,
-                            duration: toolSpanEnd - toolSpanStart,
-                        };
-                        allActions.push(action);
-                        const reflection = this.config.reflection;
-                        const reflectOnFailure = action.error !== undefined && !!reflection?.reflectAfterError;
-                        if (this.state.reflectionEngine &&
-                            reflection?.enabled &&
-                            (reflectOnFailure || reflection.reflectAfterToolCall)) {
-                            try {
-                                const reflectionResult = reflectOnFailure
-                                    ? await this.state.reflectionEngine.reflectOnError(action, agentContext)
-                                    : await this.state.reflectionEngine.reflectOnToolCall(action, agentContext);
-                                allReflections.push(reflectionResult.reflection);
-                                if (reflectionResult.shouldAdjustStrategy && reflectionResult.suggestedAction) {
-                                    reflectionMessages.push({
-                                        role: 'system',
-                                        content: `Reflection: ${reflectionResult.reflection.analysis.reasoning}. Consider: ${reflectionResult.suggestedAction}`,
-                                    });
-                                }
-                            }
-                            catch (reflectionError) {
-                                getLogger().warn('Reflection failed', {
-                                    error: reflectionError instanceof Error
-                                        ? reflectionError.message
-                                        : String(reflectionError),
-                                });
-                            }
-                        }
-                    }
-                    messages.push(...reflectionMessages);
+                    await saveEntry(threadId, active.id, assistantMessage, this.state.memoryAdapter, response.toolCalls, undefined, options.onMemoryError, options.userId);
                 }
-                else {
+                if (finalAnswer || !response.toolCalls)
                     break;
-                }
+                pausedTurn = await handleToolTurn(response.toolCalls);
+                if (pausedTurn)
+                    break;
+            }
+            if (pausedTurn) {
+                const pausedCheckpoint = {
+                    version: 1,
+                    runId,
+                    agentId: active.id,
+                    threadId,
+                    ...(options.userId !== undefined && { userId: options.userId }),
+                    model: effectiveModel,
+                    ...(routeProvider !== undefined && { provider: routeProvider }),
+                    input,
+                    messages,
+                    toolCalls: allToolCalls,
+                    ...(prompt && { prompt }),
+                    ...(active !== agent && { activeAgent: active.name }),
+                    ...(handoffs.length > 0 && { handoffs }),
+                    turn: { toolCalls: pausedTurn.toolCalls, decisions: pausedTurn.decisions },
+                    iterations,
+                    lastToolCallSignature: lastToolCallSig,
+                    usage: {
+                        inputTokens: totalInputTokens,
+                        outputTokens: totalOutputTokens,
+                        cachedInputTokens,
+                        cacheWriteTokens,
+                        reasoningTokens,
+                    },
+                    reasoning: reasoningParts,
+                    startedAt: checkpoint?.startedAt ?? startTime,
+                };
+                const paused = {
+                    output: getTextContent(messages[messages.length - 1]?.content ?? ''),
+                    runId,
+                    agentId: agent.id,
+                    threadId,
+                    status: 'paused',
+                    pendingApprovals: pausedTurn.pending,
+                    ...(handoffs.length > 0 && { handoffs, finalAgent: active.name }),
+                    checkpoint: pausedCheckpoint,
+                    usage: {
+                        inputTokens: totalInputTokens,
+                        outputTokens: totalOutputTokens,
+                        totalTokens: totalInputTokens + totalOutputTokens,
+                        cost: this.calculateCost(effectiveModel, {
+                            inputTokens: totalInputTokens,
+                            outputTokens: totalOutputTokens,
+                            cachedInputTokens,
+                            cacheWriteTokens,
+                        }),
+                        duration: Date.now() - startTime,
+                    },
+                    ...(reasoningParts.length > 0 && { reasoning: reasoningParts.join('\n\n') }),
+                    toolCalls: allToolCalls,
+                    messages,
+                    trace: { traceId, spans },
+                };
+                await this.runCheckpointStore().save(pausedCheckpoint);
+                options.onRunComplete?.(paused);
+                return paused;
             }
             const endTime = Date.now();
             const lastAssistantMessage = messages.filter((m) => m.role === 'assistant').pop();
             const finalOutput = lastAssistantMessage ? getTextContent(lastAssistantMessage.content) : '';
-            const structured = parseStructuredOutput(agent.config.responseFormat, finalOutput);
+            const structured = parseStructuredOutput(active.config.responseFormat, finalOutput);
             if (this.state.reflectionEngine &&
                 this.config.reflection?.enabled &&
                 this.config.reflection.reflectAtEnd) {
@@ -448,7 +697,12 @@ export class Cogitator {
                 'run.output_tokens': totalOutputTokens,
             }, 'ok', 'server', options.onSpan, rootSpanId);
             spans.unshift(rootSpan);
-            const runCost = this.calculateCost(effectiveModel, totalInputTokens, totalOutputTokens);
+            const runCost = this.calculateCost(effectiveModel, {
+                inputTokens: totalInputTokens,
+                outputTokens: totalOutputTokens,
+                cachedInputTokens,
+                cacheWriteTokens,
+            });
             if (this.state.costRouter) {
                 this.state.costRouter.recordCost({
                     runId,
@@ -463,6 +717,9 @@ export class Cogitator {
             const result = {
                 output: finalOutput,
                 ...(structured !== undefined && { structured }),
+                status: 'completed',
+                ...(prompt && { prompt }),
+                ...(handoffs.length > 0 && { handoffs, finalAgent: active.name }),
                 runId,
                 agentId: agent.id,
                 threadId,
@@ -473,7 +730,11 @@ export class Cogitator {
                     totalTokens: totalInputTokens + totalOutputTokens,
                     cost: runCost,
                     duration: endTime - startTime,
+                    ...(reasoningTokens > 0 && { reasoningTokens }),
+                    ...(cachedInputTokens > 0 && { cachedInputTokens }),
+                    ...(cacheWriteTokens > 0 && { cacheWriteTokens }),
                 },
+                ...(reasoningParts.length > 0 && { reasoning: reasoningParts.join('\n\n') }),
                 toolCalls: allToolCalls,
                 messages,
                 trace: {
@@ -485,10 +746,14 @@ export class Cogitator {
                     ? await this.state.reflectionEngine.getSummary(agent.id)
                     : undefined,
             };
+            if (prompt)
+                await this.recordPrompt(prompt, result, Date.now() - startTime);
             options.onRunComplete?.(result);
             return result;
         }
         catch (error) {
+            if (prompt)
+                await this.recordPrompt(prompt, undefined, Date.now() - startTime);
             const endTime = Date.now();
             const errorSpan = createSpan('agent.run', traceId, undefined, startTime, endTime, {
                 'agent.id': agent.id,
@@ -509,6 +774,129 @@ export class Cogitator {
             removeParentAbortListener?.();
         }
     }
+    /**
+     * The messages a new run starts with: the thread's history and the input,
+     * once the input passed the injection and constitutional checks, with the
+     * input saved to memory.
+     */
+    async prepareMessages(agent, options, input, threadId) {
+        const messages = await buildInitialMessages(agent, options, threadId, this.state.memoryAdapter, this.state.contextBuilder);
+        const pii = this.config.security?.pii;
+        if (pii?.mode === 'block') {
+            const found = new PiiMasker(pii).find(input);
+            if (found.length > 0) {
+                throw new CogitatorError({
+                    message: `The input contains personal data: ${[...new Set(found.map((f) => f.type))].join(', ')}`,
+                    code: ErrorCode.PII_DETECTED,
+                    details: { types: [...new Set(found.map((f) => f.type))] },
+                });
+            }
+        }
+        if (this.state.injectionDetector) {
+            const injectionResult = await this.state.injectionDetector.analyze(input);
+            if (injectionResult.action === 'blocked') {
+                const threatTypes = injectionResult.threats.map((t) => t.type).join(', ');
+                throw new CogitatorError({
+                    message: `Prompt injection detected: ${threatTypes}`,
+                    code: ErrorCode.PROMPT_INJECTION_DETECTED,
+                    details: { threats: injectionResult.threats },
+                });
+            }
+        }
+        if (this.state.constitutionalAI?.config.filterInput) {
+            const inputResult = await this.state.constitutionalAI.filterInput(input);
+            if (!inputResult.allowed) {
+                throw new Error(`Input blocked: ${inputResult.blockedReason ?? 'Policy violation'}`);
+            }
+        }
+        if (options.context) {
+            addContextToMessages(messages, options.context);
+        }
+        if (this.state.memoryAdapter && options.saveHistory !== false && options.useMemory !== false) {
+            const currentUserMessage = messages[messages.length - 1];
+            await saveEntry(threadId, agent.id, currentUserMessage, this.state.memoryAdapter, undefined, undefined, options.onMemoryError, options.userId);
+        }
+        return messages;
+    }
+    /**
+     * Versioned instructions and A/B tests of this Cogitator's agents
+     * (`prompts` config, in process memory by default).
+     */
+    get prompts() {
+        this.promptRegistry ??= new PromptRegistry(this.config.prompts);
+        return this.promptRegistry;
+    }
+    async recordPrompt(prompt, result, durationMs) {
+        try {
+            await this.prompts.record(prompt, { result, durationMs });
+        }
+        catch (error) {
+            getLogger().warn('Could not record the outcome of a run against its instructions', {
+                prompt: prompt.key,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    runCheckpointStore() {
+        if (this.config.runCheckpoints)
+            return this.config.runCheckpoints;
+        const memory = this.state.memoryAdapter;
+        if (memory) {
+            if (this.threadCheckpoints?.memory !== memory) {
+                this.threadCheckpoints = { memory, store: new ThreadRunCheckpointStore(memory) };
+            }
+            return this.threadCheckpoints.store;
+        }
+        this.processCheckpoints ??= new InMemoryRunCheckpointStore();
+        return this.processCheckpoints;
+    }
+    /**
+     * A new run on a thread whose run is waiting for approvals means the user
+     * moved on: the waiting calls are answered as declined, so the thread's
+     * history stays whole, and the pause is dropped.
+     */
+    async abandonPausedRun(agent, options, threadId) {
+        if (options.threadId === undefined)
+            return;
+        const store = this.runCheckpointStore();
+        const paused = await store.load(threadId).catch((error) => {
+            getLogger().warn('Could not read the paused run of a thread', {
+                threadId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        });
+        if (!paused)
+            return;
+        if (options.threadAccess !== 'shared' && paused.userId !== options.userId)
+            return;
+        if (this.state.memoryAdapter && options.useMemory !== false && options.saveHistory !== false) {
+            for (const toolCall of paused.turn.toolCalls) {
+                const result = {
+                    callId: toolCall.id,
+                    name: toolCall.name,
+                    result: null,
+                    error: 'The user moved on without approving this tool call',
+                };
+                await saveEntry(threadId, agent.id, createToolMessage(toolCall, result), this.state.memoryAdapter, undefined, [result], options.onMemoryError, options.userId);
+            }
+        }
+        await store.delete(threadId);
+    }
+    /**
+     * The decision for a call that needs approval: the run's `onApproval`, else
+     * `guardrails.onToolApproval`, else a pause.
+     */
+    async decideApproval(request, options) {
+        if (options.onApproval)
+            return options.onApproval(request);
+        const legacy = this.config.guardrails?.onToolApproval;
+        if (legacy) {
+            const approved = await legacy(request.toolName, request.arguments, request.sideEffects ?? []);
+            return approved ? { approved: true } : { approved: false };
+        }
+        return 'pause';
+    }
     async acquireRunSlot(signal) {
         const max = this.config.limits?.maxConcurrentRuns;
         if (max === undefined)
@@ -551,9 +939,7 @@ export class Cogitator {
         await this.initPromise;
     }
     async _doInitializeAll(agentModel) {
-        if (this.config.memory?.adapter && !this.state.memoryInitialized) {
-            await initializeMemory(this.config, this.state);
-        }
+        await this.getMemory();
         if (this.config.reflection?.enabled && !this.state.reflectionInitialized) {
             await initializeReflection(this.config, this.state, agentModel, (model) => this.route(model));
         }
@@ -606,7 +992,7 @@ export class Cogitator {
         const cached = this.backends.get(name);
         if (cached)
             return cached;
-        const backend = withLLMRetry(this.createBackend(name), this.config.llm?.retry);
+        const backend = withPiiMasking(withLLMRetry(this.createBackend(name), this.config.llm?.retry), this.config.security?.pii);
         this.backends.set(name, backend);
         return backend;
     }
@@ -624,13 +1010,9 @@ export class Cogitator {
             code: ErrorCode.CONFIGURATION_ERROR,
         });
     }
-    calculateCost(model, inputTokens, outputTokens) {
+    calculateCost(model, usage) {
         const { model: modelName } = parseModel(model);
-        const price = getPrice(modelName);
-        if (!price) {
-            return 0;
-        }
-        return (inputTokens * price.input + outputTokens * price.output) / 1_000_000;
+        return calculateModelCost(modelName, usage) ?? 0;
     }
     /**
      * Get accumulated insights from reflection for an agent.
@@ -736,8 +1118,23 @@ export class Cogitator {
         });
     }
     /**
-     * Get the memory adapter if configured and initialized.
-     * Returns undefined if memory is not configured or not yet initialized.
+     * The memory adapter, connecting it on first use when `memory` is
+     * configured, so threads can be read before any agent has run. `undefined`
+     * when memory is not configured or could not connect (it is tried again
+     * on the next call).
+     */
+    async getMemory() {
+        if (!this.state.memoryInitialized && this.config.memory?.adapter) {
+            this.memoryInit ??= initializeMemory(this.config, this.state).finally(() => {
+                this.memoryInit = undefined;
+            });
+            await this.memoryInit;
+        }
+        return this.state.memoryAdapter;
+    }
+    /**
+     * The memory adapter once connected: by a run, by {@link getMemory}, or
+     * set here. `undefined` before then — use `getMemory()` to connect it.
      */
     get memory() {
         return this.state.memoryAdapter;
@@ -803,4 +1200,16 @@ function waitForAbortable(promise, signal) {
         });
     });
 }
+/** Whether a call to `tool` with `args` needs approval; a check that throws counts as yes. */
+function needsApproval(tool, args) {
+    const check = tool.requiresApproval;
+    if (typeof check !== 'function')
+        return check === true;
+    try {
+        return check(args);
+    }
+    catch {
+        return true;
+    }
+}
 //# sourceMappingURL=runtime.js.map