feat(M2): Background Job Manager

2026-05-19 20:29:35 -05:00
parent 9c7d9cbaee
commit e7b01612c8
3 changed files with 107 additions and 1 deletions
@@ -45,6 +45,35 @@ The skill searches for the following clients in order:

 Run `list` to see which clients are installed and their resolved versions.

+## Background Jobs
+
+For long-running or fire-and-forget tasks, use the programmatic job API instead of `exec`:
+
+```typescript
+import { startJob, getJob, cancelJob, listJobs, cleanupJobs } from "./src/jobs.js";
+
+// Start a detached job
+const job = await startJob("codex", "refactor auth module", { timeoutMs: 300_000 });
+console.log(job.id); // e.g. "a1b2c3d4..."
+console.log(job.status); // "running"
+
+// Poll for completion
+const latest = getJob(job.id);
+console.log(latest.status); // "running" | "completed" | "failed" | "timed_out" | "cancelled"
+
+// Cancel a running job
+cancelJob(job.id);
+
+// List all jobs (newest first)
+const jobs = listJobs(); // Job[]
+const running = listJobs({ filter: "running" });
+
+// Clean up job files older than 24 hours (default)
+cleanupJobs({ maxAgeMs: 24 * 60 * 60 * 1000 });
+```
+
+Job files are stored under `~/.openclaw/ai-cli-dispatch/jobs/<jobId>.json` and include stdout, stderr, exit code, and timing.
+
 ## Output Rules

 - Normal JSON output redacts local file paths and credential metadata.