> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepared agent tasks and teams

> Retain private launch/input/result receipts, supervise exact worker identities, and discover registered families from fresh CLI, TUI, and MCP observers.

Prepared tasks use supervised processes and a caller-owned journal. Planning does not install
a model runtime or sign an agent into a provider account; prepare the worker environment and
its independently authorized access first.

## Plan, launch, inspect

```typescript theme={null}
import { AgentTasks, StateSetSandbox } from '@stateset/sandbox-sdk';
import { FileAgentTaskStore } from '@stateset/sandbox-sdk/node';

const apiOrigin = process.env.STATESET_BASE_URL!;
const client = new StateSetSandbox({
  baseUrl: apiOrigin, authToken: process.env.STATESET_API_KEY!, retry: false,
});
const tasks = new AgentTasks(client,
  new FileAgentTaskStore('/private/project/.stateset-agent-tasks'), apiOrigin);
const plan = await tasks.plan({
  sandbox_id: sandboxId,
  parent_task_id: 'review-team',
  objective: 'Check the prepared workspace input',
  command: ['python3', '/workspace/worker.py', '{task_file}'],
  timeout_seconds: 300,
  artifact_paths: ['result.json'],
});
const receipt = await tasks.launch(plan);
const observation = await tasks.inspect(receipt.task_id);
```

The worker file and authorized input must exist before launch. Retain the private plan and
original task ID. Placeholders expand from its contract; upload multiline source as a file.
Both original and expanded argv have validated bounds and reject control characters.

A fresh parent with the same journal inspects an uncertain launch using exact worker name,
workspace and command hash. Missing, ambiguous, mismatched and unavailable workers remain
explicit. `inspect` never launches a replacement; bounded `wait` does not stop the child on
timeout or local cancellation.

## Inputs and result bundles

Reviewed inputs bind remote path, byte count, SHA-256, and supported batch manifests. Do
not replace files after review or treat caller metadata as proof of a remote write.

Observed process success is separate from task quality. Collect declared outputs before
sandbox expiry into a new private bundle, retain its manifest, and verify hashes and the
actual answer. Partial collection retains failure evidence rather than claiming completion.
Saved bundles support offline review after process logs/sandbox disappear. Journals and
bundles may contain sensitive project data.

## Teams and durable orchestration

Node `AgentTeams` coordinates reviewed members/concurrency and private team receipts.
Keep the returned `team_id`; reconcile uncertain dispatch rather than preparing a new team.
The local `MultiAgentOrchestrator` is a different in-process DAG scheduler and does not
persist its queue through caller restart. Separately durable orchestration uses Temporal
through `DurableRunClient`, with that service's own credentials and recovery contract.

## Server registry and grants

Opt-in registered teams publish curated metadata before workers start. This needs the Node
registry release and migration **067**. Registration launches no worker; uncertain
registration fences dispatch. Its root UUID coordinates metadata and normally has no process.

| Access | Meaning |
| - | - |
| Owner | Immutable root owner; reads/manages family grants |
| Viewer | Reads accessible family metadata |
| Operator | Also registers descendants under an existing parent |

Grants cover current/future descendants. Revocation and admission serialize on the root.
Sandbox/process permissions remain independent: family discovery cannot grant execution.

`TaskRegistryObserver` supports fresh CLI/TUI/MCP observers without launch journals. It
verifies SDK process identity and command hash, pages families, and reports task quality as
`not_evaluated`. Preserve cursor/filters; a partial page cannot establish `family_complete`.
Server metadata does not reconstruct private input/control/result receipts.

## Evidence scope

The retained October 19 hosted exercise used three prepared Python workers with fresh CLI,
stdio MCP and PTY TUI observers, verified results and cleanup. A separate Codex exercise used
independently signed-in sandboxes. These do not establish arbitrary fleet scale, provider
failure recovery, or correctness of every model answer.

Source: SDK guide, `docs/SANDBOX_WORKBENCH.md`, and `docs/releases/2026-10-v2.11.0.md`,
checked at `67bc2370` on October 20, 2026. Continue with
[the workbench](/stateset-sandbox/workbench) or [MCP](/stateset-sandbox/stateset-sandbox-mcp).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.