patchwarden 0.4.0

package/src/tools/retryTask.ts

@@ -0,0 +1,53 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getTasksDir, getConfig } from "../config.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { createTask } from "./createTask.js";
+
+export function retryTask(taskId: string) {
+  const config = getConfig();
+  const tasksDir = getTasksDir(config);
+  const taskDir = join(tasksDir, taskId);
+  const statusFile = join(taskDir, "status.json");
+
+  guardReadPath(statusFile, config.workspaceRoot, config.tasksDir);
+
+  if (!existsSync(statusFile)) {
+    throw new Error(`Task not found: "${taskId}"`);
+  }
+
+  const data = JSON.parse(readFileSync(statusFile, "utf-8"));
+
+  if (!data.plan_id || !data.agent) {
+    throw new Error(`Task "${taskId}" is missing plan_id or agent. Cannot retry.`);
+  }
+
+  // Create a new task with the same parameters
+  const newTask = createTask({
+    plan_id: data.plan_id,
+    agent: data.agent,
+    repo_path: data.repo_path,
+    test_command: data.test_command,
+    verify_commands: data.verify_commands,
+    timeout_seconds: data.timeout_seconds,
+  });
+
+  // Record retry relationship in the new task
+  const newStatusFile = join(newTask.path, "status.json");
+  const newData = JSON.parse(readFileSync(newStatusFile, "utf-8"));
+  newData.retry_of = taskId;
+  newData.retry_count = (data.retry_count || 0) + 1;
+  newData.plan_source = data.plan_source || "saved";
+  newData.template = data.template || null;
+  newData.change_policy = data.change_policy || "repo_scoped_changes";
+  writeFileSync(newStatusFile, JSON.stringify(newData, null, 2), "utf-8");
+
+  return {
+    original_task_id: taskId,
+    new_task_id: newTask.task_id,
+    plan_id: newTask.plan_id,
+    agent: newTask.agent,
+    status: newTask.status,
+    message: `New task created from retry of ${taskId}. Original task is unchanged.`,
+  };
+}

package/src/tools/savePlan.ts

@@ -0,0 +1,46 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { getPlansDir, getConfig } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { guardPlanContent } from "../security/planGuard.js";
+
+export interface SavePlanInput {
+  title: string;
+  content: string;
+}
+
+export interface SavePlanOutput {
+  plan_id: string;
+  path: string;
+  title: string;
+}
+
+export function savePlan(input: SavePlanInput): SavePlanOutput {
+  const config = getConfig();
+  const plansDir = getPlansDir(config);
+
+  guardPlanContent(input.title, input.content);
+
+  const planId = `plan_${Date.now()}_${sanitizeTitle(input.title)}`;
+  const planDir = resolve(plansDir, planId);
+
+  // Guards: plan dir & file must stay inside workspace
+  guardPath(planDir, config.workspaceRoot, config.plansDir);
+  mkdirSync(planDir, { recursive: true });
+
+  const planFile = join(planDir, "plan.md");
+  const header = `# ${input.title}\n\n> Plan ID: ${planId}\n> Created: ${new Date().toISOString()}\n\n`;
+  writeFileSync(planFile, header + input.content, "utf-8");
+
+  return {
+    plan_id: planId,
+    path: planFile,
+    title: input.title,
+  };
+}
+
+function sanitizeTitle(title: string): string {
+  return title
+    .replace(/[^a-zA-Z0-9\u4e00-\u9fff_-]/g, "_")
+    .slice(0, 64);
+}

package/src/tools/taskOutputs.ts

@@ -0,0 +1,155 @@
+import { getTaskFile, GetTaskFileOutput } from "./getTaskFile.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, getTasksDir } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+
+export function getResult(taskId: string): GetTaskFileOutput {
+  return getTaskFile(taskId, "result.md");
+}
+
+export function getResultJson(taskId: string): GetTaskFileOutput {
+  return getTaskFile(taskId, "result.json");
+}
+
+export function getDiff(taskId: string): GetTaskFileOutput {
+  const config = getConfig();
+  const taskDir = resolve(getTasksDir(config), taskId);
+  const preferred = join(taskDir, "diff.patch");
+  const fallback = join(taskDir, "git.diff");
+  if (!existsSync(preferred) && !existsSync(fallback)) {
+    return getTaskFile(taskId, "diff.patch");
+  }
+  const filePath = existsSync(preferred) ? preferred : fallback;
+  guardPath(filePath, config.workspaceRoot, config.tasksDir);
+  const size = statSync(filePath).size;
+  const raw = readFileSync(filePath, "utf-8");
+  const patchHead = raw.slice(0, config.maxReadFileBytes);
+  const rawReturnedBytes = Buffer.byteLength(patchHead, "utf-8");
+  const redaction = redactSensitiveContent(patchHead);
+  const content = redaction.content;
+  const diff = {
+    task_id: taskId,
+    filename: existsSync(preferred) ? "diff.patch" : "git.diff",
+    content,
+    path: filePath,
+    available: true,
+    truncated: size > rawReturnedBytes,
+    total_bytes: size,
+    returned_bytes: Buffer.byteLength(content, "utf-8"),
+    patch_head: content,
+    diff_patch_path: filePath,
+    redacted: redaction.redacted,
+    redaction_categories: redaction.redaction_categories,
+  } as GetTaskFileOutput;
+  try {
+    const evidence = JSON.parse(getTaskFile(taskId, "changed-files.json").content);
+    return {
+      ...diff,
+      changed_files: evidence.changed_files || [],
+      diff_available: Boolean(evidence.diff_available),
+      workspace_dirty_before: Boolean(evidence.workspace_dirty_before),
+      workspace_dirty_after: Boolean(evidence.workspace_dirty_after),
+      diff_truncated: Boolean(evidence.diff_truncated || (diff as any).truncated),
+      diff_size_bytes: Number(evidence.diff_size_bytes || size),
+      additions: Number(evidence.additions || 0),
+      deletions: Number(evidence.deletions || 0),
+      file_stats: evidence.file_stats || [],
+      patch_mode: evidence.patch_mode || (evidence.diff_available ? "hash_only" : "no_changes"),
+      unavailable_reason: evidence.unavailable_reason || null,
+      message: evidence.diff_available ? "Task diff available" : "No task file changes detected",
+    } as GetTaskFileOutput;
+  } catch {
+    return diff;
+  }
+}
+
+export function getTestLog(taskId: string, options?: { tailLines?: number; maxBytes?: number }): GetTaskFileOutput {
+  const maxBytes = options?.maxBytes ?? 0;
+  const tailLines = options?.tailLines ?? 0;
+  if (tailLines > 0 || maxBytes > 0) {
+    return getTaskFileTail(taskId, "test.log", { tailLines, maxBytes });
+  }
+  return getTaskFile(taskId, "test.log");
+}
+
+/**
+ * Read the tail of a task log file with automatic redaction.
+ * Supports test.log, stdout.log, stderr.log, verify.log.
+ */
+export function getTaskLogTail(
+  taskId: string,
+  file: "stdout" | "stderr" | "test" | "verify",
+  options?: { lines?: number; redact?: boolean }
+) {
+  const config = getConfig();
+  const taskDir = resolve(getTasksDir(config), taskId);
+  const filename = file === "stdout" ? "stdout.log"
+    : file === "stderr" ? "stderr.log"
+    : file === "test" ? "test.log"
+    : "verify.log";
+  const filePath = join(taskDir, filename);
+  guardPath(filePath, config.workspaceRoot, config.tasksDir);
+
+  const maxLines = Math.min(options?.lines ?? 80, 200);
+  const applyRedact = options?.redact !== false; // default true
+
+  if (!existsSync(filePath)) {
+    return { ...getTaskFile(taskId, filename), file, lines: 0, total_bytes: 0 };
+  }
+
+  const stat = statSync(filePath);
+  const totalBytes = stat.size;
+  const raw = readFileSync(filePath, "utf-8");
+  const tail = raw.split("\n").slice(-maxLines).join("\n");
+  const content = applyRedact ? redactSensitiveContent(tail) : { content: tail, redacted: false, redaction_categories: [] as string[] };
+
+  return {
+    task_id: taskId,
+    file,
+    filename,
+    content: content.content,
+    available: true,
+    lines: tail.split("\n").length,
+    total_bytes: totalBytes,
+    truncated: totalBytes > Buffer.byteLength(tail, "utf-8"),
+    redacted: content.redacted,
+    redaction_categories: content.redaction_categories,
+  };
+}
+
+function getTaskFileTail(
+  taskId: string,
+  filename: string,
+  options: { tailLines: number; maxBytes: number }
+): GetTaskFileOutput {
+  const config = getConfig();
+  const taskDir = resolve(getTasksDir(config), taskId);
+  const filePath = join(taskDir, filename);
+  guardPath(filePath, config.workspaceRoot, config.tasksDir);
+
+  if (!existsSync(filePath)) {
+    return getTaskFile(taskId, filename);
+  }
+
+  const stat = statSync(filePath);
+  const raw = readFileSync(filePath, "utf-8");
+  let content = raw;
+  if (options.tailLines > 0) {
+    content = raw.split("\n").slice(-options.tailLines).join("\n");
+  }
+  if (options.maxBytes > 0 && Buffer.byteLength(content, "utf-8") > options.maxBytes) {
+    content = content.slice(0, options.maxBytes);
+  }
+  const redaction = redactSensitiveContent(content);
+  return {
+    task_id: taskId,
+    filename,
+    content: redaction.content,
+    path: filePath,
+    available: true,
+    redacted: redaction.redacted,
+    redaction_categories: redaction.redaction_categories,
+  };
+}

package/src/tools/taskTemplates.ts

@@ -0,0 +1,162 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, getTasksDir } from "../config.js";
+import { PatchWardenError } from "../errors.js";
+import { guardReadPath } from "../security/pathGuard.js";
+
+export const TASK_TEMPLATE_NAMES = [
+  "inspect_only",
+  "feature_small",
+  "fix_tests",
+  "release_check",
+  "rollback_scope_violation",
+] as const;
+
+export type TaskTemplateName = typeof TASK_TEMPLATE_NAMES[number];
+export type ChangePolicy = "repo_scoped_changes" | "no_changes";
+
+export interface TaskTemplateInput {
+  template: TaskTemplateName;
+  goal: string;
+  source_task_id?: string;
+  verify_commands: string[];
+}
+
+export interface ExpandedTaskTemplate {
+  title: string;
+  content: string;
+  change_policy: ChangePolicy;
+}
+
+export function expandTaskTemplate(input: TaskTemplateInput): ExpandedTaskTemplate {
+  const goal = input.goal.trim();
+  if (!goal) {
+    throw new PatchWardenError(
+      "template_goal_required",
+      "Template tasks require a non-empty goal.",
+      "Pass a concise goal describing the desired inspection or repository-local change."
+    );
+  }
+
+  const common = [
+    `## Goal\n${goal}`,
+    "## Safety boundaries",
+    "- Work only inside the resolved repository path.",
+    "- Do not commit, push, publish, expose credentials, or modify unrelated files.",
+    "- Report exact files inspected or changed and any remaining uncertainty.",
+  ];
+
+  switch (input.template) {
+    case "inspect_only":
+      return {
+        title: `Inspect only: ${shortTitle(goal)}`,
+        change_policy: "no_changes",
+        content: [
+          ...common,
+          "## Execution contract",
+          "- Perform read-only inspection only.",
+          "- Do not create, edit, delete, rename, format, or generate repository files.",
+          "- Return findings, evidence, and the smallest safe next action.",
+        ].join("\n\n"),
+      };
+
+    case "feature_small":
+      return {
+        title: `Small feature: ${shortTitle(goal)}`,
+        change_policy: "repo_scoped_changes",
+        content: [
+          ...common,
+          "## Execution contract",
+          "- Read the repository instructions, README, and package metadata first.",
+          "- Make the smallest coherent implementation; avoid framework, dependency, and directory changes unless required.",
+          "- Run only the independently configured verification commands.",
+        ].join("\n\n"),
+      };
+
+    case "fix_tests":
+      if (input.verify_commands.length === 0) {
+        throw new PatchWardenError(
+          "template_verification_required",
+          "The fix_tests template requires at least one allow-listed verify_commands entry.",
+          "Pass the failing test or check command in verify_commands."
+        );
+      }
+      return {
+        title: `Fix tests: ${shortTitle(goal)}`,
+        change_policy: "repo_scoped_changes",
+        content: [
+          ...common,
+          "## Execution contract",
+          "- Reproduce the relevant failure before editing when possible.",
+          "- Fix the root cause without deleting tests, weakening checks, or changing unrelated behavior.",
+          `- PatchWarden will independently run: ${input.verify_commands.join(", ")}.`,
+        ].join("\n\n"),
+      };
+
+    case "release_check":
+      return {
+        title: `Release check: ${shortTitle(goal)}`,
+        change_policy: "repo_scoped_changes",
+        content: [
+          ...common,
+          "## Execution contract",
+          "- Perform local release-readiness checks and inspect package contents and generated artifacts.",
+          "- Do not publish, push, create tags/releases, or claim remote completion without live remote evidence.",
+          "- Clearly separate local readiness from remote publication state.",
+        ].join("\n\n"),
+      };
+
+    case "rollback_scope_violation": {
+      const evidence = readRollbackEvidence(input.source_task_id);
+      return {
+        title: `Scope violation review: ${shortTitle(goal)}`,
+        change_policy: "no_changes",
+        content: [
+          ...common,
+          "## Execution contract",
+          `- Review scope-violation evidence from source task ${input.source_task_id}.`,
+          "- Do not perform an automatic rollback, deletion, reset, checkout, or cross-repository edit.",
+          "- Produce a file-by-file recovery proposal with backup and verification steps for user approval.",
+          "## Source task recovery evidence",
+          evidence,
+        ].join("\n\n"),
+      };
+    }
+  }
+}
+
+function readRollbackEvidence(sourceTaskId?: string): string {
+  if (!sourceTaskId?.trim()) {
+    throw new PatchWardenError(
+      "source_task_required",
+      "rollback_scope_violation requires source_task_id.",
+      "Pass the task ID that ended with failed_scope_violation."
+    );
+  }
+  const config = getConfig();
+  const taskDir = resolve(getTasksDir(config), sourceTaskId);
+  const statusFile = join(taskDir, "status.json");
+  const rollbackFile = join(taskDir, "rollback_scope_violation_plan.md");
+  guardReadPath(statusFile, config.workspaceRoot, config.tasksDir);
+  guardReadPath(rollbackFile, config.workspaceRoot, config.tasksDir);
+  if (!existsSync(statusFile) || !existsSync(rollbackFile)) {
+    throw new PatchWardenError(
+      "scope_violation_evidence_missing",
+      `Source task "${sourceTaskId}" does not contain scope-violation recovery evidence.`,
+      "Use a task that ended with failed_scope_violation and has rollback_scope_violation_plan.md."
+    );
+  }
+  const status = JSON.parse(readFileSync(statusFile, "utf-8"));
+  if (status.status !== "failed_scope_violation") {
+    throw new PatchWardenError(
+      "source_task_not_scope_violation",
+      `Source task "${sourceTaskId}" has status "${status.status}", not failed_scope_violation.`,
+      "Use the scope-violating task as source_task_id."
+    );
+  }
+  return readFileSync(rollbackFile, "utf-8").slice(0, 20_000);
+}
+
+function shortTitle(goal: string): string {
+  return goal.replace(/\s+/g, " ").slice(0, 80);
+}

package/src/tools/toolCatalog.ts

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+
+export type ToolProfile = "full" | "chatgpt_core";
+
+export interface CatalogTool {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+}
+
+export interface ToolCatalogSnapshot {
+  server_version: string;
+  schema_epoch: string;
+  tool_profile: ToolProfile;
+  tool_count: number;
+  tool_names: string[];
+  tool_manifest_sha256: string;
+}
+
+export const CHATGPT_CORE_TOOL_NAMES = [
+  "health_check",
+  "list_agents",
+  "list_workspace",
+  "read_workspace_file",
+  "save_plan",
+  "create_task",
+  "wait_for_task",
+  "get_task_summary",
+  "get_diff",
+  "get_result",
+  "get_result_json",
+  "get_test_log",
+  "get_task_status",
+  "list_tasks",
+  "cancel_task",
+  "audit_task",
+] as const;
+
+let lastSnapshot: ToolCatalogSnapshot | null = null;
+
+export function resolveToolProfile(configProfile?: string): ToolProfile {
+  const raw = (process.env.PATCHWARDEN_TOOL_PROFILE || configProfile || "full").trim();
+  if (raw !== "full" && raw !== "chatgpt_core") {
+    throw new Error(`Invalid tool profile "${raw}". Expected "full" or "chatgpt_core".`);
+  }
+  return raw;
+}
+
+export function selectToolsForProfile<T extends CatalogTool>(tools: T[], profile: ToolProfile): T[] {
+  if (profile === "full") return tools;
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+  return CHATGPT_CORE_TOOL_NAMES.map((name) => {
+    const tool = byName.get(name);
+    if (!tool) throw new Error(`chatgpt_core tool profile requires missing tool "${name}".`);
+    return tool;
+  });
+}
+
+export function buildToolCatalogSnapshot(tools: CatalogTool[], profile: ToolProfile): ToolCatalogSnapshot {
+  const manifestInput = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  }));
+  const tool_manifest_sha256 = createHash("sha256")
+    .update(stableJson(manifestInput))
+    .digest("hex");
+  lastSnapshot = {
+    server_version: PATCHWARDEN_VERSION,
+    schema_epoch: TOOL_SCHEMA_EPOCH,
+    tool_profile: profile,
+    tool_count: tools.length,
+    tool_names: tools.map((tool) => tool.name),
+    tool_manifest_sha256,
+  };
+  return lastSnapshot;
+}
+
+export function getLastToolCatalogSnapshot(): ToolCatalogSnapshot | null {
+  return lastSnapshot ? { ...lastSnapshot, tool_names: [...lastSnapshot.tool_names] } : null;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/tools/waitForTask.ts

@@ -0,0 +1,90 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { getTaskStatus } from "./getTaskStatus.js";
+import { getTaskSummary, type TaskSummaryOutput } from "./getTaskSummary.js";
+
+const TERMINAL_STATUSES = new Set([
+  "done",
+  "failed",
+  "failed_verification",
+  "failed_scope_violation",
+  "failed_policy_violation",
+  "canceled",
+]);
+
+export interface WaitForTaskProgressSummary {
+  phase: string;
+  heartbeat_at: string;
+  elapsed_seconds: number;
+  current_command: string | null;
+  hint: string;
+}
+
+export interface WaitForTaskOutput {
+  task_id: string;
+  status: string;
+  phase: string;
+  terminal: boolean;
+  timed_out: boolean;
+  continuation_required: boolean;
+  waited_ms: number;
+  next_action: string;
+  next_tool_call: {
+    name: "wait_for_task" | "audit_task" | "health_check";
+    arguments: Record<string, unknown>;
+  };
+  summary?: TaskSummaryOutput;
+  progress_summary?: WaitForTaskProgressSummary;
+}
+
+export async function waitForTask(taskId: string, waitSeconds = 25): Promise<WaitForTaskOutput> {
+  if (!Number.isInteger(waitSeconds) || waitSeconds < 1 || waitSeconds > 30) {
+    throw new Error("wait_seconds must be an integer from 1 to 30.");
+  }
+  const started = Date.now();
+  const deadline = started + waitSeconds * 1000;
+  let status = getTaskStatus(taskId);
+
+  while (!TERMINAL_STATUSES.has(status.status) && Date.now() < deadline) {
+    await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+    status = getTaskStatus(taskId);
+  }
+
+  const terminal = TERMINAL_STATUSES.has(status.status);
+  const executionBlocked = !terminal && status.execution_blocked;
+  const elapsed = Math.round((Date.now() - started) / 1000);
+
+  const progressSummary: WaitForTaskProgressSummary = {
+    phase: status.phase,
+    heartbeat_at: status.last_heartbeat_at || status.updated_at || "",
+    elapsed_seconds: elapsed,
+    current_command: status.current_command || null,
+    hint: executionBlocked
+      ? `Watcher is ${status.watcher_status}. Call health_check and restart the owned watcher; do not keep polling this task yet.`
+      : status.phase === "queued"
+      ? "Watcher is healthy and has not picked up this task yet. Continue waiting."
+      : status.phase === "executing_agent"
+        ? `Agent "${status.agent}" is running. Continue waiting, or call get_task_status for phase and current_command.`
+        : `Phase "${status.phase}". Task is still in progress.`,
+  };
+
+  return {
+    task_id: taskId,
+    status: status.status,
+    phase: status.phase,
+    terminal,
+    timed_out: !terminal,
+    continuation_required: !terminal && !executionBlocked,
+    waited_ms: Date.now() - started,
+    next_action: terminal
+      ? "Review the returned summary, then call audit_task for independent acceptance evidence."
+      : executionBlocked
+        ? "Call health_check and restore the owned watcher. The saved task will remain queued for recovery."
+      : `Call wait_for_task again immediately for task_id ${taskId}; do not end the assistant turn while continuation_required is true.`,
+    next_tool_call: terminal
+      ? { name: "audit_task", arguments: { task_id: taskId } }
+      : executionBlocked
+        ? { name: "health_check", arguments: {} }
+      : { name: "wait_for_task", arguments: { task_id: taskId, timeout_seconds: waitSeconds } },
+    ...(terminal ? { summary: getTaskSummary(taskId) } : { progress_summary: progressSummary }),
+  };
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+export const PATCHWARDEN_VERSION = "0.4.0";
+export const TOOL_SCHEMA_EPOCH = "2026-06-21-v3";