@brimveyn/aimux-plugin 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrimVeyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @brimveyn/aimux-plugin
+
+Authoring API for [aimux](https://github.com/BrimVeyn/aimux) plugins.
+
+A plugin is a directory with a manifest and up to two entry files — one per
+host process. aimux loads them in-process, so a plugin renders real UI and
+reacts to real events; and it unloads them by running every disposer they
+registered, so editing one reloads it in place.
+
+```
+my-plugin/
+  aimux-plugin.json      manifest — read without executing any code
+  ui.ts                  UI half     (optional)
+  daemon.ts              daemon half (optional)
+  package.json
+```
+
+```jsonc
+// aimux-plugin.json
+{
+  "id": "acme.telegram-notify",
+  "name": "Telegram notify",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "minAimuxVersion": "1.24.0",
+  "entries": { "daemon": "./daemon.ts" },
+  "config": {
+    "botToken": { "type": "string", "required": true, "secret": true },
+  },
+}
+```
+
+```ts
+// daemon.ts
+import { type DaemonPluginContext, definePlugin } from '@brimveyn/aimux-plugin'
+
+export default definePlugin<DaemonPluginContext>({
+  apply(ctx) {
+    ctx.on('tab:turnComplete', ({ tabId }) => {
+      ctx.log.info('turn complete', { tabId })
+    })
+
+    ctx.effect(() => {
+      const timer = setInterval(poll, 60_000)
+      return () => clearInterval(timer)
+    })
+  },
+})
+```
+
+## The one rule
+
+**Everything a plugin registers must be reversible.** Register through
+`ctx.on`, `ctx.effect`, or an API that returns a disposer, and unloading is
+automatic. Reach around the context — a global, a bare `setInterval`, a
+listener on someone else's emitter — and it survives the reload as a leak.
+
+## Context
+
+| Member                                            | What it does                                                     |
+| ------------------------------------------------- | ---------------------------------------------------------------- |
+| `ctx.id`, `ctx.manifest`, `ctx.host`              | identity, and which process this half runs in                    |
+| `ctx.log`                                         | writes to `<state>/plugin.log`, readable via `aimux plugin log`  |
+| `ctx.config`                                      | manifest schema ⊕ registry ⊕ `aimux.config.ts`, defaults applied |
+| `ctx.paths`                                       | `root`, `config`, `state`, `log`                                 |
+| `ctx.effect(setup)`                               | run now, dispose on unload (reverse order)                       |
+| `ctx.on(event, listener)`                         | subscribe; auto-disposed                                         |
+| `ctx.emit / parallel / serial / bail / waterfall` | five dispatch modes                                              |
+| `ctx.rpc.call / handle / broadcast`               | talk to this plugin's other half across the process boundary     |
+| `ctx.provide / ctx.service`                       | publish and read services other plugins may `inject`             |
+
+## Testing
+
+`createTestContext()` builds a context with the real event bus and effect
+stack behind it, and stubs only what crosses a process boundary.
+
+```ts
+import { createTestContext } from '@brimveyn/aimux-plugin'
+import plugin from './daemon'
+
+test('notifies on turn complete', async () => {
+  const t = createTestContext({ config: { botToken: 'x' }, onCall: () => ({ ok: true }) })
+  await t.apply(plugin)
+
+  t.bus.emit('tab:turnComplete', { tabId: 't1' })
+
+  await t.dispose()
+  expect(t.effectCount()).toBe(0)
+})
+```
+
+## Author loop
+
+```
+aimux plugin new acme.thing --daemon   # scaffold
+aimux plugin link ./acme-thing         # register + build, watched from now on
+aimux plugin log acme.thing -f         # watch it work
+aimux plugin doctor ./acme-thing       # validate manifest, dry-import, list registrations
+```
+
+Full docs: `docs/developer/plugins.md` in the aimux repository.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@brimveyn/aimux-plugin",
+  "version": "0.1.2",
+  "description": "Plugin authoring API for aimux — context, effects, events and RPC for in-process plugins.",
+  "keywords": [
+    "aimux",
+    "extension",
+    "multiplexer",
+    "plugin",
+    "terminal",
+    "tui"
+  ],
+  "homepage": "https://github.com/BrimVeyn/aimux#readme",
+  "bugs": {
+    "url": "https://github.com/BrimVeyn/aimux/issues"
+  },
+  "license": "MIT",
+  "author": "BrimVeyn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrimVeyn/aimux.git",
+    "directory": "packages/aimux-plugin"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}

package/src/daemon-api.ts

@@ -0,0 +1,156 @@
+import type { Disposer } from './types'
+
+/**
+ * The daemon half's services — what a plugin reaches through `ctx.tabs`,
+ * `ctx.projects`, `ctx.workspaces`, `ctx.assistants`, `ctx.hooks` and
+ * `ctx.cli`.
+ *
+ * Declared here, implemented by `src/daemon/plugin-services.ts`. Same split as
+ * the UI half: this package stays free of aimux's internals so a plugin can be
+ * typechecked with nothing but `bun install`.
+ *
+ * The shapes that cross over — a tab view, a project record — are the aimux
+ * ones, structurally re-declared where they are small and left `unknown` where
+ * re-declaring them would be a second copy to keep in sync.
+ */
+
+export interface PluginTabView {
+  id: string
+  projectId: string
+  assistant: string
+  title: string
+  command: string
+  workspaceId?: string
+  workerName?: string
+}
+
+export interface PluginSpawnTabInput {
+  projectId: string
+  /** A registered assistant id, or a bare command's id. */
+  assistant: string
+  title: string
+  command: string
+  args?: string[]
+  cwd?: string
+  workspaceId?: string
+}
+
+export interface PluginTabsApi {
+  list: (projectId?: string) => PluginTabView[]
+  get: (tabId: string) => PluginTabView | undefined
+  /** The tab the UI is focused on for this project, or null. */
+  activeId: (projectId: string) => string | null
+  /**
+   * Spawns a tab and resolves with its id. Sized from the project's last
+   * attached dimensions — a plugin has no viewport of its own — so it fails
+   * with a clear error if no UI has ever attached to that project.
+   */
+  spawn: (input: PluginSpawnTabInput) => Promise<string>
+  /** Writes to the PTY. Bytes, not a line: the newline is the caller's to add. */
+  send: (tabId: string, data: string) => Promise<void>
+  /**
+   * Sets the tab's title. Reaches every attached UI and the persisted session,
+   * so it survives a restart — the same path aimux's own auto-rename uses.
+   *
+   * A title the user typed is theirs: a plugin that renames on its own
+   * schedule should check whether one is already set rather than overwrite it.
+   */
+  rename: (tabId: string, title: string) => Promise<void>
+  focus: (projectId: string, tabId: string) => Promise<void>
+  close: (tabId: string) => Promise<void>
+  /** The tab's last rendered lines, or null when it has produced no viewport. */
+  snapshot: (tabId: string, lines?: number) => string | null
+}
+
+/**
+ * A workspace, as a plugin sees it. `path` is the directory to run a command
+ * in and `repoRoot` the repository it belongs to — for a git worktree those
+ * differ, which is exactly why both are here.
+ */
+export interface PluginWorkspaceView {
+  id: string
+  name: string
+  path: string
+  repoRoot: string
+  branch?: string
+  baseRef?: string
+}
+
+export interface PluginProjectView {
+  id: string
+  name: string
+  /** Where the project lives, when it has a directory of its own. */
+  path?: string
+  workspaces: PluginWorkspaceView[]
+  activeWorkspaceId?: string
+}
+
+/**
+ * Project and workspace records, read from the catalog on every call because
+ * another process may have written it.
+ *
+ * Narrow projections rather than the raw records: the catalog entry carries a
+ * whole persisted UI snapshot — layout trees, scrollback buffers — and handing
+ * that to a plugin would make every field of it something aimux can no longer
+ * change.
+ */
+export interface PluginProjectsApi {
+  list: () => PluginProjectView[]
+  get: (projectId: string) => PluginProjectView | undefined
+}
+
+export interface PluginWorkspacesApi {
+  list: (projectId: string) => PluginWorkspaceView[]
+}
+
+/**
+ * What aimux knows about its own use, per local calendar day — counts and
+ * nothing else. No key identity, no content, nothing that leaves the machine.
+ */
+export interface PluginCounterDay {
+  /** `YYYY-MM-DD`, local calendar. */
+  day: string
+  values: Record<string, number>
+}
+
+export interface PluginMetricsApi {
+  /** Newest day first. `days` caps how far back it looks; default 30. */
+  counters: (days?: number) => PluginCounterDay[]
+}
+
+export interface PluginAssistantsApi {
+  /**
+   * Registers a complete assistant: spawn command, status classifier, question
+   * parser, usage adapter, hook mapping. See `AssistantDefinition` in
+   * `src/pty/assistant-registry.ts` for the shape.
+   */
+  register: (definition: unknown) => Disposer
+}
+
+export interface PluginHooksApi {
+  /**
+   * Adds an HTTP hook route. The id is namespaced, so the path a bridge script
+   * POSTs to is `/hook/<pluginId>.<id>` and cannot collide with another
+   * plugin's — or with `claude`.
+   */
+  route: (routeId: string, onEvent: (event: unknown) => void) => Disposer
+  /** The URL to hand a bridge script, or null when the route is not registered. */
+  url: (routeId: string) => string | null
+}
+
+export interface PluginCliApi {
+  /**
+   * Adds an `aimux <group> <verb>`. The command runs here, in the daemon; the
+   * CLI process learns its shape from a sidecar and never loads plugin code.
+   * Whatever `run` returns becomes the command's JSON body on stdout.
+   */
+  register: (command: {
+    group: string
+    verb: string
+    summary: string
+    run: (args: {
+      flags: Record<string, string | number | boolean>
+      positionals: string[]
+    }) => Promise<unknown>
+  }) => Disposer
+}

package/src/define-plugin.ts

@@ -0,0 +1,21 @@
+import type { PluginContext, PluginDefinition } from './types'
+
+/**
+ * Identity function that pins the context type, so `apply(ctx)` is inferred
+ * rather than annotated:
+ *
+ * ```ts
+ * export default definePlugin<UiPluginContext>({
+ *   inject: ['ui'],
+ *   apply(ctx) { ctx.log.info('hello') },
+ * })
+ * ```
+ *
+ * Plain `definePlugin({ … })` gives the base context, which is all a plugin
+ * that only uses `log` / `config` / `effect` / `on` / `rpc` needs.
+ */
+export function definePlugin<Ctx extends PluginContext = PluginContext>(
+  definition: PluginDefinition<Ctx>
+): PluginDefinition<Ctx> {
+  return definition
+}

package/src/effects.ts

@@ -0,0 +1,67 @@
+import type { Disposer } from './types'
+
+/**
+ * The disposer stack behind `ctx.effect` and every `register()` that hands one
+ * back. Unwinds in reverse registration order — the same discipline as a
+ * destructor chain — so a later effect can rely on an earlier one still being
+ * live while it tears itself down.
+ *
+ * A throwing disposer never stops the unwind: the remaining effects still run
+ * and the errors are reported together. A half-disposed fiber is the one state
+ * hot reload cannot recover from.
+ */
+export class EffectStack {
+  private disposers: Disposer[] = []
+  private disposed = false
+
+  get size(): number {
+    return this.disposers.length
+  }
+
+  get isDisposed(): boolean {
+    return this.disposed
+  }
+
+  /**
+   * Registers a disposer. Adding one to an already-disposed stack runs it
+   * immediately rather than leaking it — that happens when an async `apply`
+   * resolves after the fiber was torn down.
+   */
+  add(disposer: Disposer): void {
+    if (this.disposed) {
+      void this.disposeOrphan(disposer)
+      return
+    }
+    this.disposers.push(disposer)
+  }
+
+  private async disposeOrphan(disposer: Disposer): Promise<void> {
+    try {
+      await disposer()
+    } catch {
+      // Nothing left to report to: the stack this belonged to is gone.
+    }
+  }
+
+  /** Runs `setup` now and registers whatever disposer it returns. */
+  async run(setup: () => Disposer | void | Promise<Disposer | void>): Promise<void> {
+    const disposer = await setup()
+    if (typeof disposer === 'function') this.add(disposer)
+  }
+
+  /** Unwind. Returns every error thrown, in the order they were thrown. */
+  async dispose(): Promise<unknown[]> {
+    this.disposed = true
+    const pending = this.disposers
+    this.disposers = []
+    const errors: unknown[] = []
+    for (let i = pending.length - 1; i >= 0; i--) {
+      try {
+        await pending[i]?.()
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    return errors
+  }
+}

package/src/event-bus.ts

@@ -0,0 +1,137 @@
+import type { PluginEventListener } from './types'
+
+/**
+ * The event bus lives in the public package rather than in the host so that
+ * `createTestContext()` dispatches exactly the way the kernel does. A plugin
+ * test that passes against the harness is testing the real semantics of
+ * `bail` and `waterfall`, not an approximation of them.
+ *
+ * It has no aimux dependencies — it is a listener map and five dispatch
+ * strategies.
+ */
+
+interface Registration {
+  listener: PluginEventListener<never>
+  /** Only used for error attribution; the bus itself is owner-agnostic. */
+  owner?: string
+}
+
+export interface EventBusOptions {
+  /**
+   * Called when a listener throws or rejects. `emit` has nowhere to put the
+   * error otherwise, and swallowing it silently is how a plugin bug becomes
+   * a mystery. The awaiting modes rethrow instead.
+   */
+  onError?: (error: unknown, context: { event: string; owner?: string }) => void
+}
+
+export class PluginEventBus {
+  private readonly listeners = new Map<string, Registration[]>()
+
+  constructor(private readonly options: EventBusOptions = {}) {}
+
+  /** The unsubscribe handle. Synchronous — nothing here can suspend. */
+  on<T = unknown>(event: string, listener: PluginEventListener<T>, owner?: string): () => void {
+    const registration: Registration = { listener: listener as PluginEventListener<never>, owner }
+    const existing = this.listeners.get(event)
+    if (existing) existing.push(registration)
+    else this.listeners.set(event, [registration])
+
+    return () => {
+      const current = this.listeners.get(event)
+      if (!current) return
+      const index = current.indexOf(registration)
+      if (index !== -1) current.splice(index, 1)
+      if (current.length === 0) this.listeners.delete(event)
+    }
+  }
+
+  /** Snapshot: a listener that unsubscribes mid-dispatch must not shift the list. */
+  private snapshot(event: string): Registration[] {
+    const current = this.listeners.get(event)
+    return current ? [...current] : []
+  }
+
+  listenerCount(event: string): number {
+    return this.listeners.get(event)?.length ?? 0
+  }
+
+  /** Every event that currently has at least one listener. */
+  events(): string[] {
+    return [...this.listeners.keys()]
+  }
+
+  private report(error: unknown, event: string, owner?: string): void {
+    this.options.onError?.(error, { event, owner })
+  }
+
+  private async reportRejection(
+    result: Promise<unknown>,
+    event: string,
+    owner?: string
+  ): Promise<void> {
+    try {
+      await result
+    } catch (error) {
+      this.report(error, event, owner)
+    }
+  }
+
+  /**
+   * Synchronous listeners run synchronously — `emit` then asserting on the
+   * effect must not need an intervening await. Only an async listener's
+   * rejection is picked up later.
+   */
+  emit(event: string, payload?: unknown): void {
+    for (const { listener, owner } of this.snapshot(event)) {
+      let result: unknown
+      try {
+        result = listener(payload as never)
+      } catch (error) {
+        this.report(error, event, owner)
+        continue
+      }
+      if (result instanceof Promise) void this.reportRejection(result, event, owner)
+    }
+  }
+
+  async parallel(event: string, payload?: unknown): Promise<unknown[]> {
+    return Promise.all(this.snapshot(event).map(({ listener }) => listener(payload as never)))
+  }
+
+  async serial(event: string, payload?: unknown): Promise<unknown[]> {
+    const results: unknown[] = []
+    for (const { listener } of this.snapshot(event)) {
+      results.push(await listener(payload as never))
+    }
+    return results
+  }
+
+  /** First listener to return anything but `undefined` wins; the rest never run. */
+  async bail<T>(event: string, payload?: unknown): Promise<T | undefined> {
+    for (const { listener } of this.snapshot(event)) {
+      const result = await listener(payload as never)
+      if (result !== undefined) return result as T
+    }
+    return undefined
+  }
+
+  /**
+   * Threads a value through the chain. A listener returning `undefined` is
+   * read as "no opinion" and leaves the value untouched, so a listener that
+   * only inspects the value does not have to remember to return it.
+   */
+  async waterfall<T>(event: string, value: T): Promise<T> {
+    let current = value
+    for (const { listener } of this.snapshot(event)) {
+      const next = await listener(current as never)
+      if (next !== undefined) current = next as T
+    }
+    return current
+  }
+
+  /** Drop every listener. Used when a whole kernel is torn down. */
+  clear(): void {
+    this.listeners.clear()
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+// Public API — what plugin authors import from '@brimveyn/aimux-plugin'.
+//
+// Everything here is `apiVersion: 1`. A plugin declares that number in its
+// manifest and aimux refuses to load a plugin written against a generation it
+// does not implement, rather than failing halfway through `apply`.
+
+export type {
+  PluginAssistantsApi,
+  PluginCliApi,
+  PluginCounterDay,
+  PluginHooksApi,
+  PluginMetricsApi,
+  PluginProjectsApi,
+  PluginProjectView,
+  PluginSpawnTabInput,
+  PluginTabsApi,
+  PluginTabView,
+  PluginWorkspacesApi,
+  PluginWorkspaceView,
+} from './daemon-api'
+export { definePlugin } from './define-plugin'
+export { EffectStack } from './effects'
+export { type EventBusOptions, PluginEventBus } from './event-bus'
+export {
+  PLUGIN_API_VERSION,
+  type PluginBarContribution,
+  type PluginCommandSpec,
+  type PluginConfigField,
+  type PluginConfigFieldType,
+  type PluginContributions,
+  type PluginHost,
+  type PluginKeymapContribution,
+  type PluginManifest,
+} from './manifest'
+export {
+  createTestContext,
+  type TestContextHandle,
+  type TestContextOptions,
+  type TestLogEntry,
+  type TestRpcCall,
+} from './test-context'
+export type {
+  PluginActionsApi,
+  PluginBarWidget,
+  PluginComponent,
+  PluginKit,
+  PluginModal,
+  PluginModalsApi,
+  PluginNode,
+  PluginPane,
+  PluginPanesApi,
+  PluginSettingsApi,
+  PluginSettingValue,
+  PluginStateApi,
+  PluginStatsApi,
+  PluginStatsPage,
+  PluginStatusBarApi,
+  PluginStatusBarSegment,
+  PluginStoreApi,
+  PluginTabInfo,
+  PluginThemeMode,
+  PluginThemesApi,
+  PluginThemeSnapshot,
+  PluginToastApi,
+  PluginUiApi,
+  PluginUiState,
+  PluginView,
+  PluginViewsApi,
+  PluginWidgetsApi,
+} from './ui'
+export type {
+  DaemonPluginContext,
+  Disposer,
+  PluginContext,
+  PluginDefinition,
+  PluginEventDispatch,
+  PluginEventListener,
+  PluginLogger,
+  PluginPaths,
+  PluginRpc,
+  UiPluginContext,
+} from './types'