mu-core 0.13.0 → 0.16.1

package/README.md

@@ -1,110 +0,0 @@
-# mu-core
-
-The mu plugin SDK. Provides the agent loop, plugin registry, LLM types, and
-the multi-host primitives (channels, sessions, activity bus, providers).
-Provider implementations are separate packages — for OpenAI-compatible APIs,
-add `mu-openai-provider` and register its plugin alongside.
-
-## Install
-
-```bash
-npm install mu-core mu-openai-provider
-```
-
-## Usage
-
-```ts
-import { runAgent, PluginRegistry } from "mu-core";
-import type { ChatMessage, ProviderConfig } from "mu-core";
-import { createOpenAIProviderPlugin } from "mu-openai-provider";
-
-const config: ProviderConfig = {
-  baseUrl: "http://localhost:11434/v1",
-  maxTokens: 4096,
-  temperature: 0.7,
-  streamTimeoutMs: 30000,
-  // providerId defaults to 'openai' — register at least one provider
-  // implementation (e.g. via createOpenAIProviderPlugin) before running.
-};
-
-const registry = new PluginRegistry({ cwd: process.cwd(), config: {} });
-await registry.register(createOpenAIProviderPlugin());
-
-const messages: ChatMessage[] = [
-  { role: "user", content: "Hello" },
-];
-
-const controller = new AbortController();
-
-for await (const event of runAgent(messages, config, "qwen2.5", controller.signal, registry)) {
-  if (event.type === "content") process.stdout.write(event.text);
-}
-```
-
-For a higher-level API that owns conversation state, channel I/O, and
-multi-session lifecycle, see `startMu` and `Session` (`createSessionManager`).
-
-## Plugin System
-
-Plugins can provide tools, system prompts, lifecycle hooks, slash commands,
-custom agent loops, and side-channel registries (channels, providers,
-activity bus, agent sources).
-
-```ts
-import type { Plugin } from "mu-core";
-
-const myPlugin: Plugin = {
-  name: "my-plugin",
-  tools: [
-    {
-      definition: {
-        type: "function",
-        function: {
-          name: "hello",
-          description: "Say hello",
-          parameters: { type: "object", properties: {} },
-        },
-      },
-      execute: async () => "Hello, world!",
-    },
-  ],
-  hooks: {
-    beforeLlmCall: (messages, config) => messages,
-    afterLlmCall: (result) => result,
-    beforeToolExec: (toolCall) => toolCall,
-    afterToolExec: (toolCall, result) => result,
-  },
-};
-
-await registry.register(myPlugin);
-```
-
-Filesystem and shell tools live in `mu-coding` (`createCodingToolsPlugin`),
-not in mu-core — keeps the SDK host-agnostic.
-
-## API
-
-### Agent loop
-- `runAgent(messages, config, model, signal, registry)` — async generator yielding `AgentEvent` (`content`, `reasoning`, `messages`, `usage`, `turn_end`).
-- Provider resolution: looks up `config.providerId ?? 'openai'` in the registered `ProviderRegistry`. Throws if no provider is registered.
-
-### Sessions
-- `createSessionManager({ registry, config, model })` returns a `SessionManager`.
-- `session.runTurn({ userMessage, ... })` — appends, drains queue, runs agent loop, emits events.
-- `session.subscribe(listener)` — `messages_changed`, `stream_partial`, `stream_started`, `stream_ended`, `usage`, `error`.
-
-### Channels
-- `Channel` interface (`id`, `start`, `stop`) — input surfaces (TUI, Telegram, websocket).
-- `createChannelRegistry()` — host-managed registry; `startAll()` / `stopAll()` for lifecycle.
-
-### Providers
-- `ProviderAdapter` + `createProvider(adapter)` — build a `Provider` from raw HTTP semantics.
-- `readSSE`, `readNDJSON`, `fetchWithIdleTimeout` — transport primitives.
-- `ProviderRegistry` — host-managed; populated by provider plugins.
-
-### Host
-- `startMu(options)` — generic bootstrap: loads config, builds registries, activates plugins (config-listed via `options.resolvePlugin`, then code-passed), starts channels.
-
-## License
-
-MIT

package/src/activity.test.ts

@@ -1,44 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { createActivityBus } from './activity';
-
-describe('ActivityBus', () => {
-  it('emits events to multiple subscribers', () => {
-    const bus = createActivityBus();
-    const a: string[] = [];
-    const b: string[] = [];
-    bus.subscribe((e) => a.push(e.summary));
-    bus.subscribe((e) => b.push(e.summary));
-    bus.emit('tool_start', 'bash', 'running git status');
-    expect(a).toEqual(['running git status']);
-    expect(b).toEqual(['running git status']);
-  });
-
-  it('unsubscribes', () => {
-    const bus = createActivityBus();
-    const seen: string[] = [];
-    const off = bus.subscribe((e) => seen.push(e.summary));
-    bus.emit('tool_start', 'bash', 'first');
-    off();
-    bus.emit('tool_start', 'bash', 'second');
-    expect(seen).toEqual(['first']);
-  });
-
-  it('subagent stream is independent', () => {
-    const bus = createActivityBus();
-    const sub: string[] = [];
-    bus.subscribeSubAgent((e) => sub.push(e.kind));
-    bus.emitSubAgent({ runId: 'r1', agentId: 'review', kind: 'invocation_start', ts: 1, data: {} });
-    expect(sub).toEqual(['invocation_start']);
-  });
-
-  it('throwing listener does not break the bus', () => {
-    const bus = createActivityBus();
-    bus.subscribe(() => {
-      throw new Error('boom');
-    });
-    const seen: string[] = [];
-    bus.subscribe((e) => seen.push(e.summary));
-    bus.emit('tool_end', 'bash', 'ok');
-    expect(seen).toEqual(['ok']);
-  });
-});

package/src/activity.ts

@@ -1,83 +0,0 @@
-/**
- * ActivityBus — pub/sub for high-level events emitted by the agent loop and
- * by tools. Hosts subscribe to render timelines (TUI), broadcast to
- * companion websockets, etc. Independent of the session message store —
- * messages_changed is on Session, ActivityBus is for sidebar/observability.
- */
-
-export type ActivityKind =
-  | 'agent_start'
-  | 'agent_end'
-  | 'tool_start'
-  | 'tool_end'
-  | 'task_started'
-  | 'task_completed'
-  | 'task_error';
-
-export interface ActivityEvent {
-  id: number;
-  ts: number;
-  kind: ActivityKind;
-  source: string;
-  summary: string;
-  detail?: Record<string, unknown>;
-}
-
-export type SubAgentEventKind =
-  | 'invocation_start'
-  | 'text_delta'
-  | 'message_end'
-  | 'tool_call_start'
-  | 'tool_call_end'
-  | 'invocation_end';
-
-export interface SubAgentEvent {
-  runId: string;
-  parentRunId?: string;
-  agentId: string;
-  kind: SubAgentEventKind;
-  ts: number;
-  data: Record<string, unknown>;
-}
-
-export interface ActivityBus {
-  subscribe: (fn: (e: ActivityEvent) => void) => () => void;
-  emit: (kind: ActivityKind, source: string, summary: string, detail?: Record<string, unknown>) => void;
-  subscribeSubAgent: (fn: (e: SubAgentEvent) => void) => () => void;
-  emitSubAgent: (e: SubAgentEvent) => void;
-}
-
-export function createActivityBus(): ActivityBus {
-  let nextId = 1;
-  const listeners = new Set<(e: ActivityEvent) => void>();
-  const subListeners = new Set<(e: SubAgentEvent) => void>();
-  return {
-    subscribe(fn) {
-      listeners.add(fn);
-      return () => listeners.delete(fn);
-    },
-    emit(kind, source, summary, detail) {
-      const event: ActivityEvent = { id: nextId++, ts: Date.now(), kind, source, summary, detail };
-      for (const fn of listeners) {
-        try {
-          fn(event);
-        } catch {
-          // listeners must not break the bus
-        }
-      }
-    },
-    subscribeSubAgent(fn) {
-      subListeners.add(fn);
-      return () => subListeners.delete(fn);
-    },
-    emitSubAgent(e) {
-      for (const fn of subListeners) {
-        try {
-          fn(e);
-        } catch {
-          // ignore
-        }
-      }
-    },
-  };
-}

package/src/channel.test.ts

@@ -1,52 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { type Channel, createChannelRegistry } from './channel';
-
-function makeChannel(id: string, started: { value: boolean }): Channel {
-  return {
-    id,
-    async start() {
-      started.value = true;
-    },
-    async stop() {
-      started.value = false;
-    },
-  };
-}
-
-describe('ChannelRegistry', () => {
-  it('registers, lists, gets', () => {
-    const r = createChannelRegistry();
-    const flag = { value: false };
-    r.register(makeChannel('tui', flag));
-    expect(r.list().map((c) => c.id)).toEqual(['tui']);
-    expect(r.get('tui')?.id).toBe('tui');
-    expect(r.get('missing')).toBeUndefined();
-  });
-
-  it('rejects duplicate id', () => {
-    const r = createChannelRegistry();
-    r.register(makeChannel('a', { value: false }));
-    expect(() => r.register(makeChannel('a', { value: false }))).toThrow();
-  });
-
-  it('startAll / stopAll', async () => {
-    const r = createChannelRegistry();
-    const f1 = { value: false };
-    const f2 = { value: false };
-    r.register(makeChannel('a', f1));
-    r.register(makeChannel('b', f2));
-    await r.startAll();
-    expect(f1.value).toBe(true);
-    expect(f2.value).toBe(true);
-    await r.stopAll();
-    expect(f1.value).toBe(false);
-    expect(f2.value).toBe(false);
-  });
-
-  it('unregister callback removes', () => {
-    const r = createChannelRegistry();
-    const off = r.register(makeChannel('a', { value: false }));
-    off();
-    expect(r.list()).toEqual([]);
-  });
-});

package/src/channel.ts

@@ -1,77 +0,0 @@
-/**
- * Channel — input surface for sessions. A channel converts an external
- * trigger (TUI keystroke, Telegram message, voice transcription, websocket
- * frame) into an `InboundMessage` and forwards it to a `Session`.
- *
- * The abstraction is intentionally tiny: a channel knows how to start, stop,
- * and (optionally) respond. The mu-core host owns lifecycle; channels are
- * registered via `PluginContext.channels?.register(...)`.
- */
-
-export type InboundKind = 'text' | 'audio';
-export type ResponseMode = 'text' | 'voice';
-
-export interface InboundMessage {
-  kind: InboundKind;
-  channelId: string;
-  sessionId: string;
-  messageId?: string;
-  userId?: string;
-  userName?: string;
-  text?: string;
-  responseMode?: ResponseMode;
-  audio?: { url?: string; mimeType?: string; filePath?: string };
-  raw?: unknown;
-}
-
-export interface ChannelResponder {
-  sendText: (text: string) => Promise<void>;
-  sendVoice?: (text: string) => Promise<void>;
-  sendAck?: (text: string) => Promise<void>;
-  sendError?: (text: string) => Promise<void>;
-}
-
-export interface Channel {
-  id: string;
-  start: () => Promise<void>;
-  stop?: () => Promise<void>;
-}
-
-export interface ChannelRegistry {
-  register: (channel: Channel) => () => void;
-  list: () => Channel[];
-  get: (id: string) => Channel | undefined;
-  startAll: () => Promise<void>;
-  stopAll: () => Promise<void>;
-}
-
-export function createChannelRegistry(): ChannelRegistry {
-  const channels = new Map<string, Channel>();
-  return {
-    register(channel) {
-      if (channels.has(channel.id)) {
-        throw new Error(`Channel already registered: ${channel.id}`);
-      }
-      channels.set(channel.id, channel);
-      return () => {
-        channels.delete(channel.id);
-      };
-    },
-    list() {
-      return Array.from(channels.values());
-    },
-    get(id) {
-      return channels.get(id);
-    },
-    async startAll() {
-      for (const c of channels.values()) {
-        await c.start();
-      }
-    },
-    async stopAll() {
-      for (const c of channels.values()) {
-        if (c.stop) await c.stop();
-      }
-    },
-  };
-}

package/src/hooks.test.ts

@@ -1,105 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { runBeforeToolExecHook, runTransformUserInputHooks } from './hooks';
-import type { LifecycleHooks } from './plugin';
-
-const call = { id: '1', function: { name: 'foo', arguments: '{}' } };
-
-describe('runBeforeToolExecHook', () => {
-  it('returns the call unchanged when no hook intervenes', async () => {
-    const result = await runBeforeToolExecHook([], call);
-    expect(result).toEqual(call);
-  });
-
-  it('lets later hooks transform the call', async () => {
-    const hooks: LifecycleHooks[] = [
-      {
-        beforeToolExec: (c) => ({ ...c, function: { ...c.function, name: 'bar' } }),
-      },
-      {
-        beforeToolExec: (c) =>
-          'blocked' in c ? c : { ...c, function: { ...c.function, name: c.function.name.toUpperCase() } },
-      },
-    ];
-    const result = await runBeforeToolExecHook(hooks, call);
-    expect('blocked' in result).toBe(false);
-    if (!('blocked' in result)) {
-      expect(result.function.name).toBe('BAR');
-    }
-  });
-
-  it('short-circuits on first block', async () => {
-    let secondCalled = false;
-    const hooks: LifecycleHooks[] = [
-      { beforeToolExec: () => ({ blocked: true, content: 'denied', error: true }) },
-      {
-        beforeToolExec: (c) => {
-          secondCalled = true;
-          return c;
-        },
-      },
-    ];
-    const result = await runBeforeToolExecHook(hooks, call);
-    expect('blocked' in result && result.content).toBe('denied');
-    expect(secondCalled).toBe(false);
-  });
-});
-
-describe('runTransformUserInputHooks', () => {
-  it('returns pass when no hook intervenes', async () => {
-    expect(await runTransformUserInputHooks([], 'hello')).toEqual({ kind: 'pass' });
-  });
-
-  it('threads transformed text through subsequent hooks', async () => {
-    const hooks: LifecycleHooks[] = [
-      { transformUserInput: (t) => ({ kind: 'transform', text: `[a]${t}` }) },
-      { transformUserInput: (t) => ({ kind: 'transform', text: `${t}[b]` }) },
-    ];
-    const result = await runTransformUserInputHooks(hooks, 'X');
-    expect(result.kind === 'transform' && result.text).toBe('[a]X[b]');
-  });
-
-  it('intercept short-circuits the chain', async () => {
-    let secondCalled = false;
-    const hooks: LifecycleHooks[] = [
-      { transformUserInput: () => ({ kind: 'intercept' }) },
-      {
-        transformUserInput: () => {
-          secondCalled = true;
-          return { kind: 'pass' };
-        },
-      },
-    ];
-    const result = await runTransformUserInputHooks(hooks, 'X');
-    expect(result.kind).toBe('intercept');
-    expect(secondCalled).toBe(false);
-  });
-
-  it('propagates continue to the caller', async () => {
-    // Regression: the composer used to silently drop `continue`, falling
-    // back to `pass`. That made the host re-push the user message on top
-    // of the one a plugin (mu-agents @-mention dispatch) had already
-    // appended, producing a duplicate user bubble in the transcript.
-    const hooks: LifecycleHooks[] = [{ transformUserInput: () => ({ kind: 'continue' }) }];
-    const result = await runTransformUserInputHooks(hooks, 'X');
-    expect(result.kind).toBe('continue');
-  });
-
-  it('continue short-circuits the chain', async () => {
-    // Once a plugin has appended the user message itself, downstream
-    // hooks can't safely transform absent text — same chain-termination
-    // semantics as `intercept`.
-    let secondCalled = false;
-    const hooks: LifecycleHooks[] = [
-      { transformUserInput: () => ({ kind: 'continue' }) },
-      {
-        transformUserInput: () => {
-          secondCalled = true;
-          return { kind: 'transform', text: 'should-not-apply' };
-        },
-      },
-    ];
-    const result = await runTransformUserInputHooks(hooks, 'X');
-    expect(result.kind).toBe('continue');
-    expect(secondCalled).toBe(false);
-  });
-});

package/src/hooks.ts

@@ -1,112 +0,0 @@
-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;
-}
-
-/**
- * Pipe a freshly built `ChatMessage` through every `decorateMessage` hook in
- * order. Each hook may return a (possibly mutated) message; later hooks see
- * the result of the previous one. Used to stamp display hints (agent badge,
- * color) without coupling the host to any specific plugin.
- */
-export async function runDecorateMessageHooks(hooks: LifecycleHooks[], msg: ChatMessage): Promise<ChatMessage> {
-  let current = msg;
-  for (const hook of hooks) {
-    if (hook.decorateMessage) {
-      current = await hook.decorateMessage(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` or `continue` short-circuits the chain
- * — once a plugin has either suppressed the input or appended the user
- * message itself, downstream hooks can't safely keep transforming absent
- * text, and the host needs to see the terminating signal verbatim so it
- * skips its own user-message push (see `useOnSend`).
- */
-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 === 'continue') {
-      return next;
-    }
-    if (next.kind === 'transform') {
-      working = next.text;
-      current = next;
-    }
-  }
-  return current;
-}