@pragma-sh/plugin 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,533 @@
+import { AgentFeature as SharedAgentFeature } from "@pragma-sh/constants";
+import { ComponentType, ReactNode } from "react";
+import { PragmaClient } from "@pragma-sh/sdk";
+/** Imperative durable JSON storage bound by the host to one plugin. */
+interface PluginStorage {
+	get<T>(key: string, initialValue: T): Promise<T>;
+	set<T>(key: string, value: T): Promise<void>;
+	delete(key: string): Promise<void>;
+}
+/** The active project a plugin is rendered against, or `null` when none is selected. */
+interface PluginProject {
+	id: string;
+	name: string;
+	path: string;
+}
+/** Options for {@link PluginContext.notify} / `useNotify()`. */
+interface PluginNotifyOptions {
+	variant?: "info" | "success" | "warning" | "error";
+	description?: string;
+	/** Also send a native OS notification through Pragma's notification bridge. */
+	native?: boolean;
+}
+/**
+* Context passed to every plugin callback: contribution `when` guards, command
+* `run` handlers, agent event handlers, and `activate`.
+*/
+interface PluginContext<TConfig = unknown> {
+	/** This plugin's stable id, derived from its `package.json` name. */
+	pluginId: string;
+	/** Absolute plugin package directory when available in this runtime. */
+	pluginDir?: string;
+	/** This plugin's user-supplied config, already validated against its `config` schema. */
+	config: TConfig;
+	/** The active project, or `null` when no project is selected. */
+	project: PluginProject | null;
+	/** Typed SDK client for talking to the local Pragma gateway. */
+	sdk: PragmaClient;
+	/** Shows an in-app notification. */
+	notify: (message: string, options?: PluginNotifyOptions) => void;
+	/** Durable storage scoped to this plugin. Available in desktop-hosted callbacks. */
+	storage?: PluginStorage;
+}
+/** Result shape shared by every `useSdkQuery`-style hook. */
+interface PluginQueryResult<T> {
+	data: T | undefined;
+	error: string | null;
+	loading: boolean;
+	refetch: () => void;
+}
+/** One agent's live status, as surfaced by `useAgentStatuses`. */
+interface PluginAgentStatusEntry {
+	agent: string;
+	status: "running" | "attention" | "done";
+}
+/**
+* Minimal live terminal-session summary surfaced by `useSessions` and
+* `listSessions`. This is intentionally small until the SDK exposes a
+* dedicated session-list RPC.
+*/
+interface PluginSessionSummary {
+	id: string;
+	cwd: string;
+}
+/** Payload emitted for `pragma://plugin/<pluginId>/<path>` deep links. */
+interface PluginDeepLinkEvent {
+	pluginId: string;
+	path: string;
+	url: string;
+	params: Record<string, string[]>;
+}
+/** An icon contributed alongside a sidebar tab, command, or agent. */
+type PluginIcon = ComponentType<{
+	className?: string;
+}>;
+/** Values passed directly to every host-rendered plugin component. */
+interface PluginComponentProps<TWebViewPayload = unknown> {
+	/** Payload supplied when this component renders as a plugin web view. */
+	webViewPayload?: TWebViewPayload;
+}
+/** A host-rendered plugin component. Hooks remain available for reactive host state. */
+type PluginComponent<TWebViewPayload = unknown> = {
+	bivarianceHack(props: PluginComponentProps<TWebViewPayload>): ReactNode;
+}["bivarianceHack"];
+/** A guard evaluated by the host to decide whether a contribution should render. */
+type PluginWhen<TConfig = unknown> = (ctx: PluginContext<TConfig>) => boolean;
+/** A tab contributed to the project sidebar. */
+interface SidebarTabDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	icon?: PluginIcon;
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** Declares a sidebar tab contribution. */
+declare function defineSidebarTab<TConfig = unknown>(input: SidebarTabDefinition<TConfig>): SidebarTabDefinition<TConfig>;
+/** A page contributed to Pragma Settings. */
+interface SettingsPageDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	icon?: PluginIcon;
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** Declares a React page contribution for Pragma Settings. */
+declare function defineSettingsPage<TConfig = unknown>(input: SettingsPageDefinition<TConfig>): SettingsPageDefinition<TConfig>;
+/** Options used when opening a plugin web view tab. */
+interface OpenWebViewOptions<TPayload = unknown> {
+	/** Overrides the tab title; falls back to the web view title, then id. */
+	title?: string;
+	/** JSON-serializable data made available through `useWebViewPayload`. */
+	payload?: TPayload;
+	/** Stable key used by the host to focus an existing matching web view tab. */
+	dedupeKey?: string;
+}
+/** A plugin-defined React view that renders inside a workspace tab web view. */
+interface WebViewDefinition<TPayload = unknown> {
+	id: string;
+	title?: string;
+	component: PluginComponent<TPayload>;
+	/** Opens this web view as a workspace tab. */
+	open(options?: OpenWebViewOptions<TPayload>): Promise<void>;
+}
+/** Input accepted by `defineWebView`; the returned definition adds `.open()`. */
+type WebViewDefinitionInput<TPayload = unknown> = Omit<WebViewDefinition<TPayload>, "open">;
+/** Reference accepted by `openWebView`: a web view handle or a unique web view id. */
+type WebViewReference<TPayload = unknown> = WebViewDefinition<TPayload> | string;
+/** Opens a plugin web view tab by handle, or by id when the id is unambiguous. */
+declare function openWebView2<TPayload = unknown>(webView: WebViewReference<TPayload>, options?: OpenWebViewOptions<TPayload>): Promise<void>;
+/** Declares a plugin web view contribution. */
+declare function defineWebView<TPayload = unknown>(input: WebViewDefinitionInput<TPayload>): WebViewDefinition<TPayload>;
+/** An item contributed to the workspace topper bar. */
+interface TopperItemDefinition<TConfig = unknown> {
+	align: "left" | "right";
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** Declares a topper-bar item contribution. */
+declare function defineTopperItem<TConfig = unknown>(input: TopperItemDefinition<TConfig>): TopperItemDefinition<TConfig>;
+/** A card contributed to the project sidebar. */
+interface SidebarCardDefinition<TConfig = unknown> {
+	title: string;
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** Declares a sidebar card contribution. */
+declare function defineSidebarCard<TConfig = unknown>(input: SidebarCardDefinition<TConfig>): SidebarCardDefinition<TConfig>;
+/** A command contributed to the command palette / keybindings surface. */
+interface CommandDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	icon?: PluginIcon;
+	defaultBinding?: string;
+	hidden?: boolean;
+	run: (ctx: PluginContext<TConfig>, args?: unknown) => void | Promise<void>;
+}
+/** Declares a command contribution. */
+declare function defineCommand<TConfig = unknown>(input: CommandDefinition<TConfig>): CommandDefinition<TConfig>;
+/**
+* Timed input sent to the agent's terminal after launch and before an
+* optional prompt prefill. Field names mirror the host's existing
+* the old `~/.pragma/agents/<id>/config.json` shape (`startupInput`) exactly, so
+* plugin-contributed agents carry over unchanged.
+*/
+interface AgentStartupInput {
+	delayMs: number;
+	data: string;
+}
+/** One selectable reasoning-effort level for a model. */
+interface AgentReasoning {
+	id: string;
+	name: string;
+}
+/** One selectable model for an agent. */
+interface AgentModelEntry {
+	id: string;
+	name: string;
+	reasoning?: AgentReasoning[];
+}
+/** One selectable permission mode for an agent. */
+interface AgentPermissionMode {
+	id: string;
+	name: string;
+}
+/** Builds the launch command-line arguments for a selected model/reasoning/permission mode. */
+interface AgentArgsBuilder {
+	model: (modelId: string) => string[];
+	reasoning: (reasoningId: string) => string[];
+	modelReasoning?: (modelId: string, reasoningId: string) => string[];
+	permissionMode: (permissionModeId: string) => string[];
+}
+/** Optional agent capabilities that can be excluded from `pragma-cli agent verify`. */
+type AgentFeature = SharedAgentFeature;
+/**
+* Declares an agent a plugin makes launchable from Pragma. Field names below
+* `launch`/`models`/`permissionModes`/`args` are new, JS-only additions;
+* `startupInput`/`prefillDelayMs`/`prefillMode`/`prefillSubmit`/
+* `prefillSubmitDelayMs` carry over the existing agent-launcher config shape
+* exactly (see `src-tauri/src/agents.rs`).
+*/
+interface AgentDefinition<TConfig = unknown> {
+	id: string;
+	name: string;
+	icon: PluginIcon;
+	/** Browser URL, absolute filesystem path, or plugin-dir-relative asset path for the agent icon. */
+	iconPath?: string;
+	launch: {
+		command: string[];
+	};
+	models: AgentModelEntry[] | ((ctx: PluginContext<TConfig>) => Promise<AgentModelEntry[]>);
+	permissionModes: AgentPermissionMode[];
+	args: AgentArgsBuilder;
+	/** Capabilities this agent does not support; matching verification scenarios are skipped. */
+	excludeFeatures?: AgentFeature[];
+	startupInput?: AgentStartupInput[];
+	prefillDelayMs?: number;
+	prefillMode?: "bracketed" | "plain";
+	prefillSubmit?: string;
+	prefillSubmitDelayMs?: number;
+}
+/** Declares an agent contribution. */
+declare function defineAgent<TConfig = unknown>(input: AgentDefinition<TConfig>): AgentDefinition<TConfig>;
+import { ButtonHTMLAttributes, ComponentType as ComponentType2, HTMLAttributes, JSX } from "react";
+import { AgentMessage as AgentMessage2 } from "@pragma-sh/sdk";
+import { AgentMessage, BranchSyncStatus, DirEntry, FileContents, PragmaClient as PragmaClient2, WorktreeChanges } from "@pragma-sh/sdk";
+/**
+* The hook implementations the Pragma host installs at `__PRAGMA__.hooks`.
+* Every plugin-facing hook below is a thin delegator onto this object — the
+* host owns the real React state/effects; `@pragma-sh/plugin` only declares the
+* shape so plugin authors get full typing.
+*/
+interface PragmaHooksBridge {
+	usePluginConfig: <TConfig>() => TConfig;
+	useSdk: () => PragmaClient2;
+	useProject: () => PluginProject | null;
+	useTheme: () => "light" | "dark";
+	useWebViewPayload: <T>() => T | undefined;
+	useNotify: () => (message: string, options?: PluginNotifyOptions) => void;
+	useStoredState: <T>(key: string, initialValue: T) => [T, (value: T | ((prev: T) => T)) => void];
+	useSdkQuery: <T>(queryFn: (sdk: PragmaClient2) => Promise<T>, deps: readonly unknown[]) => PluginQueryResult<T>;
+	useEvent: <TPayload>(eventName: string, handler: (payload: TPayload) => void) => void;
+	useWorktreeChanges: (worktreeRoot: string | null) => PluginQueryResult<WorktreeChanges>;
+	useBranchStatus: (worktreeRoot: string | null) => PluginQueryResult<BranchSyncStatus>;
+	useDirEntries: (root: string | null, path?: string) => PluginQueryResult<DirEntry[]>;
+	useFileContents: (root: string | null, path: string | null) => PluginQueryResult<FileContents>;
+	useAgentStatuses: (worktreeId: string | null) => PluginQueryResult<PluginAgentStatusEntry[]>;
+	useAgentMessages: (worktreeId: string | null, tabId?: string | null) => PluginQueryResult<AgentMessage[]>;
+	useSessions: () => PluginQueryResult<PluginSessionSummary[]>;
+}
+/** This plugin's config, already validated against its `config` schema. */
+declare function usePluginConfig<TConfig = unknown>(): TConfig;
+/** Typed SDK client for talking to the local Pragma gateway. */
+declare function useSdk(): PragmaClient2;
+/** The active project, or `null` when no project is selected. */
+declare function useProject(): PluginProject | null;
+/** The host's current color theme. */
+declare function useTheme(): "light" | "dark";
+/** Payload supplied when the current plugin web view tab was opened. */
+declare function useWebViewPayload<TPayload = unknown>(): TPayload | undefined;
+/** Returns a function that shows an in-app notification. */
+declare function useNotify(): (message: string, options?: PluginNotifyOptions) => void;
+/** State persisted across app restarts, scoped to this plugin. */
+declare function useStoredState<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void];
+/** Runs an arbitrary SDK query, re-running when `deps` change. */
+declare function useSdkQuery<T>(queryFn: (sdk: PragmaClient2) => Promise<T>, deps: readonly unknown[]): PluginQueryResult<T>;
+/** Subscribes to a named host event (e.g. `"agent.report"`) for this plugin's lifetime. */
+declare function useEvent<TPayload = unknown>(eventName: string, handler: (payload: TPayload) => void): void;
+/** Uncommitted + committed diff summary for a worktree root. */
+declare function useWorktreeChanges(worktreeRoot: string | null): PluginQueryResult<WorktreeChanges>;
+/** Ahead/behind sync status against the branch's upstream. */
+declare function useBranchStatus(worktreeRoot: string | null): PluginQueryResult<BranchSyncStatus>;
+/** Directory listing for a worktree-relative path (defaults to the root itself). */
+declare function useDirEntries(root: string | null, path?: string): PluginQueryResult<DirEntry[]>;
+/** File contents for a worktree-relative path. */
+declare function useFileContents(root: string | null, path: string | null): PluginQueryResult<FileContents>;
+/** Live agent statuses for a worktree. */
+declare function useAgentStatuses(worktreeId: string | null): PluginQueryResult<PluginAgentStatusEntry[]>;
+/** Live rich agent messages for a worktree, optionally scoped to one tab. */
+declare function useAgentMessages(worktreeId: string | null, tabId?: string | null): PluginQueryResult<AgentMessage[]>;
+/** Live PTY sessions. */
+declare function useSessions(): PluginQueryResult<PluginSessionSummary[]>;
+import * as import_1sj3pb from "react";
+import * as import_ilo9os from "react-dom";
+import { z as z_3e } from "zod";
+/** Minimal host Button props exposed through `@pragma-sh/plugin/ui`. */
+type PragmaButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+	variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "success" | "warning" | "link";
+	size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg";
+};
+/** Minimal host keyboard-badge props exposed through `@pragma-sh/plugin/ui`. */
+type PragmaKbdProps = HTMLAttributes<HTMLElement>;
+/** A rendered UI primitive contributed by the host (`@pragma-sh/plugin/ui`). */
+interface PragmaUiBridge {
+	Button: ComponentType2<PragmaButtonProps>;
+	Kbd: ComponentType2<PragmaKbdProps>;
+}
+/** A rendered icon component contributed by the host (`@pragma-sh/plugin/icons`). */
+type PragmaIconsBridge = Record<string, ComponentType2<{
+	className?: string;
+}>>;
+/** Host actions exposed to plugin code outside React render trees. */
+interface PragmaActionsBridge {
+	openWebView: <TPayload = unknown>(webView: WebViewReference<TPayload>, options?: OpenWebViewOptions<TPayload>) => Promise<void>;
+	agents: {
+		/** Reports one rich agent message through the host SDK bridge. */
+		reportMessage: (message: AgentMessage2) => Promise<void>;
+	};
+	events: {
+		/** Subscribes to one named host event. */
+		subscribe: (eventName: string, handler: (payload: unknown) => void) => () => void;
+	};
+	theme: {
+		/** Returns the host's current color theme. */
+		get: () => "light" | "dark";
+		/** Subscribes to host color-theme changes. */
+		subscribe: (listener: () => void) => () => void;
+	};
+	sessions: {
+		/** Lists current host sessions. */
+		list: () => Promise<PluginSessionSummary[]>;
+	};
+}
+/**
+* The runtime surface the Pragma host installs at `globalThis.__PRAGMA__`
+* before any plugin bundle is imported. Every value here is a compile-time
+* stub in `@pragma-sh/plugin` — the host supplies the real implementation so
+* plugin bundles never need to bundle React, zod, or host UI code themselves.
+*/
+interface PragmaBridge {
+	react: typeof import_1sj3pb;
+	reactDom: typeof import_ilo9os;
+	jsxRuntime: {
+		jsx: (type: unknown, props: unknown, key?: unknown) => JSX.Element;
+		jsxs: (type: unknown, props: unknown, key?: unknown) => JSX.Element;
+		Fragment: unknown;
+	};
+	zod: typeof z_3e;
+	ui: PragmaUiBridge;
+	icons: PragmaIconsBridge;
+	hooks: PragmaHooksBridge;
+	actions: PragmaActionsBridge;
+}
+/**
+* Returns the host-installed Pragma bridge, throwing a clear error when a
+* plugin module runs outside a Pragma host (e.g. imported directly in a Node
+* script, a unit test, or a non-Pragma bundler build).
+*/
+declare function getBridge(): PragmaBridge;
+/**
+* The `@pragma-sh/plugin` version a plugin was compiled against, stamped onto
+* every plugin definition by `definePlugin`. Used by the Pragma host to check
+* compatibility before loading a plugin bundle.
+*/
+declare const PLUGIN_API_VERSION = "0.1.0";
+import { AgentReportPayload } from "@pragma-sh/constants";
+import { ZodType, ZodTypeAny } from "zod";
+import { AgentMessage as AgentMessage3, PragmaClient as PragmaClient3 } from "@pragma-sh/sdk";
+/** Declares a watcher a plugin attaches to one of its agents' sessions. */
+interface WatcherDefinition<TConfig = unknown> {
+	/** The `defineAgent` id this watcher attaches to. */
+	agent: string;
+	/** Runs once per launched session; lives until the session exits. */
+	watch: (ctx: WatcherContext<TConfig>) => void | Promise<void>;
+}
+/** Host-side context passed to a running watcher instance. */
+interface WatcherContext<TConfig = unknown> {
+	/** Typed gateway SDK. */
+	sdk: PragmaClient3;
+	/** Full agent id this watcher instance is bound to (plugin-qualified). */
+	agentId: string;
+	/** This plugin's validated config. */
+	config: TConfig;
+	/** Session this watcher is attached to. */
+	session: {
+		id: string;
+		tabId: string;
+		worktreeId: string;
+	};
+	/** Decoded terminal output chunks for this session. */
+	output: AsyncIterable<string>;
+	/** Writes bytes into the live terminal session. */
+	sendKeys: (data: string) => Promise<void>;
+	/** Reports a rich message for this watcher-owned agent. */
+	reportMessage: (msg: Omit<AgentMessage3, "agent" | "tabId" | "worktreeId">) => Promise<void>;
+	/** Aborts when the session exits or the watcher is stopped. */
+	signal: AbortSignal;
+}
+/** Declares a watcher contribution. */
+declare function defineWatcher<TConfig = unknown>(input: WatcherDefinition<TConfig>): WatcherDefinition<TConfig>;
+/** One finite or unlimited usage category reported by a provider. */
+interface UsageLimit {
+	id: string;
+	title: string;
+	used: number;
+	/** A null limit represents unlimited usage. */
+	limit: number | null;
+	/** Milliseconds until this category resets, measured from `observedAt`. */
+	resetsInMs?: number;
+}
+/** A successful provider snapshot. */
+interface UsageLimitsReady {
+	status: "ready";
+	/** Unix time in milliseconds when the provider observed these values. */
+	observedAt: number;
+	/** Optional collapsed-row metric derived separately from the detailed limits. */
+	summary?: UsageLimit;
+	limits: UsageLimit[];
+}
+/** Why a provider cannot currently report usage limits. */
+type UsageLimitsUnavailableReason = "not-configured" | "authentication-required" | "unsupported" | "error";
+/** A provider state that requires user or platform action before loading. */
+interface UsageLimitsUnavailable {
+	status: "unavailable";
+	reason: UsageLimitsUnavailableReason;
+	message: string;
+}
+/** Result returned by a usage-limit provider. Unexpected failures should throw. */
+type UsageLimitsResult = UsageLimitsReady | UsageLimitsUnavailable;
+/** A plugin-owned usage source rendered by Pragma's shared usage-limits UI. */
+interface UsageLimitProviderDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	/** Absolute URL for viewing this provider's usage in its dashboard. */
+	dashboardUrl: string;
+	icon?: PluginIcon;
+	/** Browser URL, absolute path, or plugin-directory-relative asset path. */
+	iconPath?: string;
+	/** Category rendered in the provider's collapsed summary row. */
+	primaryLimitId: string;
+	/** Requested refresh cadence. The host may enforce a larger minimum. */
+	refreshIntervalMs?: number;
+	load: (ctx: PluginContext<TConfig>) => Promise<UsageLimitsResult>;
+}
+/** Declares a provider for Pragma's shared usage-limits UI. */
+declare function defineUsageLimitProvider<TConfig = unknown>(input: UsageLimitProviderDefinition<TConfig>): UsageLimitProviderDefinition<TConfig>;
+/** Color schemes supported by Pragma themes. */
+type ThemeMode = "light" | "dark";
+/** Theme token overrides for one color scheme, keyed without the `--` prefix. */
+type ThemeColors = Record<ThemeMode, Record<string, string>>;
+/** A selectable theme contributed to Pragma's Theme settings. */
+interface ThemeDefinition {
+	/** Stable id within this plugin. */
+	id: string;
+	/** Human-readable name shown in Theme settings. */
+	name: string;
+	/** Optional detail shown under the theme name. */
+	description?: string;
+	/** Light and dark Pragma theme-token overrides. */
+	colors: ThemeColors;
+}
+/** Declares a theme contribution. */
+declare function defineTheme(input: ThemeDefinition): ThemeDefinition;
+/** Infers a config schema's parsed output type, defaulting to `unknown` when no schema is given. */
+type InferConfig<TConfigSchema extends ZodTypeAny> = TConfigSchema extends ZodType<infer Output> ? Output : unknown;
+/** UI surfaces a plugin can contribute to. */
+interface PluginUiContributions<TConfig = unknown> {
+	sidebarTabs?: SidebarTabDefinition<TConfig>[];
+	settingsPages?: SettingsPageDefinition<TConfig>[];
+	topper?: TopperItemDefinition<TConfig>[];
+	sidebarCards?: SidebarCardDefinition<TConfig>[];
+	webViews?: WebViewDefinition[];
+}
+/** Whether a plugin's declared values are merged with or replace host defaults. */
+type PluginContributionStrategy = "merge" | "replace";
+/** Default settings values a plugin contributes. */
+interface PluginSettingsContributions {
+	strategy?: PluginContributionStrategy;
+	values: Record<string, unknown>;
+}
+/** Default keybindings a plugin contributes. */
+interface PluginKeybindingsContributions {
+	strategy?: PluginContributionStrategy;
+	bindings: Record<string, string>;
+}
+/** Daemon-forwarded events a plugin can subscribe to declaratively. */
+interface PluginEventHandlers<TConfig = unknown> {
+	"agent.report"?: (event: AgentReportPayload, ctx: PluginContext<TConfig>) => void;
+	deepLink?: (event: PluginDeepLinkEvent, ctx: PluginContext<TConfig>) => void;
+}
+/** The object shape passed to `definePlugin`. */
+interface PluginDefinitionInput<TConfigSchema extends ZodTypeAny = ZodTypeAny> {
+	name: string;
+	description?: string;
+	icon?: PluginIcon;
+	config?: TConfigSchema;
+	ui?: PluginUiContributions<InferConfig<TConfigSchema>>;
+	agents?: AgentDefinition<InferConfig<TConfigSchema>>[];
+	watchers?: WatcherDefinition<InferConfig<TConfigSchema>>[];
+	commands?: CommandDefinition<InferConfig<TConfigSchema>>[];
+	settings?: PluginSettingsContributions;
+	keybindings?: PluginKeybindingsContributions;
+	events?: PluginEventHandlers<InferConfig<TConfigSchema>>;
+	usageLimits?: UsageLimitProviderDefinition<InferConfig<TConfigSchema>>[];
+	themes?: ThemeDefinition[];
+	css?: string;
+	/** Runs once when Pragma first discovers this plugin installation. */
+	onInstall?: (ctx: PluginContext<InferConfig<TConfigSchema>>) => void | Promise<void>;
+	/** Runs once during every Pragma server boot. */
+	onPragmaLoad?: (ctx: PluginContext<InferConfig<TConfigSchema>>) => void | Promise<void>;
+	activate?: (ctx: PluginContext<InferConfig<TConfigSchema>>) => void | (() => void);
+}
+/**
+* A fully-declared plugin, as returned by `definePlugin`. `__apiVersion` is
+* stamped automatically — plugin authors never set it themselves, and it
+* lives under a deliberately internal-looking name so it doesn't show up as
+* something to configure.
+*/
+interface PluginDefinition<TConfigSchema extends ZodTypeAny = ZodTypeAny> extends PluginDefinitionInput<TConfigSchema> {
+	/** @internal The `@pragma-sh/plugin` version this plugin was compiled against. */
+	readonly __apiVersion: string;
+}
+/**
+* Declares a Pragma plugin. This is the single entry point a plugin's bundle
+* must default-export. Stamps the compiled-against `@pragma-sh/plugin` version
+* onto the result so the host can check compatibility before loading it.
+*/
+declare function definePlugin<TConfigSchema extends ZodTypeAny = ZodTypeAny>(input: PluginDefinitionInput<TConfigSchema>): PluginDefinition<TConfigSchema>;
+/** Returns the host's current color theme outside React. */
+declare function getTheme(): "light" | "dark";
+/** Subscribes to color-theme changes outside React. Returns an unsubscribe function. */
+declare function subscribeTheme(listener: (theme: "light" | "dark") => void): () => void;
+/** Subscribes to a named host event outside React. Returns an unsubscribe function. */
+declare function subscribeEvent<TPayload = unknown>(eventName: string, handler: (payload: TPayload) => void): () => void;
+/** Lists current host sessions outside React. */
+declare function listSessions(): Promise<PluginSessionSummary[]>;
+import { z as ZodNamespace } from "zod";
+/**
+* The zod v4 namespace, delegated to the host's own zod instance at runtime
+* via the Pragma bridge so plugin bundles never bundle zod themselves. Typed
+* against real zod so `z.object(...)`, `z.infer<...>`, etc. work exactly as
+* they would with a direct zod import.
+*/
+declare const z: typeof ZodNamespace;
+export { z, useWorktreeChanges, useWebViewPayload, useTheme, useStoredState, useSessions, useSdkQuery, useSdk, useProject, usePluginConfig, useNotify, useFileContents, useEvent, useDirEntries, useBranchStatus, useAgentStatuses, useAgentMessages, subscribeTheme, subscribeEvent, openWebView2 as openWebView, listSessions, getTheme, getBridge, defineWebView, defineWatcher, defineUsageLimitProvider, defineTopperItem, defineTheme, defineSidebarTab, defineSidebarCard, defineSettingsPage, definePlugin, defineCommand, defineAgent, WebViewReference, WebViewDefinitionInput, WebViewDefinition, WatcherDefinition, WatcherContext, UsageLimitsUnavailableReason, UsageLimitsUnavailable, UsageLimitsResult, UsageLimitsReady, UsageLimitProviderDefinition, UsageLimit, TopperItemDefinition, ThemeMode, ThemeDefinition, ThemeColors, SidebarTabDefinition, SidebarCardDefinition, SettingsPageDefinition, PragmaUiBridge, PragmaIconsBridge, PragmaHooksBridge, PragmaBridge, PragmaActionsBridge, PluginWhen, PluginUiContributions, PluginStorage, PluginSettingsContributions, PluginSessionSummary, PluginQueryResult, PluginProject, PluginNotifyOptions, PluginKeybindingsContributions, PluginIcon, PluginEventHandlers, PluginDefinitionInput, PluginDefinition, PluginDeepLinkEvent, PluginContributionStrategy, PluginContext, PluginComponentProps, PluginComponent, PluginAgentStatusEntry, PLUGIN_API_VERSION, OpenWebViewOptions, InferConfig, CommandDefinition, AgentStartupInput, AgentReasoning, AgentPermissionMode, AgentModelEntry, AgentFeature, AgentDefinition, AgentArgsBuilder };