@brimveyn/aimux-plugin 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux-plugin",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Plugin authoring API for aimux — context, effects, events and RPC for in-process plugins.",
   "keywords": [
     "aimux",
@@ -28,7 +28,8 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -37,6 +38,16 @@
     "@types/react": "^19.2.14"
   },
   "peerDependencies": {
+    "@opentui/core": ">=0.1.90",
+    "@opentui/react": ">=0.1.90",
     "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/react": {
+      "optional": true
+    }
   }
 }

package/src/daemon-api.ts

@@ -22,6 +22,16 @@ export interface PluginTabView {
   command: string
   workspaceId?: string
   workerName?: string
+  /**
+   * True while the tab still carries the title it was born with: created
+   * without one, on an assistant that supports being named, and renamed by
+   * nobody since — not the user, not aimux, not a plugin.
+   *
+   * A plugin that names tabs reads this before naming one, which is how it
+   * avoids naming the same tab twice or writing over a title the user chose.
+   * `rename` clears it, whoever calls it.
+   */
+  unnamed: boolean
 }
 
 export interface PluginSpawnTabInput {
@@ -99,8 +109,30 @@ export interface PluginProjectsApi {
   get: (projectId: string) => PluginProjectView | undefined
 }
 
+export interface PluginCreateWorkspaceInput {
+  projectId: string
+  name: string
+  /** Defaults to `aimux/<name>`. */
+  branch?: string
+  /** Base ref for the branch. Defaults to `HEAD`. */
+  base?: string
+}
+
 export interface PluginWorkspacesApi {
   list: (projectId: string) => PluginWorkspaceView[]
+  /**
+   * Creates a git worktree and its catalog record — what `aimux workspace
+   * create` does, from inside the daemon. Resolves with the record; rejects
+   * with the same messages the CLI prints, a base ref that does not exist
+   * included.
+   */
+  create: (input: PluginCreateWorkspaceInput) => Promise<PluginWorkspaceView>
+  /**
+   * Removes a worktree and its record. Refuses the primary workspace, and
+   * one with live tabs unless `force` says otherwise — a tab running in a
+   * directory that vanishes is a worse outcome than a rejected call.
+   */
+  remove: (projectId: string, workspaceId: string, options?: { force?: boolean }) => Promise<void>
 }
 
 /**
@@ -118,6 +150,38 @@ export interface PluginMetricsApi {
   counters: (days?: number) => PluginCounterDay[]
 }
 
+/** What aimux knows about the conversation behind a tab. */
+export interface PluginSessionInfo {
+  tabId: string
+  assistant: string
+  /** The vendor's conversation id, when the tab was spawned with one. */
+  sessionId: string | null
+  /** The transcript on disk, when the vendor writes one and it exists yet. */
+  transcriptPath: string | null
+  /** The `--model` the tab was spawned with, when one was given. */
+  model: string | null
+}
+
+/**
+ * Token usage of one conversation, read from its transcript. Cumulative
+ * across the whole session, which is what a token dashboard, a handoff
+ * threshold, or a "you are near the limit" nudge wants.
+ */
+export interface PluginSessionUsage {
+  tabId: string
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  total: number
+  /** Billed assistant messages seen. */
+  turns: number
+  /** Total tokens per model id. */
+  models: Record<string, number>
+  /** ISO time of the last billed message, or null with no usage yet. */
+  lastAt: string | null
+}
+
 export interface PluginAssistantsApi {
   /**
    * Registers a complete assistant: spawn command, status classifier, question
@@ -125,6 +189,19 @@ export interface PluginAssistantsApi {
    * `src/pty/assistant-registry.ts` for the shape.
    */
   register: (definition: unknown) => Disposer
+  /** The conversation behind a tab, or undefined for an unknown tab. */
+  session: (tabId: string) => PluginSessionInfo | undefined
+  /**
+   * Reads the transcript. Zero everywhere for a tab whose assistant writes
+   * none, or has not written one yet; undefined for an unknown tab.
+   */
+  usage: (tabId: string) => Promise<PluginSessionUsage | undefined>
+  /**
+   * Closes the tab and spawns a fresh one resuming the same conversation —
+   * the move after a rate limit, a crashed CLI, or a handoff. Resolves with
+   * the new tab id. Rejects when the tab has no session to resume.
+   */
+  resume: (tabId: string) => Promise<string>
 }
 
 export interface PluginHooksApi {

package/src/index.ts

@@ -8,10 +8,13 @@ export type {
   PluginAssistantsApi,
   PluginCliApi,
   PluginCounterDay,
+  PluginCreateWorkspaceInput,
   PluginHooksApi,
   PluginMetricsApi,
   PluginProjectsApi,
   PluginProjectView,
+  PluginSessionInfo,
+  PluginSessionUsage,
   PluginSpawnTabInput,
   PluginTabsApi,
   PluginTabView,
@@ -24,6 +27,7 @@ export { type EventBusOptions, PluginEventBus } from './event-bus'
 export {
   PLUGIN_API_VERSION,
   type PluginBarContribution,
+  type PluginCommandPaneSpec,
   type PluginCommandSpec,
   type PluginConfigField,
   type PluginConfigFieldType,
@@ -31,6 +35,7 @@ export {
   type PluginHost,
   type PluginKeymapContribution,
   type PluginManifest,
+  type PluginServiceSpec,
 } from './manifest'
 export { createTestUiSurface, type TestUiRegistrations, type TestUiSurface } from './test-ui'
 export {
@@ -41,15 +46,32 @@ export {
   type TestRpcCall,
 } from './test-context'
 export type {
+  PluginActionMeta,
   PluginActionsApi,
   PluginBarWidget,
+  PluginCommandEntry,
+  PluginCommandPane,
+  PluginCommandsApi,
+  PluginCommitMessage,
+  PluginCommitMessageRequest,
   PluginComponent,
+  PluginGitApi,
+  PluginGitCommitInput,
+  PluginGitFile,
+  PluginGitStatus,
   PluginKit,
+  PluginLayoutApi,
+  PluginLayoutNode,
   PluginModal,
   PluginModalsApi,
   PluginNode,
+  PluginNotification,
+  PluginNotificationEvent,
+  PluginNotificationsApi,
   PluginPane,
+  PluginPaneDirection,
   PluginPanesApi,
+  PluginScreen,
   PluginSettingsApi,
   PluginSettingValue,
   PluginStateApi,
@@ -68,6 +90,7 @@ export type {
   PluginView,
   PluginViewsApi,
   PluginWidgetsApi,
+  PluginWidgetSize,
 } from './ui'
 export type {
   DaemonPluginContext,

package/src/manifest.ts

@@ -71,6 +71,10 @@ export interface PluginBarContribution {
  * every plugin, here as everywhere else.
  */
 export interface PluginKeymapContribution {
+  /** Stable id used by user overrides. Defaults to `action`. */
+  id?: string
+  /** Human-readable label shown in settings and key help. */
+  description?: string
   /** Mode id, e.g. `navigation`, or the plugin's own pane mode. */
   mode: string
   /** Key notation, `<leader>` included. */
@@ -84,6 +88,34 @@ export interface PluginContributions {
   keymaps?: PluginKeymapContribution[]
 }
 
+/**
+ * A pane that runs a program, declared rather than registered — the manifest
+ * twin of `ctx.ui.panes.registerCommand`. `cwd` reads as it does there.
+ */
+export interface PluginCommandPaneSpec {
+  id: string
+  title?: string
+  /** argv, not a shell string. */
+  command: string[]
+  cwd?: string
+}
+
+/**
+ * A long-running process the daemon supervises: started when the plugin
+ * loads, stopped when it unloads, restarted according to `restart`. A relay,
+ * a watcher, a bridge — anything that is not a command that finishes.
+ *
+ * Runs with the same `AIMUX_*` environment as `commands[]`, so it can call
+ * back through the CLI in any language.
+ */
+export interface PluginServiceSpec {
+  id: string
+  /** argv, not a shell string. */
+  command: string[]
+  /** Default `on-failure`: a clean exit stays down, a crash comes back. */
+  restart?: 'never' | 'on-failure' | 'always'
+}
+
 export interface PluginManifest {
   /** Reverse-DNS-ish, `<vendor>.<name>`; the namespace for every registration. */
   id: string
@@ -100,6 +132,10 @@ export interface PluginManifest {
   build?: string[][]
   config?: Record<string, PluginConfigField>
   commands?: PluginCommandSpec[]
+  /** Panes that host a program. Applied when the UI half loads — or, with no UI entry, at once. */
+  panes?: PluginCommandPaneSpec[]
+  /** Processes the daemon keeps alive for the plugin. */
+  services?: PluginServiceSpec[]
   /**
    * What the plugin asks the interface for: a place for its widget, a key for
    * its action. Applied by the host when the UI half loads, withdrawn when it

package/src/test-context.ts

@@ -211,10 +211,12 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       ui: unknown
       actions: unknown
       store: unknown
+      commands: unknown
     }
     extended.ui = surface.ui
     extended.actions = surface.actions
     extended.store = surface.store
+    extended.commands = surface.commands
   }
 
   options.extend?.(ctx)

package/src/test-ui.ts

@@ -2,6 +2,11 @@ import type { EffectStack } from './effects'
 import type { Disposer } from './types'
 import type {
   PluginActionsApi,
+  PluginCommandsApi,
+  PluginCommitMessage,
+  PluginCommitMessageRequest,
+  PluginGitStatus,
+  PluginNotificationEvent,
   PluginSettingValue,
   PluginStoreApi,
   PluginThemeSnapshot,
@@ -32,10 +37,16 @@ export interface TestUiRegistrations {
   views: string[]
   modals: string[]
   panes: string[]
+  /** Command panes — programs the plugin asked to host. */
+  commandPanes: string[]
   statusBar: string[]
   statsPages: string[]
   themes: string[]
   settingsSections: number
+  /** Whether the plugin claimed the commit-message slot. */
+  commitMessageProvider: boolean
+  /** Whether the plugin claimed the notification slot. */
+  notificationSink: boolean
   actions: string[]
   effects: string[]
 }
@@ -44,17 +55,41 @@ export interface TestUiSurface {
   ui: PluginUiApi
   actions: PluginActionsApi
   store: PluginStoreApi
+  commands: PluginCommandsApi
   registrations: TestUiRegistrations
   /** Everything `ctx.ui.toast` was asked to show, newest last. */
   toasts: { level: 'info' | 'success' | 'error'; message: string }[]
+  /** Everything `ctx.ui.notifications.notify` raised, newest last. */
+  notifications: { title: string; message?: string; level?: string }[]
   /** Panes and views the plugin asked to open or close, in order. */
   opened: string[]
+  /** Layout verbs the plugin called, in order — `split:vertical`, `focus:left`, … */
+  layoutCalls: string[]
+  /** Git writes the plugin asked for, in order — `stage:a.ts`, `commit:title`, … */
+  gitWrites: string[]
   /** Drives `ctx.ui.state`: set it, and subscribers hear about it. */
   setState: (next: Partial<PluginUiState>) => void
   /** Drives `ctx.ui.settings.watch` and what `get` answers. */
   setSetting: (id: string, value: PluginSettingValue) => void
   /** Drives `ctx.ui.themes.onChange` and what `current()` answers. */
   setTheme: (snapshot: PluginThemeSnapshot) => void
+  /** Drives `ctx.ui.git.status`. */
+  setGitStatus: (status: PluginGitStatus) => void
+  /**
+   * Asks the provider the plugin registered, as the commit flow would. Throws
+   * when it registered none, because a test that silently asserts nothing is
+   * the failure this whole harness exists to avoid.
+   */
+  askForCommitMessage: (
+    request?: Partial<PluginCommitMessageRequest>
+  ) => Promise<PluginCommitMessage | null>
+  /**
+   * Delivers an event to the sink the plugin provided, as aimux would on an
+   * agent finishing a turn. Throws when it provided none.
+   */
+  deliverNotification: (event: PluginNotificationEvent) => Promise<void>
+  /** Drives `ctx.ui.git.diff`. */
+  setGitDiff: (path: string, diff: string) => void
 }
 
 const EMPTY_STATE: PluginUiState = {
@@ -66,14 +101,29 @@ const EMPTY_STATE: PluginUiState = {
 
 const DEFAULT_THEME: PluginThemeSnapshot = { colors: {}, mode: 'dark' }
 
+const EMPTY_GIT: PluginGitStatus = { ahead: 0, behind: 0, branch: null, files: [] }
+
+const EMPTY_REQUEST: PluginCommitMessageRequest = {
+  assistant: 'claude',
+  branch: 'main',
+  diff: '',
+  files: [],
+  projectId: 'p1',
+  recentCommits: '',
+  repoRoot: '/tmp/repo',
+}
+
 /** A component that renders nothing: a test asserts on registrations, not pixels. */
 const nothing = (): null => null
 
 export function createTestUiSurface(effects: EffectStack): TestUiSurface {
   const registrations: TestUiRegistrations = {
     actions: [],
+    commandPanes: [],
+    commitMessageProvider: false,
     effects: [],
     modals: [],
+    notificationSink: false,
     panes: [],
     settingsSections: 0,
     statsPages: [],
@@ -83,7 +133,12 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
     widgets: [],
   }
   const toasts: TestUiSurface['toasts'] = []
+  const notifications: TestUiSurface['notifications'] = []
   const opened: string[] = []
+  const layoutCalls: string[] = []
+  const gitWrites: string[] = []
+  const diffs = new Map<string, string>()
+  let notificationSink: ((event: PluginNotificationEvent) => void | Promise<void>) | null = null
 
   let state: PluginUiState = EMPTY_STATE
   const stateListeners = new Set<(next: PluginUiState) => void>()
@@ -92,6 +147,13 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
   let theme: PluginThemeSnapshot = DEFAULT_THEME
   const themeListeners = new Set<(snapshot: PluginThemeSnapshot) => void>()
   let slice: unknown
+  let git: PluginGitStatus = EMPTY_GIT
+  let commitProvider:
+    | ((
+        request: PluginCommitMessageRequest,
+        signal: AbortSignal
+      ) => Promise<PluginCommitMessage | null> | PluginCommitMessage | null)
+    | null = null
 
   /** Records a registration and hands back a disposer that unrecords it. */
   function record(into: string[], id: string): Disposer {
@@ -114,6 +176,32 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
   }
 
   const ui: PluginUiApi = {
+    git: {
+      commit: async (input) => {
+        gitWrites.push(`commit:${input.title}`)
+      },
+      diff: async (path) => diffs.get(path) ?? '',
+      discard: async (paths) => {
+        gitWrites.push(`discard:${paths.join(',')}`)
+      },
+      provideCommitMessage: (provider) => {
+        commitProvider = provider
+        registrations.commitMessageProvider = true
+        const dispose = (): void => {
+          if (commitProvider === provider) commitProvider = null
+          registrations.commitMessageProvider = false
+        }
+        effects.add(dispose)
+        return dispose
+      },
+      stage: async (paths) => {
+        gitWrites.push(`stage:${paths.join(',')}`)
+      },
+      status: () => git,
+      unstage: async (paths) => {
+        gitWrites.push(`unstage:${paths.join(',')}`)
+      },
+    },
     kit: {
       KeyHint: nothing,
       List: nothing,
@@ -121,15 +209,42 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
       Row: nothing,
       useTheme: () => theme.colors,
     },
+    layout: {
+      close: (tabId) => layoutCalls.push(`close:${tabId ?? 'active'}`),
+      focus: (direction) => layoutCalls.push(`focus:${direction}`),
+      panes: () => (state.activeTabId === null ? [] : [state.activeTabId]),
+      resize: (delta, axis) => layoutCalls.push(`resize:${axis}:${delta}`),
+      split: (direction) => layoutCalls.push(`split:${direction}`),
+      swap: (direction) => layoutCalls.push(`swap:${direction}`),
+      tree: () => null,
+    },
     modals: {
       close: () => opened.push('modal:close'),
       open: (id) => opened.push(`modal:${id}`),
       register: (modal) => record(registrations.modals, modal.id),
     },
+    navigate: (screen) => opened.push(`screen:${screen}`),
+    notifications: {
+      notify: (notification) => {
+        notifications.push(notification)
+      },
+      provide: (sink) => {
+        notificationSink = sink
+        registrations.notificationSink = true
+        const dispose = (): void => {
+          if (notificationSink === sink) notificationSink = null
+          registrations.notificationSink = false
+        }
+        effects.add(dispose)
+        return dispose
+      },
+    },
     panes: {
       close: (id) => opened.push(`pane:close:${id}`),
       open: (id) => opened.push(`pane:${id}`),
+      openCommandPanes: () => [],
       register: (pane) => record(registrations.panes, pane.id),
+      registerCommand: (pane) => record(registrations.commandPanes, pane.id),
     },
     settings: {
       get: (id) => settings.get(id),
@@ -187,6 +302,17 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
     register: (verb) => record(registrations.actions, verb),
   }
 
+  const commands: PluginCommandsApi = {
+    list: () =>
+      registrations.actions.map((verb) => ({
+        id: verb,
+        kind: 'action' as const,
+        pluginId: 'test',
+        title: verb,
+      })),
+    run: () => false,
+  }
+
   const store: PluginStoreApi = {
     dispatch: () => {
       /* a slice reducer is the plugin's; a bare context has none to run */
@@ -207,8 +333,26 @@ export function createTestUiSurface(effects: EffectStack): TestUiSurface {
 
   return {
     actions,
+    askForCommitMessage: async (request) => {
+      if (commitProvider === null) throw new Error('the plugin registered no commit provider')
+      return commitProvider({ ...EMPTY_REQUEST, ...request }, new AbortController().signal)
+    },
+    commands,
+    deliverNotification: async (event) => {
+      if (notificationSink === null) throw new Error('the plugin provided no notification sink')
+      await notificationSink(event)
+    },
+    gitWrites,
+    layoutCalls,
+    notifications,
     opened,
     registrations,
+    setGitDiff: (path, diff) => {
+      diffs.set(path, diff)
+    },
+    setGitStatus: (status) => {
+      git = status
+    },
     setSetting: (id, value) => {
       settings.set(id, value)
       for (const listener of settingListeners.get(id) ?? []) listener(value)

package/src/testing.ts

@@ -0,0 +1,99 @@
+import { createTestRenderer } from '@opentui/core/testing'
+import { createRoot } from '@opentui/react'
+
+import type { PluginNode } from './ui'
+
+/**
+ * Does it draw?
+ *
+ * `createTestContext` answers what a plugin *registers* — the widget exists,
+ * the action is bound, an unload leaves nothing behind. It says nothing about
+ * what any of it looks like, and a widget whose renderer throws on an empty
+ * data set registers exactly as cleanly as one that works.
+ *
+ * aimux has a test renderer; a plugin author outside this repo did not. This is
+ * that renderer, with the two lines of setup already done, in a separate entry
+ * point so the extra dependencies stay out of a plugin's runtime:
+ *
+ * ```ts
+ * import { renderPluginNode } from '@brimveyn/aimux-plugin/testing'
+ *
+ * const { frame } = await renderPluginNode(<MyWidget cols={30} rows={8} />)
+ * expect(frame).toContain('CPU')
+ * ```
+ *
+ * `@opentui/core` and `@opentui/react` are peers rather than dependencies: the
+ * host already ships them, and a second copy in a plugin's tree is the module
+ * duplication the plugin loader spends real effort avoiding at runtime.
+ */
+
+export interface RenderPluginOptions {
+  /** Terminal size to render into. Defaults to a bar-sized 40×12. */
+  cols?: number
+  rows?: number
+  /**
+   * How long to keep rendering while `until` is false. A widget that fetches on
+   * mount needs a few frames before it has anything to draw.
+   */
+  timeoutMs?: number
+  /** Stop as soon as this is true of the current frame. Default: first frame. */
+  until?: (frame: string) => boolean
+}
+
+export interface RenderedPlugin {
+  /** The drawn frame, as text. */
+  frame: string
+  /** Renders again and returns the new frame — for asserting on a change. */
+  next: () => Promise<string>
+  /** Tears the renderer down. Call it, or the process keeps a root mounted. */
+  dispose: () => void
+}
+
+const DEFAULT_COLS = 40
+const DEFAULT_ROWS = 12
+const DEFAULT_TIMEOUT_MS = 2_000
+/** One macrotask, which is what React needs to commit the tree. */
+const COMMIT_TICK_MS = 10
+
+export async function renderPluginNode(
+  node: PluginNode,
+  options: RenderPluginOptions = {}
+): Promise<RenderedPlugin> {
+  const cols = options.cols ?? DEFAULT_COLS
+  const rows = options.rows ?? DEFAULT_ROWS
+  const { captureCharFrame, renderer, renderOnce } = await createTestRenderer({
+    height: rows,
+    width: cols,
+  })
+  const root = createRoot(renderer)
+  root.render(node)
+
+  const draw = async (): Promise<string> => {
+    await renderOnce()
+    return captureCharFrame()
+  }
+
+  // React commits on a macrotask, not on the render tick: capturing straight
+  // after `root.render` gives a blank frame every time, which would make the
+  // simplest possible assertion fail for a reason that has nothing to do with
+  // the widget under test.
+  await draw()
+  await new Promise<void>((resolve) => setTimeout(resolve, COMMIT_TICK_MS))
+  let frame = await draw()
+  const until = options.until
+  if (until !== undefined) {
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+    while (!until(frame) && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 10))
+      frame = await draw()
+    }
+  }
+
+  return {
+    dispose: () => {
+      root.unmount()
+    },
+    frame,
+    next: draw,
+  }
+}

package/src/types.ts

@@ -8,7 +8,7 @@ import type {
   PluginWorkspacesApi,
 } from './daemon-api'
 import type { PluginHost, PluginManifest } from './manifest'
-import type { PluginActionsApi, PluginStoreApi, PluginUiApi } from './ui'
+import type { PluginActionsApi, PluginCommandsApi, PluginStoreApi, PluginUiApi } from './ui'
 
 /**
  * Everything a plugin registers hands back one of these. The kernel calls
@@ -122,6 +122,7 @@ export interface UiPluginContext<Slice = unknown> extends PluginContext {
   readonly ui: PluginUiApi
   readonly actions: PluginActionsApi
   readonly store: PluginStoreApi<Slice>
+  readonly commands: PluginCommandsApi
 }
 
 /**

package/src/ui.ts

@@ -36,11 +36,23 @@ export interface PluginToastApi {
   error: (message: string) => void
 }
 
+/** The room a bar widget has been given, in cells. */
+export interface PluginWidgetSize {
+  cols: number
+  rows: number
+}
+
 export interface PluginBarWidget {
   /** Unqualified; the host prefixes the plugin id. */
   id: string
   label: string
-  render: (contentWidth: number) => PluginNode
+  /**
+   * `size` is the second argument rather than a replacement for the first: the
+   * width already shipped as a number under `apiVersion: 1`, and swapping it
+   * would break every published plugin to save one parameter. `size.cols` is
+   * the same value.
+   */
+  render: (contentWidth: number, size: PluginWidgetSize) => PluginNode
 }
 
 export interface PluginView {
@@ -147,6 +159,32 @@ export interface PluginPane {
   render: () => PluginNode
 }
 
+/**
+ * A pane that hosts a *program* rather than React: lazygit, yazi, a Rust TUI
+ * the plugin ships. Same story the daemon's `commands[]` tells — a plugin in
+ * any language — applied to the interface.
+ *
+ * Opening one spawns the argv in a terminal pane aimux owns on the plugin's
+ * behalf: it is a real PTY tab, so it takes the keyboard like any terminal
+ * does. The pane outlives a reload of the plugin (a re-registration under the
+ * same id adopts it) and dies with the plugin (unlink, uninstall, disable). A
+ * program that exits leaves a pane that says so, and `Ctrl+r` restarts it.
+ */
+export interface PluginCommandPane {
+  /** Unqualified; the host prefixes the plugin id. */
+  id: string
+  /** Drawn in the pane's border and in the tab strip. */
+  title: string
+  /** argv, not a shell string — no quoting rules to get wrong. */
+  command: string[]
+  /**
+   * Where to run it. `workspace` (the default) is the active workspace's
+   * directory, `project` the project's, `plugin` the plugin's own root; any
+   * other value is taken as an absolute path.
+   */
+  cwd?: 'workspace' | 'project' | 'plugin' | (string & {})
+}
+
 export interface PluginPanesApi {
   /**
    * Declares a pane: a leaf in the layout tree that draws something other than
@@ -157,6 +195,12 @@ export interface PluginPanesApi {
    * Registering does not put it on screen; `open` does.
    */
   register: (pane: PluginPane) => Disposer
+  /**
+   * Declares a pane that runs a program. The manifest's `panes[]` block is the
+   * same declaration without a line of TypeScript. `open` and `close` take the
+   * same unqualified id either way.
+   */
+  registerCommand: (pane: PluginCommandPane) => Disposer
   /**
    * Splits the pane the user is in and puts this one beside it. Takes the
    * unqualified id. Opening one that is already open does nothing: the id is
@@ -169,8 +213,112 @@ export interface PluginPanesApi {
    * in its own mode — `plugin.pane.<pluginId>.<id>`.
    */
   open: (id: string, direction?: 'horizontal' | 'vertical') => void
-  /** Takes it off screen. The layout collapses as it would for a closed tab. */
+  /**
+   * Takes it off screen. The layout collapses as it would for a closed tab.
+   * For a command pane this also kills the program.
+   */
   close: (id: string) => void
+  /**
+   * Which command panes are on screen right now, by unqualified id. A React
+   * pane is either registered or not; a command pane also has a process, and
+   * a plugin that wants to toggle one needs to know.
+   */
+  openCommandPanes: () => string[]
+}
+
+/** The layout of one group, as a plugin reads it. Same shape aimux persists. */
+export type PluginLayoutNode =
+  | { type: 'leaf'; id: string; kind: 'tab' | 'plugin' }
+  | {
+      type: 'split'
+      direction: 'horizontal' | 'vertical'
+      ratio: number
+      first: PluginLayoutNode
+      second: PluginLayoutNode
+    }
+
+export type PluginPaneDirection = 'left' | 'right' | 'up' | 'down'
+
+/**
+ * The layout as an API rather than as keys. Every verb here is one the
+ * keyboard already has, dispatched through the same reducer, so a plugin
+ * cannot reach a layout the user could not have made by hand.
+ *
+ * Everything acts on the pane holding the keyboard unless a `tabId` says
+ * otherwise; nothing here throws for a pane that cannot move, because a
+ * key press does not either.
+ */
+export interface PluginLayoutApi {
+  /** Splits the active pane and puts a new terminal beside it, same assistant. */
+  split: (direction: 'horizontal' | 'vertical') => void
+  /** Moves the keyboard to the neighbouring pane. */
+  focus: (direction: PluginPaneDirection) => void
+  /** Exchanges the active pane with its neighbour in that direction. */
+  swap: (direction: PluginPaneDirection) => void
+  /** Nudges the split the active pane sits in. `delta` is in steps, ±1 typically. */
+  resize: (delta: number, axis: 'horizontal' | 'vertical') => void
+  /** Closes a pane — the active one when no id is given. Kills its process. */
+  close: (tabId?: string) => void
+  /** The active group's tree, or null when the active tab is not split. */
+  tree: () => PluginLayoutNode | null
+  /** Every pane id in the active group, in draw order. One id when unsplit. */
+  panes: () => string[]
+}
+
+/** What a notification says. */
+export interface PluginNotification {
+  title: string
+  message?: string
+  level?: 'info' | 'success' | 'warning' | 'error'
+}
+
+/**
+ * A notification aimux is about to make — its own (`waiting-input`,
+ * `turn-complete`) or one a plugin raised (`custom`). What a sink receives.
+ */
+export interface PluginNotificationEvent extends PluginNotification {
+  kind: 'waiting-input' | 'turn-complete' | 'custom'
+  tabId?: string
+  workspaceId?: string
+  /** The plugin that raised it; absent on aimux's own. */
+  pluginId?: string
+}
+
+export interface PluginNotificationsApi {
+  /** Shows a toast — or hands it to the sink, when a plugin provides one. */
+  notify: (notification: PluginNotification) => void
+  /**
+   * Replaces aimux's own notifications: the sound on an agent asking a
+   * question or finishing a turn stops playing, and every event — aimux's
+   * and other plugins' — lands here instead. A ntfy or Telegram plugin
+   * *replaces* the native toast rather than doubling it.
+   *
+   * One plugin at a time, on the `provideCommitMessage` model: the second to
+   * ask is refused and told so in its log.
+   */
+  provide: (sink: (event: PluginNotificationEvent) => void | Promise<void>) => Disposer
+}
+
+/** One entry of what `ctx.commands.list()` enumerates. */
+export interface PluginCommandEntry {
+  /** `action` runs in the UI, `exec` is a manifest `commands[]` subprocess, `cli` an `aimux <group> <verb>`. */
+  kind: 'action' | 'exec' | 'cli'
+  /** The name to run it by: the qualified action, `<pluginId> <commandId>`, or `<group> <verb>`. */
+  id: string
+  pluginId: string
+  title: string
+  description?: string
+}
+
+/**
+ * Everything runnable that plugins have contributed, in one list. Without it
+ * a command palette written by a third party has nothing to show; with it,
+ * `run` fires an action the way its key would.
+ */
+export interface PluginCommandsApi {
+  list: () => PluginCommandEntry[]
+  /** Runs an `action` entry by its qualified id. Returns false when nothing answered. */
+  run: (id: string) => boolean
 }
 
 export interface PluginStatusBarSegment {
@@ -269,7 +417,108 @@ export interface PluginKit {
   KeyHint: PluginComponent<{ hints: readonly { keys: string; label: string }[] }>
 }
 
+/** One changed file, as the git panel sees it. */
+export interface PluginGitFile {
+  path: string
+  /** Porcelain-ish status: `modified`, `new`, `deleted`, `renamed`, … */
+  status: string
+  /** Which half of the panel it sits in — staged or not. */
+  section: string
+  added: number | null
+  removed: number | null
+}
+
+/**
+ * The working tree as the panel last saw it. A snapshot of aimux's poll, not a
+ * fresh `git status`: it is what the user is looking at, which is the point,
+ * and it is empty until a project with a path is open.
+ */
+export interface PluginGitStatus {
+  branch: string | null
+  ahead: number
+  behind: number
+  files: PluginGitFile[]
+}
+
+/** Everything aimux gathered before asking for a commit message. */
+export interface PluginCommitMessageRequest {
+  projectId: string
+  repoRoot: string
+  branch: string
+  /**
+   * The assistant in the tab the commit is being written for — `claude`,
+   * `codex`, … A provider that calls a model headlessly needs to know which
+   * one the user is already working with.
+   */
+  assistant: string
+  /** Staged diff when anything is staged, the working-tree diff otherwise. */
+  diff: string
+  /** `git log --oneline`, for house style rather than for content. */
+  recentCommits: string
+  files: PluginGitFile[]
+  /** The tail of what the agent in the tab was doing, when there is one. */
+  sessionTail?: string
+}
+
+export interface PluginCommitMessage {
+  title: string
+  body?: string
+}
+
+export interface PluginGitCommitInput {
+  title: string
+  body?: string
+}
+
+export interface PluginGitApi {
+  /** The panel's last refresh. */
+  status: () => PluginGitStatus
+  /**
+   * The diff of one file, unified. `staged` reads the index against HEAD; the
+   * default reads the working tree against the index, which is what the
+   * panel shows for an unstaged file. Empty for an untracked file — git has
+   * nothing to compare it with — so read the file itself in that case.
+   */
+  diff: (path: string, options?: { staged?: boolean }) => Promise<string>
+  /** `git add -- <paths>`. Rejects with git's own message on failure. */
+  stage: (paths: readonly string[]) => Promise<void>
+  /** `git restore --staged -- <paths>`. */
+  unstage: (paths: readonly string[]) => Promise<void>
+  /**
+   * Throws away working-tree changes: `git checkout --` for a tracked file,
+   * deletion for an untracked one. There is no undo, which is why it takes
+   * paths rather than "everything".
+   */
+  discard: (paths: readonly string[]) => Promise<void>
+  /** Commits what is staged. Rejects when nothing is, with git's own words. */
+  commit: (input: PluginGitCommitInput) => Promise<void>
+  /**
+   * Answers "what should this commit say", replacing the headless model call
+   * aimux would otherwise make. Return `null` to decline this one — aimux falls
+   * back to its own suggestion rather than leaving the user with nothing.
+   *
+   * One plugin at a time: the second to ask is refused, and told so in its log,
+   * because a message that depends on load order is worse than no message.
+   */
+  provideCommitMessage: (
+    provider: (
+      request: PluginCommitMessageRequest,
+      signal: AbortSignal
+    ) => Promise<PluginCommitMessage | null> | PluginCommitMessage | null
+  ) => Disposer
+}
+
+/** The screens a plugin may send the user to. */
+export type PluginScreen = 'git' | 'stats' | 'settings' | 'terminal'
+
 export interface PluginUiApi {
+  /**
+   * Opens one of aimux's own screens, or `terminal` to leave the one you are
+   * on. Deliberately four names and not an id space: exposing modal or view ids
+   * would make them API, and they are not.
+   */
+  navigate: (screen: PluginScreen) => void
+  git: PluginGitApi
   widgets: PluginWidgetsApi
   views: PluginViewsApi
   modals: PluginModalsApi
@@ -277,6 +526,8 @@ export interface PluginUiApi {
   themes: PluginThemesApi
   toast: PluginToastApi
   panes: PluginPanesApi
+  layout: PluginLayoutApi
+  notifications: PluginNotificationsApi
   state: PluginStateApi
   stats: PluginStatsApi
   statusBar: PluginStatusBarApi
@@ -287,13 +538,22 @@ export interface PluginUiApi {
  * Keyboard actions and their effects. Registered by unqualified verb; a user's
  * keymap binds the qualified name with `k.plugin('acme.thing.open')`.
  */
+/** What a palette shows for an action. Optional: an action without one lists under its verb. */
+export interface PluginActionMeta {
+  title?: string
+  description?: string
+}
+
 export interface PluginActionsApi {
   /**
    * The action a key produces. Receives the mode context and returns a
    * `KeyResult` — the same value a built-in binding produces — or null for
    * "not handled here".
+   *
+   * `meta` gives it a title. An action with one is something a palette can
+   * list and a user can find; without it the verb is all anyone sees.
    */
-  register: (verb: string, handler: (ctx: unknown) => unknown) => Disposer
+  register: (verb: string, handler: (ctx: unknown) => unknown, meta?: PluginActionMeta) => Disposer
   /**
    * The side of a binding that is allowed to do things: spawn a tab, write a
    * file, call out. Reached from an action's `KeyResult` as a `plugin-effect`.