Yao Job

Background Jobs

Tools

• yao_job_start — Start a command. background false (default) blocks until done and returns output_tail; background true returns job_id immediately.
• yao_job_list — List jobs. Supports --status filter and --limit/--offset pagination.
• yao_job_get — Get full details for a job (or daemon by ID).
• yao_job_output — Read process output (works for both job and daemon IDs).
• yao_job_wait — Block until a background job finishes or timeout expires. Jobs only, not daemons.
• yao_job_stop — Kill a running job.

Parameters

yao_job_start

yao_job_list

yao_job_output

Output read behavior:

• Returns all available content from offset in a single read (no limit parameter).
• Ring buffer caps at 10 MB; older content beyond this is discarded.
• When content has been discarded, lossy=true in the response.
• size = total bytes the process has produced; offset = earliest readable byte position.
• Example: a 20 MB output has size=20000000, offset≈10000000, lossy=true — the first ~10 MB was discarded.

yao_job_wait

Response Fields

All responses are JSON. Job objects contain:

Copy code
id, kind, session_id, status, description, background,
command, command_argv, command_line, pid, pgid, user,
started_at, finished_at, duration_ms, exit_code, signal, detail, seq

Foreground start (background=false)

Returns the job object plus output_tail (≤4KB tail of stdout+stderr):

jsonCopy code
{ "id": "job_...", "status": "completed", "exit_code": 0, ..., "output_tail": "hello world\n" }

List (paginated)

jsonCopy code
{ "jobs": [...], "total": 130, "offset": 0, "limit": 20, "has_more": true }

Wait

jsonCopy code
{ "job": { ... }, "timed_out": false }

Stop (already terminal)

jsonCopy code
{ "job": { ... }, "detail": "already in terminal state (failed); no action taken" }

Errors

Structured JSON with code and message:

jsonCopy code
{ "error": { "code": "invalid_argument", "message": "job_id is required" } }

Codes: invalid_argument, not_found, internal.

Usage Rules

1. Use background true (not bare --background) for commands expected to run longer than 30 seconds.
2. Always provide a description.
3. Foreground is default — the result and output come back in one call.
4. Monitor background output with yao_job_output to check progress.
5. Use yao_job_wait to block until a background job completes rather than polling.

BackgroundJobReceipt

When a background job finishes, the system delivers a <BackgroundJobReceipt> XML message. Upon receiving it:

1. Review the status, exit_code, cause, and output_tail.
2. If status=failed, investigate and take corrective action.
3. If status=completed, acknowledge and continue the task.