anchor-ai-sdk 0.1.8 → 0.2.0

package/dist/engine/loop.js

@@ -1,23 +1,23 @@
 import { createFinishTool } from "../tools/finish.js";
 import { BudgetTracker, DEFAULT_BUDGET_LIMITS, DEFAULT_MAX_OUTPUT_TOKENS, } from "./budgets.js";
 import { DEFAULT_TRUNCATED_REPLY_CHARS, DEFAULT_MAX_ASSISTANT_CHARS, elideReply, spillReply, } from "./elision.js";
-import { compactConversation, DEFAULT_COMPACTION, estimateTokens, } from "./compaction.js";
-import { assistantMessage, conversationHistory, userMessage, } from "./context.js";
-import { renderInboxTask, } from "./inbox.js";
+import { compactConversation, compactConversationStructured, DEFAULT_COMPACTION, estimateTokens, renderCompactionHandoff, } from "./compaction.js";
+import { assistantMessage, conversationHistory, } from "./context.js";
+import { renderInboxTurn, } from "./inbox.js";
 import { defineTool } from "../tools/types.js";
 import { gitSnapshot } from "./snapshot.js";
 import { TraceFanout } from "../trace/sink.js";
 import { budgetWarning, revivalBlock, warnPercent as revivalWarnPercent, } from "./revival.js";
 import { phaseDisciplineBlock } from "./phase-discipline.js";
-import { resolveTurnIntent } from "./intent.js";
-import { addRequirement, compileLedger, ledgerGate, linkEvidence, recordEvidence, renderLedger, setRequirementStatus, verifyAlignment, } from "../ledger/index.js";
-import { chatAgent } from "../agents/chat/index.js";
-import { codingAgent } from "../agents/coding/index.js";
+import { renderPromptBlocks } from "./prompt.js";
+import { addRequirement, compileLedger, createLedger, ledgerGate, linkEvidence, recordEvidence, renderLedger, setRequirementStatus, } from "../ledger/index.js";
+import { llmJudge } from "../verify/index.js";
 import { dispatchToolCalls, } from "./dispatch.js";
 import { mintOperationId, reconcilePendingOperations, settleFromResult, } from "./operations.js";
 import { RepeatTracker, cappedReplyNudge, createCourseCorrect, emptyTurnNudge, proseCheckpoint as proseCheckpointMessage, repeatedCallNudge, silentNudge, verboseNudge, visibleOutputTokens, } from "./guardrails.js";
 import { pollBackgroundJobs, renderBackgroundResult, renderLostJob, waitForBackgroundJobs, } from "./background.js";
-async function runOne(task, opts, chain = {}) {
+export { userTurn } from "./types.js";
+async function runOne(input, opts, chain = {}) {
     const strategy = opts.strategy ?? opts.agent?.strategy;
     if (!strategy)
         throw new Error("runAgent needs an agent or a strategy — pass opts.agent (chatAgent, codingAgent, …) or opts.strategy");
@@ -114,58 +114,66 @@ async function runOne(task, opts, chain = {}) {
         !strategy.phases.some((p) => p.id === opts.startPhase)) {
         throw new Error(`startPhase "${opts.startPhase}" is not a phase of strategy "${strategy.name}"`);
     }
-    const context = task.context ?? (await strategy.prepareContext?.(opts.sandbox, task.task));
+    const requestText = input.messages
+        .filter((message) => message.role === "user" && message.content?.trim())
+        .map((message) => message.content)
+        .join("\n\n");
+    const context = input.context ?? (await strategy.prepareContext?.(opts.sandbox, requestText));
     const prior = await opts.thread?.store.load(opts.thread.id);
     if (!opts.startPhase &&
         prior?.phase &&
         strategy.phases.some((item) => item.id === prior.phase))
         phase = prior.phase;
     let summary = prior?.summary;
+    let compaction = prior?.compaction;
     const budget = chain.budget ?? new BudgetTracker(opts.budgets);
-    // ---- Task verification ------------------------------------------------
+    // ---- Task contracts and the judge --------------------------------------
     const verifierOn = opts.verifier !== undefined && opts.verifier !== false;
     const verifierConfig = verifierOn && typeof opts.verifier === "object" ? opts.verifier : {};
-    const verifierLlm = verifierConfig.llm ?? opts.llm;
     const verifierGates = new Set(verifierConfig.gates ?? ["phase", "finish"]);
-    const maxVerifierCalls = verifierConfig.maxCallsPerTask ?? 6;
-    let verifierCalls = 0;
+    const judge = verifierOn
+        ? (verifierConfig.judge ?? llmJudge(verifierConfig.llm ?? opts.llm))
+        : undefined;
+    const maxJudgeCalls = verifierConfig.maxCallsPerTask ?? 8;
+    const maxPhaseRejections = verifierConfig.maxRejectionsPerPhase ?? 3;
+    let judgeCalls = 0;
+    let phaseRejections = 0;
+    let phaseEvidence = [];
+    const contractTaskId = opts.taskId ?? opts.thread?.id ?? `task-${Date.now()}`;
     let ledger = opts.ledger ?? (verifierOn ? prior?.ledger : undefined);
-    if (verifierOn && !ledger) {
-        const compiled = await compileLedger({
-            llm: verifierLlm,
-            taskId: opts.thread?.id ?? `task-${Date.now()}`,
-            task: task.task,
-            phases: strategy.phases,
-            reasoningEffort: "low",
-        });
-        ledger = compiled.ledger;
-        if (compiled.usage)
-            budget.record(compiled.usage);
-    }
-    const recentEvidence = () => {
-        if (!ledger)
-            return "(none)";
-        return Object.values(ledger.evidence)
-            .slice(-6)
-            .map((item) => `${item.id} ${item.tool}${item.summary ? `: ${item.summary}` : ""}${item.ok ? "" : " (failed)"}`)
-            .join("\n");
-    };
-    const callVerifier = async (phaseGoal) => {
-        if (!verifierOn || !ledger || verifierCalls >= maxVerifierCalls) {
-            return { allow: true };
-        }
-        verifierCalls += 1;
+    // A settled ledger is history, not an active contract.
+    if (ledger && !hasActiveLedger(ledger))
+        ledger = undefined;
+    const callJudge = async (phaseGoal, requirements, agentReason) => {
+        if (!judge || !ledger || judgeCalls >= maxJudgeCalls)
+            return undefined;
+        judgeCalls += 1;
         try {
-            const { verdict, usage } = await verifyAlignment({
-                llm: verifierLlm,
-                task: task.task,
+            const verdict = await judge.judge({
+                request: requestText,
                 phase: phaseGoal,
                 ledger,
-                recentEvidence: recentEvidence(),
-                reasoningEffort: "low",
+                evidenceSincePhase: [...phaseEvidence],
+                ...(agentReason ? { agentReason } : {}),
+            }, signal);
+            if (verdict.usage)
+                budget.record(verdict.usage);
+            const wanted = new Set(requirements.map((item) => item.id));
+            const judged = verdict.requirements.filter((item) => wanted.has(item.id));
+            emit({
+                type: "phase_verdict",
+                phase: phaseGoal.id,
+                cleared: verdict.cleared,
+                confidence: verdict.confidence,
+                judge: judge.name,
+                requirements: judged.map((item) => ({
+                    id: item.id,
+                    status: item.status,
+                    ...(item.probability !== undefined
+                        ? { probability: item.probability }
+                        : {}),
+                })),
             });
-            if (usage)
-                budget.record(usage);
             return verdict;
         }
         catch (error) {
@@ -174,72 +182,23 @@ async function runOne(task, opts, chain = {}) {
                 kind: "verifier_failed",
                 detail: error instanceof Error ? error.message : String(error),
             });
-            return {
-                allow: verifierConfig.onError !== "block",
-                aligned: false,
-                justified: true,
-                reason: "verifier unavailable",
-                requiredAction: "none",
-                confidence: 0,
-            };
-        }
-    };
-    if (verifierOn && ledger) {
-        completionGate = async (summaryText) => {
-            const structural = ledgerGate(ledger, {
-                allowWaived: verifierConfig.allowWaived,
-            });
-            if (!structural.allow) {
+            if (verifierConfig.onError === "block") {
                 return {
-                    ok: false,
-                    content: [
-                        "Verification gate: required work is not complete.",
-                        `open: ${structural.open.join(", ") || "none"}`,
-                        `missingEvidence: ${structural.missingEvidence.join(", ") || "none"}`,
-                        `failures: ${structural.failures.join(" | ") || "none"}`,
-                        "Attach evidence to each requirement with update_ledger, resolve failures, and try again.",
-                    ].join("\n"),
+                    cleared: false,
+                    requirements: requirements.map((item) => ({
+                        id: item.id,
+                        status: "unproven",
+                    })),
+                    confidence: 0,
                 };
             }
-            if (!verifierGates.has("finish")) {
-                verified = true;
-                return { ok: true, content: "" };
-            }
-            const verdict = await callVerifier({
-                id: "finish",
-                goal: "Deliver the task outcome with evidence.",
-            });
-            if (verdict.allow) {
-                verified = true;
-                return { ok: true, content: "" };
-            }
-            return {
-                ok: false,
-                content: `Verification gate rejected completion: ${verdict.reason ?? "unsupported claim"}. ` +
-                    `Required action: ${verdict.requiredAction ?? "gather_evidence"}. ` +
-                    `Claim: ${summaryText.slice(0, 400)}`,
-            };
-        };
-    }
-    const currentRequest = userMessage(task.task);
-    const revivalOn = !!opts.revival;
-    const revivalWarnAt = revivalWarnPercent(opts.revival ? opts.revival.warnAtPercent : undefined);
-    let revivalWarned = false;
-    let revivalRequest;
-    const phaseOn = strategy.phases.length > 1 && opts.intrinsics?.phase !== false;
-    const system = () => ({
-        role: "system",
-        content: strategy.systemPrompt({ task: task.task, context, summary }) +
-            (phaseOn ? `\n\n${phaseDisciplineBlock(strategy.phases)}` : "") +
-            (revivalOn ? `\n\n${revivalBlock(revivalWarnAt)}` : "") +
-            (ledger
-                ? `\n\nPROGRESS LEDGER (authoritative task state):\n${renderLedger(ledger)}\n\nUse update_ledger to link evidence to each requirement and mark it verified. Do not claim completion while a required item is open or lacks evidence.`
-                : ""),
-    });
-    if (ledger) {
-        const updateLedger = defineTool({
+            return undefined;
+        }
+    };
+    const updateLedger = () => {
+        const tool = defineTool({
             name: "update_ledger",
-            description: "Update the task contract. Use it after gathering evidence: link a tool result to a requirement, mark it verified, record an open failure, or set the next step. Never invent evidence ids.",
+            description: "Update the task contract. Link a tool result to a requirement with a claim, verify it, record an open failure, or set the next step. Never invent evidence ids.",
             parameters: {
                 type: "object",
                 properties: {
@@ -248,6 +207,7 @@ async function runOne(task, opts, chain = {}) {
                         enum: [
                             "add_requirement",
                             "link_evidence",
+                            "verify",
                             "set_status",
                             "set_next_step",
                             "add_failure",
@@ -256,8 +216,10 @@ async function runOne(task, opts, chain = {}) {
                     },
                     text: { type: "string" },
                     required: { type: "boolean" },
+                    phase: { type: "string" },
                     requirementId: { type: "string" },
                     evidenceId: { type: "string" },
+                    claim: { type: "string" },
                     status: {
                         type: "string",
                         enum: ["open", "in_progress", "verified", "blocked", "waived"],
@@ -273,16 +235,42 @@ async function runOne(task, opts, chain = {}) {
                 const text = String(input.text ?? "").trim();
                 if (!text)
                     return { ok: false, content: "text is required" };
-                const requirement = addRequirement(ledger, { text, required: input.required !== false }, "agent");
+                const requirement = addRequirement(ledger, {
+                    text,
+                    required: input.required !== false,
+                    ...(typeof input.phase === "string" && input.phase
+                        ? { phase: input.phase }
+                        : {}),
+                }, "agent");
                 return {
                     ok: true,
                     content: `added ${requirement.id}: ${requirement.text}`,
                 };
             }
             if (op === "link_evidence") {
-                linkEvidence(ledger, String(input.requirementId ?? ""), String(input.evidenceId ?? ""));
+                const claim = String(input.claim ?? "").trim();
+                if (!claim) {
+                    return {
+                        ok: false,
+                        content: "claim is required: explain why this evidence establishes the requirement",
+                    };
+                }
+                linkEvidence(ledger, String(input.requirementId ?? ""), String(input.evidenceId ?? ""), claim);
                 return { ok: true, content: "evidence linked" };
             }
+            if (op === "verify") {
+                const claim = String(input.claim ?? "").trim();
+                if (!claim) {
+                    return {
+                        ok: false,
+                        content: "claim is required: explain why this evidence establishes the requirement",
+                    };
+                }
+                const requirementId = String(input.requirementId ?? "");
+                linkEvidence(ledger, requirementId, String(input.evidenceId ?? ""), claim);
+                setRequirementStatus(ledger, requirementId, "verified");
+                return { ok: true, content: "evidence linked and requirement verified" };
+            }
             if (op === "set_status") {
                 const status = String(input.status ?? "");
                 if (status === "superseded") {
@@ -319,12 +307,167 @@ async function runOne(task, opts, chain = {}) {
             }
             return { ok: false, content: `unknown ledger op "${op}"` };
         }, { verb: "Updating the progress ledger" });
-        available.set("update_ledger", updateLedger);
+        available.set("update_ledger", tool);
+        return tool;
+    };
+    const installCompletionGate = () => {
+        completionGate = async (summaryText, success) => {
+            const active = ledger;
+            const structural = ledgerGate(active, {
+                allowWaived: verifierConfig.allowWaived,
+            });
+            if (!structural.allow) {
+                if (!success) {
+                    // The agent explicitly reported a blocked/unsuccessful outcome. End
+                    // honestly instead of forcing it into the stalled path.
+                    for (const id of [...structural.open, ...structural.missingEvidence]) {
+                        const requirement = active.requirements.find((item) => item.id === id);
+                        if (requirement) {
+                            const note = `${id}: ${requirement.text}`;
+                            if (!active.openFailures.includes(note))
+                                active.openFailures.push(note);
+                        }
+                    }
+                    for (const failure of structural.failures) {
+                        if (!active.openFailures.includes(failure)) {
+                            active.openFailures.push(failure);
+                        }
+                    }
+                    return { ok: true, content: "" };
+                }
+                return {
+                    ok: false,
+                    content: [
+                        "Verification gate: required work is not complete.",
+                        `open: ${structural.open.join(", ") || "none"}`,
+                        `missingEvidence: ${structural.missingEvidence.join(", ") || "none"}`,
+                        `failures: ${structural.failures.join(" | ") || "none"}`,
+                        "Attach evidence to each requirement with update_ledger, resolve failures, and try again.",
+                    ].join("\n"),
+                };
+            }
+            if (!success)
+                return { ok: true, content: "" };
+            if (!verifierGates.has("finish")) {
+                verified = true;
+                return { ok: true, content: "" };
+            }
+            const required = active.requirements.filter((item) => item.required && item.status !== "superseded");
+            const verdict = await callJudge({ id: "finish", goal: "Deliver the task outcome with evidence." }, required, summaryText);
+            if (!verdict) {
+                verified = verifierConfig.onError !== "block";
+                return verified
+                    ? { ok: true, content: "" }
+                    : {
+                        ok: false,
+                        content: "Verification gate unavailable and onError is block; retry the judge before finishing.",
+                    };
+            }
+            const wanted = new Set(required.map((item) => item.id));
+            const unmet = verdict.requirements.filter((item) => wanted.has(item.id) && item.status !== "cleared");
+            if (verdict.cleared && unmet.length === 0) {
+                verified = true;
+                return { ok: true, content: "" };
+            }
+            const details = unmet.map((item) => {
+                const requirement = active.requirements.find((r) => r.id === item.id);
+                const claim = requirement?.evidenceIds
+                    .map((id) => active.evidence[id]?.claim)
+                    .find(Boolean);
+                const probability = item.probability !== undefined
+                    ? ` p=${item.probability.toFixed(2)}`
+                    : "";
+                return `${item.id}${probability} ${item.status}: ${requirement?.text ?? "unknown requirement"}${claim ? `; claim: ${claim}` : ""}`;
+            });
+            return {
+                ok: false,
+                content: `Verification gate rejected completion: ${verdict.rationale ?? "unsupported claim"}.\n` +
+                    (details.length
+                        ? `Unmet requirements:\n${details.join("\n")}`
+                        : "The judge did not clear the contract."),
+            };
+        };
+    };
+    const attachLedger = (next) => {
+        ledger = next;
+        phaseRejections = 0;
+        phaseEvidence = [];
+        updateLedger();
+        installCompletionGate();
+    };
+    if (verifierOn && ledger)
+        attachLedger(ledger);
+    else if (verifierOn && verifierConfig.create === "start") {
+        const compiled = await compileLedger({
+            llm: verifierConfig.llm ?? opts.llm,
+            taskId: contractTaskId,
+            source: requestText,
+            phases: strategy.phases,
+            reasoningEffort: "low",
+        });
+        if (compiled.usage)
+            budget.record(compiled.usage);
+        attachLedger(compiled.ledger);
     }
+    const currentRequests = input.messages;
+    const revivalOn = !!opts.revival;
+    const revivalWarnAt = revivalWarnPercent(opts.revival ? opts.revival.warnAtPercent : undefined);
+    let revivalWarned = false;
+    let revivalRequest;
+    const phaseOn = strategy.phases.length > 1 && opts.intrinsics?.phase !== false;
+    /**
+     * Stable blocks are the cacheable prefix; turn-scoped blocks are appended
+     * after the conversation. The ledger changes after every tool result, so it
+     * must never live in the system message.
+     */
+    const promptBlocks = () => [
+        {
+            id: "agent",
+            text: strategy.systemPrompt({ context, summary }),
+            stability: "stable",
+        },
+        {
+            id: "phase-discipline",
+            text: phaseOn ? phaseDisciplineBlock(strategy.phases) : undefined,
+            stability: "stable",
+        },
+        {
+            id: "budget-revival",
+            text: revivalOn ? revivalBlock(revivalWarnAt) : undefined,
+            stability: "stable",
+        },
+        {
+            id: "ledger",
+            text: ledger
+                ? [
+                    "## Runtime task state",
+                    "This is authoritative state, not a new user request.",
+                    renderLedger(ledger),
+                    "Use update_ledger to link evidence to each requirement and mark it verified. Do not claim completion while a required item is open or lacks evidence.",
+                ].join("\n\n")
+                : undefined,
+            stability: "turn",
+        },
+        {
+            id: "compaction",
+            text: compaction ? renderCompactionHandoff(compaction) : undefined,
+            stability: "turn",
+        },
+        {
+            id: "phase-state",
+            text: phase ? `Current phase: ${phase}` : undefined,
+            stability: "turn",
+        },
+    ];
+    const system = () => ({
+        role: "system",
+        content: renderPromptBlocks(promptBlocks(), "stable"),
+    });
+    const turnState = () => renderPromptBlocks(promptBlocks(), "turn");
     const messages = [
         system(),
         ...conversationHistory(prior?.messages ?? []),
-        currentRequest,
+        ...currentRequests,
     ];
     const compact = opts.compaction === false
         ? null
@@ -332,7 +475,46 @@ async function runOne(task, opts, chain = {}) {
     // The model's view of the transcript, bounded by assistant-text elision
     // (#77). `messages` stays whole — this only changes what is SENT.
     const elidedByMessage = new WeakMap();
-    const forModel = () => messages.map((m) => elidedByMessage.get(m) ?? m);
+    const forModel = (includeTurn = true) => {
+        const out = messages.map((m) => elidedByMessage.get(m) ?? m);
+        if (!includeTurn)
+            return out;
+        const turn = turnState();
+        if (turn) {
+            // Keep the turn's final message last (tests and tool protocol both rely
+            // on it); put the changing runtime state immediately before it so the
+            // stable prefix is still reused.
+            const insertAt = Math.max(1, out.length - 1);
+            out.splice(insertAt, 0, {
+                role: "user",
+                content: turn,
+            });
+        }
+        return out;
+    };
+    /**
+     * Cache the stable prefix, never the turn-scoped block. The adapter only
+     * emits `cache_control` when the consumer enabled `promptCache`.
+     */
+    const cacheBreakpointsFor = (modelMessages) => {
+        const markable = (message) => !!message &&
+            (message.role === "system" ||
+                message.role === "user" ||
+                (message.role === "assistant" && !!message.content));
+        const indexes = new Set();
+        if (markable(modelMessages[0]))
+            indexes.add(0);
+        const turn = turnState();
+        const turnIndex = turn
+            ? modelMessages.findIndex((message) => message.role === "user" && message.content === turn)
+            : -1;
+        let end = turnIndex > 0 ? turnIndex - 1 : modelMessages.length - 1;
+        while (end >= 0 && !markable(modelMessages[end]))
+            end--;
+        if (end >= 0)
+            indexes.add(end);
+        return [...indexes];
+    };
     const evidence = [];
     // Commands the provider detached. The engine owns their results: it polls at
     // every turn boundary and, before a normal finish, waits for what is left.
@@ -513,31 +695,76 @@ async function runOne(task, opts, chain = {}) {
                     content: `Unknown phase. Available: ${strategy.phases.map((item) => item.id).join(", ")}.`,
                 };
             const previous = phase;
-            if (verifierOn &&
-                ledger &&
-                verifierGates.has("phase") &&
-                target.id !== previous) {
-                const verdict = await callVerifier(target);
-                if (!verdict.allow) {
-                    emit({
-                        type: "guardrail",
-                        kind: "transition_rejected",
-                        detail: `${previous} -> ${target.id}: ${verdict.reason}`,
-                    });
-                    return {
-                        ok: false,
-                        content: [
-                            `Phase transition rejected: ${verdict.reason}`,
-                            `Required action: ${verdict.requiredAction}`,
-                            "Gather the missing evidence or update the ledger, then transition again.",
-                        ].join("\n"),
+            let forced = false;
+            if (target.id !== previous && ledger && verifierGates.has("phase")) {
+                const owned = ledger.requirements.filter((item) => item.required &&
+                    item.phase === previous &&
+                    item.status !== "verified" &&
+                    item.status !== "waived" &&
+                    item.status !== "superseded");
+                if (owned.length > 0) {
+                    const outgoing = strategy.phases.find((item) => item.id === previous) ?? {
+                        id: previous,
+                        goal: previous,
                     };
+                    const verdict = await callJudge(outgoing, owned, typeof input.reason === "string" ? input.reason : undefined);
+                    const wanted = new Set(owned.map((item) => item.id));
+                    const unmet = verdict
+                        ? verdict.requirements.filter((item) => wanted.has(item.id) && item.status !== "cleared")
+                        : [];
+                    if (verdict && (!verdict.cleared || unmet.length > 0)) {
+                        phaseRejections += 1;
+                        const details = unmet.map((item) => {
+                            const requirement = ledger.requirements.find((row) => row.id === item.id);
+                            const claim = requirement?.evidenceIds
+                                .map((id) => ledger.evidence[id]?.claim)
+                                .find(Boolean);
+                            const probability = item.probability !== undefined
+                                ? ` p=${item.probability.toFixed(2)}`
+                                : "";
+                            return `${item.id}${probability} ${item.status}: ${requirement?.text ?? "unknown requirement"}${claim ? `; claim: ${claim}` : ""}`;
+                        });
+                        const detail = `Phase ${previous} has unmet requirements.` +
+                            (details.length ? `\n${details.join("\n")}` : "");
+                        emit({
+                            type: "guardrail",
+                            kind: "transition_rejected",
+                            detail: `${previous} -> ${target.id}: ${detail}`,
+                        });
+                        if (phaseRejections <= maxPhaseRejections) {
+                            return {
+                                ok: false,
+                                content: [
+                                    `Phase transition rejected: ${previous} is not complete.`,
+                                    ...(details.length ? details : ["The judge did not clear the phase."]),
+                                    `Stay in ${previous}, finish the owned requirements, then transition again.`,
+                                ].join("\n"),
+                            };
+                        }
+                        for (const item of owned) {
+                            if (item.status !== "blocked" && item.status !== "verified") {
+                                setRequirementStatus(ledger, item.id, "in_progress");
+                            }
+                        }
+                        forced = true;
+                        emit({
+                            type: "guardrail",
+                            kind: "transition_rejected",
+                            detail: `forcing ${previous} -> ${target.id} after ${phaseRejections} rejection(s); requirements remain open and finish is still gated`,
+                        });
+                    }
                 }
             }
             phase = target.id;
+            phaseRejections = 0;
+            phaseEvidence = [];
             pauseRequested =
                 opts.pauseAfterPhase === previous && previous !== phase;
-            emit({ type: "phase_started", phase });
+            emit({
+                type: "phase_started",
+                phase,
+                ...(forced ? { via: "advance_forced" } : {}),
+            });
             return {
                 ok: true,
                 content: `Current approach: ${target.id} — ${target.goal}`,
@@ -592,6 +819,122 @@ async function runOne(task, opts, chain = {}) {
             };
         }, { verb: "Requesting budget for the remaining work" }));
     }
+    if (verifierOn && opts.intrinsics?.task !== false) {
+        available.set("create_task", defineTool({
+            name: "create_task",
+            description: "Create the task contract for this turn when the user asked for real work. " +
+                "State a measurable goal and 1-12 independently checkable requirements, each assigned " +
+                "to one of the strategy's phases. Do not include a source field; the engine derives " +
+                "the authoritative request from the user's messages.",
+            parameters: {
+                type: "object",
+                properties: {
+                    goal: { type: "string" },
+                    requirements: {
+                        type: "array",
+                        minItems: 1,
+                        maxItems: 12,
+                        items: {
+                            type: "object",
+                            properties: {
+                                text: { type: "string" },
+                                required: { type: "boolean" },
+                                phase: {
+                                    type: "string",
+                                    enum: strategy.phases.map((item) => item.id),
+                                },
+                                sourceQuote: { type: "string" },
+                            },
+                            required: ["text", "phase"],
+                            additionalProperties: false,
+                        },
+                    },
+                    nextStep: { type: "string" },
+                },
+                required: ["goal", "requirements"],
+                additionalProperties: false,
+            },
+        }, async (input) => {
+            if (ledger) {
+                return {
+                    ok: false,
+                    content: "the contract is already active; use update_ledger to change its state",
+                };
+            }
+            const goal = String(input.goal ?? "").trim();
+            if (!goal)
+                return { ok: false, content: "goal is required" };
+            const rows = Array.isArray(input.requirements)
+                ? input.requirements
+                : [];
+            if (rows.length < 1 || rows.length > 12) {
+                return {
+                    ok: false,
+                    content: "requirements must contain 1-12 items",
+                };
+            }
+            const phaseIds = new Set(strategy.phases.map((item) => item.id));
+            const requirements = [];
+            for (const [index, row] of rows.entries()) {
+                if (!row || typeof row !== "object" || Array.isArray(row)) {
+                    return {
+                        ok: false,
+                        content: `requirement ${index} must be an object`,
+                    };
+                }
+                const entry = row;
+                const text = String(entry.text ?? "").trim();
+                const phase = String(entry.phase ?? "");
+                if (!text) {
+                    return { ok: false, content: `requirement ${index} needs text` };
+                }
+                if (!phaseIds.has(phase)) {
+                    return {
+                        ok: false,
+                        content: `requirement ${index} has unknown phase "${phase}"`,
+                    };
+                }
+                const sourceQuote = typeof entry.sourceQuote === "string"
+                    ? entry.sourceQuote
+                    : undefined;
+                if (sourceQuote && !requestText.includes(sourceQuote)) {
+                    return {
+                        ok: false,
+                        content: `requirement ${index} sourceQuote is not in the user's request`,
+                    };
+                }
+                requirements.push({
+                    text,
+                    required: entry.required !== false,
+                    phase,
+                    ...(sourceQuote ? { sourceQuote } : {}),
+                });
+            }
+            const next = createLedger({
+                taskId: contractTaskId,
+                source: { kind: "user", text: requestText },
+                goal,
+                requirements: requirements.map((item) => ({
+                    ...item,
+                    origin: "agent",
+                })),
+            });
+            if (typeof input.nextStep === "string" && input.nextStep.trim()) {
+                next.nextStep = input.nextStep.trim();
+            }
+            attachLedger(next);
+            emit({ type: "task_created", ledger: next });
+            return {
+                ok: true,
+                content: [
+                    `Contract created: ${next.goal}`,
+                    ...next.requirements.map((item) => `${item.id}: ${item.text} (phase ${item.phase ?? "any"})`),
+                    "Use update_ledger to link evidence with a claim and verify each requirement.",
+                ].join("\n"),
+                meta: { ledger: next },
+            };
+        }, { verb: "Creating the task contract" }));
+    }
     /**
      * Settle operations only AFTER the conversation that contains their results
      * is durable. The opposite order opens the window this whole layer exists to
@@ -613,6 +956,7 @@ async function runOne(task, opts, chain = {}) {
                 summary,
                 messages: conversationHistory(messages),
                 phase: done ? resumePhase : phase,
+                ...(compaction ? { compaction } : {}),
                 ...(ledger ?? prior?.ledger
                     ? { ledger: ledger ?? prior?.ledger }
                     : {}),
@@ -696,6 +1040,7 @@ async function runOne(task, opts, chain = {}) {
             phase,
             evidence,
             ...(ledger ? { ledger } : {}),
+            ...(compaction ? { compaction } : {}),
             ...(verifierOn ? { verified } : {}),
             ...(revivalRequest &&
                 (reason === "budget_exceeded" || reason === "max_steps")
@@ -788,7 +1133,8 @@ async function runOne(task, opts, chain = {}) {
     }
     emit({
         type: "run_started",
-        task: task.task,
+        text: requestText,
+        ...(input.messages.length ? { messages: input.messages } : {}),
         phases: strategy.phases.map((item) => item.id),
     });
     if (chain.delivered?.length)
@@ -931,34 +1277,64 @@ async function runOne(task, opts, chain = {}) {
                 }
             }
             if (compact && estimateTokens(messages) > compact.maxEstimatedTokens) {
-                const folded = await compactConversation({
-                    llm: opts.llm,
-                    messages: forModel(),
-                    runningSummary: summary,
-                    keepRecentTokens: compact.keepRecentTokens,
-                    signal,
-                });
+                let folded = null;
+                if (ledger) {
+                    try {
+                        folded = await compactConversationStructured({
+                            llm: opts.llm,
+                            messages: forModel(false),
+                            ...(summary ? { previousSummary: summary } : {}),
+                            ...(compaction ? { previousHandoff: compaction } : {}),
+                            ledger,
+                            ...(checkpointRef ? { git: { checkpoint: checkpointRef } } : {}),
+                            keepRecentTokens: compact.keepRecentTokens,
+                            signal,
+                        });
+                    }
+                    catch {
+                        folded = null;
+                    }
+                }
+                if (!folded) {
+                    folded = await compactConversation({
+                        llm: opts.llm,
+                        messages: forModel(false),
+                        runningSummary: summary,
+                        keepRecentTokens: compact.keepRecentTokens,
+                        signal,
+                    });
+                }
                 if (folded) {
                     budget.record(folded.usage);
-                    summary = folded.summary;
+                    if (folded.handoff) {
+                        compaction = folded.handoff;
+                        summary = undefined;
+                    }
+                    else {
+                        summary = folded.summary;
+                        compaction = undefined;
+                    }
                     const tail = folded.keptMessages;
-                    // After a fold the model's earlier detail is gone from context;
-                    // point it at the durable record (see the Working notes section).
+                    // After a task reset the handoff is the durable record. A legacy
+                    // fold still points at the working-notes file.
                     const foldNote = {
                         role: "user",
-                        content: "[runtime] Context was folded to stay within the window. Your working notes " +
-                            "file (.anchor/notes.md, git-excluded) is the durable record of findings and " +
-                            "next steps — re-read it when you need detail from before the fold.",
+                        content: folded.handoff
+                            ? "[runtime] Context was reset to a durable task handoff. The authoritative task, requirements, evidence, failures, next steps, and recent observations are in the turn-scoped handoff; recent messages are retained verbatim."
+                            : "[runtime] Context was folded to stay within the window. Your working notes " +
+                                "file (.anchor/notes.md, git-excluded) is the durable record of findings and " +
+                                "next steps — re-read it when you need detail from before the fold.",
                     };
                     // Preserve the actual current request even if its earlier position
                     // was folded. Do not replace it with a generic "Begin" instruction.
-                    messages.splice(0, messages.length, system(), ...(tail.includes(currentRequest) ? [] : [currentRequest]), foldNote, ...tail);
+                    messages.splice(0, messages.length, system(), ...currentRequests.filter((message) => !tail.includes(message)), foldNote, ...tail);
                     emit({
                         type: "compacted",
                         removedMessages: folded.removedCount,
                         keptMessages: tail.length,
-                        summaryChars: summary.length,
-                        summary,
+                        summaryChars: folded.summary.length,
+                        summary: folded.summary,
+                        ...(folded.handoff ? { compaction: folded.handoff } : {}),
                         folding: folded.foldingPreview,
                         usage: folded.usage,
                     });
@@ -975,14 +1351,12 @@ async function runOne(task, opts, chain = {}) {
             // fold. A job that finished since the previous turn (including one
             // carried in from a previous run) rides this call, not the one after.
             await pollJobs();
-            // Refresh the authoritative contract every turn so evidence ids and
-            // status changes are visible after each tool result.
-            if (ledger)
-                messages[0] = system();
             steps++;
             emit({ type: "llm_call_started", phase, step: steps });
+            const modelMessages = forModel();
             const response = await opts.llm.stream({
-                messages: forModel(),
+                messages: modelMessages,
+                cacheBreakpoints: cacheBreakpointsFor(modelMessages),
                 tools: [...available.values()].map((tool) => ({
                     type: "function",
                     function: tool.definition,
@@ -1171,13 +1545,14 @@ async function runOne(task, opts, chain = {}) {
                         call.name === "update_ledger") {
                         return;
                     }
-                    recordEvidence(ledger, {
+                    const evidenceRef = recordEvidence(ledger, {
                         tool: call.name,
                         ref: `call:${call.id}`,
                         ok: result.ok,
                         summary: result.content.replace(/\s+/g, " ").slice(0, 500),
                         ...(result.meta ? { meta: result.meta } : {}),
                     });
+                    phaseEvidence.push(evidenceRef);
                 },
             });
             runaway = outcome.runaway;
@@ -1308,6 +1683,12 @@ function usageDelta(now, before) {
             : {}),
     };
 }
+/** A required obligation still needs work, or an open failure blocks finish. */
+function hasActiveLedger(ledger) {
+    if (!ledger)
+        return false;
+    return !ledgerGate(ledger).allow;
+}
 /**
  * A run chain (decision #82): one run at a time, with the consumer's inbox as
  * the source of what comes next. The chain shares one budget and carries
@@ -1318,7 +1699,7 @@ function usageDelta(now, before) {
  * cancellation, a caller-requested pause, or an exhausted budget — and returns
  * the last run's result with every run summarized on `.runs`.
  */
-async function runChain(task, opts) {
+async function runChain(input, opts) {
     const inbox = opts.inbox;
     const { store, channel } = inbox;
     if (!channel)
@@ -1337,7 +1718,7 @@ async function runChain(task, opts) {
     };
     let stepsBefore = 0;
     let jobs;
-    let current = task;
+    let current = input;
     let delivered;
     let claimed = [];
     let result;
@@ -1404,33 +1785,15 @@ async function runChain(task, opts) {
             return { ...result, runs };
         claimed = batch.map((message) => message.id);
         delivered = batch;
-        current = inbox.render ? inbox.render(batch) : renderInboxTask(batch);
+        current = inbox.render ? inbox.render(batch) : renderInboxTurn(batch);
     }
     // The zero-progress guard fired. Report the last run as it stands; `.runs`
     // shows how many interruptions it took to get here.
     return { ...result, runs };
 }
-export async function runAgent(task, opts) {
-    const verifierOn = opts.verifier !== undefined && opts.verifier !== false;
-    const intent = resolveTurnIntent(task.task, opts.intent ?? "auto");
-    // Conversation turns never create task state: no ledger, no verifier, no
-    // coding phases. A clear task uses the caller's agent, or the coding agent.
-    if (verifierOn && intent !== "task") {
-        const conversation = {
-            ...opts,
-            agent: chatAgent,
-            verifier: false,
-            intent: "chat",
-            ledger: undefined,
-        };
-        return opts.inbox
-            ? runChain(task, conversation)
-            : runOne(task, conversation);
-    }
-    const effective = {
-        ...opts,
-        agent: opts.agent ?? (verifierOn ? codingAgent : chatAgent),
-    };
-    return opts.inbox ? runChain(task, effective) : runOne(task, effective);
+export async function runAgent(input, opts) {
+    if (opts.inbox)
+        return runChain(input, opts);
+    return runOne(input, opts);
 }
 //# sourceMappingURL=loop.js.map