eve/dist/src/cli/dev/tui/runner.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import { type AgentInfoResult, type ConnectionAuthorizationOutcome, type InputRequest, Client, ClientSession } from "#client/index.js";
import { type DevBootProgressReporter } from "#internal/dev-boot-progress.js";
import { type PromptCommand } from "./prompt-commands.js";
import { type BootDetection } from "./setup-issues.js";
import type { SetupFlowRenderer } from "./setup-flow.js";
import type { AssistantResponseStatsMode, LogDisplayMode, TerminalPartDisplayMode, TuiDisplayOptions } from "./types.js";
import { type TerminalInput, type TerminalOutput } from "./terminal-renderer.js";
import { type VercelStatusEffect, type VercelStatusSnapshot } from "./vercel-status.js";
import type { detectProjectIdentity } from "#setup/project-resolution.js";
import { getVercelAuthStatus } from "#setup/vercel-project.js";
export { parsePromptCommand, type PromptCommand } from "./prompt-commands.js";
export type AgentTUIStreamResult = {
    events: AsyncIterable<AgentTUIStreamEvent> | ReadableStream<AgentTUIStreamEvent>;
    abort?: () => void;
    turnState?: AgentTUITurnState;
};
export type AgentTUIStreamUsage = {
    inputTokens?: number;
    outputTokens?: number;
};
export type AgentTUIStreamEvent = {
    type: "step-start";
} | {
    type: "step-finish";
    usage?: AgentTUIStreamUsage;
} | {
    type: "assistant-delta";
    id: string;
    delta: string;
} | {
    type: "assistant-complete";
    id: string;
    text?: string | null;
} | {
    type: "reasoning-delta";
    id: string;
    delta: string;
} | {
    type: "reasoning-complete";
    id: string;
} | {
    type: "tool-call";
    toolCallId: string;
    toolName: string;
    input: unknown;
} | {
    type: "tool-approval-request";
    approvalId: string;
    toolCallId: string;
} | {
    type: "tool-result";
    toolCallId: string;
    output: unknown;
} | {
    type: "tool-error";
    toolCallId: string;
    errorText: string;
} | {
    type: "error";
    errorText: string;
    detail?: string;
} | {
    type: "finish";
    usage?: AgentTUIStreamUsage;
};
export type AgentTUITurnState = {
    boundaryEvent?: "session.completed" | "session.failed" | "session.waiting";
    pendingApprovals: AgentTUIToolApprovalRequest[];
    pendingQuestions: InputRequest[];
    sawSessionFailure: boolean;
};
export type AgentTUISessionOptions = {
    title?: string;
    /**
     * Text to seed the editable prompt buffer with before the user types.
     * Set by the runner for the first prompt when `eve dev --input` is used.
     */
    initialDraft?: string;
    submittedPrompt?: string;
    continueSession?: boolean;
    tools?: TerminalPartDisplayMode;
    reasoning?: TerminalPartDisplayMode;
    subagents?: TerminalPartDisplayMode;
    connectionAuth?: TerminalPartDisplayMode;
    assistantResponseStats?: AssistantResponseStatsMode;
    contextSize?: number;
};
export type AgentTUIToolApprovalRequest = {
    approvalId: string;
    toolCallId: string;
    toolName: string;
    title?: string;
    input: unknown;
};
export type AgentTUIToolApprovalResponse = {
    approved: boolean;
    reason?: string;
};
export type AgentTUIInputOption = {
    id: string;
    label: string;
    description?: string;
    style?: "primary" | "danger" | "default";
};
export type AgentTUIInputQuestion = {
    requestId: string;
    prompt: string;
    display: "select" | "text";
    options?: ReadonlyArray<AgentTUIInputOption>;
    allowFreeform?: boolean;
};
export type AgentTUIInputQuestionResponse = {
    optionId?: string;
    text?: string;
};
export type AgentTUIAgentHeader = {
    name: string;
    serverUrl: string;
    info?: AgentInfoResult;
    /** Message-of-the-day line shown under the brand line (local sessions only). */
    tip?: string;
};
export type AgentTUIRenderer = {
    /**
     * Commits a startup header describing the connected agent (brand mark,
     * model, instructions, tools, skills, subagents) to the transcript before
     * the first prompt, and refreshes it after local dev artifact changes.
     * Optional — renderers without a header simply skip it.
     */
    renderAgentHeader?(header: AgentTUIAgentHeader): void;
    /**
     * Commits a single informational line to the transcript. Used for session
     * recovery and slash-command results. Optional.
     */
    renderNotice?(text: string): void;
    /**
     * Commits one development sandbox lifecycle line to the transcript.
     * Optional so non-terminal renderers can ignore local prewarm progress.
     */
    renderSandboxLog?(text: string): void;
    renderSetupWarning?(text: string): void;
    /** Clears the setup attention line once its issue is resolved. */
    clearSetupWarning?(): void;
    renderCommandResult?(text: string): void;
    readonly setupFlow?: SetupFlowRenderer;
    readPrompt?(options?: AgentTUISessionOptions): Promise<string | undefined>;
    readToolApproval?(request: AgentTUIToolApprovalRequest, options?: AgentTUISessionOptions): Promise<AgentTUIToolApprovalResponse>;
    readInputQuestion?(question: AgentTUIInputQuestion, options?: AgentTUISessionOptions): Promise<AgentTUIInputQuestionResponse | undefined>;
    renderStream(result: AgentTUIStreamResult, options?: AgentTUISessionOptions): Promise<void>;
    /**
     * Out-of-band update for one child step (reasoning + message text) of a
     * subagent dispatch. Called by the runner as child-session stream events
     * arrive. The renderer renders this as a body section colored by the
     * subagent palette.
     */
    upsertSubagentStep?(update: SubagentStepUpdate): void;
    /**
     * Out-of-band update for one child tool call of a subagent dispatch.
     */
    upsertSubagentTool?(update: SubagentToolUpdate): void;
    /**
     * Registers a tool call id as originating from a subagent's child
     * session. The renderer must skip or remove parent-level tool blocks for
     * these ids — they are surfaced via {@link upsertSubagentTool} instead.
     */
    markChildToolCallId?(callId: string): void;
    /**
     * Out-of-band update for one MCP connection authorization lifecycle.
     * Called by the runner as `authorization.*` events arrive.
     * The renderer renders this as a persistent body section per
     * connection that transitions through `required` → `pending` →
     * one of the terminal `ConnectionAuthorizationOutcome` states.
     */
    upsertConnectionAuth?(update: ConnectionAuthUpdate): void;
    /**
     * Sets the number of connections currently awaiting an OAuth
     * callback. The renderer overrides its bottom status bar with a
     * "waiting for connection authorization" hint while this is > 0,
     * so the user understands the agent is parked, not hung.
     */
    setConnectionAuthPendingCount?(count: number): void;
    /**
     * The log display mode currently in effect. Paired with
     * {@link setLogDisplayMode}; both are absent on renderers that do not
     * capture process output.
     */
    logDisplayMode?(): LogDisplayMode;
    /**
     * Switches which captured log sources (stdout/stderr) the transcript
     * shows. Captured output is buffered regardless of mode, so a change
     * applies retroactively: hiding removes already-rendered log lines from
     * the transcript and showing restores buffered ones at their original
     * positions. Used by the `/loglevel` command.
     */
    setLogDisplayMode?(mode: LogDisplayMode): void;
    /**
     * Commits any delayed local dev build errors immediately before dispatching
     * a user prompt. Renderers without process-log capture ignore it.
     */
    flushDelayedDevBuildErrors?(): void;
    /**
     * Sets the workspace-scoped Vercel segment of the persistent bottom
     * status line: linked project identity and the session's pending-deploy
     * flag. Pushed by the runner at startup (async probe) and after
     * /vercel, /channels, /deploy outcomes. Renderers without a status
     * line ignore it.
     */
    setVercelStatus?(status: VercelStatusSnapshot): void;
    /**
     * Clears the rendered transcript and resets per-conversation display
     * state, leaving the UI interactive on a fresh screen. Used by the
     * `/new` command to start a new session with a clean slate.
     */
    reset?(): void;
    /**
     * Tears down interactive mode and restores the terminal when the runner's
     * lifecycle ends.
     */
    shutdown?(): void;
};
export interface PromptCommandHandlerContext {
    readonly renderer: AgentTUIRenderer;
    readonly title: string;
    /** Provider entry authorized by confirmed boot-time model-access evidence. */
    readonly initialModelStep?: "provider";
}
/** What one handled slash command leaves behind for the runner to apply. */
export interface PromptCommandOutcome {
    /** Outcome line rendered under the echoed command; absent renders nothing. */
    message?: string;
    /** Post-command work; model access also re-probes the Vercel identity. */
    effect?: VercelStatusEffect | {
        kind: "model-access-changed";
    };
}
export interface PromptCommandHandler {
    handle(command: Extract<PromptCommand, {
        type: "extension";
    }>, context: PromptCommandHandlerContext): Promise<PromptCommandOutcome | undefined>;
}
export type EveTUIRunnerOptions = TuiDisplayOptions & {
    session: ClientSession;
    /**
     * Optional client used to attach to child sessions for live subagent
     * stream observation. When omitted, the TUI still shows the subagent
     * section but cannot surface the subagent's reasoning / response /
     * intermediate events — only the parent-stream `called` and
     * `completed` transitions.
     */
    client?: Client;
    renderer?: AgentTUIRenderer;
    screen?: TerminalOutput;
    userInput?: TerminalInput;
    /**
     * Formats an error thrown while dispatching a turn (the initial
     * `session.send()` POST — e.g. a transport failure or a Vercel
     * Deployment Protection challenge) into the text rendered in the
     * inline error region. Defaults to the error's message. Callers that
     * know about transport-specific challenges (the `eve dev` glue) inject
     * a richer formatter here.
     */
    formatTransportError?: (error: unknown) => string;
    /**
     * Local `eve dev` server URL. When present, normal prompts refresh the
     * active session after HMR so the next prompt uses the latest authored
     * artifacts; input-response resumes keep the current session.
     */
    serverUrl?: string;
    /** Absolute local application root; omitted for remote `--url` sessions. */
    appRoot?: string;
    /**
     * Seeds the editable prompt buffer for the first prompt only. The text is
     * not auto-submitted — the user can edit it and presses Enter to send.
     */
    initialInput?: string;
    /** Handles non-core slash commands without adding feature branches to the runner. */
    promptCommandHandler?: PromptCommandHandler;
    /** Boot-time installation-state checks; defaults to the built-ins. */
    bootDetections?: readonly BootDetection[];
    /** Test seam for the status line's Vercel link probe; defaults to the real one. */
    detectProjectIdentity?: typeof detectProjectIdentity;
    /** Test seam for the off-critical-path boot login probe; defaults to the real one. */
    getVercelAuthStatus?: typeof getVercelAuthStatus;
    /** Reports phases from this runner's initial local-dev connection. */
    onBootProgress?: DevBootProgressReporter;
};
export declare class EveTUIRunner {
    #private;
    constructor(options: EveTUIRunnerOptions);
    run(): Promise<void>;
}
type SubagentChildStep = {
    reasoning: string;
    message: string;
    finalized: boolean;
};
type SubagentToolState = {
    toolName: string;
    input: unknown;
    status: "approval-requested" | "executing" | "done" | "failed";
    output?: unknown;
    errorText?: string;
};
export type SubagentRun = {
    name: string;
    /**
     * One entry per logical "child message" — independent of the child's
     * `stepIndex` field, which the harness can reuse across multiple
     * assistant messages within a turn (e.g. a message before a tool call
     * and another message after the tool result both arrive under
     * `stepIndex: 0`). The key is a monotonic counter so each
     * `message.completed` opens a new box on the next inbound delta.
     */
    steps: Map<number, SubagentChildStep>;
    /**
     * Section currently accepting reasoning/message deltas. `null` means
     * the next delta opens a new section.
     */
    currentSectionKey: number | null;
    /** Monotonic counter for new section keys. */
    nextSectionKey: number;
    tools: Map<string, SubagentToolState>;
};
export type SubagentStepUpdate = {
    callId: string;
    subagentName: string;
    sectionKey: number;
    reasoning: string;
    message: string;
    finalized: boolean;
};
export type SubagentToolUpdate = {
    callId: string;
    subagentName: string;
    childCallId: string;
    toolName: string;
    input: unknown;
    status: "approval-requested" | "executing" | "done" | "failed";
    output?: unknown;
    errorText?: string;
};
export type ConnectionAuthChallenge = {
    url?: string;
    userCode?: string;
    expiresAt?: string;
    instructions?: string;
};
export type ConnectionAuthState = "required" | "pending" | ConnectionAuthorizationOutcome;
export type ConnectionAuthUpdate = {
    name: string;
    description: string;
    state: ConnectionAuthState;
    challenge?: ConnectionAuthChallenge;
    reason?: string;
};