@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0

package/dist/index.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { codexLocalReasoningEffortsForModel, DEFAULT_CODEX_LOCAL_MODEL, isCodexLocalFastModeSupported, models, normalizeCodexModel, } from "./index.js";
+describe("codex local adapter metadata", () => {
+    it("advertises current Codex-capable OpenAI models without changing the default", () => {
+        const modelIds = models.map((model) => model.id);
+        // Default to the concrete gpt-5.6-sol slug — Codex ships no metadata for the bare gpt-5.6
+        // alias, so it must not be advertised or used as the default (it triggers a fallback warning).
+        expect(DEFAULT_CODEX_LOCAL_MODEL).toBe("gpt-5.6-sol");
+        expect(modelIds.slice(0, 6)).toEqual([
+            "gpt-5.6-sol",
+            "gpt-6-astra",
+            "gpt-6-sol",
+            "gpt-6-luna",
+            "gpt-5.6-terra",
+            "gpt-5.6-luna",
+        ]);
+        expect(modelIds).not.toContain("gpt-5.6");
+        expect(isCodexLocalFastModeSupported(DEFAULT_CODEX_LOCAL_MODEL)).toBe(true);
+        expect(isCodexLocalFastModeSupported("gpt-6-astra")).toBe(true);
+        expect(isCodexLocalFastModeSupported("gpt-6-sol")).toBe(true);
+        expect(modelIds).not.toContain("gpt-5.3-codex");
+        expect(modelIds).not.toContain("gpt-5.3-codex-spark");
+    });
+    it.each(["gpt-6-astra", "gpt-6-sol", " gpt-6-sol ", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6"])("uses the reasoning efforts advertised for %s", (model) => {
+        expect(codexLocalReasoningEffortsForModel(model)).toEqual([
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "max",
+            "ultra",
+        ]);
+    });
+    it.each(["gpt-5.5", "custom-model"])("preserves legacy efforts for %s", (model) => {
+        expect(codexLocalReasoningEffortsForModel(model)).toEqual([
+            "minimal",
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+        ]);
+    });
+    it.each(["gpt-6-luna", "gpt-5.6-luna"])("caps %s at max and supports Fast mode", (model) => {
+        expect(codexLocalReasoningEffortsForModel(model)).toEqual(["low", "medium", "high", "xhigh", "max"]);
+        expect(isCodexLocalFastModeSupported(model)).toBe(true);
+    });
+    it("normalizes the legacy bare gpt-5.6 alias to the concrete gpt-5.6-sol slug", () => {
+        expect(normalizeCodexModel("gpt-5.6")).toBe("gpt-5.6-sol");
+        expect(normalizeCodexModel("  gpt-5.6  ")).toBe("gpt-5.6-sol");
+        // Concrete slugs and unknown/manual model IDs pass through untouched.
+        expect(normalizeCodexModel("gpt-5.6-sol")).toBe("gpt-5.6-sol");
+        expect(normalizeCodexModel("gpt-5.5")).toBe("gpt-5.5");
+        expect(normalizeCodexModel("future-model")).toBe("future-model");
+        expect(normalizeCodexModel("")).toBe("");
+        expect(normalizeCodexModel(null)).toBe("");
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

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

package/dist/server/acp.d.ts

@@ -0,0 +1,30 @@
+import type { AdapterBillingType, AdapterEnvironmentTestContext, AdapterEnvironmentTestResult, AdapterExecutionContext, AdapterExecutionResult } from "@tickernelz/paperclip-pro-adapter-utils";
+import type { AcpxEngineExecutorOptions } from "@tickernelz/paperclip-pro-adapter-utils/acpx-engine/execute";
+export type CodexExecutionEngine = "cli" | "acp";
+export interface CodexEngineSelection {
+    engine: CodexExecutionEngine;
+    explicit: boolean;
+    unavailableReason?: string;
+}
+type CodexEngineResolutionInput = Pick<AdapterExecutionContext, "config"> & Partial<Pick<AdapterExecutionContext, "executionTarget" | "executionTransport">>;
+type CodexAcpExecutorOptions = Omit<AcpxEngineExecutorOptions, "adapterType" | "moduleDir" | "packageRootDir">;
+type CodexAcpExecutor = (ctx: AdapterExecutionContext) => Promise<AdapterExecutionResult>;
+export declare function resolveCodexExecutionEngine(config: Record<string, unknown>): CodexEngineSelection;
+export declare function resolveCodexExecutionEngineForRun(input: CodexEngineResolutionInput): Promise<CodexEngineSelection>;
+export declare function buildCodexAcpConfig(config: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Classify billing the same way the Codex CLI lane does so ACP runs land in
+ * the cost ledger with a real provider/billingType instead of acpx/unknown.
+ * Host env only counts for local execution targets; remote targets see just
+ * the adapter-config env.
+ */
+export declare function resolveCodexAcpBillingIdentity(ctx: Pick<AdapterExecutionContext, "config"> & Partial<Pick<AdapterExecutionContext, "executionTarget" | "executionTransport">>): {
+    provider: string;
+    biller: string;
+    billingType: AdapterBillingType;
+};
+export declare function createCodexAcpExecutor(options?: CodexAcpExecutorOptions): CodexAcpExecutor;
+export declare function nodeVersionMeetsCodexAcpMinimum(version?: string): boolean;
+export declare function testCodexAcpEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
+export {};
+//# sourceMappingURL=acp.d.ts.map

package/dist/server/acp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp.d.ts","sourceRoot":"","sources":["../../src/server/acp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAElB,6BAA6B,EAC7B,4BAA4B,EAC5B,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,yCAAyC,CAAC;AAiBjD,OAAO,KAAK,EACV,yBAAyB,EAG1B,MAAM,6DAA6D,CAAC;AAuBrE,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,KAAK,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,KAAK,0BAA0B,GAC7B,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,uBAAuB,EAAE,iBAAiB,GAAG,oBAAoB,CAAC,CAAC,CAAC;AAEnF,KAAK,uBAAuB,GAAG,IAAI,CACjC,yBAAyB,EACzB,aAAa,GAAG,WAAW,GAAG,gBAAgB,CAC/C,CAAC;AAEF,KAAK,gBAAgB,GAAG,CAAC,GAAG,EAAE,uBAAuB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAS1F,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,oBAAoB,CAEjG;AAED,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,oBAAoB,CAAC,CAuB/B;AAWD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwC5F;AAqID;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,GAC1C,OAAO,CAAC,IAAI,CAAC,uBAAuB,EAAE,iBAAiB,GAAG,oBAAoB,CAAC,CAAC,GACjF;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,kBAAkB,CAAA;CAAE,CAuBvE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAe9F;AAQD,wBAAgB,+BAA+B,CAAC,OAAO,SAAkB,GAAG,OAAO,CAMlF;AA0HD,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,6BAA6B,GACjC,OAAO,CAAC,4BAA4B,CAAC,CA6JvC"}

package/dist/server/acp.js

@@ -0,0 +1,532 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseLocalProcessFilesystemScope, parseLocalProcessNetworkScope, } from "@tickernelz/paperclip-pro-adapter-utils/local-process-sandbox";
+import { inferOpenAiCompatibleBiller } from "@tickernelz/paperclip-pro-adapter-utils";
+import { ensureAdapterExecutionTargetCommandResolvable, readAdapterExecutionTarget, resolveAdapterExecutionTargetCwd, } from "@tickernelz/paperclip-pro-adapter-utils/execution-target";
+import { DEFAULT_ACP_ENGINE_MODE, DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS, DEFAULT_ACP_ENGINE_PERMISSION_MODE, DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS, } from "@tickernelz/paperclip-pro-adapter-utils/acpx-engine/constants";
+import { asNumber, asString, asStringArray, parseObject, } from "@tickernelz/paperclip-pro-adapter-utils/server-utils";
+import { createWorkspaceRestoreTeardown } from "@tickernelz/paperclip-pro-adapter-utils/workspace-restore-teardown";
+import { normalizeCodexModel } from "../index.js";
+import { classifyCodexAuthRefreshFailure } from "./parse.js";
+import { copyBackCodexAuth } from "./codex-auth-copyback.js";
+import { buildCodexAuthInboundProvision } from "./codex-auth-merge-scripts.js";
+import { evaluateCodexCredentialReadiness, resolveSharedCodexHomeDir, stageCodexHomeForSync, } from "./codex-home.js";
+import { ADAPTER_AUTH_MISSING_CHECK_CODE } from "./auth-check.js";
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRootDir = path.resolve(moduleDir, "../..");
+const MIN_ACP_NODE_VERSION = "24.11.0";
+function normalizeEngine(value) {
+    const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+    if (raw === "acp")
+        return { engine: "acp", explicit: true };
+    if (raw === "cli")
+        return { engine: "cli", explicit: true };
+    return { engine: "acp", explicit: false };
+}
+export function resolveCodexExecutionEngine(config) {
+    return normalizeEngine(config.engine);
+}
+export async function resolveCodexExecutionEngineForRun(input) {
+    const selection = normalizeEngine(input.config.engine);
+    // Engine availability must never change the agent's execution or permission contract.
+    if (selection.engine === "cli")
+        return selection;
+    const unavailable = (reason) => ({
+        ...selection,
+        unavailableReason: `${reason} Repair the ACP setup, or explicitly set engine=cli to use the CLI engine.`,
+    });
+    const target = readAdapterExecutionTarget({
+        executionTarget: input.executionTarget,
+        legacyRemoteExecution: input.executionTransport?.remoteExecution,
+    });
+    if (target?.workspaceRealization?.mode === "in_place") {
+        return unavailable("In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.");
+    }
+    const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);
+    const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);
+    if (filesystemScope || networkScope) {
+        return unavailable("Local filesystem/network confinement requires the Codex CLI engine; ACP confinement is not supported.");
+    }
+    const reason = await codexAcpUnavailableReason(input);
+    return reason ? unavailable(reason) : selection;
+}
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return undefined;
+}
+export function buildCodexAcpConfig(config) {
+    const agentCommand = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+    const stateDir = firstNonEmptyString(config.stateDir, config.acpStateDir);
+    const mode = firstNonEmptyString(config.mode, config.acpMode) ?? DEFAULT_ACP_ENGINE_MODE;
+    const permissionMode = firstNonEmptyString(config.permissionMode, config.acpPermissionMode) ??
+        DEFAULT_ACP_ENGINE_PERMISSION_MODE;
+    const nonInteractivePermissions = firstNonEmptyString(config.nonInteractivePermissions, config.acpNonInteractivePermissions) ??
+        DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS;
+    const warmHandleIdleMs = config.warmHandleIdleMs ??
+        config.acpWarmHandleIdleMs ??
+        DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS;
+    // Rewrite legacy model aliases (e.g. bare gpt-5.6) to the concrete slug Codex has metadata for,
+    // so the ACP session config matches the CLI lane and avoids the fallback-metadata warning.
+    const normalizedModel = normalizeCodexModel(typeof config.model === "string" ? config.model : "");
+    const env = parseObject(config.env);
+    let networkAccess = env.PAPERCLIP_CODEX_ACP_NETWORK_ACCESS !== "false";
+    const extraArgs = asStringArray(config.extraArgs);
+    for (const arg of extraArgs.length > 0 ? extraArgs : asStringArray(config.args)) {
+        const match = /^(?:(?:--config=|-c=?)\s*)?sandbox_workspace_write\.network_access\s*=\s*(true|false)\s*$/.exec(arg);
+        if (match)
+            networkAccess = match[1] === "true";
+    }
+    return {
+        ...config,
+        env: { ...env, PAPERCLIP_CODEX_ACP_NETWORK_ACCESS: String(networkAccess) },
+        agent: "codex",
+        mode,
+        permissionMode,
+        nonInteractivePermissions,
+        warmHandleIdleMs,
+        ...(normalizedModel ? { model: normalizedModel } : {}),
+        ...(agentCommand ? { agentCommand } : {}),
+        ...(stateDir ? { stateDir } : {}),
+    };
+}
+/**
+ * Codex remote managed-home seed + auth copy-back for the runner-backed remote
+ * sandbox ACP lane. Mirrors the codex CLI lane (`codex-local/execute.ts`): stage
+ * the managed `CODEX_HOME` (auth.json + config.toml + skills) into the sandbox
+ * as the `home` asset — carrying the inbound auth-merge `provision` and the
+ * outbound `restore` copy-back seams — then repoint `CODEX_HOME` onto the
+ * in-sandbox `assetDirs.home` path. The copy-back rides the asset `restore`,
+ * which fires inside `restoreWorkspace()` at teardown.
+ *
+ * The engine already resolved+seeded the host managed Codex home and set
+ * `env.CODEX_HOME` to it (a HOST path) before this seam runs, so `env.CODEX_HOME`
+ * is exactly the home to stage. Seed inbound and copy-back outbound land together
+ * (never seed-without-copy-back): Codex refresh tokens are single-use, so a
+ * refreshed sandbox token that is never copied back would spend the host's token
+ * and corrupt the host credential.
+ */
+async function prepareCodexRemoteManagedHome(input) {
+    const { env, runId, onLog } = input;
+    // The host managed Codex home the engine seeded and set on env.CODEX_HOME.
+    const effectiveCodexHome = env.CODEX_HOME;
+    if (!effectiveCodexHome) {
+        // No managed home resolved (e.g. custom CODEX_HOME cleared) — stage the
+        // workspace with no home asset, identical to the no-seam fallback.
+        return { stagedRuntime: await input.stage([]) };
+    }
+    // Curated allowlist temp dir (auth/config/skills only); caller owns cleanup.
+    const stagedCodexHomeDir = await stageCodexHomeForSync(effectiveCodexHome, { runId });
+    let stagedRuntime;
+    try {
+        stagedRuntime = await input.stage([
+            {
+                key: "home",
+                localDir: stagedCodexHomeDir,
+                followSymlinks: true,
+                // Inbound (host→sandbox) auth-merge: keeps whichever credential is newer
+                // when the sandbox image already carries a Codex auth.json.
+                provision: buildCodexAuthInboundProvision(),
+                // Outbound (sandbox→host) copy-back at teardown, under the same
+                // direction-agnostic decision predicate + directory merge-lock +
+                // atomic-rename + 0600 guard. Target is the SHARED host auth.json
+                // (the symlink source managed homes point at), never an in-sandbox copy.
+                restore: async ({ assetDir, readFile }) => void (await copyBackCodexAuth({
+                    readSandboxAuth: () => readFile(path.posix.join(assetDir, "auth.json")),
+                    hostAuthPath: path.join(input.config.managedAiConnection ? effectiveCodexHome : resolveSharedCodexHomeDir(process.env), "auth.json"),
+                    log: (line) => onLog("stdout", `${line}\n`),
+                })),
+            },
+        ]);
+    }
+    catch (err) {
+        await fs.rm(stagedCodexHomeDir, { recursive: true, force: true }).catch(() => { });
+        throw err;
+    }
+    // Repoint CODEX_HOME from the HOST path onto the seeded in-sandbox home.
+    env.CODEX_HOME =
+        stagedRuntime.assetDirs.home ??
+            path.posix.join(stagedRuntime.runtimeRootDir ?? "", "home");
+    return {
+        stagedRuntime,
+        // Per-run copy-back: fires on EVERY run's teardown (including a compatible
+        // resume that reuses this staged runtime). It reads the sandbox auth.json /
+        // workspace live and copies back to the host; it does NOT remove the staged
+        // in-sandbox home, so re-running it across resumes can't leave a later run
+        // without its staged home. Host staged-temp removal is deliberately NOT here
+        // — see `disposeStaged` — so caching this runtime for reuse never destroys
+        // resources the next resume needs.
+        // Fail-soft: a teardown copy-back miss loses this rotation and surfaces
+        // loudly as refresh_token_reused on the next host Codex use (re-auth
+        // recovers) — never silent host-credential corruption, so it must not
+        // mask the run result.
+        teardown: createWorkspaceRestoreTeardown({
+            stagedRuntime,
+            onLog,
+            startMessage: "[paperclip] Restoring workspace changes and Codex auth from the sandbox.\n",
+            failurePrefix: "[paperclip] Codex ACP teardown restore/copy-back failed",
+        }),
+        // One-time cleanup of the HOST staged home temp dir. Fired ONLY when the
+        // staged runtime is dropped (failed/cancelled/timed-out turn, incompatible
+        // re-stage, idle eviction) — never on a clean turn that keeps the runtime
+        // warm — so it can't remove the staged home while a reuse still depends on
+        // it. Idempotent: `force: true` no-ops if it was already removed.
+        disposeStaged: async () => {
+            await fs.rm(stagedCodexHomeDir, { recursive: true, force: true }).catch(async (error) => {
+                await onLog("stderr", `[paperclip] Failed to remove staged Codex home "${stagedCodexHomeDir}": ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+        },
+    };
+}
+function withCodexAcpDefaults(options) {
+    return {
+        resolveBillingIdentity: resolveCodexAcpBillingIdentity,
+        prepareRemoteManagedHome: prepareCodexRemoteManagedHome,
+        ...options,
+        adapterType: "codex_local",
+        moduleDir,
+        packageRootDir,
+    };
+}
+function withCodexAuthRefreshFailureClassification(result) {
+    if ((result.exitCode ?? 0) === 0)
+        return result;
+    const resultJson = parseObject(result.resultJson);
+    const stopReason = asString(resultJson.stopReason, "");
+    const authFailure = classifyCodexAuthRefreshFailure({
+        errorMessage: [result.errorMessage ?? "", result.summary ?? "", stopReason]
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .join("\n"),
+    });
+    if (!authFailure)
+        return result;
+    return {
+        ...result,
+        errorCode: authFailure,
+        errorFamily: authFailure,
+        resultJson: {
+            ...(result.resultJson ?? {}),
+            errorFamily: authFailure,
+        },
+    };
+}
+/**
+ * Classify billing the same way the Codex CLI lane does so ACP runs land in
+ * the cost ledger with a real provider/billingType instead of acpx/unknown.
+ * Host env only counts for local execution targets; remote targets see just
+ * the adapter-config env.
+ */
+export function resolveCodexAcpBillingIdentity(ctx) {
+    const envConfig = parseObject(parseObject(ctx.config).env);
+    const target = readAdapterExecutionTarget({
+        executionTarget: ctx.executionTarget,
+        legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
+    });
+    const considerHostEnv = target?.kind !== "remote";
+    const mergedEnv = {
+        ...(considerHostEnv ? process.env : {}),
+        ...Object.fromEntries(Object.entries(envConfig).filter((entry) => typeof entry[1] === "string")),
+    };
+    const apiKey = typeof mergedEnv.OPENAI_API_KEY === "string" && mergedEnv.OPENAI_API_KEY.trim().length > 0;
+    const billingType = apiKey ? "api" : "subscription";
+    const openAiCompatibleBiller = inferOpenAiCompatibleBiller(mergedEnv, "openai");
+    const biller = openAiCompatibleBiller === "openrouter"
+        ? "openrouter"
+        : billingType === "subscription"
+            ? "chatgpt"
+            : openAiCompatibleBiller ?? "openai";
+    return { provider: "openai", biller, billingType };
+}
+export function createCodexAcpExecutor(options = {}) {
+    let executor = null;
+    return async (ctx) => {
+        let currentExecutor = executor;
+        if (!currentExecutor) {
+            const { createAcpxEngineExecutor } = await import("@tickernelz/paperclip-pro-adapter-utils/acpx-engine/execute");
+            currentExecutor = createAcpxEngineExecutor(withCodexAcpDefaults(options));
+            executor = currentExecutor;
+        }
+        const result = await currentExecutor({
+            ...ctx,
+            config: buildCodexAcpConfig(ctx.config),
+        });
+        return withCodexAuthRefreshFailureClassification(result);
+    };
+}
+function parseVersion(version) {
+    const match = version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return [0, 0, 0];
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+export function nodeVersionMeetsCodexAcpMinimum(version = process.version) {
+    const [major, minor, patch] = parseVersion(version);
+    const [minMajor, minMinor, minPatch] = parseVersion(MIN_ACP_NODE_VERSION);
+    if (major !== minMajor)
+        return major > minMajor;
+    if (minor !== minMinor)
+        return minor > minMinor;
+    return patch >= minPatch;
+}
+async function pathExists(candidate) {
+    return fs.access(candidate).then(() => true).catch(() => false);
+}
+function hasPathSeparator(command) {
+    return command.includes("/") || command.includes("\\");
+}
+function looksLikeShellCommand(command) {
+    return /\s/.test(command.trim());
+}
+async function findCommandOnPath(binName) {
+    const pathValue = process.env.PATH ?? "";
+    for (const segment of pathValue.split(path.delimiter)) {
+        if (!segment)
+            continue;
+        const candidate = path.join(segment, binName);
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return null;
+}
+async function findAncestorBin(startDir, binName) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, "node_modules", ".bin", binName);
+        if (await pathExists(candidate))
+            return candidate;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+async function commandIsResolvable(command, input) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return false;
+    if (looksLikeShellCommand(trimmed))
+        return true;
+    const target = readAdapterExecutionTarget({
+        executionTarget: input?.executionTarget,
+        legacyRemoteExecution: input?.executionTransport?.remoteExecution,
+    });
+    if (target?.kind === "remote") {
+        try {
+            await ensureAdapterExecutionTargetCommandResolvable(trimmed, target, resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()), process.env);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (path.isAbsolute(trimmed) || hasPathSeparator(trimmed))
+        return pathExists(trimmed);
+    return (await findCommandOnPath(trimmed)) !== null;
+}
+async function resolveCodexAcpCommand(config) {
+    const configured = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+    if (configured)
+        return configured;
+    return ((await findAncestorBin(packageRootDir, "codex-acp")) ??
+        (await findCommandOnPath("codex-acp")) ??
+        path.join(packageRootDir, "node_modules", ".bin", "codex-acp"));
+}
+function sandboxTargetHasProcessSessionBridge(target) {
+    return target?.kind === "remote" && target.transport === "sandbox" && Boolean(target.runner);
+}
+async function resolveCodexAcpCommandForTarget(config, target) {
+    const configured = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+    if (configured)
+        return configured;
+    if (target?.kind === "remote")
+        return "codex-acp";
+    return resolveCodexAcpCommand(config);
+}
+async function codexAcpUnavailableReason(input) {
+    const target = readAdapterExecutionTarget({
+        executionTarget: input.executionTarget,
+        legacyRemoteExecution: input.executionTransport?.remoteExecution,
+    });
+    if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
+        if (target.transport === "sandbox") {
+            return "Codex ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
+        }
+        return "Codex ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
+    }
+    if (!nodeVersionMeetsCodexAcpMinimum()) {
+        return `Node ${process.version} (${process.execPath}) does not satisfy Codex ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
+    }
+    const command = await resolveCodexAcpCommandForTarget(input.config, target);
+    if (!(await commandIsResolvable(command, input))) {
+        return `Codex ACP server command is not available: ${command}.`;
+    }
+    return null;
+}
+function summarizeStatus(checks) {
+    if (checks.some((check) => check.level === "error"))
+        return "fail";
+    if (checks.some((check) => check.level === "warn"))
+        return "warn";
+    return "pass";
+}
+function isNonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export async function testCodexAcpEnvironment(ctx) {
+    const checks = [];
+    const config = parseObject(ctx.config);
+    const target = ctx.executionTarget ?? null;
+    const targetIsRemote = target?.kind === "remote";
+    const targetIsSandbox = target?.kind === "remote" && target.transport === "sandbox";
+    checks.push({
+        code: "codex_engine_selected",
+        level: "info",
+        message: "Execution engine selected: ACP.",
+        hint: "Set engine=cli to use the existing Codex CLI lane.",
+    });
+    if (targetIsRemote) {
+        checks.push({
+            code: "codex_acp_remote_target",
+            level: "info",
+            message: "Codex ACP will run against the remote execution environment.",
+            hint: "Remote ACP requires a bidirectional process target such as SSH or Paperclip's sandbox process-session bridge.",
+        });
+    }
+    const cwd = asString(config.cwd, process.cwd());
+    try {
+        await fs.mkdir(cwd, { recursive: true });
+        checks.push({
+            code: "codex_acp_cwd_valid",
+            level: "info",
+            message: `Working directory is valid: ${cwd}`,
+        });
+    }
+    catch (err) {
+        checks.push({
+            code: "codex_acp_cwd_invalid",
+            level: "error",
+            message: err instanceof Error ? err.message : "Invalid working directory",
+            detail: cwd,
+        });
+    }
+    checks.push({
+        code: nodeVersionMeetsCodexAcpMinimum() ? "codex_acp_node_supported" : "codex_acp_node_unsupported",
+        level: nodeVersionMeetsCodexAcpMinimum() ? "info" : "error",
+        message: nodeVersionMeetsCodexAcpMinimum()
+            ? `Node ${process.version} satisfies ACP runtime requirements.`
+            : `Node ${process.version} (${process.execPath}) does not satisfy ACP runtime requirements.`,
+        hint: nodeVersionMeetsCodexAcpMinimum()
+            ? undefined
+            : `Run Codex ACP with Node >=${MIN_ACP_NODE_VERSION} or switch engine=cli.`,
+    });
+    const command = await resolveCodexAcpCommandForTarget(config, target);
+    const commandResolvable = await commandIsResolvable(command, {
+        config,
+        executionTarget: ctx.executionTarget,
+    });
+    checks.push({
+        code: commandResolvable ? "codex_acp_command_resolvable" : "codex_acp_command_missing",
+        level: commandResolvable ? "info" : "error",
+        message: commandResolvable
+            ? `Codex ACP server command is executable: ${command}`
+            : `Codex ACP server command is not available: ${command}`,
+        hint: commandResolvable
+            ? undefined
+            : "Install dependencies so @agentclientprotocol/codex-acp is present, or set agentCommand to a valid Codex ACP server command.",
+    });
+    const envConfig = parseObject(config.env);
+    if (!targetIsRemote) {
+        const configApiKey = isNonEmpty(envConfig.OPENAI_API_KEY) ? envConfig.OPENAI_API_KEY : null;
+        const hostApiKey = Object.prototype.hasOwnProperty.call(envConfig, "OPENAI_API_KEY")
+            ? null
+            : isNonEmpty(process.env.OPENAI_API_KEY)
+                ? process.env.OPENAI_API_KEY
+                : null;
+        const configuredApiKey = configApiKey ?? hostApiKey;
+        const configuredCodexHome = isNonEmpty(envConfig.CODEX_HOME) ? envConfig.CODEX_HOME : null;
+        const credentialReadiness = await evaluateCodexCredentialReadiness({
+            env: process.env,
+            companyId: ctx.companyId,
+            configuredCodexHome,
+            configuredApiKey,
+        });
+        if (credentialReadiness.ready && credentialReadiness.authMode === "api") {
+            checks.push({
+                code: "codex_acp_openai_api_key_detected",
+                level: "info",
+                message: "OPENAI_API_KEY is set for Codex ACP authentication.",
+                detail: `Detected in ${configApiKey ? "adapter config env" : "server environment"}.`,
+            });
+        }
+        else if (credentialReadiness.ready && !credentialReadiness.managed) {
+            checks.push({
+                code: "codex_acp_external_home_configured",
+                level: "info",
+                message: "Codex ACP will use an externally managed CODEX_HOME.",
+                detail: credentialReadiness.effectiveHome,
+            });
+        }
+        else if (credentialReadiness.ready) {
+            checks.push({
+                code: "codex_acp_native_auth_detected",
+                level: "info",
+                message: "Codex ACP can use Codex native authentication.",
+                detail: `Credentials are available through ${credentialReadiness.effectiveHome} or shared source ${credentialReadiness.sharedSourceHome}.`,
+            });
+        }
+        else {
+            checks.push({
+                code: "codex_acp_credentials_missing",
+                level: "warn",
+                message: "No Codex ACP credentials visible to the Paperclip server were detected.",
+                hint: "Set OPENAI_API_KEY in the agent adapter env, set it in the Paperclip server environment, or run `codex login` for the same OS user that runs the Paperclip server before starting a Codex ACP agent. A `/login` in a separate Codex/chat session does not authenticate the server.",
+            });
+        }
+    }
+    else if (targetIsSandbox) {
+        // The ACP Test does not probe the sandbox, so it predicts readiness from the
+        // credentials the Paperclip server can seed into the sandbox. The host
+        // environment is not seeded, so only the adapter config key counts here.
+        const configApiKey = isNonEmpty(envConfig.OPENAI_API_KEY) ? envConfig.OPENAI_API_KEY : null;
+        const configuredCodexHome = isNonEmpty(envConfig.CODEX_HOME) ? envConfig.CODEX_HOME : null;
+        const credentialReadiness = await evaluateCodexCredentialReadiness({
+            env: process.env,
+            companyId: ctx.companyId,
+            configuredCodexHome,
+            configuredApiKey: configApiKey,
+        });
+        if (!credentialReadiness.ready) {
+            // Emit the neutral canonical check so the user interface can decide login
+            // eligibility from a stable code. The user interface does not read the
+            // message text or the top-level status.
+            checks.push({
+                code: ADAPTER_AUTH_MISSING_CHECK_CODE,
+                level: "warn",
+                message: "This environment has no ready authentication for this adapter.",
+                hint: "Provide credentials for this adapter, or start login in the environment.",
+            });
+        }
+    }
+    const mode = firstNonEmptyString(config.mode, config.acpMode) ?? DEFAULT_ACP_ENGINE_MODE;
+    const warmHandleIdleMs = asNumber(config.warmHandleIdleMs ?? config.acpWarmHandleIdleMs, DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS);
+    checks.push({
+        code: "codex_acp_runtime_scaffold",
+        level: "info",
+        message: "Codex ACP runtime execution is available through the shared ACP engine.",
+        detail: `mode=${mode}; warmHandleIdleMs=${warmHandleIdleMs}`,
+    });
+    return {
+        adapterType: ctx.adapterType,
+        status: summarizeStatus(checks),
+        checks,
+        testedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=acp.js.map