humanish 0.106.1 → 0.108.0

package/dist/actors/codex/restricted-executable.js

@@ -1,13 +1,13 @@
-// Finding and admitting the Codex CLI a restricted launch runs: the native executable behind PATH
+// Finding and admitting the Codex CLI a restricted launch runs: the native executable behind `PATH`
 // or the npm launcher, the environment its children get, and the `--version` check against the
 // host's admitted releases.
 import { constants } from "node:fs";
 import { access, open, realpath } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { parseCodexCliVersion } from "./qualified-versions.js";
+import { parseCodexCliVersion } from "./codex-admission.js";
 import { RestrictedCodexStop, closeOwnedCodexProcess, ownCodexProcess, retainUnclosedChild, } from "./restricted-transport.js";
-/** The environment of every Codex child: a private home and scratch, and PATH and locale. */
+/** The environment of every Codex child: a private home and scratch, and `PATH` and locale. */
 export function childEnvironment(source, home, scratch) {
     const result = { HOME: home, CODEX_HOME: home, TMPDIR: scratch };
     for (const key of ["PATH", "LANG", "USER", "LOGNAME"])
@@ -47,42 +47,75 @@ export function restrictedCodexNpmTarget(platform, arch) {
         return { triple: "aarch64-apple-darwin", packageName: "codex-darwin-arm64" };
     return undefined;
 }
-/** Resolve PATH without running a shell. The npm launcher is resolved to its
+/** 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 async function resolveExecutable(options, env) {
-    const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
-    let selected = options.executable;
-    if (selected === undefined) {
-        for (const directory of (env.PATH ?? "")
-            .split(path.delimiter)
-            .filter((entry) => path.isAbsolute(entry))) {
-            const candidate = path.join(directory, "codex");
-            try {
-                await access(candidate, constants.X_OK);
-                selected = candidate;
-                break;
-            }
-            catch {
-                /* Continue PATH. */
-            }
+    const located = await locateExecutable(options, env);
+    // The stop carries only its code; doctor asks refusedCodexExecutable for the file and reason.
+    if ("refused" in located)
+        throw new RestrictedCodexStop("codex_unavailable");
+    return located.file;
+}
+/** The `codex` resolveExecutable turns down and why, or undefined when it finds one to run. */
+export async function refusedCodexExecutable(env, options = {}) {
+    const located = await locateExecutable(options, env);
+    return "refused" in located ? located.refused : undefined;
+}
+/** The first executable `codex` on `PATH`, as resolveExecutable picks it. */
+async function firstCodexOnPath(env) {
+    for (const directory of (env.PATH ?? "")
+        .split(path.delimiter)
+        .filter((entry) => path.isAbsolute(entry))) {
+        const candidate = path.join(directory, "codex");
+        try {
+            await access(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            /* Try the next `PATH` entry. */
         }
     }
-    if (selected === undefined || !path.isAbsolute(selected))
-        throw new RestrictedCodexStop("codex_unavailable");
+    return 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 async function foundCodexExecutable(env) {
+    const selected = await firstCodexOnPath(env);
+    if (selected === undefined)
+        return undefined;
+    try {
+        return { path: selected, resolved: await realpath(selected) };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function locateExecutable(options, env) {
+    const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
+    const selected = options.executable ?? (await firstCodexOnPath(env));
+    const refused = (reason, file) => ({
+        refused: { ...(file === undefined ? {} : { path: file }), reason },
+    });
+    if (selected === undefined)
+        return refused("no executable `codex` is on PATH");
+    if (!path.isAbsolute(selected))
+        return refused("it is not an absolute path", selected);
     let resolved;
     try {
         resolved = await realpath(selected);
     }
     catch {
-        throw new RestrictedCodexStop("codex_unavailable");
+        return refused("it does not resolve to a file", selected);
     }
     if (await isNativeExecutable(resolved, platform))
-        return resolved;
+        return { file: resolved };
     if (path.basename(resolved) === "codex.js" && path.basename(path.dirname(resolved)) === "bin") {
         const packageRoot = path.dirname(path.dirname(resolved));
         const target = restrictedCodexNpmTarget(platform, arch);
         if (!target)
-            throw new RestrictedCodexStop("codex_unavailable");
+            return refused(`the npm package has no native build for ${platform}-${arch}`, resolved);
         const { triple, packageName: nativePackage } = target;
         const candidates = [];
         try {
@@ -97,13 +130,55 @@ export async function resolveExecutable(options, env) {
         candidates.push(path.join(packageRoot, "vendor", triple, "bin", "codex"));
         for (const candidate of candidates) {
             if (await isNativeExecutable(candidate, platform))
-                return realpath(candidate);
+                return { file: await realpath(candidate) };
+        }
+        return refused(`the npm package's native ${nativePackage} build is missing`, resolved);
+    }
+    return refused("it is neither a native Codex executable nor the @openai/codex npm launcher", resolved);
+}
+/**
+ * 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 async function generateProtocolSchema(file, env, cwd, out, spawnFn, deadline) {
+    deadline.check();
+    const owned = ownCodexProcess(spawnFn(file, ["app-server", "generate-json-schema", "--experimental", "--out", out], {
+        cwd,
+        env,
+        detached: false,
+        stdio: ["pipe", "pipe", "pipe"],
+    }));
+    let bytes = 0, exitCode = null;
+    const timer = setTimeout(() => deadline.stop("timeout"), 15_000);
+    const count = (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 65_536)
+            deadline.stop("response_too_large");
+    };
+    owned.child.on("error", () => deadline.stop("codex_unavailable"));
+    owned.child.stdin.on("error", () => deadline.stop("codex_unavailable"));
+    owned.child.stdout.on("data", count);
+    owned.child.stderr.on("data", count);
+    owned.child.on("exit", (code) => {
+        exitCode = code;
+    });
+    try {
+        owned.child.stdin.end();
+        await deadline.wait(owned.closed);
+        return exitCode === 0;
+    }
+    finally {
+        clearTimeout(timer);
+        if (!(await closeOwnedCodexProcess(owned))) {
+            retainUnclosedChild(owned.closed);
+            // oxlint-disable-next-line no-unsafe-finally -- a Codex process that did not close invalidates the check
+            throw new RestrictedCodexStop("codex_cleanup_failed");
         }
     }
-    throw new RestrictedCodexStop("codex_unavailable");
 }
-/** Returns the detected release after checking it against the admitted list. */
-export async function checkVersion(file, env, cwd, spawnFn, deadline, admitted, expected) {
+/** Returns the detected release after checking it against launch admission (`admits`). */
+export async function checkVersion(file, env, cwd, spawnFn, deadline, admits, expected) {
     deadline.check();
     const owned = ownCodexProcess(spawnFn(file, ["--version"], { cwd, env, detached: false, stdio: ["pipe", "pipe", "pipe"] }));
     let text = "", bytes = 0, exitCode = null;
@@ -131,7 +206,7 @@ export async function checkVersion(file, env, cwd, spawnFn, deadline, admitted,
             throw new RestrictedCodexStop("codex_unavailable");
         const version = parseCodexCliVersion(text);
         if (version === undefined ||
-            !admitted.includes(version) ||
+            !admits(version) ||
             (expected !== undefined && version !== expected))
             throw new RestrictedCodexStop("codex_unsupported_version", version);
         return version;

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

@@ -22,7 +22,8 @@ export interface LaunchSettings {
     readonly operatorAuth: boolean;
     readonly reasoningEffort: ReasoningEffort;
     readonly spawnFn: RestrictedCodexSpawn;
-    readonly admittedVersions: readonly string[];
+    /** Launch admission: codex-admission.ts, or the qualifier's exact list (restricted-session.ts). */
+    readonly admits: (version: string) => boolean;
 }
 /** What a launch records on the session, each piece as soon as it exists. */
 export interface LaunchState {
@@ -46,6 +47,12 @@ export interface LaunchState {
     resolvedModel: string | undefined;
     authentication: "chatgpt-account" | "api-key" | undefined;
     cliVersion: string | undefined;
+    /** Notification methods this humanish does not know that carried no item, by count. */
+    unknownNotifications: Map<string, number>;
+    /** How the release's schema differs from the fields humanish reads; set when that refuses. */
+    protocolIncompatibilities: string[] | undefined;
+    /** Schema values beyond the baseline, recorded at launch. */
+    protocolAdditions: string[] | undefined;
 }
 /** An admitted value, or the refusal a launch stops with. */
 export type Admission<T> = {
@@ -112,5 +119,5 @@ export declare function admitMcpStatus(reply: Record<string, unknown>): Admissio
  * The session's one-time launch: a private home, the auth link, the version check and the spawn,
  * then initialize, config, account, thread and MCP admission.
  */
-export declare function launchAdmittedAppServer(settings: LaunchSettings, state: LaunchState, request: RestrictedCodexRequest, deadline: RestrictedCodexDeadline, frameLimit: number, enter: (phase: CuaProviderFailurePhase) => void): Promise<RestrictedCodexTransport>;
+export declare function launchAdmittedAppServer(settings: LaunchSettings, state: LaunchState, request: RestrictedCodexRequest, deadline: RestrictedCodexDeadline, frameLimit: number, enter: (phase: CuaProviderFailurePhase) => void, install: (transport: RestrictedCodexTransport) => void): Promise<RestrictedCodexTransport>;
 export {};

package/dist/actors/codex/restricted-launch.js

@@ -4,10 +4,12 @@
 // none of them touches the session. launchAdmittedAppServer sends the requests in order, stops on
 // the first refusal, and records each piece of state as soon as it exists so the session's
 // teardown (restricted-session.ts) cleans up a launch that fails partway.
-import { chmod, mkdir, mkdtemp, realpath, stat, symlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, realpath, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
-import { checkVersion, childEnvironment, resolveExecutable } from "./restricted-executable.js";
+import { checkVersion, childEnvironment, generateProtocolSchema, resolveExecutable, } from "./restricted-executable.js";
+import { checkProtocol, loadProtocolSchema } from "./protocol-compat.js";
+import { protocolContract } from "./protocol-contract.js";
 import { admitsRestrictedCodexConfig, admitsRestrictedCodexThread, codexRecord, restrictedCodexConfig, } from "./restricted-policy.js";
 import { RestrictedCodexDeadline, RestrictedCodexStop, RestrictedCodexTransport, ownCodexProcess, } from "./restricted-transport.js";
 /** The admitted value; a refusal stops the launch. */
@@ -114,6 +116,37 @@ export function admitMcpStatus(reply) {
         return { refusal: "codex_unsafe_configuration" };
     return { value: undefined };
 }
+/**
+ * The release's own app-server schema against the fields humanish reads and sends
+ * (protocol-contract.ts), generated into the private work directory on every launch. A change
+ * there refuses as codex_incompatible_release; a value beyond the baseline is recorded when the
+ * launch is admitted. Reading the schema waits on the deadline; a stop leaves the directory to
+ * the session's teardown, which removes the whole work directory.
+ */
+async function admitProtocol(file, env, state, spawnFn, deadline, host) {
+    const directory = path.join(state.work, "schema");
+    const generated = await generateProtocolSchema(file, env, state.cwd, directory, spawnFn, deadline);
+    const schema = generated
+        ? await deadline.wait(loadProtocolSchema(directory).catch(() => undefined))
+        : undefined;
+    const result = schema === undefined
+        ? {
+            incompatibilities: [
+                generated
+                    ? "its generated app-server schema could not be read"
+                    : "it did not generate an app-server schema",
+            ],
+            additions: [],
+        }
+        : checkProtocol(schema, protocolContract(host));
+    await rm(directory, { recursive: true, force: true });
+    deadline.check();
+    if (result.incompatibilities.length > 0) {
+        state.protocolIncompatibilities = result.incompatibilities;
+        throw new RestrictedCodexStop("codex_incompatible_release");
+    }
+    state.protocolAdditions = result.additions;
+}
 /** The host's Codex auth.json, which a private home links to instead of copying. */
 async function hostAuthFile(options, sourceEnv) {
     const authHome = options.authHome ?? sourceEnv.CODEX_HOME ?? path.join(sourceEnv.HOME ?? homedir(), ".codex");
@@ -133,7 +166,7 @@ async function hostAuthFile(options, sourceEnv) {
  * The session's one-time launch: a private home, the auth link, the version check and the spawn,
  * then initialize, config, account, thread and MCP admission.
  */
-export async function launchAdmittedAppServer(settings, state, request, deadline, frameLimit, enter) {
+export async function launchAdmittedAppServer(settings, state, request, deadline, frameLimit, enter, install) {
     const { options, sourceEnv, participant, operatorAuth, reasoningEffort, spawnFn } = settings;
     const file = await resolveExecutable(options, sourceEnv);
     deadline.check();
@@ -146,7 +179,11 @@ export async function launchAdmittedAppServer(settings, state, request, deadline
     for (const directory of [home, state.cwd, state.scratch])
         await mkdir(directory, { mode: 0o700 });
     const env = childEnvironment(sourceEnv, home, state.scratch);
-    state.cliVersion = await checkVersion(file, env, state.cwd, spawnFn, deadline, settings.admittedVersions, options.cliVersion);
+    state.cliVersion = await checkVersion(file, env, state.cwd, spawnFn, deadline, settings.admits, options.cliVersion);
+    await admitProtocol(file, env, state, spawnFn, deadline, {
+        reasoningEffort,
+        platform: settings.platform,
+    });
     const configMode = {
         participantCodeMode: participant !== undefined,
         reasoningEffort,
@@ -173,6 +210,8 @@ export async function launchAdmittedAppServer(settings, state, request, deadline
         stdio: ["pipe", "pipe", "pipe"],
     }));
     const launched = new RestrictedCodexTransport(owned, deadline, frameLimit);
+    // The session's handlers check output from the first byte, before initialize returns.
+    install(launched);
     state.transport = launched;
     enter("initialize");
     const initialize = await launched.rpc("initialize", {

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

@@ -0,0 +1,101 @@
+import { type RestrictedCodexAnalysisErrorCode } from "./restricted-policy.js";
+import { type RestrictedCodexDeadline, type RestrictedCodexTransport } from "./restricted-transport.js";
+/** Raw response item types an analyst turn may produce. */
+export declare const ANALYST_RAW_ITEM_TYPES: readonly string[];
+/** A participant also runs Code Mode: `exec` custom tool calls and `wait` function calls. */
+export declare const PARTICIPANT_RAW_ITEM_TYPES: readonly string[];
+/** Thread item types an analyst turn may produce. */
+export declare const ANALYST_ITEM_TYPES: readonly string[];
+/** A participant also has its one dynamic tool. */
+export declare const PARTICIPANT_ITEM_TYPES: readonly string[];
+/**
+ * Server notification methods in Codex CLI 0.160.0's app-server schema
+ * (`codex app-server generate-json-schema --experimental`, ServerNotification), plus two it sends
+ * outside that union: rawResponseItem/completed, and rawResponse/completed, whose v2 definition
+ * (RawResponseCompletedNotification) carries only a response id and usage.
+ */
+export declare const KNOWN_CODEX_NOTIFICATIONS: ReadonlySet<string>;
+/** What the item policy depends on: the session's role and, for a participant, its tool. */
+export interface NotificationPolicy {
+    readonly participant: boolean;
+    /** The participant's tool name, read at each use; undefined for an analyst. */
+    toolName(): string | undefined;
+}
+/** The item policy for a session: a participant's tool name is read at each use. */
+export declare function notificationPolicyOf(participant: {
+    readonly tool: {
+        readonly name: string;
+    };
+} | undefined): NotificationPolicy;
+/** Adds one notification of `method` to a session's unknown-method counts. */
+export declare function countUnknownNotification(counts: Map<string, number>, method: string): void;
+/**
+ * The items a notification carries, each with the method whose policy it takes, or null when one
+ * is malformed. 0.160.0's schema puts a ThreadItem in `params.item` (item/started,
+ * item/completed), `params.turn.items` (turn/started, turn/completed) and
+ * `params.thread.turns[].items` (thread/started). An `item` array and an `items` array are read
+ * too, for a release that adds them. A nested ThreadItem takes the item/completed policy.
+ */
+export declare function notificationItems(method: string, params: Record<string, unknown>): {
+    method: string;
+    item: Record<string, unknown>;
+}[] | null;
+/**
+ * How a notification fares under the item policy: it carries no item, only allowed items, or a
+ * disallowed or malformed one.
+ */
+export declare function itemPolicyOf(method: string, params: Record<string, unknown>, policy: NotificationPolicy): "none" | "allowed" | "violation";
+/**
+ * True when an item breaks the item policy. rawResponseItem/completed, and an item of a raw type
+ * under any method other than item/started or item/completed, use the raw-item policy. Every
+ * other item uses the thread-item policy: an allowed type, the participant's one dynamic tool, and
+ * no agent message that delivers asynchronously or asks a question.
+ */
+export declare function itemPolicyViolation(method: string, item: Record<string, unknown>, policy: NotificationPolicy): boolean;
+/**
+ * The handler for notifications outside a dispatched turn: during the handshake, before
+ * turn/start, between requests and while closing. A disallowed or malformed item refuses; an
+ * unknown method without an item is counted; anything else is ignored, as there is no turn to
+ * apply it to.
+ */
+export declare function idleNotificationHandler(policy: NotificationPolicy, recordUnknown: (method: string) => void, refuse: (code: RestrictedCodexAnalysisErrorCode) => void): (method: string, params: Record<string, unknown>) => void;
+/** The run warning for unknown notification methods, or undefined when there were none. */
+export declare function unknownNotificationsWarning(counts: Readonly<Record<string, number>> | undefined, cliVersion: string | undefined): string | undefined;
+/** The run warning for a last frame cut off by humanish's own stop, or undefined when none was. */
+export declare function truncatedFrameWarning(bytes: number | undefined): string | undefined;
+/** The session fields its handlers outside a turn read and write (restricted-session). */
+export interface NotificationSessionState {
+    readonly unknownNotifications: Map<string, number>;
+    /** The request in flight's deadline, or undefined between requests. */
+    readonly activeDeadline: RestrictedCodexDeadline | undefined;
+    readonly transport: RestrictedCodexTransport | undefined;
+    /**
+     * The first policy refusal or unchecked output in the session, whenever it happened and whether
+     * or not a request reported it: a caller that tolerates a request's failure (the debrief) must
+     * not absorb it.
+     */
+    policyRefusal: RestrictedCodexAnalysisErrorCode | undefined;
+    /** Bytes of last frames cut off after humanish stopped the app-server: a warning only. */
+    truncatedFrameBytes: number | undefined;
+}
+type Participant = {
+    readonly tool: {
+        readonly name: string;
+    };
+} | undefined;
+/**
+ * A policy refusal: it is recorded, the active request stops with `code`, pending RPCs are
+ * rejected, and between requests the next request fails with it.
+ */
+export declare function refuseSession(state: NotificationSessionState, code: RestrictedCodexAnalysisErrorCode): void;
+/** The session's handler for notifications outside a dispatched turn, on its current transport. */
+export declare function idleNotifications(participant: Participant, state: NotificationSessionState): (method: string, params: Record<string, unknown>) => void;
+/**
+ * Installs the session's handlers on a new transport, before its first request: notifications
+ * outside a turn, notifications once the transport stopped or is closing, and policy failures
+ * the transport finds itself.
+ */
+export declare function installSessionHandlers(participant: Participant, state: NotificationSessionState, transport: RestrictedCodexTransport): void;
+/** After a request: the turn's handlers come off the transport, and the idle handlers go on. */
+export declare function detachTurn(participant: Participant, state: NotificationSessionState): void;
+export {};