jules-orchestrator-kit 0.51.0 → 0.52.0

package/README.md

@@ -143,7 +143,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Fail-Closed Security & Secret Redaction:** Evaluates explicit Deny rules before Allow rules against canonicalized, case-folded paths. Redacts high-entropy keys and base64-encoded credentials (such as Kubernetes `Secret` manifests).
 * **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors, with a `node --check` syntax-verification gate that transparently escalates a FAST-tier result to the primary provider if it left broken JS on disk.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **790 unit tests across 91 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **797 unit tests across 91 suites passing in < 10.0s**.
 
 <br/>
 
@@ -165,6 +165,9 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | `dispatch` | `agentctl dispatch [<prompt>] [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--author <name>] [--check-premise] [--auto-pr] [--repoless] [--dry-run]` | Dispatches autonomous task to the active provider with pre-flight idempotency checks, payload limits, and role prompt resolution. `--dry-run` stops short of the provider call and reports itself as a rehearsal rather than a dispatch. | `0` (Dispatched), `1` (Error) |
 | `plan approve` | `agentctl plan approve <sessionId> [--dry-run] [--json]` | Approves pending execution plan for an active Jules session (`:approvePlan`) with automatic 404/503 retry backoff. | `0` (Approved), `1` (Error) |
 | `session get` | `agentctl session get <sessionId> [--dry-run] [--json]` | Retrieves live session lifecycle state from provider REST API with token rotation. | `0` (Fetched), `1` (Error) |
+| `patch` | `agentctl patch <sessionId> [--apply] [--save <path>] [--json]` | Extracts raw git diff patch from a completed Jules session and tests or applies it locally with `git apply --check` safety. | `0` (Clean/Applied), `1` (Conflict/Error) |
+| `retry` | `agentctl retry <sessionId> [--role <role>] [--with-failure] [--json]` | Fetches error traces and activity logs from a failed session and synthesizes a targeted OODA retry dispatch. | `0` (Dispatched), `1` (Error) |
+| `prune` | `agentctl prune [--age 7d] [--state <state>] [--delete] [--yes] [--json]` | Queries and batch-archives or deletes stale/completed sessions via Jules v1alpha API to keep workspaces clean. | `0` (Cleaned) |
 | `pr harvest` | `agentctl pr harvest [--tier r0,r1] [--limit <n>] [--auto] [--allow-no-checks] [--dry-run]` | Discovers open agent PRs, evaluates CI checks & risk tiers, and auto-squashes green low-risk changes autonomously. A PR reporting **no** CI checks is skipped unless `--allow-no-checks` is passed, and an unavailable changed-file list blocks rather than classifying as low risk. | `0` (Triaged/Merged), `1` (Error) |
 | `doctor` | `agentctl doctor [--json]` | Diagnostic DAG check runner & automated transactional self-repair engine. | `0` (Healthy), `1` (Failures) |
 | `queue` | `agentctl queue [--dag] [--concurrency <n>] [--dry-run] [--json]` | Consumes and executes task envelopes in `.agent/jules-queue/` with Kahn's DAG dependency resolution. Non-task files (manifests, `README.md`) are skipped, and `--dry-run` previews without moving anything. | `0` (Complete) |

package/bin/agentctl.mjs

@@ -69,6 +69,9 @@ Commands:
   resume                Resume warm session with human response (--response "<text>")
   plan approve <id>     Approve pending plan for a Jules session (:approvePlan)
   session get <id>      Retrieve remote session status from provider API
+  patch <id>            Extract and test/apply git patch from a Jules session (--apply, --save)
+  retry <id>            Retry failed session with automated failure-trace injection (--role)
+  prune                 Batch-archive or delete stale sessions via Jules API (--age 7d, --yes)
   pr harvest            Triage, verify CI, and auto-merge low-risk agent PRs (--auto, --tier r0,r1)
   escalate              Dispatch or manage webhook escalation incidents (--flush, --status, --clear)
   flaky                 Manage Wilson-quarantined tests and dispatch healing swarm (status | heal | reset)
@@ -720,6 +723,147 @@ async function main() {
       break;
     }
 
+    case "patch": {
+      const { applySessionPatch, resolveRoot } = await import("../index.mjs");
+      const { values, positionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          session: { type: "string", short: "s" },
+          apply: { type: "boolean", short: "a" },
+          save: { type: "string" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const sessionId = values.session || positionals[0] || positionals[1];
+      if (!sessionId) {
+        console.error("❌ Error: Missing required session ID. Usage: agentctl patch <session_id> [--apply] [--save <path>]");
+        process.exit(1);
+      }
+
+      const root = resolveRoot();
+      const res = await applySessionPatch(sessionId, {
+        root,
+        apply: Boolean(values.apply),
+        save: values.save,
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+      } else if (!res.ok) {
+        console.error(`\n❌ Failed to extract or apply patch for session ${sessionId}:`);
+        console.error(`   ${res.error || "Unknown error"}\n`);
+      } else {
+        console.log(`\n📦 Session Git Patch (${sessionId})`);
+        console.log(`------------------------------------------------------------------`);
+        console.log(`  Modified Files      : ${res.files && res.files.length > 0 ? res.files.join(", ") : "None"}`);
+        console.log(`  git apply --check   : ${res.checkPassed ? "✅ CLEAN PASS" : "❌ CONFLICT"}`);
+        console.log(`  Applied to Disk     : ${res.patchApplied ? "✅ APPLIED" : "DRY-RUN ONLY (--apply to write)"}`);
+        if (values.save) {
+          console.log(`  Saved to File       : ${values.save}`);
+        }
+        if (!values.apply && !values.save && res.patch) {
+          console.log(`\n--- Patch Content ---\n${res.patch}\n---------------------\n`);
+        }
+      }
+
+      process.exit(res.ok ? 0 : 1);
+      break;
+    }
+
+    case "retry": {
+      const { retrySession, resolveRoot } = await import("../index.mjs");
+      const { values, positionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          session: { type: "string", short: "s" },
+          role: { type: "string", short: "r" },
+          title: { type: "string", short: "t" },
+          "without-failure": { type: "boolean" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const sessionId = values.session || positionals[0] || positionals[1];
+      if (!sessionId) {
+        console.error("❌ Error: Missing required session ID. Usage: agentctl retry <session_id> [--role <role>]");
+        process.exit(1);
+      }
+
+      const root = resolveRoot();
+      const res = await retrySession(sessionId, {
+        root,
+        role: values.role,
+        title: values.title,
+        withFailure: values["without-failure"] ? false : true,
+        dryRun: Boolean(values["dry-run"]),
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`\n🔄 Session Retry Dispatched!`);
+        console.log(`------------------------------------------------------------------`);
+        console.log(`  Original Session    : ${res.originalSessionId}`);
+        console.log(`  New Session ID      : ${res.newSession?.id || "N/A"}`);
+        console.log(`  Failure Trace Added : ${res.failureReason ? "YES" : "NO"}`);
+        console.log(`------------------------------------------------------------------\n`);
+      }
+
+      process.exit(res.ok ? 0 : 1);
+      break;
+    }
+
+    case "prune": {
+      const { pruneSessions, resolveRoot } = await import("../index.mjs");
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          age: { type: "string", short: "a" },
+          state: { type: "string", short: "s" },
+          delete: { type: "boolean" },
+          "dry-run": { type: "boolean", short: "d" },
+          yes: { type: "boolean", short: "y" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const root = resolveRoot();
+      const dryRun = values["dry-run"] || (!values.yes && !values.delete);
+      const res = await pruneSessions({
+        root,
+        age: values.age || "7d",
+        state: values.state,
+        delete: Boolean(values.delete),
+        dryRun,
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`\n🧹 Session Pruning Report (${dryRun ? "DRY RUN" : "EXECUTED"})`);
+        console.log(`------------------------------------------------------------------`);
+        console.log(`  Filter Age Cutoff   : ${values.age || "7d"}`);
+        console.log(`  Filter Target State : ${values.state || "ALL"}`);
+        console.log(`  Matched Sessions    : ${res.matchedCount}`);
+        console.log(`  Archived / Deleted  : ${res.archivedCount}`);
+        console.log(`------------------------------------------------------------------`);
+        for (const s of res.sessions) {
+          console.log(`  - [${s.action}] ${s.id} (State: ${s.state || "UNKNOWN"})`);
+        }
+        if (dryRun && res.matchedCount > 0) {
+          console.log(`\n💡 Re-run with --yes to archive matched sessions.\n`);
+        }
+      }
+
+      process.exit(0);
+      break;
+    }
+
     case "assert": {
       const { runAssertion, parseYaml } = await import("../index.mjs");
       const { values } = parseArgs({

package/index.mjs

@@ -229,3 +229,13 @@ export {
   getHandoverDir,
   HandoverError,
 } from "./src/ops/handover.mjs";
+
+// Jules Power-User Session Operations & Lifecycle Engine
+export {
+  extractSessionPatch,
+  applySessionPatch,
+  retrySession,
+  pruneSessions,
+  parseAgeDuration,
+} from "./src/session-ops.mjs";
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for Google Jules (jules) autonomous agents.",
   "repository": {
     "type": "git",

package/src/mcp.mjs

@@ -8,6 +8,13 @@ import { reapOrphanedIntents, reapStaleMutexDirs } from "./journal.mjs";
 import { readTelemetry } from "./telemetry.mjs";
 import { ProgressBus } from "./mcp-progress.mjs";
 import { KIT_VERSION } from "./version.mjs";
+import { createProvider } from "./provider.mjs";
+import {
+  extractSessionPatch,
+  applySessionPatch,
+  retrySession,
+  pruneSessions,
+} from "./session-ops.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
@@ -196,6 +203,113 @@ export const MCP_TOOLS = [
       required: ["trigger", "solution"],
     },
   },
+  {
+    name: "jules_list_sessions",
+    description: "List remote Jules coding sessions with optional pagination and state filtering.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageSize: { type: "number", description: "Maximum number of sessions to return (default 50)" },
+        pageToken: { type: "string", description: "Page token for cursor pagination" },
+      },
+    },
+  },
+  {
+    name: "jules_list_activities",
+    description: "List execution activities, logs, and error outputs for a specific Jules session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID" },
+        pageSize: { type: "number", description: "Maximum number of activities to return" },
+        pageToken: { type: "string", description: "Page token for pagination" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_get_session_output",
+    description: "Extract the git diff patch, pull request metadata, and changed files from a Jules session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_archive_session",
+    description: "Archive a Jules coding session to clean up the dashboard.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID to archive" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_delete_session",
+    description: "Permanently delete a Jules coding session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID to delete" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_retry_session",
+    description: "Retry a failed Jules session by extracting failure diagnostics and dispatching a new OODA repair session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Original failed Jules session ID" },
+        role: { type: "string", description: "Optional specialist role override" },
+        withFailure: { type: "boolean", description: "Include previous failure diagnostic in retry prompt (default true)" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_apply_patch",
+    description: "Extract and apply a Jules session's git patch to the local workspace with git apply safety verification.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID to extract patch from" },
+        apply: { type: "boolean", description: "If true, applies the patch; if false, runs git apply --check dry-run" },
+        save: { type: "string", description: "Optional file path to save raw patch diff to" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_list_sources",
+    description: "List connected GitHub repository sources available to the Jules account.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageSize: { type: "number", description: "Maximum number of sources to return" },
+        pageToken: { type: "string", description: "Page token for pagination" },
+      },
+    },
+  },
+  {
+    name: "jules_prune_sessions",
+    description: "Batch-archive or prune old/completed Jules sessions matching age and state filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        age: { type: "string", description: "Age cutoff string (e.g. '7d', '24h', '30m')" },
+        state: { type: "string", description: "Target session state to filter (e.g. 'FAILED', 'COMPLETED')" },
+        dryRun: { type: "boolean", description: "If true, previews sessions without modifying (default true)" },
+        delete: { type: "boolean", description: "If true, permanently deletes instead of archiving" },
+      },
+    },
+  },
 ];
 
 export async function handleMcpRequest(request, opts = {}) {
@@ -431,6 +545,169 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      if (toolName === "jules_list_sessions") {
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.listSessions({ root, pageSize: args.pageSize, pageToken: args.pageToken });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, ...res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_list_activities") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.listActivities(args.sessionId, { root, pageSize: args.pageSize, pageToken: args.pageToken });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, ...res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_get_session_output") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const res = await extractSessionPatch(args.sessionId, { root, config });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_archive_session") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.archiveSession(args.sessionId, { root });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, ...res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_delete_session") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.deleteSession(args.sessionId, { root });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, ...res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_retry_session") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const res = await retrySession(args.sessionId, {
+          root,
+          config,
+          role: args.role,
+          withFailure: args.withFailure !== false,
+        });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_apply_patch") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const res = await applySessionPatch(args.sessionId, {
+          root,
+          config,
+          apply: Boolean(args.apply),
+          save: args.save,
+        });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_list_sources") {
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.listSources({ root, pageSize: args.pageSize, pageToken: args.pageToken });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, ...res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_prune_sessions") {
+        const res = await pruneSessions({
+          root,
+          config,
+          age: args.age || "7d",
+          state: args.state,
+          delete: Boolean(args.delete),
+          dryRun: args.dryRun !== false,
+        });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
       return {
         jsonrpc: "2.0",
         id,

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: [] };
+    },
   };
 }

package/src/session-ops.mjs

@@ -0,0 +1,312 @@
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createProvider } from "./provider.mjs";
+import { loadConfig, resolveRoot } from "./config.mjs";
+import { redactSecrets } from "./security.mjs";
+
+/**
+ * Parses human-readable duration strings (e.g. "7d", "24h", "30m", "60s") into milliseconds.
+ *
+ * @param {string|number} duration
+ * @returns {number} Milliseconds
+ */
+export function parseAgeDuration(duration) {
+  if (typeof duration === "number" && Number.isFinite(duration)) return duration;
+  if (!duration || typeof duration !== "string") return 0;
+  const match = duration.trim().match(/^(\d+(?:\.\d+)?)\s*([smhdw])$/i);
+  if (!match) {
+    const num = Number(duration);
+    return Number.isFinite(num) ? num : 0;
+  }
+  const val = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "s": return val * 1000;
+    case "m": return val * 60 * 1000;
+    case "h": return val * 60 * 60 * 1000;
+    case "d": return val * 24 * 60 * 60 * 1000;
+    case "w": return val * 7 * 24 * 60 * 60 * 1000;
+    default: return 0;
+  }
+}
+
+/**
+ * Extracts git diff patch, PR details, and modified files from a Jules session.
+ *
+ * @param {string} sessionId
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, id: string, patch: string, pr: object|null, files: string[], error?: string }>}
+ */
+export async function extractSessionPatch(sessionId, opts = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new TypeError("extractSessionPatch requires a valid sessionId string");
+  }
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const provider = opts.provider || createProvider(config.provider || "jules", config);
+
+  const session = await provider.getSession(sessionId, opts);
+  const activitiesRes = await provider.listActivities(sessionId, opts).catch(() => ({ activities: [] }));
+  const activities = activitiesRes.activities || [];
+
+  let patch = "";
+  let pr = null;
+  const files = new Set();
+
+  // 1. Inspect session outputs
+  const outputs = session?.raw?.outputs || session?.outputs || [];
+  for (const out of outputs) {
+    if (out.pullRequest) {
+      pr = out.pullRequest;
+    }
+    if (out.gitPatch || out.patch || out.diff) {
+      patch = out.gitPatch || out.patch || out.diff;
+    }
+  }
+
+  // 2. Inspect activity artifacts and logs if patch wasn't in top-level output
+  for (const act of activities) {
+    if (act.pullRequest) pr = act.pullRequest;
+    if (act.gitPatch || act.patch || act.diff) {
+      patch = patch || act.gitPatch || act.patch || act.diff;
+    }
+    if (act.artifacts && Array.isArray(act.artifacts)) {
+      for (const art of act.artifacts) {
+        if (art.patch || art.diff || (typeof art.content === "string" && art.content.startsWith("diff --git"))) {
+          patch = patch || art.patch || art.diff || art.content;
+        }
+        if (art.path || art.filename) {
+          files.add(art.path || art.filename);
+        }
+      }
+    }
+    if (act.changedFiles && Array.isArray(act.changedFiles)) {
+      act.changedFiles.forEach((f) => files.add(f));
+    }
+  }
+
+  // Extract changed files from patch headers if files set is empty
+  if (patch && files.size === 0) {
+    const fileMatches = patch.matchAll(/^diff --git a\/(.+?) b\/(.+?)$/gm);
+    for (const m of fileMatches) {
+      files.add(m[2]);
+    }
+  }
+
+  return {
+    ok: Boolean(patch || pr),
+    id: sessionId,
+    patch: patch ? (patch.endsWith("\n") ? patch : patch + "\n") : "",
+    pr,
+    files: Array.from(files),
+    rawSession: session.raw,
+  };
+}
+
+/**
+ * Applies a Jules session's patch to the local working tree with git apply safety checks.
+ *
+ * @param {string} sessionId
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, patchApplied: boolean, checkPassed: boolean, patch: string, files: string[], error?: string }>}
+ */
+export async function applySessionPatch(sessionId, opts = {}) {
+  const root = opts.root || resolveRoot();
+  const res = await extractSessionPatch(sessionId, { ...opts, root });
+
+  if (!res.patch) {
+    return {
+      ok: false,
+      patchApplied: false,
+      checkPassed: false,
+      patch: "",
+      files: res.files || [],
+      error: "No git patch found in session output or activities.",
+    };
+  }
+
+  if (opts.save) {
+    const savePath = resolve(root, opts.save);
+    writeFileSync(savePath, res.patch, "utf-8");
+  }
+
+  // 1. Dry run: git apply --check
+  const checkRes = spawnSync("git", ["apply", "--check", "-"], {
+    cwd: root,
+    input: res.patch,
+    encoding: "utf-8",
+  });
+
+  if (checkRes.status !== 0) {
+    const stderr = (checkRes.stderr || "").trim();
+    return {
+      ok: false,
+      patchApplied: false,
+      checkPassed: false,
+      patch: res.patch,
+      files: res.files,
+      error: `git apply --check failed: ${stderr || "Patch does not cleanly apply to working directory"}`,
+    };
+  }
+
+  // 2. If apply requested, execute git apply
+  if (opts.apply) {
+    const applyRes = spawnSync("git", ["apply", "-"], {
+      cwd: root,
+      input: res.patch,
+      encoding: "utf-8",
+    });
+
+    if (applyRes.status !== 0) {
+      const stderr = (applyRes.stderr || "").trim();
+      return {
+        ok: false,
+        patchApplied: false,
+        checkPassed: true,
+        patch: res.patch,
+        files: res.files,
+        error: `git apply failed: ${stderr}`,
+      };
+    }
+
+    return {
+      ok: true,
+      patchApplied: true,
+      checkPassed: true,
+      patch: res.patch,
+      files: res.files,
+    };
+  }
+
+  return {
+    ok: true,
+    patchApplied: false,
+    checkPassed: true,
+    patch: res.patch,
+    files: res.files,
+  };
+}
+
+/**
+ * Gathers failure context and error output from a failed session and synthesizes a new OODA retry session.
+ *
+ * @param {string} sessionId
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, originalSessionId: string, newSession: object, failureReason: string }>}
+ */
+export async function retrySession(sessionId, opts = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new TypeError("retrySession requires a valid sessionId string");
+  }
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const provider = opts.provider || createProvider(config.provider || "jules", config);
+
+  const session = await provider.getSession(sessionId, opts);
+  const activitiesRes = await provider.listActivities(sessionId, opts).catch(() => ({ activities: [] }));
+  const activities = activitiesRes.activities || [];
+
+  // Extract failure diagnostics
+  const errors = [];
+  for (const act of activities) {
+    if (act.error) errors.push(typeof act.error === "string" ? act.error : JSON.stringify(act.error));
+    if (act.executionOutput && (act.exitCode !== 0 || act.status === "FAILED")) {
+      errors.push(act.executionOutput);
+    }
+  }
+
+  const rawPrompt = session?.raw?.prompt || session?.prompt || "";
+  const title = session?.raw?.title || `Retry of Session ${sessionId}`;
+  const failureReason = errors.join("\n").slice(0, 4000) || "Previous session did not complete cleanly.";
+
+  let synthesizedPrompt = rawPrompt;
+  if (opts.withFailure !== false && failureReason) {
+    synthesizedPrompt = `${rawPrompt}\n\n[PREVIOUS_ATTEMPT_FAILURE_DIAGNOSTIC]\nThe previous automated session failed with the following error output:\n\`\`\`\n${redactSecrets(failureReason)}\n\`\`\`\nPlease analyze this failure, fix the root cause, and ensure all tests pass.\n`;
+  }
+
+  const source = session?.raw?.sourceContext?.source || opts.source;
+  const branch = session?.raw?.sourceContext?.githubRepoContext?.startingBranch || opts.branch || "main";
+
+  const dispatchRes = await provider.dispatch(
+    {
+      title: opts.title || title,
+      prompt: synthesizedPrompt,
+      role: opts.role,
+      source,
+      branch,
+    },
+    opts
+  );
+
+  return {
+    ok: true,
+    originalSessionId: sessionId,
+    newSession: dispatchRes,
+    failureReason,
+  };
+}
+
+/**
+ * Queries and batch-archives old or completed Jules sessions based on age and state filters.
+ *
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, matchedCount: number, archivedCount: number, sessions: Array<{ id: string, state: string, createTime: string, action: string }> }>}
+ */
+export async function pruneSessions(opts = {}) {
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const provider = opts.provider || createProvider(config.provider || "jules", config);
+
+  const listRes = await provider.listSessions({ ...opts, pageSize: opts.pageSize || 100 });
+  const allSessions = listRes.sessions || [];
+
+  const maxAgeMs = opts.age ? parseAgeDuration(opts.age) : 0;
+  const now = Date.now();
+  const targetState = opts.state ? String(opts.state).toUpperCase() : null;
+
+  const matched = [];
+  for (const s of allSessions) {
+    const state = (s.state || s.status || "UNKNOWN").toUpperCase();
+    if (targetState && state !== targetState) continue;
+
+    if (maxAgeMs > 0) {
+      const timeStr = s.createTime || s.updateTime;
+      const sessionTime = timeStr ? new Date(timeStr).getTime() : 0;
+      if (sessionTime > 0 && now - sessionTime < maxAgeMs) {
+        continue; // Session is newer than the cutoff age
+      }
+    }
+
+    matched.push(s);
+  }
+
+  const results = [];
+  for (const s of matched) {
+    const id = s.id || (s.name ? s.name.split("/").pop() : "");
+    if (!id) continue;
+
+    if (opts.dryRun) {
+      results.push({ id, state: s.state || s.status, createTime: s.createTime, action: "DRY_RUN_SKIP" });
+    } else {
+      try {
+        if (opts.delete) {
+          await provider.deleteSession(id, opts);
+          results.push({ id, state: s.state || s.status, createTime: s.createTime, action: "DELETED" });
+        } else {
+          await provider.archiveSession(id, opts);
+          results.push({ id, state: s.state || s.status, createTime: s.createTime, action: "ARCHIVED" });
+        }
+      } catch (err) {
+        results.push({ id, state: s.state || s.status, createTime: s.createTime, action: `ERROR: ${err.message}` });
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    matchedCount: matched.length,
+    archivedCount: results.filter((r) => r.action === "ARCHIVED" || r.action === "DELETED").length,
+    sessions: results,
+  };
+}