mu-core 0.8.0

package/src/hooks.ts

@@ -0,0 +1,89 @@
+import type { AgentEndReason, BeforeToolExecResult, LifecycleHooks, TurnResult, UserInputTransform } from './plugin';
+import type { ChatMessage, ProviderConfig, ToolCall } from './types/llm';
+
+export async function runBeforeLlmHooks(
+  hooks: LifecycleHooks[],
+  messages: ChatMessage[],
+  config: ProviderConfig,
+): Promise<ChatMessage[]> {
+  let current = messages;
+  for (const hook of hooks) {
+    if (hook.beforeLlmCall) {
+      current = await hook.beforeLlmCall(current, config);
+    }
+  }
+  return current;
+}
+
+export async function runAfterLlmHooks(hooks: LifecycleHooks[], result: TurnResult): Promise<TurnResult> {
+  let current = result;
+  for (const hook of hooks) {
+    if (hook.afterLlmCall) {
+      current = await hook.afterLlmCall(current);
+    }
+  }
+  return current;
+}
+
+/**
+ * Run every `beforeToolExec` hook in order. Each hook may either return a
+ * (possibly mutated) `ToolCall` to keep the chain going, or a `ToolBlock` to
+ * short-circuit execution. Once a hook blocks the call, no further hooks run
+ * — there's nothing useful to forward.
+ */
+export async function runBeforeToolExecHook(
+  hooks: LifecycleHooks[],
+  toolCall: ToolCall,
+): Promise<BeforeToolExecResult> {
+  let current: BeforeToolExecResult = toolCall;
+  for (const hook of hooks) {
+    if (!hook.beforeToolExec) continue;
+    if ('blocked' in current) return current;
+    current = await hook.beforeToolExec(current);
+  }
+  return current;
+}
+
+export async function runAfterToolExecHook(
+  hooks: LifecycleHooks[],
+  toolCall: ToolCall,
+  result: string,
+): Promise<string> {
+  let current = result;
+  for (const hook of hooks) {
+    if (hook.afterToolExec) {
+      current = await hook.afterToolExec(toolCall, current);
+    }
+  }
+  return current;
+}
+
+export async function runAfterAgentRunHooks(hooks: LifecycleHooks[], reason: AgentEndReason): Promise<void> {
+  for (const hook of hooks) {
+    if (hook.afterAgentRun) {
+      await hook.afterAgentRun(reason);
+    }
+  }
+}
+
+/**
+ * Compose every `transformUserInput` hook. Earlier hooks see the raw text;
+ * each subsequent hook sees the (possibly rewritten) text emitted by the
+ * previous one. The first `intercept` short-circuits the chain.
+ */
+export async function runTransformUserInputHooks(hooks: LifecycleHooks[], text: string): Promise<UserInputTransform> {
+  let current: UserInputTransform = { kind: 'pass' };
+  let working = text;
+  for (const hook of hooks) {
+    if (!hook.transformUserInput) continue;
+    const next = await hook.transformUserInput(working);
+    if (next.kind === 'intercept') {
+      return next;
+    }
+    if (next.kind === 'transform') {
+      working = next.text;
+      current = next;
+    }
+  }
+  return current;
+}

package/src/host/index.ts

@@ -0,0 +1,135 @@
+/**
+ * `startMu` — generic host bootstrap. Loads a config, builds the plugin
+ * registry with the new side-channel registries (providers/channels/sessions/
+ * activity/agents), activates plugins (config first then code-passed), starts
+ * channels, and returns a handle for shutdown.
+ *
+ * Designed for non-coding hosts (Arya etc.). mu-coding currently keeps its
+ * own bootstrap (Ink TUI lifecycle) and may migrate to this entry point in a
+ * later iteration.
+ */
+
+import type { ActivityBus } from '../activity';
+import { createActivityBus } from '../activity';
+import type { ChannelRegistry } from '../channel';
+import { createChannelRegistry } from '../channel';
+import type { Plugin } from '../plugin';
+import type { ProviderRegistry } from '../provider/registry';
+import { createProviderRegistry } from '../provider/registry';
+import { PluginRegistry } from '../registry';
+import type { SessionManager } from '../session';
+import { createSessionManager } from '../session';
+import type { ProviderConfig } from '../types/llm';
+
+export interface MuConfigShape {
+  cwd?: string;
+  baseUrl?: string;
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  streamTimeoutMs?: number;
+  systemPrompt?: string;
+  plugins?: Array<string | { name: string; config?: Record<string, unknown> }>;
+}
+
+export interface StartMuOptions {
+  configPath?: string;
+  /** In-memory config — takes precedence over `configPath` when provided. */
+  config?: MuConfigShape;
+  /** Plugins passed in code (activated after config-listed plugins). */
+  plugins?: Plugin[];
+  /** Cwd default (overrides config.cwd if set). */
+  cwd?: string;
+  /**
+   * Resolves a `config.plugins` entry to a Plugin instance. Hosts (mu-coding,
+   * Arya) plug their own loader here — typically supports `npm:<name>`
+   * specifiers, absolute paths, etc. When omitted, config.plugins is ignored.
+   */
+  resolvePlugin?: (entry: string | { name: string; config?: Record<string, unknown> }) => Promise<Plugin | null>;
+}
+
+export interface MuHandle {
+  registry: PluginRegistry;
+  sessions: SessionManager;
+  channels: ChannelRegistry;
+  activity: ActivityBus;
+  providers: ProviderRegistry;
+  shutdown: () => Promise<void>;
+}
+
+async function loadConfig(opts: StartMuOptions): Promise<MuConfigShape> {
+  if (opts.config) return opts.config;
+  if (!opts.configPath) return {};
+  const { readFileSync, existsSync } = await import('node:fs');
+  if (!existsSync(opts.configPath)) return {};
+  const text = readFileSync(opts.configPath, 'utf8');
+  return JSON.parse(text) as MuConfigShape;
+}
+
+export async function startMu(options: StartMuOptions = {}): Promise<MuHandle> {
+  const cfg = await loadConfig(options);
+  const cwd = options.cwd ?? cfg.cwd ?? process.cwd();
+
+  const providers = createProviderRegistry();
+  const channels = createChannelRegistry();
+  const activity = createActivityBus();
+
+  const providerConfig: ProviderConfig = {
+    baseUrl: cfg.baseUrl ?? 'http://localhost:11434/v1',
+    model: cfg.model,
+    maxTokens: cfg.maxTokens ?? 4096,
+    temperature: cfg.temperature ?? 0.7,
+    streamTimeoutMs: cfg.streamTimeoutMs ?? 60_000,
+    systemPrompt: cfg.systemPrompt,
+  };
+
+  // Build a placeholder for sessions injected after construction (circular:
+  // SessionManager needs the registry, plugins want to see SessionManager).
+  let sessions: SessionManager | null = null;
+  const sessionsProxy: SessionManager = new Proxy({} as SessionManager, {
+    get(_t, prop) {
+      if (!sessions) throw new Error('SessionManager not yet initialised');
+      return (sessions as unknown as Record<string | symbol, unknown>)[prop as string];
+    },
+  });
+
+  const registry = new PluginRegistry({
+    cwd,
+    config: {},
+    providers,
+    channels,
+    activity,
+    sessions: sessionsProxy,
+  });
+
+  sessions = createSessionManager({ registry, config: providerConfig, model: cfg.model ?? 'unknown' });
+
+  // Activate config-listed plugins via the host's resolver. mu-coding wires
+  // its npm:/path loader; minimal hosts may omit and pass plugins in code.
+  if (options.resolvePlugin && cfg.plugins) {
+    for (const entry of cfg.plugins) {
+      const plugin = await options.resolvePlugin(entry);
+      if (plugin) await registry.register(plugin);
+    }
+  }
+  // Activate code-passed plugins after config-listed ones (so code overrides
+  // config-driven hooks compose-wise).
+  for (const plugin of options.plugins ?? []) {
+    await registry.register(plugin);
+  }
+
+  await channels.startAll();
+
+  const sm = sessions;
+  return {
+    registry,
+    sessions: sm,
+    channels,
+    activity,
+    providers,
+    async shutdown() {
+      await channels.stopAll();
+      for (const s of sm.list()) s.abort();
+    },
+  };
+}

package/src/host/startMu.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'bun:test';
+import type { Plugin } from '../plugin';
+import { startMu } from './index';
+
+function makePlugin(name: string, marks: string[]): Plugin {
+  return {
+    name,
+    activate() {
+      marks.push(`activate:${name}`);
+    },
+  };
+}
+
+describe('startMu', () => {
+  it('activates code-passed plugins in order', async () => {
+    const marks: string[] = [];
+    const handle = await startMu({
+      plugins: [makePlugin('a', marks), makePlugin('b', marks)],
+    });
+    expect(marks).toEqual(['activate:a', 'activate:b']);
+    await handle.shutdown();
+  });
+
+  it('exposes provider/channel/activity/sessions registries', async () => {
+    const handle = await startMu({});
+    expect(handle.providers.list()).toEqual([]);
+    expect(handle.channels.list()).toEqual([]);
+    expect(handle.sessions.list()).toEqual([]);
+    expect(typeof handle.activity.emit).toBe('function');
+    await handle.shutdown();
+  });
+
+  it('config-listed plugins are activated before code-passed', async () => {
+    const marks: string[] = [];
+    const cfgPlugin = makePlugin('cfg', marks);
+    const codePlugin = makePlugin('code', marks);
+    const handle = await startMu({
+      config: { plugins: ['cfg'] },
+      plugins: [codePlugin],
+      resolvePlugin: async (entry) => (typeof entry === 'string' && entry === 'cfg' ? cfgPlugin : null),
+    });
+    expect(marks).toEqual(['activate:cfg', 'activate:code']);
+    await handle.shutdown();
+  });
+
+  it('starts all registered channels', async () => {
+    const startMarks: string[] = [];
+    const handle = await startMu({
+      plugins: [
+        {
+          name: 'chan-plugin',
+          activate(ctx) {
+            ctx.channels?.register({
+              id: 'test',
+              async start() {
+                startMarks.push('started');
+              },
+            });
+          },
+        },
+      ],
+    });
+    expect(startMarks).toEqual(['started']);
+    await handle.shutdown();
+  });
+});

package/src/index.ts

@@ -0,0 +1,73 @@
+export type { ActivityBus, ActivityEvent, ActivityKind, SubAgentEvent, SubAgentEventKind } from './activity';
+export { createActivityBus } from './activity';
+export { runAgent } from './agent';
+export type { Channel, ChannelRegistry, ChannelResponder, InboundKind, InboundMessage, ResponseMode } from './channel';
+export { createChannelRegistry } from './channel';
+export { runTransformUserInputHooks } from './hooks';
+export type { MuConfigShape, MuHandle, StartMuOptions } from './host/index';
+export { startMu } from './host/index';
+export type {
+  AgentEndReason,
+  AgentEvent,
+  AgentLoopStrategy,
+  AgentSourceRegistry,
+  BeforeToolExecResult,
+  CommandContext,
+  LifecycleHooks,
+  MentionCompletion,
+  MentionProvider,
+  MessageBus,
+  MessageRenderer,
+  Plugin,
+  PluginContext,
+  PluginExtras,
+  PluginRegistryView,
+  PluginTool,
+  PluginToolPermission,
+  ShortcutHandler,
+  SlashCommand,
+  StatusSegment,
+  ToolBlock,
+  ToolDisplayHint,
+  ToolExecutor,
+  ToolExecutorResult,
+  ToolResult,
+  TurnResult,
+  UserInputTransform,
+} from './plugin';
+export type {
+  ChatRequestInput,
+  ModelsRequestInput,
+  ParsedChatEvent,
+  Provider,
+  ProviderAdapter,
+  RequestSpec,
+} from './provider/adapter';
+export { createProvider } from './provider/adapter';
+export type { ProviderRegistry } from './provider/registry';
+export { createProviderRegistry } from './provider/registry';
+export { fetchWithIdleTimeout, readNDJSON, readSSE } from './provider/transport';
+export { PluginRegistry, type PluginRegistryOptions } from './registry';
+export type {
+  CreateSessionManagerOptions,
+  RunTurnOptions,
+  Session,
+  SessionEvent,
+  SessionInit,
+  SessionManager,
+} from './session';
+export { createSessionManager } from './session';
+export type {
+  ApiModel,
+  ChatMessage,
+  ImageAttachment,
+  MessageDisplay,
+  ProviderConfig,
+  StreamChunk,
+  StreamOptions,
+  ToolCall,
+  ToolDefinition,
+  ToolResultInfo,
+  Usage,
+} from './types/llm';
+export { ConsoleUIService, type UINotifyLevel, type UIService } from './ui';

package/src/plugin.ts

@@ -0,0 +1,337 @@
+import type { ActivityBus } from './activity';
+import type { ChannelRegistry } from './channel';
+import type { ProviderRegistry } from './provider/registry';
+import type { SessionManager } from './session';
+import type { ChatMessage, ProviderConfig, ToolCall, ToolDefinition } from './types/llm';
+
+/** Source of agent definitions on disk; implemented by mu-agents. */
+export interface AgentSourceRegistry {
+  registerSource: (absoluteDirPath: string) => () => void;
+}
+
+import type { UIService } from './ui';
+
+/**
+ * MessageBus lets plugins inject synthetic messages into the live chat
+ * transcript without participating in the LLM streaming loop.
+ *
+ *   - `append(msg)` pushes a message into the **on-screen** transcript right
+ *     now. The host preserves it across subsequent agent `messages` events
+ *     when the message looks plugin-synthetic (carries `customType`, `meta`,
+ *     or `display.hidden`). The LLM does NOT see appended entries — it only
+ *     sees what was sent in the most recent turn. Use for banners / status
+ *     entries that should persist in the UI but not influence the model.
+ *   - `injectNext(msg)` queues a message that's spliced in alongside the
+ *     *next* user turn. The message reaches the LLM and is persisted with
+ *     the rest of the transcript. Use for "system reminder" injections that
+ *     should travel with the user's next message.
+ *   - `subscribe(fn)` notifies on any transcript change. The listener fires
+ *     once on subscribe with the current snapshot.
+ */
+export interface MessageBus {
+  append: (message: ChatMessage) => void;
+  injectNext: (message: ChatMessage) => void;
+  drainNext: () => ChatMessage[];
+  subscribe: (listener: (messages: ChatMessage[]) => void) => () => void;
+  get: () => ChatMessage[];
+}
+
+/**
+ * Renderer signature used by `registerMessageRenderer`. The host calls
+ * `render(message)` whenever it encounters a message whose `customType`
+ * matches the registered key. The return value is renderer-defined — for the
+ * mu-coding host, it is a React element; renderer-agnostic hosts may use a
+ * different shape.
+ */
+export type MessageRenderer = (message: ChatMessage) => unknown;
+
+/**
+ * Handler for plugin-registered keyboard shortcuts. Registering a handler
+ * always consumes the key for that frame — the default editor binding is
+ * skipped. Async handlers fire-and-forget; the input loop does not await.
+ */
+export type ShortcutHandler = () => void | Promise<void>;
+
+export interface MentionCompletion {
+  /** Value inserted into the input (replaces `@partial`). */
+  value: string;
+  /** Display label in the picker. Defaults to `value`. */
+  label?: string;
+  /** Secondary text shown dimly in the picker. */
+  description?: string;
+}
+
+export type MentionProvider = (partial: string) => MentionCompletion[] | Promise<MentionCompletion[]>;
+
+/**
+ * Side-channel registries the host exposes to plugins. None are guaranteed —
+ * plugins should null-check before calling so they degrade gracefully on
+ * non-TUI hosts (single-shot CLI, tests).
+ */
+export interface PluginExtras {
+  /** Inject / observe synthetic chat messages. */
+  messages?: MessageBus;
+  /** Register a custom renderer for `ChatMessage.customType`. */
+  registerMessageRenderer?: (customType: string, renderer: MessageRenderer) => () => void;
+  /**
+   * Claim a key combo. The id mirrors the input handler's internal key ids
+   * (`tab`, `escape`, `ctrl+t`, ...). Returns an unregister fn.
+   */
+  registerShortcut?: (key: string, handler: ShortcutHandler) => () => void;
+  /**
+   * Provide @mention completions. Trigger char defaults to `@`. Returning an
+   * empty array hides the picker for that prefix.
+   */
+  registerMentionProvider?: (trigger: string, provider: MentionProvider) => () => void;
+}
+
+/**
+ * Read-only registry surface exposed to plugins via `PluginContext.registry`.
+ * Lets a plugin enumerate tools or hand them off to a nested run (e.g. a
+ * subagent loop) without circular type imports.
+ */
+export interface PluginRegistryView {
+  getTools: () => PluginTool[];
+  getFilteredTools: () => Promise<PluginTool[]>;
+  getHooks: () => LifecycleHooks[];
+  getSystemPrompts: () => Promise<string[]>;
+  applySystemPromptTransforms: (prompt: string) => Promise<string>;
+}
+
+export interface PluginContext extends PluginExtras {
+  cwd: string;
+  config: Record<string, unknown>;
+  /**
+   * Host-provided UI service. Available when the host (e.g. mu-coding) supplies
+   * one; otherwise plugins should fall back to a no-op or `ConsoleUIService`.
+   */
+  ui?: UIService;
+  getPlugin?: <T extends Plugin>(name: string) => T | undefined;
+  /**
+   * Read-only handle to the live registry. Plugins use this for advanced
+   * scenarios — e.g. running subagent loops via `runAgent` over a custom
+   * tool subset. Most plugins should rely on hooks + their own `tools`
+   * field instead.
+   */
+  registry?: PluginRegistryView;
+  /**
+   * Push status segments for this plugin into the registry. Replaces the older
+   * polling-based `Plugin.statusLine()` getter. Pass `[]` to clear.
+   */
+  setStatusLine?: (segments: StatusSegment[]) => void;
+  /**
+   * Host-provided graceful shutdown hook. When supplied, plugins should prefer
+   * this over `process.exit(...)` so the host can deactivate plugins and restore
+   * terminal state.
+   */
+  shutdown?: (code?: number) => Promise<void> | void;
+  /** LLM provider registry. Plugins implementing providers register here. */
+  providers?: ProviderRegistry;
+  /** Channel registry — input surfaces (TUI, Telegram, websocket, ...). */
+  channels?: ChannelRegistry;
+  /** Session manager — owns conversation state per `sessionId`. */
+  sessions?: SessionManager;
+  /** Activity bus — pub/sub for agent + tool events (timeline, broadcast). */
+  activity?: ActivityBus;
+  /** Agent source registry (file-based agent definitions). */
+  agents?: AgentSourceRegistry;
+  /**
+   * Plugins that *implement* an `AgentSourceRegistry` (i.e. mu-agents)
+   * publish it here so subsequent plugins (mu-coding-agents, user packages)
+   * see it in their own `ctx.agents`. The registry mutates the registry's
+   * shared context so every following `register()` propagates the value.
+   */
+  setAgentsRegistry?: (registry: AgentSourceRegistry) => void;
+}
+
+/**
+ * What a tool's `execute` may return:
+ *  - a plain string (legacy / convenience): an error is heuristically inferred
+ *    when the string starts with `"Error:"`. Convenient for quick tools but
+ *    fragile (collisions with legitimate output that begins with that prefix).
+ *  - a `ToolExecutorResult`: explicit `error` flag, no heuristics. Preferred
+ *    for new tools and for any tool whose output may legitimately start with
+ *    "Error:".
+ *
+ * The agent runtime accepts both forms; the registry doesn't care.
+ */
+export interface ToolExecutorResult {
+  content: string;
+  error?: boolean;
+}
+
+export type ToolExecutor = (
+  args: Record<string, unknown>,
+  signal?: AbortSignal,
+) => Promise<string | ToolExecutorResult> | string | ToolExecutorResult;
+
+/**
+ * Optional rendering hints the host can use when displaying a tool call.
+ * The host (e.g. mu-coding's TUI) maps `kind` to a renderer; tools without a
+ * `display` hint fall back to a generic preview.
+ *
+ * Kept renderer-agnostic on purpose — `mu-agents` has no React / Ink dependency.
+ */
+export interface ToolDisplayHint {
+  /** Verb shown in the spinner line, e.g. "reading", "editing". */
+  verb?: string;
+  /** Renderer kind. Hosts decide how to render each kind. Built-ins use
+   *  'file-read' | 'file-write' | 'diff' | 'shell'. */
+  kind?: string;
+  /** Semantic field mapping from rendering concepts to actual JSON arg names.
+   *  Examples: { path: 'path' }, { from: 'from', to: 'to' }. */
+  fields?: Record<string, string>;
+}
+
+/**
+ * Permission descriptor. `matchKey` extracts the value to glob-match from
+ * call args (e.g. `cmd` for bash, `path` for file tools). Tools without a
+ * `matchKey` may only be configured with simple actions (`allow|deny|ask`).
+ *
+ * Validated at agent-definition load time by `mu-agents`.
+ */
+export interface PluginToolPermission {
+  matchKey?: (args: Record<string, unknown>) => string | undefined;
+}
+
+export interface PluginTool {
+  definition: ToolDefinition;
+  execute: ToolExecutor;
+  display?: ToolDisplayHint;
+  permission?: PluginToolPermission;
+}
+
+export interface ToolResult {
+  tool_call_id: string;
+  name: string;
+  content: string;
+  error?: boolean;
+}
+
+export interface TurnResult {
+  content: string;
+  reasoning: string;
+  toolCalls: ToolCall[];
+  usage: number;
+  /** Subset of prompt tokens served from the server's prompt cache, when
+   *  reported. 0 when unsupported or no cache hit. */
+  cachedPromptTokens?: number;
+}
+
+export type AgentEndReason = 'complete' | 'aborted';
+
+/**
+ * Result a `beforeToolExec` hook may return. Either:
+ *   - a `ToolCall` (possibly mutated) — execution proceeds normally
+ *   - a `ToolBlock` — the host short-circuits execution and uses the
+ *     supplied content as the tool result (rendered as if the tool ran).
+ *     Lets policy plugins reject calls without throwing.
+ */
+export interface ToolBlock {
+  blocked: true;
+  content: string;
+  error?: boolean;
+}
+
+export type BeforeToolExecResult = ToolCall | ToolBlock;
+
+/**
+ * Result a `transformUserInput` hook may return.
+ *   - `pass` (or `undefined`)  — leave the user's text untouched
+ *   - `transform` — replace the text but still send it as a user message
+ *   - `intercept` — suppress the input entirely; the host should not call the
+ *     LLM. Plugins typically pair this with `MessageBus.append` to surface a
+ *     reply or status entry.
+ */
+export type UserInputTransform = { kind: 'pass' } | { kind: 'transform'; text: string } | { kind: 'intercept' };
+
+export interface LifecycleHooks {
+  beforeLlmCall?: (messages: ChatMessage[], config: ProviderConfig) => ChatMessage[] | Promise<ChatMessage[]>;
+  afterLlmCall?: (result: TurnResult) => TurnResult | Promise<TurnResult>;
+  beforeToolExec?: (toolCall: ToolCall) => BeforeToolExecResult | Promise<BeforeToolExecResult>;
+  afterToolExec?: (toolCall: ToolCall, result: string) => string | Promise<string>;
+  /**
+   * Restrict the tool set the LLM can see for the next turn. Plugins return
+   * the subset of tools they want exposed. Multiple plugins compose by
+   * intersection — each hook narrows the previous result.
+   */
+  filterTools?: (tools: PluginTool[]) => PluginTool[] | Promise<PluginTool[]>;
+  /**
+   * Mutate the merged system prompt right before it goes to the provider.
+   * Composes left-to-right; later plugins see the prior plugin's output.
+   * Useful for per-agent prompt wrapping.
+   */
+  transformSystemPrompt?: (prompt: string) => string | Promise<string>;
+  /**
+   * Inspect / transform / intercept user input on submit. Composes by
+   * threading the current text through each plugin; an `intercept` short-
+   * circuits and stops the chain. Hosts call this before constructing the
+   * user `ChatMessage`.
+   */
+  transformUserInput?: (text: string) => UserInputTransform | Promise<UserInputTransform>;
+  /**
+   * Fires once per `runAgent` invocation, after the loop exits — whether the
+   * agent finished normally (LLM produced a final response with no tool calls)
+   * or was aborted via the signal. Plugins should use this for end-of-agent
+   * cleanup; per-turn cleanup belongs in `afterLlmCall`.
+   */
+  afterAgentRun?: (reason: AgentEndReason) => void | Promise<void>;
+}
+
+export interface CommandContext {
+  messages: ChatMessage[];
+  cwd: string;
+  config: ProviderConfig;
+}
+
+export interface SlashCommand {
+  name: string;
+  description: string;
+  execute: (args: string, context: CommandContext) => Promise<string | undefined>;
+}
+
+export type AgentEvent =
+  | { type: 'content'; text: string }
+  | { type: 'reasoning'; text: string }
+  | { type: 'usage'; totalTokens: number; cachedTokens?: number }
+  | { type: 'messages'; messages: ChatMessage[] }
+  | { type: 'turn_end' };
+
+export interface AgentLoopStrategy {
+  name: string;
+  run: (
+    messages: ChatMessage[],
+    config: ProviderConfig,
+    model: string,
+    signal: AbortSignal,
+    tools: PluginTool[],
+    hooks: LifecycleHooks[],
+  ) => AsyncGenerator<AgentEvent>;
+}
+
+export interface StatusSegment {
+  text: string;
+  color?: string;
+  dim?: boolean;
+}
+
+export interface Plugin {
+  name: string;
+  version?: string;
+
+  tools?: PluginTool[];
+  systemPrompt?: string | ((context: PluginContext) => string | Promise<string>);
+  hooks?: LifecycleHooks;
+  commands?: SlashCommand[];
+  agentLoop?: AgentLoopStrategy;
+
+  activate?: (context: PluginContext) => Promise<void> | void;
+  deactivate?: () => Promise<void> | void;
+
+  /**
+   * Plugins may attach arbitrary public fields (e.g. an ApprovalGateway
+   * instance, a SourceManager). Sibling plugins fetch them via
+   * `ctx.getPlugin<MyPlugin>('name')` and dot into typed fields.
+   */
+  [extra: string]: unknown;
+}