humanish 0.57.0 → 0.59.0

package/dist/local-agent-appserver.js

@@ -0,0 +1,267 @@
+// A codex app-server THREAD as the computer-use brain, instead of a fresh `codex exec` per turn.
+//
+// WHY THIS REPLACED THE ONE-SHOT VERSION, measured on this machine:
+//   `codex exec` per turn        ~9s every turn, and every turn starts cold
+//   app-server thread            ~500ms ONCE, then 2.7s / 5.8s / 8.9s per turn
+//
+// The speed is the smaller half. `codex exec` boots a CLI, loads config, agents and MCP servers on
+// every single turn, and — the part that actually matters — hands the model a conversation that
+// begins fresh each time. A participant driving a desktop that way has AMNESIA: it cannot remember
+// that it already tried the menu, because nothing carried. A thread remembers, which is how the
+// OpenAI computer-use provider has always worked (previous_response_id), and it is the difference
+// between studying one participant and studying sixty strangers who each see one screenshot.
+//
+// The protocol is not guessed: `codex app-server generate-json-schema` emits it, and it gives us
+// exactly what this loop needs — `turn/start` takes `input: [{type:"localImage", path}, ...]`,
+// an `outputSchema` that constrains the reply (so no fence-scraping), and per-turn `effort` and
+// `model` overrides described as applying "for this turn and subsequent turns".
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+import { toCuaActions } from "./local-agent-cli.js";
+/** Newline-delimited JSON-RPC over the child's stdio — the framing codex-app-server.ts uses. */
+export function stdioTransport(child) {
+    const rl = readline.createInterface({ input: child.stdout });
+    const pending = new Map();
+    const waiters = [];
+    let nextId = 0;
+    rl.on("line", (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return; // the server also logs non-JSON; ignore rather than crash the run
+        }
+        const id = message.id;
+        if (typeof id === "number" && pending.has(id)) {
+            const entry = pending.get(id);
+            pending.delete(id);
+            if (message.error !== undefined) {
+                entry.reject(new Error(`codex app-server: ${JSON.stringify(message.error).slice(0, 300)}`));
+            }
+            else {
+                entry.resolve((message.result ?? {}));
+            }
+            return;
+        }
+        if (typeof message.method === "string") {
+            for (let index = waiters.length - 1; index >= 0; index -= 1) {
+                if (waiters[index].method === message.method) {
+                    waiters.splice(index, 1)[0].resolve(message);
+                }
+            }
+        }
+    });
+    return {
+        request: async (method, params) => await new Promise((resolve, reject) => {
+            const id = (nextId += 1);
+            pending.set(id, { resolve, reject });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        }),
+        notify: (method, params) => {
+            child.stdin.write(`${JSON.stringify({ method, params })}\n`);
+        },
+        awaitNotification: async (method, timeoutMs) => await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`timed out waiting for ${method}`)), timeoutMs);
+            waiters.push({
+                method,
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                }
+            });
+        }),
+        close: () => {
+            rl.close();
+            child.kill();
+        }
+    };
+}
+export const APP_SERVER_CAPABILITIES = {
+    headless: true,
+    structuredTrace: true,
+    lanes: ["computer-use"],
+    producesScreenshots: true,
+    byoModel: true,
+    preGrantableApprovals: false,
+    inProcessTools: false,
+    license: "open"
+};
+/** The reply shape a turn is constrained to. Strict mode: every property in `required`. */
+export function turnOutputSchema() {
+    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: ["click", "double_click", "type", "keypress", "scroll", "wait", "done"] },
+                        x: { type: ["integer", "null"] },
+                        y: { type: ["integer", "null"] },
+                        text: { type: ["string", "null"] },
+                        keys: { type: ["array", "null"], items: { type: "string" } },
+                        ms: { type: ["integer", "null"] }
+                    }
+                }
+            }
+        }
+    };
+}
+function readNested(value, keys) {
+    let current = value;
+    for (const key of keys) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[key];
+    }
+    return typeof current === "string" ? current : undefined;
+}
+/**
+ * Start a thread and return a provider that spends it, one `turn/start` per computer-use turn.
+ *
+ * The thread is started EAGERLY (before the first screenshot) so the ~500ms handshake is paid
+ * while the sandbox is still booting rather than inside turn one.
+ */
+export async function startAppServerSession(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    const cwd = options.cwd ?? process.cwd();
+    const effort = options.reasoningEffort ?? "low";
+    let child;
+    let transport = options.transport;
+    if (transport === undefined) {
+        child = spawn("codex", ["app-server"], { cwd, stdio: ["pipe", "pipe", "pipe"] });
+        // The server logs to stderr; draining it keeps the pipe from filling and stalling the run.
+        child.stderr.resume();
+        transport = stdioTransport(child);
+    }
+    await transport.request("initialize", {
+        clientInfo: { name: "humanish_cli", title: "Humanish CLI", version: "0.1.0" },
+        capabilities: {}
+    });
+    transport.notify("initialized", {});
+    const thread = await transport.request("thread/start", {
+        cwd,
+        // The participant is here to look at a screen, not to touch this machine. read-only + never
+        // is the same bound the one-shot version had, declared once for the whole thread.
+        approvalPolicy: "never",
+        sandbox: "read-only",
+        serviceName: "humanish",
+        // Nothing about this study belongs in the operator's codex history.
+        ephemeral: true,
+        ...(options.baseInstructions === undefined ? {} : { baseInstructions: options.baseInstructions }),
+        ...(options.model === undefined ? {} : { model: options.model })
+    });
+    const threadId = readNested(thread, ["thread", "id"]);
+    if (threadId === undefined) {
+        transport.close();
+        throw new Error("codex app-server did not return a thread id");
+    }
+    const provider = {
+        id: "local-agent-codex-app-server",
+        version: options.model ?? "codex app-server (local, operator-authenticated)",
+        modelSettings: { reasoningEffort: effort },
+        capabilities: APP_SERVER_CAPABILITIES,
+        requiresFrame: true,
+        async nextTurn(request, signal) {
+            const frame = request.observation.screenshot;
+            if (frame === undefined) {
+                throw new Error("the codex app-server provider needs a screenshot and this observation has none");
+            }
+            const { mkdtemp, rm, writeFile } = await import("node:fs/promises");
+            const { tmpdir } = await import("node:os");
+            const path = await import("node:path");
+            const work = await mkdtemp(path.join(tmpdir(), "humanish-appserver-"));
+            try {
+                const shot = path.join(work, "screen.png");
+                await writeFile(shot, frame);
+                const hint = request.contextHint === undefined ? "" : `\n\nNote from the harness: ${request.contextHint}`;
+                const completed = transport.awaitNotification("turn/completed", timeoutMs);
+                await transport.request("turn/start", {
+                    threadId,
+                    cwd,
+                    approvalPolicy: "never",
+                    sandboxPolicy: { type: "readOnly" },
+                    // Per-turn, because a lane declares it and the schema says it applies to this turn and
+                    // the ones after — so a lane that raises effort raises it from that point on.
+                    effort,
+                    ...(options.model === undefined ? {} : { model: options.model }),
+                    outputSchema: turnOutputSchema(),
+                    input: [
+                        { type: "localImage", path: shot },
+                        {
+                            type: "text",
+                            // The persona already lives in baseInstructions; this is only the turn's ask, which
+                            // is why it stays this short.
+                            text: `This is the current screen. What do you do next?${hint}`,
+                            text_elements: []
+                        }
+                    ]
+                });
+                const abort = signal === undefined
+                    ? undefined
+                    : new Promise((_resolve, reject) => {
+                        signal.addEventListener("abort", () => reject(new Error("run stopped")), { once: true });
+                    });
+                const note = await (abort === undefined ? completed : Promise.race([completed, abort]));
+                return turnFromNotification(note);
+            }
+            finally {
+                await rm(work, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+    };
+    return {
+        provider,
+        close: () => {
+            transport?.close();
+            child?.kill();
+        }
+    };
+}
+/** Read a `turn/completed` notification into a CuaTurn. Exported for tests. */
+export function turnFromNotification(note) {
+    const params = (note.params ?? {});
+    const turn = (params.turn ?? {});
+    // Read the protocol, do not guess it: `turn/completed` carries `turn.items`, and the model's
+    // answer is the LAST `agentMessage` item, whose `text` is a plain string. The first cut of this
+    // looked for `turn.output`, found nothing, and silently produced an empty turn — which the loop
+    // read as "the participant is finished", ending a live study after one screenshot.
+    const items = Array.isArray(turn.items) ? turn.items : [];
+    const message = [...items].reverse().find((item) => item.type === "agentMessage");
+    const text = typeof message?.text === "string" ? message.text : "";
+    let parsed;
+    try {
+        // `outputSchema` constrains it to JSON, but a fence costs nothing to tolerate.
+        const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+        parsed = JSON.parse((fenced?.[1] ?? text).trim());
+    }
+    catch {
+        // A turn whose constrained output did not arrive 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(`codex app-server returned no structured turn output (${text.slice(0, 160)})`);
+    }
+    const actions = toCuaActions(Array.isArray(parsed.actions) ? parsed.actions : []);
+    return {
+        actions,
+        pendingSafetyChecks: [],
+        // EXPLICIT only. The first version also inferred done from "no actions plus a message", and
+        // that inference ended a live study on turn one with a 7-second "goal_satisfied": the model
+        // narrated the screen, chose no action, and the provider called it finished. The schema
+        // guarantees a `done` boolean, so there is nothing to infer.
+        done: parsed.done === true,
+        ...(typeof parsed.reasoning === "string" && parsed.reasoning.length > 0 ? { reasoning: parsed.reasoning } : {}),
+        ...(typeof parsed.message === "string" && parsed.message.length > 0 ? { message: parsed.message } : {})
+        // No `usage`: a subscription thread reports nothing we could price, and a number invented here
+        // is what would make the run's cost line a lie.
+    };
+}
+//# sourceMappingURL=local-agent-appserver.js.map

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

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

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

@@ -0,0 +1,104 @@
+import type { ActorCapabilities } from "./actor-contract.js";
+import type { CuaAction, CuaProvider } from "./computer-use.js";
+import type { ReasoningEffort } from "./reasoning-effort.js";
+export type LocalAgentId = "codex" | "claude";
+export interface LocalAgentDescriptor {
+    id: LocalAgentId;
+    /** The command a person types. */
+    bin: string;
+    /** For humans: "Codex (ChatGPT plan)". */
+    label: string;
+    /** Where its credentials live, so `doctor` can say "signed in" without reading the file. */
+    credentialPath: string;
+}
+export declare const LOCAL_AGENTS: readonly LocalAgentDescriptor[];
+/**
+ * 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 declare function localAgentTurnSchema(): Record<string, unknown>;
+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[];
+/**
+ * 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 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 {
+    agent: LocalAgentId;
+    /** Per-turn wall clock. A coding agent left to think can outlast the run. */
+    timeoutMs?: number;
+    /**
+     * Codex defaults to HIGH effort, which timed out at 240s on a single action; `low` answered the
+     * same screenshot correctly in 9s. A computer-use run is sixty of these, so the default here is
+     * deliberately low and 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;
+/**
+ * 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 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. "signed in somewhere" is all doctor needs to say, and it is all
+     * we are entitled to know.
+     */
+    credentialsPresent: boolean;
+}
+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;
+}
+/**
+ * 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 {};