agent-dealer 0.1.4 → 0.1.6

package/bundle/server/dist/runners/prompts.js

@@ -1,6 +1,6 @@
 import { getLatestArtifact } from "../repository/runs.js";
 import { documentOutputHint } from "./persist.js";
-import { humanFeedbackText, appendPlanRetrySections, appendExecutionRetrySections, retryContext, } from "./run-context.js";
+import { humanFeedbackText, appendPlanRetrySections, appendExecutionRetrySections, retryContext, reviewQaPairs, } from "./run-context.js";
 export function workspaceForRun(run) {
     return run.repo ?? run.artifactWorkspace ?? process.cwd();
 }
@@ -45,6 +45,13 @@ function outboundDraftContractSection() {
         "- Do not perform the send — the human approves and the server delivers verbatim.",
     ].join("\n");
 }
+function reviewQaSections(run) {
+    const pairs = reviewQaPairs(run);
+    if (pairs.length === 0)
+        return [];
+    const lines = pairs.flatMap((p) => [`Q: ${p.question}`, `A: ${p.answer}`, ``]);
+    return [`## Review Q&A`, `The human asked about the prior result. Honor these answers.`, ...lines];
+}
 export function buildExecutionContinuationPrompt(run) {
     const ctx = retryContext(run);
     const parts = [
@@ -64,6 +71,7 @@ export function buildExecutionContinuationPrompt(run) {
             parts.push(`## Human feedback`, feedback, ``);
         }
     }
+    parts.push(...reviewQaSections(run));
     if (run.deckId) {
         parts.push(`Use Agent Deck: bind_workspace({ deckId: "${run.deckId}", workspaceRoot: "${workspaceForRun(run)}" })`);
         if (run.playbookId) {
@@ -104,6 +112,8 @@ export function buildExecutionPrompt(run) {
         }
     }
     parts.push(...planAnswersSections(run));
+    parts.push(...planDelegationSections(run));
+    parts.push(...reviewQaSections(run));
     if (run.taskCategory === "content" || run.taskCategory === "research") {
         parts.push(`## Deliverable`, documentOutputHint(run), `You MUST write the file using your Write/edit tool — do not only print markdown in chat.`, ``);
     }
@@ -155,6 +165,35 @@ export function buildReflectPrompt(run, opts) {
     }
     return parts.join("\n");
 }
+export function buildQaPrompt(run, question, opts) {
+    const parts = [
+        `The human reviewing your finished work has a question about it.`,
+        ``,
+        `IMPORTANT:`,
+        `- Answer the question. Do NOT modify anything — no files, no edits, no commands, no sends.`,
+        `- You may read files to check your own work.`,
+        `- Answer concisely in markdown. No preamble, no restating the question.`,
+        `- If you do not know, say so plainly rather than guessing.`,
+        ``,
+    ];
+    if (opts.grounded) {
+        parts.push(`## Task`, taskText(run), ``);
+    }
+    else {
+        parts.push(`Your original session is gone, so the relevant context is reproduced below.`, ``, `## Task`, taskText(run), ``);
+        const plan = artifactMarkdown("approved_plan", run.id);
+        if (plan)
+            parts.push(`## Approved plan`, plan, ``);
+        const result = artifactMarkdown("execution_result", run.id);
+        if (result)
+            parts.push(`## Execution outcome`, result, ``);
+        const doc = artifactMarkdown("document", run.id);
+        if (doc)
+            parts.push(`## Deliverable`, doc, ``);
+    }
+    parts.push(`## Question`, question);
+    return parts.join("\n");
+}
 function hasOutboundSendGate(category) {
     return category === "communication" || category === "email";
 }
@@ -200,6 +239,61 @@ function planAnswersSections(run) {
         return [];
     }
 }
+function planDelegationSections(run) {
+    const ansArt = getLatestArtifact(run.id, "plan_answers");
+    if (!ansArt?.contentJson)
+        return [];
+    try {
+        const ans = JSON.parse(ansArt.contentJson);
+        if (ans.outcome !== "delegated")
+            return [];
+        const triArt = getLatestArtifact(run.id, "plan_triage");
+        const questions = triArt?.contentJson
+            ? JSON.parse(triArt.contentJson).questions
+            : [];
+        if (questions.length === 0)
+            return [];
+        const lines = questions.map((q) => {
+            const options = q.options.map((o) => o.label).join(" | ");
+            return `- ${q.question} (options: ${options})`;
+        });
+        return [
+            "## Unanswered plan questions",
+            "The reviewer chose to proceed without answering these. Use your best judgment.",
+            ...lines,
+            "",
+        ];
+    }
+    catch {
+        return [];
+    }
+}
+export function buildPlanFeedbackPrompt(run, feedback) {
+    return [
+        "The human reviewed your plan and wants a revision. Revise the plan accordingly — do not execute anything.",
+        "",
+        "## Task",
+        taskText(run),
+        "",
+        "## Human feedback",
+        feedback.trim(),
+        "",
+        planTriageContractSection(run.taskCategory),
+    ].join("\n");
+}
+export function buildPlanEditedReplanPrompt(run, editedMarkdown) {
+    return [
+        "The human edited the plan directly. Start from their edits and produce a refined plan — do not execute anything.",
+        "",
+        "## Task",
+        taskText(run),
+        "",
+        "## Human-edited plan",
+        editedMarkdown.trim(),
+        "",
+        planTriageContractSection(run.taskCategory),
+    ].join("\n");
+}
 export function buildPlanRevisePrompt(run, questions, answers) {
     const qa = answers.map((a) => {
         const q = questions.find((x) => x.id === a.questionId);

package/bundle/server/dist/runners/prompts.test.js

@@ -9,7 +9,7 @@ const { migrate } = await import("../db/index.js");
 const { BUILTIN_AGENT_CLAUDE_ID } = await import("@agent-dealer/shared");
 const { updateAgent } = await import("../repository/agents.js");
 const { addArtifact, createRun } = await import("../repository/runs.js");
-const { buildExecutionPrompt, buildPlanPrompt, buildPlanRevisePrompt } = await import("./prompts.js");
+const { buildExecutionPrompt, buildPlanPrompt, buildPlanEditedReplanPrompt, buildPlanFeedbackPrompt, buildPlanRevisePrompt, buildQaPrompt } = await import("./prompts.js");
 const QUESTIONS = [
     {
         id: "q1",
@@ -75,6 +75,18 @@ test("execution prompt omits answers section when none exist", () => {
     addArtifact(run.id, "approved_plan", { markdown: "# Plan" }, "human");
     assert.doesNotMatch(buildExecutionPrompt(run), /Human answers to plan questions/);
 });
+test("feedback replan prompt includes human comments and contract", () => {
+    const run = makeRun();
+    const prompt = buildPlanFeedbackPrompt(run, "Add integration tests and skip the migration step.");
+    assert.match(prompt, /Add integration tests/);
+    assert.match(prompt, /"verdict"/);
+});
+test("edited replan prompt includes human-edited markdown", () => {
+    const run = makeRun();
+    const prompt = buildPlanEditedReplanPrompt(run, "# Revised plan\n\n1. Ship feature");
+    assert.match(prompt, /Revised plan/);
+    assert.match(prompt, /Ship feature/);
+});
 test("revise prompt pairs each answer with its question and re-states the contract", () => {
     const run = makeRun();
     const prompt = buildPlanRevisePrompt(run, QUESTIONS, [{ questionId: "q1", freeText: "Use flat files instead" }]);
@@ -82,6 +94,85 @@ test("revise prompt pairs each answer with its question and re-states the contra
     assert.match(prompt, /Use flat files instead/);
     assert.match(prompt, /"verdict"/);
 });
+test("delegated plan answers surface the unanswered questions to the executor", () => {
+    const run = makeRun();
+    addArtifact(run.id, "draft_plan", { markdown: "# Plan" }, "agent");
+    addArtifact(run.id, "plan_triage", {
+        verdict: "needs_review", rationale: "r", questions: QUESTIONS, parseFallback: false, consumed: true,
+    }, "agent");
+    addArtifact(run.id, "approved_plan", { markdown: "# Plan" }, "human");
+    addArtifact(run.id, "plan_answers", { answers: [], outcome: "delegated", answeredAt: new Date().toISOString() }, "human");
+    const prompt = buildExecutionPrompt(run);
+    assert.match(prompt, /## Unanswered plan questions/);
+    assert.match(prompt, /Which storage backend\?/);
+    assert.match(prompt, /SQLite/);
+    assert.match(prompt, /best judgment/i);
+    assert.doesNotMatch(prompt, /## Human answers to plan questions/);
+});
+test("execution prompt renders answered review Q&A from the lineage parent", () => {
+    const parent = makeRun();
+    addArtifact(parent.id, "approved_plan", { markdown: "# Plan" }, "human");
+    addArtifact(parent.id, "result_qa", {
+        exchangeId: "x1",
+        question: "Did you run the tests?",
+        answer: "Yes, all 12 pass.",
+        status: "answered",
+        sessionResumed: true,
+        askedAt: "2026-07-08T00:00:00.000Z",
+        answeredAt: "2026-07-08T00:01:00.000Z",
+    }, "agent");
+    addArtifact(parent.id, "result_qa", {
+        exchangeId: "x2",
+        question: "Pending one",
+        status: "pending",
+        sessionResumed: true,
+        askedAt: "2026-07-08T00:02:00.000Z",
+    }, "human");
+    const retry = createRun({
+        title: "Prompt test task",
+        taskCategory: "other",
+        status: "plan_approved",
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+    }, { lineageId: parent.lineageId ?? parent.id });
+    addArtifact(retry.id, "approved_plan", { markdown: "# Plan" }, "human");
+    addArtifact(retry.id, "feedback", { markdown: "Tighten the summary" }, "human");
+    const prompt = buildExecutionPrompt(retry);
+    assert.match(prompt, /## Review Q&A/);
+    assert.match(prompt, /Did you run the tests\?/);
+    assert.match(prompt, /Yes, all 12 pass\./);
+    assert.doesNotMatch(prompt, /Pending one/);
+});
+test("execution prompt omits the Q&A section when there are no answered exchanges", () => {
+    const run = makeRun();
+    addArtifact(run.id, "approved_plan", { markdown: "# Plan" }, "human");
+    assert.doesNotMatch(buildExecutionPrompt(run), /## Review Q&A/);
+});
+test("grounded qa prompt asks the question without re-stating artifacts", () => {
+    const run = makeRun();
+    addArtifact(run.id, "approved_plan", { markdown: "# Plan\n1. Use SQLite" }, "human");
+    const prompt = buildQaPrompt(run, "Why SQLite?", { grounded: true });
+    assert.match(prompt, /Why SQLite\?/);
+    assert.match(prompt, /Do NOT modify anything/i);
+    assert.doesNotMatch(prompt, /## Approved plan/);
+});
+test("ungrounded qa prompt rebuilds context from artifacts", () => {
+    const run = makeRun();
+    addArtifact(run.id, "approved_plan", { markdown: "# Plan\n1. Use SQLite" }, "human");
+    addArtifact(run.id, "execution_result", { phase: "execute", exitCode: 0, resultText: "Wrote the doc", isError: false }, "agent");
+    addArtifact(run.id, "document", { path: "/tmp/x.md", title: "x", markdown: "# Deliverable body" }, "agent");
+    const prompt = buildQaPrompt(run, "Why SQLite?", { grounded: false });
+    assert.match(prompt, /## Approved plan/);
+    assert.match(prompt, /## Execution outcome/);
+    assert.match(prompt, /## Deliverable/);
+    assert.match(prompt, /# Deliverable body/);
+    assert.match(prompt, /Why SQLite\?/);
+});
+test("qa prompt never asks for a json block or an outbound draft", () => {
+    const run = makeRun();
+    const prompt = buildQaPrompt(run, "What did you check?", { grounded: true });
+    assert.doesNotMatch(prompt, /Outbound actions/);
+    assert.doesNotMatch(prompt, /"verdict"/);
+});
 test("execution prompt includes outbound draft contract", () => {
     const run = makeRun();
     addArtifact(run.id, "approved_plan", { markdown: "# Plan" }, "human");

package/bundle/server/dist/runners/qa.js

@@ -0,0 +1,41 @@
+import { QA_PHASE_BUDGET } from "@agent-dealer/shared";
+import { runClaude, runCursor } from "./claude.js";
+import { buildQaPrompt } from "./prompts.js";
+import { extractResultIsError, extractResultText, extractUsage, parseNdjson } from "./stream-json.js";
+/** One read-only Q&A turn against a finished run. Resumes the execute session when we still have it. */
+export async function runQa(run, question, resumeSessionId) {
+    let result;
+    const runtime = run.runtime ?? "claude_code";
+    const executeModel = run.executeModel ?? undefined;
+    if (runtime === "cursor_local") {
+        const prompt = buildQaPrompt(run, question, { grounded: Boolean(resumeSessionId) });
+        result = await runCursor(run, "qa", executeModel, {
+            promptOverride: prompt,
+            ...(resumeSessionId ? { resumeSessionId } : {}),
+        });
+        // Resume can fail when the local Cursor chat has expired. Retry ungrounded from artifacts.
+        if (result.exitCode !== 0 && resumeSessionId) {
+            result = await runCursor(run, "qa", executeModel, {
+                promptOverride: buildQaPrompt(run, question, { grounded: false }),
+            });
+        }
+    }
+    else {
+        result = await runClaude(run, "qa", executeModel, {
+            promptOverride: buildQaPrompt(run, question, { grounded: Boolean(resumeSessionId) }),
+            ...(resumeSessionId ? { resumeSessionId } : {}),
+        });
+    }
+    const events = parseNdjson(result.transcript);
+    const usage = extractUsage(events, "qa", runtime);
+    usage.maxTurns = QA_PHASE_BUDGET.maxTurns;
+    usage.maxBudgetUsd = QA_PHASE_BUDGET.maxBudgetUsd;
+    const answer = extractResultText(events)?.trim() ?? "";
+    const failed = result.exitCode !== 0 || extractResultIsError(events) || !answer;
+    return {
+        ok: !failed,
+        answer,
+        error: failed ? `qa exited ${result.exitCode}${answer ? "" : " with no answer"}` : undefined,
+        usage,
+    };
+}

package/bundle/server/dist/runners/run-context.js

@@ -1,4 +1,5 @@
 import { getLatestArtifact, getLineageParentRun, listArtifacts } from "../repository/runs.js";
+import { listQaExchanges } from "../repository/result-qa.js";
 const EXCERPT = 2000;
 function artifactMarkdown(runId, kind) {
     const art = getLatestArtifact(runId, kind);
@@ -64,6 +65,20 @@ export function lineageParentExecuteSessionId(run) {
     }
     return null;
 }
+/** Answered result Q&A from this run and its lineage parent — a retry inherits the discussion. */
+export function reviewQaPairs(run) {
+    const parent = getLineageParentRun(run);
+    const runIds = parent ? [parent.id, run.id] : [run.id];
+    const pairs = [];
+    for (const id of runIds) {
+        for (const e of listQaExchanges(id)) {
+            if (e.status === "answered" && e.answer) {
+                pairs.push({ question: e.question, answer: e.answer });
+            }
+        }
+    }
+    return pairs;
+}
 function priorExecuteTraceTail(run, max = 12) {
     const parent = getLineageParentRun(run);
     if (!parent)

package/bundle/server/dist/usage-summary.js

@@ -8,10 +8,13 @@ function parseUsage(contentJson) {
         return null;
     }
 }
-function labelUsage(lineageIdx, phase, planCount, execCount) {
+function labelUsage(lineageIdx, phase, planCount, execCount, qaCount) {
     if (phase === "plan") {
         return planCount > 1 ? `plan ${planCount}` : "plan";
     }
+    if (phase === "qa") {
+        return qaCount > 1 ? `Q&A ${qaCount}` : "Q&A";
+    }
     if (lineageIdx === 0) {
         return execCount > 1 ? `execute ${execCount}` : "execute";
     }
@@ -23,6 +26,7 @@ export function buildLineageUsageSummary(run, opts) {
     lineageRuns.forEach((lr, lineageIdx) => {
         let planCount = 0;
         let execCount = 0;
+        let qaCount = 0;
         const arts = opts?.artifactsByRunId?.[lr.id] ?? listArtifacts(lr.id);
         for (const art of arts) {
             if (art.kind !== "usage" || !art.contentJson)
@@ -32,11 +36,14 @@ export function buildLineageUsageSummary(run, opts) {
                 continue;
             if (usage.phase === "plan")
                 planCount++;
+            else if (usage.phase === "qa")
+                qaCount++;
             else
                 execCount++;
-            const resolved = resolveBudgetForPhase(lr, usage.phase);
+            // qa has no configurable budget — its cap is snapshotted on the artifact
+            const resolved = usage.phase === "qa" ? null : resolveBudgetForPhase(lr, usage.phase);
             lines.push({
-                label: labelUsage(lineageIdx, usage.phase, planCount, execCount),
+                label: labelUsage(lineageIdx, usage.phase, planCount, execCount, qaCount),
                 usage,
                 maxTurns: usage.maxTurns ?? resolved?.maxTurns,
                 maxBudgetUsd: usage.maxBudgetUsd ?? resolved?.maxBudgetUsd,

package/bundle/server/dist/usage-summary.test.js

@@ -0,0 +1,33 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-usage-"));
+process.env.MAX_CONCURRENT_RUNS = "0";
+const { migrate } = await import("./db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID } = await import("@agent-dealer/shared");
+const { updateAgent } = await import("./repository/agents.js");
+const { addArtifact, createRun, getRun, transitionRun } = await import("./repository/runs.js");
+const { buildLineageUsageSummary } = await import("./usage-summary.js");
+before(() => {
+    migrate();
+    updateAgent(BUILTIN_AGENT_CLAUDE_ID, { workspaceRoot: process.env.AGENT_DEALER_HOME });
+});
+test("qa usage artifacts get their own label and do not inflate the execute count", () => {
+    const run = createRun({
+        title: "Usage test",
+        taskCategory: "other",
+        status: "plan_approved",
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+    });
+    transitionRun(run.id, "running");
+    transitionRun(run.id, "review");
+    addArtifact(run.id, "usage", { phase: "execute", runtime: "claude_code", totalCostUsd: 1 }, "agent");
+    addArtifact(run.id, "usage", { phase: "qa", runtime: "claude_code", totalCostUsd: 0.1 }, "agent");
+    addArtifact(run.id, "usage", { phase: "qa", runtime: "claude_code", totalCostUsd: 0.1 }, "agent");
+    const summary = buildLineageUsageSummary(getRun(run.id));
+    const labels = summary.lines.map((l) => l.label);
+    assert.deepEqual(labels, ["execute", "Q&A", "Q&A 2"]);
+    assert.equal(Math.round(summary.total.totalCostUsd * 100) / 100, 1.2);
+});

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "dist/index.js",
   "files": [