humanish 0.105.0 → 0.106.0

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

@@ -0,0 +1,116 @@
+import type { CuaProviderFailurePhase } from "../computer-use/provider-error.js";
+import type { ReasoningEffort } from "../reasoning-effort.js";
+import { type RestrictedCodexAnalysisErrorCode, type RestrictedCodexConfigMode, type RestrictedCodexRequest } from "./restricted-policy.js";
+import { RestrictedCodexDeadline, RestrictedCodexTransport, type RestrictedCodexSpawn } from "./restricted-transport.js";
+/** The host options a launch reads; RestrictedCodexSessionOptions carries them. */
+interface LaunchOptions {
+    executable?: string;
+    authHome?: string;
+    tempRoot?: string;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    cliVersion?: string;
+}
+/** What a launch reads and the session never changes. */
+export interface LaunchSettings {
+    readonly options: LaunchOptions;
+    readonly platform: NodeJS.Platform;
+    readonly sourceEnv: NodeJS.ProcessEnv;
+    readonly participant: {
+        readonly tool: ThreadTool;
+    } | undefined;
+    readonly operatorAuth: boolean;
+    readonly reasoningEffort: ReasoningEffort;
+    readonly spawnFn: RestrictedCodexSpawn;
+    readonly admittedVersions: readonly string[];
+}
+/** What a launch records on the session, each piece as soon as it exists. */
+export interface LaunchState {
+    /** The private task directory (teardown removes it). */
+    work: string | undefined;
+    /** The private home's link to the host auth.json (teardown unlinks it). */
+    authLink: string | undefined;
+    /** The app-server (each request and teardown use it). */
+    transport: RestrictedCodexTransport | undefined;
+    /** The thread, its cwd and scratch directory (each request uses them). */
+    threadId: string | undefined;
+    cwd: string;
+    scratch: string;
+    /** The model and instructions the thread started with (each request and its admission). */
+    identity: {
+        requestedModel: string | undefined;
+        model: string;
+        instructions: string;
+    } | undefined;
+    /** What the launch admitted (the session's getters). */
+    resolvedModel: string | undefined;
+    authentication: "chatgpt-account" | "api-key" | undefined;
+    cliVersion: string | undefined;
+}
+/** An admitted value, or the refusal a launch stops with. */
+export type Admission<T> = {
+    readonly value: T;
+} | {
+    readonly refusal: RestrictedCodexAnalysisErrorCode;
+};
+/** The admitted value; a refusal stops the launch. */
+export declare function admitted<T>(admission: Admission<T>): T;
+/** `-c key=value` arguments for an operator-auth launch, which keeps the operator's config file. */
+export declare function configArguments(overrides: Record<string, unknown>): string[];
+/** initialize: the admitted release, this platform, and (isolated auth) the private home. */
+export declare function admitInitialize(reply: Record<string, unknown>, expected: {
+    cliVersion: string;
+    home: string;
+    operatorAuth: boolean;
+    platform: NodeJS.Platform;
+}): Admission<void>;
+/** config/read: the restricted configuration, and the model it selects, if any. */
+export declare function admitEffectiveConfig(reply: Record<string, unknown>, configPath: string, requestedModel: string | undefined, mode: RestrictedCodexConfigMode): Admission<string | undefined>;
+/** account/read: a ChatGPT account (or, with operator auth, an API key) that requires auth. */
+export declare function admitAccount(reply: Record<string, unknown>, operatorAuth: boolean): Admission<"chatgpt-account" | "api-key">;
+/**
+ * The thread's config: the restricted overrides, with every inherited MCP server disabled. Codex
+ * splits request overrides literally on dots, so a server name outside TOML bare-key characters
+ * could not be targeted, and more than 100 servers is refused.
+ */
+export declare function threadConfigFor(effectiveConfig: Record<string, unknown>, overrides: Record<string, unknown>): Admission<Record<string, unknown>>;
+/** The participant's one dynamic tool, as thread/start declares it. */
+export interface ThreadTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * thread/start: an ephemeral, read-only thread with no environments and at most one tool. The
+ * participant's tool is read field by field, then the request's instructions, in the order the
+ * session always read them.
+ */
+export declare function threadStartParams(args: {
+    cwd: string;
+    model: string | undefined;
+    participant: {
+        readonly tool: ThreadTool;
+    } | undefined;
+    request: {
+        readonly instructions: string;
+    };
+    config: Record<string, unknown>;
+}): Record<string, unknown>;
+/** thread/start's reply: the model it runs (the selected one, when one was) and the thread id. */
+export declare function admitThread(reply: Record<string, unknown>, expected: {
+    selectedModel: string | undefined;
+    cwd: string;
+    reasoningEffort: ReasoningEffort;
+    cliVersion: string;
+}): Admission<{
+    model: string;
+    threadId: string;
+}>;
+/** mcpServerStatus/list (isolated auth): no MCP server is running for the thread. */
+export declare function admitMcpStatus(reply: Record<string, unknown>): Admission<void>;
+/**
+ * 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 {};

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

@@ -0,0 +1,222 @@
+// The restricted app-server launch: the one-time private home, version check and spawn, then the
+// handshake (initialize, config, account, thread, MCP status). Each admit* check reads one
+// handshake reply and the settings it depends on, and returns the admitted value or the refusal;
+// 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 { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { checkVersion, childEnvironment, resolveExecutable } from "./restricted-executable.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. */
+export function admitted(admission) {
+    if ("refusal" in admission)
+        throw new RestrictedCodexStop(admission.refusal);
+    return admission.value;
+}
+/** `-c key=value` arguments for an operator-auth launch, which keeps the operator's config file. */
+export function configArguments(overrides) {
+    return Object.entries(overrides).flatMap(([key, value]) => [
+        "-c",
+        `${key}=${JSON.stringify(value)}`,
+    ]);
+}
+/** initialize: the admitted release, this platform, and (isolated auth) the private home. */
+export function admitInitialize(reply, expected) {
+    if (typeof reply.userAgent !== "string" ||
+        !reply.userAgent.includes(`/${expected.cliVersion} `) ||
+        (!expected.operatorAuth && reply.codexHome !== expected.home) ||
+        reply.platformOs !== (expected.platform === "darwin" ? "macos" : "linux") ||
+        reply.platformFamily !== "unix")
+        return { refusal: "codex_unsupported_version" };
+    return { value: undefined };
+}
+/** config/read: the restricted configuration, and the model it selects, if any. */
+export function admitEffectiveConfig(reply, configPath, requestedModel, mode) {
+    if (!admitsRestrictedCodexConfig(reply, configPath, requestedModel, mode))
+        return { refusal: "codex_unsafe_configuration" };
+    const configuredModel = codexRecord(reply.config).model;
+    return { value: typeof configuredModel === "string" ? configuredModel : undefined };
+}
+/** account/read: a ChatGPT account (or, with operator auth, an API key) that requires auth. */
+export function admitAccount(reply, operatorAuth) {
+    if (reply.account === null)
+        return { refusal: "codex_login_required" };
+    const accountType = codexRecord(reply.account).type;
+    if ((!operatorAuth && accountType !== "chatgpt") ||
+        (operatorAuth && !["chatgpt", "apiKey"].includes(String(accountType))) ||
+        reply.requiresOpenaiAuth !== true)
+        return { refusal: "codex_unsupported_auth" };
+    return { value: accountType === "apiKey" ? "api-key" : "chatgpt-account" };
+}
+/**
+ * The thread's config: the restricted overrides, with every inherited MCP server disabled. Codex
+ * splits request overrides literally on dots, so a server name outside TOML bare-key characters
+ * could not be targeted, and more than 100 servers is refused.
+ */
+export function threadConfigFor(effectiveConfig, overrides) {
+    const mcpNames = Object.keys(codexRecord(codexRecord(effectiveConfig.config).mcp_servers));
+    if (mcpNames.length > 100 || mcpNames.some((name) => !/^[A-Za-z0-9_-]{1,200}$/.test(name)))
+        return { refusal: "codex_unsafe_configuration" };
+    const threadConfig = { ...overrides };
+    for (const name of mcpNames)
+        threadConfig[`mcp_servers.${name}.enabled`] = false;
+    return { value: threadConfig };
+}
+/**
+ * thread/start: an ephemeral, read-only thread with no environments and at most one tool. The
+ * participant's tool is read field by field, then the request's instructions, in the order the
+ * session always read them.
+ */
+export function threadStartParams(args) {
+    const participant = args.participant;
+    return {
+        cwd: args.cwd,
+        ephemeral: true,
+        experimentalRawEvents: true,
+        approvalPolicy: "never",
+        sandbox: "read-only",
+        model: args.model,
+        modelProvider: "openai",
+        allowProviderModelFallback: false,
+        environments: [],
+        runtimeWorkspaceRoots: [],
+        dynamicTools: participant
+            ? [
+                {
+                    type: "function",
+                    name: participant.tool.name,
+                    description: participant.tool.description,
+                    inputSchema: participant.tool.inputSchema,
+                },
+            ]
+            : [],
+        baseInstructions: args.request.instructions,
+        config: args.config,
+    };
+}
+/** thread/start's reply: the model it runs (the selected one, when one was) and the thread id. */
+export function admitThread(reply, expected) {
+    const returnedModel = codexRecord(reply.thread).model;
+    if (typeof returnedModel !== "string" ||
+        returnedModel.length === 0 ||
+        returnedModel.length > 200 ||
+        (expected.selectedModel !== undefined && returnedModel !== expected.selectedModel) ||
+        !admitsRestrictedCodexThread(reply, returnedModel, expected.cwd, expected.reasoningEffort, expected.cliVersion))
+        return { refusal: "codex_unsafe_configuration" };
+    return { value: { model: returnedModel, threadId: String(codexRecord(reply.thread).id) } };
+}
+/** mcpServerStatus/list (isolated auth): no MCP server is running for the thread. */
+export function admitMcpStatus(reply) {
+    if (!Array.isArray(reply.data) || reply.data.length !== 0 || reply.nextCursor !== null)
+        return { refusal: "codex_unsafe_configuration" };
+    return { value: undefined };
+}
+/** 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");
+    if (!path.isAbsolute(authHome))
+        throw new RestrictedCodexStop("codex_unsupported_auth");
+    try {
+        const authFile = await realpath(path.join(authHome, "auth.json"));
+        if (!(await stat(authFile)).isFile())
+            throw new Error();
+        return authFile;
+    }
+    catch {
+        throw new RestrictedCodexStop("codex_login_required");
+    }
+}
+/**
+ * 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) {
+    const { options, sourceEnv, participant, operatorAuth, reasoningEffort, spawnFn } = settings;
+    const file = await resolveExecutable(options, sourceEnv);
+    deadline.check();
+    state.work = await mkdtemp(path.join(options.tempRoot ?? tmpdir(), "humanish-codex-analysis-"));
+    await chmod(state.work, 0o700);
+    state.work = await realpath(state.work);
+    const home = path.join(state.work, "home");
+    state.cwd = path.join(state.work, "cwd");
+    state.scratch = path.join(state.work, "scratch");
+    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);
+    const configMode = {
+        participantCodeMode: participant !== undefined,
+        reasoningEffort,
+        operatorAuth,
+    };
+    const config = restrictedCodexConfig(request.model, configMode), configPath = path.join(home, "config.toml");
+    if (!operatorAuth) {
+        await writeFile(configPath, config.toml, { mode: 0o600, flag: "wx" });
+        const authFile = await hostAuthFile(options, sourceEnv);
+        deadline.check();
+        state.authLink = path.join(home, "auth.json");
+        await symlink(authFile, state.authLink);
+    }
+    deadline.check();
+    const appServerArgs = [
+        "app-server",
+        "--strict-config",
+        ...(operatorAuth ? configArguments(config.overrides) : []),
+    ];
+    const owned = ownCodexProcess(spawnFn(file, appServerArgs, {
+        cwd: state.cwd,
+        env: operatorAuth ? { ...sourceEnv } : env,
+        detached: false,
+        stdio: ["pipe", "pipe", "pipe"],
+    }));
+    const launched = new RestrictedCodexTransport(owned, deadline, frameLimit);
+    state.transport = launched;
+    enter("initialize");
+    const initialize = await launched.rpc("initialize", {
+        clientInfo: { name: "humanish_analysis", version: "1.0.0" },
+        capabilities: { experimentalApi: true },
+    });
+    admitted(admitInitialize(initialize, {
+        cliVersion: state.cliVersion,
+        home,
+        operatorAuth,
+        platform: settings.platform,
+    }));
+    launched.notify("initialized", {});
+    enter("config/read");
+    const effective = await launched.rpc("config/read", { includeLayers: true, cwd: state.cwd });
+    const selectedModel = admitted(admitEffectiveConfig(effective, configPath, request.model, configMode));
+    enter("account/read");
+    const account = await launched.rpc("account/read", { refreshToken: false });
+    state.authentication = admitted(admitAccount(account, operatorAuth));
+    const threadConfig = admitted(threadConfigFor(effective, config.overrides));
+    enter("thread/start");
+    const thread = await launched.rpc("thread/start", threadStartParams({
+        cwd: state.cwd,
+        model: selectedModel,
+        participant,
+        request,
+        config: threadConfig,
+    }));
+    const started = admitted(admitThread(thread, {
+        selectedModel,
+        cwd: state.cwd,
+        reasoningEffort,
+        cliVersion: state.cliVersion,
+    }));
+    state.resolvedModel = started.model;
+    state.threadId = started.threadId;
+    if (!operatorAuth) {
+        enter("mcpServerStatus/list");
+        admitted(admitMcpStatus(await launched.rpc("mcpServerStatus/list", { limit: 100 })));
+    }
+    state.identity = {
+        requestedModel: request.model,
+        model: started.model,
+        instructions: request.instructions,
+    };
+    return launched;
+}

package/dist/actors/codex/restricted-participant-policy.d.ts

@@ -0,0 +1,46 @@
+import { type CuaTurn } from "../computer-use/loop.js";
+import type { ActorExecutionProfile, ParticipantClosingReport } from "../contract.js";
+/** The declared profile. A participant replaces cliVersion with its detected CLI release, or with
+ * this host's newest qualified release before its first launch. */
+export declare const PARTICIPANT_PROFILE: Readonly<ActorExecutionProfile>;
+export declare const PARTICIPANT_LIMITS: Readonly<{
+    instructions: number;
+    hint: number;
+    narration: 2000;
+    output: number;
+    actions: 4;
+    requestMs: 180000;
+    cleanupMs: 5000;
+}>;
+export declare function participantToolSchema(speechEnabled?: boolean): Record<string, unknown>;
+export declare const PARTICIPANT_TOOL_SCHEMA: Record<string, unknown>;
+export declare const PARTICIPANT_FINAL_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        outcome: {
+            type: string;
+            enum: string[];
+        };
+        summary: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+        };
+        frictionReports: {
+            type: string;
+            maxItems: number;
+            items: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+};
+/** humanish tool arguments, validated before the shared executor sees a batch. */
+export declare function parseParticipantTool(value: unknown, speechEnabled?: boolean): CuaTurn;
+export declare function parseParticipantFinal(value: unknown): CuaTurn & {
+    closingReport: ParticipantClosingReport;
+};

package/dist/actors/codex/restricted-participant-policy.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { browserControlActionSchema, browserOnlyControlActionSchema, validateBrowserControlAction, } from "../../browser-control/protocol.js";
+import { validClosingReport } from "../computer-use/loop.js";
+/** The declared profile. A participant replaces cliVersion with its detected CLI release, or with
+ * this host's newest qualified release before its first launch. */
+export const PARTICIPANT_PROFILE = Object.freeze({
+    schema: "humanish.actor-execution-profile.v1",
+    transport: "codex-app-server",
+    authentication: "chatgpt-account",
+    billing: "account-unknown",
+    requestedModel: "gpt-6-astra",
+    reasoningEffort: "low",
+    cliVersion: "0.154.0",
+    toolPolicy: "codex-ui-tools-v1",
+    participantSchema: "humanish.codex-ui-tool.v1",
+    memoryPolicy: "continuing-thread-v1",
+});
+export const PARTICIPANT_LIMITS = Object.freeze({
+    instructions: 64 * 1024,
+    hint: 8 * 1024,
+    narration: 2000,
+    output: 256 * 1024,
+    actions: 4,
+    requestMs: 180_000,
+    cleanupMs: 5000,
+});
+const toolInput = (speechEnabled) => z.strictObject({
+    narration: z.string().max(PARTICIPANT_LIMITS.narration),
+    actions: z
+        .array(speechEnabled ? browserControlActionSchema : browserOnlyControlActionSchema)
+        .min(1)
+        .max(PARTICIPANT_LIMITS.actions),
+});
+export function participantToolSchema(speechEnabled = false) {
+    return z.toJSONSchema(toolInput(speechEnabled), { io: "input" });
+}
+export const PARTICIPANT_TOOL_SCHEMA = participantToolSchema();
+export const PARTICIPANT_FINAL_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["outcome", "summary", "frictionReports"],
+    properties: {
+        outcome: { type: "string", enum: ["reached", "not_reached", "blocked"] },
+        summary: { type: "string", minLength: 1, maxLength: 4000 },
+        frictionReports: {
+            type: "array",
+            maxItems: 8,
+            items: { type: "string", minLength: 1, maxLength: 2000 },
+        },
+    },
+};
+/** humanish tool arguments, validated before the shared executor sees a batch. */
+export function parseParticipantTool(value, speechEnabled = false) {
+    if (Buffer.byteLength(JSON.stringify(value) ?? "") > PARTICIPANT_LIMITS.output)
+        throw new Error("invalid_response");
+    const v = toolInput(speechEnabled).parse(value);
+    if (Buffer.byteLength(v.narration) > PARTICIPANT_LIMITS.narration)
+        throw new Error("invalid_response");
+    return {
+        actions: v.actions.map(validateBrowserControlAction),
+        pendingSafetyChecks: [],
+        done: false,
+        ...(v.narration ? { message: v.narration } : {}),
+        providerRequestPending: true,
+    };
+}
+export function parseParticipantFinal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid_response");
+    const { outcome, ...report } = value;
+    if ((outcome !== "reached" && outcome !== "not_reached" && outcome !== "blocked") ||
+        !validClosingReport(report))
+        throw new Error("invalid_response");
+    return {
+        actions: [],
+        pendingSafetyChecks: [],
+        done: true,
+        outcome,
+        message: [report.summary, ...report.frictionReports].join("\n"),
+        closingReport: { summary: report.summary, frictionReports: [...report.frictionReports] },
+    };
+}

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

@@ -0,0 +1,20 @@
+import type { CuaProvider } from "../computer-use/loop.js";
+import { type RestrictedCodexSessionOptions } from "./restricted-session.js";
+import type { ReasoningEffort } from "../reasoning-effort.js";
+export type ParticipantProviderCloseResult = {
+    status: "confirmed" | "unconfirmed";
+};
+export interface RestrictedParticipantOptions {
+    session?: RestrictedCodexSessionOptions;
+    requestTimeoutMs?: number;
+    authMode?: "operator";
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+    /** Admit speech actions and heard-speaker evidence for a speech-capable desktop only. */
+    speechEnabled?: boolean;
+}
+/** One native tool-calling conversation; the existing CUA loop owns every input. */
+export declare function createRestrictedCodexParticipant(options?: RestrictedParticipantOptions): {
+    provider: CuaProvider;
+    close(): Promise<ParticipantProviderCloseResult>;
+};