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 with the background option of The workflow tool, fanning work out across helper agents. The call returns at once and names the job: workflow "<name>" started in the background as job <jobId>. Its return value arrives with the completion notice; check on it with job_output, stop it with job_kill.
• A command Oda runs in the background, or one that reaches its time limit and moves there. See Shell commands.
• A send to a terminal session with its background option. See Terminal sessions.

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.
• Expand a process row to see its output tail: live while the job runs, the recorded output afterwards.
• A Ralph loop folds into a single row, with each round of the loop as a member of that row. See Ralph loops.
• 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.
• While a background workflow runs, its output carries live lines that narrate the run: ▸ <phase> when a phase starts, plain log lines the run writes, and agent #1 <label> started with a matching line naming the outcome as each helper agent starts and ends. The current phase also shows on the row as its progress line.
• The output view keeps a bounded tail of the newest text. Where earlier output was dropped or is no longer kept, it marks the gap at that point.
• 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, which takes a short reason; a background workflow stopped with no reason records background workflow job killed. 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: a job does not watch the step that started it. 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.

What does started in the background as job <id> mean?

Oda has accepted the work as a background job, and the chat is free again. Oda checks it with job_output and stops it with job_kill, and a workflow's return value arrives with the completion notice.

What do the live lines under a workflow job mean?

▸ <phase> marks a phase of the run starting. A plain line is a log message the run wrote. agent #1 <label> started and the matching line with its outcome track each helper agent the run starts and ends.

Why does the output view show a gap?

The view keeps only a bounded tail of the newest text. Where earlier output was dropped or is no longer kept, it marks the gap at that point; output after the mark continues as normal. How much output a job keeps is on Background jobs: limits and lifecycle.

How does a Ralph loop appear in Activity?

As one row, with each round of the loop as a member of that row.

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.