humanish 0.104.3 → 0.106.0

package/dist/actors/local-agent/claude-session.js

@@ -0,0 +1,370 @@
+// ONE Claude Code process as the computer-use brain, instead of a fresh `claude -p` per turn.
+//
+// WHY (#520): `actors[].localAgent: codex` already runs through a persistent app-server thread,
+// so the participant remembers what it tried. `claude` spawned `claude -p` per turn, so EVERY
+// turn started cold. Measured on the same lab with the same credentials (n=1 each): one-shot,
+// 188 actions over 90 turns and never finished; a thread that remembers, 21 actions over 8 turns
+// and goal_satisfied in 103 s. A participant that cannot remember trying the menu tries the menu
+// again. Until this existed, comparing the two agents measured the transport, not the model.
+//
+// THE MECHANISM, checked on this machine before it was written: `claude -p --input-format
+// stream-json --output-format stream-json --verbose` is a bidirectional session over stdio. One
+// NDJSON `user` message in, a stream of `system` / `assistant` / `result` messages out, then it
+// waits for the next `user` message with the conversation intact. Two messages, one session id,
+// and a codeword given in the first turn was recalled in the second. `--allowedTools Read` keeps
+// the bound the one-shot version had: it looks at a picture, and that is all it can do.
+//
+// What this is NOT: a change to the loop, the executor, the trace, or the Observer. Only where
+// the next action comes from.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { CuaProviderError } from "../computer-use/provider-error.js";
+import { declaredOutcomeOf, parseAgentJson, promptFor, toCuaActions, LOCAL_AGENT_CAPABILITIES, } from "./cli.js";
+/** How long Claude Code may take to acknowledge an interrupt before the session is ended. */
+const INTERRUPT_RECEIPT_TIMEOUT_MS = 5_000;
+/** Results can no longer be paired with the turns that asked for them. */
+class ClaudeSessionDesyncError extends Error {
+}
+/** The user messages a `result` answers. Claude Code 2.1.285 names them; older versions may not. */
+function answeredMessageIds(result) {
+    const many = result.user_message_uuids;
+    if (Array.isArray(many))
+        return many.filter((id) => typeof id === "string");
+    return typeof result.user_message_uuid === "string" ? [result.user_message_uuid] : [];
+}
+/**
+ * Register turn `id` in `waiting` and settle when its result arrives. On timeout or abort the
+ * turn leaves `waiting` and `onGiveUp` runs before the rejection.
+ */
+function waitForTurn(waiting, id, timeoutMs, signal, onGiveUp) {
+    return new Promise((resolve, reject) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const giveUp = (error) => {
+            if (!waiting.delete(id))
+                return;
+            finish();
+            onGiveUp();
+            reject(error);
+        };
+        const timer = setTimeout(() => giveUp(new Error(`Claude Code produced no result within ${timeoutMs}ms`)), timeoutMs);
+        const onAbort = () => giveUp(new Error("run stopped"));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        waiting.set(id, {
+            resolve: (value) => {
+                finish();
+                resolve(value);
+            },
+            reject: (error) => {
+                finish();
+                reject(error);
+            },
+        });
+    });
+}
+/**
+ * NDJSON over the child's stdio. Each user message carries a fresh `uuid`, and a `result` goes
+ * only to the turn whose uuid it names. A turn given up on is interrupted with a control request,
+ * and the next user message waits for the interrupt's receipt, so its `cancel_queued` cancels an
+ * abandoned message still in the queue but never the message sent after it. Every other message
+ * is a progress line and is ignored.
+ */
+function stdioClaudeTransport(child) {
+    const rl = readline.createInterface({ input: child.stdout });
+    const waiting = new Map();
+    // Given-up turns whose result may still arrive; it must reach nobody.
+    const abandoned = new Set();
+    const receipts = new Map();
+    let acknowledged = Promise.resolve();
+    let interrupts = 0;
+    let stderrTail = "";
+    let ended;
+    const write = (message) => {
+        child.stdin.write(`${JSON.stringify(message)}\n`);
+    };
+    const end = (error) => {
+        if (ended !== undefined)
+            return;
+        ended = error;
+        for (const turn of waiting.values())
+            turn.reject(error);
+        waiting.clear();
+        for (const settle of receipts.values())
+            settle();
+        receipts.clear();
+    };
+    const stop = () => {
+        rl.close();
+        child.stdin.end();
+        child.kill();
+    };
+    const desynchronize = (reason) => {
+        end(new ClaudeSessionDesyncError(reason));
+        stop();
+    };
+    const abandon = (id) => {
+        abandoned.add(id);
+        if (ended !== undefined)
+            return;
+        interrupts += 1;
+        const requestId = `humanish-interrupt-${interrupts}`;
+        const receipt = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                receipts.delete(requestId);
+                desynchronize(`Claude Code did not acknowledge an interrupt within ${INTERRUPT_RECEIPT_TIMEOUT_MS}ms`);
+                resolve();
+            }, INTERRUPT_RECEIPT_TIMEOUT_MS);
+            receipts.set(requestId, () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+        acknowledged = acknowledged.then(() => receipt);
+        write({
+            type: "control_request",
+            request_id: requestId,
+            request: { subtype: "interrupt", cancel_queued: true },
+        });
+    };
+    const deliver = (result) => {
+        const ids = answeredMessageIds(result);
+        if (ids.length === 0) {
+            // Without a named message, pairing is certain only while one turn waits and none was given up.
+            const [only, ...others] = waiting.keys();
+            if (only !== undefined && others.length === 0 && abandoned.size === 0) {
+                const turn = waiting.get(only);
+                waiting.delete(only);
+                turn?.resolve(result);
+            }
+            else {
+                desynchronize("a result named no user message while another turn could still answer");
+            }
+            return;
+        }
+        let known = false;
+        for (const id of ids) {
+            if (abandoned.delete(id)) {
+                known = true;
+                continue;
+            }
+            const turn = waiting.get(id);
+            if (turn === undefined)
+                continue;
+            waiting.delete(id);
+            turn.resolve(result);
+            known = true;
+        }
+        if (!known)
+            desynchronize("a result answered a user message this session did not send");
+    };
+    rl.on("line", (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return; // never a reason to end a run
+        }
+        if (message.type === "result") {
+            deliver(message);
+        }
+        else if (message.type === "control_response") {
+            const response = message.response;
+            const requestId = response?.request_id;
+            const settle = typeof requestId === "string" ? receipts.get(requestId) : undefined;
+            if (typeof requestId !== "string" || settle === undefined)
+                return;
+            receipts.delete(requestId);
+            settle();
+            if (response?.subtype !== "success")
+                desynchronize("Claude Code refused an interrupt");
+        }
+    });
+    child.stderr.on("data", (chunk) => {
+        stderrTail = (stderrTail + chunk.toString("utf8")).slice(-400);
+    });
+    child.on("close", (code, signal) => {
+        // Fail loud with the CLI's own words: a rate-limited plan says so here, which is a sentence
+        // the operator can act on, unlike "turn failed".
+        end(new Error(`Claude Code exited ${code ?? `on ${signal ?? "a signal"}`}${stderrTail.trim() ? `: ${stderrTail.trim()}` : ""}`));
+    });
+    return {
+        async turn(message, timeoutMs, signal) {
+            if (ended !== undefined)
+                throw ended;
+            await acknowledged;
+            if (ended !== undefined)
+                throw ended;
+            if (signal?.aborted)
+                throw new Error("run stopped");
+            const id = randomUUID();
+            const result = waitForTurn(waiting, id, timeoutMs, signal, () => abandon(id));
+            write({ ...message, uuid: id });
+            return result;
+        },
+        close() {
+            end(new Error("Claude Code session closed"));
+            stop();
+        },
+    };
+}
+const CLAUDE_SESSION_CAPABILITIES = LOCAL_AGENT_CAPABILITIES;
+/** The message shape Claude Code reads on stdin in stream-json mode. */
+export function userMessage(text) {
+    return { type: "user", message: { role: "user", content: [{ type: "text", text }] } };
+}
+/**
+ * Start one Claude Code session and return a provider that spends it, one user message per
+ * computer-use turn. Started EAGERLY (before the first screenshot) so the CLI's own boot is paid
+ * while the sandbox is still settling rather than inside turn one.
+ */
+export async function startClaudeSession(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    const effort = options.reasoningEffort ?? "low";
+    const work = await mkdtemp(path.join(options.workRoot ?? tmpdir(), "humanish-claude-session-"));
+    let child;
+    let transport = options.transport;
+    if (transport === undefined) {
+        const spawnFn = options.spawnFn ?? spawn;
+        child = spawnFn("claude", [
+            "-p",
+            "--input-format",
+            "stream-json",
+            "--output-format",
+            "stream-json",
+            // Required for stream-json output in -p mode; it is what makes the per-turn `result` visible.
+            "--verbose",
+            // Read is the only tool it needs — the screenshot — and the only one it gets.
+            "--allowedTools",
+            "Read",
+            ...(options.model === undefined ? [] : ["--model", options.model]),
+        ], { cwd: work, stdio: ["pipe", "pipe", "pipe"] });
+        transport = stdioClaudeTransport(child);
+    }
+    let turnIndex = 0;
+    let previousShot;
+    // A turn that delivered no result of its own spent tokens that no delivered turn reports. Its
+    // late result is discarded rather than added to another turn, so the usage stays unknown.
+    let usageIncomplete = false;
+    const provider = {
+        id: "local-agent-claude-session",
+        version: options.model ?? "claude (local, operator-authenticated, one session per run)",
+        modelSettings: { reasoningEffort: effort },
+        capabilities: CLAUDE_SESSION_CAPABILITIES,
+        requiresFrame: true,
+        get interactionUsageIncomplete() {
+            return usageIncomplete;
+        },
+        async nextTurn(request, signal) {
+            const frame = request.observation.screenshot;
+            if (frame === undefined) {
+                throw new Error("the Claude session provider needs a screenshot and this observation has none");
+            }
+            turnIndex += 1;
+            const shot = path.join(work, `screen-${String(turnIndex).padStart(3, "0")}.png`);
+            await writeFile(shot, frame);
+            const hint = request.contextHint === undefined
+                ? ""
+                : `\n\nNote from the harness: ${request.contextHint}`;
+            // The persona and the reply shape are in the conversation after turn one; re-sending them
+            // every turn is what the one-shot version had to do, and it is most of what it cost.
+            const text = turnIndex === 1
+                ? promptFor(request, shot)
+                : `Read the image file ${shot}. That is the CURRENT SCREEN, after your last actions took effect. ` +
+                    "Same participant, same task: decide what to do next. " +
+                    "Reply with ONLY a JSON object of the same shape as before." +
+                    hint;
+            let result;
+            try {
+                result = await transport.turn(userMessage(text), timeoutMs, signal);
+            }
+            catch (error) {
+                usageIncomplete = true;
+                if (error instanceof ClaudeSessionDesyncError) {
+                    // The stream no longer pairs results with turns, so no later turn can trust it.
+                    throw new CuaProviderError("protocol_error", {
+                        dispatched: "unknown",
+                        usageComplete: false,
+                        cleanup: "unconfirmed",
+                    });
+                }
+                throw error;
+            }
+            // The frame it already looked at is not needed on disk; the conversation remembers it.
+            if (previousShot !== undefined)
+                await unlink(previousShot).catch(() => undefined);
+            previousShot = shot;
+            return turnFromResult(result);
+        },
+    };
+    return {
+        provider,
+        close: async () => {
+            transport?.close();
+            child?.kill();
+            await rm(work, { recursive: true, force: true }).catch(() => undefined);
+        },
+    };
+}
+/** Read a stream-json `result` message into a CuaTurn. Exported for tests. */
+export function turnFromResult(result) {
+    if (result.is_error === true ||
+        (typeof result.subtype === "string" && result.subtype !== "success")) {
+        // A turn that errored is a BROKEN turn, never an empty one: an empty turn reads to the loop
+        // as "the participant chose to do nothing".
+        throw new Error(`Claude Code turn ended ${String(result.subtype ?? "in error")}: ${String(result.result ?? "").slice(0, 160)}`);
+    }
+    const text = typeof result.result === "string" ? result.result : "";
+    let parsed;
+    try {
+        parsed = parseAgentJson(text);
+    }
+    catch {
+        throw new Error(`Claude Code returned no structured turn output (${text.slice(0, 160)})`);
+    }
+    const actions = toCuaActions(Array.isArray(parsed.actions) ? parsed.actions : []);
+    const done = parsed.done === true || (actions.length === 0 && typeof parsed.message === "string");
+    const outcome = declaredOutcomeOf(parsed.outcome);
+    const usage = result.usage;
+    const count = (key) => typeof usage?.[key] === "number" ? usage[key] : undefined;
+    // Anthropic's input_tokens counts only the tokens after the last cache breakpoint; cache reads
+    // and writes are reported beside it. ActorTokenUsage.input is the whole prompt, with cachedInput
+    // and cacheWriteInput as parts of it, so the three are summed.
+    const uncachedInput = count("input_tokens");
+    const output = count("output_tokens");
+    const cachedInput = count("cache_read_input_tokens");
+    const cacheWriteInput = count("cache_creation_input_tokens");
+    const input = uncachedInput === undefined
+        ? undefined
+        : uncachedInput + (cachedInput ?? 0) + (cacheWriteInput ?? 0);
+    return {
+        actions,
+        pendingSafetyChecks: [],
+        done,
+        ...(outcome === undefined ? {} : { outcome }),
+        ...(typeof parsed.reasoning === "string" && parsed.reasoning.length > 0
+            ? { reasoning: parsed.reasoning }
+            : {}),
+        ...(typeof parsed.message === "string" && parsed.message.length > 0
+            ? { message: parsed.message }
+            : {}),
+        // Claude Code reports its token counts per turn (#531). They are recorded as counts; the
+        // run's cost line stays "not priced", because a subscription is not a rate card.
+        ...(input === undefined && output === undefined
+            ? {}
+            : {
+                usage: {
+                    ...(input === undefined ? {} : { input }),
+                    ...(output === undefined ? {} : { output }),
+                    ...(cachedInput === undefined ? {} : { cachedInput }),
+                    ...(cacheWriteInput === undefined ? {} : { cacheWriteInput }),
+                },
+            }),
+    };
+}

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

@@ -0,0 +1,115 @@
+import type { ActorCapabilities, ParticipantDeclaredOutcome } from "../contract.js";
+import type { CuaAction, CuaProvider, CuaTurnRequest } from "../computer-use/loop.js";
+import type { ReasoningEffort } from "../reasoning-effort.js";
+export type LocalAgentId = "codex" | "claude";
+interface LocalAgentDescriptor {
+    id: LocalAgentId;
+    /** The command a person types. */
+    bin: string;
+    /** For humans: "Codex (ChatGPT plan)". */
+    label: string;
+    /** Legacy file location; existence is a hint, never an authentication verdict. */
+    credentialPath: string;
+}
+interface RawAction {
+    kind?: string;
+    x?: number | null;
+    y?: number | null;
+    text?: string | null;
+    keys?: string[] | null;
+    ms?: number | 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 declare function toCuaActions(raw: readonly RawAction[]): CuaAction[];
+/** The declared outcome, only if it is one of the three words; anything else is absence. */
+export declare function declaredOutcomeOf(value: unknown): ParticipantDeclaredOutcome | 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 declare function parseAgentJson(text: string): Record<string, unknown>;
+export interface SpawnResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type SpawnLike = (bin: string, args: readonly string[], options: {
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<SpawnResult>;
+export interface LocalAgentProviderOptions {
+    /** Only Claude Code runs one-shot; hosted Codex runs as an app-server participant. */
+    agent: "claude";
+    /** Per-turn wall clock. A coding agent left to think can outlast the run. */
+    timeoutMs?: number;
+    /**
+     * Recorded in the trace's model settings. Low by default: a computer-use run is sixty turns, and
+     * a high-effort answer per turn costs minutes. The lab can raise it.
+     */
+    reasoningEffort?: ReasoningEffort;
+    /** Model override passed to the CLI (`--model`). Absent = the CLI's own default. */
+    model?: string;
+    spawnFn?: SpawnLike;
+    /** Scratch root for the screenshot and schema handed to the CLI. */
+    workRoot?: string;
+}
+export declare const LOCAL_AGENT_CAPABILITIES: ActorCapabilities;
+/** The turn prompt for Claude Code: the instructions, the screenshot to read, and the reply shape. */
+export declare function promptFor(request: CuaTurnRequest, screenshotPath: string): string;
+/**
+ * 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 declare function createLocalAgentProvider(options: LocalAgentProviderOptions): CuaProvider;
+export interface DetectedLocalAgent extends LocalAgentDescriptor {
+    /** Resolved path to the binary. */
+    binPath: string;
+    /**
+     * Whether a credential file exists for it. EXISTENCE ONLY — never read, never parsed, never
+     * reported beyond this boolean. Keyring storage may have no file at all.
+     */
+    credentialsPresent: boolean;
+    /** CLI-reported local status, not a provider request or account-validity test. */
+    authStatus: "authenticated" | "unauthenticated" | "unknown";
+    /** Known Codex login billing class. Absent when the status text is not one of the pinned shapes. */
+    billing?: "account-unknown" | "api";
+}
+export interface DetectLocalAgentsOptions {
+    /** Injected for tests: resolves a binary name to a path, or undefined. */
+    which?: (bin: string) => Promise<string | undefined>;
+    /** Injected for tests: does this path exist? */
+    exists?: (file: string) => Promise<boolean>;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Status output is classified in memory and never returned or persisted. */
+    authProbe?: (bin: string, args: readonly string[], env: NodeJS.ProcessEnv) => Promise<SpawnResult>;
+}
+export type HostedCodexCompatibility = "supported" | "unsupported_platform" | "unsupported_version";
+/** Host-only compatibility check. It never initializes app-server or submits a model request. */
+export declare function checkHostedCodexCompatibility(binPath: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    probe?: (bin: string, args: readonly string[], env: NodeJS.ProcessEnv) => Promise<SpawnResult>;
+}): Promise<HostedCodexCompatibility>;
+/**
+ * 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 declare function detectLocalAgents(options?: DetectLocalAgentsOptions): Promise<DetectedLocalAgent[]>;
+/** One line for `doctor`, in the register the other rows use. */
+export declare function localAgentDoctorMessage(found: readonly DetectedLocalAgent[]): string;
+export {};