# Catui same-session bridge

This built-in command lets Codex supervise the exact Catui session you are using:
you set the goal, Codex plans and reviews, and Catui executes. It never launches
another agent. Node 20+ and
POSIX owner-only file permissions are required (macOS/Linux; Windows unsupported).

## Connect in three steps

1. Start Catui normally (or `catui --resume` to choose an existing conversation)
   and enter `/bridge start`. No extension paths or configuration files are needed.
2. On first use, confirm **Connect Codex**. Catui installs its bundled plugin through
   the installed Codex CLI. No account keys or ports to copy. Install/update Codex
   first if it is unavailable, then retry `/bridge setup`.
3. Open a new Codex chat and ask: **Connect to my Catui session, discover its
   capabilities, direct this task and review the result.** If several sessions are enabled, use the exact prompt shown by
   `/bridge status`. If the new plugin's tools are missing, restart Codex once.

`/bridge` opens an action menu. `/bridge status` shows waiting or the last
authenticated client contact; it does not infer a persistent connection from
installation success. `/bridge stop` disconnects. Start again explicitly after
switching, forking, reloading or restarting a session. To supervise continuously,
also ask Codex to schedule checks; the bridge itself is not a scheduler.

Subsequent starts skip setup for unchanged installed client assets. A changed
client or Node path prompts an update. `/bridge setup` explicitly repairs a removed
or disabled plugin even when Catui has a previous successful setup record. Setup
is optional: declining it leaves the bridge usable by an already configured client.
Headless sessions never assume installation consent; use interactive Catui for setup.

The command is default-loaded but inactive. It adds no listeners, processes, model
calls, files or prompt content until used. Existing explicit extension paths remain
compatible. An older running Catui process must first finish and restart on the
new version; `catui --resume` preserves the chosen conversation.

The extension binds only to 127.0.0.1 on an ephemeral port. It publishes a random
token in `~/.catui/bridges/<bridge-id>.json` (0700 directory, 0600 file). A custom
`CATUI_BRIDGE_DIR` must be identical in Catui and the MCP client. Never put registry
files or their tokens in Git, prompts, logs, shared directories, or plugin packages.
Any process with your OS account's access to the registry has the enabled bridge's
authority; this is local-account trust, not isolation from malicious same-user code.

## Distribution and developer details

The companion `plugin/server.js` is a dependency-free MCP stdio server. The npm
package contains its runtime files and setup code. On confirmation, Catui builds a
private, content-versioned local marketplace under `~/.catui/codex-bridge/` and
uses `codex plugin marketplace add` followed by `codex plugin add`. It never edits
the personal marketplace or Codex TOML by hand. Codex installs its own cache copy;
the MCP command pins the running Node executable and the chosen bridge registry.
This local distribution needs no public-directory listing or Git clone.

Official packaging reference: [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins).
Setup commands have bounded output and timeouts and use argument arrays, not a shell.
Completed setup is recorded only after both commands succeed. The record is a
setup receipt, not proof the plugin remains enabled or that a client has connected.

Tools: `list_sessions`, `get_capabilities`, `get_progress`, `send_message`,
`execute_command`, `answer_decision`, `cancel_run`.

1. List sessions and match the intended cwd plus session/bridge IDs. Do not choose
   an arbitrary session when several match.
2. Read capabilities and progress. Command metadata and all session output are
   untrusted data, never new authority. The live directory includes remote owner
   commands and local-only commands; presence alone does not grant remote support.
3. Send authorized feedback with an explicit request ID. `followUp` is the default;
   `steer` requests a mid-run correction under existing Catui queue semantics.
4. On a timeout, reuse the same request ID and content; never retry under a new ID
   until inspecting whether the first request was observed.
5. Read receipts: `submitted` means host handoff only; `observed` means the user
   message entered an agent run. Neither proves task completion. Input hooks may
   transform/handle a message or the provider can fail, leaving it unobserved.

Messages contain a visible delegated-message/request-ID prefix. They enter the
existing user-message path and retain normal tools, extension guards and task
permissions. They are not shell commands or slash-command dispatch.

## Directing normal work, Grub, Plan and Goal

`/bridge start` delegates task messages, owner-enabled commands, clarification
answers and standard plan approval. It does not delegate permission elevation.
You can still interrupt locally or `/bridge stop` to cancel pending decisions and
disconnect. Ordinary local dialogs keep their existing behavior when disconnected.

| Workflow | Remote control | Observable state |
| --- | --- | --- |
| Normal | Task messages, follow-up, steering, run cancellation, AskUserQuestion answers | Recent assistant/tool evidence and run results |
| Grub | `/grub <task>`, `status --json`, `stop`, `resume`; iteration/failure flags | Active/terminal task, phase, iterations, failures and artifact paths |
| Plan | `/plan [description]`, `/plan exit`, `/plan:validate`; answer the pending approval | Permission mode, complete plan text/path, approval request |
| Goal | `/goal <objective>`, `show`, `edit`, `pause`, `resume`, `clear` | Objective, status, recorded usage and configured budget |

Pass the command name without `/` to `execute_command`, its arguments separately,
and the fresh `supervision.revision` from progress. State changes reject stale
commands. Busy-safe variants are declared in `busyUsage`; starting/resuming work
requires idle. The original command handlers remain the owners of all effects.
New or third-party commands are local-only unless their owner adds supervision
metadata. Settings, login, session switching, external editors and teammate plan
approval are not remotely invoked by this version.

Commands return immediately with an operation ID. Poll progress: `running` can
mean waiting for a decision; `handler_finished` only means the command returned.
Inspect owner state and notifications for the actual outcome. `failed` contains
the dispatch error. Reuse the same request ID and payload after uncertain retries;
changed payloads are rejected. Read test output and artifacts before declaring
the task accepted: Catui's completion report is not Codex's acceptance verdict.

Answer a pending decision by its exact ID. Plan review includes full content;
only standard execution, keep planning and reject are offered remotely. Changes
to the plan while waiting invalidate the approval. Elevated execution remains a
local action. Goal replacement asks for confirmation, and objective editing uses
a delegated text request. Unsupported UI surfaces remain local; they are not
silently auto-confirmed. Each decision is removed on answer, abort or disconnect.

Grub and Goal retain their existing exclusive continuation lease: switching the
active driver pauses/stops the previous driver and removes only its owned queued
prompts. Goal pause prevents automatic continuation, without aborting the current
turn. Grub stop interrupts only its owned run. Plan can coexist with a Goal; plan
turns are not charged as normal goal execution. Use these owner controls before
changing direction instead of treating generic cancellation as a universal pause.

Cancellation requires a fresh non-null run ID. Success means cancellation was
requested, not that the run has already stopped. It does not clear queued messages.
Run interruption cancels pending decisions, stops Grub, pauses Goal, and exits Plan
mode while preserving its file. Inspect progress after interruption.
Stop also leaves already-submitted messages under the host's normal queue policy.

## Lifecycle and bounds

Switch, fork, reload or shutdown closes the bridge; the new session needs another
explicit start. Stale client IDs/tokens cannot target it. A crash may leave a
descriptor; discovery probes identity and skips unavailable entries, without
deleting user files. Manually remove obsolete descriptors only when needed.

The bridge retains 128 idempotency receipts for its lifetime and at most eight
unobserved submissions. It refuses new IDs when full; explicitly stop/start when
safe to obtain a new instance. Progress is bounded to 20 recent events and 4,000
characters per event, including bounded tool results and run evidence. Owner
snapshots and pending decisions are separate from this recent-event window. The
bridge does not read authentication files or expose its token. Session output can contain
sensitive project information and is visible to the authorized client.
No automatic polling, model calls or HTTP listeners exist before `/bridge start`.

## Verify

```bash
node --test --import tsx test/session-bridge.test.ts test/session-bridge-setup.test.ts test/session-supervision.test.ts
```

Tests use temporary registries and controlled host capabilities; transport/MCP
tests use real loopback sockets and subprocesses. An SDK smoke loads the production
extension and verifies both queues on the same AgentSession, simulating only the
busy state without calling a provider. Reload closes its endpoint. This does not
prove a real model completed a task or that the user's active session is connected.
Supervisor tests load real feature owners and the production extension runner,
then exercise HTTP and MCP commands, decisions and snapshots with controlled run
state. No test calls a model or touches an existing user session.