Background jobs

Some work takes longer than a chat turn. DataMind Oda starts it in the background as a job, keeps working with you, and collects the result when the job finishes. This page covers where jobs appear, how they are read, waited for and stopped, and how you learn that one finished. How jobs are owned, kept and limited is in Background jobs: limits and lifecycle.

What runs as a background job

Long work becomes a job of the chat that started it, whichever kind it is:

A helper agent Oda sends on a one-shot background run. Its start names the job, started background subagent job <id>, and its result waits in that job. See Background subagents and job collection.
A workflow started in the background, fanning work out across helper agents. Its return value arrives with the completion notice. See Workflows.
A command Oda runs in the background, or one that reaches its time limit and moves there. See Shell commands.

Oda manages every kind through the same three job tools: job_output reads a job, job_list lists the chat's jobs, and job_kill stops one. In the chat these calls appear as steps such as Read output from background job <id>, List background jobs and Kill background job <id>.

Where jobs appear

In Activity, a chat's background processes gather under a Background jobs list in the Running band, and the Activity pill at the top of the chat counts what is under way, in forms such as Activity: 1 running. Activity covers the panel, and Activity rows and actions takes one row apart.
A listing carries one line per job, in the form <id> [<kind>] <status> - <label>, for example bash-1 [bash] running - pnpm test. With no jobs, it answers (no background jobs).

Reading a job's output

A read returns the output that is new since the last read and closes with the job's current state, as [status: <status>]; with nothing new to add, it answers (no new output).
A read follows the output as it arrives, so Oda can check a job while it still runs. A background workflow reports only its status until it settles; its return value arrives with the completion notice.
Output that is cut or dropped is noted instead of failing: [output truncated], and [some output was dropped from memory; full output: …] when the full output was saved to a file.

Waiting for a job

Oda can wait on a job instead of moving on. A wait runs for up to 30 seconds by default, and never longer than 10 minutes.
A wait that runs out leaves the job running; Oda can check it again later.
A message from you ends a wait at once. The job itself keeps running.

Stopping a job

Stopping is a request, not an instant stop: the job reads stopping until its work actually ends, then settles as killed.
From the chat, Oda stops a job with job_kill; the receipt reads requested cancellation of job <id>, or job <id> had already finished <status> when there was nothing left to stop.
From Activity, a running row offers Stop: one press stops the job, with no confirmation. A job stopped this way settles with the reason cancelled by the user. Stop all stops every running background row in the panel at once.
Stopping the chat's turn does not stop its jobs: stop the job itself.

When a job finishes

A finished job posts a completion notice into its chat: background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output. The notice names the job and its state; the output stays in the job, where Oda reads it.
If Oda is already working in the chat, the notice folds into its next step. If the chat is idle, Oda opens a new turn for it, so a finished result does not sit unseen.
Wakes are budgeted: after three completion wakes in a row, Oda waits for your next message instead of waking the chat again.
A job Oda stopped itself with job_kill posts no notice. A job you stopped from its row still sends its notice, so Oda learns how it ended.

Questions, answered

Can I check on a job while it is still running?

Yes. A read returns the output that is new since the last read and closes with the job's current state; with nothing new, it answers (no new output). A background workflow reports only its status until it settles, and its return value arrives with the completion notice.

Where can I see the jobs of this chat?

In the Activity tab of the side panel, under Running: a chat's background processes gather in a Background jobs list, and the Activity pill at the top of the chat counts what is under way. Oda's own listing reads the same jobs out in the chat, one line each.

How long can Oda wait on a job?

Up to 30 seconds by default, and never longer than 10 minutes. If the wait runs out, the job keeps running and can be checked again.

What happens if I send a message while Oda is waiting on a job?

The wait ends at once and Oda takes your message. The job itself keeps running; ask Oda about it again when you want its output.

What do the job states mean?

running means the work is going on now; stopping means a stop was asked for, and the job ends once its work actually stops; completed means the work finished on its own; killed means it was stopped before it could finish; failed means it ended with a problem.

What happens when I stop a job from its row in Activity?

One press stops it, with no confirmation. The stop is a request: the job reads stopping until its work really ends, then settles as killed with the reason cancelled by the user. Because the stop came from you, Oda still receives the completion notice.

How will I know when a job has finished?

A completion notice appears in the chat: background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output. If Oda is busy, the notice folds into its next step; if the chat is idle, Oda opens a new turn for it. Ask Oda for the output when you want it in the chat.

Why was I not told when a job finished?

Two cases stay quiet. A job Oda stopped itself with job_kill posts no notice, because Oda stopped it on purpose. And the waking is budgeted: after three completion wakes in a row, Oda waits for your next message instead of waking the chat again.