@blundergoat/goat-flow/dist/cli/server/terminal.d.ts

AI coding agent harness and local dashboard for Claude Code, OpenAI Codex, Google Antigravity, and GitHub Copilot - setup audits, guardrails, structured skills, deny hooks, and persistent learning loops.

import type { WebSocket } from "ws";
import type { SessionInfo, CreateResponse, HealthResponse, Runner } from "./types.js";
import { validateProjectPath } from "./local-paths.js";
/** Maximum number of concurrent terminal sessions allowed.
 *  Single source of truth consumed by the dashboard API, client guards, and docs. */
export declare const MAX_SESSIONS = 10;
export declare const INITIAL_PROMPT_CHUNK_SIZE = 2048;
/** Shell, arguments, environment, and deferred input needed to launch a runner in a durable PTY. */
interface TerminalSpawnSpec {
    shell: string;
    args: string[];
    env: NodeJS.ProcessEnv;
    initialInput: string | null;
}
type TerminalTraceEventKind = "terminal.send" | "prompt.send";
/** Redaction-ready input metadata emitted for terminal auditing without changing PTY delivery. */
export interface TerminalTraceEvent {
    eventKind: TerminalTraceEventKind;
    sessionId: string;
    projectPath: string;
    cwd: string;
    targetPath: string;
    runner: Runner;
    input: string;
    bytes: number;
}
/** Observer hook for terminal input traces; sink failures are isolated from session writes. */
export type TerminalTraceSink = (event: TerminalTraceEvent) => void;
/**
 * Split terminal input into bounded chunks for PTY write reliability.
 *
 * @param input Full terminal payload to write.
 * @param chunkSize Maximum characters per PTY write; must be a positive integer.
 * @returns Ordered chunks that concatenate back to the original input.
 * @throws Error when `chunkSize` is not a positive integer.
 */
export declare function chunkTerminalInput(input: string, chunkSize?: number): string[];
/**
 * Pick the most runnable Windows runner path from a `where` result set.
 *
 * @param candidates Raw paths returned by `where`, including possible blank or duplicate lines.
 * @returns The preferred executable-like path, or null when nothing usable remains.
 */
export declare function pickWindowsRunnerPath(candidates: readonly string[]): string | null;
/**
 * Build the PTY shell invocation that keeps a usable terminal open per OS.
 *
 * @param runner Runner identity used for runner-specific launch flags.
 * @param cliPath Absolute runner binary path to launch inside the shell.
 * @param prompt Optional launch prompt delivered through PTY input after startup.
 * @param environment Environment snapshot merged into the spawned process.
 * @param platform Platform selector used by tests and cross-platform launch planning.
 * @returns Spawn details plus deferred initial input; callers own the actual PTY spawn.
 */
export declare function buildTerminalSpawnSpec(runner: Runner, cliPath: string, prompt: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): TerminalSpawnSpec;
/**
 * Resolve a CLI binary by reading the process PATH through platform lookup tools.
 * Reads process state only; swallows lookup errors and reports them as null because missing runners are normal dashboard state.
 */
declare function resolveCLIPath(name: string): string | null;
/** Manages PTY-backed terminal sessions for the dashboard */
declare class TerminalManager {
    private sessions;
    private runnerPaths;
    private nodePtyModule;
    private nodePtyAvailable;
    private startedAt;
    private readonly idleTimeoutMs;
    private readonly traceSink;
    /** Resolve available runner binaries once and convert idle-timeout minutes into timer state. */
    constructor(idleTimeoutMinutes?: number, traceSink?: TerminalTraceSink);
    /** Lazy-load node-pty on first use; throws a rebuild diagnostic when the native module is missing. */
    private loadNodePty;
    /** Create a new terminal session for the requested runner and project. */
    create(prompt: string, projectPath: string, runner?: Runner, options?: {
        targetPath?: string;
    }): Promise<CreateResponse>;
    /**
     * Attach a browser WebSocket to an existing terminal session.
     * Reports an error on the socket when the session is gone; the branching preserves detach semantics
     * because a browser disconnect must not be treated as a PTY exit.
     */
    attachWebSocket(id: string, socket: WebSocket): void;
    /**
     * Replay buffered PTY output to a newly attached socket so reconnects do not
     * lose terminal context gathered while detached, then drop the buffer.
     *
     * @param session - terminal session holding the detach buffer
     * @param socket - freshly attached browser WebSocket to replay into
     */
    private replayDetachBuffer;
    /**
     * Handle one client WebSocket payload: input keystrokes feed the PTY (with
     * idle-timer reset and prompt tracing), resize messages clamp and apply
     * terminal dimensions, and undecodable payloads report an error to the socket.
     *
     * @param session - terminal session that owns the PTY the message targets
     * @param socket - browser WebSocket the payload arrived on
     * @param raw - wire payload as received (Buffer or string)
     */
    private handleClientMessage;
    /** Return the public session snapshot for one terminal session ID. */
    get(id: string): SessionInfo | null;
    /** Terminate a terminal session by ID. */
    kill(id: string): boolean;
    /** List every terminal session that is still considered live. */
    list(): SessionInfo[];
    /** Report terminal backend health; node-pty probe errors recover into an unavailable status. */
    health(): Promise<HealthResponse>;
    /** Shut down every tracked session and notify attached clients. */
    shutdown(): void;
    /** Tear down a terminal session; swallows kill/close races because either side may already be gone. */
    private killSession;
    /** Emit redaction-ready input metadata; tracing errors never affect PTY writes. */
    private traceTerminalInput;
    /** Reset the idle-timeout timer after activity because each session must have at most one expiry path. */
    private resetIdleTimer;
    /** Clear the idle-timeout timer for a session. */
    private clearIdleTimer;
    /** Convert an internal session record into its public response shape. */
    private toInfo;
}
export { TerminalManager, resolveCLIPath, validateProjectPath };
//# sourceMappingURL=terminal.d.ts.map