humanish 0.106.0 → 0.107.0

package/dist/actors/codex/protocol-contract.js

@@ -0,0 +1,471 @@
+// The app-server protocol humanish depends on: each method it calls with the fields and values it
+// sends and the response fields it reads, each notification and server request it consumes, and
+// the containers its item policy reads in every notification. protocol-compat.ts checks a
+// release's generated schema against this table on every launch.
+//
+// Types and known values are the baseline of every release this humanish admits. A read rule's
+// `expects` lists the values humanish compares against; one a release no longer allows refuses
+// the launch. `known` lists every string value the baseline offers; one beyond it is recorded and
+// the launch goes on. Values humanish only refuses (an asynchronous delivery, a raw item type it
+// allows but does not need) are `known`, since their removal cannot make humanish accept more.
+const S = ["string"];
+const B = ["boolean"];
+const I = ["integer"];
+const A = ["array"];
+const O = ["object"];
+const orNull = (types) => [
+    ...types,
+    "null",
+];
+const sent = (path, sends, ...expects) => (expects.length === 0 ? { path, sends } : { path, sends, expects });
+const object = (path, fields) => ({
+    path,
+    sends: O,
+    fields,
+});
+const scope = [
+    { path: "threadId", types: S },
+    { path: "turnId", types: S },
+];
+/** ThreadItem types in the baseline; humanish admits five and refuses the rest. */
+const THREAD_ITEM_TYPES = [
+    "userMessage",
+    "hookPrompt",
+    "agentMessage",
+    "functionCallOutput",
+    "plan",
+    "reasoning",
+    "commandExecution",
+    "fileChange",
+    "mcpToolCall",
+    "dynamicToolCall",
+    "collabAgentToolCall",
+    "subAgentActivity",
+    "webSearch",
+    "imageView",
+    "sleep",
+    "imageGeneration",
+    "enteredReviewMode",
+    "exitedReviewMode",
+    "contextCompaction",
+];
+/** ResponseItem types in the baseline (rawResponseItem/completed). */
+const RAW_ITEM_TYPES = [
+    "message",
+    "agent_message",
+    "reasoning",
+    "local_shell_call",
+    "function_call",
+    "tool_search_call",
+    "function_call_output",
+    "custom_tool_call",
+    "custom_tool_call_output",
+    "tool_search_output",
+    "web_search_call",
+    "image_generation_call",
+    "compaction",
+    "configuration_update",
+    "compaction_trigger",
+    "context_compaction",
+    "other",
+];
+const APPROVAL_POLICIES = ["untrusted", "on-request", "never"];
+const itemType = {
+    path: "item.type",
+    types: S,
+    expects: ["userMessage", "agentMessage", "reasoning", "contextCompaction", "dynamicToolCall"],
+    known: THREAD_ITEM_TYPES,
+};
+/** What the tool policy reads on both item notifications; it refuses on a value, not an absence. */
+const agentMessageRefusals = [
+    { path: "item.{type=agentMessage}.delivery", types: orNull(S), known: ["async"], optional: true },
+    { path: "item.{type=agentMessage}.questions", types: orNull(A), optional: true },
+];
+const dynamicTool = (status, others) => [
+    { path: "item.{type=dynamicToolCall}.tool", types: S },
+    { path: "item.{type=dynamicToolCall}.namespace", types: orNull(S), expects: [null] },
+    { path: "item.{type=dynamicToolCall}.status", types: S, expects: [status], known: others },
+];
+/** item/started: the type, the tool policy and a started tool call (restricted-turn.ts admitsItem). */
+const startedReads = [
+    ...scope,
+    itemType,
+    ...agentMessageRefusals,
+    ...dynamicTool("inProgress", ["completed", "failed"]),
+];
+/** item/completed adds the answer's shape and a finished tool call. */
+const completedReads = [
+    ...scope,
+    itemType,
+    ...agentMessageRefusals,
+    { path: "item.{type=agentMessage}.id", types: S },
+    { path: "item.{type=agentMessage}.text", types: S },
+    {
+        path: "item.{type=agentMessage}.phase",
+        types: orNull(S),
+        expects: [null, "final_answer", "commentary"],
+        known: [],
+    },
+    ...dynamicTool("completed", ["inProgress", "failed"]),
+    { path: "item.{type=dynamicToolCall}.success", types: orNull(B), expects: [true] },
+];
+/** initialize, config/read and account/read: what the launch handshake sends and reads. */
+function handshakeRequests(host) {
+    const effort = host.reasoningEffort;
+    return [
+        {
+            method: "initialize",
+            params: [
+                object("", ["clientInfo", "capabilities"]),
+                object("clientInfo", ["name", "version"]),
+                sent("clientInfo.name", S),
+                sent("clientInfo.version", S),
+                object("capabilities", ["experimentalApi"]),
+                sent("capabilities.experimentalApi", B, true),
+            ],
+            response: {
+                definition: "InitializeResponse",
+                reads: [
+                    { path: "userAgent", types: S },
+                    { path: "codexHome", types: S },
+                    {
+                        path: "platformOs",
+                        types: S,
+                        expects: [host.platform === "darwin" ? "macos" : "linux"],
+                    },
+                    { path: "platformFamily", types: S, expects: ["unix"] },
+                ],
+            },
+        },
+        {
+            method: "config/read",
+            params: [
+                object("", ["includeLayers", "cwd"]),
+                sent("includeLayers", B, true),
+                sent("cwd", S),
+            ],
+            response: {
+                definition: "ConfigReadResponse",
+                reads: [
+                    { path: "layers", types: orNull(A) },
+                    {
+                        path: "layers[].name.type",
+                        types: S,
+                        expects: ["user", "system"],
+                        known: [
+                            "packagedDefaults",
+                            "mdm",
+                            "enterpriseManaged",
+                            "project",
+                            "sessionFlags",
+                            "legacyManagedConfigTomlFromFile",
+                            "legacyManagedConfigTomlFromMdm",
+                        ],
+                    },
+                    // admitsRestrictedCodexConfig reads the file and profile of the user layer only.
+                    { path: "layers[].name.{type=user}.file", types: S },
+                    { path: "layers[].name.{type=user}.profile", types: orNull(S), expects: [null] },
+                    { path: "layers[].disabledReason", types: orNull(S), expects: [null] },
+                    // A system layer must be empty (admitsRestrictedCodexConfig).
+                    { path: "layers[].config" },
+                    { path: "config", types: O },
+                    { path: "config.model", types: orNull(S) },
+                    { path: "config.model_provider", types: orNull(S), expects: ["openai"] },
+                    { path: "config.model_reasoning_effort", types: orNull(S), expects: [effort] },
+                    {
+                        path: "config.forced_login_method",
+                        types: orNull(S),
+                        expects: ["chatgpt"],
+                        known: ["api"],
+                    },
+                    {
+                        path: "config.sandbox_mode",
+                        types: orNull(S),
+                        expects: ["read-only"],
+                        known: ["workspace-write", "danger-full-access"],
+                    },
+                    {
+                        path: "config.approval_policy",
+                        types: ["string", "object", "null"],
+                        expects: ["never"],
+                        known: APPROVAL_POLICIES,
+                    },
+                    {
+                        path: "config.web_search",
+                        types: orNull(S),
+                        expects: ["disabled"],
+                        known: ["cached", "indexed", "live"],
+                    },
+                    { path: "config.analytics", types: orNull(O) },
+                    { path: "config.analytics.enabled", types: orNull(B), expects: [false] },
+                ],
+            },
+        },
+        {
+            method: "account/read",
+            params: [object("", ["refreshToken"]), sent("refreshToken", B, false)],
+            response: {
+                definition: "GetAccountResponse",
+                reads: [
+                    { path: "account", types: orNull(O), expects: [null] },
+                    {
+                        path: "account.type",
+                        types: S,
+                        expects: ["chatgpt", "apiKey"],
+                        known: ["amazonBedrock"],
+                    },
+                    { path: "requiresOpenaiAuth", types: B, expects: [true] },
+                ],
+            },
+        },
+    ];
+}
+/** thread/start, mcpServerStatus/list, turn/start and turn/interrupt. */
+function threadRequests(host) {
+    const effort = host.reasoningEffort;
+    return [
+        {
+            method: "thread/start",
+            params: [
+                object("", [
+                    "cwd",
+                    "ephemeral",
+                    "experimentalRawEvents",
+                    "approvalPolicy",
+                    "sandbox",
+                    "model",
+                    "modelProvider",
+                    "allowProviderModelFallback",
+                    "environments",
+                    "runtimeWorkspaceRoots",
+                    "dynamicTools",
+                    "baseInstructions",
+                    "config",
+                ]),
+                sent("cwd", S),
+                sent("ephemeral", B, true),
+                sent("experimentalRawEvents", B, true),
+                sent("approvalPolicy", S, "never"),
+                sent("sandbox", S, "read-only"),
+                sent("model", S),
+                sent("modelProvider", S, "openai"),
+                sent("allowProviderModelFallback", B, false),
+                sent("environments", A),
+                sent("runtimeWorkspaceRoots", A),
+                sent("dynamicTools", A),
+                sent("dynamicTools[].type", S, "function"),
+                object("dynamicTools[].{type=function}", ["type", "name", "description", "inputSchema"]),
+                sent("dynamicTools[].{type=function}.name", S),
+                sent("dynamicTools[].{type=function}.description", S),
+                sent("dynamicTools[].{type=function}.inputSchema", O),
+                sent("baseInstructions", S),
+                sent("config", O),
+            ],
+            response: {
+                definition: "ThreadStartResponse",
+                reads: [
+                    { path: "thread.id", types: S },
+                    { path: "thread.ephemeral", types: B, expects: [true] },
+                    { path: "thread.model", types: orNull(S) },
+                    { path: "thread.modelProvider", types: S, expects: ["openai"] },
+                    { path: "thread.reasoningEffort", types: orNull(S), expects: [effort] },
+                    { path: "thread.cliVersion", types: S },
+                    { path: "thread.environments", types: orNull(A) },
+                    { path: "thread.path", types: orNull(S), expects: [null] },
+                    { path: "thread.cwd", types: S },
+                    { path: "model", types: S },
+                    { path: "modelProvider", types: S, expects: ["openai"] },
+                    { path: "reasoningEffort", types: orNull(S), expects: [effort] },
+                    { path: "cwd", types: S },
+                    {
+                        path: "approvalPolicy",
+                        types: ["string", "object"],
+                        expects: ["never"],
+                        known: APPROVAL_POLICIES,
+                    },
+                    {
+                        path: "sandbox.type",
+                        types: S,
+                        expects: ["readOnly"],
+                        known: ["dangerFullAccess", "externalSandbox", "workspaceWrite"],
+                    },
+                    { path: "sandbox.{type=readOnly}.networkAccess", types: B, expects: [false] },
+                    { path: "instructionSources", types: A },
+                    { path: "runtimeWorkspaceRoots", types: A },
+                ],
+            },
+        },
+        {
+            method: "mcpServerStatus/list",
+            params: [object("", ["limit"]), sent("limit", I)],
+            response: {
+                definition: "ListMcpServerStatusResponse",
+                reads: [
+                    { path: "data", types: A },
+                    { path: "nextCursor", types: orNull(S), expects: [null] },
+                ],
+            },
+        },
+        {
+            method: "turn/start",
+            params: [
+                object("", [
+                    "threadId",
+                    "cwd",
+                    "approvalPolicy",
+                    "sandboxPolicy",
+                    "environments",
+                    "runtimeWorkspaceRoots",
+                    "effort",
+                    "model",
+                    "outputSchema",
+                    "input",
+                ]),
+                sent("threadId", S),
+                sent("cwd", S),
+                sent("approvalPolicy", S, "never"),
+                sent("sandboxPolicy.type", S, "readOnly"),
+                object("sandboxPolicy.{type=readOnly}", ["type"]),
+                sent("environments", A),
+                sent("runtimeWorkspaceRoots", A),
+                sent("effort", S, effort),
+                sent("model", S),
+                sent("outputSchema", O),
+                sent("input", A),
+                sent("input[].type", S, "text", "localImage"),
+                object("input[].{type=text}", ["type", "text", "text_elements"]),
+                sent("input[].{type=text}.text", S),
+                sent("input[].{type=text}.text_elements", A),
+                object("input[].{type=localImage}", ["type", "path"]),
+                sent("input[].{type=localImage}.path", S),
+            ],
+            response: { definition: "TurnStartResponse", reads: [{ path: "turn.id", types: S }] },
+        },
+        {
+            method: "turn/interrupt",
+            params: [object("", ["threadId", "turnId"]), sent("threadId", S), sent("turnId", S)],
+        },
+    ];
+}
+/** The notifications and the server request humanish consumes, and its reply to that request. */
+const MESSAGES = [
+    // Where the baseline carries items; a release that moves them refuses (ITEM_CARRIERS).
+    {
+        method: "thread/started",
+        definition: "ThreadStartedNotification",
+        reads: [
+            { path: "thread", types: orNull(O) },
+            { path: "thread.turns", types: orNull(A) },
+            { path: "thread.turns[].items", types: orNull(A) },
+        ],
+    },
+    {
+        method: "turn/started",
+        definition: "TurnStartedNotification",
+        reads: [
+            { path: "threadId", types: S },
+            { path: "turn.id", types: S },
+            { path: "turn.items", types: orNull(A) },
+        ],
+    },
+    {
+        method: "turn/completed",
+        definition: "TurnCompletedNotification",
+        reads: [
+            { path: "threadId", types: S },
+            { path: "turn.id", types: S },
+            {
+                path: "turn.status",
+                types: S,
+                expects: ["completed", "interrupted"],
+                known: ["failed", "inProgress"],
+            },
+            { path: "turn.error", types: orNull(O), expects: [null] },
+            { path: "turn.items", types: orNull(A) },
+        ],
+    },
+    { method: "item/started", definition: "ItemStartedNotification", reads: startedReads },
+    { method: "item/completed", definition: "ItemCompletedNotification", reads: completedReads },
+    {
+        method: "item/agentMessage/delta",
+        definition: "AgentMessageDeltaNotification",
+        reads: [...scope, { path: "delta", types: S }],
+    },
+    {
+        method: "rawResponseItem/completed",
+        definition: "RawResponseItemCompletedNotification",
+        reads: [
+            ...scope,
+            {
+                path: "item.type",
+                types: S,
+                expects: ["message", "reasoning", "custom_tool_call", "function_call"],
+                known: RAW_ITEM_TYPES,
+            },
+            { path: "item.{type=custom_tool_call}.name", types: S, expects: ["exec"] },
+            { path: "item.{type=function_call}.name", types: S, expects: ["wait"] },
+            { path: "item.{type=message}.content", types: A },
+            // humanish stops on a "refusal" content item, which the baseline schema does not list.
+            {
+                path: "item.{type=message}.content[].type",
+                types: S,
+                known: ["input_text", "input_image", "input_audio", "output_text", "refusal"],
+            },
+        ],
+    },
+    {
+        method: "thread/tokenUsage/updated",
+        definition: "ThreadTokenUsageUpdatedNotification",
+        reads: [
+            ...scope,
+            { path: "tokenUsage.total.inputTokens", types: I },
+            { path: "tokenUsage.total.outputTokens", types: I },
+            { path: "tokenUsage.total.cachedInputTokens", types: I },
+            { path: "tokenUsage.total.cacheWriteInputTokens", types: I },
+        ],
+    },
+    {
+        method: "item/tool/call",
+        definition: "DynamicToolCallParams",
+        reads: [
+            ...scope,
+            { path: "callId", types: S },
+            { path: "tool", types: S },
+            { path: "namespace", types: orNull(S), expects: [null] },
+            { path: "arguments" },
+        ],
+        reply: {
+            definition: "DynamicToolCallResponse",
+            sends: [
+                object("", ["success", "contentItems"]),
+                sent("success", B, true),
+                sent("contentItems", A),
+                sent("contentItems[].type", S, "inputText"),
+                object("contentItems[].{type=inputText}", ["type", "text"]),
+                sent("contentItems[].{type=inputText}.text", S),
+            ],
+        },
+    },
+];
+/** A container that stops being an array or object would hide its items from the item policy. */
+const ITEM_CARRIERS = [
+    { path: "items", types: orNull(A), optional: true },
+    { path: "turn", types: orNull(O), optional: true },
+    { path: "turn.items", types: orNull(A), optional: true },
+    { path: "thread", types: orNull(O), optional: true },
+    { path: "thread.turns", types: orNull(A), optional: true },
+    { path: "thread.turns[]", types: O, optional: true },
+    { path: "thread.turns[].items", types: orNull(A), optional: true },
+];
+/**
+ * The contract for one launch. config/read's `config` is typed only for some keys; the keys
+ * humanish pins that the schema leaves open are checked at launch by admitsRestrictedCodexConfig,
+ * which compares exact values, so they are not listed here.
+ */
+export function protocolContract(host) {
+    return {
+        requests: [...handshakeRequests(host), ...threadRequests(host)],
+        messages: MESSAGES,
+        itemCarriers: ITEM_CARRIERS,
+    };
+}

package/dist/actors/codex/qualified-versions.d.ts

@@ -10,7 +10,7 @@
  * of them.
  */
 export declare const QUALIFIED_CODEX_CLI_VERSIONS: {
-    readonly "linux-x64": readonly ["0.154.0", "0.157.1", "0.159.2", "0.159.3"];
+    readonly "linux-x64": readonly ["0.154.0", "0.157.1", "0.159.2", "0.159.3", "0.160.0"];
     readonly "darwin-arm64": readonly ["0.154.0"];
 };
 /**
@@ -36,10 +36,37 @@ export declare function defaultCodexCliVersion(platform?: NodeJS.Platform, arch?
 /** The version from `codex --version` output (`codex-cli 0.157.1`); any other shape is undefined. */
 export declare function parseCodexCliVersion(stdout: string): string | undefined;
 /**
- * doctor's recovery for an unadmitted CLI: the release it found, what this host admits, and the
- * exact command that installs the newest admitted release.
+ * doctor's recovery for an unadmitted CLI: the release it found and where, what this host admits,
+ * and how to replace that binary with the newest admitted release.
  */
-export declare function codexVersionRecovery(detected: string | undefined, platform?: NodeJS.Platform, arch?: string): string;
+export declare function codexVersionRecovery(detected: string | undefined, installation?: CodexInstallation, platform?: NodeJS.Platform, arch?: string): string;
+/**
+ * Where the `codex` humanish found was installed, which decides the command that replaces it.
+ * `path` is the file on `PATH`.
+ */
+export type CodexInstallation = {
+    readonly kind: "project";
+    readonly path: string;
+    readonly project: string;
+} | {
+    readonly kind: "global";
+    readonly path: string;
+} | {
+    readonly kind: "other";
+    readonly path: string;
+};
+/**
+ * Classifies the `codex` on `PATH` by the file it resolves to. A project's node_modules/.bin/codex
+ * resolving into that project's @openai/codex is project-local, so `npx` runs it before any global
+ * install. One inside npm's global prefix (`npm prefix -g`) is global. Anything else, such as
+ * Homebrew or a standalone download, is other.
+ */
+export declare function classifyCodexInstallation(found: {
+    path: string;
+    resolved: string;
+}, npmGlobalPrefix: string | undefined): CodexInstallation;
+/** One sentence: how to put the newest admitted Codex CLI in place of the one humanish found. */
+export declare function codexInstallAdvice(installation: CodexInstallation | undefined, platform?: NodeJS.Platform, arch?: string): string;
 /** For refusal messages: the admitted releases on this host, or every host when it has none. */
 export declare function describeQualifiedCodexCliVersions(platform?: NodeJS.Platform, arch?: string): string;
 export {};

package/dist/actors/codex/qualified-versions.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 /**
  * Codex CLI releases the restricted launcher admits, per host, oldest first. Each qualified
  * release needs a receipt under docs/goals/computer-use-actor/receipts/ that meets
@@ -10,7 +11,7 @@
  * of them.
  */
 export const QUALIFIED_CODEX_CLI_VERSIONS = {
-    "linux-x64": ["0.154.0", "0.157.1", "0.159.2", "0.159.3"],
+    "linux-x64": ["0.154.0", "0.157.1", "0.159.2", "0.159.3", "0.160.0"],
     "darwin-arm64": ["0.154.0"],
 };
 /**
@@ -66,15 +67,59 @@ function describeHost(host) {
         : `${PREEXISTING_CODEX_CLI_ADMISSIONS[host].join(", ")} (pre-existing admission, not qualified)`;
 }
 /**
- * doctor's recovery for an unadmitted CLI: the release it found, what this host admits, and the
- * exact command that installs the newest admitted release.
+ * doctor's recovery for an unadmitted CLI: the release it found and where, what this host admits,
+ * and how to replace that binary with the newest admitted release.
  */
-export function codexVersionRecovery(detected, platform = process.platform, arch = process.arch) {
+export function codexVersionRecovery(detected, installation, platform = process.platform, arch = process.arch) {
     const found = detected === undefined
         ? "The installed Codex CLI did not report a recognizable version"
         : `Found Codex CLI ${detected}`;
-    const install = `npm install -g @openai/codex@${defaultCodexCliVersion(platform, arch)}`;
-    return `${found}; ${describeQualifiedCodexCliVersions(platform, arch)}. Install the newest with \`${install}\`, then sign in with a ChatGPT account (\`codex login\`).`;
+    const where = installation === undefined ? "" : ` at \`${installation.path}\``;
+    return `${found}${where}; ${describeQualifiedCodexCliVersions(platform, arch)}. ${codexInstallAdvice(installation, platform, arch)} Then sign in with a ChatGPT account (\`codex login\`).`;
+}
+const inside = (file, directory) => file.startsWith(`${directory}${path.sep}`);
+/**
+ * Classifies the `codex` on `PATH` by the file it resolves to. A project's node_modules/.bin/codex
+ * resolving into that project's @openai/codex is project-local, so `npx` runs it before any global
+ * install. One inside npm's global prefix (`npm prefix -g`) is global. Anything else, such as
+ * Homebrew or a standalone download, is other.
+ */
+export function classifyCodexInstallation(found, npmGlobalPrefix) {
+    const bin = path.dirname(found.path);
+    const modules = path.dirname(bin);
+    if (path.basename(bin) === ".bin" &&
+        path.basename(modules) === "node_modules" &&
+        inside(found.resolved, path.join(modules, "@openai", "codex")))
+        return { kind: "project", path: found.path, project: path.dirname(modules) };
+    if (npmGlobalPrefix !== undefined &&
+        (found.path === path.join(npmGlobalPrefix, "bin", "codex") ||
+            inside(found.resolved, path.join(npmGlobalPrefix, "lib", "node_modules", "@openai", "codex"))))
+        return { kind: "global", path: found.path };
+    return { kind: "other", path: found.path };
+}
+/**
+ * The command that installs the newest admitted Codex CLI where it replaces the one humanish
+ * found: in its project for a project-local install, otherwise npm's global install.
+ */
+function codexInstallCommand(installation, platform = process.platform, arch = process.arch) {
+    const version = defaultCodexCliVersion(platform, arch);
+    return installation?.kind === "project"
+        ? `npm install -D @openai/codex@${version}`
+        : `npm install -g @openai/codex@${version}`;
+}
+/** One sentence: how to put the newest admitted Codex CLI in place of the one humanish found. */
+export function codexInstallAdvice(installation, platform = process.platform, arch = process.arch) {
+    const command = codexInstallCommand(installation, platform, arch);
+    switch (installation?.kind) {
+        case undefined:
+            return `Install the newest with \`${command}\`.`;
+        case "global":
+            return `Replace it with \`${command}\`.`;
+        case "project":
+            return `It is installed in this project: run \`${command}\` in \`${installation.project}\`, or \`npm uninstall @openai/codex\` there to use the global Codex.`;
+        case "other":
+            return `Update it with the tool that installed it, or put Codex ${defaultCodexCliVersion(platform, arch)} first on PATH.`;
+    }
 }
 /** For refusal messages: the admitted releases on this host, or every host when it has none. */
 export function describeQualifiedCodexCliVersions(platform = process.platform, arch = process.arch) {

package/dist/actors/codex/restricted-executable.d.ts

@@ -6,6 +6,11 @@ export declare function restrictedCodexNpmTarget(platform: NodeJS.Platform, arch
     triple: string;
     packageName: string;
 } | undefined;
+/** The `codex` file humanish found and would not run, and why. No path: none was found. */
+export interface RefusedCodexExecutable {
+    readonly path?: string;
+    readonly reason: string;
+}
 /** Resolve PATH without running a shell. The npm launcher is resolved to its
  * native optional package so cleanup owns the real app-server child. */
 export declare function resolveExecutable(options: {
@@ -13,5 +18,24 @@ export declare function resolveExecutable(options: {
     platform?: NodeJS.Platform;
     arch?: string;
 }, env: NodeJS.ProcessEnv): Promise<string>;
+/** The `codex` resolveExecutable turns down and why, or undefined when it finds one to run. */
+export declare function refusedCodexExecutable(env: NodeJS.ProcessEnv, options?: {
+    platform?: NodeJS.Platform;
+    arch?: string;
+}): Promise<RefusedCodexExecutable | undefined>;
+/**
+ * The `codex` resolveExecutable picks from `PATH`, runnable or not, and the file it resolves to:
+ * what decides the command that replaces it. Undefined when `PATH` has none that resolves.
+ */
+export declare function foundCodexExecutable(env: NodeJS.ProcessEnv): Promise<{
+    path: string;
+    resolved: string;
+} | undefined>;
+/**
+ * Writes this release's app-server schema (`app-server generate-json-schema --experimental`) into
+ * `out`, for the protocol check. False when the release exits without one. Bounded like the
+ * version check: 15 seconds, and a few kilobytes of output, which it does not otherwise read.
+ */
+export declare function generateProtocolSchema(file: string, env: NodeJS.ProcessEnv, cwd: string, out: string, spawnFn: RestrictedCodexSpawn, deadline: RestrictedCodexDeadline): Promise<boolean>;
 /** Returns the detected release after checking it against the admitted list. */
 export declare function checkVersion(file: string, env: NodeJS.ProcessEnv, cwd: string, spawnFn: RestrictedCodexSpawn, deadline: RestrictedCodexDeadline, admitted: readonly string[], expected: string | undefined): Promise<string>;