Repository navigation
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Nov 10, 2026
Closed
Closed
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.workerswith 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()andinterrupt()itself.Compared with #346
approve=True,worker.hook_registry),output_type,fork()andsync().Modelgetsstream()andprovider_name,Context.modelgets a custom validator and serializer that know about workers, andai.hook()gets aruntime=parameter.