Desktop Plugin SDK (@mibyan/plugin-sdk)

// ~/.mibyan/desktop-plugins/hello/plugin.js
import { host, haptic, useValue } from '@mibyan/plugin-sdk'
import { jsx, jsxs } from 'react/jsx-runtime'

function HelloPane() {
  const gateway = useValue(host.state.gateway)

  return jsxs('div', {
    className: 'flex h-full flex-col gap-2 p-3 text-sm',
    children: [
      jsx('div', { className: 'font-medium', children: 'Hello, Mibyan' }),
      jsx('div', {
        className: 'text-(--ui-text-tertiary)',
        children: `gateway: ${gateway}`
      })
    ]
  })
}

export default {
  id: 'hello', // must match the folder name
  name: 'Hello',
  register(ctx) {
    ctx.register({
      id: 'pane',
      area: 'panes',
      title: 'hello',
      data: { placement: 'right', width: '260px' },
      render: () => jsx(HelloPane, {})
    })
    ctx.register({
      id: 'chip',
      area: 'statusBar.right',
      order: 130,
      render: () =>
        jsx('button', {
          type: 'button',
          className: 'px-1.5 text-[0.6875rem] text-(--ui-text-tertiary)',
          onClick: () => {
            haptic('tap')
            host.notify({ kind: 'info', message: 'Hello from my plugin!' })
          },
          children: 'hello'
        })
    })
  }
}

interface MibyanPlugin {
  /** Stable slug — becomes the `plugin:<id>` source and the id namespace. */
  id: string
  /** Human name for Settings / about UI. Defaults to `id`. */
  name?: string
  /** Registers on load when the user hasn't chosen (default true). Set false
   *  for opt-in plugins: they inventory in Capabilities ▸ Plugins, off until the
   *  user flips the switch. */
  defaultEnabled?: boolean
  /** Called once at load; wire contributions through `ctx`. */
  register: (ctx: PluginContext) => void
}

interface PluginContext {
  /** Resolved source tag, e.g. `'plugin:hello'`. */
  readonly source: string
  /** Register one contribution (id namespaced, source stamped). Returns a disposer. */
  register: (c: PluginContribution) => () => void
  /** Register several at once; the returned disposer removes all of them. */
  registerMany: (cs: PluginContribution[]) => () => void
  /** REST to this plugin's own backend namespace (`/api/plugins/<id>`). */
  rest: <T>(path: string, opts?: PluginRestOptions) => Promise<T>
  /** Live WebSocket to this plugin's own namespace. Returns a disposer. */
  socket: (path: string, onMessage: (data: unknown) => void) => () => void
  /** Gateway event stream by type (`'*'` = all). Tracked: removed on unload/reload/disable. */
  onEvent: (type: string, listener: (event: GatewayEvent) => void) => () => void
  /** Any other cleanup to run on unload/reload/disable (store subscriptions, injected DOM). */
  onDispose: (fn: () => void) => void
  /** Scoped timers and DOM listeners — cleared with the plugin. Each returns a disposer. */
  setTimeout: (fn: () => void, ms: number) => () => void
  setInterval: (fn: () => void, ms: number) => () => void
  addEventListener: (target: EventTarget, type: string, listener: EventListener, options?: AddEventListenerOptions | boolean) => () => void
  /** The curated OS door: native notification, open-external, reveal-in-file-manager, clipboard. */
  os: PluginOs
  /** Plugin-scoped JSON persistence (keys live under `mibyan.plugin.<id>.`). */
  storage: PluginStorage
}

interface Contribution {
  id: string          // you write the local id; the host namespaces it
  area: string        // WHERE it goes (a contribution-area constant)
  title?: string
  order?: number      // sort within the area (lower = earlier)
  when?: () => boolean // dynamic visibility; re-evaluated by the area
  enabled?: boolean
  render?: () => ReactNode  // the component to mount
  data?: unknown      // area-specific payload (see the cookbook)
}

ctx.register({
  id: 'pane',
  area: 'panes',
  title: 'my pane',
  data: { placement: 'right', width: '260px' },
  render: () => jsx(MyPane, {})
})

// Below the conversation, 200px tall.
data: {
  placement: 'bottom',
  dock: { pane: 'workspace', pos: 'bottom' },
  height: '200px'
}

import { ROUTES_AREA, SIDEBAR_NAV_AREA } from '@mibyan/plugin-sdk'

ctx.registerMany([
  {
    id: 'page',
    area: ROUTES_AREA,
    data: { path: '/my-page' },
    render: () => jsx(MyPage, {})
  },
  {
    id: 'nav',
    area: SIDEBAR_NAV_AREA,
    data: { path: '/my-page', label: 'My Page', codicon: 'project' }
  }
])

import { STATUSBAR_AREAS, TITLEBAR_AREAS } from '@mibyan/plugin-sdk'

ctx.register({
  id: 'count',
  area: STATUSBAR_AREAS.right,
  order: 120,
  render: () => jsx(MyStatus, {})
})

import { PALETTE_AREA, KEYBINDS_AREA } from '@mibyan/plugin-sdk'

ctx.registerMany([
  {
    id: 'open',
    area: PALETTE_AREA,
    data: {
      id: 'my-page.open',
      label: 'Open My Page',
      keywords: ['my', 'page'],
      run: () => host.navigate('/my-page')
    }
  },
  {
    id: 'refresh',
    area: KEYBINDS_AREA,
    data: {
      id: 'my-page.refresh',
      label: 'Refresh My Page',
      category: 'My Plugin',
      defaults: ['mod+shift+r'],
      run: () => void doRefresh()
    }
  }
])

import { THEMES_AREA } from '@mibyan/plugin-sdk'

ctx.register({ id: 'noir', area: THEMES_AREA, data: myDesktopTheme })

import { Button, useTheme } from '@mibyan/plugin-sdk'

function ThemePicker() {
  const { availableThemes, setTheme, themeName } = useTheme()

  return availableThemes.map(t => (
    <Button key={t.name} disabled={t.name === themeName} onClick={() => setTheme(t.name)}>
      {t.label}
    </Button>
  ))
}

import { host, requestTheme } from '@mibyan/plugin-sdk'

host.onEvent('gateway.ready', () => {
  if (!requestTheme('noir')) {
    host.notifyError('Connected, but the noir theme is not installed.')
  }
})

import { host } from '@mibyan/plugin-sdk'

// Append to the active composer (modes: 'block' | 'inline' | 'prefix';
// 'prefix' seats a slash command at the start). Acknowledged like setDraft:
// true when a mounted surface applied the text, false when the text is blank
// or no live surface answers for the address.
const inserted = await host.composer.insertText(null, 'draft note', { mode: 'inline' })

// Replace a session's whole draft — '@'-ref and '/command' tokens hydrate
// into chips exactly like an official paste. False when no mounted surface
// answers (an unmounted session is never half-written).
const ok = await host.composer.setDraft('sess-1', 'plan:\n- @file:src/app.ts')

// Read the live draft: the mounted surface's in-DOM text (unsaved keystrokes
// included), falling back to the debounced persisted stash. Null when nothing
// holds it.
const text = await host.composer.getDraft('sess-1')

// Send as if the user typed + pressed Enter. Fail-closed like the app's own
// panels: no visible surface for the address → false, never a broadcast.
const sent = host.composer.submit('sess-1', 'ship it')

// Put the caret in a composer (same addressing). insertText/setDraft already
// focus a visible surface they paint; use this to return the caret after a
// plugin popover closes or from a "go to input" keybind.
host.composer.focus(null)

host.composer: {
  getDraft(sessionId: string | null): Promise<string | null>
  setDraft(sessionId: string | null, text: string): Promise<boolean>
  insertText(sessionId: string | null, text: string, opts?: { mode?: 'block' | 'inline' | 'prefix' }): Promise<boolean>
  submit(sessionId: string | null, text: string): boolean
  focus(sessionId: string | null): void
}

import { SESSION_ROW_AREAS, type SessionRowSlotContribution } from '@mibyan/plugin-sdk'

ctx.register({
  area: SESSION_ROW_AREAS.trailing,
  id: 'my-tag',
  data: {
    render: ({ sessionId }) => (owned.has(sessionId) ? <span className="my-tag">★</span> : null)
  } satisfies SessionRowSlotContribution
})

host.sessions.pin(storedSessionId: string, pinned?: boolean, index?: number): void
host.sessions.reorder(storedSessionIds: string[]): void   // Recents; [] = clear manual order → default sort
host.sessions.reorderPinned(storedSessionIds: string[]): void  // Pinned section; omitted pins keep their slot
host.sessions.setColor(storedSessionId: string, color: string | null): void

import { COMPOSER_AREAS, type ComposerModelPillContext, type ComposerModelPillProvider } from '@mibyan/plugin-sdk'

interface ComposerModelPillContext {
  model: string            // the model slug the pill would show
  reasoningEffort: string  // the session's live effort level, '' when the model has none
  compact: boolean         // floating-composer mode: chevron only, providers are NOT consulted
}
interface ComposerModelPillProvider {
  label: (ctx: ComposerModelPillContext) => string | null
}

ctx.register({
  area: COMPOSER_AREAS.modelPill,
  id: 'my-label',
  data: { label: ({ model, reasoningEffort }) => reasoningEffort ? `${model} · ${reasoningEffort}` : null } satisfies ComposerModelPillProvider
})

register(ctx) {
  ctx.register({
    area: COMPOSER_AREAS.modelPill,
    id: 'compact-reasoning-label',
    // Decline (null) whenever there is nothing to change so the core label wins.
    data: { label: ({ model }) => shorten(model) ?? null }
  })
  // No MutationObserver, no setInterval, no injected <style>: the contribution is
  // disposed with the plugin.
}

APPEARANCE_AREAS = { extra: 'appearance.extra' } as const

ctx.register({
  area: APPEARANCE_AREAS.extra,
  id: 'session-colour-rules',          // unique within your plugin
  render: () => <MyAppearanceCard />   // any React tree; SDK hooks allowed
})

interface SandboxedFrameProps {
  src: string      // absolute http(s): or data: URL; any other scheme renders nothing (console.warn)
  title: string    // required — an untitled frame is unlabelled in the a11y tree
  sandbox?: string // extra tokens; filtered through the allowlist below
  className?: string; style?: CSSProperties
  onLoad?, onError?: ReactEventHandler<HTMLIFrameElement>
  ref?: Ref<HTMLIFrameElement>
}

import { TRANSCRIPT_DIRECTIVE_AREA } from '@mibyan/plugin-sdk'

ctx.register({
  id: 'task-card',
  area: TRANSCRIPT_DIRECTIVE_AREA,
  data: {
    name: 'task', // the model writes ::task{id="BB-12"}
    render: ({ attrs, streaming }) => jsx(TaskCard, { taskId: attrs.id, streaming })
  }
})

import { Contribute, WORKSPACE_PAGE_HEADER_AREA } from '@mibyan/plugin-sdk'

jsx(Contribute, {
  area: WORKSPACE_PAGE_HEADER_AREA,
  id: 'my-page:switcher', // namespace with your slug
  children: jsx(MySwitcher, {})
})

import { WorkspacePageHeaderControl } from '@mibyan/plugin-sdk'

jsx(WorkspacePageHeaderControl, {
  id: 'my-page:switcher', // namespace with your slug
  children: jsx(MySwitcher, {})
})

import { SIDEBAR_NAV_PREFS_AREA, type SidebarNavPrefsContribution } from '@mibyan/plugin-sdk'

// Payload (`data`) of a sidebarNav.prefs contribution
interface SidebarNavPrefsContribution {
  hide?: string[]   // rows to drop
  order?: string[]  // rows to place first, in this order
}

ctx.register({
  id: 'prefs',
  area: SIDEBAR_NAV_PREFS_AREA,
  data: { hide: ['cron'], order: ['capabilities', 'new-session'] } satisfies SidebarNavPrefsContribution
})

// sidebar-manager: replaces `[data-sbm-off] { display:none }` + re-parenting <li>s
let dispose = () => {}
const apply = (prefs: SidebarNavPrefsContribution) => {
  dispose()
  dispose = ctx.register({ id: 'prefs', area: SIDEBAR_NAV_PREFS_AREA, data: prefs })
}
apply(ctx.storage.get('navPrefs', {}))
// in the editor's onChange:
ctx.storage.set('navPrefs', next); apply(next)

host.state.activeSessionId  // ReadableAtom<string | null>
host.state.awaitingResponse // ReadableAtom<boolean>  true until the first assistant payload
host.state.busy             // ReadableAtom<boolean>  focused chat is working after a send
host.state.busyBySession    // ReadableAtom<Record<string, boolean>>  runtime id → mid-turn
host.state.focusedSessionId // ReadableAtom<string | null>  (runtime id of the FOCUSED session — tile-aware; prefer for session.* RPC)
host.state.focusedSessionProfile // ReadableAtom<string>  (owner profile of the focused chat — prefer over `profile` for per-bot/profile readouts)
host.state.focusedStoredSessionId // ReadableAtom<string | null>  (durable id — navigation / session-list matching)
host.state.focusedUsage     // ReadableAtom<UsageStats | null>  (live streamed usage of the focused session, no RPC needed)
host.state.cwd              // ReadableAtom<string>
host.state.gateway          // ReadableAtom<string>  socket state ('idle' | 'connecting' | 'open' | …)
host.state.model            // ReadableAtom<string>
host.state.profile          // ReadableAtom<string>
host.state.viewport         // ReadableAtom<{ width, height, narrow }>

host.notify({ kind, message, title?, detail?, action? })  // toast; returns id
host.notifyError(error, fallbackMessage)                   // toast an error
ctx.os.notify({ title, body?, silent?, icon?, activate?, onActivate?, actions? })
                                           // native OS notification (attributed to your plugin)
ctx.os.openExternal(url)                   // OS default handler (browser, mail, spotify:) → Promise<boolean>
ctx.os.revealPath(path)                    // reveal in Finder / Explorer → Promise<boolean>
ctx.os.writeClipboard(text)                // system clipboard → Promise<boolean>
host.navigate('/route')                    // hash-route navigation
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'
host.newChat(profile?)                     // fresh chat draft, optionally in another profile
host.openWorkspace(id, { render, title?, minWidth?, onClose? })
                                           // dock a plugin-rendered tab into the MAIN
                                           //   workspace zone and reveal it; returns a disposer
host.paneVisibility(paneId)                // ReadableAtom<boolean> — is a contributed pane
                                           //   actually on screen (its zone's active tab)?
host.onEvent(type, fn)                     // gateway event stream ('*' = all); returns disposer.
                                           //   Calls made during register() are retired with the
                                           //   plugin; elsewhere prefer ctx.onEvent (always tracked)
host.logs(...)                             // tail an app log file
host.status()                              // one-shot system status snapshot
host.restartGateway()                      // restart the backend gateway
host.profileRoutes()                       // [{ profile, targetProfile, connectionId, mode }]
host.requestProfile<T>(route, method, params?, timeoutMs?, { spawnPriority? })   // registry-routed RPC; no foreground swap
host.requestProfile<T>(profile, method, params?) // legacy v1/local overload
host.request<T>(method, params?)           // active-gateway JSON-RPC — the real power
host.sessions.pin(storedSessionId, pinned?, index?)  // pin/unpin (default pinned=true); index = slot in Pinned;
                                           //   same store the row's ⇧-click / drop writes
host.sessions.reorder(ids)                 // replace the manual Recents order (what a drag persists); [] resets
host.sessions.reorderPinned(ids)           // permute the Pinned section (the pinned drag path)
host.sessions.setColor(storedSessionId, color | null)  // per-session colour override; null clears
host.skills.list(profile?)                 // every skill for the scope (Capabilities endpoints)
host.skills.setEnabled(name, on, profile?)  // enable/disable a skill — the Capabilities toggle
host.toolsets.list(profile?)               // toolsets + enabled state
host.toolsets.setEnabled(name, on, profile?)// enable/disable a toolset
host.profiles.list(scope?: ProfileScope)   // the profile list the profile rail reads
host.pluginDecisions                       // READ-ONLY atom: this window's plugin on/off decisions (frozen copies)
host.i18n.registerAppLocale(id, { endonym?, rtl?, translations? })  // add a whole UI language (language pack); returns disposer
host.i18n.languageOptions()                // [{ id, endonym, rtl, source }] — what the language switcher lists

const busy = useValue(host.state.busy)

ctx.os.notify({
  title: 'New match found',
  body: 'Someone matched your signal',
  icon: '/abs/path/to/icon.png', // Electron Notification icon
  // Body click → focus Mibyan + navigate. Same vocabulary as OS deep links:
  activate: 'mibyan://index-network/intent/1',
  // or: activate: '/index-network/intent/1'
  // or: activate: { path: '/index-network/intent/1' }
  onActivate: () => focusLocalState('1'), // optional renderer callback
  actions: [
    { id: 'open', label: 'Open', activate: 'mibyan://index-network/intent/1' },
    { id: 'dismiss', label: 'Dismiss', onAction: () => dismiss('1') },
  ],
})

type DesktopSettingValues = {
  'backdrop.v1': boolean
  'composerPopout.gesturesEnabled': boolean
  'intro-splash.v1': boolean
  'reasoning.collapsedByDefault': boolean
  sessionListDensity: 'compact' | 'comfortable' | 'detailed'
  tabStripDefault: 'auto' | 'always' | 'never'
}
host.settings.get<K extends DesktopSettingKey>(key: K): DesktopSettingValues[K]
host.settings.set<K extends DesktopSettingKey>(key: K, value: DesktopSettingValues[K]): void
host.settings.subscribe<K extends DesktopSettingKey>(key: K, fn: (value: DesktopSettingValues[K]) => void): () => void

register(ctx) {
  host.settings.set('sessionListDensity', 'detailed')

  // subscribe emits the current value now, then after every native or plugin write.
  const dispose = host.settings.subscribe('backdrop.v1', enabled => { /* … */ })
  // Teardown rule: `host` is a module singleton and cannot tell which plugin
  // subscribed, so YOU retire the listener — otherwise it outlives a disable/reload.
  ctx.onDispose(dispose)
}

// before
localStorage.setItem('mibyan.desktop.backdrop.v1', String(on))
window.dispatchEvent(new StorageEvent('storage', { key: 'mibyan.desktop.backdrop.v1', newValue: String(on) }))
// after — the store notifies its own subscribers; no synthetic StorageEvent
host.settings.set('backdrop.v1', on)
host.settings.set('sessionListDensity', id)          // was mibyan.desktop.sessionListDensity
host.settings.set('tabStripDefault', id)             // was mibyan.desktop.tabStripDefault
host.settings.set('reasoning.collapsedByDefault', on) // was mibyan.desktop.reasoning.collapsedByDefault
host.settings.set('composerPopout.gesturesEnabled', on)
host.settings.set('intro-splash.v1', mode !== 'off') // replaces clicking #setting-field-appearance.intro-splash

type ProfileScope = undefined | null | string | { connectionId?: null | string; profile?: null | string }

host.skills.list(profile?: ProfileScope): Promise<SkillInfo[]>
host.skills.setEnabled(name: string, enabled: boolean, profile?: ProfileScope): Promise<{ ok: boolean; name: string; enabled: boolean }>
host.toolsets.list(profile?: ProfileScope): Promise<ToolsetInfo[]>
host.toolsets.setEnabled(name: string, enabled: boolean, profile?: ProfileScope): Promise<{ ok: boolean; name: string; enabled: boolean }>
host.profiles.list(scope?: ProfileScope): Promise<{ profiles: ProfileInfo[] }>
host.pluginDecisions: ReadableAtom<Record<string, boolean>>   // get() / subscribe() / listen() — no set()

// before                                                  // after
desktopApi({ path: '/api/skills' })                        host.skills.list()
desktopApi({ path: '/api/skills/toggle', method: 'PUT',    host.skills.setEnabled(name, enabled)
  body: { name, enabled } })
desktopApi({ path: '/api/tools/toolsets' })                host.toolsets.list()
desktopApi({ path: `/api/tools/toolsets/${name}`,          host.toolsets.setEnabled(name, enabled)
  method: 'PUT', body: { enabled } })
desktopApi({ path: '/api/profiles' })                      host.profiles.list()
JSON.parse(localStorage.getItem(                           host.pluginDecisions.get()
  'mibyan.desktop.pluginDecisions.v2'))                    ctx.onDispose(host.pluginDecisions.subscribe(fn))
localStorage.setItem('mibyan.desktop.pluginDecisions.v2')  // declined — host.navigate('/capabilities?tab=plugins')
row.querySelector('[data-slot="switch"]').click()          // same: the app's Plugins tab owns the toggle

export default {
  id: 'mibyan-lang-pl',
  register(ctx) {
    // Attributed to this plugin and dropped on unload/disable.
    ctx.i18n.registerAppLocale('pl', {
      endonym: 'Polski',
      englishName: 'Polish',        // search-only
      rtl: false,
      translations: {
        // Nested like en.ts…
        common: { save: 'Zapisz', cancel: 'Anuluj' },
        // …or flat dotted keys (what a .desktop.yaml pack flattens to).
        'catalog.results': '{0} wyników'
      }
    })
  }
}

host.i18n.registerAppLocale(id, { endonym?, englishName?, rtl?, translations? }): () => void
host.i18n.languageOptions(): LanguageOption[]   // bundled ∪ registered ∪ backend i18n.languages

import { useQuery, useMutation, useQueryClient, atom, computed, useValue } from '@mibyan/plugin-sdk'

function MyPanel() {
  const { data, isLoading } = useQuery({
    queryKey: ['my-plugin', 'items'],
    queryFn: () => host.request('my.list', {})
  })
  // …
}

import { queryClient } from '@mibyan/plugin-sdk'

ctx.socket('/events', () => {
  queryClient.invalidateQueries({ queryKey: ['my-plugin', 'items'] })
})

~/.mibyan/plugins/<id>/           # ONE installable folder
├── plugin.yaml                   # the agent half: tools, hooks, commands
├── skills/…
├── dashboard/
│   ├── manifest.json             # { "name": "<id>", "api": "plugin_api.py" }
│   └── plugin_api.py             # backend routes → /api/plugins/<id>/
└── desktop/
    └── plugin.js                 # the desktop half: panes, commands, ctx.rest

<a href="mibyan://plugin/install?repo=owner/repo&enable=1">Install in Mibyan</a>

~/.mibyan/plugins/<id>/
└── dashboard/
    ├── manifest.json      # { "name": "<id>", "api": "plugin_api.py" }
    └── plugin_api.py      # exports `router = APIRouter()`

# plugin_api.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/board")
async def board():
    return {"items": ["one", "two", "three"]}

@router.post("/action")
async def action(body: dict):
    return {"ok": True, "received": body}

from mibyan_cli.plugin_events import broadcast_plugin_event

broadcast_plugin_event("rss-reader", "feed.updated", {"count": 3})
# → event "plugin.rss-reader.feed.updated" reaches every connected desktop client

// register(ctx): the subscription is retired with the plugin
host.onEvent('plugin.rss-reader.feed.updated', ({ payload }) => refreshFeeds(payload))

register(ctx) {
  // REST — namespace-relative path.
  const load = () => ctx.rest('/board')                 // GET /api/plugins/<id>/board
  const act  = () => ctx.rest('/action', { method: 'POST', body: { go: true } })

  // Live twin — a WebSocket to your own namespace.
  const stop = ctx.socket('/events', frame => {
    queryClient.invalidateQueries({ queryKey: [ctx.source, 'board'] })
  })
}

ctx.storage.set('lastTab', 'board')
const tab = ctx.storage.get('lastTab', 'summary')
ctx.storage.remove('lastTab')