# Codex App-Server Harness For Scout

## Thesis

Scout should keep its current broker semantics as the canonical model.

The improvement is lower in the stack: add a harness-session plane for long-running agent runtimes, then map those sessions back into the existing `message`, `invocation`, and `flight` model.

This lets OpenScout reuse the strongest part of the pairing runtime without replacing Scout's richer collaboration semantics.

## What We Are Borrowing

The useful pattern is:

- a thin adapter boundary per harness
- a persistent session per agent instead of one-shot exec calls
- a live event stream for deltas, actions, interruptions, and steering
- replayable session state that can survive broker restarts

For Codex, that means using `codex app-server` over stdio JSON-RPC instead of `codex exec` plus prompt-file polling.

## What We Are Not Replacing

The broker remains the source of truth for:

- conversations
- messages
- invocations
- flights
- deliveries
- bindings
- collaboration records

The harness-session plane is an execution substrate, not a second canonical protocol.

## Immediate Design

### Transport

Add a first-class local endpoint transport:

- `codex_app_server`

This transport means:

- the endpoint is backed by a persistent Codex app-server session
- the runtime owns the child process and thread lifecycle
- the broker can invoke the agent through the app-server adapter instead of the
  tmux prompt-delivery adapter

### Session Model

For each Codex-backed Scout agent:

1. Start or reuse one `codex app-server` child process.
2. Initialize the JSON-RPC connection once.
3. Resume a stored thread id if available.
4. Otherwise create a fresh thread with the agent's system prompt.
5. Route invocations to `turn/start`.
6. Capture final assistant output from the streamed items.

The runtime should persist the Codex thread id in the agent runtime directory so a broker restart can resume the same long-running thread.

### Prompting

Codex app-server agents should no longer be told to send their final reply through Scout shell commands.

They should instead be told:

- they are invoked directly by the OpenScout broker
- their final assistant message becomes the broker-visible reply
- they may still inspect broker context with Scout commands if they need surrounding history

That preserves current Scout semantics while removing the brittle `[ask:<id>]` tagging loop.

## Why This Is Better

Compared with the current Codex path:

- no prompt queue files
- no `codex exec resume` loop
- no broker polling for tagged replies
- no mislabeling an app-server-backed endpoint as a tmux-backed endpoint

Compared with replacing Scout semantics wholesale:

- no downgrade in collaboration richness
- no duplicate source of truth
- no protocol fork per harness

## First Implementation Slice

1. Add `codex_app_server` to protocol and runtime endpoint transport unions.
2. Derive app-server-backed Codex agents to that transport; keep tmux as the
   current transport for tmux-backed agents.
3. Add a persistent `CodexAppServerSessionManager` in `@openscout/runtime`.
4. Resume or create a Codex thread per agent and persist its thread id locally.
5. Route broker invocations for Codex agents through `turn/start`.
6. Keep the tmux path current for agents that use tmux as their runtime
   transport.

## Next Steps After This Slice

- expose interrupt and steer as first-class runtime operations
- project harness deltas into richer flight status
- add replay and snapshot APIs for live session inspection
- generalize the adapter boundary so Claude, Codex, and future harnesses share one session abstraction