humanish 0.106.1 → 0.108.0

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

@@ -2,12 +2,13 @@ import { spawn } from "node:child_process";
 import { chmod, lstat, mkdir, mkdtemp, readdir, realpath, rm, unlink, writeFile, } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
-import { admittedCodexCliVersions } from "./qualified-versions.js";
+import { admitsCodexCliVersion, supportsIsolatedCodex } from "./codex-admission.js";
 import { launchAdmittedAppServer, } from "./restricted-launch.js";
 import { CODEX_IMAGE, CODEX_MAX_OUTPUT_BYTES, CODEX_MAX_REQUEST_BYTES, RESTRICTED_CODEX_ANALYSIS_MODELS, codexRecord, restrictedCodexFailure, restrictedCodexRequestError, } from "./restricted-policy.js";
-import { RestrictedCodexDeadline, RestrictedCodexStop, RestrictedCodexTransport, hasUnclosedChildren, retainUnclosedChild, } from "./restricted-transport.js";
+import { RestrictedCodexDeadline, RestrictedCodexStop, hasUnclosedChildren, retainUnclosedChild, } from "./restricted-transport.js";
 import { checkVersion, childEnvironment, resolveExecutable, restrictedCodexNpmTarget, } from "./restricted-executable.js";
 import { RestrictedCodexTurn } from "./restricted-turn.js";
+import { countUnknownNotification, detachTurn, idleNotifications, installSessionHandlers, notificationPolicyOf, refuseSession, } from "./restricted-notifications.js";
 function validParticipant(options) {
     if (!options)
         return true;
@@ -34,12 +35,29 @@ function validParticipant(options) {
 export async function runRestrictedCodexSession(request, options = {}, readinessOnly = false) {
     const session = createRestrictedCodexSession(options);
     const result = await session.run(request, readinessOnly);
-    return (await session.close())
-        ? result
-        : {
+    const closed = await session.close();
+    const unknownNotifications = session.unknownNotifications ?? {};
+    const truncatedFrameBytes = session.truncatedFrameBytes;
+    const { protocolIncompatibilities, protocolAdditions } = session;
+    const noted = {
+        ...(Object.keys(unknownNotifications).length === 0 ? {} : { unknownNotifications }),
+        ...(truncatedFrameBytes === undefined ? {} : { truncatedFrameBytes }),
+        ...(protocolIncompatibilities === undefined ? {} : { protocolIncompatibilities }),
+        ...(protocolAdditions === undefined || protocolAdditions.length === 0
+            ? {}
+            : { protocolAdditions }),
+    };
+    if (!closed)
+        return {
             ...restrictedCodexFailure("codex_cleanup_failed", result.dispatched, result.usage),
             failurePhase: "cleanup",
+            ...noted,
         };
+    // A disallowed item while the app-server shut down fails a request that had completed.
+    const refusal = session.policyRefusal;
+    return refusal !== undefined && result.errorCode === null
+        ? { ...restrictedCodexFailure(refusal, result.dispatched, result.usage), ...noted }
+        : { ...result, ...noted };
 }
 async function writeRecoveryMarker(work, sourceEnv, reason) {
     const cache = sourceEnv.XDG_CACHE_HOME ?? path.join(sourceEnv.HOME ?? homedir(), ".cache");
@@ -200,17 +218,12 @@ function newTurn(settings, state, deadline) {
         turnStarted: (turnId) => {
             state.interrupt = { threadId: state.threadId, turnId };
         },
+        policy: notificationPolicyOf(participant),
+        idle: (method, params) => idleNotifications(participant, state)(method, params),
+        recordUnknown: (method) => countUnknownNotification(state.unknownNotifications, method),
+        refuse: (code) => refuseSession(state, code),
     });
 }
-/** After a request: the turn's handlers come off the transport. */
-function detachTurn(transport) {
-    if (transport)
-        transport.onNotification = () => undefined;
-    if (transport)
-        transport.onRequest = undefined;
-    if (transport)
-        transport.onRequestComplete = undefined;
-}
 /** Request dispatch: launch on the first request, then one turn; a failed request tears down. */
 async function runTurn(settings, state, dispose, request, readinessOnly) {
     const participant = settings.participant;
@@ -228,13 +241,13 @@ async function runTurn(settings, state, dispose, request, readinessOnly) {
         if (!state.transport) {
             state.transport = await launchAdmittedAppServer(settings, state, request, deadline, frameLimit, (next) => {
                 phase = next;
-            });
+            }, (transport) => installSessionHandlers(participant, state, transport));
             selectedModel = state.identity.model;
         }
         else
             state.transport.beginRequest(deadline, frameLimit);
-        // onNotification ignores events before dispatch and onRequestComplete follows only a host
-        // callback, so wiring both after the first launch's handshake loses nothing.
+        // Before dispatch the turn passes notifications to the idle handler the launch installed,
+        // and onRequestComplete follows only a host callback, so wiring both here loses nothing.
         state.transport.onNotification = turn.onNotification;
         state.transport.onRequestComplete = turn.onRequestComplete;
         if (readinessOnly)
@@ -269,7 +282,7 @@ async function runTurn(settings, state, dispose, request, readinessOnly) {
         state.pendingInferenceUsage = undefined;
         deadline.close();
         state.activeDeadline = undefined;
-        detachTurn(state.transport);
+        detachTurn(participant, state);
         if (result.errorCode !== null) {
             if (result.errorCode === "codex_cleanup_failed")
                 state.cleanupTrusted = false;
@@ -299,11 +312,16 @@ function refusedRun(settings, state, request, busy) {
         return restrictedCodexFailure("codex_busy");
     const supportedPlatform = operatorAuth
         ? restrictedCodexNpmTarget(platform, arch) !== undefined
-        : (platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64");
+        : supportsIsolatedCodex(platform, arch);
     if (!supportedPlatform)
         return restrictedCodexFailure("codex_unsupported_platform");
     return undefined;
 }
+/** Which releases a session starts: launch admission, or the qualifier's exact list. */
+function launchAdmission(options) {
+    const exact = options.cliVersions;
+    return exact === undefined ? admitsCodexCliVersion : (version) => exact.includes(version);
+}
 export function createRestrictedCodexSession(options = {}) {
     // Option reads keep their old order: platform, arch, env, participant, spawnFn, cliVersions.
     const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
@@ -318,7 +336,7 @@ export function createRestrictedCodexSession(options = {}) {
         operatorAuth: participant?.authMode === "operator",
         reasoningEffort: participant?.reasoningEffort ?? "low",
         spawnFn: options.spawnFn ?? ((file, args, spawnOptions) => spawn(file, args, spawnOptions)),
-        admittedVersions: options.cliVersions ?? admittedCodexCliVersions(platform, arch),
+        admits: launchAdmission(options),
     };
     const state = {
         work: undefined,
@@ -335,10 +353,15 @@ export function createRestrictedCodexSession(options = {}) {
         resolvedModel: undefined,
         authentication: undefined,
         cliVersion: undefined,
+        unknownNotifications: new Map(),
+        protocolIncompatibilities: undefined,
+        protocolAdditions: undefined,
         activeDeadline: undefined,
         interrupt: undefined,
         closed: false,
         cleanupTrusted: true,
+        policyRefusal: undefined,
+        truncatedFrameBytes: undefined,
     };
     let pending, closing, disposing;
     const dispose = () => {
@@ -361,6 +384,21 @@ export function createRestrictedCodexSession(options = {}) {
         get cliVersion() {
             return state.cliVersion;
         },
+        get unknownNotifications() {
+            return Object.fromEntries(state.unknownNotifications);
+        },
+        get policyRefusal() {
+            return state.policyRefusal;
+        },
+        get truncatedFrameBytes() {
+            return state.truncatedFrameBytes;
+        },
+        get protocolIncompatibilities() {
+            return state.protocolIncompatibilities;
+        },
+        get protocolAdditions() {
+            return state.protocolAdditions;
+        },
         run(request, readinessOnly = false) {
             const refusal = refusedRun(settings, state, request, () => pending !== undefined);
             if (refusal)
@@ -401,7 +439,7 @@ export async function checkRestrictedCodexSessionReadiness(input = {}, options =
  * `--version` runs with a private temporary home, removed afterwards. */
 export async function detectRestrictedCodexCliVersion(input = {}, options = {}) {
     const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
-    if (!((platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64")))
+    if (!supportsIsolatedCodex(platform, arch))
         return { cliVersion: null, errorCode: "codex_unsupported_platform" };
     const sourceEnv = options.env ?? process.env;
     const deadline = new RestrictedCodexDeadline(input.timeoutMs ?? 15_000, input.signal);
@@ -411,7 +449,7 @@ export async function detectRestrictedCodexCliVersion(input = {}, options = {})
         work = await realpath(await mkdtemp(path.join(options.tempRoot ?? tmpdir(), "humanish-codex-version-")));
         const home = path.join(work, "home");
         await mkdir(home, { mode: 0o700 });
-        const cliVersion = await checkVersion(file, childEnvironment(sourceEnv, home, work), work, options.spawnFn ?? ((command, args, settings) => spawn(command, args, settings)), deadline, options.cliVersions ?? admittedCodexCliVersions(platform, arch), options.cliVersion);
+        const cliVersion = await checkVersion(file, childEnvironment(sourceEnv, home, work), work, options.spawnFn ?? ((command, args, settings) => spawn(command, args, settings)), deadline, launchAdmission(options), options.cliVersion);
         return { cliVersion, errorCode: null };
     }
     catch (error) {

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

@@ -34,11 +34,21 @@ export declare class RestrictedCodexDeadline {
 }
 export declare function retainUnclosedChild(closed: Promise<void>): void;
 export declare const hasUnclosedChildren: () => boolean;
+/** How the process exited: its exit code, or the signal that ended it. */
+interface OwnedCodexExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
 export interface OwnedCodexProcess {
     child: ChildProcessWithoutNullStreams;
     closed: Promise<void>;
     isClosed(): boolean;
     hasExited(): boolean;
+    /** Resolves with the 'exit' event's code and signal. */
+    readonly exit: Promise<OwnedCodexExit>;
+    /** The signals humanish delivered while the process was still running (signalOwnedChild). */
+    signalsSent(): readonly NodeJS.Signals[];
+    recordSignal(signal: NodeJS.Signals): void;
 }
 export declare function ownCodexProcess(child: ChildProcessWithoutNullStreams): OwnedCodexProcess;
 export declare function closeOwnedCodexProcess(owned: OwnedCodexProcess): Promise<boolean>;
@@ -55,11 +65,29 @@ export declare class RestrictedCodexTransport {
     private eventCount;
     private closing;
     onNotification: (method: string, params: Record<string, unknown>) => void;
+    /** Notifications after the deadline stopped or close began: no turn handles them, only the policy. */
+    onPolicyOnlyNotification: (method: string, params: Record<string, unknown>) => void;
+    /** A server request with no handler, or output that could not be checked (failUninspected). */
+    onPolicyFailure: (code: RestrictedCodexAnalysisErrorCode) => void;
+    /** The size of a last frame cut off after humanish stopped the process: a warning only. */
+    onTruncatedFrame: (bytes: number) => void;
     onRequest: ((method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>) | undefined;
     onRequestComplete: (() => void) | undefined;
     constructor(owned: OwnedCodexProcess, deadline: RestrictedCodexDeadline, frameLimit?: number);
     /** A completed turn releases its deadline and wire budget, not its conversation. */
     beginRequest(deadline: RestrictedCodexDeadline, frameLimit: number): void;
+    /** One line of output: a malformed line could not be checked. */
+    private frame;
+    /**
+     * Output that could not be checked: past a byte, frame or event limit, malformed, or cut off.
+     * The session records it through onPolicyFailure, whatever state the transport is in.
+     */
+    private failUninspected;
+    /**
+     * Refuses the session with `code`: stops the current deadline and rejects pending requests.
+     * Between requests the stopped deadline makes the next beginRequest throw the code.
+     */
+    refuse(code: RestrictedCodexAnalysisErrorCode): void;
     private fail;
     private message;
     private write;
@@ -71,3 +99,4 @@ export declare class RestrictedCodexTransport {
         turnId: string;
     }): Promise<boolean>;
 }
+export {};

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

@@ -91,8 +91,12 @@ export function retainUnclosedChild(closed) {
 export const hasUnclosedChildren = () => unclosedChildren.size > 0;
 export function ownCodexProcess(child) {
     let closed = false, exited = false;
-    child.once("exit", () => {
-        exited = true;
+    const sent = [];
+    const exit = new Promise((resolve) => {
+        child.once("exit", (code, signal) => {
+            exited = true;
+            resolve({ code, signal });
+        });
     });
     const completion = new Promise((resolve) => {
         child.once("close", () => {
@@ -100,7 +104,17 @@ export function ownCodexProcess(child) {
             resolve();
         });
     });
-    return { child, closed: completion, isClosed: () => closed, hasExited: () => exited };
+    return {
+        child,
+        closed: completion,
+        isClosed: () => closed,
+        hasExited: () => exited,
+        exit,
+        signalsSent: () => sent,
+        recordSignal: (signal) => {
+            sent.push(signal);
+        },
+    };
 }
 async function settlesWithin(promise, ms) {
     let timer;
@@ -122,7 +136,9 @@ function signalOwnedChild(owned, signal) {
     if (owned.hasExited() || owned.isClosed())
         return;
     try {
-        owned.child.kill(signal);
+        // kill() is true when the signal was delivered.
+        if (owned.child.kill(signal))
+            owned.recordSignal(signal);
     }
     catch {
         /* Closing is still checked below. */
@@ -142,6 +158,15 @@ export async function closeOwnedCodexProcess(owned) {
     owned.child.stderr.destroy();
     return closed;
 }
+function isJson(text) {
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export class RestrictedCodexTransport {
     owned;
     deadline;
@@ -155,6 +180,12 @@ export class RestrictedCodexTransport {
     eventCount = 0;
     closing = false;
     onNotification = () => undefined;
+    /** Notifications after the deadline stopped or close began: no turn handles them, only the policy. */
+    onPolicyOnlyNotification = () => undefined;
+    /** A server request with no handler, or output that could not be checked (failUninspected). */
+    onPolicyFailure = () => undefined;
+    /** The size of a last frame cut off after humanish stopped the process: a warning only. */
+    onTruncatedFrame = () => undefined;
     onRequest;
     onRequestComplete;
     constructor(owned, deadline, frameLimit = CODEX_MAX_OUTPUT_BYTES) {
@@ -165,38 +196,59 @@ export class RestrictedCodexTransport {
         child.on("error", () => this.fail("codex_process_failed"));
         child.stdin.on("error", () => this.fail("codex_process_failed"));
         child.on("close", () => this.fail("codex_process_failed"));
+        // Output is read until the process exits. Once the deadline stops or close begins, it is read
+        // for the item policy only (message); only the byte and frame limits stop reading, and they
+        // count as unchecked output.
         child.stdout.on("data", (chunk) => {
-            if ((!this.closing && this.deadline.code !== null) ||
-                (this.closing && this.pending.size === 0))
-                return;
             this.stdoutBytes += chunk.length;
             if (this.stdoutBytes >
                 Math.max(CODEX_MAX_STDOUT_BYTES, this.frameLimit * 2 + CODEX_MAX_OUTPUT_BYTES * 2)) {
-                this.fail("response_too_large");
+                this.failUninspected("response_too_large");
                 return;
             }
             this.line += this.decoder.write(chunk);
             if (Buffer.byteLength(this.line) > this.frameLimit) {
-                this.fail("response_too_large");
+                this.failUninspected("response_too_large");
                 return;
             }
             while (this.line.includes("\n")) {
-                const split = this.line.indexOf("\n"), line = this.line.slice(0, split);
+                const split = this.line.indexOf("\n");
+                const line = this.line.slice(0, split);
                 this.line = this.line.slice(split + 1);
-                if (line.length === 0) {
-                    this.fail("codex_protocol_error");
-                    return;
-                }
-                try {
-                    this.message(JSON.parse(line));
-                }
-                catch {
-                    this.fail("codex_protocol_error");
-                }
-                if (this.deadline.code !== null && !this.closing)
-                    return;
+                this.frame(line);
             }
         });
+        // A last frame without its newline is parsed when it is whole JSON. A cut-off frame is a
+        // warning with its size only when humanish's own signal cut it: the signal reached the running
+        // process before its output ended, and the process then exited by that signal or with a code.
+        // Any other cut-off frame (an exit on its own, a crash, a signal humanish did not send) went
+        // unchecked.
+        child.stdout.on("end", () => {
+            const rest = this.line + this.decoder.end();
+            this.line = "";
+            const lines = rest.split("\n").filter((line) => line.length > 0);
+            const last = lines.pop();
+            for (const line of lines)
+                this.frame(line);
+            if (last === undefined)
+                return;
+            if (isJson(last)) {
+                this.frame(last);
+                return;
+            }
+            if (this.owned.signalsSent().length === 0) {
+                this.failUninspected("codex_protocol_error");
+                return;
+            }
+            const bytes = Buffer.byteLength(last);
+            void this.owned.exit.then(({ code, signal }) => {
+                const ours = signal === null ? code !== null : this.owned.signalsSent().includes(signal);
+                if (ours)
+                    this.onTruncatedFrame(bytes);
+                else
+                    this.failUninspected("codex_protocol_error");
+            });
+        });
         child.stderr.on("data", (chunk) => {
             this.stderrBytes += chunk.length;
             if (this.stderrBytes > CODEX_MAX_OUTPUT_BYTES)
@@ -215,6 +267,41 @@ export class RestrictedCodexTransport {
         this.stderrBytes = 0;
         this.eventCount = 0;
     }
+    /** One line of output: a malformed line could not be checked. */
+    frame(line) {
+        let parsed;
+        try {
+            parsed = line.length === 0 ? undefined : JSON.parse(line);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (parsed === undefined) {
+            this.failUninspected("codex_protocol_error");
+            return;
+        }
+        try {
+            this.message(parsed);
+        }
+        catch {
+            this.fail("codex_protocol_error");
+        }
+    }
+    /**
+     * Output that could not be checked: past a byte, frame or event limit, malformed, or cut off.
+     * The session records it through onPolicyFailure, whatever state the transport is in.
+     */
+    failUninspected(code) {
+        this.onPolicyFailure(code);
+        this.fail(code);
+    }
+    /**
+     * Refuses the session with `code`: stops the current deadline and rejects pending requests.
+     * Between requests the stopped deadline makes the next beginRequest throw the code.
+     */
+    refuse(code) {
+        this.fail(code);
+    }
     fail(code) {
         if (!this.closing)
             this.deadline.stop(code);
@@ -225,13 +312,31 @@ export class RestrictedCodexTransport {
     message(raw) {
         const value = codexRecord(raw);
         if (Object.keys(value).length === 0) {
-            this.fail("codex_protocol_error");
+            this.failUninspected("codex_protocol_error");
             return;
         }
+        // After the deadline stopped or close began, output is read for the item policy only.
+        const policyOnly = this.closing || this.deadline.code !== null;
         if (value.id !== undefined && typeof value.method === "string") {
+            // A server request is then declined unhandled: its turn is over or being interrupted, so a
+            // tool call that crossed the stop runs nothing and is not a policy refusal.
+            if (policyOnly) {
+                try {
+                    this.write({
+                        id: value.id,
+                        error: { code: -32601, message: "Host request is disabled" },
+                    });
+                }
+                catch {
+                    /* The process is already closing. */
+                }
+                return;
+            }
             if (!this.onRequest || ++this.eventCount > CODEX_MAX_EVENTS) {
+                const code = this.eventCount > CODEX_MAX_EVENTS ? "response_too_large" : "codex_tool_call";
+                this.onPolicyFailure(code);
                 this.write({ id: value.id, error: { code: -32601, message: "Host request is disabled" } });
-                this.fail(this.eventCount > CODEX_MAX_EVENTS ? "response_too_large" : "codex_tool_call");
+                this.fail(code);
                 return;
             }
             const id = value.id;
@@ -263,7 +368,9 @@ export class RestrictedCodexTransport {
         if (typeof value.id === "number" && value.method === undefined) {
             const pending = this.pending.get(value.id);
             if (!pending) {
-                this.fail("codex_protocol_error");
+                // A late reply, such as an interrupt's after its wait, carries no item.
+                if (!policyOnly)
+                    this.fail("codex_protocol_error");
                 return;
             }
             this.pending.delete(value.id);
@@ -280,10 +387,12 @@ export class RestrictedCodexTransport {
         if (typeof value.method !== "string" ||
             value.id !== undefined ||
             ++this.eventCount > CODEX_MAX_EVENTS) {
-            this.fail(this.eventCount > CODEX_MAX_EVENTS ? "response_too_large" : "codex_protocol_error");
+            this.failUninspected(this.eventCount > CODEX_MAX_EVENTS ? "response_too_large" : "codex_protocol_error");
             return;
         }
-        if (!this.closing)
+        if (policyOnly)
+            this.onPolicyOnlyNotification(value.method, codexRecord(value.params));
+        else
             this.onNotification(value.method, codexRecord(value.params));
     }
     write(value) {
@@ -324,6 +433,9 @@ export class RestrictedCodexTransport {
     }
     async close(interrupt) {
         this.closing = true;
+        // Shutdown output gets its own byte and event budget.
+        this.stdoutBytes = 0;
+        this.eventCount = 0;
         if (interrupt && !this.owned.isClosed()) {
             const { id, result } = this.request("turn/interrupt", interrupt);
             await settlesWithin(result, 1000);

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

@@ -1,5 +1,6 @@
-import { type RestrictedCodexResult, type RestrictedCodexUsage } from "./restricted-policy.js";
+import { type RestrictedCodexAnalysisErrorCode, type RestrictedCodexResult, type RestrictedCodexUsage } from "./restricted-policy.js";
 import { type RestrictedCodexDeadline, type RestrictedCodexTransport } from "./restricted-transport.js";
+import { type NotificationPolicy } from "./restricted-notifications.js";
 /** What a turn reads from and reports to its session. */
 export interface RestrictedCodexTurnContext {
     readonly deadline: RestrictedCodexDeadline;
@@ -23,11 +24,23 @@ export interface RestrictedCodexTurnContext {
     reportUsage(usage: RestrictedCodexUsage | undefined, inference: RestrictedCodexUsage[] | undefined): void;
     /** The turn the session interrupts if it closes now. */
     turnStarted(turnId: string): void;
+    /** The item policy every notification's item passes, whatever its method. */
+    readonly policy: NotificationPolicy;
+    /** The session's handler for notifications that arrive before this turn is dispatched. */
+    idle(method: string, params: Record<string, unknown>): void;
+    /** Counts a notification method this humanish does not know that carried no item. */
+    recordUnknown(method: string): void;
+    /**
+     * A policy refusal: stops this request with `code`, and the session records it when the
+     * request already stopped for another reason, such as a close.
+     */
+    refuse(code: RestrictedCodexAnalysisErrorCode): void;
 }
 /**
- * Drain: every notification and tool request of one turn. Nothing is handled before `dispatched`;
- * events that arrive before turn/start's reply wait until acknowledge() and are then checked in
- * order. `finished` resolves only with a completed, validated final answer.
+ * Drain: every notification and tool request of one turn. Before `dispatched`, notifications go
+ * to the session's idle handler; events that arrive after dispatch but before turn/start's reply
+ * pass the item policy at once, then wait until acknowledge() and are checked in order.
+ * `finished` resolves only with a completed, validated final answer.
  */
 export declare class RestrictedCodexTurn {
     private readonly context;
@@ -53,6 +66,8 @@ export declare class RestrictedCodexTurn {
     acknowledge(returnedTurnId: unknown): void;
     readonly onNotification: RestrictedCodexTransport["onNotification"];
     readonly onRequest: NonNullable<RestrictedCodexTransport["onRequest"]>;
+    /** Refuses a tool request: the session records the refusal, and the transport answers it. */
+    private refuseRequest;
     readonly onRequestComplete: () => void;
     private handleTurnEvent;
     private recordUsage;