Skip to content

The agent that grows with you

feat(desktop): preview.executeJavaScript SDK door for plugins

Schildkrote416d096e36f5
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.ts
index 1a126f4d201..672c544f495 100644
--- a/apps/desktop/src/sdk/index.ts
+++ b/apps/desktop/src/sdk/index.ts
@@ -111,6 +111,7 @@ import { pluginDecisions, profiles, skills, toolsets } from './bridge'
import { composerHost } from './composer'
import { i18nHost } from './i18n'
import { planPluginOpenSession } from './plugin-open-session-plan'
+import { executePreviewJavaScript, previewIsAvailable } from './preview'
import {
type PluginProfileRequestOptions,
type PluginProfileRoute,
@@ -606,6 +607,18 @@ export const host = {
/** Read, update, and observe the allowlisted Desktop appearance preferences. */
settings: desktopSettings,
+ /**
+ * Run JavaScript in the focused session's live preview Browser tab — the
+ * same guest `executeJavaScript` drive_preview and the tour use. Rejects
+ * when this window has no mounted webview (empty rail, a file peek, or a
+ * Browser popped out into another window). Always a Promise so a plugin
+ * `.catch()` sees a missing page the same way it sees a guest throw.
+ */
+ preview: {
+ executeJavaScript: executePreviewJavaScript,
+ isAvailable: previewIsAvailable
+ },
+
/** Toast into the app's notification stack. */
notify,
notifyError,
diff --git a/apps/desktop/src/sdk/preview.test.ts b/apps/desktop/src/sdk/preview.test.ts
new file mode 100644
index 00000000000..d4718ff2bc1
--- /dev/null
+++ b/apps/desktop/src/sdk/preview.test.ts
@@ -0,0 +1,68 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { registerPreviewScriptRunner } from '@/app/chat/right-rail/preview-script-runner'
+import { host } from '@/sdk'
+import { $rightRailActiveTabId } from '@/store/layout'
+import { closeRightRail, openPreview } from '@/store/preview'
+
+function urlTarget(url: string) {
+ return { kind: 'url' as const, label: 'Browser', source: url, url }
+}
+
+function fileTarget(path: string) {
+ return {
+ kind: 'file' as const,
+ label: path,
+ path,
+ previewKind: 'text' as const,
+ source: path,
+ url: `file://${path}`
+ }
+}
+
+describe('host.preview', () => {
+ let unbind: (() => void) | undefined
+
+ beforeEach(() => {
+ unbind?.()
+ unbind = undefined
+ closeRightRail()
+ window.localStorage.clear()
+ })
+
+ it('rejects when no preview page is open', async () => {
+ expect(host.preview.isAvailable()).toBe(false)
+ await expect(host.preview.executeJavaScript('1 + 1')).rejects.toThrow('No preview page is open.')
+ })
+
+ it('is unavailable on a file peek that never registered a guest runner', () => {
+ openPreview(fileTarget('/work/notes.txt'))
+ expect(host.preview.isAvailable()).toBe(false)
+ })
+
+ it('runs JS on the active Browser tab and returns the guest value', async () => {
+ openPreview(urlTarget('https://example.com'))
+ const tabId = $rightRailActiveTabId.get()!
+
+ unbind = registerPreviewScriptRunner(tabId, async code => ({ ran: code }))
+
+ expect(host.preview.isAvailable()).toBe(true)
+ await expect(host.preview.executeJavaScript('document.title')).resolves.toEqual({ ran: 'document.title' })
+ })
+
+ it('rejects a non-string without throwing synchronously', async () => {
+ const pending = host.preview.executeJavaScript(1 as never)
+
+ expect(pending).toBeInstanceOf(Promise)
+ await expect(pending).rejects.toThrow('host.preview.executeJavaScript requires a string')
+ })
+
+ it('forwards a guest throw as a rejection', async () => {
+ openPreview(urlTarget('https://example.com'))
+ unbind = registerPreviewScriptRunner($rightRailActiveTabId.get()!, async () => {
+ throw new Error('guest exploded')
+ })
+
+ await expect(host.preview.executeJavaScript('x')).rejects.toThrow('guest exploded')
+ })
+})
diff --git a/apps/desktop/src/sdk/preview.ts b/apps/desktop/src/sdk/preview.ts
new file mode 100644
index 00000000000..2f47813e6e6
--- /dev/null
+++ b/apps/desktop/src/sdk/preview.ts
@@ -0,0 +1,40 @@
+/**
+ * Plugin door into the preview Browser's guest page.
+ *
+ * drive_preview and the preview tour already reach the guest through
+ * `activePreviewScriptRunner` (the pane registers webview.executeJavaScript).
+ * Plugins had no supported equivalent, so authors scraped `<webview>` out of
+ * the app DOM — which the catalog `desktop surface` rule exists to stop.
+ * This module is that equivalent: the focused session's live Browser tab, in
+ * this window. A file peek, an empty rail, or a Browser popped out into
+ * another window have no runner here.
+ */
+import { activePreviewScriptRunner } from '@/app/chat/right-rail/preview-script-runner'
+
+export const PREVIEW_NOTHING_OPEN = 'No preview page is open.'
+
+/** True when this window has a live guest page for the focused session. */
+export function previewIsAvailable(): boolean {
+ return Boolean(activePreviewScriptRunner())
+}
+
+/**
+ * Run `code` in the focused session's active preview Browser tab.
+ * Always a Promise: a missing page and a guest throw both reject, so plugin
+ * `.catch()` sees them the same way (host doors are async-safe).
+ */
+export function executePreviewJavaScript(code: string): Promise<unknown> {
+ return (async () => {
+ if (typeof code !== 'string') {
+ throw new Error('host.preview.executeJavaScript requires a string')
+ }
+
+ const run = activePreviewScriptRunner()
+
+ if (!run) {
+ throw new Error(PREVIEW_NOTHING_OPEN)
+ }
+
+ return run(code)
+ })()
+}
diff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.md
index b9bd9aa3680..f47d1b25889 100644
--- a/website/docs/developer-guide/desktop-plugin-sdk.md
+++ b/website/docs/developer-guide/desktop-plugin-sdk.md
@@ -43,6 +43,10 @@ plugin, and fail to resolve in a disk plugin). Capability comes in tiers:
model, profile, viewport. `gateway` is the WebSocket, not turn-busy.
- **`host.*` actions** — curated safe verbs: toast, navigate, tail logs,
restart the gateway, subscribe to the gateway event stream.
+- **`host.preview`** — run JavaScript in the focused session's live preview
+ Browser tab (`executeJavaScript` / `isAvailable`). Same guest runner as
+ `drive_preview`. Missing when this window has no webview (empty rail, a
+ file peek, or a popped-out Browser).
- **`host.request`** — the gateway JSON-RPC door: sessions, config, skills,
cron — everything the app itself calls.
- **`captureGatewayFileDownload()`** — capture a gateway file-save action
@@ -1282,6 +1286,10 @@ ctx.pet.visible // ReadableAtom<boolean> — is a pet
ctx.runAction('view.showBrowser') // run a built-in app action → { ok: true } | { ok: false, reason, error }
ctx.listActions() // [{ id, label, category }] — the ids runAction accepts
host.navigate('/route') // hash-route navigation
+host.preview.isAvailable() // focused session has a live Browser tab in THIS window
+host.preview.executeJavaScript(code) // run JS in that guest page → Promise<unknown>
+ // rejects 'No preview page is open.' when unavailable
+ // (file peek, empty rail, or popped-out Browser)
host.openSession(id, { profile?, intent? }) // open a stored session core-style;
// profile: soft-swap to that profile's backend first
// intent: 'in-place' (default) | 'stack' | 'tab' | 'window'