# ChatGPT Orchestrator — Specification

Status: authoritative v0 specification  
Date: 2026-08-19  
Repository: `platform-modules/chatgpt-orchestrator`

## 1. Purpose

`chatgpt-orchestrator` turns ordinary ChatGPT Web conversations into a coordinated manager/worker system without Playwright, CDP, Selenium, or undocumented ChatGPT backend APIs.

A root ChatGPT conversation decomposes a large goal through MCP. A Firefox-first WebExtension is the ChatGPT-Web executor: it creates worker conversations, injects a minimal bootstrap prompt, binds each managed conversation to a logical worker, observes coarse lifecycle state, and can wake an idle managed worker when new work arrives.

Workers communicate through the orchestrator MCP and durable control-plane state. ChatGPT Web is an execution host, not the orchestration source of truth.

## 2. Target workflow

1. User gives one large request to `/root` in ChatGPT Web.
2. Root creates a run/DAG and calls `worker.spawn` for parallel-safe tasks.
3. The extension receives launch commands and creates background ChatGPT chats.
4. Each child receives a short bootstrap prompt, calls `worker.attach`, and retrieves its authoritative assignment from MCP.
5. Root repeatedly calls bounded `events.wait` while workers execute, answering questions and unlocking dependencies.
6. Workers report messages, progress, artifacts, completion, or failure through MCP.
7. If an idle worker needs another turn, the orchestrator tells the extension to inject a standard wake/resume prompt into that managed conversation.
8. Root integrates/reviews results and returns to the user when the run is terminal or a genuine human decision is required.

## 3. Non-goals

- no general-purpose browser automation framework;
- no private `chatgpt.com` backend calls;
- no arbitrary personal-chat scraping;
- no conversation text as IPC;
- no Project memory as authoritative worker state;
- no ACP/A2A requirement for v0;
- no dependency on screenshots/pixel automation;
- no live browser testing on the user's workstation display.

## 4. Core architecture

### 4.1 Logical worker is not a conversation

```text
worker.spawn
    |
    v
logical worker W17
    |
    +-- chatgpt-web executor --> ChatGPT conversation
    +-- future responses -----> API runtime
    +-- future codex ----------> Codex runtime
```

ChatGPT conversation IDs/URLs and DOM behavior stay behind an executor boundary.

### 4.2 MCP is the agent-facing seam

MCP owns task attachment, worker lifecycle, messaging, progress, completion, and event waiting. The extension does not own DAG semantics.

### 4.3 Extension is a narrow host adapter

The extension may:

- create a managed ChatGPT conversation;
- submit a prompt;
- detect its URL/conversation identity;
- observe coarse state (`loading`, `generating`, `idle`, `error`, `closed`);
- send a wake/follow-up prompt when idle;
- close a managed tab when requested;
- later support branching as an optional executor capability.

It may not own task definitions, acceptance criteria, inter-agent mailboxes, repository state, or arbitrary DOM execution.

### 4.4 Durable events + bounded waits

`events.wait(runId, afterCursor, timeoutMs)` is a bounded long poll. No correctness property depends on a single MCP call staying open indefinitely. State survives client/server reconnects.

### 4.5 Managed tabs only

The extension controls only tabs it created for the orchestrator or tabs explicitly attached by the user. It must not inspect/control unrelated ChatGPT tabs.

## 5. Monorepo

```text
apps/
  mcp-server/             MCP transports + agent-facing tools
  extension/              Firefox-first WebExtension
packages/
  protocol/               shared schemas/IDs/events/commands
  core/                   orchestration state machine/service
  persistence/            durable repository implementation
  chatgpt-web-adapter/    isolated DOM adapter
SPEC.md
PLAN.md
```

Packages are split by seams/trust boundaries. Domain logic remains testable without MCP or a browser.

## 6. Runtime topology

```text
                  ChatGPT Web /root
                         |
                         | MCP
                         v
              +-----------------------+
              | Orchestrator + MCP    |
              | runs/tasks/workers    |
              | mailboxes/event log   |
              | executor queue        |
              +-----------+-----------+
                          |
                  authenticated local
                   executor transport
                          |
                          v
              +-----------------------+
              | Firefox WebExtension  |
              +-----------+-----------+
                          |
                 +--------+--------+
                 v        v        v
                W1       W2       W3
                 \        |       /
                  +-------+------+ 
                          |
                          | MCP
                          v
                     Orchestrator
```

The extension connection is executor transport, not agent IPC.

## 7. Domain model

### Run

Fields: `runId`, title, root worker, state, timestamps, monotonic event cursor.

States: `active | completing | completed | failed | cancelled`.

### Worker

Fields: `workerId`, `runId`, hierarchical name (`/root/backend`), parent, executor, state, assignment, optional execution binding, timestamps.

States:

```text
created -> launch_requested -> launching -> running -> waiting -> completed
                     \          \             \----> failed/cancelled
                      \----------> launch_failed
```

A completed worker resumes only through explicit follow-up work.

### Assignment

Authoritative worker context: objective, constraints, acceptance criteria, dependencies, allowed/forbidden scope, artifact references, communication policy, completion protocol.

The DOM bootstrap contains only a worker attach identity plus concise instructions; full assignment data stays in MCP/control-plane storage.

### Message

Durable asynchronous message types: `question`, `answer`, `information`, `blocker`, `review_request`, `correction`.

### Event

Every state mutation appends an ordered event. Representative types:

`run.created`, `worker.created`, `worker.launch_requested`, `worker.bound`, `worker.state_changed`, `worker.message`, `worker.progress`, `worker.completed`, `worker.failed`, `executor.connected`, `executor.disconnected`, `executor.command_acked`, `conversation.created`, `conversation.state_changed`.

## 8. MCP v0

### Run
- `run.create`
- `run.get`
- `run.cancel`

### Worker
- `worker.spawn`
- `worker.attach`
- `worker.list`
- `worker.progress`
- `worker.complete`
- `worker.fail`
- `worker.interrupt`
- `worker.followup`

### Messaging
- `message.send`
- `message.broadcast` (root/policy gated)

### Events
- `events.wait`
- `events.list`

All tools use structured output, stable error codes, and explicit annotations. `events.wait` returns `{cursor, events, timedOut}`.

## 9. Executor protocol v0

The extension registers over an authenticated local connection. v0 uses a loopback WebSocket served by the orchestrator runtime; Native Messaging remains a future transport option.

Server -> extension commands:

- `conversation.create`
- `conversation.send`
- `conversation.inspect`
- `conversation.close`
- later: `conversation.branch`

Extension -> server events:

- `executor.hello`
- `executor.heartbeat`
- `command.ack`
- `conversation.created`
- `conversation.bound`
- `conversation.state`
- `conversation.error`
- `conversation.closed`

Each command includes `commandId`, `workerId`, deadline, and idempotency key. Replays must not duplicate conversations or prompt submissions.

## 10. Firefox-first WebExtension

Use WebExtensions APIs with shared TypeScript. Build browser-specific manifests where Firefox/Chromium MV3 differs. Shared source uses Promise-oriented `browser.*` via Mozilla's WebExtension polyfill.

Outputs:

```text
dist/firefox/
dist/chromium/
```

Components:

- background runtime: executor connection, tab bindings, command routing/idempotency;
- content script: only on `https://chatgpt.com/*`, owns DOM interaction;
- `ChatGptWebAdapter`: semantic locators + state observation;
- options/debug page: endpoint/token and managed-worker status, not arbitrary scripting.

### Fresh chat is default

A new worker normally gets a fresh chat because MCP supplies authoritative context. Branching is deferred as an optimization.

```text
worker.spawn
 -> conversation.create
 -> tabs.create({active:false})
 -> content script ready
 -> submit bootstrap once
 -> observe canonical conversation URL/ID
 -> report binding
 -> child calls worker.attach
```

### Bootstrap

Versioned minimal form:

```text
You are an orchestrated worker. Attach to worker <opaque-id> using the ChatGPT Orchestrator MCP, retrieve your assignment, execute it to completion, communicate through the orchestrator, and call worker.complete or worker.fail before ending your task.
```

### Wake/resume

If a worker is idle and new work is queued, send a standard resume prompt. If it is generating, queue the wake until idle. Never inject concurrent composer submissions.

## 11. ChatGPT DOM adapter rules

ChatGPT Web DOM is not a public stable API, therefore:

1. all selectors/heuristics live behind `ChatGptWebAdapter`;
2. prefer semantic/accessibility attributes over generated classes;
3. ordered fallback locators must fail closed;
4. use bounded `MutationObserver`, not tight polling;
5. no `eval`, private fetch interception, or backend calls;
6. mismatched UI emits typed `HOST_UI_CHANGED` rather than approximate clicking;
7. unit-test against sanitized/synthetic DOM fixtures before live browser tests.

## 12. Persistence requirements

Expose a transaction-oriented repository interface with:

- durable run/worker/assignment/message/event state;
- atomic state transition + event append;
- monotonic per-run event cursor;
- idempotency-key uniqueness;
- restart recovery;
- configurable retention independent of correctness.

Prefer dependency-light local persistence; avoid native dependencies unless they materially improve correctness.

## 13. Security/privacy

- minimal extension permissions;
- ChatGPT host access only plus configured local executor endpoint where needed;
- high-entropy executor token, never in prompts/URLs;
- page DOM is untrusted input;
- no generic `window.postMessage` privileged bridge;
- extension rejects commands for unmanaged tabs;
- no full conversation-content logging by default;
- no screenshot dependency.

## 14. Reliability/concurrency

- idempotent `worker.spawn` when supplied an idempotency key;
- command ACK distinct from completion;
- pending commands survive executor disconnect;
- restart replays only incomplete commands;
- extension restart restores/verifies bindings where possible;
- root can reconstruct state after interruption with `run.get`, `worker.list`, `events.list`;
- all waits bounded;
- conservative defaults: 2 concurrent launches, 4 active managed ChatGPT workers, one in-flight send per conversation; configurable, not architectural caps.

## 15. Testing policy

No live browser tests, screenshots, or ChatGPT interaction on the user's workstation display.

Layers:

1. protocol/schema tests;
2. core state-machine tests;
3. persistence restart/idempotency tests;
4. extension background tests with mocked WebExtension APIs;
5. DOM-fixture adapter tests;
6. Firefox/Chromium package/manifest validation;
7. live browser smoke only on designated isolated buildboxes (`debian1`, `debian2`, `debian3`) or another explicitly isolated display.

Any live ChatGPT-account test uses a deliberately provisioned isolated profile and never the user's active browser session.

## 16. MVP acceptance

1. Root spawns at least two ChatGPT-Web workers through MCP.
2. Firefox extension creates two background ChatGPT chats without Playwright/CDP.
3. Each child attaches to the correct distinct assignment.
4. Child can message root while root loops on `events.wait`; root reply reaches child without manual copying.
5. Idle child can be woken for follow-up in the same managed conversation.
6. Orchestrator/extension reconnect does not duplicate work or chats.
7. Extension cannot control unrelated ChatGPT tabs.
8. Firefox live smoke passes; Chromium distribution passes compatibility/package checks and equivalent smoke when an isolated profile exists.
9. No undocumented ChatGPT backend API is required.
10. No test touches the user's active workstation browser/display.

## 17. Deferred

Branch-at-parent-message, automatic Project selection/creation, Responses/Codex/Claude executors, ACP/A2A gateway, orchestration dashboard, rich artifact transport, multi-user tenancy, remote browser executors, automatic model/tier routing.

## 18. Authority

This file is authoritative. If implementation exposes a contradiction or missing trust boundary, amend `SPEC.md` and `PLAN.md` before coding around it.