jules-orchestrator-kit 0.51.0 → 0.52.1

package/src/ops/command-registry.mjs

@@ -141,10 +141,23 @@ export const COMMAND_REGISTRY = [
       "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" },
+      { name: "title", type: "string", description: "Short title for task (-t)" },
+      { name: "prompt", type: "string", description: "Detailed task instructions (-p)" },
+      { name: "prompt-file", type: "string", description: "Read prompt from file (-f)" },
+      { name: "role", type: "string", description: "Specialist role (overseer, bolt, sentinel, janitor, a11y, scribe, spectator, alchemist) (-r)" },
+      { name: "tier", type: "string", description: "Execution tier override (fast | complex)" },
+      { name: "template", type: "string", description: "Task template preset ID" },
+      { name: "depends-on", type: "string", description: "Comma-separated task dependency IDs" },
+      { name: "verify-cmd", type: "string", description: "Verification command override (-v)" },
+      { name: "auto-pr", type: "boolean", description: "Automatically create GitHub PR upon completion" },
+      { name: "require-plan-approval", type: "boolean", description: "Require approval of agent plan before execution" },
+      { name: "repoless", type: "boolean", description: "Execute in repoless sandbox mode" },
+      { name: "interactive", type: "boolean", description: "Launch interactive task wizard (-i)" },
+      { name: "non-interactive", type: "boolean", description: "Bypass interactive prompts and use CLI flags" },
+      { name: "no-interactive", type: "boolean", description: "Alias for --non-interactive" },
+      { name: "yes", type: "boolean", description: "Accept default values non-interactively (-y)" },
+      { name: "dry-run", type: "boolean", description: "Simulate task envelope creation without queueing (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON envelope (-j)" },
     ],
   },
   {
@@ -187,9 +200,14 @@ export const COMMAND_REGISTRY = [
       "agentctl init --tier pro --yes",
     ],
     flags: [
-      { name: "tier", type: "string", description: "Target configuration tier (free, pro, ultra, enterprise)" },
-      { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard" },
-      { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults" },
+      { name: "tier", type: "string", description: "Target configuration tier (free, pro, ultra, enterprise) (-t)" },
+      { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard (-i)" },
+      { name: "non-interactive", type: "boolean", description: "Run non-interactively with defaults" },
+      { name: "no-interactive", type: "boolean", description: "Alias for --non-interactive" },
+      { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults (-y)" },
+      { name: "force", type: "boolean", description: "Force overwrite existing config and assets (-f)" },
+      { name: "dry-run", type: "boolean", description: "Preview plan without writing files (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON manifest (-j)" },
     ],
   },
   {
@@ -333,6 +351,185 @@ export const COMMAND_REGISTRY = [
       { name: "limit", type: "string", description: "Maximum handovers to list" },
     ],
   },
+  {
+    id: "mutate",
+    path: ["mutate"],
+    title: "mutate",
+    description: "Run zero-dependency diff mutation testing harness",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["mutation"],
+    examples: [
+      "agentctl mutate",
+      "agentctl mutate --min-score 80",
+      'agentctl mutate --max-mutants 20 --test-cmd "npm test"',
+    ],
+    flags: [
+      { name: "min-score", type: "string", description: "Target minimum mutation score threshold (0-100)" },
+      { name: "max-mutants", type: "string", description: "Maximum number of mutants to generate and test" },
+      { name: "test-cmd", type: "string", description: "Test command override" },
+      { name: "verify-cmd", type: "string", description: "Alias for test-cmd" },
+      { name: "tier", type: "string", description: "Execution tier (fast | complex)" },
+      { name: "dry-run", type: "boolean", description: "Simulate mutation analysis without executing tests (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON mutation report (-j)" },
+    ],
+  },
+  {
+    id: "coverage",
+    path: ["coverage"],
+    title: "coverage",
+    description: "Run native zero-dependency V8 diff coverage check",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["cov"],
+    examples: [
+      "agentctl coverage",
+      "agentctl coverage --min 80",
+      'agentctl coverage --cmd "node --test"',
+    ],
+    flags: [
+      { name: "min", type: "string", description: "Minimum diff line coverage percentage required" },
+      { name: "cmd", type: "string", description: "Test command override to run with V8 coverage" },
+      { name: "test-cmd", type: "string", description: "Alias for cmd" },
+      { name: "verify-cmd", type: "string", description: "Alias for cmd" },
+      { name: "dry-run", type: "boolean", description: "Simulate coverage collection without running (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON coverage report (-j)" },
+    ],
+  },
+  {
+    id: "gate",
+    path: ["gate"],
+    title: "gate",
+    description: "Run CI security, rules, and stack verification gate",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["audit", "check"],
+    examples: [
+      "agentctl gate",
+      "agentctl gate --mode working-tree",
+      "agentctl gate --fix",
+      "agentctl gate --json",
+    ],
+    flags: [
+      { name: "mode", type: "string", description: "Evaluation mode (working-tree | committed | staged) (-m)" },
+      { name: "tier", type: "string", description: "Enforce specific tier policies (free | pro | ultra | enterprise)" },
+      { name: "allow-protected", type: "boolean", description: "Bypass protected path checks for authorized maintainers" },
+      { name: "fix", type: "boolean", description: "Trigger automated OODA self-repair loop on failure" },
+      { name: "strict-locks", type: "boolean", description: "Enforce strict anti-tampering verification on test files" },
+      { name: "dry-run", type: "boolean", description: "Simulate gate evaluation without persisting evidence (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON gate report (-j)" },
+    ],
+  },
+  {
+    id: "probe",
+    path: ["probe"],
+    title: "probe",
+    description: "Run test flakiness stability probe across N repetitions",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["stability"],
+    examples: [
+      "agentctl probe",
+      "agentctl probe --repeat 10",
+      'agentctl probe --repeat 5 --cmd "pytest"',
+    ],
+    flags: [
+      { name: "repeat", type: "string", description: "Number of probe executions (default: 5)" },
+      { name: "cmd", type: "string", description: "Test command to probe" },
+      { name: "test-cmd", type: "string", description: "Alias for cmd" },
+      { name: "verify-cmd", type: "string", description: "Alias for cmd" },
+      { name: "dry-run", type: "boolean", description: "Preview probe plan without execution (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON probe telemetry (-j)" },
+    ],
+  },
+  {
+    id: "perf",
+    path: ["perf"],
+    title: "perf",
+    description: "Monitor Node.js event loop delay and Big-O performance lag",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["event-loop"],
+    examples: [
+      "agentctl perf",
+      'agentctl perf --max-ms 50 --cmd "npm test"',
+    ],
+    flags: [
+      { name: "max-ms", type: "string", description: "Maximum allowable event loop delay threshold in ms" },
+      { name: "cmd", type: "string", description: "Command to execute during performance monitoring" },
+      { name: "test-cmd", type: "string", description: "Alias for cmd" },
+      { name: "verify-cmd", type: "string", description: "Alias for cmd" },
+      { name: "dry-run", type: "boolean", description: "Preview performance monitoring configuration (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON performance report (-j)" },
+    ],
+  },
+  {
+    id: "dispatch",
+    path: ["dispatch"],
+    title: "dispatch",
+    description: "Dispatch a single task to an AI agent",
+    category: "Operate",
+    mutates: true,
+    risk: "moderate",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["create"],
+    examples: [
+      'agentctl dispatch --prompt "Add retry handling to src/webhook.js"',
+      'agentctl dispatch -p "Fix type errors" --role bolt --tier fast',
+      'agentctl dispatch --prompt-file task.md --dry-run',
+    ],
+    flags: [
+      { name: "prompt", type: "string", description: "Task prompt instructions (-p)" },
+      { name: "prompt-file", type: "string", description: "Read prompt from file (-f)" },
+      { name: "role", type: "string", description: "Specialist role (overseer, bolt, sentinel, janitor, a11y, scribe, spectator, alchemist) (-r)" },
+      { name: "tier", type: "string", description: "Execution tier override (fast | complex)" },
+      { name: "check-premise", type: "boolean", description: "Verify premise locally before dispatching" },
+      { name: "source", type: "string", description: "Jules repository source identifier (-s)" },
+      { name: "branch", type: "string", description: "Starting branch for task execution (-b)" },
+      { name: "repoless", type: "boolean", description: "Dispatch task in repoless execution mode" },
+      { name: "auto-pr", type: "boolean", description: "Automatically create PR upon completion" },
+      { name: "require-plan-approval", type: "boolean", description: "Require human approval for proposed plan" },
+      { name: "dry-run", type: "boolean", description: "Simulate dispatch without sending to provider (-d)" },
+      { name: "json", type: "boolean", description: "Output JSON structured dispatch result (-j)" },
+    ],
+  },
+  {
+    id: "bootstrap",
+    path: ["bootstrap"],
+    title: "bootstrap",
+    description: "Bootstrap zero-test repository with verification oracle",
+    category: "Configure",
+    mutates: true,
+    risk: "moderate",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["bs"],
+    examples: [
+      "agentctl bootstrap",
+      "agentctl bootstrap --force",
+    ],
+    flags: [
+      { name: "force", type: "boolean", description: "Overwrite existing verification oracle or config (-f)" },
+      { name: "dry-run", type: "boolean", description: "Simulate bootstrap without writing files (-d)" },
+      { name: "json", type: "boolean", description: "Output JSON structured bootstrap result (-j)" },
+    ],
+  },
 ];
 
 /**

package/src/ops/next-step.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
+import { isTaskFile } from "../engine.mjs";
 
 /**
  * Work out the one thing the operator should do next.
@@ -66,7 +67,7 @@ export function resolveNextStep(root, env = process.env) {
   const fallbackQueueDir = join(root, ".agent", "queue");
   const queueDir = existsSync(primaryQueueDir) ? primaryQueueDir : fallbackQueueDir;
   const queued = existsSync(queueDir)
-    ? readdirSync(queueDir).filter((f) => f.endsWith(".md") || f.endsWith(".json") || f.endsWith(".yml")).length
+    ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)).length
     : 0;
   if (queued > 0) {
     return {

package/src/provider.mjs

@@ -691,9 +691,9 @@ export function createProvider(spec = "jules", config = {}) {
       }
 
       if (providerSpec.type === "http") {
-        const getSessionUrlTemplate = providerSpec.getSessionUrl || `${providerSpec.url}/${sessionId}`;
+        const getSessionUrlTemplate = ctx.customUrl || providerSpec.getSessionUrl || `${providerSpec.url}/${sessionId}`;
         const urlData = { sessionId, ...ctx };
-        const url = interpolateString(getSessionUrlTemplate, urlData);
+        const url = ctx.customUrl || interpolateString(getSessionUrlTemplate, urlData);
 
         const headerData = { ...urlData, token: rawToken };
         const headers = {};
@@ -720,8 +720,9 @@ export function createProvider(spec = "jules", config = {}) {
           let res;
           try {
             res = await fetch(url, {
-              method: "GET",
+              method: ctx.method || "GET",
               headers,
+              body: ctx.body ? JSON.stringify(ctx.body) : undefined,
               signal: AbortSignal.timeout(timeoutMs),
             });
           } catch (err) {
@@ -816,9 +817,9 @@ export function createProvider(spec = "jules", config = {}) {
       }
 
       if (providerSpec.type === "http") {
-        const approvePlanUrlTemplate = providerSpec.approvePlanUrl || `${providerSpec.url}/${sessionId}:approvePlan`;
+        const approvePlanUrlTemplate = ctx.customUrl || providerSpec.approvePlanUrl || `${providerSpec.url}/${sessionId}:approvePlan`;
         const urlData = { sessionId, ...ctx };
-        const url = interpolateString(approvePlanUrlTemplate, urlData);
+        const url = ctx.customUrl || interpolateString(approvePlanUrlTemplate, urlData);
 
         const headerData = { ...urlData, token: rawToken };
         const headers = {};
@@ -918,6 +919,94 @@ export function createProvider(spec = "jules", config = {}) {
 
       throw new Error(`Unsupported provider type: ${providerSpec.type}`);
     },
+
+    async listSessions(ctx = {}) {
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { sessions: [], raw: {} };
+      if (providerSpec.type === "http") {
+        const baseUrl = providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions";
+        const params = new URLSearchParams();
+        if (ctx.pageSize) params.set("pageSize", String(ctx.pageSize));
+        if (ctx.pageToken) params.set("pageToken", String(ctx.pageToken));
+        const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+        const res = await this.getSession("", { ...ctx, customUrl: url });
+        return {
+          sessions: res?.raw?.sessions || [],
+          nextPageToken: res?.raw?.nextPageToken,
+          raw: res?.raw || {},
+        };
+      }
+      return { sessions: [], raw: {} };
+    },
+
+    async listActivities(sessionId, ctx = {}) {
+      if (!sessionId || typeof sessionId !== "string") {
+        throw new TypeError("listActivities() requires a valid sessionId string");
+      }
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { activities: [], raw: {} };
+      if (providerSpec.type === "http") {
+        const baseUrl = `${providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions"}/${sessionId}/activities`;
+        const params = new URLSearchParams();
+        if (ctx.pageSize) params.set("pageSize", String(ctx.pageSize));
+        if (ctx.pageToken) params.set("pageToken", String(ctx.pageToken));
+        const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+        const res = await this.getSession("", { ...ctx, customUrl: url });
+        return {
+          activities: res?.raw?.activities || [],
+          nextPageToken: res?.raw?.nextPageToken,
+          raw: res?.raw || {},
+        };
+      }
+      return { activities: [], raw: {} };
+    },
+
+    async archiveSession(sessionId, ctx = {}) {
+      if (!sessionId || typeof sessionId !== "string") {
+        throw new TypeError("archiveSession() requires a valid sessionId string");
+      }
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { id: sessionId, archived: true, raw: {} };
+      if (providerSpec.type === "http") {
+        const url = `${providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions"}/${sessionId}:archive`;
+        const res = await this.approvePlan(sessionId, { ...ctx, customUrl: url });
+        return { id: sessionId, archived: true, raw: res?.raw || {} };
+      }
+      return { id: sessionId, archived: true, raw: {} };
+    },
+
+    async deleteSession(sessionId, ctx = {}) {
+      if (!sessionId || typeof sessionId !== "string") {
+        throw new TypeError("deleteSession() requires a valid sessionId string");
+      }
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { id: sessionId, deleted: true, raw: {} };
+      if (providerSpec.type === "http") {
+        const url = `${providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions"}/${sessionId}`;
+        const res = await this.getSession("", { ...ctx, customUrl: url, method: "DELETE" });
+        return { id: sessionId, deleted: true, raw: res?.raw || {} };
+      }
+      return { id: sessionId, deleted: true, raw: {} };
+    },
+
+    async listSources(ctx = {}) {
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { sources: [], raw: {} };
+      if (providerSpec.type === "http") {
+        const baseUrl = "https://jules.googleapis.com/v1alpha/sources";
+        const params = new URLSearchParams();
+        if (ctx.pageSize) params.set("pageSize", String(ctx.pageSize));
+        if (ctx.pageToken) params.set("pageToken", String(ctx.pageToken));
+        const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+        const res = await this.getSession("", { ...ctx, customUrl: url });
+        return {
+          sources: res?.raw?.sources || [],
+          nextPageToken: res?.raw?.nextPageToken,
+          raw: res?.raw || {},
+        };
+      }
+      return { sources: [], raw: {} };
+    },
   };
 }
 
@@ -1038,6 +1127,26 @@ export function createFailoverProvider(providers = ["jules"], config = {}) {
       }
     },
 
+    async listSessions(ctx = {}) {
+      return providerList[0].listSessions(ctx);
+    },
+
+    async listActivities(sessionId, ctx = {}) {
+      return providerList[0].listActivities(sessionId, ctx);
+    },
+
+    async archiveSession(sessionId, ctx = {}) {
+      return providerList[0].archiveSession(sessionId, ctx);
+    },
+
+    async deleteSession(sessionId, ctx = {}) {
+      return providerList[0].deleteSession(sessionId, ctx);
+    },
+
+    async listSources(ctx = {}) {
+      return providerList[0].listSources(ctx);
+    },
+
     validate() {
       return providerList.every((p) => typeof p.validate !== "function" || p.validate());
     },
@@ -1108,5 +1217,25 @@ export function createSyntaxVerifiedProvider(fastProvider, complexProvider, conf
     approvePlan(...args) {
       return fastProvider.approvePlan(...args);
     },
+
+    listSessions(...args) {
+      return typeof fastProvider.listSessions === "function" ? fastProvider.listSessions(...args) : { sessions: [] };
+    },
+
+    listActivities(...args) {
+      return typeof fastProvider.listActivities === "function" ? fastProvider.listActivities(...args) : { activities: [] };
+    },
+
+    archiveSession(...args) {
+      return typeof fastProvider.archiveSession === "function" ? fastProvider.archiveSession(...args) : { id: args[0], archived: true };
+    },
+
+    deleteSession(...args) {
+      return typeof fastProvider.deleteSession === "function" ? fastProvider.deleteSession(...args) : { id: args[0], deleted: true };
+    },
+
+    listSources(...args) {
+      return typeof fastProvider.listSources === "function" ? fastProvider.listSources(...args) : { sources: [] };
+    },
   };
 }