jules-orchestrator-kit 0.52.8 → 0.54.0

package/src/ops/doctor-planner.mjs

@@ -1,220 +0,0 @@
-import { join, resolve } from "node:path";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { createHash, randomUUID } from "node:crypto";
-import { detectStack } from "../config.mjs";
-
-/**
- * @typedef {import("../ux/capabilities.mjs").ActionPlan} ActionPlan
- * @typedef {import("./doctor-registry.mjs").DoctorReport} DoctorReport
- *
- * @typedef {Object} FixPlanningContext
- * @property {string} root
- * @property {DoctorReport} report
- * @property {string[]} selectedFixIds
- * @property {Record<string, unknown>} [answers]
- */
-
-/**
- * Generate unified diff preview string for file creation/replacement.
- * @param {string} path
- * @param {string} oldContent
- * @param {string} newContent
- * @returns {string}
- */
-function createDiffPreview(path, oldContent, newContent) {
-  const oldLines = oldContent ? oldContent.split("\n") : [];
-  const newLines = newContent ? newContent.split("\n") : [];
-  const lines = [];
-
-  lines.push(`--- a/${path}`);
-  lines.push(`+++ b/${path}`);
-  lines.push(`@@ -1,${oldLines.length || 0} +1,${newLines.length || 0} @@`);
-
-  for (const line of oldLines) {
-    lines.push(`-${line}`);
-  }
-  for (const line of newLines) {
-    lines.push(`+${line}`);
-  }
-
-  return lines.join("\n");
-}
-
-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 });
-}
-
-/**
- * Plan diagnostic fixes into immutable ActionPlan objects.
- * @param {FixPlanningContext} context
- * @returns {Promise<ActionPlan[]>}
- */
-export async function planDiagnosticFixes(context = {}) {
-  const root = resolve(context.root || process.cwd());
-  const report = context.report || { results: [] };
-  const selectedFixIds = Array.isArray(context.selectedFixIds) ? context.selectedFixIds : ["safe"];
-
-  const wantSafeOnly = selectedFixIds.includes("safe");
-  /** @type {ActionPlan[]} */
-  const plans = [];
-
-  for (const result of report.results || []) {
-    for (const fix of result.fixes || []) {
-      const isSelected = selectedFixIds.includes(fix.id) || (wantSafeOnly && fix.automatic);
-      if (!isSelected) continue;
-
-      if (fix.id === "config.create-default") {
-        const configPath = ".agent/config.yml";
-        // Detected, not assumed. Writing `npm test` into a Rust or Python
-        // repository's config produced a manifest whose first verification run
-        // could only fail, and the stack detector already has the answer.
-        const detected = detectStack(root);
-        const newContent = `# jules-orchestrator-kit configuration manifest
-version: 1
-# Free-tier limits until you state your plan (free | pro | ultra).
-tier: free
-verify:
-  test: ${JSON.stringify(detected.testCmd || "")}
-  build: ${JSON.stringify(detected.buildCmd || "")}
-`;
-        const diff = createDiffPreview(configPath, "", newContent);
-        const planId = `PLAN-${Date.now()}-${randomUUID().slice(0, 8)}`;
-
-        plans.push({
-          schema: "agentctl/action-plan-v1",
-          id: planId,
-          kind: "config.create-default",
-          title: "Create default .agent/config.yml",
-          summary: "Generate initial configuration manifest for jules-orchestrator-kit",
-          risk: "low",
-          repository: root,
-          createdAt: new Date().toISOString(),
-          preconditions: [],
-          fileMutations: [
-            {
-              operation: "create",
-              path: configPath,
-              newContent,
-            },
-          ],
-          commandEffects: [],
-          stateTransitions: [],
-          preview: {
-            unifiedDiff: diff,
-            warnings: [],
-            estimatedImpact: ["Creates .agent/config.yml"],
-          },
-          confirmation: {
-            mode: "none",
-            prompt: "Apply default configuration?",
-          },
-          planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-        });
-      } else if (fix.id === "state.rebuild-head") {
-        const dateStr = new Date().toISOString().split("T")[0];
-        const stateDir = join(root, ".agent", "state");
-        const headPath = `.agent/state/telemetry-${dateStr}.head`;
-        let tailHash = "0".repeat(64);
-        let segment = 0;
-        try {
-          const telemetryFiles = readdirSync(stateDir)
-            .filter((name) => name.startsWith(`telemetry-${dateStr}`) && name.endsWith(".jsonl"))
-            .sort((a, b) => {
-              const index = (name) => Number(name.match(/-(\d+)\.jsonl$/)?.[1] || 0);
-              return index(a) - index(b);
-            });
-          const lastFile = telemetryFiles.at(-1);
-          if (lastFile) {
-            const lines = readFileSync(join(stateDir, lastFile), "utf-8").split("\n").filter(Boolean);
-            const lastEntry = JSON.parse(lines.at(-1));
-            if (typeof lastEntry?.hash === "string") tailHash = lastEntry.hash;
-            const segmentMatch = lastFile.match(/-(\d+)\.jsonl$/);
-            segment = segmentMatch ? Number(segmentMatch[1]) : 0;
-          }
-        } catch (_) {}
-        const newContent = JSON.stringify({ v: 1, hash: tailHash, segment, ts: new Date().toISOString() });
-        const planId = `PLAN-${Date.now()}-${randomUUID().slice(0, 8)}`;
-
-        plans.push({
-          schema: "agentctl/action-plan-v1",
-          id: planId,
-          kind: "state.rebuild-head",
-          title: "Rebuild telemetry spine head pointer",
-          summary: "Re-initialize .head pointer for telemetry spine ledger",
-          risk: "low",
-          repository: root,
-          createdAt: new Date().toISOString(),
-          preconditions: [],
-          fileMutations: [
-            {
-              operation: "create",
-              path: headPath,
-              newContent,
-            },
-          ],
-          commandEffects: [],
-          stateTransitions: [],
-          preview: {
-            unifiedDiff: createDiffPreview(headPath, "", newContent),
-            warnings: [],
-            estimatedImpact: [`Creates ${headPath} pointer`],
-          },
-          confirmation: {
-            mode: "none",
-            prompt: "Rebuild telemetry head pointer?",
-          },
-          planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-        });
-      } else if (fix.id === "locks.prune-stale") {
-        const locksDir = join(root, ".agent", "state", "locks");
-        if (existsSync(locksDir)) {
-          const lockFiles = readdirSync(locksDir).filter((f) => f.endsWith(".json"));
-          for (const lockFile of lockFiles) {
-            const lockRelPath = `.agent/state/locks/${lockFile}`;
-            const planId = `PLAN-${Date.now()}-${randomUUID().slice(0, 8)}`;
-
-            plans.push({
-              schema: "agentctl/action-plan-v1",
-              id: planId,
-              kind: "locks.prune-stale",
-              title: `Remove stale lock ${lockFile}`,
-              summary: `Prune inactive VFS lock file ${lockRelPath}`,
-              risk: "low",
-              repository: root,
-              createdAt: new Date().toISOString(),
-              preconditions: [],
-              fileMutations: [
-                {
-                  operation: "delete",
-                  path: lockRelPath,
-                },
-              ],
-              commandEffects: [],
-              stateTransitions: [],
-              preview: {
-                unifiedDiff: `--- a/${lockRelPath}\n+++ /dev/null\n`,
-                warnings: [],
-                estimatedImpact: [`Removes ${lockRelPath}`],
-              },
-              confirmation: {
-                mode: "none",
-                prompt: `Remove lock ${lockFile}?`,
-              },
-              planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-            });
-          }
-        }
-      }
-    }
-  }
-
-  return plans.map(finalizePlan);
-}

package/src/ops/receipts.mjs

@@ -1,171 +0,0 @@
-import {
-  readFileSync,
-  mkdirSync,
-  existsSync,
-  openSync,
-  writeSync,
-  fsyncSync,
-  closeSync,
-  renameSync,
-  unlinkSync,
-} from "node:fs";
-import { join, resolve, relative, isAbsolute } from "node:path";
-import { createHash, randomUUID } from "node:crypto";
-import { redactSecrets } from "../security.mjs";
-
-/**
- * @typedef {Object} OperationReceipt
- * @property {"agentctl/operation-receipt-v1"} schema
- * @property {string} receiptId
- * @property {string} actionPlanId
- * @property {string} kind
- * @property {string} title
- * @property {string} repository
- * @property {string} appliedAt
- * @property {"success" | "rolled-back" | "failed"} status
- * @property {number} durationMs
- * @property {Array<{ path: string, operation: string, hashBefore?: string, hashAfter?: string }>} mutationsApplied
- * @property {Array<{ executable: string, args: string[], exitCode: number }>} effectsExecuted
- * @property {string} receiptHash
- */
-
-/**
- * Compute SHA-256 hash of operation receipt metadata.
- * @param {Omit<OperationReceipt, "receiptHash">} receipt
- * @returns {string}
- */
-export function computeReceiptHash(receipt) {
-  const payload = JSON.stringify({
-    schema: receipt.schema,
-    receiptId: receipt.receiptId,
-    actionPlanId: receipt.actionPlanId,
-    kind: receipt.kind,
-    title: receipt.title,
-    repository: receipt.repository,
-    status: receipt.status,
-    appliedAt: receipt.appliedAt,
-    durationMs: receipt.durationMs,
-    mutationsApplied: receipt.mutationsApplied,
-    effectsExecuted: receipt.effectsExecuted,
-  });
-  return "sha256:" + createHash("sha256").update(payload).digest("hex");
-}
-
-function redactReceiptValue(value) {
-  if (typeof value === "string") return redactSecrets(value);
-  if (Array.isArray(value)) return value.map(redactReceiptValue);
-  if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, redactReceiptValue(child)]));
-  }
-  return value;
-}
-
-function assertReceiptId(receiptId) {
-  if (typeof receiptId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(receiptId)) {
-    throw new Error("Invalid operation receipt id");
-  }
-}
-
-function writeFileAtomically(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;
-  }
-}
-
-/**
- * Create and persist an OperationReceipt atomically.
- * @param {string} root
- * @param {Omit<OperationReceipt, "schema" | "receiptId" | "appliedAt" | "receiptHash"> & { receiptId?: string }} data
- * @returns {OperationReceipt}
- */
-export function createOperationReceipt(root, data) {
-  const receiptsDir = join(root, ".agent", "receipts");
-  if (!existsSync(receiptsDir)) {
-    mkdirSync(receiptsDir, { recursive: true });
-  }
-
-  const receiptId = data.receiptId || `REC-${Date.now()}-${randomUUID().slice(0, 8)}`;
-  assertReceiptId(receiptId);
-  const appliedAt = new Date().toISOString();
-
-  const baseReceipt = redactReceiptValue({
-    schema: /** @type {const} */ ("agentctl/operation-receipt-v1"),
-    receiptId,
-    actionPlanId: data.actionPlanId,
-    kind: data.kind,
-    title: data.title,
-    repository: data.repository || "local",
-    appliedAt,
-    status: data.status,
-    durationMs: data.durationMs || 0,
-    mutationsApplied: data.mutationsApplied || [],
-    effectsExecuted: data.effectsExecuted || [],
-  });
-
-  const receiptHash = computeReceiptHash(baseReceipt);
-  /** @type {OperationReceipt} */
-  const fullReceipt = {
-    ...baseReceipt,
-    receiptHash,
-  };
-
-  const targetPath = join(receiptsDir, `${receiptId}.json`);
-  writeFileAtomically(targetPath, JSON.stringify(fullReceipt, null, 2));
-
-  return fullReceipt;
-}
-
-/**
- * Load and validate an OperationReceipt from disk.
- * @param {string} root
- * @param {string} receiptIdOrPath
- * @returns {OperationReceipt}
- */
-export function loadOperationReceipt(root, receiptIdOrPath) {
-  const receiptsDir = resolve(root, ".agent", "receipts");
-  let targetPath;
-  if (typeof receiptIdOrPath !== "string" || !receiptIdOrPath) {
-    throw new Error("Operation receipt id or path is required");
-  }
-
-  if (!receiptIdOrPath.endsWith(".json")) {
-    assertReceiptId(receiptIdOrPath);
-    targetPath = join(receiptsDir, `${receiptIdOrPath}.json`);
-  } else {
-    targetPath = isAbsolute(receiptIdOrPath) ? resolve(receiptIdOrPath) : resolve(root, receiptIdOrPath);
-    const rel = relative(receiptsDir, targetPath);
-    if (rel.startsWith("..") || isAbsolute(rel)) {
-      throw new Error("Operation receipt path escapes the receipts directory");
-    }
-  }
-
-  if (!existsSync(targetPath)) {
-    throw new Error(`Operation receipt not found: ${targetPath}`);
-  }
-
-  const content = readFileSync(targetPath, "utf-8");
-  /** @type {OperationReceipt} */
-  const receipt = JSON.parse(content);
-
-  if (receipt.schema !== "agentctl/operation-receipt-v1") {
-    throw new Error(`Invalid receipt schema version: ${receipt.schema}`);
-  }
-  if (receipt.receiptHash !== computeReceiptHash(receipt)) {
-    throw new Error(`Invalid operation receipt hash: ${targetPath}`);
-  }
-
-  return receipt;
-}

package/src/ops/swarm-actions.mjs

@@ -1,156 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-
-/**
- * @typedef {import("../ux/capabilities.mjs").ActionPlan} ActionPlan
- * @typedef {import("../ux/swarm-model.mjs").SwarmSlot} SwarmSlot
- */
-
-/**
- * Plan swarm concurrency action into an immutable ActionPlan.
- * @param {{ slots: SwarmSlot[], revision: string }} snapshot
- * @param {Object} intent
- * @param {string} intent.kind
- * @param {string} [intent.slotId]
- * @param {string} [intent.taskId]
- * @param {Record<string, any>} [intent.answers]
- * @returns {Promise<ActionPlan>}
- */
-export async function planSwarmAction(snapshot, intent) {
-  const planId = `PLAN-SWARM-${Date.now()}-${randomUUID().slice(0, 8)}`;
-
-  if (intent.kind === "pause-scheduler" || intent.kind === "resume-scheduler") {
-    const isPause = intent.kind === "pause-scheduler";
-    const schedulerRelPath = ".agent/state/swarm/scheduler.json";
-    const newContent = JSON.stringify(
-      {
-        schema: "agentctl/swarm-scheduler-v1",
-        paused: isPause,
-        updatedAt: new Date().toISOString(),
-      },
-      null,
-      2
-    );
-
-    return {
-      schema: "agentctl/action-plan-v1",
-      id: planId,
-      kind: intent.kind,
-      title: `${isPause ? "Pause" : "Resume"} Swarm Scheduler`,
-      summary: `${isPause ? "Halt dispatching new tasks to swarm slots" : "Resume task dispatching to available slots"}`,
-      risk: "moderate",
-      repository: "local",
-      createdAt: new Date().toISOString(),
-      preconditions: [],
-      fileMutations: [
-        {
-          operation: "replace",
-          path: schedulerRelPath,
-          newContent,
-        },
-      ],
-      commandEffects: [],
-      stateTransitions: [],
-      preview: {
-        unifiedDiff: `--- a/${schedulerRelPath}\n+++ b/${schedulerRelPath}\n@@ -paused @@\n- paused: ${!isPause}\n+ paused: ${isPause}\n`,
-        warnings: isPause ? ["Running tasks will complete, but no new tasks will be scheduled."] : [],
-        estimatedImpact: [`Swarm scheduler state set to ${isPause ? "PAUSED" : "RUNNING"}`],
-      },
-      confirmation: {
-        mode: "keypress",
-        prompt: `Confirm ${isPause ? "pause" : "resume"} of swarm scheduler?`,
-      },
-      planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-    };
-  }
-
-  if (intent.kind === "cancel-slot-task") {
-    const slotId = intent.slotId;
-    const slot = (snapshot.slots || []).find((s) => s.id === slotId || s.taskId === intent.taskId);
-    if (!slot) {
-      throw new Error(`Target slot ${slotId || intent.taskId} not found.`);
-    }
-
-    const slotRelPath = `.agent/state/swarm/${slot.id}.json`;
-    const newContent = JSON.stringify(
-      {
-        id: slot.id,
-        state: "draining",
-        taskId: slot.taskId,
-        cancelledAt: new Date().toISOString(),
-      },
-      null,
-      2
-    );
-
-    return {
-      schema: "agentctl/action-plan-v1",
-      id: planId,
-      kind: "swarm.cancel-slot-task",
-      title: `Cancel active slot task ${slot.taskId || slot.id}`,
-      summary: `Send cancellation signal to slot ${slot.id} (Task ${slot.taskId || "N/A"})`,
-      risk: "high",
-      repository: "local",
-      createdAt: new Date().toISOString(),
-      preconditions: [],
-      fileMutations: [
-        {
-          operation: "replace",
-          path: slotRelPath,
-          newContent,
-        },
-      ],
-      commandEffects: [],
-      stateTransitions: [{ taskId: slot.taskId, from: slot.state, to: "cancelled" }],
-      preview: {
-        unifiedDiff: `--- a/${slotRelPath}\n+++ b/${slotRelPath}\n@@ -state @@\n- state: ${slot.state}\n+ state: draining\n`,
-        warnings: ["Cancelling a running worker process will terminate its active attempt."],
-        estimatedImpact: [`Cancels execution in slot ${slot.id}`],
-      },
-      confirmation: {
-        mode: "typed-task-id",
-        prompt: `Type '${slot.taskId || slot.id}' to confirm cancellation:`,
-        expected: slot.taskId || slot.id,
-      },
-      planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-    };
-  }
-
-  if (intent.kind === "prune-stale-slots") {
-    const staleSlots = (snapshot.slots || []).filter((s) => s.state === "stale");
-    if (staleSlots.length === 0) {
-      throw new Error("No stale slots found to prune.");
-    }
-
-    const fileMutations = staleSlots.map((s) => ({
-      operation: /** @type {const} */ ("delete"),
-      path: `.agent/state/swarm/${s.id}.json`,
-    }));
-
-    return {
-      schema: "agentctl/action-plan-v1",
-      id: planId,
-      kind: "swarm.prune-stale-slots",
-      title: `Prune ${staleSlots.length} stale swarm slot(s)`,
-      summary: `Remove stale slot state files for dead worker process PIDs`,
-      risk: "low",
-      repository: "local",
-      createdAt: new Date().toISOString(),
-      preconditions: [],
-      fileMutations,
-      commandEffects: [],
-      stateTransitions: [],
-      preview: {
-        unifiedDiff: staleSlots.map((s) => `--- a/.agent/state/swarm/${s.id}.json\n+++ /dev/null\n`).join("\n"),
-        warnings: [],
-        estimatedImpact: [`Prunes ${staleSlots.length} stale slot file(s)`],
-      },
-      confirmation: {
-        mode: "keypress",
-        prompt: `Prune ${staleSlots.length} stale slot(s)?`,
-      },
-      planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
-    };
-  }
-
-  throw new Error(`Unsupported swarm action intent: ${intent.kind}`);
-}