Steadmesh

Disposable task workers

A persistent seat can delegate a bounded piece of work to a fresh worker, then inspect its output and explicitly chosen artifacts. The parent keeps its identity, workspace, memory, harness session and one-turn lease. A worker is a separate short-lived Kubernetes Pod, not another persistent seat.

Introduced in v0.6.0. Install matching platform, controller and seat images before trying these tools. See upgrade notes.

For independent teammates with their own inboxes, ordinary turns and private memory, use native team pools. Disposable tasks and legacy elastic workers remain a separate mode; they are not automatically migrated.

Start, inspect and cancel

During an active parent turn, call tasks.start with a unique UUID request_id, a prompt, optional input_files (path, content), and artifact_paths to return. Repeating an identical request ID returns the same run; reusing it for different input fails. Use tasks.get with its id to inspect state, bounded output and artifact names, and tasks.cancel to stop it. When runtime cleanup completes, a durable, deduplicated system message wakes the parent with the task ID and parent execution correlation. That message reports technical completion, not business success.

Run this illustrative example inside an active seat, where the runner supplies its token, lease generation and execution ID. steadmesh-tools is not an unauthenticated operator command. Generate a new UUID for each new job; the UUID below is only an example.

steadmesh-tools call tasks.start '{
  "request_id": "814cdd22-73ed-4d55-8bb7-02b685291dbb",
  "prompt": "Review input.txt and write a short critique to review.txt",
  "timeout_seconds": 300,
  "input_files": [{"path": "input.txt", "content": "An explicit draft to review"}],
  "artifact_paths": ["review.txt"]
}'

# Use the id returned by tasks.start
steadmesh-tools call tasks.get '{"id":"TASK_RUN_ID"}'
steadmesh-tools call tasks.get '{"id":"TASK_RUN_ID","artifact_path":"review.txt"}'

# Cancel only if this run is no longer needed
steadmesh-tools call tasks.cancel '{"id":"TASK_RUN_ID"}'

The runtime API also offers POST /v1/task-runs, GET /v1/task-runs, GET /v1/task-runs/{id}, and POST /v1/task-runs/{id}/cancel. Creation requires the current generation and a real running parent execution in the existing runtime headers. Reads are scoped to the parent seat. The full GET returns the explicit input and result files; tool results retain the existing 16 KiB limit. tasks.get with artifact_path returns a single small artifact; use the runtime API for larger files.

Bounds and authority

Shared model budgets

Worker model calls debit the parent's organisation-daily, seat-daily and original parent-execution counters. Siblings share those counters even if the parent turn has finished. A worker cannot obtain extra budget by supplying another execution ID. Requests retain the same per-request cap and conservative accounting for unknown usage. See model output budgets.

Completion and cleanup

States are pending, running, completed, failed, cancelled and timed_out. A terminal state does not mean cleanup has finished: cleaned_at is populated only after the controller confirms removal. The completion message is delivered after cleanup if the parent is still active; a retiring or retired parent is not woken for a result.

Outstanding workers keep an otherwise idle parent runtime warm until cleanup finishes, so a completion notification cannot cause an idle restart that revokes still-running siblings. This does not bypass suspension or blocking.

Changing the parent's configuration revision or lease generation, retiring it, or reaching the task deadline revokes worker authentication. Suspending or blocking the parent causes the controller to cancel its workers. A claimed worker whose Pod disappears fails rather than silently repeating external work. Cancellation is immediate at the API boundary; Pod removal remains asynchronous. Capacity is reusable only after the controller confirms Pod absence and deletes its identity and policy.

Results remain durable after cleanup. Nothing copies results into the parent workspace or changes shared memory automatically. The parent decides what to use. Deleting an organisation with data deletion also removes its worker records. No production cluster or credentials are needed to run the unit and PostgreSQL integration tests.

What is not copied

This first implementation uses explicit text snapshots and artifacts. It does not clone repositories, copy live files automatically, resume worker sessions, delegate credential access or support nested workers.