pi-jobs

Local pi package for the supervised job runtime exposed through job, jobs, and jobs_plan.

This repository is the source of truth for job-related pi work. Do not maintain the live runtime copy by syncing from pi-tools anymore.

What lives here

• extensions/jobs/ - the job extension and supervisor runtime modules
• extensions/jobs/prompts/ - dynamically loaded guidance, tool prompt text, and worker prompt templates for easy local debugging
• tests/jobs/ - focused Node tests for status, audit artifacts, supervisor behavior, retry, throttle, UI helpers, and smoke fixtures
• scripts/jobs-audit-smoke.sh - end-to-end temp-workspace smoke validation
• docs/specs/ - job design specs, including jobs-supervisor-v3.md
• docs/plans/ - implementation plans for job runtime work

Runtime model

Jobs Supervisor V3 treats each job as a supervised worker attempt.

• The root process owns planning, scheduling, retry classification, acceptance checks, and synthesis.
• Use job workers narrowly: not for ordinary main-quest work the root agent can handle well, not when parallelism is unnecessary, not when workers could touch the same files or need tight shared state, and not when the root agent should directly learn/debug the process details.
• Use job workers when the user explicitly requests parallel jobs/agents, when the work would consume lots of context and only final deliverables matter, or for separable research/reporting/audit/review directions.
• Fan-out is explicit. Prefer jobs_plan: a compact matrix + promptTemplate + acceptanceTemplate payload that the extension expands locally into N supervised jobs. Inline jobs is a small-batch escape hatch (<=4 jobs, <=8000 prompt bytes) and rejects oversized payloads with a pointer to jobs_plan.
• Concurrency is explicit when capped: omitting concurrency runs every supplied leaf job concurrently; root agents should split large batches into explicit jobs_plan waves of about 4-6 jobs unless the user asks for full concurrency. Dynamic throttling is opt-in via throttle.enabled: true.
• Each worker is a full child pi --mode json -p --session <attempt>/session.jsonl process with its own session/compaction boundary; the parent only supervises stdout JSONL, artifacts, and the structured report protocol.
• Workers handle recoverable work-level errors themselves and should submit job-report.json via the child-only job_report tool or file fallback when practical.
• Parent retry is reserved for launch/session/provider transient failures and no-signal worker incompletion.
• success requires runtime success, acceptance pass when an acceptance contract exists, either a completed report or visible terminal completion when no acceptance contract exists, and finalized audit artifacts.
• Legacy JOB_STATUS markers are only warning signals; they are not a completion protocol.

Batch artifacts live under:

.pi/jobs/<batchId>/
  batch.json
  events.jsonl
  summary.md
  plan.json                  # only present when jobs_plan was used
  jobs/<jobId>.json
  attempts/<jobId>/attempt-N/

.pi/jobs/** is a sensitive audit directory and may include full prompts, child sessions, stdout/stderr, and local paths.

Settings UI

Use /jobs-settings to inspect or update the focused policy controls. File-only settings live in .pi/jobs-settings.json:

{
  "workerExtensions": {
    "include": [
      "./extensions/provider-oauth.ts",
      "npm:@example/pi-worker-provider"
    ]
  }
}

• report policy: fixed default, with acceptance report is optional audit evidence; without acceptance require report or visible terminal completion;
• jobs_plan wave guidance: default enabled, about 4-6 jobs per explicit wave for large batches;
• sync-first guidance: default enabled, keeps the extension oriented around blocking parent-tool runs and avoids scheduler/background/steer/resume complexity;
• worker extensions: worker-only allowlist; job agents load job-worker-runtime.ts plus only workerExtensions.include entries. The default empty list loads no regular/discovered extensions into job agents, so provider, OAuth, or custom-model extensions required by worker models must be listed here. Nested jobs remain blocked by the PI_CHILD_TYPE=job-worker guard even when the jobs extension is allowlisted.

Artifact UI

Use /jobs-ui to navigate persisted artifacts:

/jobs-ui
/jobs-ui help
/jobs-ui <batchId>
/jobs-ui <batchId> job <jobId>
/jobs-ui <batchId> attempt <jobId> <attemptId|latest>
/jobs-ui rerun failed <batchId>
/jobs-ui rerun acceptance-failed <batchId>
/jobs-ui rerun provider-transient <batchId>
/jobs-ui rerun selected <batchId> <jobId> [jobId...]

The UI is artifact-first: batch detail groups failures, job detail shows acceptance/report state, attempt detail shows runtime fields, thinking/tool activity, and artifact paths, and rerun preparation preserves parent batch provenance. Live job / jobs updates also show recent per-job thinking/activity lines while workers run.

Load it in pi

Install the published package from npm:

pi install npm:@capyup/pi-jobs

For local development, add this repository as a local package in ~/.pi/agent/settings.json, or install it directly:

pi install /Users/lucas/Developer/pi-jobs

Pi will load the extension from:

• extensions/jobs/index.ts

Prompt and template text is intentionally kept outside TypeScript under extensions/jobs/prompts/. Those files are dynamically loaded from disk with import.meta.url-relative paths, so local edits can be tested by restarting/reloading pi without rebuilding a bundled prompt string.

Local validation

cd /Users/lucas/Developer/pi-jobs
npm run test
npm run smoke

Key docs

• docs/specs/jobs-supervisor-v3.md - authoritative V3 design history
• docs/job-failure-audit-2026-04-26.md - incident audit and V3 replacement notes
• extensions/jobs/README.md - tool usage and artifact overview