zidane 7.0.14 → 7.0.16

package/docs/EXECUTION_CONTEXT.md

@@ -8,6 +8,7 @@ context**. You pick one with `--context`:
 | `process` (default) | None — runs on the host | You trust the prompt and want the fastest path with full host access. |
 | `docker` | Container | You want a disposable, isolated environment on your own machine. |
 | `e2b` | Remote micro-VM sandbox | You want isolation off-box, on E2B's hosted cloud or a self-hosted cluster. |
+| `daytona` | Remote sandbox | You want isolation off-box on Daytona instead of E2B. |
 
 ```bash
 bun start --prompt "build a TODO API"                       # process (default)
@@ -26,18 +27,20 @@ files → destroy), so the agent behaves identically regardless of which one you
 choose. What changes is *where* the work runs, *how it's isolated*, and a few
 context-specific flags.
 
+Contents: [Flags at a glance](#flags-at-a-glance) · [The `e2b` context](#the-e2b-context) · [The `daytona` context](#the-daytona-context) · [The `docker` context](#the-docker-context) · [The `process` context](#the-process-context-default) · [Programmatic use](#programmatic-use) · [See also](#see-also)
+
 ## Flags at a glance
 
-| Flag | `process` | `docker` | `e2b` | Meaning |
-|------|:---------:|:--------:|:-----:|---------|
-| `--context <name>` | ✓ | ✓ | ✓ | Select the context (`process` \| `docker` \| `e2b`). |
-| `--cwd <dir>` | ✓ | ✓ | ✓ | Working directory for the agent's commands. |
-| `--env KEY=VALUE` | ✓ | ✓ | ✓ | Set an environment variable (repeatable). |
-| `--pass-env VARNAME` | ✓ | ✓ | ✓ | Forward a host env var into the context by name (repeatable). |
-| `--image <name>` | — | ✓ | — | Docker image to run. |
-| `--pregame <file>` | warns | warns | ✓ | Setup script to run before prompting. |
-| `--sandbox <id>` | warns | warns | ✓ | Attach to an existing E2B sandbox. |
-| `--sandbox-on-destroy kill\|pause\|leave` | warns | warns | ✓ | What to do with an owned sandbox when the run ends (default `kill`). |
+| Flag | `process` | `docker` | `e2b` | `daytona` | Meaning |
+|------|:---------:|:--------:|:-----:|:---------:|---------|
+| `--context <name>` | ✓ | ✓ | ✓ | ✓ | Select the context (`process` \| `docker` \| `e2b` \| `daytona`). |
+| `--cwd <dir>` | ✓ | ✓ | ✓ | ✓ | Working directory for the agent's commands. |
+| `--env KEY=VALUE` | ✓ | ✓ | ✓ | ✓ | Set an environment variable (repeatable). |
+| `--pass-env VARNAME` | ✓ | ✓ | ✓ | ✓ | Forward a host env var into the context by name (repeatable). |
+| `--image <name>` | — | ✓ | — | — | Docker image to run. |
+| `--pregame <file>` | warns | warns | ✓ | ✓ | Setup script to run before prompting. |
+| `--sandbox <id>` | warns | warns | ✓ | ✓ | Attach to an existing sandbox. |
+| `--sandbox-on-destroy kill\|pause\|leave` | warns | warns | ✓ | ✓ | What to do with an owned sandbox when the run ends (default `kill`). |
 
 "warns" means the flag is accepted but ignored with a warning when it doesn't
 apply to the selected context.
@@ -178,6 +181,28 @@ command, so a warm or pre-provisioned sandbox never loses it.
 
 ---
 
+## The `daytona` context
+
+Daytona gives the agent a remote sandbox the same way `e2b` does — a different
+provider behind the same `SandboxProvider` interface. Install the optional
+peer dependency and set `DAYTONA_API_KEY` (also `DAYTONA_API_URL` /
+`DAYTONA_TARGET` for a non-default endpoint or region):
+
+```bash
+bun add @daytona/sdk
+export DAYTONA_API_KEY=dtn_xxxxxxxxxxxxxxxx
+bun start --prompt "run the test suite" --context daytona
+```
+
+`--cwd`, `--pregame`, `--sandbox`, and `--sandbox-on-destroy` behave exactly as
+they do for `e2b` (see above), including the accepted `kill`/`pause`/`leave`
+values. Programmatic use (`createDaytonaProvider`, see
+[Programmatic use](#programmatic-use)) exposes a few extra `onDestroy` values
+(`stop`, `archive`, `delete`) and an `ownAttached` flag for taking over an
+attached sandbox's lifecycle — neither is reachable from the CLI.
+
+---
+
 ## The `docker` context
 
 Docker runs the agent inside a container on your own machine — isolated, but
@@ -258,13 +283,11 @@ The process context also implements the optional `fileSize` capability — a
 containment-aware size probe that lets whole-file tools (`read_file`, `edit`,
 `multi_edit`, grep's no-ripgrep fallback) refuse multi-GB targets (256MB
 ceiling) instead of materializing them into host memory. The docker context
-implements the same probe via `wc -c` through its exec (its `readFile` also
-gets transport headroom above the tool ceiling, so tool policy — not the
-docker transport — decides read limits). Remote sandbox contexts (e2b,
-daytona, custom providers) probe identically through the sandbox's shell —
-one extra round-trip per whole-read tool call, paid so a multi-GB file is
-refused before the SDK transfers it into host memory. The experience is
-uniform across contexts: the same 256MB ceiling, the same refusal message.
+probes via `wc -c` through its exec; remote sandbox contexts (e2b, daytona,
+custom providers) probe identically through the sandbox's shell, one extra
+round-trip per whole-read tool call. The experience is uniform across
+contexts: the same 256MB ceiling, the same refusal message.
+
 One residual remains in the remote SDK contexts: `exec` output is buffered
 inside the provider SDKs and can't be capped from our side, so a command that
 streams GBs to stdout within its timeout can still balloon the host — bounded
@@ -278,6 +301,7 @@ The CLI flags map onto context factories you can call directly:
 
 ```ts
 import { createProcessContext, createSandboxContext } from 'zidane/contexts'
+import { createDaytonaProvider } from 'zidane/contexts/daytona'
 import { createDockerContext } from 'zidane/contexts/docker'
 import { createE2BProvider } from 'zidane/contexts/e2b'
 
@@ -304,6 +328,9 @@ const e2bPause = createSandboxContext(createE2BProvider({
 const e2bResume = createSandboxContext(createE2BProvider({
   sandboxId: 'sbx-abc123def456',  // Sandbox.connect auto-resumes a paused sandbox
 }))
+
+// daytona
+const daytona = createSandboxContext(createDaytonaProvider({ cwd: '/home/daytona/project' }))
 ```
 
 The Docker factory accepts the full advanced `SpawnConfig` (mounts, ports, user,
@@ -314,5 +341,5 @@ network, labels, resource limits) that the CLI doesn't surface.
 ## See also
 
 - [HEADLESS.md](HEADLESS.md) — the non-interactive CLI contract.
-- [ARCHITECTURE.md](ARCHITECTURE.md) — agent lifecycle, context teardown
-  ordering, and background-task semantics.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — agent lifecycle and background-task
+  semantics.