@dna113p/machines 0.1.0 → 0.3.0

package/dist/src/claude.d.ts

@@ -0,0 +1,35 @@
+import type { AgentRunner } from "./index.ts";
+export interface ClaudeAgentOptions {
+    readonly env?: Readonly<Record<string, string>>;
+    readonly harness?: string;
+    /** A Claude Code model alias (for example "opus", "sonnet", "haiku") or a full model name. */
+    readonly model?: string;
+    /** An effort level supported by the installed Claude Code and selected model. */
+    readonly effort?: string;
+    /**
+     * Defaults to "dontAsk": tools run only when Claude Code's own permission
+     * rules already allow them, and anything that would prompt is denied.
+     */
+    readonly permissionMode?: "acceptEdits" | "auto" | "bypassPermissions" | "dontAsk" | "manual" | "plan";
+    /** Restricts the built-in tool set, for example ["Read"]. */
+    readonly tools?: readonly string[];
+    /** Permission rules to allow in addition to Claude Code's settings, for example ["Bash(npm test)"]. */
+    readonly allowedTools?: readonly string[];
+    /** Tools or permission rules to deny regardless of Claude Code's settings. */
+    readonly disallowedTools?: readonly string[];
+    /** Defaults to false, so each invocation does not save a resumable Claude Code session. */
+    readonly sessionPersistence?: boolean;
+    /**
+     * Defaults to "limit": once the plan limit is used up and Claude Code starts
+     * spending paid extra usage, the turn stops with an `AgentLimitError`.
+     * "allow" lets the turn continue on extra usage.
+     */
+    readonly extraUsage?: "limit" | "allow";
+    readonly output?: "capture" | "stream";
+}
+/**
+ * Runs one fresh, non-interactive Claude Code turn using the installed CLI and
+ * its existing login. Authentication, settings, and permission rules stay in
+ * Claude Code; this runner never reads or forwards credentials.
+ */
+export declare function claudeAgent(command?: string, args?: readonly string[], options?: ClaudeAgentOptions): AgentRunner;

package/dist/src/claude.js

@@ -0,0 +1,294 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import * as v from "valibot";
+import { AgentLimitError } from "./agent-limit.js";
+import { agentPrompt, readAgentEvent } from "./agent-protocol.js";
+/**
+ * Runs one fresh, non-interactive Claude Code turn using the installed CLI and
+ * its existing login. Authentication, settings, and permission rules stay in
+ * Claude Code; this runner never reads or forwards credentials.
+ */
+export function claudeAgent(command = "claude", args = [], options = {}) {
+    return async (request, report) => {
+        if (request.cwd === undefined)
+            throw new Error("Claude Agent requires a working directory");
+        if (request.outcomes.length === 0)
+            throw new Error("Claude Agent requires at least one allowed outcome");
+        const harness = options.harness ?? command;
+        const env = { ...process.env, ...options.env };
+        // Claude Code exports its own CLAUDE_* variables (including CLAUDE_EFFORT) to
+        // child processes, so runner settings use names it does not own.
+        const model = options.model ?? env.MACHINES_CLAUDE_MODEL ?? env.MACHINES_AGENT_MODEL;
+        const effort = options.effort ?? env.MACHINES_CLAUDE_EFFORT ?? env.MACHINES_AGENT_EFFORT;
+        const outputMode = options.output ?? "stream";
+        report?.({
+            type: "identity",
+            harness,
+            ...(model === undefined ? {} : { model }),
+            ...(effort === undefined ? {} : { thinking: effort }),
+        });
+        let stderr = "";
+        try {
+            const child = spawn(command, [
+                ...args,
+                "--print", "--output-format", "stream-json", "--verbose",
+                "--permission-mode", options.permissionMode ?? "dontAsk",
+                ...(options.sessionPersistence === true ? [] : ["--no-session-persistence"]),
+                ...(model === undefined ? [] : ["--model", model]),
+                ...(effort === undefined ? [] : ["--effort", effort]),
+                ...(options.tools === undefined ? [] : ["--tools", options.tools.join(",")]),
+                ...(options.allowedTools === undefined ? [] : ["--allowed-tools", options.allowedTools.join(",")]),
+                ...(options.disallowedTools === undefined ? [] : ["--disallowed-tools", options.disallowedTools.join(",")]),
+            ], { cwd: request.cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+            const exited = new Promise((resolve, reject) => {
+                child.once("error", reject);
+                child.stdin.once("error", reject);
+                child.once("close", (code, signal) => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(signal === null
+                            ? `Process exited with code ${code}`
+                            : `Process terminated by ${signal}`));
+                });
+            });
+            // Attach handlers before reading stdout: errors can arrive while it drains.
+            void exited.catch(() => { });
+            child.stderr.setEncoding("utf8");
+            child.stderr.on("data", (chunk) => {
+                stderr += chunk;
+                if (outputMode === "stream")
+                    process.stderr.write(chunk);
+            });
+            const lines = createInterface({ input: child.stdout });
+            const toolTitles = new Map();
+            let result;
+            // The CLI reports a limit beside its messages: on the last top-level
+            // assistant record and in the latest rate-limit information.
+            let assistantError = {};
+            let rateLimit;
+            // The CLI streams one record per content block, and its final result
+            // joins the text blocks of the closing message.
+            let closingMessage;
+            let closingText = "";
+            const emitMessage = (text) => {
+                if (text === "")
+                    return;
+                report?.({ type: "output", text: `${text}${text.endsWith("\n") ? "" : "\n"}` });
+                if (outputMode === "stream")
+                    process.stdout.write(`${text}${text.endsWith("\n") ? "" : "\n"}`);
+            };
+            try {
+                child.stdin.end(agentPrompt(request));
+                for await (const line of lines) {
+                    const record = decodeRecord(line);
+                    if (record === undefined)
+                        continue;
+                    if (record.type === "malformed-result") {
+                        // An unreadable final result must not leave an earlier one in effect.
+                        result = { failed: true, text: "Claude returned a malformed final result" };
+                    }
+                    else if (record.type === "system") {
+                        // The CLI resolves aliases and defaults; report what actually runs.
+                        report?.({
+                            type: "identity",
+                            harness,
+                            model: record.model,
+                            ...(effort === undefined ? {} : { thinking: effort }),
+                        });
+                    }
+                    else if (record.type === "rate_limit_event") {
+                        const info = record.rate_limit_info;
+                        if (info?.isUsingOverage === true && options.extraUsage !== "allow") {
+                            // The plan limit is already used up; continuing would spend paid credits.
+                            throw new AgentLimitError("Claude plan limit reached; extra usage is not used", agentLimit(harness, info));
+                        }
+                        // Information without a recognised status does not replace what is known.
+                        if (info?.status !== undefined)
+                            rateLimit = info;
+                    }
+                    else if (record.type === "result") {
+                        result = {
+                            failed: record.is_error === true || record.subtype !== "success",
+                            text: record.result ?? record.errors?.join("\n") ?? record.subtype,
+                            ...(record.is_error === true
+                                ? { apiError: { name: record.api_error, rateLimited: record.api_error_status === 429 } }
+                                : {}),
+                        };
+                    }
+                    else if (record.parent_tool_use_id !== undefined && record.parent_tool_use_id !== null) {
+                        // Subagent activity belongs to the parent's tool call, not the final answer.
+                    }
+                    else if (record.type === "assistant") {
+                        assistantError = { name: record.api_error, rateLimited: record.error === "rate_limit" };
+                        const info = record.api_error_params?.rate_limit_info;
+                        if (info?.status !== undefined)
+                            rateLimit = info;
+                        const message = record.message.id ?? undefined;
+                        if (message === undefined || message !== closingMessage)
+                            closingText = "";
+                        closingMessage = message;
+                        for (const block of record.message.content) {
+                            if (block.type === "text") {
+                                closingText += block.text;
+                                emitMessage(block.text);
+                            }
+                            else if (block.type === "tool_use") {
+                                toolTitles.set(block.id, block.name);
+                                report?.({ type: "tool", id: block.id, title: block.name, status: "in_progress" });
+                            }
+                        }
+                    }
+                    else if (typeof record.message.content !== "string") {
+                        for (const block of record.message.content) {
+                            if (block.type !== "tool_result")
+                                continue;
+                            const title = toolTitles.get(block.tool_use_id);
+                            report?.({
+                                type: "tool",
+                                id: block.tool_use_id,
+                                ...(title === undefined ? {} : { title }),
+                                status: block.is_error === true ? "failed" : "completed",
+                            });
+                        }
+                    }
+                }
+                // Only a final result that ended on an API error can be a limit. The latest
+                // rate-limit information names it and its reset, whatever its own status.
+                const limit = result?.apiError !== undefined
+                    && reachedLimit(result.apiError, assistantError, rateLimit, result.text)
+                    ? agentLimit(harness, rateLimit)
+                    : undefined;
+                try {
+                    await exited;
+                }
+                catch (cause) {
+                    // An empty result adds nothing to the exit, but a limit it carries is still reported.
+                    if (result === undefined || (result.text === "" && limit === undefined))
+                        throw cause;
+                    const message = cause instanceof Error ? cause.message : String(cause);
+                    throw turnFailure(result.text === "" ? message : `${message}: ${result.text}`, limit, { cause });
+                }
+                if (result === undefined)
+                    throw new Error("Claude exited without a final result");
+                if (result.failed)
+                    throw turnFailure(result.text, limit);
+                // Earlier messages may contain progress or a preliminary event. Only the
+                // CLI's final result determines the outcome, never accumulated activity.
+                if (withoutSpace(result.text) !== withoutSpace(closingText))
+                    emitMessage(result.text);
+                return readAgentEvent(result.text, { adapter: "Claude", includeMessage: outputMode === "capture" });
+            }
+            finally {
+                lines.close();
+                child.kill();
+            }
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            const detail = stderr.trim();
+            const text = `Claude Agent "${command}" failed in "${request.cwd}": ${message}${detail === "" ? "" : `\n${detail}`}`;
+            throw cause instanceof AgentLimitError
+                ? new AgentLimitError(text, cause.limit, { cause })
+                : new Error(text, { cause });
+        }
+    };
+}
+const planLimitErrors = new Set(["usage_limit_reached", "model_requires_usage_credits"]);
+const limitText = /^(?:You've (?:hit|reached) your |You're out of (?:usage credits|extra usage))/u;
+const maximumResetDelay = 8 * 24 * 60 * 60 * 1000;
+// A 429 alone may be a temporary throttle; a plan limit also names itself, is
+// rejected by the rate-limit information, or uses Claude Code's limit wording.
+function reachedLimit(result, assistant, rateLimit, text) {
+    if ([result.name, assistant.name].some((name) => name !== undefined && planLimitErrors.has(name)))
+        return true;
+    if (result.rateLimited !== true && assistant.rateLimited !== true)
+        return false;
+    return (rateLimit?.status === "rejected" && rateLimit.isUsingOverage !== true) || limitText.test(text);
+}
+function agentLimit(harness, info) {
+    const now = Date.now();
+    const resetsAt = info?.resetsAt === undefined ? undefined : info.resetsAt * 1000;
+    return {
+        harness,
+        ...(info?.rateLimitType === undefined ? {} : { kind: info.rateLimitType }),
+        // A reset time that is past or implausibly distant is not reported.
+        ...(resetsAt !== undefined && Number.isFinite(resetsAt) && resetsAt > now && resetsAt <= now + maximumResetDelay
+            ? { resetsAt }
+            : {}),
+    };
+}
+function turnFailure(message, limit, options) {
+    return limit === undefined ? new Error(message, options) : new AgentLimitError(message, limit, options);
+}
+const parentSchema = v.nullish(v.string());
+// Unlisted block types (thinking, images, future additions) are skipped, not rejected.
+const otherBlockSchema = v.pipe(v.object({ type: v.string() }), v.transform(() => ({ type: "other" })));
+const assistantBlockSchema = v.union([
+    v.object({ type: v.literal("text"), text: v.string() }),
+    v.object({ type: v.literal("tool_use"), id: v.string(), name: v.string() }),
+    otherBlockSchema,
+]);
+const userBlockSchema = v.union([
+    v.object({ type: v.literal("tool_result"), tool_use_id: v.string(), is_error: v.nullish(v.boolean()) }),
+    otherBlockSchema,
+]);
+// The limit fields were read from the Claude Code bundle, not observed at a real
+// limit, so a malformed one is dropped without rejecting the record that carries it.
+// A value outside the listed ones counts as malformed.
+const tolerant = (schema) => v.fallback(v.optional(schema), undefined);
+const rateLimitInfoSchema = v.object({
+    status: tolerant(v.picklist(["allowed", "allowed_warning", "rejected"])),
+    // Whole Unix seconds.
+    resetsAt: tolerant(v.pipe(v.number(), v.safeInteger())),
+    rateLimitType: tolerant(v.picklist([
+        "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "seven_day_overage_included", "overage",
+    ])),
+    isUsingOverage: tolerant(v.boolean()),
+});
+const recordSchema = v.variant("type", [
+    v.object({ type: v.literal("system"), subtype: v.literal("init"), model: v.string() }),
+    v.object({ type: v.literal("rate_limit_event"), rate_limit_info: tolerant(rateLimitInfoSchema) }),
+    v.object({
+        type: v.literal("assistant"),
+        parent_tool_use_id: parentSchema,
+        message: v.object({ id: v.nullish(v.string()), content: v.array(assistantBlockSchema) }),
+        error: tolerant(v.string()),
+        api_error: tolerant(v.string()),
+        api_error_params: tolerant(v.object({ rate_limit_info: tolerant(rateLimitInfoSchema) })),
+    }),
+    v.object({
+        type: v.literal("user"),
+        parent_tool_use_id: parentSchema,
+        message: v.object({ content: v.union([v.string(), v.array(userBlockSchema)]) }),
+    }),
+    v.object({
+        type: v.literal("result"),
+        subtype: v.string(),
+        is_error: v.nullish(v.boolean()),
+        result: v.nullish(v.string()),
+        errors: v.nullish(v.array(v.string())),
+        api_error: tolerant(v.string()),
+        api_error_status: tolerant(v.number()),
+    }),
+]);
+// Ignore unsupported events and malformed records without exposing raw protocol data.
+function decodeRecord(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = v.safeParse(recordSchema, value);
+    if (parsed.success)
+        return parsed.output;
+    return value !== null && typeof value === "object" && "type" in value && value.type === "result"
+        ? { type: "malformed-result" }
+        : undefined;
+}
+// Block boundaries differ between streamed messages and the joined result.
+function withoutSpace(text) {
+    return text.replace(/\s+/gu, "");
+}

package/dist/src/cli.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
+import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { emitKeypressEvents } from "node:readline";
-import { stripVTControlCharacters } from "node:util";
+import { inspect, stripVTControlCharacters } from "node:util";
 import yoctoSpinner from "yocto-spinner";
 import { bold, cyan, dim, green, magenta, red, yellow } from "yoctocolors";
+import { assertJsonValue, isJsonValue } from "./json.js";
 import { discoverMachines, machinesUserHome } from "./discovery.js";
 import { listAgentPresets, listMachines, prepareMachineRun, } from "./launcher.js";
+import { inboxHuman, respondToRun } from "./run-inbox.js";
+import { createRunStatusPublisher, isProcessAlive, readRunStatuses, runStatusDirectory, } from "./run-status.js";
 const [command, selector, ...argumentsAfterSelector] = process.argv.slice(2);
 try {
     if (command === "list" && selector === undefined) {
@@ -35,13 +39,21 @@ try {
     else if (command === "run" && selector !== undefined) {
         await runMachine(await resolveMachine(selector), argumentsAfterSelector);
     }
+    else if (command === "runs" && (selector === undefined || selector === "--json") && argumentsAfterSelector.length === 0) {
+        listRuns(selector === "--json");
+    }
+    else if (command === "respond" && selector !== undefined) {
+        await respond([selector, ...argumentsAfterSelector]);
+    }
     else {
         throw new Error([
             "Usage:",
             "  machine list",
             "  machine agents",
             "  machine show <name-or-file>",
-            "  machine run <name-or-file> [--agent role=preset]... [--] [input]",
+            "  machine run <name-or-file> [--agent role=preset]... [--input-file <file|->] [--] [input]",
+            "  machine runs [--json]",
+            "  machine respond [--question] <run-id> <request-id> [--] <response>",
         ].join("\n"));
     }
 }
@@ -61,7 +73,7 @@ async function resolveMachine(selector) {
     return found.path;
 }
 async function runMachine(machinePath, args) {
-    const invocation = parseRunArguments(args);
+    const invocation = await parseRunArguments(args);
     printMachineHeader(machinePath);
     const prepared = await prepareMachineRun({
         cwd: process.cwd(),
@@ -70,16 +82,78 @@ async function runMachine(machinePath, args) {
         agents: Object.fromEntries(invocation.agentOverrides),
     });
     const status = createRunStatus(machinePath);
+    const runId = randomUUID();
+    const published = createRunStatusPublisher({ id: runId, machine: prepared.name, path: prepared.path, cwd: process.cwd() });
+    const statusDirectory = runStatusDirectory();
+    // Machines started by this run's Operations and Agents are its sub-runs.
+    process.env.MACHINES_RUN_PARENT = runId;
+    let publishedState;
+    // A runner reports its identity as it starts. For a state entered by a
+    // transition that is before the state is announced, so an identity is held
+    // for the rest of the tick and published with the state it belongs to.
+    let arriving;
     try {
         const result = await prepared.start({
-            onAgentUpdate: status.onAgentUpdate,
-            onHumanInput: status.onHumanInput,
-            onState: status.onState,
+            onAgentUpdate(update) {
+                if (update.type === "identity") {
+                    arriving = update;
+                    queueMicrotask(() => {
+                        if (arriving !== update)
+                            return;
+                        arriving = undefined;
+                        published.update({ agent: update });
+                    });
+                }
+                else if (update.type === "limit" && update.status !== "swapped") {
+                    // A swap while every preset is being tried again leaves the wait as it is published.
+                    published.update({
+                        limit: update.status === "resumed"
+                            ? undefined
+                            : { text: update.text, ...(update.until === undefined ? {} : { until: update.until }) },
+                    });
+                }
+                status.onAgentUpdate(update);
+            },
+            // A published run can also be answered through its inbox by `machine respond`.
+            ...(statusDirectory === undefined ? {} : {
+                human: inboxHuman({
+                    directory: statusDirectory,
+                    runId,
+                    publish: (request) => published.update({ status: "waiting", human: request }),
+                    acknowledge: (delivery) => published.update({ delivery }),
+                    onTerminalRefused: (reason) => console.error(reason),
+                    onTerminalClosed(requestId) {
+                        // Finish the unanswered prompt line before saying where the answer can come from.
+                        process.stdout.write("\n");
+                        console.error(`No terminal input. Answer with: machine respond ${runId} ${requestId} <response>`);
+                    },
+                }),
+            }),
+            onHumanInput(active) {
+                published.update(active ? { status: "waiting" } : { status: "running", human: undefined });
+                status.onHumanInput(active);
+            },
+            onState(state) {
+                const entered = formatState(state);
+                if (entered === publishedState)
+                    published.update({ state });
+                else {
+                    published.update({ state, agent: arriving });
+                    arriving = undefined;
+                }
+                publishedState = entered;
+                status.onState(state);
+            },
         });
+        published.finish({ state: result.value });
         status.succeed();
         console.log(`--> ${String(result.value)}`);
+        if (result.output !== undefined) {
+            console.log(isJsonValue(result.output) ? JSON.stringify(result.output, null, 2) : inspect(result.output));
+        }
     }
     catch (cause) {
+        published.finish({ error: cause instanceof Error ? cause.message : String(cause) });
         status.fail();
         throw cause;
     }
@@ -87,7 +161,46 @@ async function runMachine(machinePath, args) {
         status.close();
     }
 }
-function parseRunArguments(args) {
+function listRuns(json) {
+    const runs = readRunStatuses(requireStatusDirectory())
+        .filter((record) => (record.status === "running" || record.status === "waiting") && isProcessAlive(record.pid))
+        .sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
+    if (json) {
+        console.log(JSON.stringify(runs, null, 2));
+        return;
+    }
+    if (runs.length === 0)
+        console.log("No Machine runs are running or waiting.");
+    runs.forEach((record, index) => {
+        printRunListing(record, index > 0);
+    });
+}
+async function respond(args) {
+    const question = args[0] === "--question";
+    const [runId, requestId, ...words] = question ? args.slice(1) : args;
+    if (words[0] === "--")
+        words.shift();
+    if (runId === undefined || requestId === undefined || words.length === 0) {
+        throw new Error("Usage: machine respond [--question] <run-id> <request-id> [--] <response>");
+    }
+    const text = words.join(" ");
+    await respondToRun({
+        directory: requireStatusDirectory(),
+        runId,
+        requestId,
+        response: question ? { type: "question", text } : text,
+    });
+    console.log(`Machine run ${runId} took the ${question ? "question" : "response"}.`);
+}
+function requireStatusDirectory() {
+    const directory = runStatusDirectory();
+    if (directory === undefined) {
+        throw new Error("Run status publication is off: set MACHINES_RUN_STATUS_DIR to the directory the runs publish to.");
+    }
+    return directory;
+}
+async function parseRunArguments(args) {
+    let inputFile;
     const agentOverrides = new Map();
     let index = 0;
     while (index < args.length) {
@@ -96,6 +209,13 @@ function parseRunArguments(args) {
             index += 1;
             break;
         }
+        if (argument === "--input-file") {
+            if (inputFile !== undefined || args[index + 1] === undefined)
+                throw new Error("Expected one --input-file <file|->");
+            inputFile = args[index + 1];
+            index += 2;
+            continue;
+        }
         if (argument !== "--agent")
             break;
         const assignment = args[index + 1];
@@ -117,10 +237,24 @@ function parseRunArguments(args) {
         agentOverrides.set(role, preset);
         index += 2;
     }
-    return {
-        agentOverrides,
-        input: args.slice(index).join(" "),
-    };
+    let input = args.slice(index).join(" ");
+    if (inputFile !== undefined) {
+        if (args.length > index)
+            throw new Error("Use positional input or --input-file, not both");
+        let text;
+        if (inputFile === "-") {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(Buffer.from(chunk));
+            text = Buffer.concat(chunks).toString("utf8");
+        }
+        else
+            text = await readFile(inputFile, "utf8");
+        const parsed = JSON.parse(text);
+        assertJsonValue(parsed, "Machine input");
+        input = parsed;
+    }
+    return { agentOverrides, input };
 }
 function printMachineListing(found, separate) {
     if (!process.stdout.isTTY) {
@@ -153,6 +287,7 @@ function printAgentListing(preset, separate) {
             preset.model ?? "",
             preset.thinking ?? "",
             preset.source,
+            preset.fallback?.join(", ") ?? "",
         ].join("\t"));
         return;
     }
@@ -162,8 +297,35 @@ function printAgentListing(preset, separate) {
     console.log(`  ${preset.description}`);
     if (identity.length > 0)
         console.log(`  ${magenta(identity.join(" · "))}`);
+    if (preset.fallback !== undefined)
+        console.log(`  fallback: ${preset.fallback.join(", ") || "none"}`);
     console.log(`  ${dim(preset.source)}`);
 }
+function printRunListing(record, separate) {
+    const state = record.state ?? "starting";
+    const human = record.status === "waiting" ? record.human : undefined;
+    // Recorded text must not be able to move the cursor or restyle the terminal.
+    const plain = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").trim();
+    const details = human === undefined ? (record.limit === undefined ? [] : [plain(record.limit.text)]) : [
+        ...human.prompt.split("\n").map(plain).filter((line) => line !== ""),
+        ...(human.requestId === undefined ? [] : [`request: ${plain(human.requestId)}`]),
+        ...(human.choices === undefined ? [] : [`choices: ${human.choices.map(plain).join(", ")}`]),
+        ...(human.suggestions === undefined ? [] : [`suggestions: ${human.suggestions.map(plain).join(", ")}`]),
+        ...(human.discussion === true ? ["discussion: questions allowed"] : []),
+    ];
+    if (!process.stdout.isTTY) {
+        console.log([record.id, record.machine, record.status, state].map(plain).join("\t"));
+        for (const line of details)
+            console.log(`  ${line}`);
+        return;
+    }
+    if (separate)
+        console.log();
+    const status = record.status === "waiting" ? yellow("waiting") : cyan("running");
+    console.log(`${bold(plain(record.id))}  ${bold(cyan(plain(record.machine)))} › ${status} · ${plain(state)}`);
+    for (const line of details)
+        console.log(`  ${line.startsWith("request: ") ? dim(line) : line}`);
+}
 function printMachineHeader(machinePath) {
     if (!process.stdout.isTTY) {
         console.log(`Machine: ${machinePath}`);
@@ -179,7 +341,10 @@ function createRunStatus(machinePath) {
             onState(state) {
                 console.error(`● ${name} · ${formatState(state)}`);
             },
-            onAgentUpdate() { },
+            onAgentUpdate(update) {
+                if (update.type === "limit")
+                    console.error(update.text.replace(/\s+/gu, " "));
+            },
             onHumanInput() { },
             succeed() { },
             fail() { },
@@ -192,6 +357,8 @@ function createRunStatus(machinePath) {
     let activityExpanded = false;
     let agentOutput = "";
     let agentIdentity = {};
+    let agentLimit = "";
+    let agentWaiting = false;
     let refresh;
     const tools = new Map();
     const hotkeysAvailable = Boolean(process.stdin.isTTY && process.stdin.setRawMode);
@@ -211,12 +378,14 @@ function createRunStatus(machinePath) {
                 ? undefined
                 : `thinking ${agentIdentity.thinking}`,
         ].filter(Boolean).join(" · ");
-        const identityLine = identity === ""
+        const width = Math.max(20, (process.stderr.columns ?? 100) - 4);
+        const identityLine = identity === "" ? "" : `\n  ${dim(truncate(identity, width))}`;
+        const limitLine = agentLimit === ""
             ? ""
-            : `\n  ${dim(truncate(identity, Math.max(20, (process.stderr.columns ?? 100) - 4)))}`;
+            : `\n  ${yellow(truncate(stripVTControlCharacters(agentLimit).replace(/\s+/gu, " "), width))}`;
         return activityExpanded
-            ? `${status}${identityLine}\n${activityText()}`
-            : `${status}${identityLine}`;
+            ? `${status}${identityLine}${limitLine}\n${activityText()}`
+            : `${status}${identityLine}${limitLine}`;
     }
     function completedText() {
         return `${green(displayState(currentState))} · ${dim(formatElapsed(Date.now() - enteredAt))}`;
@@ -317,6 +486,13 @@ function createRunStatus(machinePath) {
             else if (update.type === "output") {
                 agentOutput = (agentOutput + update.text).slice(-32_768);
             }
+            else if (update.type === "limit") {
+                // A wait stays on screen while its presets are tried again, until one of them resumes.
+                if (update.status !== "swapped")
+                    agentWaiting = update.status === "waiting";
+                if (update.status !== "swapped" || !agentWaiting)
+                    agentLimit = update.text;
+            }
             else {
                 const previous = tools.get(update.id);
                 tools.set(update.id, {
@@ -344,6 +520,8 @@ function createRunStatus(machinePath) {
             enteredAt = Date.now();
             agentOutput = "";
             agentIdentity = {};
+            agentLimit = "";
+            agentWaiting = false;
             tools.clear();
             if (humanInputActive)
                 return;

package/dist/src/codex.d.ts

@@ -0,0 +1,16 @@
+import type { AgentRunner } from "./index.ts";
+export interface CodexAgentOptions {
+    readonly env?: Readonly<Record<string, string>>;
+    readonly harness?: string;
+    readonly model?: string;
+    /** A reasoning effort supported by the selected Codex model. */
+    readonly effort?: string;
+    /** Defaults to read-only; writes and unrestricted access require an explicit choice. */
+    readonly sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+    readonly skipGitRepoCheck?: boolean;
+    /** Defaults to true, so each invocation does not persist a Codex session. */
+    readonly ephemeral?: boolean;
+    readonly output?: "capture" | "stream";
+}
+/** Runs one fresh, non-interactive Codex turn using the installed CLI and its authentication. */
+export declare function codexAgent(command?: string, args?: readonly string[], options?: CodexAgentOptions): AgentRunner;