Add ai.harnesses.experimental and ai.workspaces.experimental

.github/workflows/ci.yml

@@ -44,9 +44,11 @@ jobs:
           - sdk-versions: minimum
             openai: openai==2.34.0
             anthropic: anthropic==0.83.0
+            claude-agent-sdk: claude-agent-sdk==0.2.144
           - sdk-versions: latest
             openai: openai>=2.34.0,<4.0.0
             anthropic: anthropic>=0.83.0,<2.0.0
+            claude-agent-sdk: claude-agent-sdk>=0.2.144,<0.3
     name: Provider SDKs (${{ matrix.sdk-versions }})
     steps:
       - uses: actions/checkout@v4
@@ -64,10 +66,35 @@ jobs:
           uv pip install --upgrade
           '${{ matrix.openai }}'
           '${{ matrix.anthropic }}'
+          '${{ matrix.claude-agent-sdk }}'
 
       - run: uv run --no-sync mypy src tests
       - run: uv run --no-sync ty check
       - run: >-
           uv run --no-sync pytest
           tests/providers/openai
           tests/providers/anthropic
+          tests/harnesses
+
+  no-extras:
+    # `pip install ai` with no extras: the harness and sandbox pieces must
+    # import, and fail with InstallationError when built, not on first use.
+    runs-on: ubuntu-latest
+    name: Without optional extras
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv sync --no-default-groups
+
+      - run: uv pip install pytest
+
+      - run: >-
+          uv run --no-sync pytest
+          tests/harnesses/experimental/test_extras.py
+          tests/workspaces/experimental/test_extras.py

.gitignore

@@ -216,3 +216,4 @@ __marimo__/
 
 .claude/
 .codex
+.env*

CONTRIBUTING.md

@@ -1,3 +1,115 @@
+## Harnesses and workspaces
+
+`ai.harnesses.experimental` drives coding-agent CLIs. Adapters live in
+`src/ai/harnesses/experimental/_adapters/` (`claude.py` on
+`claude-agent-sdk`, `codex.py` on `codex app-server`). Workspaces live in
+`src/ai/workspaces/experimental/` (`_local.py`, `_sandbox.py`).
+
+Rules that apply to both:
+
+- **Layering.** Caller, then `Harness`, then adapter, then workspace. Each
+  layer knows only the one below. A workspace never imports harness names
+  and never learns a CLI's dialect. A new CLI touches one adapter; a new
+  place to run touches one workspace.
+- **Capability honesty.** Every `Capabilities` field is a claim you watched
+  be true. When a capability is absent, raise `UnsupportedError`. Never a
+  silent no-op.
+- **Translate errors at the boundary.** Callers never catch a CLI library's
+  or provider's exceptions. Map them to `ai.harnesses.experimental.errors`
+  or `ai.workspaces.experimental.errors`.
+
+### Adding a harness
+
+1. Pick the CLI protocol first. It must offer, in one mode: a long-lived
+   process or resume by id, input while a turn runs (steer), an interrupt,
+   and a way to ask the client about tool calls. Codex had to move from
+   `codex exec --json` to `app-server` for this.
+2. Implement the `Adapter` protocol in `_adapters/base.py`. `new_session()`
+   returns the CLI's own id, never one you mint.
+3. Never spawn a process yourself. Call `workspace.spawn(argv)`. If the CLI
+   library insists on spawning, give it a transport backed by the workspace
+   (see `_adapters/remote_cli.py`).
+4. Yield `ai.types.events` only, ending with `StreamEnd`. Text, reasoning,
+   and tool calls need Start / Delta / End triples. Emit tool arguments as a
+   `ToolDelta`, even when the call arrives complete. Tool results are
+   `ToolCallResult` events.
+5. `approve is None` means approve everything. Answer the CLI's approval
+   requests yourself; never fall back to asking a terminal that is not there.
+   Exceptions inside a permission callback do not reach the caller: park them
+   on the adapter and re-raise from `turn()`.
+6. Hold the workspace session lock (`_session_lock.SessionLock`) for every
+   conversation you open, so a second writer gets `SessionBusyError` on every
+   CLI.
+7. Store `history=` natively with the rules in `_handoff.py`: text verbatim,
+   tool calls with their original names, reasoning as a note or dropped with
+   a warning. Never drop context silently.
+8. Spell the gateway in the adapter (`gateway_env`, `gateway_config`). When
+   `workspace.injects_credentials_for(gateway.host)`, hand the CLI
+   `gateway.brokered()`.
+9. Add a factory in `_factories.py` (and to `BUILDERS`), then add the kind to
+   `SPECS` and `HARNESS_CLI` in `tests/harnesses/experimental/conftest.py`.
+   That runs the whole e2e suite against the new adapter.
+
+### Adding a workspace
+
+1. Subclass `Workspace` from `_base.py`. Set `kind`, `owner` (`"provider"`
+   only for a box the SDK may install software into), and `duplex_spawn`.
+   `env` belongs to the work, not the agent.
+2. Do not override `contains()`. It is pure-path on purpose: a remote path
+   does not exist on this machine.
+3. Move files through `read_text`, `write_text`, `_copy_in`, and `_copy_out`.
+   Filter both directions with `walk_uploadable` and `copy_tree`. Batch
+   uploads; round trips are the cost on a remote box.
+4. Map failures: a program that cannot run is `exit_code=127` from `exec`
+   and `WorkspaceError` from `spawn`; a missing file is `FileNotFoundError`;
+   a workspace that no longer exists is `WorkspaceGoneError`.
+5. `Process.terminate()` returns only when the program is gone, and raises
+   when it could not make that true.
+6. If the workspace can outlive the client, support reconnect by `name=`,
+   carry that identity in `coords`, and add a `keep` flag. Live state is
+   found by asking a harness inside the workspace, never by the workspace.
+7. For ptys, reuse `_pty_holder.py` and `_pty.FramedPty` over your byte
+   channel. Never name a module `pty.py`.
+8. Export it from `src/ai/workspaces/experimental/__init__.py`, and add it to
+   the `any_workspace` fixtures in `tests/workspaces/experimental/conftest.py`
+   and `tests/harnesses/experimental/conftest.py` as
+   `pytest.param("yours", marks=pytest.mark.yours)`. It must present the same
+   `project` the local branch does.
+
+### Tests
+
+Live tests drive real CLIs and real sandboxes. No fakes, no recorded doubles.
+A missing CLI skips; it never passes silently. Markers:
+
+- `live`: drives a real local `claude` or `codex`.
+- `sandbox`: needs Vercel Sandbox credentials.
+- `slow`: minutes, not seconds.
+
+```bash
+uv run pytest                                               # offline (default)
+uv run pytest tests/harnesses tests/workspaces -m "not sandbox"  # plus local CLIs
+uv run pytest tests/harnesses tests/workspaces -m ""        # everything
+```
+
+Plain `uv run pytest` deselects `live` and `sandbox` (see `addopts` in
+`pyproject.toml`); passing `-m` replaces that filter.
+
+The live suite needs `claude` and `codex` CLIs that can reach a model: a
+login, or the gateway variables in `.env.local`. The sandbox suite
+also needs Vercel credentials and `AI_GATEWAY_API_KEY` in a `.env.local` at
+the repo root (`vercel link`, then `vercel env pull`). Every test is capped at
+300 seconds.
+
+When writing tests, never branch on native tool names, wait on events instead
+of sleeping, assert exact answers, and put anything on the control surface
+on `any_harness` so it runs on both harnesses and both workspaces.
+
+Run the harness examples with:
+
+```bash
+uv run examples/.test_scripts/run-examples.py --harnesses
+```
+
 ## Releasing
 
 Every PR needs to be labeled as `breaking`, `feature`, `fix`, or

README.md

@@ -19,6 +19,8 @@ official SDK lazily. Vercel OIDC for AI Gateway also uses an optional extra:
 uv add "ai[openai]"      # OpenAI-compatible providers
 uv add "ai[anthropic]"   # Anthropic-compatible providers
 uv add "ai[vercel]"      # Vercel OIDC for AI Gateway
+uv add "ai[claude-code]" # Claude Code harness (experimental)
+uv add "ai[sandbox]"     # Vercel Sandbox workspaces (experimental)
 ```
 
 ```python
@@ -156,6 +158,24 @@ approval = await ai.hook(
 ai.resolve_hook("approve_send_email", {"granted": True, "reason": "approved"})
 ```
 
+## Harnesses (experimental)
+
+Harnesses drive coding-agent CLIs you already have, Claude Code and Codex,
+on this machine or in a Vercel Sandbox. A turn streams the same `ai.events`
+as an agent:
+
+```python
+from ai.harnesses import experimental as harnesses
+from ai.workspaces import experimental as workspaces
+
+async with harnesses.claude_code(workspace=workspaces.Local(".")) as harness:
+    result = await harness.run("What does this repo do?")
+```
+
+This API is experimental and may change or be removed. See
+[Harnesses](https://ai-python.dev/docs/basics/harnesses) and
+[Workspaces](https://ai-python.dev/docs/basics/workspaces).
+
 ## Examples
 
 Focused samples live in category directories under `examples/`.
@@ -164,6 +184,8 @@ Focused samples live in category directories under `examples/`.
 - `examples/media/` - image, video, speech, transcription, embeddings,
   reranking, and multimodal input/output
 - `examples/models/` - streaming, structured output, and provider examples
+- `examples/harnesses/` - driving Claude Code and Codex, locally and in a
+  sandbox (experimental)
 - `examples/apps/` - end-to-end demos
 
 End-to-end demos:
@@ -173,3 +195,7 @@ End-to-end demos:
 - `examples/apps/durable_agent_temporal/` - durable agent with Temporal
 - `examples/apps/durable_agent_workflows/` - durable agent with Workflows
 - `examples/apps/slack_agent/` - Slack agent
+- `examples/apps/afk/` - move a coding-agent conversation into a sandbox and
+  back (experimental harnesses)
+- `examples/apps/deepysec/` - security-scanning pipeline on harnesses
+  (experimental)