@marifold/core 0.60.0

package/dist/agent/AgentRunner.js

@@ -0,0 +1,727 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRunner = void 0;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const MemoryControls_1 = require("../memory/MemoryControls");
+const AgentHistory_1 = require("./AgentHistory");
+const ControlBlockTools_1 = require("./ControlBlockTools");
+const RunWorkspace_1 = require("./RunWorkspace");
+const PLAN_SCHEMA = {
+    type: 'object',
+    properties: {
+        title: { type: 'string' },
+        steps: { type: 'array', items: { type: 'string' }, maxItems: 5 },
+    },
+    required: ['title', 'steps'],
+};
+/** Char budget for the injected history window when no profile budget is set. */
+const HISTORY_BUDGET_DEFAULT_CHARS = 16000;
+/**
+ * Approval-aware agent loop. Optionally plans, iterates tool calls against the
+ * ToolRegistry, and records the final outcome in the ephemeral TaskStore.
+ * Observable checks run through ordinary tools inside the loop; there is no
+ * separate model self-grading phase. Task state is never promoted into profile
+ * memory, and the chat memory pipeline is bypassed entirely: hidden memory
+ * control blocks in model output are stripped and their payloads discarded.
+ *
+ * Events are delivered as an AsyncGenerator so renderers get backpressure and
+ * cancellation for free. v0.11 emits one text event per model turn; a future
+ * upgrade to SDK streamEvents can add live deltas without changing the event
+ * contract.
+ */
+class AgentRunner {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async *run(options) {
+        const startedAtMs = Date.now();
+        const startedAt = new Date(startedAtMs).toISOString();
+        const agentConfig = this.deps.agentConfig;
+        const settings = this.deps.resolveSettings(options);
+        // A skill invocation already supplies its own authoritative instructions;
+        // only ordinary agent objectives receive lazily selected built-in guides.
+        const builtInInstructions = options.lean
+            ? []
+            : (this.deps.resolveBuiltInInstructions?.(options.objective, settings.profile) ?? []);
+        let runOptions = builtInInstructions.length > 0
+            ? { ...options, instructions: [...builtInInstructions, ...(options.instructions ?? [])] }
+            : options;
+        if (runOptions.images && this.deps.prepareImages) {
+            runOptions = {
+                ...runOptions,
+                images: await this.deps.prepareImages(runOptions.images, runOptions.originalImages !== true),
+            };
+        }
+        const { engine: rawEngine, config } = await this.deps.prepareEngine(settings);
+        // Tally token usage across every model call (optional plan + loop turns).
+        const usage = {};
+        const engine = withUsageTally(rawEngine, usage);
+        const cwd = options.cwd ?? process.cwd();
+        const maxIterations = Math.max(1, options.maxIterations ?? agentConfig.maxIterations);
+        const requestedMode = options.toolMode ?? agentConfig.toolMode;
+        const task = this.deps.taskStore.create({
+            objective: options.objective,
+            profile: settings.profile,
+            tags: ['agent', ...(options.tags ?? [])],
+        });
+        yield { type: 'status', taskId: task.id, status: 'running' };
+        const workspace = (0, RunWorkspace_1.createRunWorkspace)({
+            id: options.executionId ?? task.id,
+            cwd,
+            trustedFolders: [...agentConfig.trustedFolders, ...(options.trustedFolders ?? [])],
+            readOnlyFolders: this.deps.resolveReadOnlyFolders?.(settings.profile),
+            files: options.files,
+            images: runOptions.images,
+        });
+        const toolContext = {
+            cwd: workspace.cwd,
+            trustedFolders: [...agentConfig.trustedFolders, ...(options.trustedFolders ?? [])],
+            workspace,
+            signal: options.signal,
+            outputLimit: agentConfig.toolOutputLimit,
+        };
+        // Bounded cross-objective memory: inject a window of the recent clean
+        // session pairs so a NON-lean task can reference prior turns ("save the
+        // above prompt"). Lean/skill runs stay stateless (isolated).
+        const recentTurns = !options.lean && options.sessionId && this.deps.loadRecentTurns
+            ? this.deps.loadRecentTurns(options.sessionId, options.replaceUserTurnIndex)
+            : [];
+        // Cap to the last N turns when the profile sets session_context_turns — the
+        // same turn window chat uses, so the knob means the same thing in both modes.
+        // The char budget (≈ the token budget) remains the secondary bound.
+        const windowedTurns = settings.sessionContextTurns != null
+            ? recentTurns.slice(Math.max(0, recentTurns.length - settings.sessionContextTurns))
+            : recentTurns;
+        const historyContext = (0, AgentHistory_1.buildHistoryContext)(windowedTurns, settings.maxContextTokens ?? HISTORY_BUDGET_DEFAULT_CHARS);
+        const state = {
+            mode: requestedMode === 'auto' ? 'native' : requestedMode,
+            triedNativeFallback: requestedMode !== 'auto',
+            exchange: [],
+            transcript: [],
+            historyContext,
+            toolSummaries: [],
+            steeringNotes: [],
+            activeImages: [],
+        };
+        let sessionTurnPersisted = false;
+        const persistSessionTurn = async (assistantText, outcome) => {
+            if (sessionTurnPersisted || !options.sessionId || !this.deps.persistTurn)
+                return;
+            // A failed regeneration must leave the existing exchange intact. Ordinary
+            // append-only runs still keep their submitted prompt and terminal state.
+            if (outcome !== 'completed' && options.replaceUserTurnIndex !== undefined)
+                return;
+            sessionTurnPersisted = true;
+            let responseMetrics;
+            if (outcome === 'completed') {
+                const finishedAtMs = Date.now();
+                responseMetrics = {
+                    mode: 'agent',
+                    provider: settings.provider,
+                    model: settings.model,
+                    think: settings.think,
+                    startedAt,
+                    finishedAt: new Date(finishedAtMs).toISOString(),
+                    latencyMs: Math.max(0, finishedAtMs - startedAtMs),
+                    ...(hasUsage(usage) ? { usage: { ...usage } } : {}),
+                };
+            }
+            try {
+                await this.deps.persistTurn(options.sessionId, settings.profile, options.userTurn ?? options.objective, assistantText, runOptions.images, options.replaceUserTurnIndex, responseMetrics);
+            }
+            catch (error) {
+                if (outcome === 'completed')
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                this.deps.taskStore.appendEvent(task.id, {
+                    kind: 'note',
+                    message: `Could not persist the ${outcome} session turn: ${truncate(message, 500)}`,
+                });
+            }
+        };
+        try {
+            // Phase 1 — plan, only when forced (the TUI's `/steps`, or a weak-model
+            // config). Adaptive by default: a separate planning call is overhead for
+            // the common single-step task, so the model just reasons inline.
+            if (options.forcePlan) {
+                const plan = await this.buildPlan(engine, config, settings.profile, runOptions);
+                const planned = this.deps.taskStore.update(task.id, {
+                    title: plan.title,
+                    plan: plan.steps.map((text, index) => ({
+                        id: `step_${index + 1}`,
+                        text,
+                        status: index === 0 ? 'in_progress' : 'pending',
+                    })),
+                });
+                yield { type: 'plan', taskId: task.id, plan: planned.plan };
+            }
+            // Phase 2 — tool loop
+            let finalText;
+            let iterations = 0;
+            while (iterations < maxIterations) {
+                iterations += 1;
+                this.assertNotAborted(options.signal);
+                for (const note of this.drainSteering(task.id, options, state)) {
+                    yield { type: 'steering', taskId: task.id, text: note };
+                }
+                const response = await engine.run(this.loopRequest(config, settings.profile, runOptions, state, workspace), {
+                    signal: options.signal,
+                });
+                this.trace({
+                    kind: 'iteration',
+                    iteration: iterations,
+                    mode: state.mode,
+                    inputTokens: response.usage?.inputTokens,
+                    outputTokens: response.usage?.outputTokens,
+                    // Cumulative loop context the model saw this turn (the thing that grows).
+                    exchangeTurns: state.exchange.length,
+                    exchangeChars: state.exchange.reduce((n, t) => n + (t.kind === 'tool_result' ? t.content.length : (t.text?.length ?? 0)), 0),
+                    transcriptChars: state.transcript.reduce((n, t) => n + t.length, 0),
+                });
+                if (!response.ok) {
+                    if (this.shouldFallBackToControlBlocks(response, state)) {
+                        state.mode = 'control-block';
+                        state.triedNativeFallback = true;
+                        this.deps.taskStore.appendEvent(task.id, {
+                            kind: 'decision',
+                            message: 'Provider rejected native tool calling; switching to control-block tool mode.',
+                        });
+                        continue;
+                    }
+                    if (response.error?.code === 'REQUEST_ABORTED')
+                        throw new AbortedError();
+                    const message = response.error?.message ?? 'Provider call failed.';
+                    yield { type: 'error', code: response.error?.code ?? 'PROVIDER_ERROR', message };
+                    await persistSessionTurn(failedSessionOutcome(message), 'failed');
+                    yield* this.finish(task.id, 'failed', undefined, 'Retry the run once the provider issue is resolved.', usage);
+                    return;
+                }
+                const { text, calls } = this.extractTurn(response, state);
+                if (response.reasoning?.summary) {
+                    yield { type: 'reasoning', summary: response.reasoning.summary };
+                }
+                if (text)
+                    yield { type: 'text', text, phase: calls.length > 0 ? 'progress' : 'final' };
+                if (calls.length === 0) {
+                    finalText = text;
+                    break;
+                }
+                if (state.mode === 'native') {
+                    state.exchange.push({
+                        kind: 'assistant',
+                        text,
+                        toolCalls: calls,
+                        ...(response.reasoning ? { reasoning: response.reasoning } : {}),
+                    });
+                }
+                else if (text || calls.length > 0) {
+                    state.transcript.push(`Assistant reply:\n${text || '(tool calls only)'}`);
+                }
+                for (const call of calls) {
+                    this.assertNotAborted(options.signal);
+                    yield* this.executeCall(task.id, call, options, state, toolContext);
+                }
+            }
+            if (finalText === undefined) {
+                this.deps.taskStore.appendEvent(task.id, {
+                    kind: 'blocker',
+                    message: `Iteration cap of ${maxIterations} reached before the objective was completed.`,
+                });
+                await persistSessionTurn(failedSessionOutcome(`Stopped at the iteration cap of ${maxIterations} before completing the objective.`), 'failed');
+                yield* this.finish(task.id, 'failed', 'Stopped at the iteration cap before completing the objective.', 'Re-run with a higher iteration cap or a narrower objective.', usage);
+                return;
+            }
+            // Persist a single clean turn pair (objective → final answer) so resuming
+            // the session shows the result, not the raw `Objective:`/tool framing.
+            await persistSessionTurn(finalText, 'completed');
+            // Complete. No verification phase: a separate self-grading model call was
+            // non-actionable (a failed grade didn't retry or fix anything) and models
+            // self-grade unreliably — so it was pure token overhead. Real checks belong
+            // in tools the agent runs inside the loop, not a final self-assessment.
+            this.completePlanSteps(task.id, true);
+            yield* this.finish(task.id, 'completed', finalText, undefined, usage);
+        }
+        catch (error) {
+            if (error instanceof AbortedError || (options.signal?.aborted ?? false)) {
+                this.deps.taskStore.appendEvent(task.id, { kind: 'note', message: 'Run cancelled by the user.' });
+                await persistSessionTurn('Run cancelled before a final response was produced.', 'cancelled');
+                yield* this.finish(task.id, 'cancelled', undefined, 'Resume by starting a new run with the same objective.', usage);
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            yield { type: 'error', code: 'AGENT_RUN_ERROR', message };
+            await persistSessionTurn(failedSessionOutcome(message), 'failed');
+            yield* this.finish(task.id, 'failed', undefined, message, usage);
+        }
+    }
+    async *executeCall(taskId, call, options, state, toolContext) {
+        const tool = this.deps.registry.get(call.name);
+        if (!tool) {
+            const message = `Unknown tool '${call.name}'. Available tools: ${this.deps.registry.list().map(t => t.definition.name).join(', ')}.`;
+            yield { type: 'tool_result', callId: call.id, tool: call.name, summary: `unknown tool '${call.name}'`, isError: true };
+            this.recordToolResult(taskId, state, call, message, true, `unknown tool '${call.name}'`);
+            return;
+        }
+        const summary = tool.summarizeCall(call.arguments);
+        yield {
+            type: 'tool_request',
+            call: { id: call.id, tool: call.name, kind: tool.kind, input: call.arguments, summary },
+        };
+        if (tool.kind === 'interaction') {
+            yield* this.requestUserInput(taskId, call, tool, summary, options, state);
+            return;
+        }
+        const decision = yield* this.resolveApproval(call, tool, summary, options, toolContext);
+        if (!decision.approved) {
+            const message = `Tool call denied${decision.reason ? `: ${decision.reason}` : '.'}`;
+            yield { type: 'tool_result', callId: call.id, tool: call.name, summary: 'denied', isError: true };
+            this.deps.taskStore.appendEvent(taskId, { kind: 'decision', message: `Denied ${summary}${decision.reason ? ` (${decision.reason})` : ''}` });
+            this.recordToolResult(taskId, state, call, message, true, 'denied', false);
+            return;
+        }
+        let content;
+        let isError = false;
+        let resultSummary = summary;
+        try {
+            const result = await tool.execute(call.arguments, toolContext);
+            content = result.content;
+            isError = result.isError ?? false;
+            resultSummary = result.summary ?? summary;
+            if (!isError && result.images?.length) {
+                for (const image of result.images) {
+                    if (!state.activeImages.includes(image))
+                        state.activeImages.push(image);
+                }
+            }
+        }
+        catch (error) {
+            content = `Tool '${call.name}' failed: ${error instanceof Error ? error.message : String(error)}`;
+            isError = true;
+            resultSummary = `${summary} failed`;
+        }
+        yield { type: 'tool_result', callId: call.id, tool: call.name, summary: resultSummary, isError };
+        this.recordToolResult(taskId, state, call, content, isError, resultSummary);
+    }
+    async *requestUserInput(taskId, call, tool, summary, options, state) {
+        let request;
+        try {
+            request = tool.createRequest(call.id, call.arguments);
+        }
+        catch (error) {
+            const content = `Tool '${call.name}' failed: ${error instanceof Error ? error.message : String(error)}`;
+            yield { type: 'tool_result', callId: call.id, tool: call.name, summary: `${summary} failed`, isError: true };
+            this.recordToolResult(taskId, state, call, content, true, `${summary} failed`);
+            return;
+        }
+        if (options.unattended || !options.userInputHandler) {
+            const content = [
+                'No interactive user is available for this run.',
+                'Continue with a reasonable assumption when that is safe; otherwise explain what information is missing.',
+            ].join(' ');
+            yield { type: 'tool_result', callId: call.id, tool: call.name, summary: 'user input unavailable', isError: true };
+            this.recordToolResult(taskId, state, call, content, true, 'user input unavailable');
+            return;
+        }
+        yield { type: 'user_input_request', request };
+        const submission = await options.userInputHandler(request);
+        if (!submission) {
+            const content = 'The clarification request ended without an answer.';
+            yield { type: 'tool_result', callId: call.id, tool: call.name, summary: 'no user answer received', isError: true };
+            this.recordToolResult(taskId, state, call, content, true, 'no user answer received');
+            return;
+        }
+        try {
+            const response = tool.resolveResponse(request, submission);
+            const content = tool.formatResponse(response);
+            yield { type: 'user_input_response', response };
+            yield {
+                type: 'tool_result',
+                callId: call.id,
+                tool: call.name,
+                summary: `received ${response.answers.length} user ${response.answers.length === 1 ? 'answer' : 'answers'}`,
+                isError: false,
+            };
+            this.deps.taskStore.appendEvent(taskId, { kind: 'decision', message: content });
+            this.recordToolResult(taskId, state, call, content, false, `received ${response.answers.length} user ${response.answers.length === 1 ? 'answer' : 'answers'}`);
+        }
+        catch (error) {
+            const content = `Could not accept the user answers: ${error instanceof Error ? error.message : String(error)}`;
+            yield { type: 'tool_result', callId: call.id, tool: call.name, summary: 'invalid user answers', isError: true };
+            this.recordToolResult(taskId, state, call, content, true, 'invalid user answers');
+        }
+    }
+    async *resolveApproval(call, tool, summary, options, toolContext) {
+        const risk = tool.assessRisk?.(call.arguments, toolContext) ?? { escalate: false };
+        if (risk.blocked) {
+            const reason = risk.reason ?? 'blocked by the run security policy';
+            yield { type: 'approval_decision', requestId: call.id, approved: false, source: 'policy', reason };
+            return { approved: false, reason };
+        }
+        // Tools set `trusted` only for narrow pre-authorized capabilities such as
+        // current-run attachments and eligible in-home trusted folders.
+        if (risk.trusted) {
+            yield { type: 'approval_decision', requestId: call.id, approved: true, source: 'policy' };
+            return { approved: true };
+        }
+        const approval = options.unattended
+            ? { ...this.deps.agentConfig.approval, ...(this.deps.agentConfig.unattended ?? {}) }
+            : this.deps.agentConfig.approval;
+        let mode = approval[tool.kind];
+        if (risk.escalate && mode === 'allow')
+            mode = 'ask';
+        if (mode === 'allow') {
+            yield { type: 'approval_decision', requestId: call.id, approved: true, source: 'policy' };
+            return { approved: true };
+        }
+        if (mode === 'deny') {
+            yield { type: 'approval_decision', requestId: call.id, approved: false, source: 'policy', reason: `${tool.kind} tools are denied by policy` };
+            return { approved: false, reason: `${tool.kind} tools are denied by policy` };
+        }
+        if (!options.approvalHandler) {
+            const reason = 'approval required but the run is unattended';
+            yield { type: 'approval_decision', requestId: call.id, approved: false, source: 'policy', reason };
+            return { approved: false, reason };
+        }
+        const request = {
+            id: call.id,
+            tool: call.name,
+            kind: tool.kind,
+            summary,
+            input: call.arguments,
+            escalated: risk.escalate,
+            ...(risk.reason ? { escalationReason: risk.reason } : {}),
+            ...(risk.targetPath ? { escalatedPath: risk.targetPath } : {}),
+            ...(risk.persistable === false ? { persistable: false } : {}),
+        };
+        yield { type: 'approval_request', request };
+        const decision = await options.approvalHandler(request);
+        yield {
+            type: 'approval_decision',
+            requestId: call.id,
+            approved: decision.approved,
+            source: 'user',
+            ...(decision.reason ? { reason: decision.reason } : {}),
+        };
+        return decision;
+    }
+    /**
+     * Opt-in diagnostic trace for agent-mode context cost (off by default).
+     * Set `MARIFOLD_AGENT_TRACE=1` to append JSONL to ~/.marifold/agent-trace.jsonl,
+     * or `MARIFOLD_AGENT_TRACE=<path>` for a custom file. Captures per-iteration
+     * input tokens + cumulative loop-context size and per-tool-result sizes, so we
+     * can see whether huge results or many small steps drive the growth. Never
+     * throws — tracing must not affect a run.
+     */
+    trace(record) {
+        const target = process.env.MARIFOLD_AGENT_TRACE;
+        if (!target)
+            return;
+        try {
+            const file = target === '1' || target === 'true'
+                ? path.join(os.homedir(), '.marifold', 'agent-trace.jsonl')
+                : target;
+            fs.appendFileSync(file, JSON.stringify({ ts: new Date().toISOString(), ...record }) + '\n');
+        }
+        catch {
+            // Diagnostics are best-effort; a trace failure must never break a run.
+        }
+    }
+    recordToolResult(taskId, state, call, content, isError, summary, appendObservation = true) {
+        this.trace({ kind: 'tool_result', tool: call.name, chars: content.length, isError });
+        if (state.mode === 'native') {
+            state.exchange.push({ kind: 'tool_result', toolCallId: call.id, name: call.name, content, isError });
+        }
+        else {
+            state.transcript.push((0, ControlBlockTools_1.formatControlBlockResult)(call, content, isError));
+        }
+        state.toolSummaries.push(`${isError ? '[error] ' : ''}${summary}`);
+        if (appendObservation) {
+            this.deps.taskStore.appendEvent(taskId, {
+                kind: 'observation',
+                message: summary,
+                metadata: { tool: call.name, ...(isError ? { error: 'true' } : {}) },
+            });
+        }
+    }
+    /** Drain any `/btw` steering the caller queued and record it for the next
+     * turn. Returns the drained notes so the run generator can surface each as a
+     * `steering` event to attached clients. */
+    drainSteering(taskId, options, state) {
+        if (!options.steering)
+            return [];
+        const drained = [];
+        for (const note of options.steering()) {
+            const text = note.trim();
+            if (!text)
+                continue;
+            state.steeringNotes.push(text);
+            drained.push(text);
+            this.deps.taskStore.appendEvent(taskId, { kind: 'note', message: `Steering: ${text}` });
+        }
+        return drained;
+    }
+    loopRequest(config, profile, options, state, workspace) {
+        const base = {
+            config,
+            profile,
+            prompt: options.lean
+                ? options.objective
+                : `Objective: ${options.objective}\n\nUse tools only when the objective genuinely requires reading or writing files, running commands, searching the web, or delegating. Many objectives — greetings, questions, explanations, drafting text — need no tools at all; for those, answer directly from your own knowledge. Do not invent tool calls. When the objective is complete, reply with a short final answer describing the outcome.`,
+            context: this.agentContext(state, workspace, options.instructions, options.lean),
+            ...(options.sessionId ? { session: { id: options.sessionId, createIfMissing: true } } : {}),
+            ...(state.activeImages.length > 0 ? { images: state.activeImages } : {}),
+        };
+        const steering = state.steeringNotes.map(note => `The user added this guidance while you were working — take it into account: ${note}`);
+        if (state.mode === 'native') {
+            return {
+                ...base,
+                tools: this.deps.registry.definitions(),
+                toolExchange: state.exchange,
+                ...(steering.length > 0 ? { userContext: steering } : {}),
+            };
+        }
+        return {
+            ...base,
+            userContext: [...state.transcript, ...steering],
+        };
+    }
+    agentContext(state, workspace, instructions, lean = false) {
+        const attachments = workspace.attachments.length > 0
+            ? [
+                'Attachments uploaded for this run:',
+                ...workspace.attachments.map(attachment => (`- ${attachment.id}: ${attachment.name} (${attachment.mediaType}, ${formatAttachmentBytes(attachment.size)})`)),
+                'Attachments are not embedded in this agent prompt. Use inspect_attachment with an attachment ID when their contents matter. You may inspect independent attachments in parallel with other read-only tool calls.',
+            ].join('\n')
+            : 'No attachments were uploaded for this run.';
+        const workspaceContext = [
+            `Working directory: ${workspace.cwd}. Relative tool paths resolve against it.`,
+            `User home: ${workspace.userHome}. In tool paths and shell commands, ~ refers to this directory.`,
+            `Isolated run directory: ${workspace.rootDir}. Its internal runtime home is ${workspace.homeDir}.`,
+            `${attachments}\nHonor explicit destination paths from the user; otherwise write generated deliverables to ${workspace.outputDir}. Temporary scripts and environments belong in ${workspace.workDir}.`,
+            ...(this.deps.registry.get('ask_user')?.kind === 'interaction' ? [
+                'ask_user is optional. Use it only when essential information is missing and a reasonable assumption could materially change the result. Otherwise proceed. Batch all currently known questions into one call, and call it without other tools in that response.',
+            ] : []),
+            'shell_exec has no network access and can write only the working directory, configured trusted folders, and private run directories even after execution approval. Use write_file for an explicit output path elsewhere. Use python_package_install for approved Python dependencies; it installs only into this run’s disposable uv environment.',
+        ].join('\n');
+        // Lean run (skills): minimal framing — the instructions are authoritative,
+        // and we ask for only the final output to avoid plan/preamble/reasoning prose.
+        if (lean) {
+            const context = [...(instructions ?? [])];
+            context.push(`${workspaceContext}\nUse inspect_attachment when the skill depends on an uploaded attachment. Use read_file only if the instructions reference a bundled file (e.g. vars.toml). Resolve required inputs, then reply with ONLY the final output the instructions define — no plan, preamble, reasoning, or commentary.`);
+            if (state.mode === 'control-block') {
+                context.push((0, ControlBlockTools_1.buildControlBlockInstructions)(this.deps.registry.definitions()));
+            }
+            return context;
+        }
+        const context = [
+            'You are running as the Marifold agent. Stay focused on the stated objective and keep replies concise.',
+            'Prefer answering directly. Reach for a tool only when the objective cannot be completed from your own knowledge — never use a tool just to demonstrate one.',
+            'After changing files or producing an observable result, use the narrowest relevant tool for a focused check before claiming success. Report the evidence you actually observed; do not invent results or perform a separate self-grade.',
+            workspaceContext,
+        ];
+        // Skill instructions are authoritative for this run — lead with them.
+        if (instructions?.length)
+            context.unshift(...instructions);
+        // Bounded prior-conversation memory (non-lean only) so the objective can
+        // reference earlier turns. Placed after framing, before tool instructions.
+        if (state.historyContext)
+            context.push(state.historyContext);
+        if (state.mode === 'control-block') {
+            context.push((0, ControlBlockTools_1.buildControlBlockInstructions)(this.deps.registry.definitions()));
+        }
+        return context;
+    }
+    extractTurn(response, state) {
+        // Memory control blocks are stripped and their payloads discarded — agent
+        // runs never write profile memory (see docs/architecture.md).
+        const stripped = (0, MemoryControls_1.stripMemoryControls)(response.text ?? '');
+        if (state.mode === 'native') {
+            return { text: stripped.text.trim(), calls: response.toolCalls ?? [] };
+        }
+        const parsed = (0, ControlBlockTools_1.parseControlBlockCalls)(stripped.text);
+        // Re-id calls so they stay unique across loop iterations.
+        const calls = parsed.calls.map(call => ({ ...call, id: `call_${crypto.randomBytes(4).toString('hex')}` }));
+        return { text: parsed.visibleText, calls };
+    }
+    shouldFallBackToControlBlocks(response, state) {
+        if (state.mode !== 'native' || state.triedNativeFallback)
+            return false;
+        if (response.error?.code !== 'PROVIDER_ERROR')
+            return false;
+        return /tool/i.test(response.error.message);
+    }
+    async buildPlan(engine, config, profile, options) {
+        const fallback = {
+            title: options.objective.split(/\r?\n/)[0]?.slice(0, 80) ?? 'Agent task',
+            steps: ['Work toward the objective.'],
+        };
+        const response = await engine.run({
+            config,
+            profile,
+            prompt: `Objective: ${options.objective}\n\nCreate a short execution plan for this objective. Reply with JSON {"title": string, "steps": string[]} using at most 5 short steps.`,
+            context: ['You are planning an agent task. Reply with JSON only.'],
+            output: { jsonSchema: PLAN_SCHEMA, jsonSchemaName: 'agent_plan' },
+        }, { signal: options.signal });
+        if (!response.ok) {
+            if (response.error?.code === 'REQUEST_ABORTED')
+                throw new AbortedError();
+            return fallback;
+        }
+        const parsed = parseJsonObject(response.text ?? '');
+        const title = typeof parsed?.title === 'string' && parsed.title.trim() ? parsed.title.trim() : fallback.title;
+        const steps = Array.isArray(parsed?.steps)
+            ? parsed.steps.filter((step) => typeof step === 'string' && step.trim().length > 0).slice(0, 5)
+            : [];
+        return { title, steps: steps.length > 0 ? steps : fallback.steps };
+    }
+    completePlanSteps(taskId, passed) {
+        if (!passed)
+            return;
+        const task = this.deps.taskStore.get(taskId);
+        if (!task)
+            return;
+        this.deps.taskStore.update(taskId, {
+            plan: task.plan.map(step => ({ id: step.id, text: step.text, status: 'completed' })),
+        });
+    }
+    async *finish(taskId, status, summary, nextAction, usage) {
+        const updated = this.deps.taskStore.update(taskId, {
+            status,
+            ...(summary ? { summary: truncate(summary, 2000) } : {}),
+            ...(nextAction ? { nextAction: truncate(nextAction, 500) } : {}),
+        });
+        yield { type: 'status', taskId, status: updated.status };
+        yield {
+            type: 'done',
+            taskId,
+            status: updated.status,
+            ...(updated.summary ? { summary: updated.summary } : {}),
+            ...(usage && hasUsage(usage) ? { usage } : {}),
+        };
+    }
+    assertNotAborted(signal) {
+        if (signal?.aborted)
+            throw new AbortedError();
+    }
+}
+exports.AgentRunner = AgentRunner;
+class AbortedError extends Error {
+    constructor() {
+        super('Agent run aborted.');
+        this.name = 'AbortedError';
+    }
+}
+function parseJsonObject(text) {
+    const candidates = [text.trim()];
+    const match = text.match(/\{[\s\S]*\}/);
+    if (match)
+        candidates.push(match[0]);
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return undefined;
+}
+function formatAttachmentBytes(bytes) {
+    if (bytes === 0)
+        return 'remote';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit - 3)}...`;
+}
+function failedSessionOutcome(message) {
+    const detail = truncate(message.trim(), 1000);
+    return detail
+        ? `Run failed before a final response was produced.\n\n${detail}`
+        : 'Run failed before a final response was produced.';
+}
+/** Wrap an engine so each model call's token usage accrues into `total`. */
+function withUsageTally(engine, total) {
+    return {
+        run: async (request, options) => {
+            const response = await engine.run(request, options);
+            addUsage(total, response.usage);
+            return response;
+        },
+    };
+}
+function addUsage(total, usage) {
+    if (!usage)
+        return;
+    if (usage.inputTokens != null)
+        total.inputTokens = (total.inputTokens ?? 0) + usage.inputTokens;
+    if (usage.outputTokens != null)
+        total.outputTokens = (total.outputTokens ?? 0) + usage.outputTokens;
+    if (usage.cachedInputTokens != null)
+        total.cachedInputTokens = (total.cachedInputTokens ?? 0) + usage.cachedInputTokens;
+    if (usage.reasoningTokens != null)
+        total.reasoningTokens = (total.reasoningTokens ?? 0) + usage.reasoningTokens;
+    const turnTotal = usage.totalTokens ?? sumDefined(usage.inputTokens, usage.outputTokens);
+    if (turnTotal != null)
+        total.totalTokens = (total.totalTokens ?? 0) + turnTotal;
+    if (usage.estimatedCostUSD != null)
+        total.estimatedCostUSD = (total.estimatedCostUSD ?? 0) + usage.estimatedCostUSD;
+}
+function sumDefined(a, b) {
+    if (a == null && b == null)
+        return undefined;
+    return (a ?? 0) + (b ?? 0);
+}
+function hasUsage(usage) {
+    return usage.inputTokens != null
+        || usage.outputTokens != null
+        || usage.totalTokens != null
+        || usage.cachedInputTokens != null
+        || usage.reasoningTokens != null
+        || usage.estimatedCostUSD != null;
+}
+//# sourceMappingURL=AgentRunner.js.map