humanish 0.106.0 → 0.107.0

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

@@ -50,39 +50,72 @@ export function restrictedCodexNpmTarget(platform, arch) {
 /** 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 {
+            /* Continue PATH. */
         }
     }
-    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,10 +130,52 @@ 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) {

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

@@ -46,6 +46,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 +118,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();
@@ -147,6 +180,10 @@ export async function launchAdmittedAppServer(settings, state, request, deadline
         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);
+    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 {};

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

@@ -0,0 +1,277 @@
+// The policy every app-server notification passes, whenever it arrives: during the launch
+// handshake, before a turn is dispatched, during a turn, or between requests. A notification that
+// carries an item is checked against the item policy whatever its method, so a new method cannot
+// carry a native operation past it. A method this humanish does not know that carries no item is
+// counted and reported, not refused, so a release's new progress events do not break a run.
+import { codexRecord, toolPolicyViolation, } from "./restricted-policy.js";
+import { RestrictedCodexStop, } from "./restricted-transport.js";
+const rawCompactionTypes = ["compaction", "compaction_summary", "context_compaction"];
+/** Raw response item types an analyst turn may produce. */
+export const ANALYST_RAW_ITEM_TYPES = [
+    "message",
+    "reasoning",
+    ...rawCompactionTypes,
+];
+/** A participant also runs Code Mode: `exec` custom tool calls and `wait` function calls. */
+export const PARTICIPANT_RAW_ITEM_TYPES = [
+    ...ANALYST_RAW_ITEM_TYPES,
+    "custom_tool_call",
+    "custom_tool_call_output",
+    "function_call",
+    "function_call_output",
+];
+/** Thread item types an analyst turn may produce. */
+export const ANALYST_ITEM_TYPES = [
+    "userMessage",
+    "agentMessage",
+    "reasoning",
+    "contextCompaction",
+];
+/** A participant also has its one dynamic tool. */
+export const PARTICIPANT_ITEM_TYPES = [...ANALYST_ITEM_TYPES, "dynamicToolCall"];
+/**
+ * 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 const KNOWN_CODEX_NOTIFICATIONS = new Set([
+    "account/gatewayOAuth/changed",
+    "account/login/completed",
+    "account/rateLimits/updated",
+    "account/updated",
+    "app/list/updated",
+    "autoApprovalReview/strictReviewRequired",
+    "command/exec/outputDelta",
+    "configWarning",
+    "deprecationNotice",
+    "error",
+    "externalAgentConfig/import/completed",
+    "externalAgentConfig/import/progress",
+    "fs/changed",
+    "fuzzyFileSearch/sessionCompleted",
+    "fuzzyFileSearch/sessionUpdated",
+    "guardianWarning",
+    "hook/completed",
+    "hook/started",
+    "item/agentMessage/delta",
+    "item/autoApprovalReview/completed",
+    "item/autoApprovalReview/started",
+    "item/commandExecution/outputDelta",
+    "item/commandExecution/terminalInteraction",
+    "item/completed",
+    "item/fileChange/outputDelta",
+    "item/fileChange/patchUpdated",
+    "item/mcpToolCall/progress",
+    "item/plan/delta",
+    "item/reasoning/summaryPartAdded",
+    "item/reasoning/summaryTextDelta",
+    "item/reasoning/textDelta",
+    "item/started",
+    "mcpServer/event/stream/notification",
+    "mcpServer/oauthLogin/completed",
+    "mcpServer/startupStatus/updated",
+    "model/rerouted",
+    "model/safetyBuffering/updated",
+    "model/verification",
+    "modelProvider/authRecoveryCompleted",
+    "modelProvider/authRecoveryStarted",
+    "process/exited",
+    "process/outputDelta",
+    "project/changed",
+    "rawResponse/completed",
+    "rawResponseItem/completed",
+    "remoteControl/status/changed",
+    "serverRequest/resolved",
+    "skills/changed",
+    "thread/archived",
+    "thread/attachment/updated",
+    "thread/closed",
+    "thread/compacted",
+    "thread/deleted",
+    "thread/environment/connected",
+    "thread/environment/disconnected",
+    "thread/goal/cleared",
+    "thread/goal/updated",
+    "thread/name/updated",
+    "thread/project/updated",
+    "thread/queue/changed",
+    "thread/realtime/closed",
+    "thread/realtime/error",
+    "thread/realtime/item/completed",
+    "thread/realtime/item/started",
+    "thread/realtime/item/transcript/delta",
+    "thread/realtime/itemAdded",
+    "thread/realtime/outputAudio/delta",
+    "thread/realtime/sdp",
+    "thread/realtime/started",
+    "thread/realtime/transcript/delta",
+    "thread/realtime/transcript/done",
+    "thread/reverted",
+    "thread/settings/updated",
+    "thread/started",
+    "thread/status/changed",
+    "thread/tokenUsage/updated",
+    "thread/unarchived",
+    "turn/completed",
+    "turn/diff/updated",
+    "turn/moderationMetadata",
+    "turn/plan/updated",
+    "turn/started",
+    "warning",
+    "windows/worldWritableWarning",
+    "windowsSandbox/setupCompleted",
+]);
+/** The item policy for a session: a participant's tool name is read at each use. */
+export function notificationPolicyOf(participant) {
+    return { participant: participant !== undefined, toolName: () => participant?.tool.name };
+}
+/** Adds one notification of `method` to a session's unknown-method counts. */
+export function countUnknownNotification(counts, method) {
+    counts.set(method, (counts.get(method) ?? 0) + 1);
+}
+const isItem = (value) => value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof value.type === "string";
+/**
+ * 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 function notificationItems(method, params) {
+    const found = [];
+    let malformed = false;
+    const add = (value, itemMethod) => {
+        if (isItem(value))
+            found.push({ method: itemMethod, item: value });
+        else
+            malformed = true;
+    };
+    const addAll = (value, itemMethod) => {
+        if (Array.isArray(value))
+            for (const item of value)
+                add(item, itemMethod);
+    };
+    if (Array.isArray(params.item))
+        addAll(params.item, method);
+    else if (params.item !== undefined && params.item !== null)
+        add(params.item, method);
+    addAll(params.items, method);
+    addAll(codexRecord(params.turn).items, "item/completed");
+    const turns = codexRecord(params.thread).turns;
+    if (Array.isArray(turns))
+        for (const turn of turns)
+            addAll(codexRecord(turn).items, "item/completed");
+    return malformed ? null : found;
+}
+/**
+ * How a notification fares under the item policy: it carries no item, only allowed items, or a
+ * disallowed or malformed one.
+ */
+export function itemPolicyOf(method, params, policy) {
+    const found = notificationItems(method, params);
+    if (found === null)
+        return "violation";
+    if (found.length === 0)
+        return "none";
+    return found.some((entry) => itemPolicyViolation(entry.method, entry.item, policy))
+        ? "violation"
+        : "allowed";
+}
+/**
+ * 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 function itemPolicyViolation(method, item, policy) {
+    const rawTypes = policy.participant ? PARTICIPANT_RAW_ITEM_TYPES : ANALYST_RAW_ITEM_TYPES;
+    const threadItemMethod = method === "item/started" || method === "item/completed";
+    const type = String(item.type);
+    if (method === "rawResponseItem/completed" || (!threadItemMethod && rawTypes.includes(type)))
+        return toolPolicyViolation("rawResponseItem/completed", item, rawTypes);
+    const itemTypes = policy.participant ? PARTICIPANT_ITEM_TYPES : ANALYST_ITEM_TYPES;
+    if (!itemTypes.includes(type))
+        return true;
+    if (type === "dynamicToolCall" && (item.tool !== policy.toolName() || item.namespace !== null))
+        return true;
+    return toolPolicyViolation("item/completed", item, rawTypes);
+}
+/**
+ * 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 function idleNotificationHandler(policy, recordUnknown, refuse) {
+    return (method, params) => {
+        const items = itemPolicyOf(method, params, policy);
+        if (items === "violation")
+            refuse("codex_tool_call");
+        else if (items === "none" && !KNOWN_CODEX_NOTIFICATIONS.has(method))
+            recordUnknown(method);
+    };
+}
+/** The run warning for unknown notification methods, or undefined when there were none. */
+export function unknownNotificationsWarning(counts, cliVersion) {
+    const entries = Object.entries(counts ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0)
+        return undefined;
+    const list = entries.map(([method, count]) => `${method} ×${count}`).join(", ");
+    return `Codex CLI${cliVersion === undefined ? "" : ` ${cliVersion}`} sent notification methods humanish does not know: ${list}. They carried no item and were ignored.`;
+}
+/** The run warning for a last frame cut off by humanish's own stop, or undefined when none was. */
+export function truncatedFrameWarning(bytes) {
+    return bytes === undefined
+        ? undefined
+        : `Codex output was cut off when humanish stopped the app-server: ${bytes} bytes of an unfinished last frame were not checked.`;
+}
+/**
+ * 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 function refuseSession(state, code) {
+    state.policyRefusal ??= code;
+    state.activeDeadline?.stop(code);
+    state.transport?.refuse(code);
+}
+/** The session's handler for notifications outside a dispatched turn, on its current transport. */
+export function idleNotifications(participant, state) {
+    return idleNotificationHandler(notificationPolicyOf(participant), (method) => countUnknownNotification(state.unknownNotifications, method), (code) => refuseSession(state, code));
+}
+/**
+ * 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 function installSessionHandlers(participant, state, transport) {
+    transport.onNotification = idleNotifications(participant, state);
+    transport.onPolicyOnlyNotification = idleNotificationHandler(notificationPolicyOf(participant), (method) => countUnknownNotification(state.unknownNotifications, method), (code) => {
+        state.policyRefusal ??= code;
+    });
+    transport.onPolicyFailure = (code) => {
+        state.policyRefusal ??= code;
+    };
+    transport.onTruncatedFrame = (bytes) => {
+        state.truncatedFrameBytes = (state.truncatedFrameBytes ?? 0) + bytes;
+    };
+}
+/** A server request outside a turn is refused; the transport answers it and stops the request. */
+function idleRequests(state) {
+    return async () => {
+        state.policyRefusal ??= "codex_tool_call";
+        throw new RestrictedCodexStop("codex_tool_call");
+    };
+}
+/** After a request: the turn's handlers come off the transport, and the idle handlers go on. */
+export function detachTurn(participant, state) {
+    const transport = state.transport;
+    if (!transport)
+        return;
+    transport.onNotification = idleNotifications(participant, state);
+    transport.onRequest = idleRequests(state);
+    transport.onRequestComplete = undefined;
+}