@kendoo.agentdesk/agentdesk 0.27.0 → 0.28.0

package/cli/engine/prompts.mjs

@@ -0,0 +1,181 @@
+// Phase prompt rendering for the main thread (the lead).
+//
+// Templates live in ./phases/<PHASE>.md and ./tracker/<tracker>.md. The
+// template language is the same minimal one prompts/phased.md used:
+//   {{VAR}}                    substitution
+//   {{#FLAG}} ... {{/FLAG}}    kept when FLAG is on, removed otherwise
+// Untrusted content (task description) is wrapped with wrapUntrusted() and
+// the security header from cli/prompt.mjs is prepended, as before.
+
+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 { generateContext } from "../detect.mjs";
+import { formatFindingsForRetry } from "./verdict.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const cache = new Map();
+function template(rel) {
+  if (!cache.has(rel)) cache.set(rel, readFileSync(join(here, rel), "utf-8"));
+  return cache.get(rel);
+}
+
+const SECTION_RE = /\{\{#([A-Z_]+)\}\}([\s\S]*?)\{\{\/\1\}\}/g;
+
+export function renderTemplate(text, { flags = new Set(), vars = {} } = {}) {
+  let out = text;
+  // Sections nest (e.g. CHILD_BRANCH inside CHILD_TASKS). A kept outer body
+  // is emitted verbatim, so its inner markers need another pass; loop until
+  // a pass changes nothing. Bounded, in case of a malformed template.
+  for (let pass = 0; pass < 10; pass++) {
+    const next = out.replace(SECTION_RE, (_, flag, body) => (flags.has(flag) ? body : ""));
+    if (next === out) break;
+    out = next;
+  }
+  out = out.replace(/\{\{([A-Z_]+)\}\}/g, (_, name) => (name in vars ? String(vars[name] ?? "") : ""));
+  return out;
+}
+
+function trackerSection(tracker, phases, vars) {
+  if (!tracker) return "";
+  let text;
+  try { text = template(`tracker/${tracker}.md`); } catch { return ""; }
+  const flags = new Set(["COMMON", ...(Array.isArray(phases) ? phases : [phases])]);
+  return renderTemplate(text, { flags, vars }).trim();
+}
+
+function soloSearchAndCreate({ tracker, config }) {
+  const jiraBase = (config.jira?.baseUrl || "").replace(/\/+$/, "");
+  const search = {
+    linear: "Search Linear for an existing issue related to the task description using the GraphQL API (endpoint https://api.linear.app/graphql, header `Authorization: $LINEAR_API_KEY`). Search by keywords from the description; look for open/in-progress issues that match.",
+    jira: `Search Jira for an existing issue related to the task description: POST ${jiraBase}/rest/api/3/search with basic auth (\`$JIRA_EMAIL:$JIRA_API_TOKEN\`) and a JQL text query built from keywords in the description; look for open/in-progress issues.`,
+    github: 'Search GitHub for an existing issue: `gh issue list --search "<keywords from description>" --state open`.',
+  };
+  const create = {
+    linear: "Create a Linear issue with the GraphQL API (`issueCreate`), title from the description.",
+    jira: `Create a Jira issue: POST ${jiraBase}/rest/api/3/issue with basic auth, summary from the description.`,
+    github: 'Create a GitHub issue: `gh issue create --title "..." --body "..."`.',
+  };
+  return { SEARCH_INSTR: search[tracker] || "", CREATE_INSTR: create[tracker] || "" };
+}
+
+// The single-agent variant: one query, the agent is the main thread with full
+// 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,
+}) {
+  const hasRealTaskId = !!taskId && !String(taskId).startsWith("new-") && !String(taskId).startsWith("task-");
+  const vars = {
+    AGENT_NAME: agent.name,
+    AGENT_ROLE: agent.role,
+    AGENT_DESCRIPTION: agent.description,
+    GROUND_RULES: agent.groundRules || "",
+    CODE_PRINCIPLE: agent.codePrinciple || "",
+    RESPONSIBILITIES: Array.isArray(agent.execution?.tasks) ? agent.execution.tasks.map(t => `- ${t}`).join("\n") : "",
+    TASK_ID: hasRealTaskId ? taskId : "TBD",
+    TASK_LINK: taskLink || "",
+    SESSION_URL: sessionUrl || "",
+    JIRA_BASE_URL: config.jira?.baseUrl || "",
+    TASK_DESCRIPTION: description ? wrapUntrusted("task_description", description) : "",
+    ...soloSearchAndCreate({ tracker, config }),
+  };
+  const flags = new Set();
+  if (vars.GROUND_RULES) flags.add("GROUND_RULES");
+  if (vars.CODE_PRINCIPLE) flags.add("CODE_PRINCIPLE");
+  if (vars.RESPONSIBILITIES) flags.add("RESPONSIBILITIES");
+  if (description) flags.add("TASK_DESCRIPTION");
+  if (tracker) {
+    flags.add(tracker.toUpperCase());
+    flags.add(hasRealTaskId ? "HAS_TASK_ID" : "FIND_OR_CREATE");
+    flags.add("CHILD_TASKS");
+    flags.add((childStrategy || "inline") === "branch" ? "CHILD_BRANCH" : "CHILD_INLINE");
+  }
+
+  vars.TRACKER_SECTION = trackerSection(tracker, ["INTAKE", "EXECUTION", "SUMMARY"], vars);
+
+  let body = renderTemplate(template("phases/SOLO.md"), { flags, vars }).trim();
+  if (tracker) {
+    body += `\n\n## TRACKER LOCK\n\nThis project uses **${tracker.toUpperCase()}**. Do NOT use any other tracker, even if its API returns errors — troubleshoot credentials and permissions instead.`;
+  }
+  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}`;
+
+  const context = generateContext(project);
+  const now = new Date();
+  const timeInfo = `Current date/time: ${now.toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" })} ${now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })}`;
+  return `${PROMPT_SECURITY_HEADER}\n\n${body}\n\n---\n\n## PROJECT CONTEXT\n\n${context}\n\n${timeInfo}`;
+}
+
+function createTaskSection({ tracker, config, description }) {
+  const lines = ["## CREATE TASK (MANDATORY — FIRST ACTION)", "",
+    "No task id was provided. Have Dennis create the task in the tracker as the very first action, then announce it on its own line as `TASK_ID: <identifier>`.", ""];
+  if (tracker === "linear") {
+    lines.push("Create a Linear issue with the GraphQL API.");
+    if (config.linear?.teamKey) lines.push(`**Team MUST be \`${config.linear.teamKey}\`.** Resolve its id via \`{ teams(filter: { key: { eq: "${config.linear.teamKey}" } }) { nodes { id } } }\` and pass it as \`teamId\` in \`issueCreate\`.`);
+    lines.push("**Assign to the connected user:** fetch `{ viewer { id } }` and pass that id as `assigneeId`.");
+  } else if (tracker === "jira") {
+    lines.push(`Create a Jira issue at ${config.jira?.baseUrl || ""}.`);
+    if (config.jira?.project) lines.push(`**Project MUST be \`${config.jira.project}\`.** Set \`fields.project.key = "${config.jira.project}"\`.`);
+    lines.push(`**Assign to the connected user:** GET \`${config.jira?.baseUrl || ""}/rest/api/3/myself\` for the \`accountId\`, then set \`fields.assignee = { "accountId": "<id>" }\`.`);
+  } else if (tracker === "github") {
+    lines.push('Create a GitHub issue: `gh issue create --title "..." --body "..." --assignee @me`.');
+  }
+  lines.push("", `Task description: ${wrapUntrusted("task_description", description)}`, "");
+  return lines.join("\n");
+}
+
+// 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,
+}) {
+  const vars = {
+    TASK_ID: taskId,
+    TASK_LINK: taskLink || "",
+    SESSION_URL: sessionUrl || "",
+    JIRA_BASE_URL: config.jira?.baseUrl || "",
+    TASK_DESCRIPTION: description ? wrapUntrusted("task_description", description) : "",
+    RETRY_FINDINGS: retryVerdict ? formatFindingsForRetry(retryVerdict) : "",
+  };
+  const flags = new Set();
+  if (description) flags.add("TASK_DESCRIPTION");
+  if (config.screenshots !== false) flags.add("SCREENSHOTS_ENABLED"); else flags.add("SCREENSHOTS_DISABLED");
+  if (tracker) flags.add(tracker.toUpperCase()); else flags.add("NO_TRACKER");
+  if (retryVerdict) flags.add("RETRY");
+
+  vars.TRACKER_SECTION = trackerSection(tracker, phase, vars);
+
+  let body = renderTemplate(template(`phases/${phase}.md`), { flags, vars }).trim();
+
+  if (phase === "INTAKE" && createTask && description) {
+    body += `\n\n${createTaskSection({ tracker, config, description })}`;
+  }
+  if (tracker) {
+    body += `\n\n## TRACKER LOCK\n\nThis project uses **${tracker.toUpperCase()}**. Do NOT use any other tracker.`;
+  }
+  if (config.instructions) {
+    body += `\n\n## ADDITIONAL INSTRUCTIONS\n\n${config.instructions}`;
+  }
+  if (sessionMemory) {
+    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}`;
+
+  if (config.projectAgents?.length) {
+    project.configAgents = config.projectAgents.map(a => ({ ...a, type: a.type || "declared", source: ".agentdesk.json" }));
+  }
+  const context = generateContext(project);
+  const now = new Date();
+  const timeInfo = `Current date/time: ${now.toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" })} ${now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })}`;
+
+  return `${PROMPT_SECURITY_HEADER}\n\n${body}\n\n---\n\n## PROJECT CONTEXT\n\n${context}\n\n${timeInfo}`;
+}

package/cli/engine/query.mjs

@@ -0,0 +1,63 @@
+// One phase = one Agent SDK query(). This module builds the Options object
+// and owns the only import of the SDK's query(), so the session loop can be
+// exercised in tests with a scripted message stream instead.
+
+import { query as sdkQuery } from "@anthropic-ai/claude-agent-sdk";
+import { createSandboxedSpawn } from "./spawn.mjs";
+import { PHASE_OUTPUT_SCHEMAS } from "./schemas.mjs";
+import { hooksForPhase } from "./hooks.mjs";
+
+// Agentic turns per phase before the SDK stops the query (error_max_turns →
+// the phase counts as failed). Overridable per project via config.phaseMaxTurns.
+export const DEFAULT_MAX_TURNS = Object.freeze({
+  INTAKE: 40,
+  PLAN: 60,
+  EXECUTION: 250,
+  REVIEW: 80,
+  SUMMARY: 40,
+  SOLO: 250,
+});
+
+export function maxTurnsFor(phase, config = {}) {
+  const v = Number(config.phaseMaxTurns?.[phase]);
+  return Number.isFinite(v) && v > 0 ? v : DEFAULT_MAX_TURNS[phase];
+}
+
+// Pure: returns the SDK Options for one phase. Everything that must be true
+// of every unattended session is decided here, once:
+//   - permissionMode "dontAsk": pre-approved tools run, anything else is denied,
+//     nothing ever waits on a prompt
+//   - settingSources []: the user's ~/.claude settings never leak into a session
+//   - persistSession false: no transcripts written to the user's profile
+//   - forwardSubagentText: subagent messages arrive with parent_tool_use_id
+//   - outputFormat: the phase's handoff schema (schemas.mjs)
+export function buildQueryOptions({
+  phase, cwd, env, model, agents, allowedTools, lead, state, config = {},
+  abortController, sandbox, onChild, onIsolation, hookCallbacks = {},
+  claudePath = process.env.AGENTDESK_CLAUDE_PATH,
+}) {
+  const options = {
+    cwd,
+    env,
+    agent: lead,
+    agents,
+    allowedTools,
+    permissionMode: "dontAsk",
+    settingSources: [],
+    persistSession: false,
+    maxTurns: maxTurnsFor(phase, config),
+    abortController,
+    forwardSubagentText: true,
+    outputFormat: { type: "json_schema", schema: PHASE_OUTPUT_SCHEMAS[phase] },
+    hooks: hooksForPhase({ phase, state, ...hookCallbacks }),
+    spawnClaudeCodeProcess: createSandboxedSpawn({ sandbox, onChild, onIsolation }),
+  };
+  if (model) options.model = model;
+  if (Number(config.maxBudgetUsd) > 0) options.maxBudgetUsd = Number(config.maxBudgetUsd);
+  if (claudePath) options.pathToClaudeCodeExecutable = claudePath;
+  return options;
+}
+
+export async function* defaultRunQuery({ prompt, options }) {
+  yield* sdkQuery({ prompt, options });
+}

package/cli/engine/schemas.mjs

@@ -0,0 +1,180 @@
+// Per-phase structured output: what each phase must hand to the next.
+//
+// The old design asked the model to "write .agentdesk/session-memory.md
+// before finishing" and then read the file back. Phases forgot, wrote
+// partial sections, or wrote a different shape. Now every phase ends its
+// query with `outputFormat: { type: "json_schema" }`, the SDK validates the
+// object, and the engine renders the markdown section itself. The file keeps
+// the same headings as before so anything that reads it still works.
+
+import { VERDICT_SCHEMA } from "./verdict.mjs";
+
+const strList = { type: "array", items: { type: "string" } };
+
+export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
+  INTAKE: {
+    type: "object",
+    additionalProperties: false,
+    required: ["title", "taskSummary", "requirements", "assessment", "subtasks", "nextPhaseFocus"],
+    properties: {
+      title: { type: "string", description: "4-8 word session title" },
+      taskSummary: { type: "string" },
+      requirements: strList,
+      assessment: { ...strList, description: "existing branches/PRs, code patterns, resume context" },
+      subtasks: { ...strList, description: "subtasks created, if the task was decomposed; else empty" },
+      nextPhaseFocus: strList,
+    },
+  },
+  PLAN: {
+    type: "object",
+    additionalProperties: false,
+    required: ["approach", "filesToModify", "decisions", "risks", "assignments", "steps"],
+    properties: {
+      approach: strList,
+      filesToModify: strList,
+      decisions: strList,
+      risks: strList,
+      assignments: { ...strList, description: "who does what during execution" },
+      steps: { ...strList, description: "ordered implementation steps" },
+    },
+  },
+  EXECUTION: {
+    type: "object",
+    additionalProperties: false,
+    required: ["implemented", "filesChanged", "prUrl", "qaResults", "issuesFixed", "reviewerAttention"],
+    properties: {
+      implemented: strList,
+      filesChanged: strList,
+      prUrl: { type: "string", description: "empty string if no PR was created" },
+      qaResults: strList,
+      issuesFixed: strList,
+      reviewerAttention: strList,
+    },
+  },
+  REVIEW: VERDICT_SCHEMA,
+  SOLO: {
+    type: "object",
+    additionalProperties: false,
+    required: ["summary", "filesChanged", "prUrl", "deferred", "manualSteps"],
+    properties: {
+      summary: { type: "string" },
+      filesChanged: strList,
+      prUrl: { type: "string", description: "empty string if no PR was created" },
+      deferred: strList,
+      manualSteps: strList,
+    },
+  },
+  SUMMARY: {
+    type: "object",
+    additionalProperties: false,
+    required: ["status", "prUrl", "deferred", "manualSteps", "summaryComment"],
+    properties: {
+      status: { type: "string" },
+      prUrl: { type: "string" },
+      deferred: strList,
+      manualSteps: strList,
+      summaryComment: { type: "string", description: "the final tracker comment as posted" },
+    },
+  },
+});
+
+const bullets = (items, empty = "- none") =>
+  Array.isArray(items) && items.length ? items.map(i => `- ${String(i)}`).join("\n") : empty;
+
+// Markdown appended to .agentdesk/session-memory.md after each phase. Same
+// headings the previous prompts asked the model to write.
+export function renderMemorySection(phase, out) {
+  if (!out || typeof out !== "object") {
+    return `## ${phase}\n- (phase produced no structured summary)\n`;
+  }
+  switch (phase) {
+    case "INTAKE":
+      return [
+        "## Task",
+        `- Title: ${out.title || ""}`,
+        `- Summary: ${out.taskSummary || ""}`,
+        "",
+        "## Requirements",
+        bullets(out.requirements),
+        "",
+        "## Assessment",
+        bullets(out.assessment),
+        "",
+        "## Subtasks (if decomposed)",
+        bullets(out.subtasks),
+        "",
+        "## Next Phase: PLAN",
+        bullets(out.nextPhaseFocus),
+        "",
+      ].join("\n");
+    case "PLAN":
+      return [
+        "## Plan",
+        bullets(out.approach),
+        bullets(out.filesToModify?.map(f => `File: ${f}`), ""),
+        bullets(out.decisions?.map(d => `Decision: ${d}`), ""),
+        bullets(out.risks?.map(r => `Risk: ${r}`), ""),
+        "",
+        "## Agent Assignments",
+        bullets(out.assignments),
+        "",
+        "## Next Phase: EXECUTION",
+        bullets(out.steps),
+        "",
+      ].filter(l => l !== "").join("\n") + "\n";
+    case "EXECUTION":
+      return [
+        "## Execution Summary",
+        bullets(out.implemented),
+        bullets(out.filesChanged?.map(f => `Changed: ${f}`), ""),
+        `- PR: ${out.prUrl || "(none)"}`,
+        "",
+        "## QA Results",
+        bullets(out.qaResults),
+        bullets(out.issuesFixed?.map(i => `Fixed: ${i}`), ""),
+        "",
+        "## Next Phase: REVIEW",
+        bullets(out.reviewerAttention),
+        "",
+      ].filter(l => l !== "").join("\n") + "\n";
+    case "REVIEW":
+      return [
+        "## Review",
+        `- Verdict: ${out.verdict || "MISSING"}`,
+        `- Findings: ${Array.isArray(out.findings) && out.findings.length ? "" : "none"}`,
+        ...(Array.isArray(out.findings) ? out.findings.map(f => `  - ${f.title}${f.file ? ` (${f.file}${f.line ? `:${f.line}` : ""})` : ""} — ${f.detail} [${f.reviewer}]`) : []),
+        `- Out of scope: ${Array.isArray(out.deferred) && out.deferred.length ? out.deferred.join("; ") : "none"}`,
+        `- Unverified claims: ${Array.isArray(out.unverifiedClaims) && out.unverifiedClaims.length ? out.unverifiedClaims.join("; ") : "none"}`,
+        "",
+      ].join("\n");
+    case "SOLO":
+      return [
+        "## Solo Summary",
+        `- ${out.summary || ""}`,
+        bullets(out.filesChanged?.map(f => `Changed: ${f}`), ""),
+        `- PR: ${out.prUrl || "(none)"}`,
+        "",
+        "## Deferred",
+        bullets(out.deferred),
+        "",
+        "## Manual Steps",
+        bullets(out.manualSteps),
+        "",
+      ].filter(l => l !== "").join("\n") + "\n";
+    case "SUMMARY":
+      return [
+        "## Final Status",
+        `- ${out.status || ""}`,
+        `- PR: ${out.prUrl || "(none)"}`,
+        "",
+        "## Deferred",
+        bullets(out.deferred),
+        "",
+        "## Manual Steps",
+        bullets(out.manualSteps),
+        "",
+      ].join("\n");
+    default:
+      return `## ${phase}\n${JSON.stringify(out, null, 2)}\n`;
+  }
+}