@ocis/myagent-cli 0.2.0

package/dist/git/status.js

@@ -0,0 +1,226 @@
+// ---------------------------------------------------------------------------
+// Git working-tree status for the TUI's "changes" panel, plus the per-file
+// diff shown in the sidebar's popup viewer.
+//
+// Pure parsers (tested) + a collector that shells out to git. Any failure
+// (no repo, no git binary) yields `isRepo: false` and the panel hides itself.
+// ---------------------------------------------------------------------------
+export const EMPTY_GIT_STATUS = {
+    isRepo: false,
+    branch: null,
+    files: [],
+    totalInsertions: 0,
+    totalDeletions: 0,
+};
+/**
+ * Strip terminal-control sequences from a git-derived string (file paths,
+ * branch names). A malicious repository can carry filenames embedding ANSI/OSC
+ * escape sequences; rendering those raw would inject cursor moves, terminal
+ * title changes, or clipboard writes into the user's terminal. Applied at
+ * the parse boundary so every consumer (sidebar, footer, diff popup) is
+ * covered without each one having to remember.
+ */
+import { sanitizeForTerminal } from "../sanitize.js";
+import { spawnProcess } from "../runtime.js";
+export { sanitizeForTerminal };
+/**
+ * Parse `git status --porcelain=v1 -z --branch` output. The -z form is
+ * NUL-separated and never quotes paths, so filenames with spaces, quotes,
+ * tabs, or non-ASCII bytes arrive verbatim — no unquoting step to get wrong.
+ * Renames are `XY PATH\0ORIG_PATH\0` (PATH is already the destination).
+ */
+export function parsePorcelain(output) {
+    let branch = null;
+    const files = [];
+    const parts = output.split("\0");
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (!entry)
+            continue;
+        if (entry.startsWith("## ")) {
+            const info = entry.slice(3).trim();
+            // "main...origin/main [ahead 1]" → "main"; "HEAD (no branch)" → "HEAD"
+            const name = info.split("...")[0].split(" ")[0];
+            branch = name ? sanitizeForTerminal(name) : null;
+            continue;
+        }
+        if (entry.length < 3)
+            continue;
+        const rawStatus = entry.slice(0, 2);
+        const status = rawStatus.trim() || rawStatus;
+        files.push({ path: sanitizeForTerminal(entry.slice(3)), status });
+        // Rename/copy entries carry the origin path as the next NUL part.
+        if (status.includes("R") || status.includes("C"))
+            i++;
+    }
+    return { branch, files };
+}
+/**
+ * Parse `git diff --numstat -z` output into a path → line-count map.
+ *
+ * The -z form never quotes or abbreviates: a regular record is
+ * `ins\tdel\tpath\0`; a rename is `ins\tdel\t\0ORIG\0DEST\0` (the stats field
+ * ends at the tab, then the two paths follow as their own NUL fields, orig
+ * first). Keying on DEST matches porcelain -z's destination path, so the
+ * panel's +/- counts line up with the file list for every filename — CJK,
+ * spaces, quotes — instead of silently zeroing on a quoted/abbreviated key.
+ */
+export function parseNumstat(output) {
+    const map = new Map();
+    const parts = output.split("\0");
+    const statsPattern = /^(-|\d+)\t(-|\d+)\t(.*)$/;
+    for (let i = 0; i < parts.length; i++) {
+        const match = statsPattern.exec(parts[i]);
+        if (!match)
+            continue; // not a stats field (trailing NUL, stray part)
+        const insertions = match[1] === "-" ? 0 : parseInt(match[1], 10) || 0;
+        const deletions = match[2] === "-" ? 0 : parseInt(match[2], 10) || 0;
+        // Rename: the stats field ends at the tab and the next two NUL fields are
+        // ORIG then DEST — key on DEST (porcelain's destination path).
+        const rename = match[3] === "";
+        const path = rename ? parts[i + 2] : match[3];
+        if (rename)
+            i += 2;
+        if (!path)
+            continue;
+        const sanitized = sanitizeForTerminal(path);
+        const existing = map.get(sanitized) ?? { insertions: 0, deletions: 0 };
+        existing.insertions += insertions;
+        existing.deletions += deletions;
+        map.set(sanitized, existing);
+    }
+    return map;
+}
+/** Combine porcelain + staged/unstaged numstat into the panel model. */
+export function mergeGitStatus(porcelain, unstaged, staged) {
+    const files = porcelain.files.map(({ path, status }) => {
+        const a = unstaged.get(path);
+        const b = staged.get(path);
+        const insertions = (a?.insertions ?? 0) + (b?.insertions ?? 0);
+        const deletions = (a?.deletions ?? 0) + (b?.deletions ?? 0);
+        return { path, status, insertions, deletions };
+    });
+    return {
+        isRepo: true,
+        branch: porcelain.branch,
+        files,
+        totalInsertions: files.reduce((sum, f) => sum + f.insertions, 0),
+        totalDeletions: files.reduce((sum, f) => sum + f.deletions, 0),
+    };
+}
+/**
+ * Hard cap on any single git output held in memory. The diff popup only ever
+ * shows MAX_DIFF_CHARS, but the collector used to buffer the child's entire
+ * stdout first — a huge tracked file would balloon memory before truncation.
+ * Past the cap the stream keeps draining (discarding) so the child still
+ * exits cleanly instead of dying on a broken pipe.
+ */
+const MAX_GIT_OUTPUT_CHARS = 512 * 1024;
+async function gitOutput(workspace, args, signal, okExitCodes) {
+    try {
+        const proc = spawnProcess(["git", "-C", workspace, ...args], { stdout: "pipe", stderr: "ignore", stdin: "ignore" });
+        const onAbort = () => { try {
+            proc.kill();
+        }
+        catch { /* gone */ } };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const reader = proc.stdout.getReader();
+            const decoder = new TextDecoder();
+            let text = "";
+            let capped = false;
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (!capped) {
+                    text += decoder.decode(value, { stream: true });
+                    if (text.length > MAX_GIT_OUTPUT_CHARS)
+                        capped = true;
+                }
+                // Past the cap: drain and discard.
+            }
+            // Flush any incomplete multibyte sequence buffered by the streaming decoder.
+            if (!capped)
+                text += decoder.decode();
+            const code = await proc.exited;
+            return okExitCodes.includes(code) ? text : null;
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+async function git(workspace, args, signal) {
+    return gitOutput(workspace, args, signal, [0]);
+}
+/** Collect the current git status; never throws. */
+export async function collectGitStatus(workspace, signal) {
+    const porcelainText = await git(workspace, ["status", "--porcelain=v1", "-z", "--branch"], signal);
+    if (porcelainText === null)
+        return { ...EMPTY_GIT_STATUS, files: [] };
+    const porcelain = parsePorcelain(porcelainText);
+    const [unstagedText, stagedText] = await Promise.all([
+        git(workspace, ["diff", "--numstat", "-z"], signal),
+        git(workspace, ["diff", "--cached", "--numstat", "-z"], signal),
+    ]);
+    return mergeGitStatus(porcelain, parseNumstat(unstagedText ?? ""), parseNumstat(stagedText ?? ""));
+}
+export const MAX_DIFF_LINES = 5000;
+export const MAX_DIFF_CHARS = 256 * 1024;
+/** Cut the diff to the char/line budget, reporting whether anything was lost. */
+export function truncateDiff(text) {
+    // Diff bodies embed file content from an untrusted repo — strip terminal
+    // sequences before the text reaches the popup renderer.
+    let out = sanitizeForTerminal(text);
+    let truncated = false;
+    if (out.length > MAX_DIFF_CHARS) {
+        // Code-point-safe cut: a trailing high surrogate would render as a lone
+        // replacement character (mojibake) at the end of the popup.
+        let end = MAX_DIFF_CHARS;
+        if (end < out.length) {
+            const prev = out.charCodeAt(end - 1);
+            if (prev >= 0xd800 && prev <= 0xdbff)
+                end -= 1;
+        }
+        out = out.slice(0, end);
+        truncated = true;
+    }
+    const lines = out.split("\n");
+    if (lines.length > MAX_DIFF_LINES) {
+        out = lines.slice(0, MAX_DIFF_LINES).join("\n");
+        truncated = true;
+    }
+    return { text: out, truncated };
+}
+/**
+ * Unified diff for one working-tree file. Tracked files diff against HEAD
+ * (staged + unstaged); when there is no HEAD yet (fresh `git init`) the
+ * index/worktree pair is diffed instead, so staged edits still show.
+ * Untracked files diff against /dev/null, where git exits 1 even on success.
+ *
+ * Porcelain paths are relative to the repository root, so the diff runs from
+ * the root too — otherwise a workspace that is a subdirectory of the repo
+ * resolves the pathspec against the wrong prefix and produces nothing.
+ * Returns an empty text when git cannot produce a diff.
+ */
+export async function collectFileDiff(workspace, file, signal) {
+    const root = (await gitOutput(workspace, ["rev-parse", "--show-toplevel"], signal, [0]))?.trim() || workspace;
+    if (file.status === "??") {
+        const text = await gitOutput(root, ["diff", "--no-index", "--", "/dev/null", file.path], signal, [0, 1]);
+        return truncateDiff(text ?? "");
+    }
+    let text = await gitOutput(root, ["diff", "HEAD", "--", file.path], signal, [0]);
+    if (text === null) {
+        // No HEAD commits yet: staged (index vs empty tree) + unstaged (worktree vs index).
+        const [staged, unstaged] = await Promise.all([
+            gitOutput(root, ["diff", "--cached", "--", file.path], signal, [0]),
+            gitOutput(root, ["diff", "--", file.path], signal, [0]),
+        ]);
+        text = [staged, unstaged].filter((part) => part !== null && part.trim().length > 0).join("\n");
+    }
+    return truncateDiff(text);
+}

package/dist/headless.d.ts

@@ -0,0 +1,72 @@
+import type { IntegrationClient } from "./protocol/client.js";
+import type { AgentUsage } from "./protocol/types.js";
+import type { ToolRegistry } from "./tools/registry.js";
+import { SessionIndex } from "./agent/sessions.js";
+import { type ApprovalMode } from "./approval/policy.js";
+import type { AgentMode } from "./agent/modes.js";
+export type OutputFormat = "text" | "json" | "stream-json";
+export interface HeadlessOptions {
+    client: IntegrationClient;
+    registry: ToolRegistry;
+    sessionIndex: SessionIndex;
+    workspace: string;
+    allowOutside: boolean;
+    skillDirs: string[];
+    mode: AgentMode;
+    approval: ApprovalMode;
+    /** Client-choice model for a new thread (resumed threads keep their model). */
+    model?: string;
+    thinkingLevel?: string;
+    extraInstructions?: string;
+    noContextFiles?: boolean;
+    resumeThreadId?: string;
+    prompt: string;
+    outputFormat: OutputFormat;
+    quiet?: boolean;
+    /** Print only the final assistant message (prompt mode). */
+    lastMessageOnly?: boolean;
+    /** Abort the run after this many ms (headless only). */
+    timeoutMs?: number;
+}
+/** The single JSON object `--output-format json` emits — success and failure
+ *  alike, so a CI parser always gets a parseable object. */
+export interface HeadlessResult {
+    thread_id: string | null;
+    model: string | null;
+    text: string;
+    usage: AgentUsage | null;
+    error: string | null;
+    error_code: string | null;
+}
+/** Failure shape for pre-run errors (config/connection/usage) — same object
+ *  as a failed run, so `--output-format json` never emits non-JSON. */
+export declare function failureResult(message: string, code?: string): string;
+/** Terminal stream-json event for a pre-run failure (same shape as a failed
+ *  run's `done`). */
+export declare function failureDoneEvent(message: string, code?: string): string;
+/**
+ * First-error lock for a headless run: text and code are captured together,
+ * so a later notice's code can never pair with an earlier notice's text (two
+ * independent `??=` would let a null code be overwritten while the text stays
+ * locked to the first error).
+ */
+export declare class ErrorNotice {
+    text: string | null;
+    code: string | null;
+    /** Record the first error only; later calls are ignored. */
+    record(text: string, code?: string): void;
+}
+/**
+ * Tracks the last assistant message across a run. AG-UI text deltas carry a
+ * messageId per assistant message; a new id starts a new message. The last
+ * message that received any text wins — an empty final message (the agent
+ * ended on a tool call) falls back to the last one with text.
+ */
+export declare class FinalMessageTracker {
+    private currentId;
+    private current;
+    private last;
+    push(delta: string, messageId?: string): void;
+    get text(): string;
+}
+export declare function runHeadless(opts: HeadlessOptions): Promise<number>;

package/dist/headless.js

@@ -0,0 +1,330 @@
+// ---------------------------------------------------------------------------
+// Non-interactive mode (`myagent -p`, `run`, `--prompt`, piped stdin).
+//
+// Same runner as the TUI, different renderer:
+//   text        — assistant text to stdout, tool activity to stderr
+//   json        — one JSON object at the end (always parseable, failures too)
+//   stream-json — JSONL events as they happen (for scripting/GUI wrappers)
+//
+// Prompt mode (`--prompt`) additionally prints only the FINAL assistant
+// message, bounds the run with `--timeout`, and stops the remote run
+// gracefully on SIGINT/SIGTERM (CI cancellation).
+// ---------------------------------------------------------------------------
+import { AgentRunner, usageFromSession } from "./agent/turn.js";
+import { createSystemPromptBuilder } from "./agent/prompt-builder.js";
+import { deriveTitle } from "./agent/sessions.js";
+import { TodoStore } from "./agent/todo.js";
+import { ApprovalPolicy } from "./approval/policy.js";
+import { style } from "./ui/colors.js";
+import { sanitizeForTerminal } from "./sanitize.js";
+/** Grace period after a stop is initiated before the process force-exits —
+ *  the runner's post-run refresh has no timeout of its own. */
+const STOP_GRACE_MS = 10_000;
+/**
+ * Programmatic output contract for `--prompt` (CI) mode. The server no longer
+ * injects one for integration sessions — phrasing is the client's call, and
+ * this is the CLI's: the final message is the only thing CI reads, so it must
+ * be the answer, not a narration of how the agent got there. Sent every turn
+ * (the runner's system block is per-request); identical text is a no-op
+ * server-side, so the prompt cache holds.
+ */
+const FINAL_ANSWER_INSTRUCTION = "Your response will be consumed programmatically. Respond with the final answer only. " +
+    "Do not describe your internal tool usage or reasoning process unless the user explicitly asks for it.";
+/** Failure shape for pre-run errors (config/connection/usage) — same object
+ *  as a failed run, so `--output-format json` never emits non-JSON. */
+export function failureResult(message, code) {
+    return JSON.stringify({
+        thread_id: null,
+        model: null,
+        text: "",
+        usage: null,
+        error: message,
+        error_code: code ?? null,
+    });
+}
+/** Terminal stream-json event for a pre-run failure (same shape as a failed
+ *  run's `done`). */
+export function failureDoneEvent(message, code) {
+    return JSON.stringify({
+        type: "done",
+        thread_id: null,
+        error: message,
+        ...(code ? { error_code: code } : {}),
+    });
+}
+/**
+ * First-error lock for a headless run: text and code are captured together,
+ * so a later notice's code can never pair with an earlier notice's text (two
+ * independent `??=` would let a null code be overwritten while the text stays
+ * locked to the first error).
+ */
+export class ErrorNotice {
+    text = null;
+    code = null;
+    /** Record the first error only; later calls are ignored. */
+    record(text, code) {
+        if (this.text !== null)
+            return;
+        this.text = text;
+        this.code = code ?? null;
+    }
+}
+/**
+ * Tracks the last assistant message across a run. AG-UI text deltas carry a
+ * messageId per assistant message; a new id starts a new message. The last
+ * message that received any text wins — an empty final message (the agent
+ * ended on a tool call) falls back to the last one with text.
+ */
+export class FinalMessageTracker {
+    currentId;
+    current = "";
+    last = "";
+    push(delta, messageId) {
+        if (messageId !== this.currentId) {
+            if (this.current)
+                this.last = this.current;
+            this.current = "";
+            this.currentId = messageId;
+        }
+        this.current += delta;
+    }
+    get text() {
+        return this.current || this.last;
+    }
+}
+/**
+ * Timeout + signal control for a headless run. Both funnel into one stop
+ * path: abort the stream, stop the remote run, and arm a hard-exit grace so
+ * a wedged post-run refresh can never hang CI.
+ */
+function createStopControl(runner, timeoutMs) {
+    let timedOut = false;
+    let signalCode = null;
+    let stopping = false;
+    let hardExit = null;
+    const beginStop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void runner.stop().catch(() => { });
+        hardExit = setTimeout(() => process.exit(signalCode ?? 1), STOP_GRACE_MS);
+        hardExit.unref?.();
+    };
+    const onSignal = (signal) => {
+        signalCode = signal === "SIGINT" ? 130 : 143;
+        // A second signal means "stop waiting" — exit immediately.
+        if (stopping)
+            process.exit(signalCode);
+        beginStop();
+    };
+    const onSigint = () => onSignal("SIGINT");
+    const onSigterm = () => onSignal("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    const timer = timeoutMs
+        ? setTimeout(() => {
+            // The run may have finished in the same tick the timer fired, and a
+            // signal-initiated stop owns the outcome — only a live run that no
+            // one is already stopping is a timeout.
+            if (stopping || runner.state === "idle")
+                return;
+            timedOut = true;
+            beginStop();
+        }, timeoutMs)
+        : null;
+    timer?.unref?.();
+    return {
+        get timedOut() {
+            return timedOut;
+        },
+        get signalCode() {
+            return signalCode;
+        },
+        dispose() {
+            if (timer)
+                clearTimeout(timer);
+            if (hardExit)
+                clearTimeout(hardExit);
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+        },
+    };
+}
+export async function runHeadless(opts) {
+    const todos = new TodoStore();
+    const streamJson = opts.outputFormat === "stream-json";
+    const json = opts.outputFormat === "json";
+    const tracker = new FinalMessageTracker();
+    let assistantText = "";
+    let usage = null;
+    const firstError = new ErrorNotice();
+    let titleUpdate = Promise.resolve();
+    const emitJson = (event) => {
+        process.stdout.write(JSON.stringify(event) + "\n");
+    };
+    const notice = (text, level, code) => {
+        if (level === "error")
+            firstError.record(text, code);
+        if (streamJson)
+            emitJson({ type: "notice", level, text, ...(code ? { code } : {}) });
+        else if (!json && !opts.quiet) {
+            process.stderr.write(style.dim(`${level === "error" ? "error: " : ""}${sanitizeForTerminal(text)}\n`));
+        }
+    };
+    const buildSystemPrompt = createSystemPromptBuilder({
+        workspace: opts.workspace,
+        skillDirs: opts.skillDirs,
+        noContextFiles: opts.noContextFiles,
+        extraInstructions: [
+            opts.extraInstructions,
+            opts.lastMessageOnly ? FINAL_ANSWER_INSTRUCTION : undefined,
+        ].filter(Boolean).join("\n\n") || undefined,
+    });
+    const runner = new AgentRunner({
+        client: opts.client,
+        registry: opts.registry,
+        workspace: opts.workspace,
+        allowOutside: opts.allowOutside,
+        skillDirs: opts.skillDirs,
+        todos,
+        // No one is present to answer an approval prompt, so `--ask` denies every
+        // mutating tool — say so instead of claiming the user declined.
+        approval: new ApprovalPolicy(opts.approval, async () => "denied", () => opts.mode, "Error: mutating tools are denied — no user is present to approve them in non-interactive mode. Re-run interactively or use --auto."),
+        buildSystemPrompt,
+        callbacks: {
+            onUserMessage: (text, queued) => {
+                if (streamJson)
+                    emitJson({ type: "user", text, queued });
+            },
+            // Steers float in the TUI; headless just reports the attempt on the
+            // stream-json line (same event the old queued user message produced).
+            onSteerQueued: (text) => {
+                if (streamJson)
+                    emitJson({ type: "user", text, queued: true });
+            },
+            onContent: (delta, messageId) => {
+                assistantText += delta;
+                tracker.push(delta, messageId);
+                if (streamJson)
+                    emitJson({ type: "content", delta });
+                // Assistant text can echo untrusted content (a prompt-injected model,
+                // a file body it read) — strip terminal escapes before the user's
+                // real terminal sees them. Per-delta is safe: a sequence split across
+                // deltas degrades to harmless literal text, never a live escape.
+                else if (!json && !opts.lastMessageOnly)
+                    process.stdout.write(sanitizeForTerminal(delta));
+            },
+            onReasoning: (delta) => {
+                if (streamJson)
+                    emitJson({ type: "reasoning", delta });
+            },
+            onUsage: (u) => {
+                usage = u;
+                if (streamJson)
+                    emitJson({ type: "usage", usage: u });
+            },
+            onServerTool: (tool) => {
+                if (streamJson)
+                    emitJson({ type: "server_tool", tool });
+                else if (!json && !opts.quiet) {
+                    process.stderr.write(style.dim(`  ⚙ ${sanitizeForTerminal(tool.name)} (server · ${tool.phase})\n`));
+                }
+            },
+            onToolStart: (call, summary) => {
+                if (streamJson)
+                    emitJson({ type: "tool_start", id: call.id, name: call.name, summary });
+                else if (!json && !opts.quiet) {
+                    process.stderr.write(style.dim(`  ⚙ ${sanitizeForTerminal(call.name)}: ${sanitizeForTerminal(summary)}\n`));
+                }
+            },
+            onToolEnd: (call, output, isError) => {
+                if (streamJson)
+                    emitJson({ type: "tool_end", id: call.id, name: call.name, isError, output: truncate(output) });
+                else if (!json && !opts.quiet && isError) {
+                    process.stderr.write(style.red(`  ✗ ${sanitizeForTerminal(firstLine(output))}\n`));
+                }
+            },
+            onNotice: notice,
+            onRunState: (state) => {
+                if (streamJson)
+                    emitJson({ type: "run_state", state });
+            },
+            onThread: (threadId) => {
+                opts.sessionIndex.remember(opts.workspace, threadId, deriveTitle(opts.prompt));
+                // Best-effort remote title update — tracked so the await below keeps
+                // process exit from cutting the request off when onThread fires late
+                // in a run. Bounded: a hung server must not hang the exit.
+                titleUpdate = opts.client
+                    .patchSessionTitle(threadId, deriveTitle(opts.prompt), { signal: AbortSignal.timeout(5_000) })
+                    .catch(() => { });
+                if (streamJson)
+                    emitJson({ type: "thread", threadId });
+            },
+            onSession: (detail) => {
+                if (detail.model)
+                    runner.model = detail.model;
+                const mapped = usageFromSession(detail.usage);
+                if (mapped)
+                    usage = mapped;
+            },
+        },
+    });
+    runner.mode = opts.mode;
+    runner.thinkingLevel = opts.thinkingLevel;
+    runner.setModel(opts.model ?? null);
+    runner.threadId = opts.resumeThreadId ?? null;
+    const stop = createStopControl(runner, opts.timeoutMs);
+    try {
+        await runner.send(opts.prompt);
+        // Deliver any queued follow-up turn before reporting — process exit must
+        // not cut it off.
+        await runner.waitForIdle();
+        // Same for the best-effort title update latched by onThread above.
+        await titleUpdate;
+    }
+    finally {
+        stop.dispose();
+    }
+    if (stop.timedOut)
+        firstError.record(`Timed out after ${(opts.timeoutMs ?? 0) / 1000}s`, "timeout");
+    if (stop.signalCode !== null)
+        firstError.record("Run cancelled by signal", "cancelled");
+    const finalText = opts.lastMessageOnly ? tracker.text : assistantText;
+    if (!streamJson && !json) {
+        if (opts.lastMessageOnly) {
+            // Whole-message sanitize (not per delta): the final text is written in
+            // one go, so a sequence split across deltas is still stripped.
+            const safeFinal = sanitizeForTerminal(finalText);
+            if (safeFinal)
+                process.stdout.write(safeFinal.endsWith("\n") ? safeFinal : `${safeFinal}\n`);
+        }
+        else if (!assistantText.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+    }
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            thread_id: runner.threadId,
+            model: runner.model,
+            text: finalText,
+            usage,
+            error: firstError.text,
+            error_code: firstError.code,
+        }) + "\n");
+    }
+    else if (streamJson) {
+        emitJson({
+            type: "done",
+            thread_id: runner.threadId,
+            error: firstError.text,
+            ...(firstError.code ? { error_code: firstError.code } : {}),
+        });
+    }
+    return stop.signalCode ?? (firstError.text ? 1 : 0);
+}
+function truncate(text) {
+    return text.length > 2000 ? `${text.slice(0, 2000)}…` : text;
+}
+function firstLine(text) {
+    return text.split("\n")[0] ?? "";
+}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { type StoredConfig } from "./config.js";
+import { type AgentMode } from "./agent/modes.js";
+import { type OutputFormat } from "./headless.js";
+interface Args {
+    command: "chat" | "run" | "config" | "skills" | "sessions" | "help" | "version";
+    configSub?: string;
+    flags: Partial<StoredConfig> & {
+        continue?: boolean;
+        resume?: boolean;
+        session?: string;
+        mode?: AgentMode;
+        ask?: boolean;
+        auto?: boolean;
+        model?: string;
+        thinking?: string;
+        allowOutside?: boolean;
+        noContextFiles?: boolean;
+        noLogo?: boolean;
+        quiet?: boolean;
+        outputFormat?: OutputFormat;
+        workspace?: string;
+        prompt?: string;
+        timeout?: number;
+    };
+    skillsDirs: string[];
+    promptParts: string[];
+}
+export declare function parseArgs(argv: string[]): Args;
+/**
+ * Interactive means the TUI: a plain `chat` invocation with both streams on a
+ * TTY. `run`/`-p`, `--prompt`, `--output-format`, and piped stdin all mean
+ * headless.
+ */
+export declare function isInteractiveMode(args: Args, stdinIsTty: boolean, stdoutIsTty: boolean): boolean;
+/**
+ * Whether stdin should be read as prompt text. Piped stdin is a prompt for
+ * every headless path (`echo fix | myagent`); an inline `--prompt` never reads
+ * it (a CI stdin may be an open pipe — reading it would hang), while
+ * `--prompt -` reads it explicitly.
+ */
+export declare function shouldReadStdin(args: Args, interactive: boolean): boolean;
+/** Join the prompt sources: positional words, `--prompt` (or stdin), piped stdin. */
+export declare function assemblePrompt(args: Args, stdinText: string): string;
+/**
+ * Report a pre-run failure (usage/config/connection) in the requested output
+ * format and return the exit code. `json` always emits a parseable object — a
+ * CI parser must never see an empty stdout; `stream-json` emits a terminal
+ * `done` event; text goes to stderr.
+ */
+export declare function fail(format: OutputFormat | undefined, message: string, errorCode?: string): number;
+/**
+ * Read piped stdin as prompt text. Bounded by the run's `--timeout` when one
+ * is set: a non-TTY stdin that never closes (a CI misconfiguration like
+ * `docker run -i` without `< /dev/null`) would otherwise hang before the
+ * run's own timeout control is even created. Returns null on timeout so the
+ * caller can fail with a clear message instead of running an empty prompt.
+ */
+export declare function readStdin(timeoutMs?: number): Promise<string | null>;
+export {};