Terminals API

agent.terminals runs programs that need a real terminal and finds them again by name. The guide agents read is on Terminals.

Types#

As declared in the repl.d.ts the skills ship. Constructors are left out: code in a cell is handed these objects and doesn’t build them.

• Terminals
• TerminalOpenOptions
• Terminal
• TerminalInfo
• ExpectPattern
• TerminalWaitOptions
• ExpectResult
• TerminalIdleOptions
• TerminalStatus

/** `agent.terminals`: open terminals that outlive the kernel, and find them again. */
class Terminals {
	readonly stateDir: string;
	readonly owner: string;
	/**
	 * Start a command under a real terminal, or return the terminal of that
	 * name if it is still running. A name whose program has ended is replaced
	 * and its logs start over.
	 */
	open(name: string, command: string, options?: TerminalOpenOptions): Promise<Terminal>;
	/** Every terminal on the codemode server, running or ended, from any kernel. */
	list(): Promise<TerminalInfo[]>;
	/** A terminal by name, running or ended, whichever kernel opened it. */
	get(name: string): Promise<Terminal>;
	/** End every terminal on the codemode server and stop it. Log files stay. */
	killAll(): Promise<void>;
	/**
	 * End terminals created by this owner, plus abandoned process-owned terminals.
	 * Host-provided durable owner tags are never considered abandoned.
	 */
	killOwn(): Promise<void>;
	/** Drop this kernel's connection to the server. Terminals keep running. */
	close(): void;
}

type TerminalOpenOptions = {
	/** Working directory; defaults to the kernel's `agent.cwd`. */
	cwd?: string;
	/** Set for the program, over this kernel's own environment. */
	env?: Record<string, string>;
	cols?: number;
	rows?: number;
};

class Terminal {
	readonly name: string;
	readonly paneId: string;
	readonly logs: {
		plain: string;
		raw: string;
	};
	/** Fresh state from tmux. */
	info(): Promise<TerminalInfo>;
	/** The rendered viewport, as a user would see it, without trailing blanks. */
	screen(): Promise<string>;
	/**
	 * What the plain log gained since the last `read()` on this terminal, by any
	 * kernel: the same lines the agent sees in the file, so nothing a program
	 * does to the screen (a clear, a redraw) can lose them. The byte cursor
	 * lives in tmux, so it survives a restart.
	 */
	read(): Promise<string>;
	/**
	 * Type text. A newline is sent as Enter, so a multi-line snippet arrives as
	 * separate lines. Resolves with the screen once the program has answered.
	 */
	type(text: string): Promise<string>;
	/** Send one named key, e.g. "Enter", "Control+C", "ArrowUp", "F5". Resolves with the screen. */
	press(combo: string): Promise<string>;
	/**
	 * Wait until the screen or the recent plain log contains one of the
	 * patterns. Give the alternatives you expect — a prompt, an error, a
	 * question — and branch on `index`. Rejects with the screen if the program
	 * exits first or the timeout passes.
	 */
	expect(patterns: ExpectPattern | ExpectPattern[], { timeoutMs }?: TerminalWaitOptions): Promise<ExpectResult>;
	/** Wait until the program has written nothing for `quietMs`. Resolves with the screen. */
	waitForIdle({ quietMs, timeoutMs }?: TerminalIdleOptions): Promise<string>;
	/** Wait for the program to end. Its output is complete when this resolves. */
	waitForExit({ timeoutMs }?: TerminalWaitOptions): Promise<{
		exitCode: number;
		screen: string;
	}>;
	/** Wait until something accepts a TCP connection on the port: a dev server is up. */
	waitForPort(port: number, { host, timeoutMs }?: {
		host?: string;
		timeoutMs?: number;
	}): Promise<void>;
	/** Wait until the URL answers an HTTP request with any status. */
	waitForUrl(url: string, { timeoutMs }?: TerminalWaitOptions): Promise<void>;
	resize(cols: number, rows: number): Promise<void>;
	/** End the program and remove the terminal. The log files stay. */
	kill(): Promise<void>;
}

type TerminalInfo = {
	name: string;
	paneId: string;
	pid: number;
	command: string;
	cwd: string;
	status: TerminalStatus;
	/**
	 * Once ended: the exit status, or 128 plus the signal number when a signal
	 * ended it, as a shell reports it. Null while running.
	 */
	exitCode: number | null;
	/** The signal that ended it, by name or decimal number as reported by tmux, or null. */
	signal: string | null;
	cols: number;
	rows: number;
	createdAt: number;
	lastOutputAt: number;
	/** Creation owner: a host-provided tag or the default `pid@host`. */
	owner: string;
	/** Files the agent can read, grep, or tail with its own tools. */
	logs: {
		plain: string;
		raw: string;
	};
};

type ExpectPattern = string | RegExp;

type TerminalWaitOptions = {
	timeoutMs?: number;
};

type ExpectResult = {
	/** Which pattern matched, by position in the list. */
	index: number;
	pattern: ExpectPattern;
	match: string;
	screen: string;
};

type TerminalIdleOptions = {
	quietMs?: number;
	timeoutMs?: number;
};

type TerminalStatus = "running" | "exited";