@kendoo.agentdesk/agentdesk 0.32.1 → 0.34.0

package/cli/engine/phases/SUMMARY.md

@@ -12,12 +12,13 @@ Task: {{TASK_ID}}
 
 ## Your mission
 
-1. Dictate the final summary in product terms. It must include:
+1. **Own the delivery report.** Reconcile the latest review and engine verification before dictating the summary. Distinguish delivered, unverified, blocked and user-approved deferred items. If review remains unresolved, report the work as incomplete; do not describe it as ready or substitute a successful test for an unmet acceptance criterion. It must include:
    - **What was done** — outcome-focused, non-technical.
    - **What was omitted / deferred** — everything from REVIEW's out-of-scope list plus anything the team explicitly skipped.
-   - **Manual steps** — actions the developer must perform (migrations, config, deploys).
+   - **Manual steps** — every remaining action outside this session, including access recovery, migrations, config and deploys. Name the responsible person or role and how completion will be confirmed. Required work blocked on access is not an out-of-scope deferral.
    - **PR link**.
    - **Session link**: {{SESSION_URL}}
-2. Delegate the tracker writes to Dennis and require the command output for each: verify the PR link is attached (attach it if missing), transition the task to "In Review", post the final comment.
+2. Delegate the tracker writes to Dennis and require the command output for each: verify the existing PR link is attached (attach it if missing), transition the task to "In Review" only when the review and engine verification permit it, and post the accurate final comment. If a write fails, identify the blocker in `status` and put the recovery owner/action in `manualSteps`, including who retries delivery after access is restored and the receipt needed to confirm it. Do not leave `manualSteps` empty when an access fix is required. Put only the confirmed posted text in `summaryComment`, leaving it empty if posting was not confirmed. The final user-facing update must state the outcome and any remaining action with its owner.
+3. **Lessons for future sessions.** The handoff has `lessons` and `retireLessons`. Propose a lesson only for something non-obvious that cost this session time and would cost the next one too — a setup step, seed data, an environment quirk, a deployment step, a review finding that keeps recurring. Each needs the evidence (what happened: the command and its outcome) and a scope: `project`, `area:<ui|copy|docs|api|data>`, or `path:<file or directory prefix>`. Never store secrets — name the env var instead. Do not restate what README, CLAUDE.md or the code already says. If an entry under PROJECT LESSONS proved wrong or obsolete in this session, retire it by its id with the reason. Empty arrays are the normal case.
 
-The structured output required by the schema is captured automatically — status, PR URL, deferred items, manual steps, and the summary comment exactly as posted. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.
+The structured output required by the schema is captured automatically — status, PR URL, deferred items, manual steps, the summary comment exactly as posted, lessons, and retirements. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/prompts.mjs

@@ -10,11 +10,12 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { wrapUntrusted, PROMPT_SECURITY_HEADER, MEMORY_INSTRUCTIONS, loadProjectMemory } from "../prompt.mjs";
+import { wrapUntrusted, PROMPT_SECURITY_HEADER, LEGACY_NOTES_HEADER } from "../prompt.mjs";
 import { generateContext } from "../detect.mjs";
 import { formatFindingsForRetry } from "./verdict.mjs";
 import { formatEvidenceForPrompt } from "./evidence.mjs";
 import { renderOpenItems } from "./handoff.mjs";
+import { renderLessonsSection } from "./lessons.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -40,6 +41,16 @@ export function renderTemplate(text, { flags = new Set(), vars = {} } = {}) {
   return out;
 }
 
+// Engine-provided project knowledge: active lessons in scope, then the
+// hand-written notes from before the ledger existed (read-only).
+function projectKnowledge({ lessons = [], projectNotes = "" }) {
+  let out = "";
+  const block = renderLessonsSection(lessons);
+  if (block) out += `\n\n${block}`;
+  if (projectNotes) out += `\n\n${LEGACY_NOTES_HEADER}\n\n${projectNotes}`;
+  return out;
+}
+
 function trackerSection(tracker, phases, vars) {
   if (!tracker) return "";
   let text;
@@ -67,7 +78,7 @@ function soloSearchAndCreate({ tracker, config }) {
 // tools, no lead and no review gate. Ported from the legacy buildSoloPrompt.
 export function renderSoloPrompt({
   agent, taskId, taskLink, description, tracker, config = {}, project = {},
-  sessionUrl, cwd, childStrategy,
+  sessionUrl, childStrategy, lessons = [], projectNotes = "",
 }) {
   const hasRealTaskId = !!taskId && !String(taskId).startsWith("new-") && !String(taskId).startsWith("task-");
   const vars = {
@@ -104,9 +115,7 @@ export function renderSoloPrompt({
   }
   if (config.instructions) body += `\n\n## ADDITIONAL INSTRUCTIONS\n\n${config.instructions}`;
 
-  body += `\n\n${MEMORY_INSTRUCTIONS}`;
-  const memory = loadProjectMemory(cwd);
-  if (memory) body += `\n\n### Current memory\n\n${memory}`;
+  body += projectKnowledge({ lessons, projectNotes });
 
   const context = generateContext(project);
   const now = new Date();
@@ -135,8 +144,8 @@ function createTaskSection({ tracker, config, description }) {
 // Returns the full user prompt for one phase's query().
 export function renderPhasePrompt({
   phase, taskId, taskLink, description, createTask, tracker, config = {}, project = {},
-  sessionUrl, cwd, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
-  roster = null, profile = null, handoffRetry = false,
+  sessionUrl, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
+  roster = null, profile = null, handoffRetry = false, lessons = [], projectNotes = "",
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -187,9 +196,7 @@ export function renderPhasePrompt({
     body += `\n\n## SESSION MEMORY (previous phases)\n\n${sessionMemory}`;
   }
 
-  body += `\n\n${MEMORY_INSTRUCTIONS}`;
-  const memory = loadProjectMemory(cwd);
-  if (memory) body += `\n\n### Current memory\n\n${memory}`;
+  body += projectKnowledge({ lessons, projectNotes });
 
   if (config.projectAgents?.length) {
     project.configAgents = config.projectAgents.map(a => ({ ...a, type: a.type || "declared", source: ".agentdesk.json" }));

package/cli/engine/recovery.mjs

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { PHASE_OUTPUT_SCHEMAS } from "./schemas.mjs";
+
+export function checkpointStore(directory, sessionId, { resume = false } = {}) {
+  mkdirSync(directory, { recursive: true });
+  const path = join(directory, `recovery-${createHash("sha256").update(sessionId).digest("hex").slice(0, 24)}.json`);
+  let data = { version: 1, sessionId, queue: null, receipts: {}, outcomes: [], instructions: [], transcript: [], totals: null };
+  if (resume) {
+    if (!existsSync(path)) throw new Error("No recovery checkpoint exists for this session. Start a separately reviewed continuation instead.");
+    data = JSON.parse(readFileSync(path, "utf8"));
+    if (data.version !== 1 || data.sessionId !== sessionId) throw new Error("Recovery checkpoint does not match this session.");
+  }
+  const save = patch => {
+    data = { ...data, ...patch };
+    writeFileSync(`${path}.tmp`, JSON.stringify(data), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+  };
+  return { get data() { return data; }, save, path };
+}
+
+export function validHandoff(phase, value) {
+  const matches = (schema, v) => {
+    if (schema.type === "object") return !!v && typeof v === "object" && !Array.isArray(v)
+      && (schema.required || []).every(k => k in v)
+      && Object.entries(v).every(([k, item]) => schema.properties?.[k] ? matches(schema.properties[k], item) : schema.additionalProperties !== false);
+    if (schema.type === "array") return Array.isArray(v) && v.every(item => matches(schema.items, item));
+    if (schema.type === "string") return typeof v === "string" && (!schema.enum || schema.enum.includes(v));
+    if (schema.type === "integer") return Number.isInteger(v);
+    return true;
+  };
+  return !!PHASE_OUTPUT_SCHEMAS[phase] && matches(PHASE_OUTPUT_SCHEMAS[phase], value);
+}
+
+// Conservative journal for externally visible commands. Exact repeats are
+// refused; uncertain responses require reconciliation, never automatic replay.
+export function externalActionKey(tool, input = {}) {
+  const command = String(input.command || "");
+  const external = tool.startsWith("mcp__") && /create|update|delete|transition|comment|post|send/i.test(tool) || (tool === "Bash" && (
+    /\bgh\s+(?:pr|issue)\s+(?:create|comment|edit|merge|close|reopen)\b/.test(command)
+    || /\bcurl\b/.test(command) && /(?:--data|-d\b|-X\s*(?:POST|PUT|PATCH|DELETE)|--request\s+(?:POST|PUT|PATCH|DELETE))/.test(command)
+  ));
+  if (!external) return null;
+  const canonical = value => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
+  // Bash descriptions/timeouts are presentation, not the external action.
+  return createHash("sha256").update(JSON.stringify([tool, tool === "Bash" ? command.trim() : canonical(input)])).digest("hex");
+}
+
+export function journalExternalActions(options, recovery) {
+  const previousPre = options.hooks.PreToolUse[0].hooks[0];
+  options.hooks.PreToolUse[0].hooks[0] = async input => {
+    const decision = await previousPre(input);
+    if (decision.hookSpecificOutput?.permissionDecision === "deny") return decision;
+    const key = externalActionKey(input.tool_name, input.tool_input);
+    if (!key) return decision;
+    const receipt = recovery.data.receipts[key];
+    if (receipt) return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny",
+      permissionDecisionReason: `This external action is recorded as ${receipt.state}. Do not repeat or reword it to bypass this guard. Inspect the provider to reconcile its result; preserve the existing PR/comment.` } };
+    recovery.save({ receipts: { ...recovery.data.receipts, [key]: { state: "pending", tool: input.tool_name, at: Date.now() } } });
+    return decision;
+  };
+  const previousPost = options.hooks.PostToolUse[0].hooks[0];
+  options.hooks.PostToolUse[0].hooks[0] = async input => {
+    const result = await previousPost(input);
+    const key = externalActionKey(input.tool_name, input.tool_input);
+    if (key && recovery.data.receipts[key]) {
+      // A tool returning is not proof of an external write succeeding. Only
+      // the provider-specific outcome parser can produce a confirmed receipt.
+      recovery.save({ receipts: { ...recovery.data.receipts, [key]: { ...recovery.data.receipts[key], state: "response-received" } } });
+    }
+    return result;
+  };
+}
+
+// A PreToolUse matcher that lets only the SDK's schema tool through and denies
+// everything else with the given reason. Shared by the engine's handoff repair
+// and the opt-in SDK smoke tests, so the production guard and the diagnostics
+// cannot drift apart.
+export function structuredOutputOnlyHook(reason) {
+  return { hooks: [async input => input.tool_name === "StructuredOutput" ? {} : {
+    hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
+  }] };
+}
+
+export function repairQueryOptions(options) {
+  return { ...options, agents: {}, agent: undefined, allowedTools: ["StructuredOutput"], tools: ["StructuredOutput"], mcpServers: {},
+    hooks: { PreToolUse: [structuredOutputOnlyHook("Handoff repair cannot execute tools.")] }, maxTurns: 2 };
+}
+
+export function trackerAccessDenied(denials) {
+  return denials.some(d => /mcp__.*(?:jira|atlassian|linear|github)/i.test(d.tool_name || "")
+    || d.tool_name === "Bash" && /\bcurl\b|\bgh\s+(?:issue|pr)\s+(?:view|list)\b/.test(d.tool_input?.command || ""));
+}
+
+export function recoveryBrief(data, tree) {
+  return [
+    "## Authoritative task and user instructions",
+    `Original task: ${data.taskId || ""}\n${data.description || ""}`,
+    "Stay within this objective. Propose unrelated discoveries separately; do not expand scope to repair lost context.",
+    ...data.instructions.map((i, n) => `${n + 1}. ${i.text}`),
+    "Latest user corrections override earlier plans. Acknowledge their effect before working.",
+    `Current revision: ${tree.revision || "unknown"}; working tree clean: ${tree.clean}. Preserve unfinished edits. Inspect the diff and existing PR before continuing. Prior verification must be re-established.`,
+    `Recorded external actions: ${JSON.stringify(data.receipts)}`,
+    `Confirmed provider outcomes: ${JSON.stringify(data.outcomes || [])}`,
+    "Do not repeat confirmed actions. A pending or response-received entry is uncertain: reconcile it against the provider first. Never reword commands to bypass the replay guard. Never claim an action failed merely because this phase cannot access the provider.",
+  ].join("\n\n");
+}

package/cli/engine/schemas.mjs

@@ -11,6 +11,33 @@ import { VERDICT_SCHEMA } from "./verdict.mjs";
 
 const strList = { type: "array", items: { type: "string" } };
 
+// What SUMMARY/SOLO hand back for the project lessons ledger. The engine
+// records these with provenance; agents never write the ledger themselves.
+const lessonList = {
+  type: "array",
+  description: "non-obvious things that cost this session time and would cost the next one too; empty when nothing qualifies",
+  items: {
+    type: "object",
+    additionalProperties: false,
+    required: ["text", "scope", "evidence"],
+    properties: {
+      text: { type: "string", description: "one actionable sentence" },
+      scope: { type: "string", description: "project | area:<ui|copy|docs|api|data> | path:<file or directory prefix>" },
+      evidence: { type: "string", description: "what happened that proves it (command and outcome)" },
+    },
+  },
+};
+const retireList = {
+  type: "array",
+  description: "ids from PROJECT LESSONS that proved wrong or obsolete in this session; empty when none did",
+  items: {
+    type: "object",
+    additionalProperties: false,
+    required: ["id", "reason"],
+    properties: { id: { type: "string" }, reason: { type: "string" } },
+  },
+};
+
 export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
   INTAKE: {
     type: "object",
@@ -44,8 +71,8 @@ export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
       filesToModify: strList,
       decisions: strList,
       risks: strList,
-      assignments: { ...strList, description: "who does what during execution" },
-      steps: { ...strList, description: "ordered implementation steps" },
+      assignments: { ...strList, description: "each assignment names one owner, a bounded deliverable, dependencies, and acceptance evidence" },
+      steps: { ...strList, description: "ordered implementation steps with owners; implementation and the subsequent audit both happen in EXECUTION, with audit approval required before publishing" },
     },
   },
   EXECUTION: {
@@ -65,25 +92,29 @@ export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
   SOLO: {
     type: "object",
     additionalProperties: false,
-    required: ["summary", "filesChanged", "prUrl", "deferred", "manualSteps"],
+    required: ["summary", "filesChanged", "prUrl", "deferred", "manualSteps", "lessons", "retireLessons"],
     properties: {
       summary: { type: "string" },
       filesChanged: strList,
       prUrl: { type: "string", description: "empty string if no PR was created" },
       deferred: strList,
       manualSteps: strList,
+      lessons: lessonList,
+      retireLessons: retireList,
     },
   },
   SUMMARY: {
     type: "object",
     additionalProperties: false,
-    required: ["status", "prUrl", "deferred", "manualSteps", "summaryComment"],
+    required: ["status", "prUrl", "deferred", "manualSteps", "summaryComment", "lessons", "retireLessons"],
     properties: {
-      status: { type: "string" },
+      status: { type: "string", description: "accurate delivery outcome, including any unresolved review or tracker-write blocker" },
       prUrl: { type: "string" },
-      deferred: strList,
-      manualSteps: strList,
-      summaryComment: { type: "string", description: "the final tracker comment as posted" },
+      deferred: { ...strList, description: "only explicitly out-of-scope or user-approved deferrals; required work blocked on access belongs in status and manualSteps" },
+      manualSteps: { ...strList, description: "each remaining manual action with its named owner and completion evidence; include access recovery and the subsequent delivery retry when a tracker write failed; empty only when no manual action remains" },
+      summaryComment: { type: "string", description: "the final tracker comment exactly as confirmed posted; empty string if posting failed or was not confirmed" },
+      lessons: lessonList,
+      retireLessons: retireList,
     },
   },
 });