@pragma-sh/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,3038 @@
+/**
+* Which world a terminal session's shell lives in. `native` runs the host's own shell through the host's PTY (a pseudo-terminal on macOS and Linux, ConPTY on Windows). `wsl` runs a Linux shell inside a WSL distribution, served by a Linux `pragma-server` running in that distribution. Only Windows offers a real choice; macOS and Linux always resolve to `native`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "TerminalBackend".
+*/
+type TerminalBackend = "native" | "wsl";
+/**
+* Top-level request/response RPC domains served by pragma-server over the Unix-socket frame protocol.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ProtocolRpcMethod".
+*/
+type ProtocolRpcMethod = "git" | "filesystem" | "database" | "kanban" | "worktrees" | "projects" | "tabs" | "settings" | "github" | "ai" | "exec" | "automations" | "plugins" | "tunnel" | "ports" | "scratchpads" | "whiteboards" | "wsl" | "fanouts";
+/**
+* Snapshot-then-delta subscription event streams served by pragma-server.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ProtocolEventKind".
+*/
+type ProtocolEventKind = "agentStatus" | "worktreeChanged" | "kanbanChanged" | "tabsChanged" | "fileChanged" | "echoMode" | "automationPending" | "automationsChanged" | "workspace" | "fanouts";
+/**
+* Stable protocol-level RPC error codes.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ProtocolErrorCode".
+*/
+type ProtocolErrorCode = "invalidPayload" | "unsupportedMethod" | "notFound" | "staleWrite" | "permissionDenied" | "internal";
+/**
+* How a desktop update is applied. `reload` swaps the webview UI overlay and leaves the host running. `restart` always runs the full OS installer.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "UpdateApplyMode".
+*/
+type UpdateApplyMode = "reload" | "restart";
+/**
+* Installer target id sent on the check request so a restart offer returns the right asset.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "UpdatePlatform".
+*/
+type UpdatePlatform = "darwin-aarch64" | "darwin-x86_64" | "linux-x86_64-deb" | "linux-x86_64-rpm" | "linux-x86_64-appimage" | "linux-aarch64-deb" | "linux-aarch64-rpm" | "linux-aarch64-appimage" | "windows-x86_64";
+/**
+* Lifecycle of one fanout. Deliberately separate from agent runtime status: an attempt's agent may be idle while the fanout is still `active`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutStatus".
+*/
+type FanoutStatus = "provisioning" | "active" | "attention" | "partial" | "ready" | "failed" | "interrupted" | "cancelled" | "finalizing" | "needsResolution" | "cleanupFailed" | "completed";
+/**
+* Lifecycle of one fanout attempt. `interrupted` means the host restarted while the attempt was live; its prompt is never replayed automatically.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutMemberStatus".
+*/
+type FanoutMemberStatus = "pending" | "provisioning" | "running" | "attention" | "done" | "failed" | "interrupted" | "cancelled" | "selected";
+/**
+* Durable progress marker for the destructive pick transaction. Persisted after every successful step so a retry resumes at the first incomplete stage instead of repeating a destructive one.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutFinalizeStage".
+*/
+type FanoutFinalizeStage = "validating" | "committingWinner" | "merging" | "promotingScratchpads" | "stoppingSessions" | "cleaningUp" | "completed";
+/**
+* Machine-readable reason a fanout operation failed, preserved through the CLI, the gateway, and the SDK so callers branch on a code rather than on message text.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutFailureCode".
+*/
+type FanoutFailureCode = "invalidSelector" | "unknownAgent" | "unknownModel" | "unknownReasoning" | "activeFanoutExists" | "dirtyParent" | "worktreeCreateFailed" | "setupFailed" | "launchFailed" | "notFound" | "conflict" | "descendantWorktree" | "commitMessageFailed" | "mergeConflict" | "promotionFailed" | "cleanupFailed" | "internal";
+/**
+* Where a fanout's single parent comes from: an existing worktree, or a fresh coordination worktree created from a source worktree.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutParentSpec".
+*/
+type FanoutParentSpec = FanoutExistingParent | FanoutNewParent;
+/**
+* Follow-up delivery outcome per member: `accepted` is the fire-and-forget terminal state, the rest are only observable when waiting.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutDeliveryState".
+*/
+type FanoutDeliveryState = "accepted" | "delivered" | "failed" | "timedOut";
+/**
+* Optional agent capability used to exclude unsupported agent-verification scenarios.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentFeature".
+*/
+type AgentFeature = "questions" | "commandApproval" | "commands" | "subagents" | "abort" | "interrupt" | "usageLimits" | "sessionName";
+/**
+* Discriminates what a tab hosts: a shell terminal, an embedded browser, a file editor, a scratchpad, a whiteboard, a read-only diff, the read-only daemon log viewer, a pull-request review, or a plugin web view.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "TabKind".
+*/
+type TabKind = "terminal" | "browser" | "editor" | "scratchpad" | "whiteboard" | "diff" | "log" | "pr-review" | "plugin-webview";
+/**
+* Runtime status an external agent reports for a terminal tab. `cleared` is a transient signal that removes the agent's indicator entirely (used when the agent process exits), as opposed to `done`, which leaves a green "finished, go look" dot.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentStatus".
+*/
+type AgentStatus = "running" | "attention" | "done" | "cleared";
+/**
+* Reason an agent needs the user's attention.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentAttentionKind".
+*/
+type AgentAttentionKind = "question" | "command";
+/**
+* Role/source for one rich agent message entry.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentMessageRole".
+*/
+type AgentMessageRole = "assistant" | "tool" | "user" | "system";
+/**
+* Lifecycle status for a tool call reported inside an AgentMessage.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentToolCallStatus".
+*/
+type AgentToolCallStatus = "running" | "done" | "error";
+/**
+* File interaction kind reported inside an AgentMessage.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentFileChangeKind".
+*/
+type AgentFileChangeKind = "read" | "edited" | "created" | "deleted";
+/**
+* Which axis of change a diff/listing record refers to. committed (base branch → HEAD), staged (HEAD → index), and unstaged (index → working tree) are the three listing axes. worktree (base branch → working tree) is the unified review side every Changes-sidebar click opens — it compares the file's current on-disk content against what used to be on the worktree at its fork point, regardless of which list the file appears in.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "DiffSide".
+*/
+type DiffSide = "committed" | "staged" | "unstaged" | "worktree";
+/**
+* How a file changed relative to the diff base.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ChangeStatus".
+*/
+type ChangeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
+/**
+* Column a prompt card lives in on the project Kanban board.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "KanbanPromptStatus".
+*/
+type KanbanPromptStatus = "draft" | "inProgress" | "reviewNeeded" | "completed";
+/**
+* How a reviewed card was completed: committed and merged, committed with a PR opened, or finished manually.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "KanbanCompletedAction".
+*/
+type KanbanCompletedAction = "commitMerge" | "commitPr" | "manual";
+/**
+* When the card's agent run is started. MVP supports manual start only.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "KanbanSchedulingMode".
+*/
+type KanbanSchedulingMode = "manual";
+/**
+* Shared compile-time constants. Single source of truth for both the TypeScript frontend (src) and the Rust backend (src-tauri). Edit values.json; never edit generated code.
+*/
+interface Constants {
+	app: AppInfo;
+	window: WindowDefaults;
+	editorLaunchers: EditorLaunchers;
+	scripts: Scripts;
+	agents: Agents;
+	platform: Platform;
+	daemon: Daemon;
+	gateway: Gateway;
+	protocol: Protocol;
+	github: GitHub;
+	plugins: Plugins;
+	theme: Theme;
+	tunnel: Tunnel;
+	keybindings: KeybindingsFiles;
+	agentStatus: AgentStatusDefaults;
+	terminalDefaults: TerminalDefaults;
+	tabs: TabDefaults;
+	bench: Bench;
+	files: FileReadLimits;
+	scratchpads: Scratchpads;
+	whiteboards: WhiteboardDefaults;
+	fanout: FanoutDefaults;
+	updates: Updates;
+	onboarding: Onboarding;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AppInfo".
+*/
+interface AppInfo {
+	/**
+	* Human-readable product name.
+	*/
+	name: string;
+	/**
+	* Reverse-DNS bundle identifier.
+	*/
+	identifier: string;
+	/**
+	* Semantic version string.
+	*/
+	version: string;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WindowDefaults".
+*/
+interface WindowDefaults {
+	defaultWidth: number;
+	defaultHeight: number;
+	minWidth: number;
+	minHeight: number;
+	/**
+	* Height in px of the custom draggable titlebar strip the frontend reserves above the content. Must clear the inset macOS traffic lights.
+	*/
+	titlebarHeight: number;
+	/**
+	* macOS traffic-light button inset in px from the top-left window corner, applied via tauri-plugin-decorum so the controls center vertically within the custom titlebar.
+	*/
+	trafficLightInset: number;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "EditorLaunchers".
+*/
+interface EditorLaunchers {
+	defaultEditorId: string;
+	options: EditorLauncher[];
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "EditorLauncher".
+*/
+interface EditorLauncher {
+	id: string;
+	name: string;
+	/**
+	* Iconify icon name, preferably from the simple-icons namespace for branded editors.
+	*/
+	brandIcon: string;
+	/**
+	* Hex color used to render the monochrome Iconify brand glyph.
+	*/
+	brandColor: string;
+	/**
+	* Executable name used to launch the editor with the worktree path. Null uses the system file explorer.
+	*/
+	cliCommand: string | null;
+}
+/**
+* Shared script execution limits used by project lifecycle scripts.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Scripts".
+*/
+interface Scripts {
+	/**
+	* Maximum number of headless project script commands Pragma runs at once. Interactive run scripts create terminal tabs and are not limited by this value.
+	*/
+	maxConcurrentCommands: number;
+	/**
+	* Project-root-relative POSIX path of the optional project script config file. Read by the Rust backend and matched against worktree file-watch events by the frontend to hot-reload script buttons.
+	*/
+	configPath: string;
+	/**
+	* Other agent orchestrators whose checked-in lifecycle-script config Pragma can import into `.pragma/scripts.json`. Order is the detection priority: when a project carries more than one, the first match wins.
+	*/
+	migrationSources: ScriptMigrationSource[];
+	/**
+	* Conventional-commit subject for the generated `.pragma/scripts.json` commit, written when the import prompt's commit toggle is on. The commit carries no trailers: the user is its sole author.
+	*/
+	migrationCommitMessage: string;
+}
+/**
+* One importable foreign script config: its identifier, display name, and the project-root-relative paths that identify it.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ScriptMigrationSource".
+*/
+interface ScriptMigrationSource {
+	/**
+	* Stable identifier the frontend sends back over IPC to import this source. Never a display string.
+	*/
+	id: string;
+	/**
+	* Tool name shown in the import prompt.
+	*/
+	label: string;
+	/**
+	* Project-root-relative POSIX paths this tool stores its lifecycle scripts in, in probe order.
+	*
+	* @minItems 1
+	*/
+	configPaths: [string, ...string[]];
+}
+/**
+* Shared agent-launch timing used by both the frontend's terminal-write scheduling and the Rust CLI/broker launch path.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Agents".
+*/
+interface Agents {
+	/**
+	* Delay before writing an agent's start command to a freshly spawned PTY, giving the shell time to become ready. There is no readiness signal from the PTY, so this is a best-effort fixed delay.
+	*/
+	startDelayMs: number;
+	/**
+	* Maximum extra wait for a bracketed-prefill agent to enter its alternate screen before the prompt is sent anyway.
+	*/
+	altScreenExtraWaitMs: number;
+	/**
+	* Delay after a late alternate-screen entry before sending the prompt, allowing the TUI input widget to mount.
+	*/
+	altScreenSettleMs: number;
+}
+/**
+* Per-operating-system launch defaults shared by the Rust session layer and the TypeScript settings UI. Values here are defaults only: a project may override them in its `.pragma/config.json`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Platform".
+*/
+interface Platform {
+	shells: DefaultShells;
+	wsl: Wsl;
+	defaultBackend: TerminalBackend;
+}
+/**
+* Fallback shell used when the environment names none. On macOS and Linux the `SHELL` environment variable wins when it is set; Windows has no such convention, so the candidate list is probed in order instead.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "DefaultShells".
+*/
+interface DefaultShells {
+	/**
+	* Shell launched on macOS when `SHELL` is unset.
+	*/
+	macos: string;
+	/**
+	* Shell launched on Linux when `SHELL` is unset.
+	*/
+	linux: string;
+	/**
+	* Windows shell candidates, probed in order and resolved against `PATH`. PowerShell 7+ (`pwsh.exe`) is preferred over the in-box Windows PowerShell (`powershell.exe`) because it ships the modern ConPTY behaviour; the last entry must be a shell that is present on every Windows install so resolution cannot fail.
+	*
+	* @minItems 1
+	*/
+	windows: [string, ...string[]];
+}
+/**
+* How the Windows client reaches a Linux `pragma-server` running inside a WSL distribution. The Windows side never translates `\\wsl$\` paths: the Linux server owns its own filesystem world and is addressed exactly like a remote host.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Wsl".
+*/
+interface Wsl {
+	/**
+	* Executable used to run a command inside a WSL distribution.
+	*/
+	launcher: string;
+	/**
+	* Arguments that list installed distributions with their state and WSL version. The output is UTF-16LE encoded, which the parser has to decode before splitting.
+	*/
+	listArgs: string[];
+	/**
+	* Name of the Linux `pragma-server` executable expected on the distribution's PATH, or installed by Pragma into the distribution when it is missing.
+	*/
+	serverBinary: string;
+}
+/**
+* Contract between the Pragma app and the detached PTY daemon.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Daemon".
+*/
+interface Daemon {
+	/**
+	* Internal daemon wire-protocol SemVer, spoken on Hello, `gateway.json` and `/v1/health`. Mirrored from crates/pragma-protocol's package version by `bun run generate`; do not edit by hand. Comparison is exact equality, and that is load-bearing: every peer here ships in one bundle, so a version that no longer matches is a stale process to evict, not a peer to negotiate with. Remote clients use `gateway.apiVersion` instead.
+	*/
+	protocolVersion: string;
+	/**
+	* File name of the server's local IPC endpoint inside the server directory. A Unix-domain socket on every supported platform: macOS and Linux use the kernel's AF_UNIX, Windows uses the AF_UNIX support present since Windows 10 build 17063. The server binds it and every native client connects to it, so the name must never be spelled out by hand on either side of the language boundary.
+	*/
+	socketFile: string;
+	/**
+	* File name of the startup lock the server holds inside the server directory, used to keep a second server from binding over a live one.
+	*/
+	lockFile: string;
+	/**
+	* File name the detached server writes its stdout and stderr to inside the server directory.
+	*/
+	logFile: string;
+}
+/**
+* Local HTTP gateway discovery and authentication constants shared by Rust gateway code and TypeScript clients.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Gateway".
+*/
+interface Gateway {
+	/**
+	* SemVer of the client-facing gateway HTTP contract, advertised in the pairing payload so a remote client can reject an incompatible host before it stores a connection. Deliberately NOT `daemon.protocolVersion`: that one is the internal daemon frame protocol and is bumped by every desktop release, whereas Pragma Go and the web build embed their copy of this value at build time and ship on their own cadence. Comparison is exact equality, so bump this only on a breaking change to the `/v1` API, and only in the same release as a client build that embeds the new value — a client that never launches cannot be updated first.
+	*/
+	apiVersion: string;
+	/**
+	* Filename written beside daemon.sock with gateway port, token, pid, and protocol version.
+	*/
+	discoveryFile: string;
+	/**
+	* Filename written beside daemon.sock holding the persistent 0600 bearer token, so the token survives gateway restarts and stays stable across paired devices until explicitly regenerated.
+	*/
+	tokenFile: string;
+	/**
+	* Filename written beside daemon.sock holding devices that successfully authenticated with the gateway.
+	*/
+	devicesFile: string;
+	/**
+	* HTTP authorization header name used for bearer-token authentication.
+	*/
+	tokenHeader: string;
+	/**
+	* HTTP headers carrying installation-scoped mobile device metadata.
+	*/
+	deviceHeaders: {
+		id: string;
+		name: string;
+		platform: string;
+		appVersion: string;
+	};
+	push: GatewayPush;
+	web: GatewayWeb;
+}
+/**
+* Expo push delivery constants. The gateway watches the agent status stream and pushes to every registered phone; the mobile app registers its Expo token through `/v1/push/tokens`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "GatewayPush".
+*/
+interface GatewayPush {
+	/**
+	* Expo push service endpoint the gateway POSTs batches of messages to.
+	*/
+	sendUrl: string;
+	/**
+	* Largest number of messages sent in one request; Expo documents 100 per call.
+	*/
+	batchSize: number;
+	/**
+	* How long a desktop presence heartbeat counts as current. While a heartbeat says the desktop is focused, phone pushes are suppressed — the user is already looking at the alert. A desktop that dies without blurring stops suppressing after this window.
+	*/
+	presenceTtlMs: number;
+	/**
+	* Accepted Expo push token prefixes. A token that matches none is rejected at registration rather than failing later inside Expo.
+	*/
+	tokenPrefixes: string[];
+}
+/**
+* Where the gateway serves the Pragma Go web bundle from, and how that bundle is staged. Shared so the Expo export, the staging script, the Rust static-file routes, and the desktop's shareable link all agree on one path.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "GatewayWeb".
+*/
+interface GatewayWeb {
+	/**
+	* Default access state for the public Pragma Go browser bundle. Users override it with gateway.webEnabled in the global config file.
+	*/
+	enabled: boolean;
+	/**
+	* URL prefix the exported web bundle is deployed and served under. Passed to Expo as `EXPO_BASE_URL` at time so the asset URLs baked into `index.html` match the routes the gateway answers.
+	*/
+	basePath: string;
+	/**
+	* Filename inside the staged bundle listing every servable asset with its URL path, content type, and encoding. The gateway serves only what this manifest names, so a request path is looked up as a map key and never joined onto a filesystem path.
+	*/
+	manifestFile: string;
+	/**
+	* Directory name under the desktop app's Tauri resources holding the staged bundle.
+	*/
+	resourceDir: string;
+}
+/**
+* Shared schema source of truth for the host-server RPC and subscription protocol. The frame codec itself lives in `pragma-protocol`; these values name the cross-language methods, events, and errors.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Protocol".
+*/
+interface Protocol {
+	rpcMethods: ProtocolRpcMethod[];
+	events: ProtocolEventKind[];
+	errors: ProtocolErrorCode[];
+}
+/**
+* GitHub integration contract: the secret-free OAuth Device Flow client id, scopes, and the endpoint URLs shared by the Rust backend (device flow + token exchange) and the frontend Octokit client.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "GitHub".
+*/
+interface GitHub {
+	/**
+	* Client id of the registered Pragma GitHub OAuth App (device flow enabled). No client secret — a distributed desktop app can't keep one secret.
+	*/
+	oauthClientId: string;
+	/**
+	* OAuth scopes requested during the device flow (e.g. `repo`).
+	*/
+	scopes: string[];
+	/**
+	* Endpoint that issues a device + user code (`POST https://github.com/login/device/code`).
+	*/
+	deviceCodeUrl: string;
+	/**
+	* Page the user opens to enter the user code (`https://github.com/login/device`).
+	*/
+	deviceVerifyUrl: string;
+	/**
+	* Endpoint polled to exchange an authorized device code for an access token.
+	*/
+	accessTokenUrl: string;
+	/**
+	* Base URL for the GitHub REST/GraphQL API (Octokit `baseUrl`).
+	*/
+	apiBaseUrl: string;
+	/**
+	* Pragma's public GitHub home page, linked from the pull-request signature footer.
+	*/
+	homepageUrl: string;
+	prSignature: PrSignature;
+}
+/**
+* The "Created with Pragma" footer appended to pull requests Pragma opens. The markers delimit the block so Pragma can strip it again when it renders a PR body, and so a body written by an older Pragma is still recognised.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "PrSignature".
+*/
+interface PrSignature {
+	/**
+	* Whether the footer is appended when the user has not configured `github.prSignature`.
+	*/
+	enabled: boolean;
+	/**
+	* HTML comment opening the footer block. Everything from here to `endMarker` is Pragma-owned and is stripped before the body is shown in Pragma.
+	*/
+	startMarker: string;
+	/**
+	* HTML comment closing the footer block.
+	*/
+	endMarker: string;
+	/**
+	* Text of the small "Open worktree" link rendered under the footer heading.
+	*/
+	linkLabel: string;
+	/**
+	* Web redirector the badge links to, which forwards its query string to the `pragma://open` deep link. GitHub's markdown sanitizer keeps only `http`/`https`/`mailto` hrefs, so a `pragma://` URL would render as inert text.
+	*/
+	openUrl: string;
+}
+/**
+* Plugin-system constants shared by the Rust config reader and the TypeScript loader.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Plugins".
+*/
+interface Plugins {
+	/**
+	* Relative path of the Pragma config file that declares plugin entries. Resolved against the home directory for global plugins and against the project root for project plugins.
+	*/
+	configFileName: string;
+	/**
+	* Plugin storage scopes supported by the host runtime. v1 persists global plugin key/value state; project scope is reserved for project-addressed plugin config/storage layers.
+	*/
+	storageScopes: ("global" | "project")[];
+}
+/**
+* Optional color-theme override file read by the desktop app. Shared so the Rust reader/writer and the TypeScript theme runtime agree on the file location and the color-scheme blocks it may declare.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Theme".
+*/
+interface Theme {
+	/**
+	* Relative path of the optional theme file. Resolved against the home directory for the global theme and against the project root for a project theme — the same layout rule as `plugins.configFileName`. Both files are optional; the app merges built-in defaults <- global <- project per token.
+	*/
+	fileName: string;
+	/**
+	* Color-scheme blocks a theme file may declare under `colors`. Each maps to the matching CSS variable block in the app stylesheet (`:root` for light, `.dark` for dark).
+	*/
+	modes: ("light" | "dark")[];
+}
+/**
+* Defaults for the remote-access tunnel that exposes the local HTTP gateway to a paired mobile device. A user overrides these per-install via the `tunnel` key in `~/.pragma/config.json`. Shared so the Rust tunnel supervisor and any TypeScript config UI agree on the shipped defaults.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Tunnel".
+*/
+interface Tunnel {
+	/**
+	* Default tunnel command template. `{port}` is the only substitution and is replaced with the live gateway port. Ships targeting ngrok's JSON log output.
+	*/
+	defaultCommand: string;
+	/**
+	* Default regular expression whose first capture group is the public tunnel URL, matched against both stdout and stderr lines. Covers ngrok's JSON `"url":"https://…"` log and plain `https://…` URLs (e.g. cloudflared).
+	*/
+	defaultUrlPattern: string;
+}
+/**
+* Location of the editable keybindings file. Resolved against the home directory for global bindings and against the project root for project bindings, so Rust and the Settings UI agree on one path.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "KeybindingsFiles".
+*/
+interface KeybindingsFiles {
+	/**
+	* Relative path of the keybindings file (e.g. `.pragma/keybindings.json`). A project file only needs the actions it overrides; missing actions fall back to the global file, then to the built-in defaults.
+	*/
+	configFileName: string;
+}
+/**
+* Shipped defaults and limits for agent alert notifications and sounds. A user overrides these per install/project via the `agentStatus` key of `.pragma/config.json`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentStatusDefaults".
+*/
+interface AgentStatusDefaults {
+	/**
+	* Relative directory scanned for alert sounds. Resolved against the home directory for global sounds and against the project root for project sounds.
+	*/
+	soundsDirName: string;
+	/**
+	* Longest allowed alert clip. Longer uploads are rejected rather than truncated.
+	*/
+	maxSoundSeconds: number;
+	/**
+	* Largest allowed alert clip in bytes, bounding what crosses IPC when a clip is imported or played.
+	*/
+	maxSoundBytes: number;
+	/**
+	* Lower-case file extensions (no dot) treated as alert sounds when listing the sounds directory.
+	*/
+	soundExtensions: string[];
+	/**
+	* Whether platform notifications fire for agent alerts when the user has not configured `agentStatus.notificationsEnabled`.
+	*/
+	notificationsEnabled: boolean;
+	notificationText: AgentNotificationText;
+}
+/**
+* Templates for the text of an agent alert. Rendered identically by the desktop toast, the desktop platform notification, and the Expo push the gateway sends to a paired phone, so all three read the same. `{agent}`, `{project}`, `{worktree}`, and `{tab}` are substituted; no other placeholder is recognised.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentNotificationText".
+*/
+interface AgentNotificationText {
+	/**
+	* Title when the agent finished its turn. Takes `{agent}`.
+	*/
+	doneTitle: string;
+	/**
+	* Title when the agent needs attention for an unclassified reason. Takes `{agent}`.
+	*/
+	attentionTitle: string;
+	/**
+	* Title when the agent is waiting for an answer. Takes `{agent}`.
+	*/
+	questionTitle: string;
+	/**
+	* Title when the agent is asking to run a command. Takes `{agent}`.
+	*/
+	commandTitle: string;
+	/**
+	* Joins the project and worktree names in the body line.
+	*/
+	locationSeparator: string;
+	/**
+	* Appended to the body when the reporting tab has a name of its own. Takes `{tab}`.
+	*/
+	tabSuffix: string;
+	/**
+	* Body used when neither the project nor the worktree could be resolved — a report can arrive for a worktree the client has not loaded yet.
+	*/
+	unknownLocation: string;
+}
+/**
+* Shipped defaults for terminal launching. A user overrides these per install/project via the `terminal` key of `.pragma/config.json` (`TerminalSettings`).
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "TerminalDefaults".
+*/
+interface TerminalDefaults {
+	/**
+	* WSL distribution names hidden from the shell picker by default because they back other tools rather than interactive shells (Docker Desktop's VM distros).
+	*/
+	hiddenDistros: string[];
+	/**
+	* Whether a plain new tab defaults to the shell profile most recently picked for that project instead of the configured default terminal.
+	*/
+	rememberLastShell: boolean;
+	/**
+	* Largest file (typically an image) that may be dropped onto a terminal. The bytes are copied to the host that runs the PTY in one `filesystem` RPC, so this plus its base64 expansion must stay inside the protocol's frame limit.
+	*/
+	maxDroppedFileBytes: number;
+	/**
+	* Directory under the host's temporary directory that holds copies of files dropped onto a terminal, whose absolute paths are pasted into the PTY.
+	*/
+	droppedFilesDirName: string;
+	/**
+	* How long a per-drop directory under `droppedFilesDirName` may sit on disk before a sweep deletes it. The host sweeps once at startup and on a fixed interval after that (`DROPPED_FILES_SWEEP_INTERVAL` in `pragma-server`), so a drop is retained for at most this age plus one sweep interval.
+	*/
+	droppedFilesMaxAgeMs: number;
+}
+/**
+* Shipped tab defaults shared by the desktop app and any host that has to reason about a tab's name.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "TabDefaults".
+*/
+interface TabDefaults {
+	/**
+	* Fallback title per tab kind, used for a tab whose shell or page has not named itself. A tab still carrying its default title has no name worth showing in a notification, so both languages compare against these.
+	*/
+	defaultTitles: {
+		fallback: string;
+		browser: string;
+		log: string;
+		scratchpad: string;
+		whiteboard: string;
+		prReview: string;
+		pluginWebview: string;
+	};
+}
+/**
+* Names the terminal benchmark (`@pragma-sh/bench`) and the desktop app agree on. The app installs the hook global in dev builds only; the benchmark's injected runner reads it back by the same name.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Bench".
+*/
+interface Bench {
+	/**
+	* `window` property under which a dev build exposes read-only access to its live xterm instances. Absent in production builds.
+	*/
+	hookGlobal: string;
+	/**
+	* `window` property the benchmark installs its own injected scenario runner under. Owned by the benchmark, never by the app.
+	*/
+	runnerGlobal: string;
+	/**
+	* Leading token of the status line the `pragma-bench tui` payload paints on its first row. The runner scans painted frames for it to learn which input the terminal has finished rendering.
+	*/
+	markerPrefix: string;
+	/**
+	* Title given to the terminal tab the benchmark opens, so a run is identifiable in the UI and reclaimable after a crash.
+	*/
+	tabTitle: string;
+}
+/**
+* Limits for reading a binary file in chunks over the `filesystem` RPC. A single chunk plus its base64 expansion must stay well inside the protocol's frame limit, so the host rejects any request for more than `chunkBytes` at once and the frontend loops until the whole file is read.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FileReadLimits".
+*/
+interface FileReadLimits {
+	/**
+	* Largest number of raw bytes one `readBytesRange` request may return. Base64 inflates this by 4/3 on the wire.
+	*/
+	chunkBytes: number;
+	/**
+	* Largest binary file a viewer will assemble in memory from chunks. Bigger files are refused with a message instead of exhausting the webview's heap.
+	*/
+	maxBinaryBytes: number;
+}
+/**
+* Managed scratchpad file contract shared by the CLI, desktop host, and editor.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Scratchpads".
+*/
+interface Scratchpads {
+	directory: string;
+	extension: string;
+	frontmatterKey: string;
+	version: number;
+}
+/**
+* Host persistence and validation limits for worktree-scoped whiteboards.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WhiteboardDefaults".
+*/
+interface WhiteboardDefaults {
+	databaseFile: string;
+	defaultTitle: string;
+	maxTitleChars: number;
+	maxSceneBytes: number;
+	maxRenderDimension: number;
+}
+/**
+* Shipped defaults for fanout orchestration: the host state file, attempt branch naming, the member floor, and follow-up delivery timeouts. Both `pragma-server` and the desktop read these instead of hard-coding either side.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutDefaults".
+*/
+interface FanoutDefaults {
+	/**
+	* Owner-only durable fanout record, written beside the server socket.
+	*/
+	stateFile: string;
+	/**
+	* Leading segment of every generated attempt branch (`<prefix>/<fanout>/<member>`).
+	*/
+	branchPrefix: string;
+	/**
+	* Fewest attempts a fanout may have. A single attempt is an ordinary agent launch.
+	*/
+	minMembers: number;
+	/**
+	* Default bound on concurrently launching attempts.
+	*/
+	defaultJobs: number;
+	/**
+	* How long a waiting follow-up send waits for each member's delivery receipt.
+	*/
+	deliveryTimeoutMs: number;
+	/**
+	* Environment variable exported into every attempt session with the owning fanout id.
+	*/
+	envFanoutId: string;
+	/**
+	* Environment variable exported into every attempt session with its member id.
+	*/
+	envMemberId: string;
+}
+/**
+* Shipped defaults for desktop auto-updates. User overrides live in global `.pragma/config.json` under `updates`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Updates".
+*/
+interface Updates {
+	/**
+	* Production Next.js check endpoint. Dev builds use `devCheckUrl` unless user overrides `other.serverUrl`.
+	*/
+	checkUrl: string;
+	/**
+	* Check endpoint used by `pragma-dev-*` builds so they never poll production.
+	*/
+	devCheckUrl: string;
+	/**
+	* How often a production (or opted-in) session re-checks for an update.
+	*/
+	pollIntervalMs: number;
+	/**
+	* Default for whether the desktop polls on launch and on an interval.
+	*/
+	autoDownload: boolean;
+	/**
+	* GitHub Release asset name for the per-release manifest.
+	*/
+	manifestFile: string;
+	/**
+	* Directory name under the instance data dir that holds the optional UI overlay (`<data>/<uiDirName>/<version>/`).
+	*/
+	uiDirName: string;
+	/**
+	* Sidebar button that applies a downloaded (or on-click) update.
+	*/
+	buttonLabel: string;
+	/**
+	* Link label for the GitHub Release notes URL.
+	*/
+	changelogLabel: string;
+	/**
+	* Modal title shown before a restart (installer) update.
+	*/
+	restartWarningTitle: string;
+	/**
+	* Modal body warning that the app server restarts and terminals stop.
+	*/
+	restartWarningBody: string;
+	/**
+	* Supported apply modes, in display order.
+	*
+	* @minItems 2
+	*/
+	applyModes: [UpdateApplyMode, UpdateApplyMode, ...UpdateApplyMode[]];
+	/**
+	* Installer platform ids the check API accepts.
+	*
+	* @minItems 1
+	*/
+	platforms: [UpdatePlatform, ...UpdatePlatform[]];
+}
+/**
+* Shipped values for the first-run onboarding flow: where its preview videos stream from, and which global skill directories the skills step can install into.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Onboarding".
+*/
+interface Onboarding {
+	/**
+	* Base URL the onboarding preview videos are streamed from (the marketing site's `public/media`). Videos are streamed rather than bundled so installers stay small.
+	*/
+	mediaBaseUrl: string;
+	skill: OnboardingSkill;
+}
+/**
+* The Pragma skill offered during onboarding and the global directories it can be installed into.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "OnboardingSkill".
+*/
+interface OnboardingSkill {
+	/**
+	* Directory name the skill is written as, inside each target directory.
+	*/
+	id: string;
+	/**
+	* Install destinations offered by the skills step.
+	*/
+	targets: OnboardingSkillTarget[];
+}
+/**
+* One skill install destination. The frontend sends `id` over IPC; the backend resolves `directory` against the home directory.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "OnboardingSkillTarget".
+*/
+interface OnboardingSkillTarget {
+	/**
+	* Stable identifier sent over IPC.
+	*/
+	id: string;
+	/**
+	* Directory holding the skill, relative to the user's home directory.
+	*/
+	directory: string;
+	/**
+	* Button label shown in onboarding.
+	*/
+	label: string;
+}
+/**
+* One failure attached to a fanout or a single member.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutFailure".
+*/
+interface FanoutFailure {
+	code: FanoutFailureCode;
+	message: string;
+	/**
+	* Member the failure belongs to, or null for a fanout-wide failure.
+	*/
+	memberId?: string | null;
+	/**
+	* Finalize stage the failure happened in, when it happened during a pick.
+	*/
+	stage?: FanoutFinalizeStage | null;
+}
+/**
+* One requested attempt before resolution. `selector` is the raw `agent[.model[.reasoning]]` text a CLI caller typed; a structured caller may instead set the fields directly. Duplicate selectors are valid — sampling one model twice is a supported use.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutMemberSelector".
+*/
+interface FanoutMemberSelector {
+	/**
+	* Raw selector text: a catalog agent id optionally followed by `.<modelId>` and `.<reasoningId>`.
+	*/
+	selector: string;
+	/**
+	* Explicit model id, overriding anything parsed out of `selector`.
+	*/
+	modelId?: string | null;
+	/**
+	* Explicit reasoning id, overriding both `selector` and the request-wide default.
+	*/
+	reasoningId?: string | null;
+}
+/**
+* One durable fanout attempt: a worktree branched from the fanout's captured base commit, plus the agent-owned terminal tab running in it.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutMember".
+*/
+interface FanoutMember {
+	id: string;
+	/**
+	* Stable creation order, so the comparison grid column order never shuffles.
+	*/
+	ordinal: number;
+	/**
+	* The selector text this member was created from, retained for retry and display.
+	*/
+	selector: string;
+	/**
+	* Fully qualified plugin catalog id (`plugin.agent`) used to resolve launch metadata.
+	*/
+	catalogAgentId: string;
+	/**
+	* Runtime reporter/watcher id the agent event stream is keyed by. Never derive this at a call site — the host resolves it from the plugin's watcher metadata.
+	*/
+	runtimeAgentId: string;
+	modelId: string | null;
+	reasoningId: string | null;
+	branch: string;
+	worktreeId: string | null;
+	tabId: string | null;
+	/**
+	* Tabs this member previously ran in. A retry moves the current tab id here.
+	*/
+	priorTabIds: string[];
+	status: FanoutMemberStatus;
+	failure: FanoutFailure | null;
+}
+/**
+* One durable fanout: a single parent worktree, an immutable base commit, one shared prompt, and N isolated attempts. A parent may own at most one fanout that is not in a terminal state.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Fanout".
+*/
+interface Fanout {
+	id: string;
+	projectId: string;
+	parentWorktreeId: string;
+	/**
+	* Worktree a newly-created coordination parent was branched from; null when an existing parent was used.
+	*/
+	sourceWorktreeId: string | null;
+	/**
+	* True when this fanout created its own parent worktree.
+	*/
+	ownsParent: boolean;
+	/**
+	* Exact parent HEAD captured at creation. Every attempt branches from it and every comparison diffs against it, even after the parent moves on.
+	*/
+	baseCommit: string;
+	title: string;
+	prompt: string;
+	status: FanoutStatus;
+	winningMemberId: string | null;
+	finalizeStage: FanoutFinalizeStage | null;
+	failure?: FanoutFailure | null;
+	members: FanoutMember[];
+	createdAt: string;
+	updatedAt: string;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutExistingParent".
+*/
+interface FanoutExistingParent {
+	kind: "existing";
+	worktreeId: string;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutNewParent".
+*/
+interface FanoutNewParent {
+	kind: "new";
+	sourceWorktreeId: string;
+	branch: string;
+	title?: string | null;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutCreateRequest".
+*/
+interface FanoutCreateRequest {
+	projectId: string;
+	parent: FanoutParentSpec;
+	prompt: string;
+	/**
+	* Display title. Derived from the prompt's first line when omitted.
+	*/
+	title?: string | null;
+	/**
+	* Reasoning effort applied to every member that does not name its own.
+	*/
+	defaultReasoningId?: string | null;
+	members: FanoutMemberSelector[];
+	/**
+	* Bound on concurrently launching attempts. Git worktree mutations are serialized regardless.
+	*/
+	jobs?: number | null;
+	/**
+	* Repeating a create with the same key returns the existing fanout instead of provisioning a second one.
+	*/
+	idempotencyKey?: string | null;
+}
+/**
+* Addresses one fanout by exactly one of its id or any worktree that belongs to it (its parent, or any attempt).
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutRef".
+*/
+interface FanoutRef {
+	fanoutId?: string | null;
+	worktreeId?: string | null;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutReadRequest".
+*/
+interface FanoutReadRequest {
+	fanoutId?: string | null;
+	worktreeId?: string | null;
+	memberId?: string | null;
+	all?: boolean | null;
+	lines?: number | null;
+}
+/**
+* One member's terminal output. `text` is the escape-stripped rendering; `data` is the same bounded window as base64 raw bytes, which the SDK decodes to a Uint8Array.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutReadTarget".
+*/
+interface FanoutReadTarget {
+	memberId: string;
+	worktreeId: string;
+	tabId: string;
+	runtimeAgentId: string;
+	bytes: number;
+	text: string;
+	data: string;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutReadResult".
+*/
+interface FanoutReadResult {
+	fanoutId: string;
+	targets: FanoutReadTarget[];
+}
+/**
+* Who a follow-up goes to: every live member, or one stable member id.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutSendTarget".
+*/
+interface FanoutSendTarget {
+	kind: "all" | "member";
+	memberId?: string | null;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutSendRequest".
+*/
+interface FanoutSendRequest {
+	fanoutId?: string | null;
+	worktreeId?: string | null;
+	target: FanoutSendTarget;
+	message: string;
+	/**
+	* Caller-supplied id making a retry idempotent: a message already delivered under this id is not typed twice.
+	*/
+	messageId?: string | null;
+	/**
+	* Wait for bounded per-member receipts (the default) instead of returning after durable enqueue.
+	*/
+	waitForDelivery?: boolean | null;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutDeliveryReceipt".
+*/
+interface FanoutDeliveryReceipt {
+	memberId: string;
+	worktreeId: string;
+	tabId: string;
+	runtimeAgentId: string;
+	messageId: string;
+	state: FanoutDeliveryState;
+	error?: string | null;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutSendResult".
+*/
+interface FanoutSendResult {
+	fanoutId: string;
+	messageId: string;
+	receipts: FanoutDeliveryReceipt[];
+}
+/**
+* Addresses one member of one fanout — used by retry and pick.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutMemberRequest".
+*/
+interface FanoutMemberRequest {
+	fanoutId?: string | null;
+	worktreeId?: string | null;
+	memberId: string;
+}
+/**
+* The durable fanout after a mutation, plus any failures that did not abort it. `partial` is true when at least one member failed while others stayed healthy.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutResult".
+*/
+interface FanoutResult {
+	fanout: Fanout;
+	partial: boolean;
+	failures: FanoutFailure[];
+}
+/**
+* Outcome of the destructive pick transaction. A conflicted or partly-cleaned pick still returns the durable fanout so a caller can resume from `stage`.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutPickResult".
+*/
+interface FanoutPickResult {
+	fanout: Fanout;
+	stage: FanoutFinalizeStage;
+	winningMemberId: string;
+	/**
+	* Commit created from the winner's uncommitted changes, when there were any.
+	*/
+	commit?: string | null;
+	/**
+	* Parent-relative paths the winner's scratchpads were promoted to.
+	*/
+	promotedScratchpads: string[];
+	deletedWorktreeIds: string[];
+	/**
+	* Attempt worktrees cleanup could not remove. Non-empty means `cleanupFailed`, never `completed`.
+	*/
+	survivingWorktreeIds: string[];
+	failures: FanoutFailure[];
+}
+/**
+* Snapshot and delta payload of the `fanouts` subscription. v1 keeps deltas trivial: every delta is a full replacement of the host's fanout set.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FanoutSubscriptionPayload".
+*/
+interface FanoutSubscriptionPayload {
+	fanouts: Fanout[];
+}
+/**
+* Result of a fetch + ahead/behind comparison against the upstream of a worktree's branch — the create-PR pre-flight.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "BranchSyncStatus".
+*/
+interface BranchSyncStatus {
+	/**
+	* The worktree's current branch.
+	*/
+	branch: string;
+	/**
+	* Commits the local branch is ahead of its upstream.
+	*/
+	ahead: number;
+	/**
+	* Commits the local branch is behind its upstream. Non-zero blocks PR creation.
+	*/
+	behind: number;
+	/**
+	* True when the branch already tracks a remote upstream; false means it must be pushed first.
+	*/
+	hasUpstream: boolean;
+}
+/**
+* One concrete choice of shell world for a terminal session: the resolved form of a `TerminalSettings` default, or the profile a single tab was opened with. Carried on the spawn request so the session layer launches the same shell the picker named, and persisted on the tab so a respawned session keeps it.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ShellProfile".
+*/
+interface ShellProfile {
+	backend: TerminalBackend;
+	/**
+	* WSL distribution launched when `backend` is `wsl`. Null uses the distribution WSL itself marks as default. Always null for `native`.
+	*/
+	distro?: string | null;
+}
+/**
+* One selectable reasoning-effort level for an agent model. Promoted from @pragma-sh/plugin so the catalog wire type has one source of truth.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentReasoning".
+*/
+interface AgentReasoning {
+	id: string;
+	name: string;
+}
+/**
+* One selectable model for an agent, with optional reasoning levels.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentModelEntry".
+*/
+interface AgentModelEntry {
+	id: string;
+	name: string;
+	reasoning?: AgentReasoning[];
+}
+/**
+* Reference to a plugin-contributed agent icon asset, fetched by content hash through the gateway `/v1/assets/{hash}` route.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentIcon".
+*/
+interface AgentIcon {
+	/**
+	* Lowercase-hex sha256 of the icon bytes; also the ETag and cache key.
+	*/
+	hash: string;
+	/**
+	* Icon MIME type (e.g. `image/svg+xml`).
+	*/
+	mime: string;
+}
+/**
+* One launchable agent in the resolved plugin catalog.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "CatalogAgent".
+*/
+interface CatalogAgent {
+	id: string;
+	name: string;
+	/**
+	* Id of the plugin that contributed this agent.
+	*/
+	pluginId: string;
+	/**
+	* Where the contributing plugin was resolved from. A `project` agent belongs to exactly one project root and must not be offered to another one.
+	*/
+	scope?: "global" | "project" | null;
+	/**
+	* Absolute root the contributing plugin was resolved from: the project root for `project` scope or the home directory for `global`.
+	*/
+	root?: string | null;
+	/**
+	* Runtime reporter/watcher id the agent event stream is keyed by, when the plugin declares a watcher. Callers must use this rather than re-deriving an id from the dotted catalog id.
+	*/
+	runtimeAgentId?: string | null;
+	icon?: AgentIcon | null;
+	models: AgentModelEntry[];
+	/**
+	* Capabilities the agent declares unsupported; agent verification skips matching scenarios.
+	*/
+	excludeFeatures?: AgentFeature[];
+	launch: AgentLaunchConfig;
+}
+/**
+* Resolved launch commands and terminal-input behavior needed by the persistent host to start an agent without a desktop webview.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentLaunchConfig".
+*/
+interface AgentLaunchConfig {
+	commands: AgentLaunchCommand[];
+	startupInput?: AgentStartupInput[];
+	prefillDelayMs?: number;
+	prefillMode?: "bracketed" | "plain";
+	prefillSubmit?: string;
+	prefillSubmitDelayMs?: number;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentLaunchCommand".
+*/
+interface AgentLaunchCommand {
+	modelId: string | null;
+	reasoningId: string | null;
+	command: string[];
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentStartupInput".
+*/
+interface AgentStartupInput {
+	delayMs: number;
+	data: string;
+}
+/**
+* The resolved set of launchable agents contributed by all loaded plugins, assembled by the pragma-plugins sidecar and cached by pragma-server.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentCatalog".
+*/
+interface AgentCatalog {
+	agents: CatalogAgent[];
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Project".
+*/
+interface Project {
+	id: string;
+	name: string;
+	path: string;
+	/**
+	* User-chosen emoji shown in the project switcher; null falls back to a favicon found in the checkout, then to the project name's initial.
+	*/
+	iconEmoji: string | null;
+	orderIndex: number;
+	createdAt: string;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Worktree".
+*/
+interface Worktree {
+	id: string;
+	projectId: string;
+	parentId: string | null;
+	branch: string;
+	title: string | null;
+	path: string;
+	isMain: boolean;
+	/**
+	* True when the user has hidden this worktree from the sidebar. Persists across restarts.
+	*/
+	hidden: boolean;
+	createdAt: string;
+}
+/**
+* A managed scratchpad plus its MDX source and attached-agent metadata, as served by the host's `scratchpads` RPC to clients that render the document themselves.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ScratchpadFile".
+*/
+interface ScratchpadFile {
+	id: string;
+	title: string;
+	/**
+	* Worktree-relative POSIX path to the scratchpad's MDX file.
+	*/
+	filePath: string;
+	/**
+	* The full MDX source, frontmatter included.
+	*/
+	contents: string;
+	/**
+	* Terminal tab id this scratchpad prompts, or null when nothing is attached.
+	*/
+	agentTabId: string | null;
+	/**
+	* Catalog agent id of the attached tab, or null when nothing is attached.
+	*/
+	agentId: string | null;
+	/**
+	* Epoch milliseconds the scratchpad was created, from its managed frontmatter.
+	*/
+	createdAt: number;
+}
+/**
+* Serializable Excalidraw scene. Core fields are validated while element, app-state, and binary-file extensions remain forward compatible with Excalidraw releases.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ExcalidrawScene".
+*/
+interface ExcalidrawScene {
+	type: "excalidraw";
+	version: number;
+	source?: string;
+	elements: {
+		id: string;
+		type: string;
+		[k: string]: unknown;
+	}[];
+	appState: {
+		[k: string]: unknown;
+	};
+	files: {
+		[k: string]: unknown;
+	};
+}
+/**
+* One durable worktree-scoped Excalidraw document.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Whiteboard".
+*/
+interface Whiteboard {
+	id: string;
+	worktreeId: string;
+	title: string;
+	scene: ExcalidrawScene;
+	version: number;
+	createdAt: number;
+	updatedAt: number;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WhiteboardCreateInput".
+*/
+interface WhiteboardCreateInput {
+	worktreeId: string;
+	title: string;
+	scene: ExcalidrawScene;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WhiteboardEditInput".
+*/
+interface WhiteboardEditInput {
+	worktreeId: string;
+	id: string;
+	title: string;
+	scene: ExcalidrawScene;
+	expectedVersion: number;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WhiteboardListInput".
+*/
+interface WhiteboardListInput {
+	worktreeId: string;
+	query?: string;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WhiteboardIdInput".
+*/
+interface WhiteboardIdInput {
+	worktreeId: string;
+	id: string;
+}
+/**
+* Base64-encoded PNG rendering of one whiteboard.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WhiteboardViewResult".
+*/
+interface WhiteboardViewResult {
+	data: string;
+}
+/**
+* One tool call surfaced by an agent message.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentToolCall".
+*/
+interface AgentToolCall {
+	id: string;
+	name: string;
+	status: AgentToolCallStatus;
+	summary?: string;
+}
+/**
+* A path touched by an agent, without file contents.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentFileChange".
+*/
+interface AgentFileChange {
+	path: string;
+	change: AgentFileChangeKind;
+}
+/**
+* Append-only rich message entry reported by an agent. Consumers upsert by id when tool-call state changes.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentMessage".
+*/
+interface AgentMessage {
+	agent: string;
+	worktreeId: string;
+	tabId: string;
+	id: string;
+	role: AgentMessageRole;
+	text?: string;
+	toolCalls?: AgentToolCall[];
+	files?: AgentFileChange[];
+	/**
+	* Count of active sub-agents visible to the reporting plugin; no nested transcript is carried.
+	*/
+	subAgentsActive: number;
+	/**
+	* Emitter timestamp in milliseconds since Unix epoch.
+	*/
+	ts: number;
+}
+/**
+* Status report sent by pragma-cli through pragma-server to native clients.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentReportPayload".
+*/
+interface AgentReportPayload {
+	agent: string;
+	worktreeId: string;
+	tabId: string;
+	/**
+	* New agent status, or null for a status-less report (e.g. a `session-name` rename) that must leave the stored status untouched.
+	*/
+	status: AgentStatus | null;
+	/**
+	* Human-readable name of the agent's active session. Reported on session create/rename/switch; the client renames the hosting tab unless the user renamed it manually.
+	*/
+	sessionName?: string;
+	attentionKind?: AgentAttentionKind | null;
+	/**
+	* The command (or tool invocation) the agent is asking permission to run. Set when attentionKind is `command` so a non-terminal client can show it and approve remotely.
+	*/
+	command?: string;
+	/**
+	* The question the agent is asking. Set when attentionKind is `question` so a non-terminal client can show it and answer remotely.
+	*/
+	question?: string;
+	/**
+	* Answer choices for a `question` attention. Empty/omitted when the question is free-text only or when attentionKind is `command`.
+	*/
+	options?: QuestionOption[];
+	/**
+	* Multiple questions for a `question` attention. When present, clients render a back/next question wizard and submit every answer together; the legacy `question`/`options` fields are still used for a single question.
+	*/
+	questions?: AgentQuestion[];
+	/**
+	* Correlation id for a command-approval or question round-trip. The reporter sets it on a `command`/`question` attention report and waits for a matching AgentDecision/AgentAnswer before proceeding.
+	*/
+	requestId?: string;
+}
+/**
+* A selectable answer to an agent question.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "QuestionOption".
+*/
+interface QuestionOption {
+	/**
+	* Answer text sent back to the agent when selected.
+	*/
+	label: string;
+	/**
+	* Optional explanation shown beneath the answer label.
+	*/
+	description?: string;
+}
+/**
+* One question in a multi-question attention request. Each entry carries its own prompt and optional answer choices.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentQuestion".
+*/
+interface AgentQuestion {
+	/**
+	* The question the agent is asking.
+	*/
+	question: string;
+	/**
+	* Answer choices for this question. Empty/omitted when the question is free-text only.
+	*/
+	options?: QuestionOption[];
+}
+/**
+* Approve/deny verdict for a command-approval request, published by the controlling client and fanned out to agent subscribers. The waiting reporter (a blocking harness hook or a plugin watcher) matches it by requestId.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentDecision".
+*/
+interface AgentDecision {
+	agent: string;
+	worktreeId: string;
+	tabId: string;
+	requestId: string;
+	/**
+	* true to run the command, false to reject it.
+	*/
+	approved: boolean;
+}
+/**
+* Reply to a `question` attention request, published by the controlling client and fanned out to agent subscribers. The waiting reporter (a blocking harness hook or a plugin watcher) matches it by requestId.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentAnswer".
+*/
+interface AgentAnswer {
+	agent: string;
+	worktreeId: string;
+	tabId: string;
+	requestId: string;
+	/**
+	* The reply text. Present when the question was answered; omitted when dismissed.
+	*/
+	answer?: string;
+	/**
+	* true when the question was dismissed without an answer.
+	*/
+	dismissed: boolean;
+}
+/**
+* Free-form input (an interjection) sent by the controlling client to a running agent and fanned out to agent subscribers. A blocking harness hook or a plugin watcher delivers `text` into the agent's turn (via a harness input API, or by writing it to the tab's PTY). Unlike AgentDecision/AgentAnswer this is not tied to an outstanding request; `requestId` is optional and only set when the interjection answers a specific prompt.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentInput".
+*/
+interface AgentInput {
+	agent: string;
+	worktreeId: string;
+	tabId: string;
+	/**
+	* The message text to deliver to the running agent.
+	*/
+	text: string;
+	/**
+	* Optional correlation id when the interjection answers a specific outstanding prompt.
+	*/
+	requestId?: string;
+}
+/**
+* Transient request to interrupt a running agent's current turn, published by the controlling client and fanned out to agent subscribers. Delivery is best-effort with no replay buffer: a watcher subscribed to the matching tab sends an interrupt (ESC) to the agent's PTY. Unlike AgentDecision/AgentAnswer it is not required to carry a requestId.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentInterrupt".
+*/
+interface AgentInterrupt {
+	agent: string;
+	worktreeId: string;
+	tabId: string;
+	/**
+	* Optional correlation id when the interrupt targets a specific outstanding request.
+	*/
+	requestId?: string;
+}
+/**
+* Mirror of the desktop app's entire workspace state (all projects, worktrees, and tabs), published to pragma-server so remote clients (e.g. a paired phone) can render the session launcher without registering as the controller. The desktop publishes the full snapshot on every mutation; v1 keeps deltas trivial (every delta is a full replacement).
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WorkspaceSnapshot".
+*/
+interface WorkspaceSnapshot {
+	projects: Project[];
+	worktrees: Worktree[];
+	tabs: Tab[];
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "Tab".
+*/
+interface Tab {
+	id: string;
+	projectId: string;
+	worktreeId: string;
+	kind: TabKind;
+	title: string | null;
+	/**
+	* The current page URL for browser tabs; null for terminal tabs.
+	*/
+	url: string | null;
+	/**
+	* Worktree-relative path for editor/diff tabs; null for terminal/browser tabs.
+	*/
+	filePath: string | null;
+	/**
+	* Durable whiteboard id for whiteboard tabs; null for every other tab kind.
+	*/
+	whiteboardId: string | null;
+	/**
+	* Which diff side a diff tab shows; null for non-diff tabs.
+	*/
+	diffSide: DiffSide | null;
+	/**
+	* Commit hash a commit-scoped diff tab shows (first parent → commit); null for range diffs and non-diff tabs.
+	*/
+	diffCommit: string | null;
+	/**
+	* Pull-request number a pr-review tab reviews; null for non-PR tabs.
+	*/
+	prNumber: number | null;
+	/**
+	* Owning plugin id for plugin-webview tabs; null for non-plugin tabs.
+	*/
+	pluginId: string | null;
+	/**
+	* Plugin-defined web view id for plugin-webview tabs; null for non-plugin tabs.
+	*/
+	pluginViewId: string | null;
+	/**
+	* JSON-encoded payload supplied when opening a plugin-webview tab; null when omitted or for non-plugin tabs.
+	*/
+	pluginPayload: string | null;
+	/**
+	* Optional dedupe key used to focus an existing plugin-webview tab instead of opening another.
+	*/
+	pluginDedupeKey: string | null;
+	/**
+	* Catalog id of the agent launched into this terminal tab, set at launch time. Drives the tab's agent icon and default title; null for tabs without an agent.
+	*/
+	agentId: string | null;
+	/**
+	* True once the user has manually renamed a terminal tab via double-click/context menu. Shell-emitted title updates (OSC 0/2) and agent session-name renames are ignored while this is true. Always false for non-terminal tabs.
+	*/
+	userRenamed: boolean;
+	/**
+	* Fanout this terminal tab is an attempt of. Optional rather than nullable: absent on every tab that is not a fanout attempt.
+	*/
+	fanoutId?: string | null;
+	/**
+	* Fanout member this terminal tab runs. Always set together with `fanoutId`.
+	*/
+	fanoutMemberId?: string | null;
+	/**
+	* Shell profile this terminal tab was opened with, so a session respawned after a daemon restart returns to the same shell instead of the current default. Optional rather than nullable: absent on every tab created before shell selection existed, and on non-terminal tabs.
+	*/
+	shell?: ShellProfile | null;
+	orderIndex: number;
+	createdAt: string;
+}
+/**
+* Payload for the brokered `agentSessionLaunch` control method. The desktop creates or resolves the target worktree + tab, replies with `{ worktreeId, tabId }` immediately, then asynchronously spawns the agent + watcher through the proven Kanban background-launch sequence. Either an existing `worktreeId` or a `newWorktree` spec must be provided.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "AgentSessionLaunchPayload".
+*/
+interface AgentSessionLaunchPayload {
+	projectId: string;
+	/**
+	* Id of an existing worktree to launch into. Mutually exclusive with `newWorktree`.
+	*/
+	worktreeId: string | null;
+	/**
+	* Describes a fresh worktree to create when `worktreeId` is absent. Mutually exclusive with `worktreeId`.
+	*/
+	newWorktree: NewWorktreeSpec | null;
+	agentId: string;
+	modelId?: string | null;
+	reasoningId?: string | null;
+	/**
+	* Raw shell snippet appended to the agent's base launch command instead of catalog model/reasoning args (for example `--model moonshot/kimi-k3`). Overrides `modelId`/`reasoningId` when set.
+	*/
+	modelCmd?: string | null;
+	prompt?: string | null;
+	/**
+	* When true, the host server launches the session itself (PTY + watcher, no desktop tab) even while a desktop controller is connected. Used by `pragma-cli agent verify` so scenario sessions do not open a desktop tab per step.
+	*/
+	headless?: boolean | null;
+}
+/**
+* Spec for creating a fresh worktree as part of an `agentSessionLaunch` request. Omitted/optional fields fall back to Pragma defaults.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "NewWorktreeSpec".
+*/
+interface NewWorktreeSpec {
+	parentWorktreeId: string;
+	branch: string;
+	title?: string | null;
+}
+/**
+* A single entry in a worktree directory listing.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "DirEntry".
+*/
+interface DirEntry {
+	/**
+	* The entry's file name (no directory part).
+	*/
+	name: string;
+	/**
+	* Worktree-relative POSIX path (forward slashes) to the entry.
+	*/
+	path: string;
+	isDir: boolean;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "ChangedFile".
+*/
+interface ChangedFile {
+	/**
+	* Worktree-relative POSIX path of the changed file.
+	*/
+	path: string;
+	/**
+	* Previous path for a rename; null otherwise.
+	*/
+	oldPath: string | null;
+	status: ChangeStatus;
+	side: DiffSide;
+	/**
+	* Lines added in this file's diff on its side. Null for binary files (git reports -/-) and for untracked files whose on-disk line count could not be determined.
+	*/
+	additions: number | null;
+	/**
+	* Lines removed in this file's diff on its side. Null for binary files and for untracked files. 0 for untracked files (a brand-new file has nothing to remove).
+	*/
+	deletions: number | null;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "WorktreeChanges".
+*/
+interface WorktreeChanges {
+	committed: ChangedFile[];
+	staged: ChangedFile[];
+	unstaged: ChangedFile[];
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FileDiff".
+*/
+interface FileDiff {
+	path: string;
+	/**
+	* The base-side text; empty when the file was added or is binary.
+	*/
+	oldText: string;
+	/**
+	* The new-side text; empty when the file was deleted or is binary.
+	*/
+	newText: string;
+	/**
+	* True when git reports the file as binary; old/new text are empty.
+	*/
+	binary: boolean;
+}
+/**
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "FileContents".
+*/
+interface FileContents {
+	path: string;
+	/**
+	* The decoded UTF-8 text; empty when binary or truncated.
+	*/
+	text: string;
+	/**
+	* True when the bytes are not valid UTF-8.
+	*/
+	binary: boolean;
+	/**
+	* True when the file exceeds the read cap and was not read.
+	*/
+	truncated: boolean;
+	/**
+	* On-disk size in bytes from the file metadata.
+	*/
+	byteSize: number;
+}
+/**
+* A persisted prompt card on a project's Kanban board, scoped by projectId.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "KanbanPromptCard".
+*/
+interface KanbanPromptCard {
+	id: string;
+	projectId: string;
+	/**
+	* The worktree backing this card once it starts running; null for a draft.
+	*/
+	worktreeId?: string | null;
+	/**
+	* Branch the card targets — an existing project worktree branch or a new one to create.
+	*/
+	branchName: string;
+	prompt: string;
+	agentId: string;
+	/**
+	* Selected model id for the agent launch; null uses the agent default.
+	*/
+	modelId?: string | null;
+	/**
+	* Selected reasoning level id for the agent launch; null uses automatic reasoning.
+	*/
+	reasoningId?: string | null;
+	status: KanbanPromptStatus;
+	/**
+	* Terminal tab/daemon session id the agent runs in once started; null before launch.
+	*/
+	agentTabId?: string | null;
+	/**
+	* Which completion path finished the card; null until completed.
+	*/
+	completedAction?: KanbanCompletedAction | null;
+	/**
+	* URL of the pull request opened during completion, when applicable.
+	*/
+	pullRequestUrl?: string | null;
+	/**
+	* Number of the pull request opened during completion, when applicable.
+	*/
+	pullRequestNumber?: number | null;
+	schedulingMode: KanbanSchedulingMode;
+	/**
+	* Reserved for scheduled runs; always null in the manual MVP.
+	*/
+	scheduledFor?: string | null;
+	createdAt: string;
+	updatedAt: string;
+	/**
+	* When the card first moved to inProgress; null before launch.
+	*/
+	startedAt?: string | null;
+	/**
+	* When the card moved to completed; null until completed.
+	*/
+	completedAt?: string | null;
+}
+/**
+* Payload for creating an agent-board draft through the brokered desktop controller.
+*
+* This interface was referenced by `Constants`'s JSON-Schema
+* via the `definition` "BoardDraftCreatePayload".
+*/
+interface BoardDraftCreatePayload {
+	prompt: string;
+	/**
+	* Existing worktree whose project and branch receive the draft.
+	*/
+	worktreeId: string;
+	agentId: string;
+	modelId?: string | null;
+	reasoningId?: string | null;
+}
+/**
+* Shared application constants.
+*
+* The values live in `values.json` and are validated against `schema.json`.
+* The same JSON is consumed by the Rust backend (see `src/lib.rs`), so this is
+* the single source of truth across both languages.
+*/
+declare const constants: Constants;
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface PragmaClientConfig {
+	baseUrl?: string;
+	token?: string;
+	fetch?: FetchLike;
+	headers?: Record<string, string>;
+}
+interface RequestOptions {
+	method?: string;
+	body?: unknown;
+	rawBody?: Uint8Array;
+	headers?: Record<string, string>;
+	signal?: AbortSignal;
+}
+declare class Transport {
+	readonly baseUrl: string;
+	readonly token: string;
+	readonly fetch: FetchLike;
+	readonly headers: Record<string, string>;
+	constructor(config?: PragmaClientConfig);
+	request<T>(path: string, options?: RequestOptions): Promise<T>;
+	raw(path: string, options?: RequestOptions): Promise<Response>;
+}
+/** Result of `client.agents.launch(...)`: the resolved worktree + tab. */
+interface AgentSessionLaunchResult {
+	worktreeId: string;
+	tabId: string;
+}
+interface AgentEvent {
+	type: "agent";
+	worktreeId: string;
+	tabId: string;
+	agent: string;
+	/** Effective status; null/absent only for a status-less session-name report. */
+	status?: AgentStatus | null;
+	/** Session display name last reported by the agent, when present. */
+	sessionName?: string | null;
+	attentionKind: AgentAttentionKind | null;
+	/** The command awaiting approval when `attentionKind` is `command`. */
+	command?: string | null;
+	/** The question awaiting an answer when `attentionKind` is `question`. */
+	question?: string | null;
+	/** Answer choices for a `question` attention, when present. */
+	options?: QuestionOption[] | null;
+	/** Multiple questions for a `question` attention, when present. */
+	questions?: AgentQuestion[] | null;
+	/** Correlation id for the command/question round-trip, when present. */
+	requestId?: string | null;
+}
+interface AgentMessageEvent {
+	type: "agentMessage";
+	message: AgentMessage;
+}
+/** Approve/deny verdict fanned out to agent subscribers. */
+interface AgentDecisionEvent {
+	type: "agentDecision";
+	decision: AgentDecision;
+}
+/** Question reply fanned out to agent subscribers. */
+interface AgentAnswerEvent {
+	type: "agentAnswer";
+	answer: AgentAnswer;
+}
+/** Free-form interjection fanned out to agent subscribers. */
+interface AgentInputEvent {
+	type: "agentInput";
+	input: AgentInput;
+}
+/** Transient interrupt fanned out to agent subscribers. */
+interface AgentInterruptEvent {
+	type: "agentInterrupt";
+	interrupt: AgentInterrupt;
+}
+type AgentStreamEvent = AgentEvent | AgentMessageEvent | AgentDecisionEvent | AgentAnswerEvent | AgentInputEvent | AgentInterruptEvent;
+interface ReportOptions {
+	agent: string;
+	worktreeId?: string;
+	kind?: AgentAttentionKind;
+	/** Command text for a `command` attention report (shown in the approval toast). */
+	command?: string;
+	/** Question text for a `question` attention report (shown in the answer UI). */
+	question?: string;
+	/** Answer choices for a `question` attention report. */
+	options?: QuestionOption[];
+	/** Multiple questions for a `question` attention report. */
+	questions?: AgentQuestion[];
+	/** Correlation id so a waiting caller can match the resulting decision. */
+	requestId?: string;
+	client?: PragmaClient;
+	env?: Record<string, string | undefined>;
+	signal?: AbortSignal;
+}
+/** Options for {@link reportSessionName}: a session display name plus routing. */
+type ReportSessionNameOptions = Omit<ReportOptions, "kind"> & {
+	/** The session's human-readable display name. */
+	name: string;
+};
+type ReportMessageOptions = Omit<ReportOptions, "kind"> & {
+	message: Omit<AgentMessage, "agent" | "worktreeId" | "tabId"> & Partial<Pick<AgentMessage, "agent" | "worktreeId" | "tabId">>;
+};
+/** Identifies the single running agent a {@link AgentConnection} is bound to. */
+interface ConnectOptions {
+	/** Stable agent id of the running agent to connect to. */
+	agent: string;
+	/** The terminal tab hosting the agent. */
+	tabId: string;
+	/** The worktree hosting the agent. */
+	worktreeId: string;
+	/** Optional initial request sent as the first interjection on connect. */
+	prompt?: string;
+	/** Aborts the whole connection (read stream + in-flight sends). */
+	signal?: AbortSignal;
+}
+/**
+* A single duplex channel to one running agent. Async-iterate it to read every
+* event routed to that agent + tab ({@link AgentStreamEvent} filtered to the
+* connect target); call the methods to talk back on the same channel —
+* {@link send} to interject, {@link answer} to reply to a question,
+* {@link decide} to approve/deny a command.
+*/
+interface AgentConnection extends AsyncIterable<AgentStreamEvent> {
+	/** Interjects free-form text into the agent's turn. */
+	send(text: string, options?: {
+		requestId?: string;
+	}): Promise<void>;
+	/** Replies to a `question` attention request; `null` dismisses it. */
+	answer(requestId: string, reply: string | null): Promise<void>;
+	/** Approves (`true`) or denies (`false`) a `command` attention request. */
+	decide(requestId: string, approved: boolean): Promise<void>;
+	/** Interrupts the agent's current turn; a watcher sends ESC to its tab. */
+	interrupt(requestId?: string): Promise<void>;
+	/** Closes the read stream and releases the connection. */
+	close(): void;
+}
+/** Agent status gateway namespace. */
+declare class AgentsClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	report(payload: AgentReportPayload, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	reportMessage(payload: AgentMessage, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Publishes a command-approval verdict, fanned out to agent subscribers. */
+	reportDecision(payload: AgentDecision, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Publishes a reply to a question request, fanned out to agent subscribers. */
+	reportAnswer(payload: AgentAnswer, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Publishes a free-form interjection, fanned out to agent subscribers. */
+	reportInput(payload: AgentInput, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Publishes a transient interrupt, fanned out to agent subscribers. */
+	reportInterrupt(payload: AgentInterrupt, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	reportStarted(options: ReportOptions): Promise<void>;
+	reportStopped(options: ReportOptions): Promise<void>;
+	reportAttention(options: ReportOptions): Promise<void>;
+	reportCleared(options: ReportOptions): Promise<void>;
+	/**
+	* Reports the human-readable name of the agent's active session without
+	* changing status. Pragma renames the hosting tab (user renames win). Call
+	* again on every rename or session switch.
+	*/
+	reportSessionName(options: ReportSessionNameOptions): Promise<void>;
+	/** Returns the resolved agent catalog assembled by the plugins sidecar. */
+	catalog(options?: {
+		signal?: AbortSignal;
+	}): Promise<AgentCatalog>;
+	/**
+	* Launches a new agent session through the brokered `agentSessionLaunch`
+	* control route. A connected desktop persists tab/worktree metadata; without
+	* one, the persistent host can launch into an existing mirrored worktree.
+	*/
+	launch(payload: AgentSessionLaunchPayload, options?: {
+		signal?: AbortSignal;
+	}): Promise<AgentSessionLaunchResult>;
+	markAgentsSeen(payload: {
+		tabId: string;
+	}, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/**
+	* Opens a single duplex channel to one running agent: async-iterate it to
+	* read every event routed to `agent` + `tabId`, and use its methods to talk
+	* back on the same channel ({@link AgentConnection.send} to interject,
+	* {@link AgentConnection.answer} to reply to a question,
+	* {@link AgentConnection.decide} to approve/deny a command). Supersedes the
+	* old read-only agent-event subscription. When `prompt` is set it is delivered
+	* as the first interjection before the connection is returned.
+	*/
+	connect(options: ConnectOptions): Promise<AgentConnection>;
+	/** Raw, unfiltered agent event stream. Internal read half of {@link connect}. */
+	private readStream;
+	/**
+	* Blocks on the agent event stream until an {@link AgentDecision} matching
+	* `agent` + `requestId` arrives, resolving its `approved` verdict. Resolves
+	* `null` on timeout, abort, or stream error so a caller can fall back to the
+	* harness's own permission prompt.
+	*/
+	awaitDecision(params: {
+		agent: string;
+		requestId: string;
+		timeoutMs?: number;
+		signal?: AbortSignal;
+	}): Promise<boolean | null>;
+	/**
+	* Blocks on the agent event stream until an {@link AgentAnswer} matching
+	* `agent` + `requestId` arrives, resolving its reply text. Resolves `null` on
+	* dismiss, timeout, abort, or stream error so a caller can fall back to the
+	* harness's own question prompt.
+	*/
+	awaitAnswer(params: {
+		agent: string;
+		requestId: string;
+		timeoutMs?: number;
+		signal?: AbortSignal;
+	}): Promise<string | null>;
+}
+/** Reports an agent started status. */
+declare function reportStarted(options: ReportOptions): Promise<void>;
+/** Reports an agent stopped/done status. */
+declare function reportStopped(options: ReportOptions): Promise<void>;
+/** Reports an agent attention status. */
+declare function reportAttention(options: ReportOptions): Promise<void>;
+/** Reports an agent cleared status. */
+declare function reportCleared(options: ReportOptions): Promise<void>;
+/**
+* Reports the session's display name without changing agent status. Pragma
+* renames the hosting tab unless the user renamed it manually; report again on
+* every rename or session switch.
+*/
+declare function reportSessionName(options: ReportSessionNameOptions): Promise<void>;
+/** Reports one rich agent message. No-ops unless Pragma gateway env is present. */
+declare function reportMessage(options: ReportMessageOptions): Promise<void>;
+/** Options for {@link awaitAgentDecision}. */
+interface AwaitDecisionOptions {
+	agent: string;
+	requestId: string;
+	timeoutMs?: number;
+	client?: PragmaClient;
+	env?: Record<string, string | undefined>;
+	signal?: AbortSignal;
+}
+/**
+* Resolves the approve/deny verdict a Pragma approval toast publishes for
+* `requestId`, or `null` when there is no Pragma gateway env, on timeout, or on
+* error. Used by a harness plugin (e.g. opencode's `permission.ask`) to turn a
+* remote approval into an in-process permission decision.
+*/
+declare function awaitAgentDecision(options: AwaitDecisionOptions): Promise<boolean | null>;
+/** Options for {@link awaitAgentAnswer}. */
+interface AwaitAnswerOptions {
+	agent: string;
+	requestId: string;
+	timeoutMs?: number;
+	client?: PragmaClient;
+	env?: Record<string, string | undefined>;
+	signal?: AbortSignal;
+}
+/**
+* Resolves the reply text a Pragma question toast publishes for `requestId`, or
+* `null` when there is no Pragma gateway env, on dismiss, on timeout, or on
+* error. Used by a harness plugin to turn a remote answer into an in-process
+* question response.
+*/
+declare function awaitAgentAnswer(options: AwaitAnswerOptions): Promise<string | null>;
+/** A fetched asset: its raw bytes and MIME type. */
+interface FetchedAsset {
+	bytes: Uint8Array;
+	mime: string;
+}
+/**
+* Gateway namespace for plugin-contributed assets (agent icons). Assets are
+* fetched by content hash through the authenticated SDK transport — never as
+* bare `<img>` URLs — so the bearer token rides the request header.
+*/
+declare class AssetsClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	/** Fetches an asset's raw bytes + MIME type by content hash. */
+	fetch(hash: string, options?: {
+		signal?: AbortSignal;
+	}): Promise<FetchedAsset>;
+	/** Fetches an asset and returns it as a `data:` URI, ready for an `<img src>`. */
+	toDataUri(hash: string, options?: {
+		signal?: AbortSignal;
+	}): Promise<string>;
+}
+type ProtocolSubscriptionEvent = {
+	type: "snapshot";
+	subscription: ProtocolEventKind;
+	payload: unknown;
+} | {
+	type: "delta";
+	subscription: ProtocolEventKind;
+	payload: unknown;
+};
+/** Protocol event subscription namespace. */
+declare class EventsClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	subscribe(event: ProtocolEventKind, options?: {
+		cursor?: string;
+		worktreeId?: string;
+		cwd?: string;
+		signal?: AbortSignal;
+	}): AsyncGenerator<ProtocolSubscriptionEvent>;
+}
+interface ExecRunRequest {
+	cwd: string;
+	commands: string[];
+	env?: Array<[string, string]>;
+	maxConcurrent?: number;
+}
+interface CommandResult {
+	command: string;
+	stdout: string;
+	stderr: string;
+	status: number | null;
+	durationMs: number;
+}
+/** Headless command execution RPC namespace. */
+declare class ExecClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	run(payload: ExecRunRequest): Promise<CommandResult[]>;
+}
+/** Options accepted by every fanout call. */
+interface FanoutRequestOptions {
+	signal?: AbortSignal;
+}
+/** One member's terminal output, with the base64 wire field decoded. */
+interface FanoutReadTargetBytes extends Omit<FanoutReadTarget, "data"> {
+	/** The same window as raw bytes. Callers never see the base64 wire form. */
+	raw: Uint8Array;
+}
+/** A read result whose targets carry decoded bytes. */
+interface FanoutReadResultBytes {
+	fanoutId: string;
+	targets: FanoutReadTargetBytes[];
+}
+/** A fanout subscription event: a snapshot then full-replacement deltas. */
+type FanoutSubscriptionEvent = {
+	type: "snapshot";
+	subscription: ProtocolEventKind;
+	payload: FanoutSubscriptionPayload;
+} | {
+	type: "delta";
+	subscription: ProtocolEventKind;
+	payload: FanoutSubscriptionPayload;
+};
+/**
+* Fanout orchestration: launching one prompt into several isolated attempts,
+* following them, and finally picking one.
+*
+* Every method goes through the local gateway to the host that owns the
+* project — the same `fanouts` RPC `pragma-cli` uses — so a fanout behaves
+* identically whether it was started from a terminal, from the desktop, or from
+* a script, and whether or not the desktop app is running.
+*/
+declare class FanoutsClient {
+	private readonly transport;
+	private readonly events;
+	constructor(transport: Transport, events: EventsClient);
+	/**
+	* Provisions a whole fanout: the parent, one worktree per attempt branched
+	* from one captured commit, and one agent-owned terminal tab in each.
+	*
+	* Resolves once every attempt has launched or failed. A partly-provisioned
+	* fanout resolves rather than throwing — `partial` is true and `failures`
+	* names the members to retry — because the healthy attempts are real and
+	* already running.
+	*/
+	create(request: FanoutCreateRequest, options?: FanoutRequestOptions): Promise<FanoutResult>;
+	/** Reads one fanout by id, or by any worktree that belongs to it. */
+	get(reference: FanoutRef, options?: FanoutRequestOptions): Promise<Fanout>;
+	/**
+	* Bounded terminal output for one member (`memberId`) or every member
+	* (`all: true`). The raw bytes arrive base64-encoded and are decoded here, so
+	* callers see a `Uint8Array` and never the wire form.
+	*/
+	read(request: FanoutReadRequest, options?: FanoutRequestOptions): Promise<FanoutReadResultBytes>;
+	/**
+	* Delivers a follow-up to one member or to every live member.
+	*
+	* Waits for per-member delivery receipts unless `waitForDelivery` is false.
+	* Passing the same `messageId` twice is safe: a member that already took the
+	* message is not typed into again.
+	*/
+	send(request: FanoutSendRequest, options?: FanoutRequestOptions): Promise<FanoutSendResult>;
+	/**
+	* Relaunches one member's agent in its existing worktree. The worktree is
+	* reused deliberately — it may already hold work — and the previous tab moves
+	* into the member's history.
+	*/
+	retry(request: FanoutMemberRequest, options?: FanoutRequestOptions): Promise<FanoutResult>;
+	/** Stops every attempt and releases the parent. Checkouts are kept. */
+	cancel(reference: FanoutRef, options?: FanoutRequestOptions): Promise<FanoutResult>;
+	/**
+	* **Destructive.** Commits the winner's uncommitted work under an
+	* AI-generated message, merges it into the parent, promotes its scratchpads,
+	* and then deletes every attempt worktree and branch — the winner included.
+	*
+	* There is deliberately no confirmation flag here: confirming is the UI's and
+	* the CLI's job. A merge conflict or a failed cleanup resolves with the
+	* durable fanout and a `stage` to resume from rather than throwing.
+	*/
+	pick(request: FanoutMemberRequest, options?: FanoutRequestOptions): Promise<FanoutPickResult>;
+	/**
+	* Typed fanout snapshot-then-delta subscription. v1 keeps deltas trivial:
+	* every delta carries the host's full fanout set.
+	*/
+	subscribe(options?: {
+		fanoutId?: string;
+		signal?: AbortSignal;
+	}): AsyncGenerator<FanoutSubscriptionEvent>;
+	private narrow;
+	private rpc;
+}
+interface WorktreePathRequest {
+	root: string;
+	path: string;
+}
+interface WriteFileRequest extends WorktreePathRequest {
+	contents: string;
+}
+interface RenameRequest {
+	root: string;
+	from: string;
+	to: string;
+}
+/** Filesystem RPC namespace. */
+declare class FsClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	listDir(payload: WorktreePathRequest): Promise<DirEntry[]>;
+	createFile(payload: WorktreePathRequest): Promise<void>;
+	createFolder(payload: WorktreePathRequest): Promise<void>;
+	pathExists(payload: WorktreePathRequest): Promise<boolean>;
+	readFile(payload: WorktreePathRequest): Promise<FileContents>;
+	writeFile(payload: WriteFileRequest): Promise<void>;
+	rename(payload: RenameRequest): Promise<void>;
+	delete(payload: WorktreePathRequest): Promise<void>;
+	private rpc;
+}
+interface MergedStatusItem {
+	id: string;
+	root: string;
+	branch: string;
+	parentBranch: string | null;
+}
+interface GithubRepoInfo {
+	remoteUrl: string;
+	defaultBranch: string;
+	headBranch: string;
+}
+type GitPayload = Record<string, unknown>;
+/** Git RPC namespace. */
+declare class GitClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	worktreeChanges(payload: {
+		root: string;
+		parentBranch?: string | null;
+	}): Promise<WorktreeChanges>;
+	mergedStatus(payload: {
+		items: MergedStatusItem[];
+	}): Promise<Record<string, boolean>>;
+	fileDiff(payload: GitPayload): Promise<FileDiff>;
+	discardUnstagedFile(payload: GitPayload): Promise<void>;
+	discardAllUnstaged(payload: {
+		root: string;
+	}): Promise<void>;
+	stageFile(payload: {
+		root: string;
+		path: string;
+	}): Promise<void>;
+	stageAll(payload: {
+		root: string;
+	}): Promise<void>;
+	unstageFile(payload: {
+		root: string;
+		path: string;
+		oldPath?: string | null;
+	}): Promise<void>;
+	unstageAll(payload: {
+		root: string;
+	}): Promise<void>;
+	commitStaged(payload: {
+		root: string;
+		message: string;
+	}): Promise<void>;
+	mergeWorktreeToParent(payload: GitPayload): Promise<void>;
+	prFileDiff(payload: GitPayload): Promise<FileDiff>;
+	githubRepoInfo(payload: {
+		root: string;
+	}): Promise<GithubRepoInfo>;
+	githubDefaultPrTitle(payload: {
+		root: string;
+	}): Promise<string>;
+	githubFetchAndSync(payload: {
+		root: string;
+	}): Promise<BranchSyncStatus>;
+	githubPullBranch(payload: {
+		root: string;
+	}): Promise<void>;
+	githubSyncBranch(payload: {
+		root: string;
+	}): Promise<void>;
+	githubPushBranch(payload: {
+		root: string;
+	}): Promise<void>;
+	githubDeleteRemoteBranch(payload: {
+		root: string;
+	}): Promise<void>;
+	ensurePragmaExcluded(payload: {
+		projectRoot: string;
+	}): Promise<void>;
+	createWorktree(payload: {
+		parentRoot: string;
+		branch: string;
+		path: string;
+	}): Promise<void>;
+	removeWorktree(payload: {
+		repoRoot: string;
+		worktreePath: string;
+		force: boolean;
+	}): Promise<void>;
+	deleteBranch(payload: {
+		repoRoot: string;
+		branch: string;
+	}): Promise<void>;
+	isDirty(payload: {
+		root: string;
+	}): Promise<boolean>;
+	private rpc;
+}
+/** Body of `GET /v1/health`. */
+interface GatewayHealth {
+	status: string;
+	protocolVersion: string;
+	gatewayVersion: string;
+	/**
+	* `gateway.apiVersion` — the client-facing `/v1` contract this host speaks.
+	*
+	* Optional because a host older than the release that added it answers
+	* without the field; a remote client treats that as "unknown", not
+	* "incompatible".
+	*/
+	apiVersion?: string;
+}
+/**
+* Gateway namespace for the liveness probe.
+*
+* `/v1/health` is one of the gateway's unauthenticated routes, so this answers
+* even when a token has gone stale — which is what makes it useful for telling
+* "the host is gone" apart from "the host rejected us".
+*/
+declare class HealthClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	/** Fetches the host's health, including its protocol and gateway versions. */
+	check(options?: {
+		signal?: AbortSignal;
+	}): Promise<GatewayHealth>;
+}
+/** What a test push reached, and what the push service refused. */
+interface PushTestResult {
+	/** How many registered phones the notification was addressed to. */
+	sent: number;
+	/** One line per message the push service rejected, with its reason. */
+	errors: string[];
+}
+/** One phone registered for Expo push notifications on this host. */
+interface PushRegistration {
+	/** Gateway device id (the `x-pragma-device-id` header the client sends). */
+	deviceId: string;
+	name: string;
+	platform: string;
+	/** Expo push token, or null once the device unregisters. */
+	pushToken: string | null;
+	registeredAt: number;
+}
+/** Push notification gateway namespace. */
+declare class PushClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	/**
+	* Registers (or refreshes) this installation's Expo push token, so agent
+	* alerts reach the phone while it is away from the app. The device is
+	* identified by the `x-pragma-device-id` header the client already sends.
+	*/
+	register(payload: {
+		token: string;
+	}, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Stops push delivery to this installation (unpair, or notifications off). */
+	unregister(options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Lists every phone currently registered for push on this host. */
+	list(options?: {
+		signal?: AbortSignal;
+	}): Promise<PushRegistration[]>;
+	/**
+	* Sends a test notification to every registered phone and reports what the
+	* push service made of it. `sent` counts the phones addressed; `errors`
+	* carries a line per message the push service refused, which is the only
+	* place a project-wide credential problem is ever named.
+	*/
+	test(options?: {
+		signal?: AbortSignal;
+	}): Promise<PushTestResult>;
+	/**
+	* Reports whether the desktop window is focused. While a recent heartbeat says
+	* it is, the gateway holds back phone pushes — the user is already looking at
+	* the desktop alert. Heartbeats expire (`gateway.push.presenceTtlMs`), so a
+	* desktop that dies without blurring stops suppressing on its own.
+	*/
+	presence(payload: {
+		focused: boolean;
+	}, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+}
+/**
+* The on-disk shapes every scratchpad client shares.
+*
+* They live in their own module (and their own package) because the desktop
+* editor, the SDK, the read-only viewer, and the native clients all read and
+* write the same two files — the MDX with its managed frontmatter, and the
+* sibling comment thread — and a second definition of either shape is how they
+* drift apart.
+*/
+/** One block of the rendered document a comment can be attached to. */
+interface ScratchpadBlock {
+	/** Index of the block among the document's top-level rendered blocks. */
+	index: number;
+	/** Plain-text excerpt of the block, used as the comment's quote. */
+	quote: string;
+}
+/** One persisted scratchpad comment, in the desktop's on-disk shape. */
+interface ScratchpadComment {
+	id: string;
+	/**
+	* ProseMirror document positions the desktop editor decorates. A native
+	* client has no ProseMirror document, so it writes `0`/`0` and anchors by
+	* {@link ScratchpadComment.quote} and {@link ScratchpadComment.blockIndex}
+	* instead; the desktop then renders the comment without a highlight rather
+	* than highlighting the wrong range.
+	*/
+	from: number;
+	to: number;
+	quote: string;
+	text: string;
+	createdAt: number;
+	resolvedAt: number | null;
+	/** Rendered block this comment was attached to, when written on mobile. */
+	blockIndex?: number;
+}
+/** Options for {@link ScratchpadsClient.getScratchpads}. */
+interface GetScratchpadsOptions {
+	/** Absolute path of the worktree whose scratchpads should be listed. */
+	root: string;
+	signal?: AbortSignal;
+}
+/** One scratchpad, addressed the way every host RPC addresses a file. */
+interface ScratchpadRef {
+	/** Absolute path of the worktree the scratchpad lives in. */
+	root: string;
+	/** Worktree-relative POSIX path of the scratchpad's MDX file. */
+	filePath: string;
+}
+/** Options for {@link ScratchpadsClient.comment}. */
+interface CommentScratchpadOptions extends ScratchpadRef {
+	/** The rendered block the comment is anchored to. */
+	block: ScratchpadBlock;
+	/** The comment body. Trimmed before it is stored. */
+	text: string;
+	/** Comment id. Generated when omitted. */
+	id?: string;
+	/** Creation timestamp in epoch milliseconds. Defaults to now. */
+	createdAt?: number;
+}
+/** Options for {@link ScratchpadsClient.attachAgent}. */
+interface AttachScratchpadAgentOptions extends ScratchpadRef {
+	/** Terminal tab id hosting the agent the scratchpad should prompt. */
+	tabId: string;
+	/** Catalog agent id of that tab (e.g. `pragma.claude-code`). */
+	agentId: string;
+	/** Current MDX source, when the caller already holds it, to skip a read. */
+	contents?: string;
+}
+/** Options for {@link ScratchpadsClient.sendAttached}. */
+interface SendAttachedOptions extends ScratchpadRef {
+	/** Worktree the attached tab belongs to. */
+	worktreeId: string;
+	/** Text delivered to the agent as an interjection. */
+	text: string;
+	/** Current MDX source, when the caller already holds it, to skip a read. */
+	contents?: string;
+	signal?: AbortSignal;
+}
+/**
+* Outcome of {@link ScratchpadsClient.sendAttached}: `delivered: false` means
+* the scratchpad names no agent, not that delivery failed.
+*/
+type SendAttachedResult = {
+	delivered: false;
+} | {
+	delivered: true;
+	/** Runtime agent id the interjection was addressed to. */
+	agent: string;
+	/** Tab the interjection was sent to. */
+	tabId: string;
+};
+/**
+* Gateway namespace for a worktree's managed scratchpads.
+*
+* The host lists the worktree's scratchpad directory and parses each file's
+* managed frontmatter, so every client sees the same contract the desktop does:
+* the MDX source plus the agent tab the scratchpad is attached to.
+*
+* Everything past {@link ScratchpadsClient.getScratchpads} is composed from the
+* filesystem and agent namespaces rather than served by a route of its own, but
+* belongs here because the composition *is* the contract: the comment thread
+* lives in a sibling file whose name only `@pragma-sh/scratchpad-contract` knows,
+* the attachment lives in managed frontmatter, and a prompt has to be addressed
+* to the running agent's runtime id rather than its catalog id. Re-deriving any
+* of that per client is how the three drift apart.
+*/
+declare class ScratchpadsClient {
+	private readonly transport;
+	private readonly fs;
+	private readonly agents;
+	constructor(transport: Transport, fs: FsClient, agents: AgentsClient);
+	/** Lists every managed scratchpad in one worktree, source included. */
+	getScratchpads(options: GetScratchpadsOptions): Promise<ScratchpadFile[]>;
+	/**
+	* Reads a scratchpad's comment thread. A scratchpad that was never commented
+	* on has no sibling file, which reads as an empty thread rather than an error.
+	*/
+	getComments(options: ScratchpadRef): Promise<ScratchpadComment[]>;
+	/**
+	* Appends one comment anchored to a rendered block and returns it.
+	*
+	* Read-modify-write against the whole file: the thread is small, and the
+	* desktop rewrites it wholesale too, so a partial append would be the odd one
+	* out. Concurrent callers must serialize their own writes.
+	*/
+	comment(options: CommentScratchpadOptions): Promise<ScratchpadComment>;
+	/** Replaces a scratchpad's comment thread wholesale. */
+	setComments(options: ScratchpadRef, comments: readonly ScratchpadComment[]): Promise<void>;
+	/**
+	* Records the agent tab a scratchpad prompts, in its managed frontmatter.
+	*
+	* The attachment lives in the file rather than in client state so it survives
+	* the session that created it and reads the same from every client.
+	*/
+	attachAgent(options: AttachScratchpadAgentOptions): Promise<void>;
+	/**
+	* Sends text to the agent this scratchpad is attached to.
+	*
+	* Resolves `{ delivered: false }` when nothing is attached — the common case,
+	* because a scratchpad outlives the session that wrote it — so a caller can
+	* raise its own "attach an agent" UI instead of catching an error. Delivery
+	* itself is fire-and-forget past the gateway: the watcher attached to that
+	* session types the text into the agent's TUI, and a tab whose session has
+	* already exited drops it.
+	*/
+	sendAttached(options: SendAttachedOptions): Promise<SendAttachedResult>;
+	private readScratchpad;
+	private writeComments;
+}
+/**
+* The runtime agent id a report must carry.
+*
+* Frontmatter stores the catalog id (`plugin.agent`), while the agent event
+* stream is keyed by the plugin's own runtime id — its last segment. Sending
+* the qualified id makes the message invisible to the running agent.
+*/
+declare function runtimeAgentId2(agentId: string): string;
+interface SpawnSessionRequest {
+	cwd: string;
+	cols?: number;
+	rows?: number;
+	worktreeId?: string;
+}
+interface SpawnSessionResponse {
+	sessionId: string;
+	worktreeId: string;
+	cwd: string;
+}
+type SessionEvent = {
+	type: "output";
+	sessionId: string;
+	dataBase64: string;
+} | {
+	type: "title";
+	sessionId: string;
+	title: string;
+} | {
+	type: "exit";
+	sessionId: string;
+	code: number | null;
+} | {
+	type: "echoMode";
+	sessionId: string;
+	echo: boolean;
+};
+interface StreamOptions {
+	signal?: AbortSignal;
+}
+/** PTY session gateway namespace. */
+declare class SessionsClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	spawn(payload: SpawnSessionRequest, options?: {
+		signal?: AbortSignal;
+	}): Promise<SpawnSessionResponse>;
+	attach(sessionId: string, options?: StreamOptions): AsyncGenerator<SessionEvent>;
+	write(sessionId: string, bytes: Uint8Array, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	resize(sessionId: string, payload: {
+		cols: number;
+		rows: number;
+	}, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	kill(sessionId: string, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+	/** Renames the workspace tab associated with a session. */
+	rename(sessionId: string, title: string): Promise<void>;
+	killForCwd(cwd: string, options?: {
+		signal?: AbortSignal;
+	}): Promise<void>;
+}
+/** A color scheme a `.pragma/theme.json` may declare under `colors`. */
+type ThemeMode = (typeof constants.theme.modes)[number];
+/** Color overrides for one scheme, keyed by token name (no `--` prefix). */
+type ThemeOverrides = Partial<Record<string, string>>;
+/** Which theme-file scopes existed on the host. */
+interface ThemeSources {
+	/** `~/.pragma/theme.json` was present. */
+	global: boolean;
+	/** `<root>/.pragma/theme.json` was present (only when a root was requested). */
+	project: boolean;
+}
+/**
+* The host's user theme: `global` layered under `project`, per token. Shipped
+* defaults are deliberately absent — they belong to the app doing the
+* rendering, so a client applies these on top of its own.
+*/
+interface HostTheme {
+	colors: Partial<Record<ThemeMode, ThemeOverrides>>;
+	sources: ThemeSources;
+}
+/** Options for {@link ThemeClient.get}. */
+interface GetThemeOptions {
+	/**
+	* Absolute root of a project whose `.pragma/theme.json` should layer over the
+	* global one. Omit for the global theme alone.
+	*/
+	root?: string;
+	signal?: AbortSignal;
+}
+/**
+* Gateway namespace for the host's user theme (`.pragma/theme.json`).
+*
+* The host returns overrides only — never the desktop's shipped defaults — so a
+* client mirrors the user's customisation on top of its own base palette.
+*/
+declare class ThemeClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	/** Fetches the host's merged theme overrides. */
+	get(options?: GetThemeOptions): Promise<HostTheme>;
+}
+/** Whiteboard list input requiring the optional query field. */
+interface WhiteboardSearchInput extends WhiteboardListInput {
+	query: string;
+}
+/** Input selecting one whiteboard for PNG rendering. */
+interface WhiteboardViewInput extends WhiteboardIdInput {
+	/** Uses Excalidraw's dark palette. */
+	dark?: boolean;
+}
+/** Decoded PNG bytes returned by whiteboard rendering. */
+type WhiteboardViewBytes = Uint8Array;
+/** Durable Excalidraw whiteboard RPC namespace. */
+declare class WhiteboardsClient {
+	private readonly transport;
+	constructor(transport: Transport);
+	/** Creates one worktree-scoped whiteboard. */
+	create(input: WhiteboardCreateInput): Promise<Whiteboard>;
+	/** Gets one whiteboard by durable id. */
+	get(input: WhiteboardIdInput): Promise<Whiteboard>;
+	/** Lists whiteboards for one worktree, optionally filtering by query. */
+	list(input: WhiteboardListInput): Promise<Whiteboard[]>;
+	/** Searches whiteboard titles and element text within one worktree. */
+	search(input: WhiteboardSearchInput): Promise<Whiteboard[]>;
+	/** Replaces one whiteboard after its optimistic version check. */
+	edit(input: WhiteboardEditInput): Promise<Whiteboard>;
+	/** Deletes one whiteboard by durable id. */
+	delete(input: WhiteboardIdInput): Promise<void>;
+	/** Requests a rendered whiteboard and returns its decoded PNG bytes. */
+	view(input: WhiteboardViewInput): Promise<WhiteboardViewBytes>;
+	private rpc;
+}
+/** A workspace subscription event: a snapshot then full-replacement deltas. */
+type WorkspaceSubscriptionEvent = {
+	type: "snapshot";
+	subscription: ProtocolEventKind;
+	payload: WorkspaceSnapshot;
+} | {
+	type: "delta";
+	subscription: ProtocolEventKind;
+	payload: WorkspaceSnapshot;
+};
+/**
+* Typed workspace snapshot-then-delta subscription. v1 keeps deltas trivial:
+* every delta carries a full replacement snapshot. Delegates to the generic
+* {@link EventsClient} and narrows the payload to {@link WorkspaceSnapshot}.
+*/
+declare class WorkspaceClient {
+	private readonly events;
+	constructor(events: EventsClient);
+	subscribe(options?: {
+		signal?: AbortSignal;
+	}): AsyncGenerator<WorkspaceSubscriptionEvent>;
+	private narrow;
+}
+/** Fetch-based client for the local Pragma HTTP gateway. */
+declare class PragmaClient {
+	readonly fs: FsClient;
+	readonly git: GitClient;
+	readonly exec: ExecClient;
+	readonly sessions: SessionsClient;
+	readonly agents: AgentsClient;
+	readonly assets: AssetsClient;
+	readonly events: EventsClient;
+	readonly workspace: WorkspaceClient;
+	readonly fanouts: FanoutsClient;
+	readonly push: PushClient;
+	readonly theme: ThemeClient;
+	readonly health: HealthClient;
+	readonly scratchpads: ScratchpadsClient;
+	/** Durable Excalidraw whiteboards. */
+	readonly whiteboards: WhiteboardsClient;
+	private readonly transport;
+	constructor(config?: PragmaClientConfig);
+	rpc<T = unknown>(method: string, payload: unknown, options?: {
+		signal?: AbortSignal;
+	}): Promise<T>;
+	/** Creates a draft on the agent board for an existing worktree. */
+	createBoardDraft(payload: BoardDraftCreatePayload, options?: {
+		signal?: AbortSignal;
+	}): Promise<KanbanPromptCard>;
+}
+/** Encodes bytes to base64 without `Buffer`. */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decodes base64 to bytes without `Buffer`. */
+declare function base64ToBytes(value: string): Uint8Array;
+/** Environment variable names used by the gateway SDK. */
+declare const PRAGMA_ENV_KEYS: {
+	readonly gatewayUrl: "PRAGMA_GATEWAY_URL";
+	readonly gatewayToken: "PRAGMA_GATEWAY_TOKEN";
+	readonly tabId: "PRAGMA_TAB_ID";
+	readonly worktreeId: "PRAGMA_WORKTREE_ID";
+};
+type PragmaEnv = Record<string, string | undefined>;
+/** Reads one env var from an injected env object or guarded `globalThis.process`. */
+declare function readEnv(name: string, env?: PragmaEnv): string | undefined;
+/** Returns true when enough Pragma gateway/session env is present for agent reports. */
+declare function hasPragmaEnvironment(env?: PragmaEnv): boolean;
+/** Error returned by the Pragma HTTP gateway. */
+declare class PragmaGatewayError extends Error {
+	readonly code: string;
+	readonly httpStatus: number;
+	/**
+	* Domain error detail the gateway code cannot express — for a fanout, the
+	* `FanoutFailure` (its own failure code, the member it belongs to, and the
+	* finalize stage it stopped at). Present only when the host sent one.
+	*/
+	readonly details?: unknown;
+	readonly cause?: unknown;
+	constructor(message: string, info: {
+		code: string;
+		httpStatus: number;
+		details?: unknown;
+		cause?: unknown;
+	});
+}
+/** Network, configuration, and non-JSON transport failure. */
+declare class PragmaTransportError extends Error {
+	readonly cause?: unknown;
+	constructor(message: string, cause?: unknown);
+}
+export { runtimeAgentId2 as runtimeAgentId, reportStopped, reportStarted, reportSessionName, reportMessage, reportCleared, reportAttention, readEnv, hasPragmaEnvironment, bytesToBase64, base64ToBytes, awaitAgentDecision, awaitAgentAnswer, WriteFileRequest, WorktreePathRequest, WorktreeChanges, WorkspaceSubscriptionEvent, WorkspaceSnapshot, WorkspaceClient, WhiteboardsClient, WhiteboardViewResult, WhiteboardViewInput, WhiteboardViewBytes, WhiteboardSearchInput, WhiteboardListInput, WhiteboardIdInput, WhiteboardEditInput, WhiteboardCreateInput, Whiteboard, ThemeSources, ThemeOverrides, ThemeMode, ThemeClient, StreamOptions, SpawnSessionResponse, SpawnSessionRequest, SessionEvent, SendAttachedResult, SendAttachedOptions, ScratchpadsClient, ScratchpadRef, ScratchpadFile, ScratchpadComment, ScratchpadBlock, ReportSessionNameOptions, ReportOptions, ReportMessageOptions, RenameRequest, QuestionOption, PushTestResult, PushRegistration, PushClient, PragmaTransportError, PragmaGatewayError, PragmaClientConfig, PragmaClient, PRAGMA_ENV_KEYS, MergedStatusItem, KanbanPromptCard, HostTheme, HealthClient, GithubRepoInfo, GitPayload, GetThemeOptions, GetScratchpadsOptions, GatewayHealth, FileDiff, FileContents, FetchedAsset, FanoutsClient, FanoutSubscriptionPayload, FanoutSubscriptionEvent, FanoutStatus, FanoutSendTarget, FanoutSendResult, FanoutSendRequest, FanoutResult, FanoutRequestOptions, FanoutRef, FanoutReadTargetBytes, FanoutReadTarget, FanoutReadResultBytes, FanoutReadResult, FanoutReadRequest, FanoutPickResult, FanoutParentSpec, FanoutNewParent, FanoutMemberStatus, FanoutMemberSelector, FanoutMemberRequest, FanoutMember, FanoutFinalizeStage, FanoutFailureCode, FanoutFailure, FanoutExistingParent, FanoutDeliveryState, FanoutDeliveryReceipt, FanoutCreateRequest, Fanout, ExecRunRequest, ExcalidrawScene, DirEntry, ConnectOptions, CommentScratchpadOptions, CommandResult, CatalogAgent, BranchSyncStatus, BoardDraftCreatePayload, AwaitDecisionOptions, AwaitAnswerOptions, AttachScratchpadAgentOptions, AssetsClient, AgentStreamEvent, AgentStatus, AgentSessionLaunchResult, AgentSessionLaunchPayload, AgentReportPayload, AgentReasoning, AgentQuestion, AgentModelEntry, AgentMessageEvent, AgentMessage, AgentInterruptEvent, AgentInterrupt, AgentInputEvent, AgentInput, AgentIcon, AgentEvent, AgentDecisionEvent, AgentDecision, AgentConnection, AgentCatalog, AgentAttentionKind, AgentAnswerEvent, AgentAnswer };