# ChatGPT Orchestrator

Private manager/worker orchestration for ChatGPT Web. The control plane is MCP; a Firefox-first WebExtension is the ChatGPT-Web executor.

See [`SPEC.md`](./SPEC.md), [`PLAN.md`](./PLAN.md), the [Execution Continuity operator/developer guide](./docs/EXECUTION-CONTINUITY.md), and the authoritative Execution Continuity design under [`docs/specs`](./docs/specs/execution-continuity-auto-resume.md).

## Workspace

- `packages/protocol` — transport-independent schemas and wire contracts
- `packages/persistence` — durable/in-memory orchestration repositories
- `packages/core` — run/worker/message/event state machine
- `apps/mcp-server` — agent-facing MCP server plus local executor bridge
- `apps/extension` — Firefox/LibreWolf-first, Chromium-compatible ChatGPT-Web executor
- `packages/chatgpt-web-adapter` — isolated semantic ChatGPT DOM adapter
- `skills/durable-continuation-output` — output-only Agent Skill used by long-running workers

## Local runtime

The persistent HTTP MCP runtime binds only to loopback:

```text
MCP                 http://127.0.0.1:8764/mcp
Health              http://127.0.0.1:8764/healthz
Browser executor    ws://127.0.0.1:8765
```

Authentication secrets live outside the repository under `~/.config/chatgpt-orchestrator/` and are created with mode `0600`.

The supplied user services are:

```text
chatgpt-orchestrator.service
chatgpt-orchestrator-tunnel.service
```

The first runs the MCP server/executor bridge. The second runs OpenAI `tunnel-client` against the dedicated `chatgpt-orchestrator` Secure MCP Tunnel. No public inbound listener is required.

See [`docs/OPERATIONS.md`](./docs/OPERATIONS.md) for installation, tunnel, browser-extension, and verification details.

## Extension builds

```bash
pnpm build
node apps/extension/scripts/build.mjs --package
```

Outputs:

```text
dist/firefox/
dist/chromium/
dist/chatgpt-orchestrator-firefox-<version>.xpi
dist/chatgpt-orchestrator-chromium-<version>.zip
```

A local paired deployment may inject the executor token at build time without committing it:

```bash
CHATGPT_ORCHESTRATOR_EXECUTOR_TOKEN="$(cat ~/.config/chatgpt-orchestrator/executor-token)" \
  node apps/extension/scripts/build.mjs --package
```

The paired artifact contains a local executor credential and must be treated as private local deployment material.

### Chromium 142+

Current Chromium applies Local Network Access permission checks to loopback requests. The Chromium build therefore requests only loopback HTTP host access needed for a one-time permission probe and exposes **Allow local executor access** in its options page. After Chromium grants loopback access, the background service worker can use the configured loopback WebSocket executor. Firefox/LibreWolf does not request the Chromium-only loopback HTTP host permission.

## Agent skill

The canonical Agent Skill is intentionally output-only:

```text
skills/durable-continuation-output/SKILL.md
```

Package it with:

```bash
pnpm package:skill
```

The resulting archive is `dist/durable-continuation-output-skill.zip`.

The skill does not contain Retry behavior, `continue` instructions, browser policy, scheduling, or orchestration mechanics. Those are orchestrator/plugin responsibilities.

## Verification

```bash
pnpm gate
pnpm dlx web-ext@latest lint --source-dir dist/firefox --warnings-as-errors
```

Browser qualification is performed only in isolated browser profiles/buildboxes, never against the active workstation browser session. See [`docs/QUALIFICATION.md`](./docs/QUALIFICATION.md).