jules-orchestrator-kit 0.29.1 → 0.32.0

package/src/mcp.mjs

@@ -148,6 +148,19 @@ export const MCP_TOOLS = [
       },
     },
   },
+  {
+    name: "optimize_jules_prompt",
+    description: "Evaluate task prompt falsifiability, check static path validity, and synthesize optimized task envelope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Raw task prompt instructions to analyze or optimize" },
+        fix: { type: "boolean", description: "If true, synthesizes and returns an optimized task envelope" },
+        verifyCmd: { type: "string", description: "Optional explicit verification command" },
+      },
+      required: ["prompt"],
+    },
+  },
 ];
 
 export async function handleMcpRequest(request, opts = {}) {
@@ -291,6 +304,27 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      if (toolName === "optimize_jules_prompt") {
+        if (!args || typeof args.prompt !== "string") {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Invalid parameters: 'prompt' must be a string" },
+          };
+        }
+        const { scorePromptFalsifiability, optimizeTaskPrompt } = await import("./task-optimizer.mjs");
+        const res = args.fix
+          ? optimizeTaskPrompt(args.prompt, { rootDir: root, verifyCmd: args.verifyCmd })
+          : scorePromptFalsifiability(args.prompt, { rootDir: root, verifyCmd: args.verifyCmd });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
       return {
         jsonrpc: "2.0",
         id,

package/src/memory.mjs

@@ -0,0 +1,148 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+function atomicWrite(file, content) {
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+  writeFileSync(tmp, content, "utf8");
+  renameSync(tmp, file);
+}
+
+export function getLearningsPath(root = process.cwd()) {
+  return join(root, ".agent", "knowledge", "learnings.json");
+}
+
+export function getSystemLearningsMdPath(root = process.cwd()) {
+  return join(root, ".agent", "SYSTEM_LEARNINGS.md");
+}
+
+export function loadLearnings(root = process.cwd()) {
+  const dbFile = getLearningsPath(root);
+  if (!existsSync(dbFile)) return [];
+  try {
+    return JSON.parse(readFileSync(dbFile, "utf8"));
+  } catch (_) {
+    return [];
+  }
+}
+
+export function recordLearning(root = process.cwd(), learning = {}) {
+  const { agent = "agent", trigger, solution, category = "GENERAL" } = learning;
+  if (!trigger || !solution) {
+    throw new Error("Trigger and solution are required to record a learning.");
+  }
+
+  const dbFile = getLearningsPath(root);
+  const mdFile = getSystemLearningsMdPath(root);
+  const db = loadLearnings(root);
+
+  const cleanTrigger = trigger.trim();
+  const cleanSolution = solution.trim();
+
+  const isDuplicate = db.some(
+    (l) =>
+      l.trigger.toLowerCase() === cleanTrigger.toLowerCase() &&
+      l.solution.toLowerCase() === cleanSolution.toLowerCase()
+  );
+
+  if (!isDuplicate) {
+    db.push({
+      date: new Date().toISOString().split("T")[0],
+      agent,
+      category,
+      trigger: cleanTrigger,
+      solution: cleanSolution,
+    });
+    atomicWrite(dbFile, JSON.stringify(db, null, 2));
+  }
+
+  // Render Markdown table
+  const sanitize = (str) => str.replace(/\|/g, "&#124;").replace(/\r?\n/g, "<br>");
+  let md = `<!-- 🚫 AUTO-GENERATED. AGENTS: DO NOT EDIT THIS FILE DIRECTLY. -->\n`;
+  md += `# 🧠 System Learnings & Platform Quirks\n\n`;
+  md += `> **⚠️ TILL AGENTER:** Redigera ALDRIG denna fil manuellt. Registrera lärdomar via:\n`;
+  md += `> \`agentctl learning add "<trigger>" "<solution>"\`\n\n`;
+  md += `| Datum | Agent | Trigger / Symptom | Mandatory Rule / Solution |\n`;
+  md += `| :--- | :--- | :--- | :--- |\n`;
+
+  db.forEach((l) => {
+    md += `| ${l.date} | \`${l.agent}\` | ${sanitize(l.trigger)} | **${sanitize(l.solution)}** |\n`;
+  });
+
+  atomicWrite(mdFile, md);
+  return { recorded: !isDuplicate, count: db.length };
+}
+
+export function hydratePrompt(root = process.cwd(), promptText = "", opts = {}) {
+  const max = opts.max || 5;
+  const learnings = loadLearnings(root);
+  if (learnings.length === 0) return promptText;
+
+  const lowerPrompt = promptText.toLowerCase();
+  const matched = learnings.filter((l) => {
+    const triggerWords = l.trigger.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+    return triggerWords.some((w) => lowerPrompt.includes(w));
+  }).slice(0, max);
+
+  const activeLearnings = matched.length > 0 ? matched : learnings.slice(-max);
+
+  let header = "\n\n<ACTIVE_SYSTEM_LEARNINGS>\n";
+  header += "The following platform quirks & resolution rules apply to this task:\n";
+  activeLearnings.forEach((l) => {
+    header += `- [${l.category || "RULE"}] WHEN: ${l.trigger} → THEN: ${l.solution}\n`;
+  });
+  header += "</ACTIVE_SYSTEM_LEARNINGS>\n";
+
+  // Check for baton pass state
+  const batonFile = join(root, ".agent", "state", "baton_pass.json");
+  let batonBlock = "";
+  if (existsSync(batonFile)) {
+    try {
+      const baton = JSON.parse(readFileSync(batonFile, "utf8"));
+      batonBlock = `\n<BATON_PASS_STATE>\n`;
+      batonBlock += `Previous Task ID: ${baton.taskId || "unknown"}\n`;
+      batonBlock += `Last Status: ${baton.status || "BLOCKED"}\n`;
+      if (baton.summary) batonBlock += `Summary: ${baton.summary}\n`;
+      batonBlock += `</BATON_PASS_STATE>\n`;
+    } catch (_) {}
+  }
+
+  return `${header}${batonBlock}\n${promptText}`;
+}
+
+export function harvestFailure(root = process.cwd(), opts = {}) {
+  const { exitCode = 4, logPath, diffText = "", taskId = "unknown", agent = "jules" } = opts;
+
+  let logContent = "";
+  if (logPath && existsSync(logPath)) {
+    try {
+      logContent = readFileSync(logPath, "utf8");
+    } catch (_) {}
+  }
+
+  // Guard: Test Weakening check
+  const testWeakeningRegex = /-\s*(it\(|test\(|expect\(|assert\.)/g;
+  if (testWeakeningRegex.test(diffText)) {
+    return { status: "REJECTED", reason: "TEST_WEAKENING: Attempted to delete or weaken test assertions." };
+  }
+
+  // Guard: Diff Limit check (75 KiB limit)
+  const MAX_DIFF_BYTES = 75 * 1024;
+  if (Buffer.byteLength(diffText, "utf8") > MAX_DIFF_BYTES) {
+    return { status: "REJECTED", reason: "DIFF_PAYLOAD_LIMIT: Diff payload exceeds 75 KiB limit." };
+  }
+
+  // Extract error trace line
+  const errorLine = logContent.split("\n").find((line) => /Error:|FAIL|TypeError|AssertionError/.test(line)) || "Unknown execution failure";
+
+  const candidate = {
+    agent,
+    category: "OODA_HARVEST",
+    trigger: `[OODA Exit ${exitCode}] ${errorLine.slice(0, 120)}`,
+    solution: `Verify root cause from log (Task ${taskId}) before altering logic. Avoid fragile hacks or removing assertions.`,
+  };
+
+  const res = recordLearning(root, candidate);
+  return { status: "HARVESTED", candidate, recorded: res.recorded };
+}

package/src/ops/checkpoint.mjs

@@ -0,0 +1,167 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { git, changedFiles, diffText } from "../git.mjs";
+import { resolveRoot } from "../config.mjs";
+
+export class CheckpointError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "CheckpointError";
+    this.code = opts.code || 1;
+  }
+}
+
+/**
+ * Ensures checkpoint storage directory exists.
+ */
+export function getCheckpointDir(root = resolveRoot()) {
+  const dir = join(root, ".agent", "state", "checkpoints");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (_) {}
+  return dir;
+}
+
+/**
+ * Creates an atomic pre-flight snapshot of the repository state before an agent task runs.
+ * @param {string} sessionId
+ * @param {object} options
+ * @returns {object} Checkpoint metadata
+ */
+export function createCheckpoint(sessionId = `session-${Date.now()}`, options = {}) {
+  const root = options.root || resolveRoot();
+  const dir = getCheckpointDir(root);
+
+  let headSha = "";
+  try {
+    headSha = git(["rev-parse", "HEAD"], { cwd: root, ignoreError: true }).trim();
+  } catch (_) {}
+
+  let branch = "";
+  try {
+    branch = git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root, ignoreError: true }).trim();
+  } catch (_) {}
+
+  const uncommittedFiles = changedFiles(root, branch || "main", "working-tree");
+  const diffContent = diffText(root, branch || "main", "working-tree");
+
+  const snapshot = {
+    version: 1,
+    id: sessionId,
+    timestamp: new Date().toISOString(),
+    headSha,
+    branch,
+    uncommittedFiles,
+    diffContent,
+  };
+
+  const snapshotPath = join(dir, `${sessionId}.json`);
+  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
+
+  // Keep last 10 checkpoints
+  pruneCheckpoints(root, 10);
+
+  return snapshot;
+}
+
+/**
+ * Restores working tree and git state to a previously saved checkpoint.
+ * @param {string} sessionId or '--latest'
+ * @param {object} options
+ * @returns {object} Restore result summary
+ */
+export function restoreCheckpoint(sessionId = "--latest", options = {}) {
+  const root = options.root || resolveRoot();
+  const dir = getCheckpointDir(root);
+
+  let targetId = sessionId;
+  if (!targetId || targetId === "--latest" || targetId === "latest") {
+    const list = listCheckpoints(root);
+    if (list.length === 0) {
+      throw new CheckpointError("No checkpoints found to restore.");
+    }
+    targetId = list[0].id;
+  }
+
+  const snapshotFile = join(dir, `${targetId}.json`);
+  if (!existsSync(snapshotFile)) {
+    throw new CheckpointError(`Checkpoint snapshot file not found for session '${targetId}'.`);
+  }
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(readFileSync(snapshotFile, "utf-8"));
+  } catch (err) {
+    throw new CheckpointError(`Corrupted checkpoint file '${targetId}.json': ${err.message}`);
+  }
+
+  if (snapshot.headSha) {
+    try {
+      git(["reset", "--hard", snapshot.headSha], { cwd: root, ignoreError: true });
+    } catch (err) {
+      throw new CheckpointError(`Failed git reset --hard ${snapshot.headSha}: ${err.message}`);
+    }
+  }
+
+  // Clean untracked files generated during session
+  try {
+    git(["clean", "-fd"], { cwd: root, ignoreError: true });
+  } catch (_) {}
+
+  return {
+    ok: true,
+    id: snapshot.id,
+    headSha: snapshot.headSha,
+    restoredAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Lists all active checkpoints ordered by timestamp descending.
+ */
+export function listCheckpoints(root = resolveRoot()) {
+  const dir = getCheckpointDir(root);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  const items = [];
+
+  for (const file of files) {
+    const filePath = join(dir, file);
+    try {
+      const data = JSON.parse(readFileSync(filePath, "utf-8"));
+      items.push({
+        id: data.id || file.replace(/\.json$/, ""),
+        timestamp: data.timestamp || new Date(statSync(filePath).mtimeMs).toISOString(),
+        headSha: data.headSha || "",
+        branch: data.branch || "",
+        filePath,
+      });
+    } catch (_) {}
+  }
+
+  items.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+  return items;
+}
+
+/**
+ * Prunes checkpoints keeping only the most recent N sessions.
+ */
+export function pruneCheckpoints(root = resolveRoot(), maxRetention = 10) {
+  const list = listCheckpoints(root);
+  if (list.length <= maxRetention) return 0;
+
+  const toRemove = list.slice(maxRetention);
+  let prunedCount = 0;
+
+  for (const item of toRemove) {
+    try {
+      if (existsSync(item.filePath)) {
+        rmSync(item.filePath, { force: true });
+        prunedCount++;
+      }
+    } catch (_) {}
+  }
+
+  return prunedCount;
+}

package/src/ops/command-registry.mjs

@@ -0,0 +1,274 @@
+/**
+ * @typedef {"low" | "moderate" | "high" | "destructive"} RiskLevel
+ * @typedef {"Create" | "Inspect" | "Operate" | "Repair" | "Configure"} CommandCategory
+ *
+ * @typedef {Object} CommandFlag
+ * @property {string} name
+ * @property {"boolean" | "string"} type
+ * @property {string} description
+ * @property {any} [default]
+ *
+ * @typedef {Object} CommandDescriptor
+ * @property {string} id
+ * @property {string[]} path
+ * @property {string} title
+ * @property {string} description
+ * @property {CommandCategory} category
+ * @property {boolean} mutates
+ * @property {RiskLevel} risk
+ * @property {"never" | "optional" | "authoring-auto"} interactive
+ * @property {boolean} requiresRepository
+ * @property {string[]} shortcuts
+ * @property {string[]} examples
+ * @property {CommandFlag[]} flags
+ */
+
+/** @type {CommandDescriptor[]} */
+export const COMMAND_REGISTRY = [
+  {
+    id: "doctor",
+    path: ["doctor"],
+    title: "doctor",
+    description: "Run repository diagnostics and guided fixes",
+    category: "Repair",
+    mutates: false,
+    risk: "low",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["d", "doc"],
+    examples: [
+      "agentctl doctor",
+      "agentctl doctor --interactive",
+      "agentctl doctor --fix safe --yes",
+      "agentctl doctor --json",
+    ],
+    flags: [
+      { name: "interactive", type: "boolean", description: "Open full-screen diagnostic matrix" },
+      { name: "fix", type: "string", description: "Apply fix classes (e.g. 'safe' or check IDs)" },
+      { name: "probe", type: "boolean", description: "Enable active network/execution probes" },
+      { name: "json", type: "boolean", description: "Output structured JSON doctor report" },
+      { name: "yes", type: "boolean", description: "Bypass interactive confirmation for safe fixes" },
+    ],
+  },
+  {
+    id: "queue",
+    path: ["queue"],
+    title: "queue",
+    description: "Browse and manage canonical task queue",
+    category: "Operate",
+    mutates: false,
+    risk: "low",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["q"],
+    examples: [
+      "agentctl queue",
+      "agentctl queue --interactive",
+      "agentctl queue --json",
+    ],
+    flags: [
+      { name: "interactive", type: "boolean", description: "Open full-screen queue dashboard" },
+      { name: "json", type: "boolean", description: "Output structured JSON queue snapshot" },
+      { name: "limit", type: "string", description: "Maximum tasks to include in snapshot" },
+    ],
+  },
+  {
+    id: "swarm",
+    path: ["swarm"],
+    title: "swarm",
+    description: "Inspect active worker slots and concurrency scheduler",
+    category: "Operate",
+    mutates: false,
+    risk: "low",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["s"],
+    examples: [
+      "agentctl swarm",
+      "agentctl swarm --interactive",
+      "agentctl swarm --json",
+    ],
+    flags: [
+      { name: "interactive", type: "boolean", description: "Open full-screen swarm dashboard" },
+      { name: "json", type: "boolean", description: "Output structured JSON swarm snapshot" },
+    ],
+  },
+  {
+    id: "task-create",
+    path: ["task", "create"],
+    title: "task create",
+    description: "Author a scoped, falsifiable task",
+    category: "Create",
+    mutates: true,
+    risk: "moderate",
+    interactive: "authoring-auto",
+    requiresRepository: true,
+    shortcuts: ["tc", "create"],
+    examples: [
+      'agentctl task create --title "Fix webhook" --prompt "Add retry handling" --verify-cmd "npm test"',
+      "agentctl task create --interactive",
+    ],
+    flags: [
+      { name: "title", type: "string", description: "Short title for task" },
+      { name: "prompt", type: "string", description: "Detailed task instructions" },
+      { name: "verify-cmd", type: "string", description: "Verification command" },
+      { name: "interactive", type: "boolean", description: "Launch interactive task wizard" },
+    ],
+  },
+  {
+    id: "task-optimize",
+    path: ["task", "optimize"],
+    title: "task optimize",
+    description: "Score task prompt falsifiability and static path resolution",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["to", "optimize"],
+    examples: [
+      'agentctl task optimize "Fix JWT token expiry in src/auth.js"',
+      'agentctl task optimize "Refactor auth" --fix',
+      'agentctl task optimize --file prompt.txt --json',
+    ],
+    flags: [
+      { name: "fix", type: "boolean", description: "Synthesize optimized markdown task envelope" },
+      { name: "json", type: "boolean", description: "Output structured JSON prompt evaluation" },
+      { name: "file", type: "string", description: "Path to text file containing task prompt" },
+      { name: "dir", type: "string", description: "Target repository directory root" },
+    ],
+  },
+  {
+    id: "init",
+    path: ["init"],
+    title: "init",
+    description: "Configure Stack Oracle and Jules provider manifests",
+    category: "Configure",
+    mutates: true,
+    risk: "moderate",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["i"],
+    examples: [
+      "agentctl init",
+      "agentctl init --interactive",
+      "agentctl init --tier pro --yes",
+    ],
+    flags: [
+      { name: "tier", type: "string", description: "Target configuration tier (free, pro, enterprise)" },
+      { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard" },
+      { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults" },
+    ],
+  },
+  {
+    id: "dashboard",
+    path: ["dashboard"],
+    title: "dashboard",
+    description: "Start local web dashboard server",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["dash"],
+    examples: [
+      "agentctl dashboard",
+      "agentctl dashboard --port 3000",
+    ],
+    flags: [
+      { name: "port", type: "string", description: "HTTP server port (default 3000)" },
+      { name: "host", type: "string", description: "Bind host address (default 127.0.0.1)" },
+    ],
+  },
+  {
+    id: "status",
+    path: ["status"],
+    title: "status",
+    description: "Show operating status and health summary",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: false,
+    shortcuts: ["st"],
+    examples: [
+      "agentctl status",
+      "agentctl status --json",
+    ],
+    flags: [
+      { name: "json", type: "boolean", description: "Output status in JSON format" },
+    ],
+  },
+];
+
+/**
+ * Lookup command descriptor by ID, command path, or shortcut alias.
+ * @param {string} idOrAlias
+ * @returns {CommandDescriptor | null}
+ */
+export function getCommandDescriptor(idOrAlias) {
+  if (!idOrAlias) return null;
+  const target = String(idOrAlias).trim().toLowerCase();
+
+  return (
+    COMMAND_REGISTRY.find((cmd) => {
+      if (cmd.id.toLowerCase() === target) return true;
+      if (cmd.path.join(" ").toLowerCase() === target) return true;
+      if (cmd.shortcuts.some((s) => s.toLowerCase() === target)) return true;
+      return false;
+    }) || null
+  );
+}
+
+/**
+ * List commands filtered by category.
+ * @param {CommandCategory} [category]
+ * @returns {CommandDescriptor[]}
+ */
+export function listCommandsByCategory(category) {
+  if (!category) return COMMAND_REGISTRY;
+  return COMMAND_REGISTRY.filter((cmd) => cmd.category === category);
+}
+
+/**
+ * Format clean CLI --help text for a command descriptor.
+ * @param {CommandDescriptor} descriptor
+ * @returns {string}
+ */
+export function formatCommandHelp(descriptor) {
+  const lines = [];
+  lines.push(`Usage: agentctl ${descriptor.path.join(" ")} [flags]`);
+  lines.push("");
+  lines.push(`Description: ${descriptor.description}`);
+  lines.push(`Category:    ${descriptor.category}`);
+  lines.push(`Risk Tier:   ${descriptor.risk.toUpperCase()}`);
+  lines.push("");
+
+  if (descriptor.flags && descriptor.flags.length > 0) {
+    lines.push("Flags:");
+    for (const flag of descriptor.flags) {
+      lines.push(`  --${flag.name.padEnd(16)} ${flag.description}`);
+    }
+    lines.push("");
+  }
+
+  if (descriptor.examples && descriptor.examples.length > 0) {
+    lines.push("Examples:");
+    for (const ex of descriptor.examples) {
+      lines.push(`  $ ${ex}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format JSON representation of full command registry.
+ * @returns {{ ok: true, commands: CommandDescriptor[] }}
+ */
+export function formatRegistryJson() {
+  return {
+    ok: true,
+    commands: COMMAND_REGISTRY,
+  };
+}