humanish 0.56.0 → 0.58.0

package/dist/local-agent-cli.js

@@ -0,0 +1,337 @@
+// A computer-use brain that is already installed on the operator's machine.
+//
+// WHY: the fastest thing humanish can do for someone new is show them a persona driving a real
+// desktop. Today that needs a provider API key before anything happens, and "go make an API key"
+// is where most people stop. But a developer trying humanish very often ALREADY has a coding agent
+// signed in — Codex on a ChatGPT plan, Claude Code on a Max plan — and those CLIs will look at a
+// screenshot and answer with the next action. Measured, not assumed: with every OPENAI_* variable
+// explicitly unset, `codex exec --image` returned a correct click on the Applications menu of a
+// real desktop screenshot, and `claude -p` independently 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 E2B 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";
+export const LOCAL_AGENTS = [
+    { id: "codex", bin: "codex", label: "Codex", credentialPath: ".codex/auth.json" },
+    { id: "claude", bin: "claude", label: "Claude Code", credentialPath: ".claude/.credentials.json" }
+];
+/** The action vocabulary the local agent is asked to answer in — a strict subset of CuaAction. */
+const ACTION_KINDS = ["click", "double_click", "type", "keypress", "scroll", "wait", "done"];
+/**
+ * OpenAI structured outputs run in STRICT mode: every property must appear in `required`, so
+ * "optional" is expressed as a nullable type. Getting this wrong is a 400 before any thinking
+ * happens, which is how this shape was arrived at.
+ */
+export function localAgentTurnSchema() {
+    return {
+        type: "object",
+        additionalProperties: false,
+        required: ["reasoning", "done", "message", "actions"],
+        properties: {
+            reasoning: { type: "string" },
+            done: { type: "boolean" },
+            message: { type: ["string", "null"] },
+            actions: {
+                type: "array",
+                items: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["kind", "x", "y", "text", "keys", "ms"],
+                    properties: {
+                        kind: { type: "string", enum: [...ACTION_KINDS] },
+                        x: { type: ["integer", "null"] },
+                        y: { type: ["integer", "null"] },
+                        text: { type: ["string", "null"] },
+                        keys: { type: ["array", "null"], items: { type: "string" } },
+                        ms: { type: ["integer", "null"] }
+                    }
+                }
+            }
+        }
+    };
+}
+/**
+ * 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;
+}
+/**
+ * Pull the JSON object out of whatever the CLI printed. Codex writes clean JSON to
+ * `--output-last-message`; Claude Code wraps it in a ```json fence. Both are handled here rather
+ * than in two places, and 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"
+};
+function promptFor(request, screenshotPath, agent) {
+    const hint = request.contextHint === undefined ? "" : `\n\nNote from the harness: ${request.contextHint}`;
+    // Claude Code has no --output-schema, so the shape is stated in the prompt for both; codex gets
+    // it enforced as well. Saying it twice costs nothing and keeps one prompt for both adapters.
+    const shape = '{"reasoning":string,"done":boolean,"message":string|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}]}';
+    const readFile = agent === "claude" ? `Read the image file ${screenshotPath}. ` : "";
+    return [
+        request.instructions,
+        "",
+        `${readFile}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.",
+        `Reply with ONLY a JSON object of this shape: ${shape}`,
+        hint
+    ].join("\n");
+}
+/**
+ * A CuaProvider backed by a coding agent that is already signed in on this machine.
+ *
+ * Deliberately NOT a new lane: the loop, the executor, the trace, the affordance record and the
+ * Observer are all unchanged, because the only thing that differs is where the next action comes
+ * from. That is also why it is honest to compare a local-agent run against an API run.
+ */
+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, descriptor.id);
+                let args;
+                if (descriptor.id === "codex") {
+                    const schemaPath = path.join(work, "turn-schema.json");
+                    await writeFile(schemaPath, JSON.stringify(localAgentTurnSchema()), "utf8");
+                    args = [
+                        "exec",
+                        "--image", screenshotPath,
+                        "--output-schema", schemaPath,
+                        "--output-last-message", path.join(work, "turn.json"),
+                        "--skip-git-repo-check",
+                        // The agent's OWN shell tools stay read-only: it is here to look at a picture, and a
+                        // coding agent that decides to go exploring is exploring the operator's disk.
+                        "--sandbox", "read-only",
+                        "-c", `model_reasoning_effort=${effort}`,
+                        ...(options.model === undefined ? [] : ["--model", options.model]),
+                        prompt
+                    ];
+                }
+                else {
+                    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]),
+                        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}`);
+                }
+                // Codex writes the structured answer to a file; Claude Code returns an envelope on stdout
+                // whose `result` field holds the text.
+                let payload = result.stdout;
+                if (descriptor.id === "codex") {
+                    const { readFile: read } = await import("node:fs/promises");
+                    payload = await read(path.join(work, "turn.json"), "utf8");
+                }
+                else {
+                    const envelope = parseAgentJson(result.stdout);
+                    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");
+                return {
+                    actions,
+                    pendingSafetyChecks: [],
+                    done,
+                    ...(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);
+            }
+        }
+    };
+}
+/**
+ * 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 home = options.home ?? process.env.HOME ?? "";
+    const which = options.which ?? (async (bin) => {
+        const found = await defaultSpawn("sh", ["-lc", `command -v ${bin} 2>/dev/null || true`], {
+            cwd: home || ".",
+            timeoutMs: 10_000
+        });
+        const resolved = found.stdout.trim().split("\n")[0]?.trim();
+        return resolved !== undefined && resolved.length > 0 ? resolved : 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;
+        found.push({
+            ...descriptor,
+            binPath,
+            credentialsPresent: home.length > 0 && (await exists(path.join(home, descriptor.credentialPath)))
+        });
+    }
+    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 — a live run needs a provider API key (`humanish keys set openai`)";
+    }
+    const ready = found.filter((agent) => agent.credentialsPresent);
+    if (ready.length === 0) {
+        const names = found.map((agent) => agent.label).join(", ");
+        return `${names} installed but not signed in — sign in, or use a provider API key`;
+    }
+    const names = ready.map((agent) => agent.label).join(", ");
+    return `${names} signed in — a live run can use ${ready.length === 1 ? "it" : "one"} instead of a provider API key (actors[0].type: local-agent)`;
+}
+//# sourceMappingURL=local-agent-cli.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-agent-cli.js","sourceRoot":"","sources":["../src/local-agent-cli.ts"],"names":[],"mappings":"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"}

package/dist/program.d.ts

@@ -37,6 +37,8 @@ export interface TuiRuntime {
     stdin: NodeJS.ReadStream;
     stdout: NodeJS.WriteStream;
     nodeVersion: string;
+    /** Injected so a test can pose as an agent session without touching the real process env. */
+    env: NodeJS.ProcessEnv;
     /** Resolves the bundle, or null when it is not present. */
     loadTui(bundle: URL): Promise<TuiModule | null>;
 }

package/dist/program.js

@@ -31,6 +31,8 @@ import { openObserverArtifact, stopRun } from "./tui-actions.js";
 import { readRunDetail } from "./run-detail.js";
 import { launchRun, readLaunchLogTail } from "./tui-launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, tuiBundleUrl } from "./tui-contract.js";
+import { forTerminal } from "./terminal-encoding.js";
+import { detectAgentSession } from "./agent-session.js";
 import { runCommsCatchHost } from "./comms-catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "./comms-sandbox-catch.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
@@ -43,9 +45,14 @@ const CLI_VERSION = readCliVersion();
 // Shared so the ~20 leaf commands that declare their own --json flag cannot drift
 // from each other in wording.
 const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
+// Transcode ONLY for a terminal. A pipe carries bytes to another program — mangling those would
+// corrupt a JSON payload for a reader that handles UTF-8 perfectly well — while a TTY carries them
+// to a font, through a locale that may not decode them. See src/terminal-encoding.ts for what a
+// participant actually read back off the screen.
+const forStream = (stream, text) => stream.isTTY === true ? forTerminal(text) : text;
 const defaultIo = {
-    writeOut: (text) => process.stdout.write(text),
-    writeErr: (text) => process.stderr.write(text),
+    writeOut: (text) => process.stdout.write(forStream(process.stdout, text)),
+    writeErr: (text) => process.stderr.write(forStream(process.stderr, text)),
     setExitCode: (code) => {
         process.exitCode = code;
     }
@@ -291,6 +298,7 @@ function registerDoctorCommand(parent, io) {
 const defaultTuiRuntime = {
     stdin: process.stdin,
     stdout: process.stdout,
+    env: process.env,
     nodeVersion: process.version,
     loadTui: async (bundle) => {
         if (!existsSync(bundle))
@@ -325,9 +333,31 @@ function registerTuiCommand(parent, io) {
         .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
         .summary("Open the interactive terminal surface.")
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const { stdin, stdout } = tuiRuntime;
+        // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands
+        // it runs, so the TTY check below passes and the surface used to open: a study watched an
+        // agent navigate the labs list and start a run it did not mean to start
+        // (labs/handed-a-human-surface.yaml). A TTY says a terminal exists, not that anyone is
+        // reading it. `--force` is the escape for the person who really is at this keyboard —
+        // capturing frames from inside an agent session is exactly that case.
+        const agent = options.force === true ? undefined : detectAgentSession(tuiRuntime.env);
+        if (agent !== undefined) {
+            refuseTui(command, io, {
+                schema: TUI_RESULT_SCHEMA,
+                ok: false,
+                error: {
+                    code: "HUMANISH_TUI_AGENT_SESSION",
+                    message: `humanish tui is a surface for a person, and ${agent.marker} says this session belongs to ${agent.runner}. `
+                        + "It renders frames of escape codes into a transcript, and its keys can start runs. "
+                        + "`humanish runs --json` lists runs, `humanish lab list --json` lists the studies in this project, "
+                        + "and `humanish lab run <lab> --json` starts one. If you are a person at this keyboard, add --force."
+                }
+            });
+            return;
+        }
         if (stdin.isTTY !== true || stdout.isTTY !== true) {
             refuseTui(command, io, {
                 schema: TUI_RESULT_SCHEMA,
@@ -2853,7 +2883,10 @@ function formatDoctorHuman(result) {
     return [
         `humanish doctor ${result.ok ? "ok" : "needs setup"}`,
         `cwd: ${result.cwd}`,
-        ...result.checks.map((check) => `- ${check.ok ? "ok" : "missing"} ${check.name}: ${check.message}`)
+        // "missing" is a VERDICT, and a row that never ran has none. A participant reading doctor on a
+        // fresh desktop got `- missing package.json: package.json is present and safe to read`, which
+        // contradicts itself in eleven words (labs/tui-self-study.yaml).
+        ...result.checks.map((check) => `- ${check.ok ? "ok" : check.checked === false ? "not checked" : "missing"} ${check.name}: ${check.message}`)
     ].join("\n") + "\n";
 }
 function formatRunHuman(result) {