@mclawnet/codex-adapter 0.1.0

package/dist/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { ModelDescriptor, ModeDescriptor } from "@mclawnet/shared";
+export declare const CODEX_MODELS: ModelDescriptor[];
+export declare const CODEX_MODES: ModeDescriptor[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKxE,eAAO,MAAM,YAAY,EAAE,eAAe,EAkBzC,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,cAAc,EAIvC,CAAC"}

package/dist/catalog.js

@@ -0,0 +1,29 @@
+// PROVISIONAL — not verified against `codex --help` on a real install.
+// Update once we have a way to query codex's accepted model list at runtime.
+// `code` values must be ones OpenAI's API accepts (codex CLI passes via -c model="...").
+export const CODEX_MODELS = [
+    {
+        code: "gpt-4o",
+        label: "GPT-4o",
+        tier: "premium",
+        contextWindow: 128_000,
+        supportsVision: true,
+        supportsToolUse: true,
+        default: true,
+    },
+    {
+        code: "gpt-4o-mini",
+        label: "GPT-4o mini",
+        tier: "standard",
+        contextWindow: 128_000,
+        supportsVision: true,
+        supportsToolUse: true,
+    },
+];
+// codex 的 mode = sandbox_mode
+export const CODEX_MODES = [
+    { code: "read-only", label: "Read Only", description: "No FS writes" },
+    { code: "workspace-write", label: "Workspace Write", description: "Write inside cwd only", default: true },
+    { code: "full-access", label: "Full Access", description: "No sandbox" },
+];
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,6EAA6E;AAC7E,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC7C;QACE,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,QAAQ;QACf,IAAI,EAAE,SAAS;QACf,aAAa,EAAE,OAAO;QACtB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,IAAI;QACrB,OAAO,EAAE,IAAI;KACd;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,UAAU;QAChB,aAAa,EAAE,OAAO;QACtB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,IAAI;KACtB;CACF,CAAC;AAEF,8BAA8B;AAC9B,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,EAAE,IAAI,EAAE,WAAW,EAAQ,KAAK,EAAE,WAAW,EAAQ,WAAW,EAAE,cAAc,EAAE;IAClF,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,uBAAuB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC1G,EAAE,IAAI,EAAE,aAAa,EAAM,KAAK,EAAE,aAAa,EAAM,WAAW,EAAE,YAAY,EAAE;CACjF,CAAC"}

package/dist/codex-adapter.d.ts

@@ -0,0 +1,171 @@
+import { type ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import type { BackendAdapter, BackendProcess, PermissionDecision, PermissionRequest, SpawnOptions } from "@mclawnet/backend-types";
+import type { BackendManifestEntry } from "@mclawnet/shared";
+import { JsonRpcClient } from "./json-rpc-client.js";
+import { type ApprovalWireFamily } from "./permission-mapper.js";
+import { type DetectResult } from "./detect.js";
+/** Test-only: clear the resolved-bin cache between cases. */
+export declare function __resetResolvedCodexBinCache(): void;
+/** Test-only: how many times resolveCodexBin actually ran (i.e. cache misses). */
+export declare function __getResolveCodexBinCallCount(): number;
+/**
+ * Resolve how to spawn codex without invoking cmd.exe on Windows.
+ *
+ * codex.cmd is an npm shim that dispatches to the real Rust .exe (or in
+ * some installs, a node-shimmed cli.js). Spawning the .cmd directly:
+ *   - requires `shell: true` post-CVE-2024-27980, which would also have to
+ *     deal with cmd.exe's 8191-char command-line cap.
+ *   - drops the child's stdio attachment in subtle ways through cmd.exe.
+ *
+ * So we parse the shim and spawn the underlying .exe (or `node cli.js`)
+ * directly. Mirrors claude-adapter's resolveSpawnTarget pattern.
+ */
+export declare function resolveSpawnTarget(codexBin: string): {
+    command: string;
+    prefixArgs: string[];
+};
+/**
+ * Per-process state wrapper. Holds the JSON-RPC client + pending approval
+ * resolvers so `respondToPermission` can find the right server-initiated
+ * request id to reply to.
+ */
+export declare class CodexProcess extends EventEmitter implements BackendProcess {
+    readonly id: string;
+    readonly workDir: string;
+    pid?: number;
+    proc?: ChildProcess;
+    private killed;
+    /** callId → JSON-RPC server-request id we still owe a result to. */
+    pendingApprovals: Map<string, number>;
+    /** callId → originating wire family (drives v2/legacy/mcp reply shape). */
+    approvalMethods: Map<string, ApprovalWireFamily>;
+    /** Monotonic counter for approval resolver keys. */
+    private nextResolverKey;
+    /** Resolver registered by the rpc client for each pending approval. */
+    approvalResolvers: Map<number, (reply: Record<string, string>) => void>;
+    rpc?: JsonRpcClient;
+    backendSessionId?: string;
+    /**
+     * Thread id to resume on agent restart. When set, handshake() sends
+     * `thread/resume { threadId }` instead of `thread/start { cwd }`.
+     * Set from SpawnOptions.resumeId in CodexAdapter.spawn(). Must NOT be
+     * passed as `--resume` CLI flag — app-server rejects it.
+     */
+    resumeId?: string;
+    /** True once `initialize` round-trip + `thread/start` (or `thread/resume`) have completed. */
+    handshakeComplete: boolean;
+    /** Inputs queued by send() while the handshake is still in flight. */
+    pendingInputs: string[];
+    /**
+     * Per-itemId accumulator of assistant text already emitted via
+     * `item/agentMessage/delta` chunks. Consulted on `item/completed` with
+     * `item.type === "agentMessage"` to decide what (if anything) of the
+     * completed payload still needs to be emitted. Without this, codex
+     * delivers the same assistant text twice (deltas + final) and the UI
+     * renders "Hello worldHello world".
+     *
+     * Entries are cleared per item when the matching `item/completed` fires.
+     * We do NOT clear the whole map on `turn/completed`: codex's wire
+     * doesn't strictly guarantee that every item/completed precedes its
+     * parent turn/completed, and a trailing item/completed against an empty
+     * accumulator would re-emit the full text (reactivating the bug). To
+     * cap unbounded growth from interrupted turns that never fire
+     * completed, the map is size-bounded with FIFO eviction; in practice a
+     * single turn produces 1-2 agentMessage items so the cap is generous.
+     */
+    assistantTextSeen: Map<string, string>;
+    /** Temp file for briefing injection; cleaned up on kill(). */
+    briefingFile?: string;
+    /**
+     * Set by CodexAdapter.spawn() so handshake() can surface real process-exit
+     * info if the codex CLI died (e.g. arg parse error). Without this, a dead
+     * process leads to a generic "handshake timeout" instead of the actual
+     * "error: unexpected argument …" stderr message.
+     *
+     * Default returns (null, "") for tests that construct CodexProcess
+     * directly without going through spawn() (e.g. attachRpc mock pipes).
+     * spawn() overrides these with real getters wired to the child process.
+     */
+    getExitInfo: () => {
+        code: number | null;
+        signal: string | null;
+    } | null;
+    getStderr: () => string;
+    /** Allocate a resolver key. Monotonic; never reused. */
+    allocResolverKey(): number;
+    constructor(sessionId: string, workDir: string, proc?: ChildProcess);
+    kill(): Promise<void>;
+    isAlive(): boolean;
+}
+export interface CodexAdapterOptions {
+    /** Override path to the codex binary. Default: lookup in PATH. */
+    codexBin?: string;
+    /**
+     * Max time to wait for codex handshake (initialize + thread/start|resume)
+     * to complete before emitting an error. Default: 15s. Used to detect the
+     * case where the codex process dies mid-handshake (CLI parse error,
+     * crash) — without this, pendingInputs stack up forever and the swarm
+     * silently stalls.
+     */
+    handshakeTimeoutMs?: number;
+    /**
+     * Override the CLI detection probe. Defaults to `detectCodexInstall`.
+     * Exposed for tests (ESM module exports aren't configurable, so we
+     * inject the dependency instead of spying on the module).
+     */
+    detect?: () => Promise<DetectResult>;
+}
+/**
+ * CodexAdapter — BackendAdapter wrapping `codex app-server --listen stdio://`.
+ *
+ * M3.S3 scope: spawn/stop/send/onOutput plus the permission flow
+ * (`onPermissionRequest` / `respondToPermission`). Resume + token-budget +
+ * MCP plumbing land in follow-up slices.
+ */
+export declare class CodexAdapter implements BackendAdapter {
+    readonly type = "codex";
+    private codexBin;
+    private handshakeTimeoutMs;
+    private detect;
+    constructor(options?: CodexAdapterOptions);
+    spawn(options: SpawnOptions): Promise<CodexProcess>;
+    private buildMcpServerConfig;
+    /**
+     * Bind a CodexProcess to a JSON-RPC duplex. Public so tests can inject a
+     * mocked stdin/stdout pair without spawning a real subprocess.
+     *
+     * Drives the v2 handshake automatically: `initialize` → `thread/start`.
+     * Once `thread/start` resolves, `cp.backendSessionId` is set and a
+     * `session_started` event fires so the agent's hub bridge can persist it.
+     */
+    attachRpc(cp: CodexProcess, stdin: NodeJS.WritableStream, stdout: NodeJS.ReadableStream): void;
+    private handshake;
+    private wireRpc;
+    private handleServerRequest;
+    private handleNotification;
+    /**
+     * Selective notification logging. The previous catch-all `log.debug("codex
+     * notification")` fired for every streaming `item/agentMessage/delta` chunk
+     * (many per turn), drowning the actually useful events. Instead, log only
+     * structural events at INFO and surface unrecognised methods as WARN so the
+     * `{kind:"raw"}` degradation isn't silent.
+     */
+    private logBackendOutput;
+    stop(process: BackendProcess): Promise<void>;
+    send(process: BackendProcess, input: string): void;
+    private dispatchTurn;
+    onOutput(process: BackendProcess, handler: (msg: unknown) => void): void;
+    onPermissionRequest(process: BackendProcess, handler: (req: PermissionRequest) => void): void;
+    respondToPermission(process: BackendProcess, decision: PermissionDecision): Promise<void>;
+    onTurnComplete(process: BackendProcess, handler: (info: {
+        backendSessionId?: string;
+    }) => void): void;
+    onSessionStarted(process: BackendProcess, handler: (info: {
+        backendSessionId: string;
+    }) => void): void;
+    onError(process: BackendProcess, handler: (err: Error) => void): void;
+    onExit(process: BackendProcess, handler: (code: number | null) => void): void;
+    getManifest(): Promise<BackendManifestEntry>;
+}
+//# sourceMappingURL=codex-adapter.d.ts.map

package/dist/codex-adapter.d.ts.map

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