long-running-jobs

Long-Running Jobs

Some commands take minutes or hours. Rather than blocking on them, spawn them with async_mode=True. The harness owns the process — captures stdout/stderr to files, surfaces the job in the web UI, and fires a completion event back into the agent's queue when the subprocess exits.

The completion event is a fresh turn: journal, memory blocks, and recent messages get rebuilt from disk. There is no in-context state to preserve. Whatever you need to remember when the job finishes has to live somewhere durable (journal entry, state file, the command itself) before you spawn.

When to Use This

USE when:

• Build commands (cargo build, npm run build, make)
• Test suites that take more than ~30 seconds
• Data processing, model training, large downloads
• Deployments or migrations
• Sub-agent invocations (acpx, codex exec, etc.)
• Any command where you want to keep working while it runs

DON'T USE when:

• Quick commands (< 30s) — just call shell normally and wait
• Commands you need the result of immediately (chain into next reasoning step)
• Interactive commands that need stdin

The Canonical Pattern

shell(command="cargo build --release", async_mode=True)

That's it. The harness:

1. Spawns the command in its own process group, file-backs stdout/stderr
2. Returns immediately with Spawned async job j_abc123 (pid 12345)
3. Surfaces the job in the web UI with a live status indicator
4. When the subprocess exits, fires a shell_job_complete event that wakes the agent with a prompt containing job_id, command, exit_code, elapsed, and the tail (~4KB) of each stream

You keep working in the current turn. The completion event arrives as a separate wake-up.

Inspecting Running Jobs

While a job is running you have three options — and one of them isn't a tool call:

• Web UI — the user can see running jobs at a glance with elapsed time and status. If the user's watching, they already know.
• shell_jobs_list() — every job the registry knows about (running + recently finished), with job_id, pid, status, elapsed_seconds, and seconds_since_last_signal.
• shell_job_output(job_id, tail_lines=N, stream="stdout"|"stderr"|"both") — tail current output without waiting for completion. Useful for sanity-checking that a build is making progress vs hung.