Orchestration (M4)
Data Passing & Scoped Env
Share structured task outputs via ctx.output and ctx.deps without cross-file imports.
ctx.output(...) and ctx.deps[...]
Tasks produce structured outputs with ctx.output(value) and downstream dependents read them via read-only ctx.deps["<canonical_name>"]:
- Immediate validation: JSON serializability is validated as soon as
ctx.output(...)is called. - Commit on success: Outputs are buffered during task execution and committed only when the task succeeds—failed tasks never poison downstream tasks or caches.
- Declared dependencies only: Reading a key from
ctx.depsthat is not listed independsraisesToolError. Reading a declared dependency that emitted no output returnsNone/undefined. - Cross-runner portable default: JSON is the canonical format across Python and TypeScript. Python also supports opt-in local-only
format="pickle"(never shared across runners or unpickled on ABI mismatch).
Scoped Environment (ctx.env)
ToolContext tracks task-local environment reads and overrides without mutating global os.environ or process.env:
- Python:
ctx.env(name, default=None),ctx.set_env(name, value),ctx.unset_env(name),with ctx.scoped_env({...}): ... - TypeScript:
ctx.env(name, defaultValue?),ctx.setEnv(name, value),ctx.unsetEnv(name),await ctx.withEnv({...}, fn)
Every accessed environment key is automatically recorded so cached tasks incorporate dynamic env reads into their full cache key.