humanish 0.105.0 → 0.106.1

package/dist/actors/local-agent/cli.js

@@ -0,0 +1,413 @@
+// The local-agent participant's shared pieces: which signed-in coding agents this machine has
+// (Codex, Claude Code), the doctor line and hosted-Codex version check built on that, the action
+// mapping and JSON reading the two Claude Code paths share, and the one-shot Claude Code provider.
+//
+// A developer trying humanish often already has a coding agent signed in (Codex on a ChatGPT plan,
+// Claude Code on a Max plan), so `actors[0].type: local-agent` lets that agent decide the next
+// action instead of a provider API key. Codex runs as a restricted app-server participant
+// (actors/codex/restricted-participant.ts) and Claude Code as one session for the whole run
+// (claude-session.ts). The one-shot provider below spawns `claude -p` per turn, with no memory of
+// the last turn; it stays reachable through HUMANISH_LOCAL_AGENT_ONE_SHOT as a measurement switch.
+// The design started from a measurement: with every OPENAI_* variable unset, `codex exec --image`
+// returned a correct click on a real desktop screenshot and `claude -p` agreed within three pixels.
+//
+// WHAT THIS IS NOT: a way to avoid paying. Subscription usage consumes the operator's own plan,
+// which is why the cost line for these runs says "not priced" rather than $0 — $0 would be a lie.
+// It is also not marketed as free API access, and it fails closed on a rate limit rather than
+// hammering a plan that was sold for interactive coding.
+//
+// WHERE IT IS SAFE, and this inverts the intuitive reading: the local agent only DECIDES. humanish
+// executes the action inside the desktop sandbox, so nothing the persona chooses ever runs on the
+// operator's machine. The same trick on the TERMINAL lane would be the opposite — it would move
+// code execution out of the sandbox and onto a real disk — which is why this is a computer-use
+// provider and nothing else. Even so, these are coding agents with their own shell and file tools,
+// so each one is spawned tool-restricted, in a scratch directory, with a per-turn timeout.
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { admittedCodexCliVersions, parseCodexCliVersion } from "../codex/qualified-versions.js";
+import { restrictedCodexNpmTarget } from "../codex/restricted-executable.js";
+const LOCAL_AGENTS = [
+    { id: "codex", bin: "codex", label: "Codex", credentialPath: ".codex/auth.json" },
+    {
+        id: "claude",
+        bin: "claude",
+        label: "Claude Code",
+        credentialPath: ".claude/.credentials.json",
+    },
+];
+/**
+ * Map the agent's answer onto the harness action vocabulary. Anything unrecognized is DROPPED
+ * rather than guessed at: a coordinate we invented would be recorded as the participant's choice.
+ */
+export function toCuaActions(raw) {
+    const actions = [];
+    for (const item of raw) {
+        const x = typeof item.x === "number" ? Math.round(item.x) : undefined;
+        const y = typeof item.y === "number" ? Math.round(item.y) : undefined;
+        switch (item.kind) {
+            case "click":
+                if (x !== undefined && y !== undefined)
+                    actions.push({ kind: "click", x, y });
+                break;
+            case "double_click":
+                if (x !== undefined && y !== undefined)
+                    actions.push({ kind: "double_click", x, y });
+                break;
+            case "type":
+                if (typeof item.text === "string" && item.text.length > 0)
+                    actions.push({ kind: "type", text: item.text });
+                break;
+            case "keypress":
+                if (Array.isArray(item.keys) && item.keys.length > 0)
+                    actions.push({ kind: "keypress", keys: [...item.keys] });
+                break;
+            case "scroll":
+                if (x !== undefined && y !== undefined) {
+                    actions.push({
+                        kind: "scroll",
+                        x,
+                        y,
+                        dx: 0,
+                        dy: typeof item.ms === "number" ? item.ms : 300,
+                    });
+                }
+                break;
+            case "wait":
+                actions.push({ kind: "wait", ...(typeof item.ms === "number" ? { ms: item.ms } : {}) });
+                break;
+            default:
+                break; // "done" carries no action; unknown kinds are dropped on purpose
+        }
+    }
+    return actions;
+}
+/** The declared outcome, only if it is one of the three words; anything else is absence. */
+export function declaredOutcomeOf(value) {
+    return value === "reached" || value === "not_reached" || value === "blocked" ? value : undefined;
+}
+/**
+ * Pull the JSON object out of whatever the CLI printed: clean JSON, a Claude Code envelope, or an
+ * answer wrapped in a ```json fence. A response with no object at all is a turn error, never an
+ * empty turn — an empty turn would read to the loop as "the participant chose to do nothing".
+ */
+export function parseAgentJson(text) {
+    // ORDER MATTERS, and a test caught it: Claude Code's envelope is valid JSON whose `result`
+    // STRING contains a ```json fence. Stripping fences first reached inside that string and
+    // mangled the envelope. So: parse what we were given, and only go fence-hunting if it is not
+    // already JSON.
+    const attempts = [text.trim()];
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+    if (fenced?.[1] !== undefined)
+        attempts.push(fenced[1].trim());
+    const bare = text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1);
+    if (text.indexOf("{") >= 0 && bare.length > 1)
+        attempts.push(bare);
+    for (const attempt of attempts) {
+        if (attempt.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(attempt);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // try the next shape
+        }
+    }
+    throw new Error("the local agent did not return a JSON object");
+}
+const defaultSpawn = async (bin, args, options) => await new Promise((resolve) => {
+    const child = spawn(bin, [...args], { cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), options.timeoutMs);
+    // Stopping a run must stop the thinking too: a local agent mid-turn can hold a terminal for
+    // minutes, and a Stop that leaves it running is not a stop.
+    const onAbort = () => {
+        child.kill("SIGKILL");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    };
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    child.on("error", (error) => {
+        cleanup();
+        resolve({ code: null, stdout, stderr: `${stderr}${String(error)}` });
+    });
+    child.on("close", (code) => {
+        cleanup();
+        resolve({ code, stdout, stderr });
+    });
+});
+export const LOCAL_AGENT_CAPABILITIES = {
+    headless: true,
+    structuredTrace: true,
+    lanes: ["computer-use"],
+    producesScreenshots: true,
+    // The operator brings the model by being signed into it already; humanish never sees a key.
+    byoModel: true,
+    preGrantableApprovals: false,
+    inProcessTools: false,
+    license: "open",
+};
+/** The turn prompt for Claude Code: the instructions, the screenshot to read, and the reply shape. */
+export function promptFor(request, screenshotPath) {
+    const hint = request.contextHint === undefined ? "" : `\n\nNote from the harness: ${request.contextHint}`;
+    // Claude Code has no --output-schema, so the reply shape is stated in the prompt.
+    const shape = '{"reasoning":string,"done":boolean,"message":string|null,"outcome":"reached"|"not_reached"|"blocked"|null,' +
+        '"actions":[{"kind":"click|double_click|type|keypress|scroll|wait|done",' +
+        '"x":int|null,"y":int|null,"text":string|null,"keys":[string]|null,"ms":int|null}]}';
+    return [
+        request.instructions,
+        "",
+        `Read the image file ${screenshotPath}. That image is the CURRENT SCREEN. You are the participant: decide what to do next, ` +
+            "as this person would. Coordinates are pixels from the top-left of the screenshot.",
+        "Return between one and three actions. Set done=true ONLY when the task is finished or you are " +
+            "giving up, and put your closing words in message. When done=true, set outcome: reached if " +
+            "the task is finished, blocked if something in the app stopped you, not_reached if you are " +
+            "stopping for another reason. Otherwise outcome is null.",
+        `Reply with ONLY a JSON object of this shape: ${shape}`,
+        hint,
+    ].join("\n");
+}
+/**
+ * A CuaProvider that spawns a signed-in Claude Code (`claude -p`) once per turn, with no memory of
+ * the last turn. The run's default is one session (claude-session.ts); this path is reached only
+ * through HUMANISH_LOCAL_AGENT_ONE_SHOT, to measure "remembers" against "does not".
+ *
+ * The loop, the executor, the trace, the affordance record and the Observer are unchanged: the
+ * only thing that differs is where the next action comes from.
+ */
+export function createLocalAgentProvider(options) {
+    const spawnFn = options.spawnFn ?? defaultSpawn;
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    const effort = options.reasoningEffort ?? "low";
+    const descriptor = LOCAL_AGENTS.find((candidate) => candidate.id === options.agent);
+    if (descriptor === undefined) {
+        throw new Error(`unknown local agent "${options.agent}"`);
+    }
+    return {
+        id: `local-agent-${descriptor.id}`,
+        version: options.model ?? `${descriptor.bin} (local, operator-authenticated)`,
+        modelSettings: { reasoningEffort: effort },
+        capabilities: LOCAL_AGENT_CAPABILITIES,
+        // It reasons over pixels, so the loop must hand it a frame or fail closed.
+        requiresFrame: true,
+        async nextTurn(request, signal) {
+            const frame = request.observation.screenshot;
+            if (frame === undefined) {
+                throw new Error("the local-agent provider needs a screenshot and this observation has none");
+            }
+            const work = await mkdtemp(path.join(options.workRoot ?? tmpdir(), "humanish-local-agent-"));
+            try {
+                const screenshotPath = path.join(work, "screen.png");
+                await writeFile(screenshotPath, frame);
+                const prompt = promptFor(request, screenshotPath);
+                const args = [
+                    "-p",
+                    "--output-format",
+                    "json",
+                    // Read is the only tool it needs — the screenshot — and the only one it gets.
+                    "--allowedTools",
+                    "Read",
+                    ...(options.model === undefined ? [] : ["--model", options.model]),
+                    // `--allowedTools` takes a list, so a prompt placed right after it is read as a tool
+                    // name and Claude Code exits 1 with "Input must be provided". Three of three one-shot
+                    // runs failed on turn one that way on 2026-09-01 (Claude Code 2.1.257); `--` ends the
+                    // options so the prompt is the prompt.
+                    "--",
+                    prompt,
+                ];
+                const result = await spawnFn(descriptor.bin, args, {
+                    cwd: work,
+                    timeoutMs,
+                    ...(signal === undefined ? {} : { signal }),
+                });
+                if (result.code !== 0) {
+                    // Fail loud with the CLI's own words. A rate-limited plan says so here, and that is a
+                    // sentence the operator can act on, unlike "turn failed".
+                    const detail = (result.stderr || result.stdout).trim().slice(-400);
+                    throw new Error(`${descriptor.label} exited ${result.code ?? "on a signal"}: ${detail}`);
+                }
+                // Claude Code returns an envelope on stdout whose `result` field holds the text.
+                const envelope = parseAgentJson(result.stdout);
+                const payload = typeof envelope.result === "string" ? envelope.result : result.stdout;
+                const turn = parseAgentJson(payload);
+                const actions = toCuaActions(Array.isArray(turn.actions) ? turn.actions : []);
+                const done = turn.done === true || (actions.length === 0 && typeof turn.message === "string");
+                const outcome = declaredOutcomeOf(turn.outcome);
+                return {
+                    actions,
+                    pendingSafetyChecks: [],
+                    done,
+                    ...(outcome === undefined ? {} : { outcome }),
+                    ...(typeof turn.reasoning === "string" && turn.reasoning.length > 0
+                        ? { reasoning: turn.reasoning }
+                        : {}),
+                    ...(typeof turn.message === "string" && turn.message.length > 0
+                        ? { message: turn.message }
+                        : {}),
+                    // No `usage`: a subscription CLI does not report tokens we can price, and inventing a
+                    // number here is what would make the run's cost line a lie.
+                };
+            }
+            finally {
+                await rm(work, { recursive: true, force: true }).catch(() => undefined);
+            }
+        },
+    };
+}
+/** No shell, prompts or model request. Bound time and output even for a broken CLI. */
+async function authProbe(bin, args, env) {
+    return await new Promise((resolve) => {
+        const child = spawn(bin, [...args], { cwd: tmpdir(), env, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "", stderr = "", bytes = 0, settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const stop = () => {
+            child.kill("SIGKILL");
+            child.stdout.destroy();
+            child.stderr.destroy();
+            finish({ code: null, stdout: "", stderr: "" });
+        };
+        const timer = setTimeout(stop, 5_000);
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 64 * 1024)
+                stop();
+            else
+                stdout += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 64 * 1024)
+                stop();
+            else
+                stderr += chunk.toString("utf8");
+        });
+        child.on("error", () => finish({ code: null, stdout: "", stderr: "" }));
+        child.on("close", (code) => finish({ code, stdout, stderr }));
+    });
+}
+function classifyAuth(agent, result) {
+    if (agent === "codex") {
+        const text = `${result.stdout}\n${result.stderr}`;
+        if (result.code === 0 && /^Logged in using ChatGPT\b/m.test(text))
+            return { authStatus: "authenticated", billing: "account-unknown" };
+        if (result.code === 0 && /^Logged in using an API key\b/m.test(text))
+            return { authStatus: "authenticated", billing: "api" };
+        if (result.code === 0 && /^Logged in\b/m.test(text))
+            return { authStatus: "authenticated" };
+        if (result.code === 1 && /^Not logged in\s*$/m.test(text))
+            return { authStatus: "unauthenticated" };
+    }
+    else {
+        try {
+            const value = JSON.parse(result.stdout);
+            if (value && typeof value === "object" && "loggedIn" in value) {
+                if (value.loggedIn === true && result.code === 0)
+                    return { authStatus: "authenticated" };
+                if (value.loggedIn === false && result.code === 1)
+                    return { authStatus: "unauthenticated" };
+            }
+        }
+        catch {
+            /* Old CLI, invalid config or unsupported status command: unknown. */
+        }
+    }
+    return { authStatus: "unknown" };
+}
+/** Host-only compatibility check. It never initializes app-server or submits a model request. */
+export async function checkHostedCodexCompatibility(binPath, options = {}) {
+    const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
+    if (restrictedCodexNpmTarget(platform, arch) === undefined)
+        return "unsupported_platform";
+    const result = await (options.probe ?? authProbe)(binPath, ["--version"], options.env ?? process.env).catch(() => ({ code: null, stdout: "", stderr: "" }));
+    const version = parseCodexCliVersion(result.stdout);
+    return result.code === 0 &&
+        version !== undefined &&
+        admittedCodexCliVersions(platform, arch).some((admitted) => admitted === version)
+        ? "supported"
+        : "unsupported_version";
+}
+/**
+ * Which coding agents are installed and signed in on this machine.
+ *
+ * This is the whole point of the feature at the surface: someone new does not have to go and make
+ * an API key if the thing that can drive the study is already on their laptop. `doctor` says so,
+ * and says it as a capability rather than a gate — a machine with no local agent is not broken,
+ * it just needs a key.
+ */
+export async function detectLocalAgents(options = {}) {
+    const env = options.env ?? process.env;
+    const home = options.home ?? env.HOME ?? "";
+    const which = options.which ??
+        (async (bin) => {
+            const { access, constants } = await import("node:fs/promises");
+            for (const directory of (env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+                const candidate = path.resolve(directory, bin);
+                if (await access(candidate, constants.X_OK)
+                    .then(() => true)
+                    .catch(() => false))
+                    return candidate;
+            }
+            return undefined;
+        });
+    const exists = options.exists ??
+        (async (file) => {
+            const { access } = await import("node:fs/promises");
+            return await access(file)
+                .then(() => true)
+                .catch(() => false);
+        });
+    const found = [];
+    for (const descriptor of LOCAL_AGENTS) {
+        const binPath = await which(descriptor.bin);
+        if (binPath === undefined)
+            continue;
+        const file = descriptor.id === "codex" && env.CODEX_HOME
+            ? path.join(env.CODEX_HOME, "auth.json")
+            : descriptor.id === "claude" && env.CLAUDE_CONFIG_DIR
+                ? path.join(env.CLAUDE_CONFIG_DIR, ".credentials.json")
+                : path.join(home, descriptor.credentialPath);
+        const status = await (options.authProbe ?? authProbe)(binPath, descriptor.id === "codex" ? ["login", "status"] : ["auth", "status"], env)
+            .then((result) => classifyAuth(descriptor.id, result))
+            .catch(() => ({ authStatus: "unknown" }));
+        found.push({
+            ...descriptor,
+            binPath,
+            credentialsPresent: await exists(file).catch(() => false),
+            ...status,
+        });
+    }
+    return found;
+}
+/** One line for `doctor`, in the register the other rows use. */
+export function localAgentDoctorMessage(found) {
+    if (found.length === 0) {
+        return "no local coding agent found — openai-computer-use needs OPENAI_API_KEY; local-agent needs Codex or Claude Code installed and authenticated. Hosted desktops also need E2B_API_KEY.";
+    }
+    return (found
+        .map((agent) => agent.authStatus === "authenticated"
+        ? `${agent.label} reports authenticated — actors[0].type: local-agent can use it instead of a provider API key; account access and limits are untested`
+        : agent.authStatus === "unauthenticated"
+            ? `${agent.label} reports not signed in — run \`${agent.id === "codex" ? "codex login" : "claude auth login"}\``
+            : `${agent.label} installed; authentication status could not be checked — run \`${agent.id === "codex" ? "codex login status" : "claude auth status"}\` and update the CLI if needed`)
+        .join(". ") +
+        ". Desktop and analysis requirements depend on the selected lab; run doctor --lab <lab> for its setup checks.");
+}

package/dist/actors/local-agent/readiness.d.ts

@@ -0,0 +1,31 @@
+import { type LocalAgentId } from "./cli.js";
+/** Why a local-agent participant cannot run here. */
+export type LocalAgentRefusal = 
+/** The CLI is not on PATH. */
+{
+    kind: "agent-missing";
+    message: string;
+}
+/** The CLI is signed out, or could not report its sign-in status. */
+ | {
+    kind: "signin-required";
+    message: string;
+}
+/** Hosted Codex on an unsupported platform or an unqualified CLI release. */
+ | {
+    kind: "unsupported";
+    message: string;
+}
+/** A ChatGPT-account Codex with execution.caps, which it cannot price. */
+ | {
+    kind: "unpriced-cap";
+    message: string;
+};
+export declare function localAgentRefusal(args: {
+    agent: LocalAgentId;
+    env: Record<string, string | undefined>;
+    caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+}): Promise<LocalAgentRefusal | undefined>;

package/dist/actors/local-agent/readiness.js

@@ -0,0 +1,45 @@
+// Whether a local-agent participant can run on this machine before anything is acquired: its CLI
+// is on PATH and signed in, a hosted Codex CLI is a qualified release on a supported platform, and
+// a ChatGPT-account Codex is not asked to enforce a dollar cap it has no price for. Each route maps
+// the refusal's kind to its own error code.
+import { describeQualifiedCodexCliVersions } from "../codex/qualified-versions.js";
+import { checkHostedCodexCompatibility, detectLocalAgents } from "./cli.js";
+export async function localAgentRefusal(args) {
+    const { agent, env, caps } = args;
+    const available = await detectLocalAgents({ env });
+    const chosen = available.find((candidate) => candidate.id === agent);
+    if (chosen === undefined) {
+        return {
+            kind: "agent-missing",
+            message: `actors[0].type: local-agent needs the ${agent} CLI on PATH and signed in. ` +
+                `Install it, or set OPENAI_API_KEY and use actors[0].type: openai-computer-use instead.`,
+        };
+    }
+    if (chosen.authStatus !== "authenticated") {
+        return {
+            kind: "signin-required",
+            message: chosen.authStatus === "unauthenticated"
+                ? `${chosen.label} reports not signed in — run \`${chosen.id === "codex" ? "codex login" : "claude auth login"}\`, then retry.`
+                : `${chosen.label} authentication status could not be checked. Run \`${chosen.id === "codex" ? "codex login status" : "claude auth status"}\` and update the CLI if needed. No desktop was launched.`,
+        };
+    }
+    if (chosen.id !== "codex")
+        return undefined;
+    const compatibility = await checkHostedCodexCompatibility(chosen.binPath, { env });
+    if (compatibility !== "supported") {
+        return {
+            kind: "unsupported",
+            message: compatibility === "unsupported_platform"
+                ? `Hosted Codex participants require Linux or macOS on x64 or arm64. This host is ${process.platform}/${process.arch}; no desktop was launched.`
+                : `Hosted Codex participants require a qualified Codex CLI (${describeQualifiedCodexCliVersions()}). Run \`codex --version\` and install a qualified version before retrying; no desktop was launched.`,
+        };
+    }
+    if (chosen.billing === "account-unknown" &&
+        (caps.maxUsd !== undefined || caps.maxTotalUsd !== undefined)) {
+        return {
+            kind: "unpriced-cap",
+            message: "A ChatGPT-account Codex participant has no API-dollar price, so execution.caps.maxUsd/maxTotalUsd cannot be enforced. Remove the dollar cap and use finite execution timeout/step limits, or use an API-backed participant; no desktop was launched.",
+        };
+    }
+    return undefined;
+}

package/dist/actors/openai-endpoint.d.ts

@@ -0,0 +1,2 @@
+/** The OpenAI Responses API endpoint. Callers may take a test override; nothing reads it from env. */
+export declare const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";

package/dist/actors/openai-endpoint.js

@@ -0,0 +1,2 @@
+/** The OpenAI Responses API endpoint. Callers may take a test override; nothing reads it from env. */
+export const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";

package/dist/actors/output-token-limit.js

@@ -0,0 +1,4 @@
+/** Output includes reasoning tokens. This is a request limit, not a dollar budget. */
+export function isMaxOutputTokens(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}

package/dist/actors/reasoning-effort.js

@@ -0,0 +1,33 @@
+// The provider-declared reasoning-effort vocabulary, kept in its own module so the lab schema and
+// the OpenAI provider can share it without the schema depending on a provider.
+//
+// WHY THIS EXISTS AT ALL: effort was reachable in the provider and unreachable from a lab. Every
+// computer-use run humanish had ever done was therefore the provider default — not by decision but
+// by omission (#497). Effort changes who the PARTICIPANT is, the same way a persona prompt does
+// (docs/principles/actor-fidelity.md: capability settings are recruiting decisions), so pinning it
+// invisibly meant every persona finding was really a finding about that persona at medium, with the
+// second half unsaid.
+//
+// SUPPORT IS MODEL-DEPENDENT. OpenAI documents the vocabulary below as the union across models and
+// states plainly that "supported values are model-dependent"; there is no offline way to know which
+// subset a given model id accepts. So this module refuses to pretend: it validates that a lab asked
+// for a REAL effort level, and a model that does not support the one it was asked for fails on the
+// first turn with the provider's own message rather than being silently downgraded. Silent
+// downgrade is the worse failure — it would record an effort the run did not actually use.
+/** The documented vocabulary, ordered from least to most reasoning. */
+export const REASONING_EFFORTS = [
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+export function isReasoningEffort(value) {
+    return typeof value === "string" && REASONING_EFFORTS.includes(value);
+}
+/** For error messages: the vocabulary as an inline list. */
+export function reasoningEffortNames() {
+    return REASONING_EFFORTS.join(", ");
+}

package/dist/actors/registry.d.ts

@@ -0,0 +1,59 @@
+import { type CodexAppServerRunOptions, type CodexAppServerRunResult } from "./codex/app-server.js";
+import { type ActorCapabilities, type ActorPersonaRef, type ActorTrace } from "./contract.js";
+import { type CuaActorSessionOptions } from "./computer-use/actor.js";
+import type { CuaLoopResult } from "./computer-use/loop.js";
+import { type ScriptedBrowserSessionOptions, type ScriptedBrowserSessionResult } from "./scripted-browser/actor.js";
+export type ActorId = "codex-app-server" | "openai-computer-use" | "local-agent" | "scripted-browser" | "codex-exec";
+interface ActorDescriptorBase {
+    id: ActorId;
+    label: string;
+    capabilities: ActorCapabilities;
+}
+export interface CodexActorDescriptor extends ActorDescriptorBase {
+    id: "codex-app-server";
+    runSession(options: CodexAppServerRunOptions): Promise<CodexAppServerRunResult>;
+    toActorTrace(result: CodexAppServerRunResult, persona: ActorPersonaRef): ActorTrace;
+}
+export interface CuaActorDescriptor extends ActorDescriptorBase {
+    id: "openai-computer-use" | "local-agent";
+    runSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;
+}
+export interface ScriptedBrowserActorDescriptor extends ActorDescriptorBase {
+    id: "scripted-browser";
+    runSession(options: ScriptedBrowserSessionOptions): Promise<ScriptedBrowserSessionResult>;
+}
+export interface TerminalActorDescriptor extends ActorDescriptorBase {
+    id: "codex-exec";
+}
+export type ActorDescriptor = CodexActorDescriptor | CuaActorDescriptor | ScriptedBrowserActorDescriptor | TerminalActorDescriptor;
+/**
+ * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
+ * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
+ * Any future computer-use provider (e.g. stagehand-cua) must keep that session signature and add
+ * its id to CuaActorDescriptor["id"], so code narrowed by this guard can still tell the ids apart.
+ * This guard is what lets the lab dispatch on capabilities rather than on hardcoded actor ids.
+ */
+export declare function isCuaActorDescriptor(descriptor: ActorDescriptor): descriptor is CuaActorDescriptor;
+/**
+ * REGISTRY CONTRACT (mirror of isCuaActorDescriptor): an actor whose capabilities include the
+ * "scripted-browser" lane IS a ScriptedBrowserActorDescriptor — runSession takes
+ * ScriptedBrowserSessionOptions and returns ScriptedBrowserSessionResult (trace fully formed,
+ * like the CUA shape — no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
+ */
+export declare function isScriptedBrowserActorDescriptor(descriptor: ActorDescriptor): descriptor is ScriptedBrowserActorDescriptor;
+/**
+ * REGISTRY CONTRACT (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
+ * whose capabilities include the "terminal" lane IS a TerminalActorDescriptor. This is the guard
+ * the terminal-product lab uses for route selection and capability enforcement. The current
+ * descriptor's direct runSession is intentionally unsupported; live execution is route-owned.
+ * Any future terminal actor must declare keyPlacement honestly and integrate with that lifecycle.
+ */
+export declare function isTerminalActorDescriptor(descriptor: ActorDescriptor): descriptor is TerminalActorDescriptor;
+export declare const actorRegistry: Record<ActorId, ActorDescriptor>;
+export declare function getActor(id: "codex-app-server"): CodexActorDescriptor;
+export declare function getActor(id: CuaActorDescriptor["id"]): CuaActorDescriptor;
+export declare function getActor(id: "scripted-browser"): ScriptedBrowserActorDescriptor;
+export declare function getActor(id: "codex-exec"): TerminalActorDescriptor;
+export declare function getActor(id: ActorId): ActorDescriptor;
+export {};