Tools and agent

Everything an agent’s code can call. This reference comes from Tilda’s plugin itself: the documents its kernel serves to agents through agent.documentation, and the type declarations its skills ship in repl.d.ts. It’s shown as agents read it, so parts of it speak to the agent.

The tools#

Agents get two tools. JsReplExec runs one cell of JavaScript:

JsReplReset takes no inputs. It clears every binding and closes every page, tab group, and terminal that agent opened.

The documents agents read#

In a cell, agent.documentation.get(name) returns one of these documents, and agent.documentation.catalog() lists them. Each configured MCP server adds one more, mcp:<server>, describing its tools.

By area#

• Browser API: agent.browsers, pages, and locators.

• Mac apps API: agent.computer, apps, windows, and displays.

• Terminals API: agent.terminals.

• MCP API: agent.mcp.

• Assertions: expect.

Standard Node.js globals and modules work in every cell as well, and aren’t listed here.

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.

• Agent
• global
• Documentation
• DocumentName
• Subagents
• SubagentPresetInfo
• SubagentPreset
• SubagentAccess
• SubagentInfo
• SubagentTranscript
• WebSocket
• FileChooser
• Dialog
• SubagentRequest
• SubagentOutcome
• SubagentEvent
• expect

/** Available in every REPL cell via the `agent` global. */
interface Agent {
	/** The connected browser registry: list(), get(id), getDefault(). */
	browsers: Browsers;
	/** Playwright-shaped macOS application control. */
	computer: Computer;
	/** Runtime documentation the agent reads with get(name) / list() / catalog(). */
	documentation: Documentation;
	/**
	 * The MCP servers in ~/.tilda/mcp.json: list(), reload(), and one handle
	 * per server, `agent.mcp.<server>.<tool>(args)`. Read
	 * `agent.documentation.get("mcp:<server>")` for a server's tools.
	 */
	mcp: Mcp & {
		[server: string]: McpServer;
	};
	/**
	 * Other coding agents as subagents of this session, each in a preset's role:
	 * presets(), spawn(), message(), decide(), interrupt(), list(),
	 * transcript(). Read `agent.documentation.get("subagents")` first.
	 */
	subagents: Subagents;
	/**
	 * Programs under a real terminal, kept by tmux so they outlive this process:
	 * open(name, command), get(name), list(), killAll(). Run a plain command with
	 * node:child_process instead.
	 */
	terminals: Terminals;
	/** Current working directory of the server process. */
	cwd: string;
	/** User home directory. */
	homeDir: string;
	/** Temporary directory. The bare global tmpDir is the same value. */
	tmpDir: string;
	/**
	 * Send a picture into the current cell result. Accepts bytes, a data URL,
	 * base64, { bytes, mimeType }, { image_url }, or a tool result with image
	 * content.
	 */
	viewImage(imageLike: unknown, options?: {
		mimeType?: string;
	}): Promise<{
		bytes: number;
	}>;
}

declare global {
	/** Available in every REPL cell: browsers, documentation, paths, viewImage. */
	const agent: Agent;
	/** Playwright-shaped assertions: expect(page.getByRole("button")).toBeVisible(). */
	const expect: Expect;
	/** Temporary directory of the server process. */
	const tmpDir: string;
	/** Dynamic import through codemode's resolver (builtins, .js/.mjs files, bare packages). */
	function __import(specifier: string): Promise<unknown>;
}

class Documentation {
	get(name: string): Promise<string>;
	list(): Promise<string[]>;
	catalog(): Promise<Array<{
		name: string;
		description: string;
	}>>;
}

type DocumentName = "browser" | "browser-api" | "locators" | "network" | "events" | "downloads" | "files-and-dialogs" | "cdp" | "codemode" | "computer-api" | "troubleshooting" | "security" | "mcp" | "subagents";

class Subagents {
	/** Every preset, with the models this machine can run for it and why the others cannot run. */
	presets(): Promise<SubagentPresetInfo[]>;
	/**
	 * Starts a subagent on `task` and returns at once; it works in the background.
	 * It runs on a random one of the preset's models this machine can run, or on
	 * `model` when given. `access` defaults to "auto": the subagent's own reviewer
	 * model decides, and what it will not allow comes to you as an approval request.
	 */
	spawn(input: {
		preset: SubagentPreset;
		task: string;
		cwd: string;
		model?: string;
		access?: SubagentAccess;
	}): Promise<SubagentInfo>;
	/**
	 * Sends `text` to the subagent: it answers an open question, joins the running
	 * turn, or starts the next one once the subagent is idle.
	 */
	message(input: {
		id: string;
		text: string;
	}): Promise<SubagentInfo>;
	/** Settles one of the subagent's approval requests. */
	decide(input: {
		id: string;
		requestId: string;
		decision: "allow" | "deny";
	}): Promise<SubagentInfo>;
	/** Ends the running turn; the subagent stays and takes the next message. An idle one is left as it is. */
	interrupt(input: {
		id: string;
	}): Promise<SubagentInfo>;
	/** This session's subagents, oldest first. */
	list(): Promise<SubagentInfo[]>;
	/** What the subagent did, in brief, from entry `sinceSeq` on. */
	transcript(input: {
		id: string;
		sinceSeq: number;
		limit: number;
	}): Promise<SubagentTranscript>;
}

type SubagentPresetInfo = {
	preset: SubagentPreset;
	purpose: string;
	choices: {
		model: string;
		effort: "high" | "low" | "max" | "medium" | "xhigh" | null;
	}[];
	unavailable: {
		model: string;
		effort: "high" | "low" | "max" | "medium" | "xhigh" | null;
		reason: string;
	}[];
};

type SubagentPreset = "explore" | "implement" | "reason" | "review";

type SubagentAccess = "auto" | "full" | "read-only";

type SubagentInfo = { model: string; effort: "high" | "low" | "max" | "medium" | "xhigh" | null; id: string; preset: "explore" | "implement" | "reason" | "review"; access: "auto" | "full" | "read-only"; cwd: string; pending: ({ kind: "approval"; requestId: string; action: "tool" | "command" | "file-change" | "permissions"; summary: string; blocking: boolean; } | { kind: "question"; requestId: string; questions: { id: string; question: string; options: string[]; }[]; })[]; } & { status: "running"; } | { model: string; effort: "high" | "low" | "max" | "medium" | "xhigh" | null; id: string; preset: "explore" | "implement" | "reason" | "review"; access: "auto" | "full" | "read-only"; cwd: string; pending: ({ kind: "approval"; requestId: string; action: "tool" | "command" | "file-change" | "permissions"; summary: string; blocking: boolean; } | { kind: "question"; requestId: string; questions: { id: string; question: string; options: string[]; }[]; })[]; } & { status: "done"; text: string; } | { model: string; effort: "high" | "low" | "max" | "medium" | "xhigh" | null; id: string; preset: "explore" | "implement" | "reason" | "review"; access: "auto" | "full" | "read-only"; cwd: string; pending: ({ kind: "approval"; requestId: string; action: "tool" | "command" | "file-change" | "permissions"; summary: string; blocking: boolean; } | { kind: "question"; requestId: string; questions: { id: string; question: string; options: string[]; }[]; })[]; } & { status: "failed"; reason: string; } | { model: string; effort: "high" | "low" | "max" | "medium" | "xhigh" | null; id: string; preset: "explore" | "implement" | "reason" | "review"; access: "auto" | "full" | "read-only"; cwd: string; pending: ({ kind: "approval"; requestId: string; action: "tool" | "command" | "file-change" | "permissions"; summary: string; blocking: boolean; } | { kind: "question"; requestId: string; questions: { id: string; question: string; options: string[]; }[]; })[]; } & { status: "interrupted"; };

type SubagentTranscript = {
	entries: {
		seq: number;
		at: number;
		role: "tool" | "parent" | "subagent" | "tilda";
		text: string;
	}[];
	nextSeq: number;
};

/**
 * Playwright-shaped WebSocket (thin).
 * @see https://playwright.dev/docs/api/class-websocket
 */
class WebSocket {
	url(): string;
	isClosed(): boolean;
}

/**
 * Playwright-shaped file chooser (from waitForEvent("filechooser")).
 * @see https://playwright.dev/docs/api/class-filechooser
 */
class FileChooser {
	page(): Page;
	isMultiple(): boolean;
	setFiles(files: string | string[]): Promise<void>;
}

/**
 * Playwright-shaped JavaScript dialog (alert / confirm / prompt / beforeunload).
 * @see https://playwright.dev/docs/api/class-dialog
 */
class Dialog {
	type(): "alert" | "beforeunload" | "confirm" | "prompt" | string;
	message(): string;
	defaultValue(): string;
	page(): Page;
	accept(promptText?: string): Promise<void>;
	dismiss(): Promise<void>;
}

type SubagentRequest = {
	kind: "approval";
	requestId: string;
	action: "tool" | "command" | "file-change" | "permissions";
	summary: string;
	blocking: false | true;
} | {
	kind: "question";
	requestId: string;
	questions: {
		id: string;
		question: string;
		options: string[];
	}[];
};

type SubagentOutcome = {
	status: "done";
	text: string;
} | {
	status: "failed";
	reason: string;
} | {
	status: "interrupted";
};

type SubagentEvent = { seq: number; subagent: string; } & { kind: "message"; text: string; } | { seq: number; subagent: string; } & { kind: "request"; request: { kind: "approval"; requestId: string; action: "tool" | "command" | "file-change" | "permissions"; summary: string; blocking: boolean; } | { kind: "question"; requestId: string; questions: { id: string; question: string; options: string[]; }[]; }; } | { seq: number; subagent: string; } & { kind: "finished"; outcome: { status: "done"; text: string; } | { status: "failed"; reason: string; } | { status: "interrupted"; }; };

const expect: Expect;