The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
feat(desktop): preview.executeJavaScript SDK door for plugins
Schildkrote416d096e36f5
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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 petctx.runAction('view.showBrowser') // run a built-in app action → { ok: true } | { ok: false, reason, error }ctx.listActions() // [{ id, label, category }] — the ids runAction acceptshost.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'