Skip to main content

Background jobs

Start a long command through exec with background:true. With this plugin enabled, completion is delivered automatically: the current turn can finish, the model connection closes, and the user can keep chatting. An OS process-close event triggers delivery; there is no model-driven polling or waiting model call.

{"command":"npm run build","background":true,"timeoutMs":3600000}

exec returns a shellId. The default subscription mode is wake: after that shell completes, one deduplicated follow-up runs in its originating agent core. It waits for the current turn; nearby completions can share a follow-up request. A user interruption pauses queued follow-ups until the user continues. Agent follow-ups use agent provenance and normal model/token/permission limits.

The completion message contains only shell ID, reason and exit code. It never includes command output, command text or environment variables. The agent can read output with exec_output and stop a process with exec_kill, through their usual permission checks. Process output remains untrusted data.

Activate​

Requires the host background-job/follow-up contracts introduced in event catalog 0.20.0. Use this source checkout or a host release containing these contracts; the older v0.4.0 distribution needs a host update as well as the new plugin.

/extensions install background-jobs@agent-compositor --project
/extensions enable background-jobs --project
/reload

Like other filesystem plugins, this package starts inactive. Existing exec background execution remains available independently of this plugin.

Subscriptions​

The background_jobs tool manages subscriptions; it does not spawn commands or kill them outside the normal shell tools.

{"action":"list"}
{"action":"status","id":"<shellId>"}
{"action":"subscribe","id":"<shellId>","mode":"notify"}
{"action":"unsubscribe","id":"<shellId>"}

Lists return the latest 20 job summaries by default, with total and truncated. Use limit (1..128) when a larger history is needed. Output buffers are excluded.

notify posts a user notification without starting a model request. Unsubscribe stops future delivery; it does not stop the command or undo an already dispatched follow-up. Cancelled commands only notify, rather than automatically restarting an agent that the user stopped. Timeouts/nonzero exits are reported truthfully and can wake the agent to handle failure. Subscribing after a fast completion replays its metadata; repeated subscriptions do not duplicate a delivered completion.

Configure shared or private project settings through background-jobs.json:

{"autoSubscribe":true,"mode":"wake"}

Set autoSubscribe:false for manual subscriptions, or mode:"notify" to make notification-only delivery the default. Invalid configuration is reported.

Ownership and limits​

Jobs belong to the live originating core, including when several agents share a project. Other cores cannot read or kill them by guessing a shell ID. The host allows 16 concurrent shells per core, approximately 128 retained completed jobs, and a deadline of 1..86400000 ms. The exec default deadline is 120000 ms; set a larger value for a long build. Each stdout/stderr buffer retains its last 512 KiB and reports truncation. These shells provide host execution, not an OS sandbox.

Subscription history retains 128 entries in version-1 session storage. Reload reattaches pending subscriptions to live jobs. Invalid/unknown state is rebuilt from live host metadata; commands are never replayed to reconstruct state. A fresh process cannot recover an OS child it no longer owns: stale pending IDs become unavailable. There is no historical release migration claim for 0.1.0.

Disabling/reloading the plugin revokes its callbacks and queued follow-ups. Host-owned commands continue independently; a reload restores subscriptions to live commands. Use exec_kill to cancel one. Session clear/end and application close stop/drain owned process groups and discard pending subscriptions. Revoking an attached workspace stops its running commands. Single-shot headless runs close their jobs when the app exits; this feature does not keep a daemon alive.

Stopping the agent pauses accepted queued wakes until the next explicit prompt, whether a job completed before or after Stop. It discards ordinary queued user prompts. An already running follow-up is interrupted and is not automatically restarted. A delivered wake receipt means the host accepted the follow-up, not that the model has reviewed or completed the job. Conversation clear and application close discard pending wakes; new jobs after clear can wake the new conversation normally.

Delivery/storage errors are surfaced rather than retried in a model loop. Wake receipts are bounded and deduplicated in the live core; process output is fetched only when requested. No success/speed/token-efficiency claim about every model follows from the deterministic delivery mechanism.