@elliotsystems/eai 0.1.2 → 0.1.4

package/plugin/opencode-plugin/src/index.ts

@@ -0,0 +1,211 @@
+/**
+ * @elliotsystems/opencode-plugin — Elliot AI's OpenCode integration.
+ *
+ * Phase C2 scope: exactly one job. The Elliot backend serves `knowledge_search`
+ * over the native MCP + OAuth boundary (agent-visible as
+ * `elliot_knowledge_search`); this plugin injects the session's repository
+ * scope into that tool's arguments so retrieval can be repo-focused — while the
+ * model itself never names a repository, and the backend's `resolve_repo_scope`
+ * remains the only authorizer.
+ *
+ * What this plugin deliberately does NOT do:
+ *   - no tokens: OAuth lifecycle (login, storage, refresh) is OpenCode's native
+ *     MCP client, verified end-to-end against this backend;
+ *   - no transport: there is no tool-invoke server route at v1.18.19, and
+ *     reading mcp-auth.json would create a second credential path;
+ *   - no prompt stuffing: knowledge arrives when the agent elects the tool.
+ *
+ * Loading (any of): opencode.json `"plugin": [["@elliotsystems/opencode-plugin",
+ * {"serverNames": ["elliot"]}]]`, a path spec during development, or a
+ * `.opencode/plugin/` file re-export.
+ */
+import { isElliotKnowledgeTool, parseOptions, shellVerdict } from "./policy.js"
+import { ELLIOT_PROVIDER_ID, configHook, makeAuthHook } from "./proxy-provider.js"
+import { readElliotConfig } from "./elliot-auth.js"
+import { formatScope, scopeForWorktree } from "./scope.js"
+import { applyElliotIdentity } from "./identity.js"
+
+// Structural mirrors of the host types (packages/plugin/src/index.ts @
+// v1.18.19). Declared locally so this package type-checks and unit-tests
+// without the opencode workspace on the module path; the host validates
+// plugins structurally (`readV1Plugin`), so compatibility is by shape, not by
+// nominal import.
+export interface PluginInput {
+  directory: string
+  worktree: string
+  project?: unknown
+  client?: {
+    auth?: {
+      set: (input: { path: { id: string }; body: Record<string, unknown> }) => Promise<unknown>
+    }
+    [k: string]: unknown
+  }
+  serverUrl?: URL
+  $?: unknown
+}
+
+/** The host's Permission payload — only the fields this plugin reads. */
+export interface PermissionInput {
+  type: string
+  pattern?: string | string[]
+  metadata?: Record<string, unknown>
+}
+
+/** Structural mirror of the host's `AuthHook` (packages/plugin/src/index.ts). */
+export interface AuthHook {
+  provider: string
+  methods: unknown[]
+  loader?: (auth: () => Promise<unknown>, provider: unknown) => Promise<Record<string, any>>
+}
+
+export interface Hooks {
+  "tool.execute.before"?: (
+    input: { tool: string; sessionID: string; callID: string },
+    output: { args: Record<string, unknown> },
+  ) => Promise<void>
+  "permission.ask"?: (
+    input: PermissionInput,
+    output: { status: "ask" | "deny" | "allow" },
+  ) => Promise<void>
+  "experimental.chat.system.transform"?: (
+    input: { sessionID?: string; model: unknown },
+    output: { system: string[] },
+  ) => Promise<void>
+  config?: (input: any) => Promise<void>
+  auth?: AuthHook
+  dispose?: () => Promise<void>
+}
+
+export type Plugin = (input: PluginInput, options?: Record<string, unknown>) => Promise<Hooks>
+
+export const ElliotPlugin: Plugin = async (input, rawOptions) => {
+  // Fail loudly at load on bad options — a plugin that limps with a typo'd
+  // config is worse than one that says why it refused to start.
+  const options = parseOptions(rawOptions)
+
+  // Session truth, resolved once. The worktree comes from OpenCode itself —
+  // the one source the model cannot influence.
+  const worktree = input.worktree || input.directory
+
+  // Seed a placeholder auth entry for the `elliot` provider so the host's
+  // auth loader fires at all (`provider.ts:1584` skips the loader entirely
+  // when nothing is stored for its provider id — see Task-1 findings). The
+  // value itself is never the credential that reaches the wire; the auth
+  // loader's `fetch` attaches the live bearer token per request. Guarded so
+  // a client-RPC failure never breaks plugin init, and skipped outright when
+  // the user isn't logged into Elliot.
+  if (readElliotConfig()) {
+    try {
+      await input.client?.auth?.set({
+        path: { id: ELLIOT_PROVIDER_ID },
+        body: { type: "api", key: "elliot-managed" },
+      })
+    } catch {
+      // Never break plugin init on a seeding failure — the auth loader
+      // simply won't fire this session, same as the no-login path.
+    }
+  }
+
+  return {
+    /**
+     * One handler, two jobs — a JS object literal may carry only one
+     * `tool.execute.before` key, and a second would silently shadow the first.
+     *   (a) the Elliot knowledge tool -> inject worktree-derived repo scope
+     *   (b) the shell tool            -> enforce org hard-deny / credential policy
+     */
+    "tool.execute.before": async (hookInput, output) => {
+      // (a) Knowledge-tool scope injection. The model never names a repository;
+      // this value comes from the session worktree, and the backend authorizes it.
+      if (isElliotKnowledgeTool(hookInput.tool, options)) {
+        const scope = await scopeForWorktree(worktree)
+        if (scope) {
+          // Unconditional overwrite: session truth beats anything already in args.
+          // The backend schema forbids model-supplied scope, but if one ever slipped
+          // through a future contract change, it dies here first.
+          output.args["repo_scope_hint"] = formatScope(scope)
+        } else {
+          // No derivable scope -> guarantee none is smuggled either. Tenant-wide
+          // search is the correct degradation (authorized, just unfocused).
+          delete output.args["repo_scope_hint"]
+        }
+        return
+      }
+
+      // (b) Shell policy, enforced HERE rather than in `permission.ask`.
+      //
+      // Forced by upstream reality, verified by scanning every `plugin.trigger(...)`
+      // site in v1.18.19: thirteen hooks are triggered and `permission.ask` is NOT
+      // among them. It is declared in the public plugin API
+      // (packages/plugin/src/index.ts:261) but never invoked, so a handler there is
+      // dead code in this version. `tool.execute.before` IS triggered
+      // (session/prompt.ts), and throwing from it aborts the tool call — the only
+      // plugin-side hard stop available today.
+      //
+      // Why bother when the org glob policy already asks/denies? Defence in depth
+      // against what globs structurally cannot see: a catastrophic shape hiding
+      // behind a safe-looking chain segment (`git status ; rm -rf /`), and a command
+      // that both names a secret-shaped path and invokes a network tool. If an org
+      // policy is ever loosened by accident, these still do not get through.
+      //
+      // Deliberately narrow: it only ever BLOCKS, and only on the hard-deny and
+      // credential classes. Commands the classifier merely wants confirmed are left
+      // to the host's own ask flow, which already handles them well.
+      if (hookInput.tool !== "bash" && !hookInput.tool.endsWith("_bash")) return
+
+      const command = output.args?.["command"]
+      if (typeof command !== "string") return
+
+      const verdict = shellVerdict(command)
+      if (verdict?.status !== "deny") return
+
+      throw new Error(
+        `Blocked by Elliot organization policy: ${verdict.reason}. Command: ${command}`,
+      )
+    },
+
+    /**
+     * Kept deliberately, though currently INERT: `permission.ask` has no trigger
+     * site in v1.18.19 (verified across every `plugin.trigger` call). When upstream
+     * wires it, policy decisions belong here — a returned status is cleaner than a
+     * thrown tool error — so this is the forward-compatible home. It can only ever
+     * tighten.
+     */
+    // The agent introduces itself as OpenCode on a stock runtime, because that
+    // is what the compiled system prompt says. Rewritten here so the fix lives
+    // in the overlay instead of in the harness. See ./identity.ts.
+    "experimental.chat.system.transform": async (_hookInput, output) => {
+      applyElliotIdentity(output.system)
+    },
+
+    "permission.ask": async (permInput, output) => {
+      if (permInput.type !== "bash") return
+      const command = permInput.metadata?.["command"]
+      if (typeof command !== "string") return
+      const verdict = shellVerdict(command)
+      if (!verdict) return
+      if (output.status === "deny") return // never loosen
+      output.status = verdict.status
+    },
+
+    /**
+     * Registers the `elliot` provider (proxy baseURL) and defaults the
+     * model to it — no-op when the user isn't logged into Elliot. See
+     * `proxy-provider.ts`.
+     */
+    config: async (c) => {
+      configHook(c)
+    },
+
+    /**
+     * Self-refreshing auth loader for the `elliot` provider — see
+     * `proxy-provider.ts`. Only fires once the seeding above has stored an
+     * auth entry for `ELLIOT_PROVIDER_ID`.
+     */
+    auth: makeAuthHook(),
+  }
+}
+
+// Both export styles the host loader accepts (`getLegacyPlugins` takes any
+// function export; `PluginModule` prefers `server`).
+export const server = ElliotPlugin
+export default ElliotPlugin

package/plugin/opencode-plugin/src/mcp-keys.ts

@@ -0,0 +1,30 @@
+/**
+ * How OpenCode composes agent-visible MCP tool keys.
+ *
+ * Its own module, with ZERO imports, because two runtimes need it. `policy.ts`
+ * uses it in the server plugin (where zod is available) and `tui/knowledge.ts`
+ * uses it in the TUI plugin runtime — which shares only a fixed list of modules
+ * with plugins (`solid-js`, `@opentui/*`, `bun`; see `tui/host.d.ts`) and would
+ * fail to load a module that reached for `zod` transitively.
+ *
+ * Duplicating the rule in both places was the alternative. A drifted copy of a
+ * key-composition rule fails silently — the tool simply stops being recognised —
+ * so one definition, imported twice, is the safer shape.
+ */
+
+/**
+ * Mirror of OpenCode's `McpCatalog.sanitize` (mcp/catalog.ts:117) so composed
+ * keys are predicted exactly, including server names carrying characters MCP
+ * sanitises away.
+ */
+export function sanitizeKey(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "_")
+}
+
+/** The backend tool behind every Elliot knowledge lookup. */
+export const KNOWLEDGE_TOOL = "knowledge_search"
+
+/** The agent-visible key for `KNOWLEDGE_TOOL` on a given MCP server. */
+export function knowledgeToolKey(serverName: string): string {
+  return `${sanitizeKey(serverName)}_${KNOWLEDGE_TOOL}`
+}

package/plugin/opencode-plugin/src/policy.ts

@@ -0,0 +1,122 @@
+/**
+ * C2-minimal policy: validate the plugin's own options, and identify which
+ * agent-visible tool keys are Elliot knowledge tools.
+ *
+ * Deliberately small. The full bash-policy port (command classification,
+ * hard-deny set) is a later phase — nothing in C2 executes shell commands, and
+ * carrying unused policy code would be scope creep wearing a safety costume.
+ *
+ * `PluginOptions` is untyped upstream (`Record<string, unknown>`), so a typo'd
+ * option would otherwise vanish silently; zod turns that into a load-time
+ * message instead.
+ */
+import { z } from "zod"
+
+import {
+  type Category,
+  classifyCommand,
+  isHardDenied,
+  killsAgentRuntime,
+  looksLikeCredentialExfiltration,
+} from "./classifier.js"
+import { KNOWLEDGE_TOOL, knowledgeToolKey, sanitizeKey } from "./mcp-keys.js"
+
+const OptionsSchema = z
+  .object({
+    /**
+     * MCP server name(s) this plugin should treat as Elliot. Must match the
+     * key(s) under `mcp` in opencode.json. OpenCode composes agent-visible MCP
+     * tool keys as `<client>_<tool>` (mcp/catalog.ts:119), so these names are
+     * what let the hooks recognise Elliot tools.
+     */
+    serverNames: z.array(z.string().min(1)).min(1).default(["elliot"]),
+  })
+  .strict()
+
+export type ElliotPluginOptions = z.infer<typeof OptionsSchema>
+
+/**
+ * Parse options, throwing a load-time error on unknown/invalid keys. A plugin
+ * that starts with wrong options and limps is worse than one that says why it
+ * refused to.
+ */
+export function parseOptions(raw: unknown): ElliotPluginOptions {
+  return OptionsSchema.parse(raw ?? {})
+}
+
+/**
+ * Re-exported so existing importers (and the test suite) keep one entry point
+ * for the key rule, which now lives in `mcp-keys.ts` — see that module for why
+ * it had to become import-free.
+ */
+export { KNOWLEDGE_TOOL, sanitizeKey }
+
+/**
+ * Is this agent-visible tool key Elliot's knowledge tool on one of our
+ * configured servers? Exact composed-key match only — a suffix match would let
+ * an unrelated MCP server named e.g. "not-elliot" receive our scope hints.
+ */
+export function isElliotKnowledgeTool(toolKey: string, options: ElliotPluginOptions): boolean {
+  return options.serverNames.some((server) => toolKey === knowledgeToolKey(server))
+}
+
+// -- Shell policy verdicts ---------------------------------------------------
+
+/**
+ * What the plugin does to a shell permission decision, and — just as importantly —
+ * what it refuses to do.
+ *
+ * `undefined` means "leave the host's decision untouched". That is the default for
+ * anything read-shaped, and it matters: the org's glob policy already decided those,
+ * and a plugin that *widened* a permission it did not grant would be a privilege
+ * escalation wearing a helpful face. This function can therefore only ever tighten.
+ */
+export function shellVerdict(
+  command: string,
+): { status: "deny" | "ask"; category: Category; reason: string } | undefined {
+  if (!command.trim()) {
+    // Nothing to inspect: say nothing rather than guess. The host's own policy
+    // (`bash *: ask` in the org default) remains in force.
+    return undefined
+  }
+
+  if (isHardDenied(command)) {
+    return {
+      status: "deny",
+      category: "DESTRUCTIVE",
+      reason:
+        "catastrophic command shape (org hard-deny list) — refused outright; " +
+        "confirmation adds no safety against a runaway loop",
+    }
+  }
+
+  if (killsAgentRuntime(command)) {
+    return {
+      status: "deny",
+      category: "DESTRUCTIVE",
+      reason:
+        "kills processes by name matching Elliot's own runtime (node/bun/opencode), " +
+        "which terminates this session mid-command and leaves the terminal in " +
+        "mouse-reporting mode — target a specific PID instead (Stop-Process -Id, " +
+        "taskkill /PID), or kill the service by its own process name",
+    }
+  }
+
+  if (looksLikeCredentialExfiltration(command)) {
+    return {
+      status: "deny",
+      category: "DESTRUCTIVE",
+      reason:
+        "names a secret-shaped path AND invokes a network tool — refused as possible " +
+        "credential exfiltration",
+    }
+  }
+
+  const category = classifyCommand(command)
+  if (category === "DESTRUCTIVE" || category === "MUTATION" || category === "UNKNOWN") {
+    return { status: "ask", category, reason: `classified ${category} — needs confirmation` }
+  }
+
+  // READ / TEST / BUILD: the org globs already allow these. Stay out of the way.
+  return undefined
+}

package/plugin/opencode-plugin/src/proxy-provider.ts

@@ -0,0 +1,96 @@
+/**
+ * The Elliot proxy provider: a `config` hook that registers a custom
+ * `elliot` OpenCode provider pointed at the Elliot LightLLM proxy, and an
+ * `auth` hook whose `loader` returns a self-refreshing `fetch` that attaches
+ * a live bearer token per request.
+ *
+ * Mechanism pinned in `.superpowers/sdd/2026-09-03-eai-proxy-auth/task-1-findings.md`:
+ *   - `config` hook mutates its input in place (no separate output param).
+ *   - `auth.loader`'s return value is spread wholesale into the provider's
+ *     resolved `options`, so `{ apiKey, fetch }` land there directly.
+ *   - `apiKey` is baked into the AI-SDK client at construction time and
+ *     never changes; the actually-rotating credential is injected per
+ *     request by `options.fetch`'s `Authorization` header (never the static
+ *     `apiKey`) — same pattern as OpenCode's bundled snowflake-cortex plugin.
+ *   - The loader only runs once a stored auth entry exists for its
+ *     `provider` id (`provider.ts:1584`); the plugin seeds that entry itself
+ *     at init (see `index.ts`) so no interactive `opencode auth login` step
+ *     is ever required.
+ *
+ * Everything here is a no-op when the user isn't logged in
+ * (`readElliotConfig()` returns null) — OpenCode then runs exactly as it
+ * would without this plugin.
+ */
+import { freshToken, readElliotConfig } from "./elliot-auth.js"
+
+export const ELLIOT_LLM_PROXY_URL = "https://backend.elliotsystemsonline.com/llm-proxy"
+export const ELLIOT_PROVIDER_ID = "elliot"
+
+/**
+ * Registers the `elliot` provider (baseURL = the LightLLM proxy) and
+ * defaults `cfg.model` to it, mutating `cfg` in place. No-op when the user
+ * isn't logged in. Never overwrites a model the user already configured, or
+ * any other existing key under `cfg.provider`/`cfg.plugin`/`cfg.mcp`/etc.
+ */
+export function configHook(cfg: any): void {
+  if (!readElliotConfig()) return
+
+  cfg.provider ??= {}
+  cfg.provider[ELLIOT_PROVIDER_ID] = {
+    npm: "@ai-sdk/anthropic",
+    name: "Elliot (governed)",
+    options: { baseURL: ELLIOT_LLM_PROXY_URL },
+    models: { "elliot-governed": { name: "Elliot (governed)" } },
+  }
+
+  cfg.model ??= "elliot/elliot-governed"
+}
+
+/**
+ * Merge `Authorization: Bearer <token>` into whatever headers `init` already
+ * carries, without dropping them. Works whether `init.headers` is a plain
+ * object, a `Headers` instance, or an array of pairs.
+ */
+function withAuthHeader(init: RequestInit | undefined, token: string): RequestInit {
+  const headers = new Headers(init?.headers)
+  headers.set("Authorization", `Bearer ${token}`)
+  return { ...init, headers }
+}
+
+/**
+ * The per-request fetch wrapper: reads `~/.elliot/config.json` fresh on
+ * every call (so a refresh picked up by another process is honored
+ * immediately), refreshes via `freshToken` when needed, and attaches the
+ * bearer token. Never throws — a missing/expired/unrefreshable token just
+ * means the request goes out unauthenticated and the proxy 401s.
+ */
+async function elliotFetch(input: string | URL | Request, init?: RequestInit): Promise<Response> {
+  try {
+    const cfg = readElliotConfig()
+    const token = cfg ? await freshToken(cfg) : null
+    if (token) {
+      return globalThis.fetch(input, withAuthHeader(init, token))
+    }
+    return globalThis.fetch(input, init)
+  } catch {
+    return globalThis.fetch(input, init)
+  }
+}
+
+/**
+ * Builds the `auth` hook object per the Task-1 pinned `AuthHook` shape.
+ * `methods` is empty — this provider is never set up via interactive
+ * `opencode auth login`; the plugin seeds the stored auth entry itself
+ * (see `index.ts`) so the loader always fires once the user is logged into
+ * Elliot.
+ */
+export function makeAuthHook() {
+  return {
+    provider: ELLIOT_PROVIDER_ID,
+    methods: [] as unknown[],
+    loader: async (_auth: () => Promise<unknown>, _provider: unknown) => ({
+      apiKey: "elliot-managed",
+      fetch: elliotFetch,
+    }),
+  }
+}

package/plugin/opencode-plugin/src/scope.ts

@@ -0,0 +1,78 @@
+/**
+ * Repository scope from the session worktree — the trusted-context half of the
+ * "the model never names a repository" invariant.
+ *
+ * Ported (trimmed, not imported) from `elliot-cli/src/project.ts`: the same
+ * `execFile` discipline — a fixed, hardcoded argument array, never a string a
+ * shell would parse, and never anything the LLM supplies. The worktree path
+ * comes from OpenCode's own `PluginInput`/`ToolContext`, which is session
+ * truth, not model output.
+ *
+ * Authorization is NOT here and never will be: the derived `owner/name` is a
+ * hint the Elliot backend authorizes via `resolve_repo_scope`. A wrong value
+ * can therefore select nothing the tenant was not already granted — which is
+ * why every failure path below degrades to `null` (tenant-wide search) rather
+ * than throwing. Scope is an optimization, never a gate.
+ */
+import { execFile } from "node:child_process"
+
+export interface RepoScope {
+  owner: string
+  name: string
+}
+
+/**
+ * Handles SSH (git@host:owner/repo.git) and HTTPS (https://host/owner/repo.git)
+ * remote forms generically — not GitHub-specific. Same regex the CLI used.
+ */
+export function parseOwnerRepo(remoteUrl: string | null | undefined): RepoScope | null {
+  if (!remoteUrl) return null
+  const match = remoteUrl.match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?$/)
+  if (!match) return null
+  return { owner: match[1], name: match[2] }
+}
+
+/** `owner/name`, the wire form `repo_scope_hint` carries. */
+export function formatScope(scope: RepoScope): string {
+  return `${scope.owner}/${scope.name}`
+}
+
+function gitRemoteUrl(worktree: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile(
+      "git",
+      ["remote", "get-url", "origin"],
+      { cwd: worktree, timeout: 5_000, windowsHide: true },
+      (err, stdout) => {
+        // Any failure — not a repo, no origin, git absent, timeout — is a
+        // normal discovery miss, never an error to surface.
+        if (err) return resolve(null)
+        const url = stdout.trim()
+        resolve(url.length ? url : null)
+      },
+    )
+  })
+}
+
+/**
+ * Derive `owner/name` for a worktree, or null when it cannot be known.
+ *
+ * Cached per worktree path for the plugin's lifetime: the remote of an open
+ * session's repository does not meaningfully change mid-session, and the CLI's
+ * rule ("detected once, never re-run per tool call") carries over.
+ */
+const cache = new Map<string, Promise<RepoScope | null>>()
+
+export function scopeForWorktree(worktree: string | null | undefined): Promise<RepoScope | null> {
+  if (!worktree) return Promise.resolve(null)
+  const hit = cache.get(worktree)
+  if (hit) return hit
+  const pending = gitRemoteUrl(worktree).then(parseOwnerRepo)
+  cache.set(worktree, pending)
+  return pending
+}
+
+/** Test-only: clear the per-worktree cache. */
+export function resetScopeCache(): void {
+  cache.clear()
+}

package/plugin/opencode-plugin/src/tui/api.ts

@@ -0,0 +1,117 @@
+/**
+ * Structural mirror of the slice of `TuiPluginApi` this chrome uses.
+ *
+ * `@opencode-ai/plugin/tui` is deliberately absent from the module list the host
+ * shares with runtime-loaded plugins (see `host.d.ts`), so its types cannot be
+ * imported. The host validates plugins by SHAPE, not by nominal type, which is
+ * what makes a local mirror correct rather than a workaround.
+ *
+ * Only the members the chrome actually reads appear here. A mirror that copied
+ * the whole surface would be a second copy of upstream's API to keep in sync,
+ * and every unused member in it is a silent drift risk.
+ */
+import type { RGBA } from "@opentui/core"
+
+/** Theme roles this chrome paints with. Names match upstream's exactly. */
+export interface ThemeCurrent {
+  readonly primary: RGBA
+  readonly text: RGBA
+  readonly textMuted: RGBA
+  readonly background: RGBA
+  readonly backgroundPanel: RGBA
+  readonly border: RGBA
+  readonly success: RGBA
+  readonly warning: RGBA
+  readonly error: RGBA
+}
+
+/** `TuiSidebarFileItem`. */
+export interface FileItem {
+  readonly file: string
+  readonly additions: number
+  readonly deletions: number
+}
+
+/** `TuiSidebarMcpItem`. */
+export interface McpStatusItem {
+  readonly name: string
+  readonly status: string
+  readonly error?: string
+}
+
+/** A `Message`, narrowed to the id needed to fetch its parts. */
+export interface MessageLike {
+  readonly id: string
+}
+
+/** A `Part`, narrowed to what a knowledge citation needs. */
+export interface PartLike {
+  readonly type: string
+  readonly tool?: string
+  readonly state?: {
+    readonly status?: string
+    readonly output?: string
+  }
+}
+
+/** `TuiState` — the read-only session view the chrome derives everything from. */
+export interface StateApi {
+  readonly ready: boolean
+  readonly path: {
+    readonly worktree: string
+    readonly directory: string
+  }
+  readonly vcs: { readonly branch?: string; readonly default_branch?: string } | undefined
+  readonly session: {
+    count: () => number
+    diff: (sessionID: string) => ReadonlyArray<FileItem>
+    messages: (sessionID: string) => ReadonlyArray<MessageLike>
+  }
+  part: (messageID: string) => ReadonlyArray<PartLike>
+  mcp: () => ReadonlyArray<McpStatusItem>
+}
+
+/** `TuiPromptProps` — the host's prompt component, reused rather than rebuilt. */
+export interface PromptProps {
+  sessionID?: string
+  visible?: boolean
+  disabled?: boolean
+  onSubmit?: () => void
+  ref?: (ref: unknown) => void
+  hint?: unknown
+  right?: unknown
+  showPlaceholder?: boolean
+  placeholders?: { normal?: string[]; shell?: string[] }
+}
+
+export interface TuiPluginApi {
+  readonly app: { readonly version: string }
+  readonly theme: {
+    readonly current: ThemeCurrent
+    /**
+     * Copies a theme file from the plugin root into a directory the host's
+     * theme discovery scans. Resolved relative to the plugin root by
+     * `createThemeInstaller` (packages/opencode/src/plugin/tui/runtime.ts:245).
+     */
+    install: (jsonPath: string) => Promise<void>
+    has: (name: string) => boolean
+  }
+  readonly state: StateApi
+  readonly ui: {
+    Prompt: (props: PromptProps) => unknown
+  }
+  readonly slots: {
+    register(input: { order?: number; slots: Record<string, unknown> }): unknown
+  }
+}
+
+export type TuiPlugin = (api: TuiPluginApi) => Promise<void>
+
+/** Props the host passes to the session-scoped slots. */
+export interface SessionSlotProps {
+  readonly session_id: string
+  readonly visible?: boolean
+  readonly disabled?: boolean
+  readonly on_submit?: () => void
+  readonly ref?: (ref: unknown) => void
+}