Skip to content

Implement ai.workers: one object per CLI session - #347

Closed
anbuzin wants to merge 6 commits into
mainfrom
add-claude-code-and-pi-workers
Closed

anbuzin wants to merge 6 commits into
mainfrom
add-claude-code-and-pi-workers

Conversation

@anbuzin

@anbuzin anbuzin commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

One of two competing drafts for ai.workers. The other is #346.

This PR holds the whole former stack in one PR off main. It replaces #342 (ai.ModelLike), #343 (ai.workers with Codex) and #344 (Claude Code and Pi); the commits and the branch are the same.

A worker is one session of a coding-agent CLI (Codex, Claude Code, Pi). In this draft the worker is one object per session: it goes where a model goes, and it has send(), events() and interrupt() itself.

async with workers.ClaudeCode(model_name="sonnet") as worker:
    async with ai.stream(worker, [ai.user_message("Fix the tests")]) as s: ...
    await worker.send(prompt)

Compared with #346

  • More features: approvals through hooks (approve=True, worker.hook_registry), output_type, fork() and sync().
  • More core changes: Model gets stream() and provider_name, Context.model gets a custom validator and serializer that know about workers, and ai.hook() gets a runtime= parameter.

@anbuzin anbuzin added the feature New functionality label Nov 10, 2026
@vercel

vercel Bot commented Nov 10, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ai-python Ready Ready Preview, v0 Nov 10, 2026 5:28pm UTC

@socket-security

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedpypi/​claude-agent-sdk@​0.2.17899100100100100
Addedpypi/​pytest-timeout@​2.4.0100100100100100

View full report

@vercel-internal-security-reviewer

Copy link
Copy Markdown

Security review details

@anbuzin anbuzin closed this Nov 10, 2026
anbuzin added a commit that referenced this pull request Nov 18, 2026
…ession (#346)

A draft for `ai.external`. #347, the competing draft, is closed.

An external harness is a coding-agent CLI (Codex, Claude Code, Pi, fx)
where a model goes. It has the shape of an `ai.Model`: plain data and a
provider. The state is in a session.

- `ExternalHarness`: the settings of the CLI. It holds no state.
- `ExternalHarnessProvider`: `name`, `executable`, `env`, and the
`stream()` that `ai.stream` and `ai.Agent.run` call.
- `Session`: the state (`id`, `messages`) and direct control (`start`,
`send`, `events`, `interrupt`, `close`).

```python
harness = ai.external.Codex(cwd=".")
async with harness.session() as session:
    async with agent.run(harness, messages) as run: ...
    await session.send(ai.user_message("And the tests?"))
```

## Sessions

- `async with harness.session()` is the only way to start the CLI. A
model call outside the block raises `ExternalHarnessError`. No call
starts a CLI for one turn.
- `harness.session()` is a new session. `harness.session(session_id)`
continues one that the CLI has, and `harness.session(messages=history)`
starts one with a past (lossy). To continue later, save `session.id`
with the harness data.
- A harness has one open session in a task: a second `harness.session()`
in the block raises. Two tasks can each open one.
- `session.start()` starts the CLI early in an open block. It does not
open a session.

## Compared with #347

- Core changes less. `ai.stream` still calls
`model.provider.stream(model, ...)`; the diff outside `ai/external` is
`Model` -> `ModelLike` annotations, one `aclosing` block in `api.py`,
the `Context.model` annotation, and the two protocols (`ModelLike`,
`ProviderLike`) in `models/core/model.py`. `ai/__init__.py` imports
`external`, as it does `durable` and `testing`. `hooks.py` is as on
`main`.
- The state and direct control are on a separate `Session`, not on the
harness.
- Not here, and in #347: approvals through hooks, `output_type`,
`fork()` and `sync()`.

## fx

`ai.external.Fx` drives `fx acp` (Agent Client Protocol over stdio). The
wire follows Codex; `JsonRpcPeer` moved to `external/_jsonrpc.py` so
that both use it.

- Fields: `model_provider` and `effort`. fx runs with `--permission-mode
full-access`.
- A new session with a past is written into the fx session store, with
tool calls, results and images, and opened with `session/load`. If fx
refuses it, the wire removes what it wrote and raises
`ExternalHarnessError` with the fx version.
- Limits, stated on `Fx`: a bridge tool must answer in 5 minutes;
streamed tool results are short previews; instructions are fixed when
the session starts; the built-in tools cannot be limited. The store
format is internal to fx, so a new fx release can break the seed.
- `Session.interrupt()` does nothing between the end of a turn and the
start of the turn that fx makes from a late steer. After an interrupt, a
steer that fx dropped goes again as a new prompt.

## Status

- Offline tests, ruff, mypy (`src tests`) and ty pass locally and in CI
(Python 3.12 to 3.14) on `0073da8`.
- The live tests (`AI_EXTERNAL_LIVE=1 uv run pytest
tests/external/test_live.py`) were not run after the session changes
(`d0dffe8` and later). The last recorded run is fx only, with fx 0.0.17
on `57bd861`.

This branch was successfully deployed

1 active deployment
Preview — 182feb1e Deployed Nov 9, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New functionality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant