mu-core 0.15.0 → 0.16.3

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/agent.test.ts

@@ -1,91 +0,0 @@
-/**
- * Focused tests for `runAgent`. Most coverage lives in higher layers
- * (session, mu-agents subagent, integration) but we keep a few pinpoint
- * cases here to lock down behaviour that's easy to break:
- *
- *  - `display.llmHidden` strips messages from the network payload but
- *    keeps them in the streamed transcript surface (regression target
- *    for the `@`-mention dispatch flow that injects a UI-only subagent
- *    header alongside a real synthetic tool flow).
- */
-import { describe, expect, it } from 'bun:test';
-import { runAgent } from './agent';
-import { createProviderRegistry } from './provider/registry';
-import { PluginRegistry } from './registry';
-import type { ChatMessage, ProviderConfig, StreamChunk } from './types/llm';
-
-interface CapturedCall {
-  messages: ChatMessage[];
-}
-
-function fakeRegistry(captured: CapturedCall[]): PluginRegistry {
-  const providers = createProviderRegistry();
-  providers.register({
-    id: 'openai',
-    async *streamChat(messages: ChatMessage[]): AsyncIterable<StreamChunk> {
-      // Snapshot the exact message list the provider receives so the test
-      // can assert on what `streamTurn` actually sent over the wire.
-      captured.push({ messages: messages.map((m) => ({ ...m })) });
-      yield { type: 'content', text: 'ok' };
-    },
-    async listModels() {
-      return [];
-    },
-  });
-  return new PluginRegistry({ cwd: '/tmp', config: {}, providers });
-}
-
-const CFG: ProviderConfig = { providerId: 'openai' };
-
-describe('runAgent — display.llmHidden filter', () => {
-  it('strips llmHidden messages from the provider payload', async () => {
-    const captured: CapturedCall[] = [];
-    const registry = fakeRegistry(captured);
-
-    const messages: ChatMessage[] = [
-      { role: 'system', content: 'sys' },
-      // UI-only marker — must be filtered before the network call.
-      {
-        role: 'assistant',
-        content: 'phantom header',
-        display: { llmHidden: true },
-      },
-      { role: 'user', content: 'hi' },
-    ];
-
-    for await (const _ of runAgent(messages, CFG, 'm', new AbortController().signal, registry)) {
-      // drain
-    }
-
-    expect(captured.length).toBe(1);
-    const sent = captured[0].messages;
-    // Only system + user reach the provider.
-    expect(sent.length).toBe(2);
-    expect(sent[0].role).toBe('system');
-    expect(sent[1].role).toBe('user');
-    expect(sent.find((m) => m.content === 'phantom header')).toBeUndefined();
-  });
-
-  it('keeps non-llmHidden messages even when `display.hidden` is set', async () => {
-    // Inverse flag: `display.hidden` is UI-only suppression and must NOT
-    // affect the LLM payload. This test pins that the two flags do not
-    // accidentally collapse into the same filter.
-    const captured: CapturedCall[] = [];
-    const registry = fakeRegistry(captured);
-
-    const messages: ChatMessage[] = [
-      { role: 'system', content: 'sys' },
-      { role: 'user', content: 'silent reminder', display: { hidden: true } },
-      { role: 'user', content: 'hi' },
-    ];
-
-    for await (const _ of runAgent(messages, CFG, 'm', new AbortController().signal, registry)) {
-      // drain
-    }
-
-    expect(captured.length).toBe(1);
-    const sent = captured[0].messages;
-    expect(sent.length).toBe(3);
-    expect(sent.find((m) => m.content === 'silent reminder')).toBeDefined();
-  });
-});

package/src/agent.ts

@@ -1,249 +0,0 @@
-import {
-  runAfterAgentRunHooks,
-  runAfterLlmHooks,
-  runAfterToolExecHook,
-  runBeforeLlmHooks,
-  runBeforeToolExecHook,
-  runDecorateMessageHooks,
-} 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;
-  let promptTokens = 0;
-  const toolCalls: ToolCall[] = [];
-
-  const hooks = registry.getHooks();
-  const hookedMessages = await runBeforeLlmHooks(hooks, messages, config);
-  // `display.llmHidden` keeps a message in the on-screen transcript but
-  // strips it from the LLM payload. Applied AFTER `beforeLlmHooks` so plugin
-  // hooks still see the full transcript if they want it; this is the very
-  // last filter before the network call. Inverse of `display.hidden`, which
-  // hides from UI but keeps in the LLM payload.
-  const llmMessages = hookedMessages.filter((m) => !m.display?.llmHidden);
-  const toolDefinitions = toolDefs.map((t) => t.definition);
-
-  for await (const chunk of streamChatViaRegistry(registry, llmMessages, config, model, {
-    signal,
-    tools: toolDefinitions,
-    onUsage: (u) => {
-      usage = u.totalTokens;
-      promptTokens = u.promptTokens;
-      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, promptTokens, 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 runDecorateMessageHooks(hooks, {
-      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 runDecorateMessageHooks(hooks, {
-    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, promptTokens, cachedPromptTokens } = yield* streamTurn(
-        current,
-        mergedConfig,
-        model,
-        signal,
-        registry,
-        tools,
-      );
-
-      if (usage > 0) {
-        yield { type: 'usage', totalTokens: usage, promptTokens, cachedTokens: cachedPromptTokens };
-      }
-      if (signal.aborted) {
-        break;
-      }
-
-      const reasoningField = reasoning || undefined;
-      const assistantBase: ChatMessage = { role: 'assistant', content, reasoning: reasoningField };
-      if (toolCalls.length === 0) {
-        const assistant = await runDecorateMessageHooks(registry.getHooks(), assistantBase);
-        current = [...current, assistant];
-        yield { type: 'messages', messages: current };
-        return;
-      }
-
-      const assistantWithCalls = await runDecorateMessageHooks(registry.getHooks(), { ...assistantBase, toolCalls });
-      current = [...current, assistantWithCalls];
-      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

@@ -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);
-  });
-});