@geteigen/cli 0.0.0-stage → 3.0.0

package/dist/shared/backends/index.d.ts

@@ -0,0 +1,18 @@
+import type { AgentBackendKind, WorkerBackend } from "./types.js";
+import { ClaudeCodeBackend, claudeCodeBackend } from "./claudeCode.js";
+import { CodexBackend, codexBackend } from "./codex.js";
+export type { AgentBackendKind, BuildArgsOptions, CliSandboxBackendKind, NormalizedAgentEvent, ParseLineContext, RunGitInfo, RunUsage, WorkerBackend, } from "./types.js";
+export { EMPTY_RUN_USAGE, addRunUsage, runUsageCostUsd } from "./usage.js";
+export { CLI_SANDBOX_BACKENDS, backendShortLabel, isCliSandboxBackend, parseAgentBackendKind, } from "./types.js";
+export { CursorAgentBackend, cursorAgentBackend, extractThinkingText, isEditTool, mergeAssistantText, mergeThinkingText, normalizeThinkingText, diffFromToolArgs, diffFromToolResult, diffFromToolEvent, formatToolResultDetail, formatToolTranscript, mergeToolStartAndResult, unwrapToolResultPayload, } from "./cursor.js";
+export { ClaudeCodeBackend, claudeCodeBackend };
+export { CodexBackend, codexBackend };
+export { OpencodeBackend, opencodeBackend, opencodeToolName } from "./opencode.js";
+/**
+ * Return a backend suitable for one agent run.
+ * Claude Code parsers are stateful (pending tool_use ids), so each call
+ * for `claude-code` returns a fresh instance.
+ */
+export declare function getBackend(kind: AgentBackendKind): WorkerBackend;
+export declare function listBackends(): WorkerBackend[];
+export declare function isBackendAvailable(kind: AgentBackendKind): boolean;

package/dist/shared/backends/index.js

@@ -0,0 +1,58 @@
+import { cursorAgentBackend } from "./cursor.js";
+import { ClaudeCodeBackend, claudeCodeBackend } from "./claudeCode.js";
+import { CodexBackend, codexBackend } from "./codex.js";
+import { OpencodeBackend, opencodeBackend } from "./opencode.js";
+import { cursorStreamLineIntegration } from "../toolIntegration.js";
+export { EMPTY_RUN_USAGE, addRunUsage, runUsageCostUsd } from "./usage.js";
+export { CLI_SANDBOX_BACKENDS, backendShortLabel, isCliSandboxBackend, parseAgentBackendKind, } from "./types.js";
+export { CursorAgentBackend, cursorAgentBackend, extractThinkingText, isEditTool, mergeAssistantText, mergeThinkingText, normalizeThinkingText, diffFromToolArgs, diffFromToolResult, diffFromToolEvent, formatToolResultDetail, formatToolTranscript, mergeToolStartAndResult, unwrapToolResultPayload, } from "./cursor.js";
+export { ClaudeCodeBackend, claudeCodeBackend };
+export { CodexBackend, codexBackend };
+export { OpencodeBackend, opencodeBackend, opencodeToolName } from "./opencode.js";
+/**
+ * Cursor parser + MCP integration tags. Tagging lives here, not in cursor.ts,
+ * because the web bundle imports cursor.ts and can't follow its runtime
+ * `.js` imports.
+ */
+const taggedCursorBackend = {
+    kind: cursorAgentBackend.kind,
+    available: cursorAgentBackend.available,
+    command: cursorAgentBackend.command,
+    buildArgs: (opts) => cursorAgentBackend.buildArgs(opts),
+    parseLine(json, ctx) {
+        const events = cursorAgentBackend.parseLine(json, ctx);
+        const integration = cursorStreamLineIntegration(json);
+        if (!integration)
+            return events;
+        return events.map((event) => event.kind === "tool_start" || event.kind === "tool_done"
+            ? { ...event, integration }
+            : event);
+    },
+};
+/** Singletons for availability checks / UI. Cursor is stateless; Claude is not. */
+const prototypes = {
+    cursor: taggedCursorBackend,
+    "claude-code": claudeCodeBackend,
+    codex: codexBackend,
+    opencode: opencodeBackend,
+};
+/**
+ * Return a backend suitable for one agent run.
+ * Claude Code parsers are stateful (pending tool_use ids), so each call
+ * for `claude-code` returns a fresh instance.
+ */
+export function getBackend(kind) {
+    if (kind === "claude-code")
+        return new ClaudeCodeBackend();
+    if (kind === "codex")
+        return new CodexBackend();
+    if (kind === "opencode")
+        return new OpencodeBackend();
+    return prototypes[kind] ?? taggedCursorBackend;
+}
+export function listBackends() {
+    return Object.values(prototypes);
+}
+export function isBackendAvailable(kind) {
+    return Boolean(prototypes[kind]?.available);
+}

package/dist/shared/backends/opencode.d.ts

@@ -0,0 +1,40 @@
+import type { BuildArgsOptions, NormalizedAgentEvent, ParseLineContext, WorkerBackend } from "./types.js";
+/** Map OpenCode's lowercase built-ins to the names the chat UI renders. */
+export declare function opencodeToolName(raw: string): string;
+/**
+ * OpenCode CLI headless backend.
+ * Spawns: `opencode run --format json --thinking …`
+ *
+ * Emits one NDJSON object per line with a `part` payload. Text/reasoning can
+ * arrive as either full part snapshots (`text`, `reasoning`) or incremental
+ * `part_delta` events depending on the CLI version, so both are handled and
+ * de-duplicated per part id. Tool calls arrive once, already completed.
+ */
+export declare class OpencodeBackend implements WorkerBackend {
+    readonly kind: "opencode";
+    readonly available = true;
+    readonly command = "opencode";
+    private sessionEmitted;
+    private usage;
+    private textSent;
+    private thinkingSent;
+    private startedTools;
+    private doneTools;
+    private anonSeq;
+    /**
+     * A `stop` step-finish can belong to the compaction summary, after which the
+     * same turn continues. Hold it until the stream goes quiet (flush) instead of
+     * ending the reply as soon as it arrives.
+     */
+    private pendingDone;
+    /** A held `done` was flushed; clear the terminal flag if the turn resumes. */
+    private deferredTerminal;
+    buildArgs(opts: BuildArgsOptions): string[];
+    /** OpenCode takes MCP servers through its merged config, not a CLI flag. */
+    buildEnv(opts: BuildArgsOptions): Record<string, string>;
+    private appendText;
+    private parseTool;
+    parseLine(json: unknown, ctx?: ParseLineContext): NormalizedAgentEvent[];
+    flush(ctx?: ParseLineContext): NormalizedAgentEvent[];
+}
+export declare const opencodeBackend: OpencodeBackend;

package/dist/shared/backends/opencode.js

@@ -0,0 +1,397 @@
+import { opencodeToolIntegration } from "../toolIntegration.js";
+import { formatToolResultDetail, todosFromToolArgs, todoStatusSummary, } from "./cursor.js";
+import { stringifyUnknown } from "../stringifyUnknown.js";
+const TOOL_NAMES = {
+    bash: "Bash",
+    shell: "Bash",
+    read: "Read",
+    write: "Write",
+    edit: "Edit",
+    multiedit: "Edit",
+    patch: "Edit",
+    apply_patch: "Edit",
+    list: "List",
+    ls: "List",
+    glob: "Glob",
+    grep: "Grep",
+    webfetch: "WebFetch",
+    websearch: "WebSearch",
+    task: "Task",
+    todowrite: "todo",
+    todoread: "todo",
+    skill: "Skill",
+};
+/** Map OpenCode's lowercase built-ins to the names the chat UI renders. */
+export function opencodeToolName(raw) {
+    const name = raw.trim();
+    if (!name)
+        return "Tool";
+    return TOOL_NAMES[name.toLowerCase()] || name;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function textField(value) {
+    return typeof value === "string" ? value : "";
+}
+function toolPath(args) {
+    if (!args)
+        return undefined;
+    for (const key of ["filePath", "file_path", "path", "targetFile", "target_file"]) {
+        const value = args[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function toolDetail(name, args, path, title) {
+    if (title.trim())
+        return title.trim();
+    if (args) {
+        const command = typeof args.command === "string"
+            ? args.command
+            : typeof args.pattern === "string"
+                ? args.pattern
+                : typeof args.glob === "string"
+                    ? args.glob
+                    : typeof args.query === "string"
+                        ? args.query
+                        : typeof args.url === "string"
+                            ? args.url
+                            : undefined;
+        if (command)
+            return command;
+    }
+    if (path)
+        return path;
+    if (args) {
+        try {
+            return JSON.stringify(args).slice(0, 120);
+        }
+        catch {
+            // fall through
+        }
+    }
+    return name;
+}
+function toolError(state) {
+    const error = state.error;
+    if (typeof error === "string" && error.trim())
+        return error.trim();
+    const rec = asRecord(error);
+    if (rec) {
+        const data = asRecord(rec.data);
+        const message = textField(rec.message) ||
+            textField(data?.message) ||
+            textField(rec.data);
+        if (message.trim())
+            return message.trim();
+    }
+    return "";
+}
+function resultText(state) {
+    const error = toolError(state);
+    if (error)
+        return error;
+    const output = state.output;
+    if (typeof output === "string")
+        return output;
+    if (output !== undefined)
+        return stringifyUnknown(output);
+    return "";
+}
+function stepUsage(part) {
+    const tokens = asRecord(part.tokens);
+    const cost = Number(part.cost);
+    if (!tokens && !Number.isFinite(cost))
+        return {};
+    const cache = asRecord(tokens?.cache);
+    const n = (value) => {
+        const num = typeof value === "number" ? value : Number(value);
+        return Number.isFinite(num) && num > 0 ? num : 0;
+    };
+    return {
+        usage: {
+            inputTokens: n(tokens?.input),
+            outputTokens: n(tokens?.output),
+            cacheReadTokens: n(cache?.read),
+            cacheWriteTokens: n(cache?.write),
+            ...(Number.isFinite(cost) && cost > 0 ? { costUsd: cost } : {}),
+        },
+    };
+}
+/**
+ * OpenCode CLI headless backend.
+ * Spawns: `opencode run --format json --thinking …`
+ *
+ * Emits one NDJSON object per line with a `part` payload. Text/reasoning can
+ * arrive as either full part snapshots (`text`, `reasoning`) or incremental
+ * `part_delta` events depending on the CLI version, so both are handled and
+ * de-duplicated per part id. Tool calls arrive once, already completed.
+ */
+export class OpencodeBackend {
+    kind = "opencode";
+    available = true;
+    command = "opencode";
+    sessionEmitted = false;
+    usage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        costUsd: 0,
+    };
+    textSent = new Map();
+    thinkingSent = new Map();
+    startedTools = new Set();
+    doneTools = new Set();
+    anonSeq = 0;
+    /**
+     * A `stop` step-finish can belong to the compaction summary, after which the
+     * same turn continues. Hold it until the stream goes quiet (flush) instead of
+     * ending the reply as soon as it arrives.
+     */
+    pendingDone = null;
+    /** A held `done` was flushed; clear the terminal flag if the turn resumes. */
+    deferredTerminal = false;
+    buildArgs(opts) {
+        const args = ["run", "--format", "json", "--thinking"];
+        if (opts.mode === "plan") {
+            args.push("--agent", "plan");
+        }
+        else {
+            args.push("--auto");
+        }
+        if (opts.modelId && opts.modelId !== "auto") {
+            args.push("--model", opts.modelId);
+        }
+        if (opts.sessionId) {
+            args.push("--session", opts.sessionId);
+        }
+        args.push("--", opts.prompt);
+        return args;
+    }
+    /** OpenCode takes MCP servers through its merged config, not a CLI flag. */
+    buildEnv(opts) {
+        const servers = opts.mcpServers;
+        if (!servers || !Object.keys(servers).length)
+            return {};
+        const mcp = {};
+        for (const [name, server] of Object.entries(servers)) {
+            mcp[name] = {
+                type: "remote",
+                url: server.url,
+                headers: server.headers,
+                enabled: true,
+            };
+        }
+        return {
+            OPENCODE_CONFIG_CONTENT: JSON.stringify({
+                $schema: "https://opencode.ai/config.json",
+                mcp,
+            }),
+        };
+    }
+    appendText(ctx, partId, incoming, kind, full) {
+        const sentMap = kind === "text" ? this.textSent : this.thinkingSent;
+        const buffer = kind === "text" ? ctx.assistantBuf : (ctx.thinkingBuf ??= { value: "" });
+        const already = sentMap.get(partId) || "";
+        let chunk = "";
+        if (!incoming)
+            return "";
+        if (full) {
+            if (incoming.startsWith(already))
+                chunk = incoming.slice(already.length);
+            else if (already && already.startsWith(incoming))
+                chunk = "";
+            else
+                chunk = incoming;
+            sentMap.set(partId, incoming);
+        }
+        else {
+            chunk = incoming;
+            sentMap.set(partId, already + incoming);
+        }
+        if (!chunk)
+            return "";
+        // A new part (e.g. text after a tool step) starts its own paragraph.
+        if (!already && buffer.value && !/\s$/.test(buffer.value) && !/^\s/.test(chunk)) {
+            buffer.value += "\n\n";
+        }
+        buffer.value += chunk;
+        return buffer.value;
+    }
+    parseTool(ev, part, ctx) {
+        const out = [];
+        const rawName = textField(part.tool) || "tool";
+        const name = opencodeToolName(rawName);
+        const callId = textField(part.callID) ||
+            textField(part.id) ||
+            `opencode-tool-${(this.anonSeq += 1)}`;
+        const state = asRecord(part.state) || {};
+        const args = asRecord(state.input);
+        const path = toolPath(args);
+        const status = textField(state.status).toLowerCase();
+        const title = textField(state.title);
+        const detail = toolDetail(name, args, path, title);
+        const todos = todosFromToolArgs(args);
+        const integration = opencodeToolIntegration(rawName, args);
+        const error = toolError(state);
+        const done = status === "completed" || status === "error" || status === "failed";
+        if (!this.startedTools.has(callId)) {
+            this.startedTools.add(callId);
+            out.push({
+                kind: "tool_start",
+                callId,
+                name,
+                detail: todos.length > 0
+                    ? `${todos.length} todo${todos.length === 1 ? "" : "s"} · ${todoStatusSummary(todos)}`
+                    : detail,
+                ...(path ? { path } : {}),
+                ...(todos.length ? { todos } : {}),
+                ...(integration ? { integration } : {}),
+            });
+        }
+        if (done && !this.doneTools.has(callId)) {
+            this.doneTools.add(callId);
+            const result = resultText(state);
+            out.push({
+                kind: "tool_done",
+                callId,
+                name,
+                detail: todos.length > 0
+                    ? `${todos.length} todo${todos.length === 1 ? "" : "s"} · ${todoStatusSummary(todos)}`
+                    : formatToolResultDetail(name, args, result || (error ? "Failed" : "Done"), error ? "Failed" : "Done"),
+                ...(path ? { path } : {}),
+                ...(status !== "completed" ? { isError: true } : {}),
+                ...(todos.length ? { todos } : {}),
+                ...(integration ? { integration } : {}),
+            });
+        }
+        return out;
+    }
+    parseLine(json, ctx = {
+        assistantBuf: { value: "" },
+        gotTerminalEvent: { value: false },
+    }) {
+        if (!json || typeof json !== "object")
+            return [];
+        const ev = json;
+        const type = textField(ev.type);
+        const part = asRecord(ev.part);
+        const out = [];
+        const sessionId = textField(ev.sessionID) || textField(part?.sessionID);
+        if (sessionId && !this.sessionEmitted) {
+            this.sessionEmitted = true;
+            out.push({ kind: "session", sessionId });
+        }
+        // Any new step/output after a held `stop` means the turn continued (this is
+        // how OpenCode's compaction summary looks on the wire).
+        if (type === "step_start" ||
+            type === "part_delta" ||
+            type === "text" ||
+            type === "reasoning" ||
+            type === "tool_use") {
+            this.pendingDone = null;
+            if (this.deferredTerminal) {
+                this.deferredTerminal = false;
+                ctx.gotTerminalEvent.value = false;
+            }
+        }
+        if (type === "error") {
+            this.pendingDone = null;
+            this.deferredTerminal = false;
+            ctx.gotTerminalEvent.value = true;
+            const error = asRecord(ev.error);
+            const data = asRecord(error?.data);
+            const message = textField(data?.message) ||
+                textField(error?.message) ||
+                stringifyUnknown(error?.data ?? error) ||
+                textField(ev.message) ||
+                ctx.stderr ||
+                "OpenCode error";
+            out.push({ kind: "error", message });
+            return out;
+        }
+        if (type === "step_finish") {
+            if (part) {
+                const { usage } = stepUsage(part);
+                if (usage) {
+                    this.usage.inputTokens += usage.inputTokens;
+                    this.usage.outputTokens += usage.outputTokens;
+                    this.usage.cacheReadTokens += usage.cacheReadTokens;
+                    this.usage.cacheWriteTokens += usage.cacheWriteTokens;
+                    this.usage.costUsd += usage.costUsd ?? 0;
+                }
+                if (textField(part.reason) === "stop") {
+                    this.pendingDone = {
+                        kind: "done",
+                        result: ctx.assistantBuf.value,
+                        usage: {
+                            ...this.usage,
+                            ...(this.usage.costUsd > 0 ? { costUsd: this.usage.costUsd } : {}),
+                        },
+                    };
+                }
+                else {
+                    this.pendingDone = null;
+                }
+            }
+            return out;
+        }
+        if (type === "part_delta") {
+            const partId = textField(ev.partID) || textField(part?.id) || `delta-${(this.anonSeq += 1)}`;
+            const partType = textField(ev.partType) || textField(part?.type);
+            const delta = textField(ev.delta);
+            if (!delta || ctx.toolsOnly)
+                return out;
+            if (partType === "reasoning" || partType === "thinking") {
+                const full = this.appendText(ctx, partId, delta, "thinking", false);
+                if (full)
+                    out.push({ kind: "thinking_delta", text: full });
+            }
+            else {
+                const full = this.appendText(ctx, partId, delta, "text", false);
+                if (full)
+                    out.push({ kind: "assistant_delta", text: full });
+            }
+            return out;
+        }
+        if (type === "text" || type === "reasoning") {
+            if (!part || ctx.toolsOnly)
+                return out;
+            const partId = textField(part.id) || `part-${(this.anonSeq += 1)}`;
+            const text = textField(part.text);
+            if (!text)
+                return out;
+            if (type === "reasoning") {
+                const full = this.appendText(ctx, partId, text, "thinking", true);
+                if (full)
+                    out.push({ kind: "thinking_delta", text: full });
+            }
+            else {
+                const full = this.appendText(ctx, partId, text, "text", true);
+                if (full)
+                    out.push({ kind: "assistant_delta", text: full });
+            }
+            return out;
+        }
+        if (type === "tool_use" && part) {
+            return out.concat(this.parseTool(ev, part, ctx));
+        }
+        return out;
+    }
+    flush(ctx) {
+        const done = this.pendingDone;
+        if (!done)
+            return [];
+        this.pendingDone = null;
+        this.deferredTerminal = true;
+        if (ctx)
+            ctx.gotTerminalEvent.value = true;
+        return [done];
+    }
+}
+export const opencodeBackend = new OpencodeBackend();

package/dist/shared/backends/types.d.ts

@@ -0,0 +1,171 @@
+import type { AgentTodoItem, ClarifyingQuestion } from "../events.js";
+import type { ToolIntegrationRef } from "../toolIntegration.js";
+import type { CliCommandCatalog } from "../slashCommands.js";
+/** Backend kind for a room-level agent process. */
+export type AgentBackendKind = "cursor" | "claude-code" | "codex" | "opencode";
+/** Claude Code, Codex, and OpenCode share the local-CLI + Blaxel-sandbox path. */
+export declare const CLI_SANDBOX_BACKENDS: readonly ["claude-code", "codex", "opencode"];
+export type CliSandboxBackendKind = (typeof CLI_SANDBOX_BACKENDS)[number];
+export declare function isCliSandboxBackend(kind: string | null | undefined): kind is CliSandboxBackendKind;
+export declare function parseAgentBackendKind(raw: unknown): AgentBackendKind;
+export declare function backendShortLabel(kind: AgentBackendKind): string;
+/** Git / PR metadata attached to a completed cloud agent run. */
+export interface RunGitInfo {
+    branches: Array<{
+        repoUrl: string;
+        branch?: string;
+        prUrl?: string;
+    }>;
+}
+/** Token use (and cost, when the CLI reports it) for one finished turn. */
+export interface RunUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Reported by the CLI (Claude Code); absent when it has to be estimated. */
+    costUsd?: number;
+}
+export type { AgentTodoItem, ClarifyingQuestion };
+/**
+ * Normalized agent stream events used internally by Steer.
+ * Subagent events from within a single agent carry `subagent_nested`
+ * and a parent tool-call id — they do NOT create a new Agent row.
+ */
+export type NormalizedAgentEvent = {
+    kind: "session";
+    sessionId: string;
+} | {
+    kind: "assistant_delta";
+    text: string;
+} | {
+    kind: "assistant_final";
+    text: string;
+} | {
+    kind: "thinking_delta";
+    text: string;
+} | {
+    kind: "thinking_final";
+    text: string;
+} | {
+    kind: "tool_start";
+    callId: string;
+    name: string;
+    detail: string;
+    path?: string;
+    todos?: AgentTodoItem[];
+    questions?: ClarifyingQuestion[];
+    /** Set for MCP calls: which server / integration / tool ran. */
+    integration?: ToolIntegrationRef;
+} | {
+    kind: "tool_done";
+    callId: string;
+    name: string;
+    detail: string;
+    path?: string;
+    /** The tool failed / was rejected; `detail` carries the error. */
+    isError?: boolean;
+    diffPatch?: string;
+    todos?: AgentTodoItem[];
+    questions?: ClarifyingQuestion[];
+    /** Set for MCP calls: which server / integration / tool ran. */
+    integration?: ToolIntegrationRef;
+} | {
+    kind: "subagent_nested";
+    parentCallId: string;
+    callId: string;
+    name: string;
+    detail: string;
+    path?: string;
+    status: "started" | "completed";
+} | {
+    kind: "error";
+    message: string;
+}
+/**
+ * The agent's reply and tools are finished; the runner may still be doing
+ * post-run work (e.g. pushing the branch) before `done` arrives.
+ */
+ | {
+    kind: "turn_complete";
+    detail?: string;
+}
+/** Runner progress before/around the agent (e.g. "Starting sandbox…"); empty clears it. */
+ | {
+    kind: "status";
+    detail?: string;
+}
+/** Slash commands the CLI reported at startup (drives the composer menu). */
+ | {
+    kind: "cli_commands";
+    catalog: CliCommandCatalog;
+} | {
+    kind: "done";
+    result: string;
+    git?: RunGitInfo;
+    usage?: RunUsage;
+};
+export interface BuildArgsOptions {
+    prompt: string;
+    modelId: string;
+    sessionId?: string | null;
+    /** Cursor `--mode plan` / Claude `--permission-mode plan`. */
+    mode?: "agent" | "plan";
+    /** Working directory for Codex `--cd` (repo root in Blaxel). */
+    cwd?: string | null;
+    /** Streamable-HTTP MCP servers to attach for this invocation. */
+    mcpServers?: Record<string, {
+        type: "http";
+        url: string;
+        headers: Record<string, string>;
+    }>;
+}
+/**
+ * Abstraction over headless coding-agent CLIs.
+ * Implementations spawn the process and parse NDJSON into NormalizedAgentEvent.
+ */
+export interface WorkerBackend {
+    kind: AgentBackendKind;
+    /** False until the backend is fully wired and tested. */
+    available: boolean;
+    /** Executable name (`cursor`, `claude`, …). */
+    command: string;
+    buildArgs(opts: BuildArgsOptions): string[];
+    /** Extra env for this invocation (e.g. OpenCode inline MCP config). */
+    buildEnv?(opts: BuildArgsOptions): Record<string, string>;
+    /**
+     * Parse one JSON object from a stream-json line into zero or more
+     * normalized events. Stateful parsers may hold buffers on the instance;
+     * callers that need isolation should create a fresh backend per run.
+     */
+    parseLine(json: unknown, ctx?: ParseLineContext): NormalizedAgentEvent[];
+    /**
+     * Emit a terminal event the parser is holding back. OpenCode reports a
+     * `stop` on the step that *triggers* compaction too, so its `done` is
+     * deferred until the stream stays quiet (a new step cancels it) or the
+     * process exits. Call periodically and once on process close.
+     */
+    flush?(ctx?: ParseLineContext): NormalizedAgentEvent[];
+}
+export interface ParseLineContext {
+    /** Accumulated assistant text so far (mutated by the parser). */
+    assistantBuf: {
+        value: string;
+    };
+    /** Accumulated model thinking / reasoning for the current turn. */
+    thinkingBuf?: {
+        value: string;
+    };
+    /** Set true when a terminal result/done/error event is emitted. */
+    gotTerminalEvent: {
+        value: boolean;
+    };
+    /** Optional stderr buffer used for error messages. */
+    stderr?: string;
+    /**
+     * When true, only emit tool/session events (no assistant text / done / error).
+     * Used to re-parse Blaxel process stdout after streamLogs may have missed
+     * mid-run tool lines while still delivering the terminal result.
+     */
+    toolsOnly?: boolean;
+}