Provider-agnostic worker decision spike

[cbusillo]

Intent

Decide whether provider-agnostic workers for the Codex fork overlay can be handled through plugins, app-server thread orchestration, an OpenAI-compatible translation gateway, or external CLI-backed workers, or whether Codex needs a minimal host worker substrate.

Parent: #1

Finish Line

Produce a recommendation with evidence for the first milestone, covering:

• provider selection and auth/config loading
• lifecycle: start, stream, cancel, wait, collect output
• usage/quota accounting
• sandbox and git worktree policy
• structured events and Desktop/TUI visibility
• diff collection and resume/journal behavior
• failure/degraded behavior when one provider is unavailable or out of quota

Current Status

Updated 2026-06-14 by Code.

State: Waiting. #58 / PR #82 delivered the first concrete external-command dogfood backend, so this spike should now use that implementation as evidence rather than treat it as a prerequisite. The immediate MVP dogfood path exists; #2 remains the broader provider-agnostic worker decision record.

Evidence from #58 / PR #82:

• Role-scoped [agents.<role>].backend config can select an external_command backend without regressing internal agents.
• A one-shot subprocess backend can support request/response, lifecycle status, completion, cancellation, close, bounded output, and config fallback through the V2 multi-agent path.
• The first slice intentionally did not settle streaming, resume/full-history fork support, app-server runtime APIs, richer provider/auth strategy, usage/quota accounting, or broader UX polish.

Remaining decision scope:

• Provider selection and auth/config loading beyond role-scoped external_command.
• Lifecycle, failure, cancellation, wait, output, and streaming semantics across provider types.
• Usage/quota accounting and degraded behavior when a provider is unavailable or out of quota.
• Sandbox, git worktree, diff collection, resume/journal, and app-server visibility policy.
• When to graduate from the initial dogfood backend into a provider-agnostic worker abstraction.

Options To Compare

1. Plugin-only workers using codex exec --json and app-server transport.
2. OpenAI-compatible Responses translation gateway, such as LiteLLM or a small local proxy.
3. External CLI-backed workers for Claude/Gemini/AGY with normalized event and usage wrappers.
4. Minimal Codex host substrate for provider-independent workers requested by plugins.

Guardrails

• Do not implement binary code during the spike.
• Do not treat provider support as a model-list issue only.
• Prefer the smallest layer that gives first-class cancellation, usage, sandbox/worktree policy, structured events, and Desktop/TUI visibility.
• Keep orchestration policy in plugins unless a host primitive is genuinely missing.