@cotal-ai/connector-codex 0.1.4 → 0.16.0

package/dist/app-server.d.ts

@@ -0,0 +1,208 @@
+import { EventEmitter } from "node:events";
+/** A thread item as the notifications carry it — only the fields the host reads. */
+export interface ThreadItem {
+    type?: string;
+    id?: string;
+    text?: string;
+    /** agentMessage: `commentary` (preamble) or `final_answer`. */
+    phase?: string;
+    /** commandExecution */
+    command?: string;
+    exitCode?: number | null;
+    /** mcpToolCall */
+    tool?: string;
+    status?: string;
+    arguments?: unknown;
+    [k: string]: unknown;
+}
+/** Terminal turn statuses (`inProgress` is the only non-terminal one). */
+export type TurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
+/** Where (and with what credential) the real Codex TUI can attach to this agent's thread. */
+export interface RemoteEndpoint {
+    /** `ws://127.0.0.1:<port>` — loopback only; the child refuses to bind anything else. */
+    url: string;
+    /** The capability token the listener requires (also on disk, 0600, inside CODEX_HOME). */
+    token: string;
+    /** Absolute path of that token file. */
+    tokenFile: string;
+}
+export interface DriverOpts {
+    /** The agent's working directory (the thread's cwd). */
+    cwd: string;
+    /** Per-agent CODEX_HOME (isolation boundary: operator MCP servers / hooks / config never load). */
+    codexHome: string;
+    /** `-c key=value` config overrides for the child (model, effort, approval/sandbox policy …). */
+    configOverrides: readonly (readonly [string, string])[];
+    /** Persona → `thread/start.developerInstructions`. */
+    developerInstructions?: string;
+    /** Extra env for the child, applied AFTER the COTAL_* scrub. The MCP bearer token rides here:
+     *  the child genuinely needs that one capability, while everything else COTAL_* stays hidden.
+     *  (That token is host-lifetime — the endpoint outlives app-server restarts — unlike the
+     *  websocket capability token, which is minted fresh per incarnation.) */
+    extraEnv?: Record<string, string>;
+    /** Binary override (tests point this at a fake server). */
+    bin?: string;
+    log?: (m: string) => void;
+}
+/**
+ * Emits:
+ *  - `"turnStarted"` (turnId, owned)                   — a turn began (→ working)
+ *  - `"turnCompleted"` ({turnId, status, owned})       — a turn reached a terminal status.
+ *    `owned` is false for a turn the attached TUI started: this host may observe it, but only
+ *    a turn it started itself may finalize its own delivery accounting.
+ *  - `"itemStarted"` / `"itemCompleted"` (item, turnId) — thread items (feed/transcript/presence)
+ *  - `"waiting"` (detail)                              — an approval was requested (auto-answered)
+ *  - `"closed"` (code)                                 — the child exited
+ */
+export declare class AppServerDriver extends EventEmitter {
+    private child?;
+    private ws?;
+    private nextId;
+    private readonly pending;
+    private threadId?;
+    /** Every turn currently running on the thread — OURS and the attached TUI's alike. The
+     *  app-server broadcasts turn lifecycle to every client, so with a UI attached this host sees
+     *  turns it did not start. A single "the active turn" slot cannot model that: a foreign turn
+     *  would overwrite ours, and whichever terminal arrived second would be discarded as stale,
+     *  wedging the delivery loop on a boundary that never comes. */
+    private readonly liveTurns;
+    /** The subset of {@link liveTurns} this host started, recorded from the `turn/start` RESPONSE
+     *  as it is decoded — synchronously, in wire order. It cannot be recorded in the awaited
+     *  continuation instead: that runs as a later microtask, so a frame packing
+     *  response+started+completed would finalize the turn before we ever claimed it. */
+    private readonly ownedTurns;
+    /** Request ids of `turn/start` calls sent and not yet answered. While one is outstanding, a
+     *  terminal for a turn we have not claimed is AMBIGUOUS — it may be the turn that request is
+     *  about to name, whose notifications overtook its response. JSON-RPC does not order a
+     *  notification after the response to a request in flight, so this cannot be assumed away. */
+    private readonly pendingStarts;
+    /** Terminals held back by that ambiguity, in arrival order, each carrying whether its turn was
+     *  ever seen live. Drained the moment no `turn/start` is outstanding, so each one is finally
+     *  classified against a settled ownership set by the same rule the live path uses. */
+    private buffered;
+    /** Turns whose terminal this incarnation has already seen. `turn/started`, `turn/completed`,
+     *  and the `turn/start` response are independently ordered, so a start can arrive AFTER its own
+     *  terminal — and a turn re-added to {@link liveTurns} then has no terminal left to remove it,
+     *  which reads as permanently `busy` and stops delivery for good. Bounded: a late start follows
+     *  its terminal by milliseconds, so only a short tail is worth remembering, and the whole set
+     *  dies with the thread on finalize. */
+    private readonly finishedTurns;
+    /** Per-incarnation record of what codex says about each configured MCP server, from its
+     *  `mcpServer/startupStatus/updated` notifications. Kept as state rather than consumed as an
+     *  event because the `ready` can land before anyone waits for it. */
+    private readonly mcpStatus;
+    private readonly mcpWaiters;
+    /** Set by {@link stop}: this driver has been torn down ON PURPOSE, so the child's death is
+     *  expected and must not be recovered from. */
+    private terminal;
+    /** Which app-server incarnation is current. Stamped by {@link start} before its first await,
+     *  so a caller reading {@link gen} on the next line holds ITS OWN incarnation's id — including
+     *  on the failure path, where there is no return value to carry one. */
+    private generation;
+    /** Has this driver been deliberately stopped? The host's crash rail asks before restarting. */
+    get stopped(): boolean;
+    /** The current incarnation's id (see {@link generation}). */
+    get gen(): number;
+    /**
+     * Does `gen` still name the LIVE app-server? Every await in the host's launch/restart tails is
+     * a point where the child can die and the crash rail can bring up a replacement. A tail that
+     * kept going would set the context id, mark the peer ready, replace the TUI and drive over an
+     * incarnation it no longer owns — and its failure branch would `die()`/`stop()` the SUCCESSOR's
+     * child, turning one crash into a dead agent. Stale tails must return, silently.
+     *
+     * A DELIBERATE stop invalidates every tail too, and does not bump the generation — the child is
+     * not being replaced, it is being retired. Without `!terminal` here, a shutdown landing while a
+     * tail awaits startup or readiness leaves that tail authoritative: its failure branch turns a
+     * requested clean exit into a fatal one, and its success branch marks the peer ready and drives
+     * into a mesh that is already being torn down.
+     */
+    isCurrent(gen: number): boolean;
+    private endpoint?;
+    private readonly opts;
+    private readonly log;
+    /** Where the TUI attaches. Defined once {@link start} has resolved. */
+    get remote(): RemoteEndpoint | undefined;
+    get thread(): string | undefined;
+    constructor(opts: DriverOpts);
+    get busy(): boolean;
+    /** The turn to steer into or interrupt: OURS if one is running, else the human's. (Steering a
+     *  peer message into a TUI-owned turn is deliberate — the person sees it — and safe, because
+     *  only a turn we own can ack, so anything steered elsewhere simply redelivers.) */
+    get currentTurnId(): string | undefined;
+    /** Our own live turn, if any — the only one this host may interrupt or finalize. */
+    private get ownTurnId();
+    /** Spawn `codex app-server`, initialize, and start the thread. Resolves with the thread id.
+     *  Re-callable: the host restarts a crashed app-server in place (same mesh lifecycle). */
+    start(): Promise<string>;
+    /** Dial the child's websocket, presenting the capability token. Rejects (rather than hanging)
+     *  on a refused or unauthorized handshake. */
+    private connect;
+    /** The model the thread actually started with (config default or `-c model` override). */
+    private startedModel?;
+    get model(): string | undefined;
+    /** Begin a new user turn — wakes the session. The active turn id is adopted from the
+     *  `turn/started` NOTIFICATION, never from this response: notifications are processed in wire
+     *  order inside the read loop, so `turn/started` always precedes `turn/completed`, and by the
+     *  time a terminal event is handled the id is set. Adopting from the awaited response instead
+     *  would run as a later microtask — after a same-chunk `turn/started`+`turn/completed` already
+     *  cleared the id — and would resurrect the dead turn (falsely busy forever). */
+    startTurn(text: string): Promise<void>;
+    /** Inject input into the turn currently in flight (true mid-turn steer). Returns false when
+     *  there is no active turn or it just ended — the caller falls back to {@link startTurn} at the
+     *  next turn boundary. `expectedTurnId` makes the injection race-safe: if the turn we aimed at
+     *  already completed, the server rejects instead of silently binding to a newer turn. */
+    steer(text: string): Promise<boolean>;
+    /**
+     * Block until codex reports the named MCP server READY, or fail.
+     *
+     * Without this the peer can come online MUTE: the thread starts fine, presence publishes, the
+     * agent soaks deliveries — and every turn discovers it has no cotal_* tools, because the one
+     * server carrying them never finished connecting. A tool-less mesh peer is exactly the silent
+     * degradation this codebase refuses, so an unready server is fatal, not a warning.
+     *
+     * `gen` is the caller's incarnation ({@link gen}, captured right after {@link start}). Readiness
+     * is a fact about ONE app-server child: without this fence a caller whose child died before it
+     * even registered here would wait, see the REPLACEMENT's `ready`, and continue as though its
+     * own generation had come up.
+     */
+    awaitMcpReady(name: string, gen: number, timeoutMs?: number): Promise<void>;
+    /** The account state Codex reports (`account/read`): `account` is null when no credentials
+     *  resolve; `requiresOpenaiAuth` is false for fully custom model providers. */
+    readAccount(): Promise<{
+        account?: unknown;
+        requiresOpenaiAuth?: boolean;
+    }>;
+    /** Cancel the in-flight turn, if any (its surfaced messages then redeliver — see host.ts). */
+    interrupt(): Promise<void>;
+    /**
+     * Stop for good. DELIBERATE teardown, so it is marked terminal first: the child's death would
+     * otherwise reach the host's crash-recovery rail, which would spawn a REPLACEMENT app-server
+     * while the caller is busy exiting — leaving a listening codex orphaned behind a dead host.
+     *
+     * It also REAPS rather than just signalling. A SIGTERM that returns immediately leaves the
+     * caller free to exit while the child is still winding down; a listening app-server is not
+     * reaped by our pipes closing the way a stdio child was.
+     */
+    stop(): Promise<void>;
+    private consecutiveTimeouts;
+    private request;
+    private notify;
+    private writeLine;
+    /** One websocket frame. Unlike a byte stream a frame is already a COMPLETE unit — there is no
+     *  partial message to carry across reads, and waiting for a trailing newline that framing does
+     *  not require would stall the protocol forever. A frame may still pack several newline-
+     *  delimited messages, so split, and process them in wire order. */
+    private onData;
+    private dispatch;
+    private onServerRequest;
+    /** Emit the terminals held while ownership was undecidable. Once no `turn/start` is outstanding
+     *  the ownership set is settled, so each held turn gets its true `owned` — including one that
+     *  completed before the response that claimed it ever arrived. */
+    /** Tombstone a turn whose terminal has been seen, keeping only a short recent tail — a late
+     *  `turn/started` follows its terminal by milliseconds, so unbounded history buys nothing while
+     *  a long-lived agent would accumulate one entry per turn forever. */
+    private markFinished;
+    private releaseBuffered;
+    private onNotification;
+}
+//# sourceMappingURL=app-server.d.ts.map

package/dist/app-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-server.d.ts","sourceRoot":"","sources":["../src/app-server.ts"],"names":[],"mappings":"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"}

package/dist/extension.d.ts

@@ -1,11 +1,3 @@
 import { type Connector } from "@cotal-ai/core";
-/**
- * The Codex connector: launches `codex` with the cotal MCP server injected via `-c` overrides,
- * so the session joins the mesh as a lateral peer. Codex is **pull-only** — it sandboxes
- * lifecycle hooks (they can't reach the connector's control socket), so there are no hooks: the
- * agent reads its inbox with `cotal_inbox` and reports presence with `cotal_status`. The overrides
- * live in memory only — the operator's `~/.codex` (auth, model, their own servers) is never
- * written. Self-registers on import; the manager resolves it by agent type "codex".
- */
 export declare const codexConnector: Connector;
 //# sourceMappingURL=extension.d.ts.map

package/dist/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,SAAS,EAAoC,MAAM,gBAAgB,CAAC;AAW5F;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,SAgC5B,CAAC"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAaA,OAAO,EAA2B,KAAK,SAAS,EAAuE,MAAM,gBAAgB,CAAC;AAuG9I,eAAO,MAAM,cAAc,EAAE,SAoH5B,CAAC"}

package/dist/host-main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=host-main.d.ts.map

package/dist/host-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-main.d.ts","sourceRoot":"","sources":["../src/host-main.ts"],"names":[],"mappings":""}

package/dist/host.d.ts

@@ -0,0 +1,2 @@
+export declare function runCodexHost(): Promise<void>;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAqQA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAwpBlD"}