mu-core 0.8.0

package/README.md

@@ -0,0 +1,110 @@
+# 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/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mu-core",
+  "version": "0.8.0",
+  "description": "Agent loop orchestration core: types, plugin SDK, channels, sessions",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/activity.test.ts

@@ -0,0 +1,44 @@
+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

@@ -0,0 +1,83 @@
+/**
+ * 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/agent.ts

@@ -0,0 +1,238 @@
+import {
+  runAfterAgentRunHooks,
+  runAfterLlmHooks,
+  runAfterToolExecHook,
+  runBeforeLlmHooks,
+  runBeforeToolExecHook,
+} from './hooks';
+import type { AgentEvent, PluginTool, ToolResult, TurnResult } from './plugin';
+import type { PluginRegistry } from './registry';
+import type { ChatMessage, ProviderConfig, StreamChunk, StreamOptions, ToolCall } from './types/llm';
+
+const DEFAULT_PROVIDER_ID = 'openai';
+
+/**
+ * Stream a chat completion through the host's provider registry. Resolved
+ * by `config.providerId` (default `'openai'`). When no provider matches, we
+ * throw — `mu-core` is provider-agnostic, the host is responsible for
+ * registering at least one (e.g. via `mu-openai-provider`).
+ */
+function streamChatViaRegistry(
+  registry: PluginRegistry,
+  messages: ChatMessage[],
+  config: ProviderConfig,
+  model: string,
+  options: StreamOptions,
+): AsyncIterable<StreamChunk> {
+  const id = config.providerId ?? DEFAULT_PROVIDER_ID;
+  const providers = registry.getProviders();
+  const provider = providers?.get(id);
+  if (!provider) {
+    throw new Error(
+      `No provider registered for id "${id}". Register one (e.g. via mu-openai-provider) before calling runAgent.`,
+    );
+  }
+  return provider.streamChat(messages, config, model, options);
+}
+
+async function executeTool(call: ToolCall, tools: PluginTool[], signal?: AbortSignal): Promise<ToolResult> {
+  let args: Record<string, unknown>;
+  try {
+    args = JSON.parse(call.function.arguments);
+  } catch {
+    return { tool_call_id: call.id, name: call.function.name, content: 'Error: Invalid JSON arguments', error: true };
+  }
+
+  const tool = tools.find((t) => t.definition.function.name === call.function.name);
+  if (!tool) {
+    return {
+      tool_call_id: call.id,
+      name: call.function.name,
+      content: `Error: Unknown tool: ${call.function.name}`,
+      error: true,
+    };
+  }
+
+  try {
+    const result = await tool.execute(args, signal);
+    // Tools may return either a plain string (error inferred from "Error:"
+    // prefix — legacy/convenience form) or a typed `{ content, error }`
+    // object that makes the error flag explicit. Both forms are accepted to
+    // avoid breaking existing plugin authors.
+    if (typeof result === 'string') {
+      return { tool_call_id: call.id, name: call.function.name, content: result, error: result.startsWith('Error:') };
+    }
+    return {
+      tool_call_id: call.id,
+      name: call.function.name,
+      content: result.content,
+      error: result.error ?? false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'Unknown error';
+    return { tool_call_id: call.id, name: call.function.name, content: `Error: ${msg}`, error: true };
+  }
+}
+
+async function* streamTurn(
+  messages: ChatMessage[],
+  config: ProviderConfig,
+  model: string,
+  signal: AbortSignal,
+  registry: PluginRegistry,
+  toolDefs: PluginTool[],
+): AsyncGenerator<AgentEvent, TurnResult> {
+  let content = '';
+  let reasoning = '';
+  let usage = 0;
+  let cachedPromptTokens = 0;
+  const toolCalls: ToolCall[] = [];
+
+  const hooks = registry.getHooks();
+  const hookedMessages = await runBeforeLlmHooks(hooks, messages, config);
+  const toolDefinitions = toolDefs.map((t) => t.definition);
+
+  for await (const chunk of streamChatViaRegistry(registry, hookedMessages, config, model, {
+    signal,
+    tools: toolDefinitions,
+    onUsage: (u) => {
+      usage = u.totalTokens;
+      cachedPromptTokens = u.cachedPromptTokens ?? 0;
+    },
+  })) {
+    if (signal.aborted) {
+      break;
+    }
+    if (chunk.type === 'reasoning') {
+      reasoning += chunk.text;
+      yield { type: 'reasoning', text: reasoning };
+    } else if (chunk.type === 'content') {
+      content += chunk.text;
+      yield { type: 'content', text: content };
+    } else if (chunk.type === 'tool_call') {
+      toolCalls.push({ id: chunk.toolCall.id, function: chunk.toolCall.function });
+    }
+  }
+
+  const result: TurnResult = { content, reasoning, toolCalls, usage, cachedPromptTokens };
+  return await runAfterLlmHooks(hooks, result);
+}
+
+async function executeOneToolCall(
+  tc: ToolCall,
+  tools: PluginTool[],
+  signal: AbortSignal,
+  registry: PluginRegistry,
+): Promise<ChatMessage> {
+  const hooks = registry.getHooks();
+  const hookOutcome = await runBeforeToolExecHook(hooks, tc);
+
+  if ('blocked' in hookOutcome) {
+    const content = await runAfterToolExecHook(hooks, tc, hookOutcome.content);
+    return {
+      role: 'tool',
+      content,
+      toolCallId: tc.id,
+      toolResult: { name: tc.function.name, content, error: hookOutcome.error ?? true },
+      toolCallArgs: { [tc.function.name]: tc.function.arguments },
+    };
+  }
+
+  const result = await executeTool(hookOutcome, tools, signal);
+  const content = await runAfterToolExecHook(hooks, hookOutcome, result.content);
+  return {
+    role: 'tool',
+    content,
+    toolCallId: result.tool_call_id,
+    toolResult: { name: result.name, content, error: result.error },
+    toolCallArgs: { [result.name]: tc.function.arguments },
+  };
+}
+
+async function* executeToolCalls(
+  calls: ToolCall[],
+  start: ChatMessage[],
+  signal: AbortSignal,
+  registry: PluginRegistry,
+  tools: PluginTool[],
+): AsyncGenerator<AgentEvent, ChatMessage[]> {
+  let current = start;
+
+  for (const tc of calls) {
+    if (signal.aborted) break;
+    const toolMessage = await executeOneToolCall(tc, tools, signal, registry);
+    if (signal.aborted) break;
+    current = [...current, toolMessage];
+    yield { type: 'messages', messages: current };
+  }
+  return current;
+}
+
+async function buildMergedConfig(config: ProviderConfig, registry: PluginRegistry): Promise<ProviderConfig> {
+  const pluginPrompts = await registry.getSystemPrompts();
+  const merged = [config.systemPrompt, ...pluginPrompts].filter(Boolean).join('\n\n');
+  const transformed = await registry.applySystemPromptTransforms(merged);
+  if (!transformed) return config;
+  return { ...config, systemPrompt: transformed };
+}
+
+export async function* runAgent(
+  initialMessages: ChatMessage[],
+  config: ProviderConfig,
+  model: string,
+  signal: AbortSignal,
+  registry: PluginRegistry,
+): AsyncGenerator<AgentEvent> {
+  const mergedConfig = await buildMergedConfig(config, registry);
+  const hooks = registry.getHooks();
+
+  // Wrap the body in try/finally so `afterAgentRun` fires exactly once per
+  // `runAgent` call, regardless of how it terminates: normal completion (LLM
+  // produced a final response), abort via `signal.aborted`, or generator
+  // cancellation by the consumer (Ink unmount, manual `.return()`).
+  try {
+    const customLoop = registry.getAgentLoop();
+    if (customLoop) {
+      const filtered = await registry.getFilteredTools();
+      yield* customLoop.run(initialMessages, mergedConfig, model, signal, filtered, hooks);
+      return;
+    }
+
+    let current = initialMessages;
+
+    while (!signal.aborted) {
+      // Re-evaluate every turn so per-turn agent switches are honoured.
+      const tools = await registry.getFilteredTools();
+      const { content, reasoning, toolCalls, usage, cachedPromptTokens } = yield* streamTurn(
+        current,
+        mergedConfig,
+        model,
+        signal,
+        registry,
+        tools,
+      );
+
+      if (usage > 0) {
+        yield { type: 'usage', totalTokens: usage, cachedTokens: cachedPromptTokens };
+      }
+      if (signal.aborted) {
+        break;
+      }
+
+      const reasoningField = reasoning || undefined;
+      const assistant: ChatMessage = { role: 'assistant', content, reasoning: reasoningField };
+      if (toolCalls.length === 0) {
+        current = [...current, assistant];
+        yield { type: 'messages', messages: current };
+        return;
+      }
+
+      current = [...current, { ...assistant, toolCalls }];
+      yield { type: 'messages', messages: current };
+      current = yield* executeToolCalls(toolCalls, current, signal, registry, tools);
+      yield { type: 'turn_end' };
+    }
+  } finally {
+    await runAfterAgentRunHooks(hooks, signal.aborted ? 'aborted' : 'complete');
+  }
+}

package/src/channel.test.ts

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,77 @@
+/**
+ * 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

@@ -0,0 +1,76 @@
+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);
+  });
+});