jules-orchestrator-kit 0.52.8 → 0.53.0

package/src/ops/task-actions.mjs

@@ -1,214 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { redactSecrets } from "../security.mjs";
-
-function deepFreeze(value) {
-  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
-  for (const child of Object.values(value)) deepFreeze(child);
-  return Object.freeze(value);
-}
-
-function finalizePlan(plan) {
-  const { planHash: _oldHash, ...unsigned } = plan;
-  const planHash = "sha256:" + createHash("sha256").update(JSON.stringify(unsigned)).digest("hex");
-  return deepFreeze({ ...unsigned, planHash });
-}
-
-/**
- * @typedef {import("../ux/capabilities.mjs").ActionPlan} ActionPlan
- * @typedef {import("../ux/queue-model.mjs").QueueSnapshot} QueueSnapshot
- */
-
-/**
- * Plan task lifecycle action into an immutable ActionPlan.
- * @param {QueueSnapshot} snapshot
- * @param {Object} intent
- * @param {string} intent.kind
- * @param {string} intent.taskId
- * @param {Record<string, any>} [intent.answers]
- * @returns {Promise<ActionPlan>}
- */
-export async function planTaskAction(snapshot, intent = {}) {
-  const taskId = typeof intent.taskId === "string" ? intent.taskId : "";
-  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(taskId)) {
-    throw new Error("Task id must be a safe queue identifier.");
-  }
-  const task = (snapshot?.tasks || []).find((t) => t.id === taskId);
-  if (!task) {
-    throw new Error(`Task ${taskId} not found in queue snapshot.`);
-  }
-
-  const root = snapshot.repository;
-  const planId = `PLAN-TASK-${Date.now()}-${randomUUID().slice(0, 8)}`;
-  const sidecarRelPath = `.agent/jules-queue/${taskId}.state.json`;
-
-  if (intent.kind === "retry") {
-    const allowedStates = ["failed", "deferred", "quarantined", "cancelled"];
-    if (!allowedStates.includes(task.state)) {
-      throw new Error(`Task ${taskId} in state '${task.state}' cannot be retried.`);
-    }
-
-    const nextAttempt = (Number.isFinite(task.attempt) ? task.attempt : 0) + 1;
-    const sidecarContent = JSON.stringify(
-      {
-        schema: "agentctl/task-state-v1",
-        taskId,
-        revision: (Number.isFinite(task.stateRevision) ? task.stateRevision : 0) + 1,
-        state: "pending",
-        attempt: nextAttempt,
-        maxAttempts: task.maxAttempts,
-        createdAt: task.createdAt,
-        updatedAt: new Date().toISOString(),
-      },
-      null,
-      2
-    );
-
-    return finalizePlan({
-      schema: "agentctl/action-plan-v1",
-      id: planId,
-      kind: "task.retry",
-      title: `Retry task ${taskId}`,
-      summary: `Reset state to pending and increment attempt count to ${nextAttempt}`,
-      risk: "moderate",
-      repository: root,
-      createdAt: new Date().toISOString(),
-      preconditions: [
-        {
-          kind: "file-hash",
-          target: sidecarRelPath,
-          expected: task.stateHash, // Checked prior state hash if sidecar exists
-        },
-      ],
-      fileMutations: [
-        {
-          operation: "replace",
-          path: sidecarRelPath,
-          newContent: sidecarContent,
-        },
-      ],
-      commandEffects: [],
-      stateTransitions: [{ taskId, from: task.state, to: "pending" }],
-      preview: {
-        unifiedDiff: `--- a/${sidecarRelPath}\n+++ b/${sidecarRelPath}\n@@ -state @@\n- state: ${task.state}\n+ state: pending\n- attempt: ${task.attempt}\n+ attempt: ${nextAttempt}\n`,
-        warnings: [],
-        estimatedImpact: [`Resets ${taskId} to pending state (Attempt ${nextAttempt})`],
-      },
-      confirmation: {
-        mode: "keypress",
-        prompt: `Confirm retry of ${taskId} (Attempt ${nextAttempt})?`,
-      },
-      planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-    });
-  }
-
-  if (intent.kind === "quarantine-override") {
-    if (task.state !== "quarantined") {
-      throw new Error(`Task ${taskId} is not in quarantined state.`);
-    }
-
-    const reason = redactSecrets(String(intent.answers?.reason || "").trim());
-    if (!reason) {
-      throw new Error("Quarantine override requires a non-empty reason.");
-    }
-
-    const sidecarContent = JSON.stringify(
-      {
-        schema: "agentctl/task-state-v1",
-        taskId,
-        revision: (Number.isFinite(task.stateRevision) ? task.stateRevision : 0) + 1,
-        state: "pending",
-        attempt: task.attempt,
-        maxAttempts: task.maxAttempts,
-        quarantineOverrideReason: reason,
-        updatedAt: new Date().toISOString(),
-      },
-      null,
-      2
-    );
-
-    return finalizePlan({
-      schema: "agentctl/action-plan-v1",
-      id: planId,
-      kind: "task.quarantine-override",
-      title: `Override quarantine for ${taskId}`,
-      summary: `Bypass quarantine with reason: "${reason}"`,
-      risk: "high",
-      repository: root,
-      createdAt: new Date().toISOString(),
-      preconditions: [
-        {
-          kind: "file-hash",
-          target: sidecarRelPath,
-          expected: task.stateHash,
-        },
-      ],
-      fileMutations: [
-        {
-          operation: "replace",
-          path: sidecarRelPath,
-          newContent: sidecarContent,
-        },
-      ],
-      commandEffects: [],
-      stateTransitions: [{ taskId, from: "quarantined", to: "pending" }],
-      preview: {
-        unifiedDiff: `--- a/${sidecarRelPath}\n+++ b/${sidecarRelPath}\n@@ -state @@\n- state: quarantined\n+ state: pending\n+ overrideReason: "${reason}"\n`,
-        warnings: ["Bypassing quarantine filter requires verified operator review."],
-        estimatedImpact: [`Re-enables ${taskId} for dispatch`],
-      },
-      confirmation: {
-        mode: "typed-task-id",
-        prompt: `Type '${taskId}' to confirm quarantine override:`,
-        expected: taskId,
-        requireReason: true,
-      },
-      planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-    });
-  }
-
-  if (intent.kind === "delete-task") {
-    if (task.state === "running" || task.state === "verifying") {
-      throw new Error(`Task ${taskId} is currently active (${task.state}) and cannot be deleted.`);
-    }
-
-    const trashRelPath = `.agent/jules-queue/.trash/${taskId}.md`;
-    return finalizePlan({
-      schema: "agentctl/action-plan-v1",
-      id: planId,
-      kind: "task.delete",
-      title: `Delete task ${taskId}`,
-      summary: `Move task file ${task.taskFile} to trash directory`,
-      risk: "moderate",
-      repository: root,
-      createdAt: new Date().toISOString(),
-      preconditions: [
-        {
-          kind: "file-hash",
-          target: task.taskFile,
-          expected: task.envelopeHash,
-        },
-      ],
-      fileMutations: [
-        {
-          operation: "move",
-          path: trashRelPath,
-          fromPath: task.taskFile,
-        },
-      ],
-      commandEffects: [],
-      stateTransitions: [{ taskId, from: task.state, to: "cancelled" }],
-      preview: {
-        unifiedDiff: `--- a/${task.taskFile}\n+++ /dev/null\n`,
-        warnings: [],
-        estimatedImpact: [`Moves ${taskId} to trash`],
-      },
-      confirmation: {
-        mode: "keypress",
-        prompt: `Delete task ${taskId}?`,
-      },
-      planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-    });
-  }
-
-  throw new Error(`Unsupported task action intent: ${intent.kind}`);
-}

package/src/ops/transaction.mjs

@@ -1,278 +0,0 @@
-import {
-  readFileSync,
-  mkdirSync,
-  existsSync,
-  unlinkSync,
-  renameSync,
-  openSync,
-  writeSync,
-  fsyncSync,
-  closeSync,
-} from "node:fs";
-import { join, dirname, resolve, relative, isAbsolute } from "node:path";
-import { createHash, randomUUID } from "node:crypto";
-import { execFileSync } from "node:child_process";
-import { createOperationReceipt } from "./receipts.mjs";
-import { withVfsMutex } from "../state.mjs";
-
-/**
- * @typedef {import("../ux/capabilities.mjs").TerminalSessionOptions} TerminalSessionOptions
- */
-
-/**
- * Calculate file SHA-256 hash.
- * @param {string} filePath
- * @returns {string | null}
- */
-function getFileHash(filePath) {
-  if (!existsSync(filePath)) return null;
-  try {
-    const data = readFileSync(filePath);
-    return "sha256:" + createHash("sha256").update(data).digest("hex");
-  } catch {
-    return null;
-  }
-}
-
-function resolveWithinRoot(root, candidate, label) {
-  if (typeof candidate !== "string" || !candidate || candidate.includes("\0")) {
-    throw new Error(`Invalid ${label} path`);
-  }
-  const targetPath = resolve(root, candidate);
-  const rel = relative(resolve(root), targetPath);
-  if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
-    throw new Error(`${label} path escapes repository root: ${candidate}`);
-  }
-  return targetPath;
-}
-
-function atomicWriteFile(filePath, content) {
-  const tmpPath = `${filePath}.${randomUUID()}.tmp`;
-  let fd;
-  try {
-    fd = openSync(tmpPath, "wx", 0o600);
-    writeSync(fd, content, "utf-8");
-    fsyncSync(fd);
-    closeSync(fd);
-    fd = undefined;
-    renameSync(tmpPath, filePath);
-  } catch (err) {
-    if (fd !== undefined) {
-      try { closeSync(fd); } catch (_) {}
-    }
-    try { unlinkSync(tmpPath); } catch (_) {}
-    throw err;
-  }
-}
-
-function throwIfAborted(signal) {
-  if (signal?.aborted) {
-    throw signal.reason || new Error("Action plan application aborted");
-  }
-}
-
-/**
- * Verify preconditions of an ActionPlan against target repository state.
- * @param {import("../ux/capabilities.mjs").ActionPlan} plan
- * @param {string} root
- */
-export function verifyPreconditions(plan, root) {
-  for (const cond of plan.preconditions || []) {
-    if (cond.kind === "file-hash") {
-      const targetPath = resolveWithinRoot(root, cond.target, "Precondition target");
-      const actualHash = getFileHash(targetPath);
-      if (actualHash !== cond.expected) {
-        throw new Error(
-          `Precondition failed [file-hash]: ${cond.target} expected ${cond.expected}, received ${actualHash}`
-        );
-      }
-    } else if (cond.kind === "lock-free") {
-      const lockTarget = String(cond.target || "");
-      const lockBase = resolveWithinRoot(root, join(".agent", "state", "locks", lockTarget), "Lock target");
-      const lockPaths = [`${lockBase}.json`, `${lockBase}.lock`];
-      if (lockPaths.some((lockPath) => existsSync(lockPath))) {
-        throw new Error(`Precondition failed [lock-free]: Lock ${cond.target} is active.`);
-      }
-    }
-  }
-}
-
-/**
- * Execute an ActionPlan within a transactional boundaries (atomic apply + rollback).
- * @param {any} plan
- * @param {Object} options
- * @param {string} options.root
- * @param {AbortSignal} [options.signal]
- * @returns {Promise<import("./receipts.mjs").OperationReceipt>}
- */
-export async function applyActionPlan(plan, options = {}) {
-  const root = resolve(options.root || process.cwd());
-  const mutexDir = join(root, ".agent", "state", ".action-plan.mutex");
-  mkdirSync(dirname(mutexDir), { recursive: true });
-  return withVfsMutex(mutexDir, () => applyActionPlanLocked(plan, { ...options, root }));
-}
-
-async function applyActionPlanLocked(plan, options) {
-  const root = options.root;
-  const startTime = Date.now();
-  throwIfAborted(options.signal);
-
-  // 1. Verify Preconditions
-  verifyPreconditions(plan, root);
-
-  // 2. Prepare Intent Journaling
-  if (!plan || typeof plan.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(plan.id)) {
-    throw new Error("Invalid action plan id");
-  }
-  const journalDir = join(root, ".agent", "state", "journal");
-  if (!existsSync(journalDir)) {
-    mkdirSync(journalDir, { recursive: true });
-  }
-  const journalPath = join(journalDir, `${plan.id}.intent.json`);
-  atomicWriteFile(journalPath, JSON.stringify({ plan, startedAt: new Date().toISOString() }, null, 2));
-
-  /** @type {Array<{ path: string, originalContent: string | null, operation?: string, fromPath?: string, sourceContent?: string }>} */
-  const rollbackStack = [];
-  const mutationsApplied = [];
-  const effectsExecuted = [];
-
-  try {
-    // 3. Apply File Mutations
-    for (const mutation of plan.fileMutations || []) {
-      throwIfAborted(options.signal);
-      const targetPath = resolveWithinRoot(root, mutation.path, "Mutation target");
-
-      if (mutation.operation === "move") {
-        const sourcePath = resolveWithinRoot(root, mutation.fromPath, "Move source");
-        if (sourcePath === targetPath) {
-          throw new Error(`Move source and target are identical: ${mutation.path}`);
-        }
-        if (!existsSync(sourcePath)) {
-          throw new Error(`Move source does not exist: ${mutation.fromPath}`);
-        }
-        if (existsSync(targetPath)) {
-          throw new Error(`Move target already exists: ${mutation.path}`);
-        }
-        const sourceContent = readFileSync(sourcePath, "utf-8");
-        const sourceHash = "sha256:" + createHash("sha256").update(sourceContent).digest("hex");
-        mkdirSync(dirname(targetPath), { recursive: true });
-        rollbackStack.push({
-          path: targetPath,
-          originalContent: null,
-          operation: "move",
-          fromPath: sourcePath,
-          sourceContent,
-        });
-        renameSync(sourcePath, targetPath);
-        mutationsApplied.push({ path: mutation.path, operation: "move", hashBefore: sourceHash });
-        continue;
-      }
-
-      if (!["delete", "create", "replace"].includes(mutation.operation)) {
-        throw new Error(`Unsupported file mutation operation: ${mutation.operation}`);
-      }
-
-      const parentDir = dirname(targetPath);
-      if (!existsSync(parentDir)) {
-        mkdirSync(parentDir, { recursive: true });
-      }
-
-      const existingContent = existsSync(targetPath) ? readFileSync(targetPath, "utf-8") : null;
-      const hashBefore = existingContent !== null
-        ? "sha256:" + createHash("sha256").update(existingContent).digest("hex")
-        : undefined;
-
-      if (mutation.operation === "create" && existingContent !== null) {
-        throw new Error(`Create target already exists: ${mutation.path}`);
-      }
-      rollbackStack.push({ path: targetPath, originalContent: existingContent, operation: mutation.operation });
-
-      if (mutation.operation === "delete") {
-        if (existsSync(targetPath)) {
-          unlinkSync(targetPath);
-        }
-        mutationsApplied.push({ path: mutation.path, operation: "delete", hashBefore });
-      } else {
-        const newContent = mutation.newContent ?? "";
-        atomicWriteFile(targetPath, newContent);
-
-        const hashAfter = "sha256:" + createHash("sha256").update(newContent).digest("hex");
-        mutationsApplied.push({ path: mutation.path, operation: mutation.operation, hashBefore, hashAfter });
-      }
-    }
-
-    // 4. Execute Command Effects
-    for (const effect of plan.commandEffects || []) {
-      throwIfAborted(options.signal);
-      const execPath = effect.executable;
-      const args = Array.isArray(effect.args) ? effect.args : [];
-      const cwd = effect.cwd ? resolveWithinRoot(root, effect.cwd, "Command working directory") : root;
-
-      try {
-        execFileSync(execPath, args, {
-          cwd,
-          timeout: effect.timeoutMs || 30000,
-          env: process.env,
-        });
-        effectsExecuted.push({ executable: execPath, args, exitCode: 0 });
-      } catch (err) {
-        const exitCode = typeof err.status === "number" ? err.status : 1;
-        effectsExecuted.push({ executable: execPath, args, exitCode });
-        throw new Error(`Command effect failed (${execPath} ${args.join(" ")}): exit code ${exitCode}`);
-      }
-    }
-
-    // 5. Clean up Journal & Record Success Receipt
-    if (existsSync(journalPath)) {
-      unlinkSync(journalPath);
-    }
-
-    const receipt = createOperationReceipt(root, {
-      actionPlanId: plan.id,
-      kind: plan.kind,
-      title: plan.title,
-      repository: plan.repository || "local",
-      status: "success",
-      durationMs: Date.now() - startTime,
-      mutationsApplied,
-      effectsExecuted,
-    });
-
-    return receipt;
-  } catch (err) {
-    // Execute Rollback Stack in reverse order
-    for (let i = rollbackStack.length - 1; i >= 0; i--) {
-      const mutation = rollbackStack[i];
-      try {
-        if (mutation.operation === "move") {
-          if (existsSync(mutation.path) && !existsSync(mutation.fromPath)) {
-            renameSync(mutation.path, mutation.fromPath);
-          }
-        } else if (mutation.originalContent === null) {
-          if (existsSync(mutation.path)) unlinkSync(mutation.path);
-        } else {
-          atomicWriteFile(mutation.path, mutation.originalContent);
-        }
-      } catch {
-        // Best-effort rollback
-      }
-    }
-
-    if (existsSync(journalPath)) {
-      try { unlinkSync(journalPath); } catch (_) {}
-    }
-
-    const failedReceipt = createOperationReceipt(root, {
-      actionPlanId: plan.id,
-      kind: plan.kind,
-      title: plan.title,
-      repository: plan.repository || "local",
-      status: "rolled-back",
-      durationMs: Date.now() - startTime,
-      mutationsApplied,
-      effectsExecuted,
-    });
-
-    throw new Error(`Action plan execution failed and was rolled back: ${err.message}. Receipt: ${failedReceipt.receiptId}`);
-  }
-}

package/src/ux/capabilities.mjs

@@ -1,180 +0,0 @@
-import { isatty } from "node:tty";
-
-/**
- * @typedef {Object} TerminalCapabilities
- * @property {boolean} inputIsTTY
- * @property {boolean} outputIsTTY
- * @property {number} columns
- * @property {number} rows
- * @property {0 | 4 | 8 | 24} colorDepth
- * @property {boolean} ansi
- * @property {boolean} unicode
- * @property {boolean} alternateScreen
- * @property {false} mouse
- * @property {NodeJS.Platform} platform
- * @property {string} term
- * @property {boolean} noColor
- * @property {boolean} forceColor
- * @property {boolean} reducedMotion
- */
-
-/**
- * @typedef {Object} TerminalSessionOptions
- * @property {import("node:stream").Readable} [input]
- * @property {import("node:stream").Writable} [output]
- * @property {import("node:stream").Writable} [errorOutput]
- * @property {boolean} [jsonMode]
- * @property {boolean} [alternateScreen]
- * @property {"auto" | "always" | "never"} [color]
- * @property {"auto" | "always" | "never"} [unicode]
- * @property {boolean} [reducedMotion]
- */
-
-/**
- * Detect current terminal capabilities based on streams, environment variables, and CLI options.
- * @param {TerminalSessionOptions} [options]
- * @returns {TerminalCapabilities}
- */
-export function detectTerminalCapabilities(options = {}) {
-  const input = options.input || process.stdin;
-  const output = options.output || process.stdout;
-  const env = process.env || {};
-  const argv = process.argv || [];
-
-  const inputIsTTY = Boolean(input && (input.isTTY || (typeof input.fd === "number" && isatty(input.fd))));
-  const outputIsTTY = Boolean(output && (output.isTTY || (typeof output.fd === "number" && isatty(output.fd))));
-
-  const term = String(env.TERM || "").toLowerCase();
-  const colorTerm = String(env.COLORTERM || "").toLowerCase();
-
-  // Environment color flags
-  const envNoColor = Boolean(env.NO_COLOR !== undefined && env.NO_COLOR !== "");
-  let envForceColor = false;
-  let envDisableColor = false;
-
-  if (env.FORCE_COLOR !== undefined) {
-    if (env.FORCE_COLOR === "0" || env.FORCE_COLOR === "false") {
-      envDisableColor = true;
-    } else {
-      envForceColor = true;
-    }
-  }
-
-  // CLI argument overrides
-  const cliNoColor = argv.includes("--no-color");
-  const cliColor = argv.includes("--color");
-  const cliAscii = argv.includes("--ascii");
-  const jsonMode = Boolean(options.jsonMode || argv.includes("--json"));
-
-  const noColor = envNoColor || cliNoColor || options.color === "never";
-  const forceColor = (envForceColor || cliColor || options.color === "always") && !envDisableColor;
-
-  // Priority evaluation for ANSI support:
-  // --no-color / options.color === "never" > NO_COLOR > FORCE_COLOR=0 > jsonMode > --color / FORCE_COLOR > auto TTY capability
-  let ansi = false;
-  if (jsonMode) {
-    ansi = false;
-  } else if (noColor || envDisableColor) {
-    ansi = false;
-  } else if (forceColor) {
-    ansi = true;
-  } else {
-    ansi = outputIsTTY && term !== "dumb";
-  }
-
-  // Color depth calculation
-  /** @type {0 | 4 | 8 | 24} */
-  let colorDepth = 0;
-  if (ansi) {
-    if (colorTerm === "truecolor" || colorTerm === "24bit" || env.FORCE_COLOR === "3") {
-      colorDepth = 24;
-    } else if (term.includes("256color") || colorTerm === "256color" || env.FORCE_COLOR === "2") {
-      colorDepth = 8;
-    } else {
-      colorDepth = 4;
-    }
-  }
-
-  // Unicode support detection
-  let unicode = true;
-  if (cliAscii || options.unicode === "never") {
-    unicode = false;
-  } else if (options.unicode === "always") {
-    unicode = true;
-  } else {
-    const lang = String(env.LANG || env.LC_ALL || env.LC_CTYPE || "").toLowerCase();
-    const isUtf8 = lang.includes("utf-8") || lang.includes("utf8");
-    // Default to true on non-windows or utf-8 windows terminals
-    unicode = isUtf8 || process.platform !== "win32" || Boolean(env.WT_SESSION);
-  }
-
-  // Terminal dimensions
-  const columns = Math.max(10, output.columns || input.columns || process.stdout.columns || 80);
-  const rows = Math.max(5, output.rows || input.rows || process.stdout.rows || 24);
-
-  const reducedMotion = Boolean(
-    options.reducedMotion ||
-    env.REDUCED_MOTION === "1" ||
-    env.REDUCED_MOTION === "true"
-  );
-
-  const alternateScreen = options.alternateScreen !== false && ansi && outputIsTTY;
-
-  return {
-    inputIsTTY,
-    outputIsTTY,
-    columns,
-    rows,
-    colorDepth,
-    ansi,
-    unicode,
-    alternateScreen,
-    mouse: false,
-    platform: process.platform,
-    term: env.TERM || "",
-    noColor,
-    forceColor,
-    reducedMotion,
-  };
-}
-
-/**
- * Get display symbol set based on unicode capability.
- * @param {TerminalCapabilities} caps
- */
-export function getSymbols(caps) {
-  if (caps.unicode) {
-    return {
-      select: "❯",
-      checked: "●",
-      unchecked: "○",
-      success: "✓",
-      warning: "!",
-      failure: "✗",
-      info: "ℹ",
-      bullet: "•",
-      ellipsis: "…",
-      spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
-      branchMiddle: "├─",
-      branchEnd: "└─",
-      arrowUp: "↑",
-      arrowDown: "↓",
-    };
-  }
-  return {
-    select: ">",
-    checked: "[x]",
-    unchecked: "[ ]",
-    success: "OK",
-    warning: "WARN",
-    failure: "ERR",
-    info: "INFO",
-    bullet: "*",
-    ellipsis: "...",
-    spinner: ["-", "\\", "|", "/"],
-    branchMiddle: "+-",
-    branchEnd: "`-",
-    arrowUp: "^",
-    arrowDown: "v",
-  };
-}