mu-core 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mu-core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Agent loop orchestration core: types, plugin SDK, channels, sessions",
   "type": "module",
   "main": "./src/index.ts",

package/src/agent.test.ts

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

@@ -4,6 +4,7 @@ import {
   runAfterToolExecHook,
   runBeforeLlmHooks,
   runBeforeToolExecHook,
+  runDecorateMessageHooks,
 } from './hooks';
 import type { AgentEvent, PluginTool, ToolResult, TurnResult } from './plugin';
 import type { PluginRegistry } from './registry';
@@ -90,9 +91,15 @@ async function* streamTurn(
 
   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, hookedMessages, config, model, {
+  for await (const chunk of streamChatViaRegistry(registry, llmMessages, config, model, {
     signal,
     tools: toolDefinitions,
     onUsage: (u) => {
@@ -129,24 +136,24 @@ async function executeOneToolCall(
 
   if ('blocked' in hookOutcome) {
     const content = await runAfterToolExecHook(hooks, tc, hookOutcome.content);
-    return {
+    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 {
+  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(
@@ -220,14 +227,16 @@ export async function* runAgent(
       }
 
       const reasoningField = reasoning || undefined;
-      const assistant: ChatMessage = { role: 'assistant', content, reasoning: reasoningField };
+      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;
       }
 
-      current = [...current, { ...assistant, toolCalls }];
+      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' };

package/src/hooks.test.ts

@@ -73,4 +73,33 @@ describe('runTransformUserInputHooks', () => {
     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

@@ -58,6 +58,22 @@ export async function runAfterToolExecHook(
   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) {
@@ -69,7 +85,11 @@ export async function runAfterAgentRunHooks(hooks: LifecycleHooks[], reason: Age
 /**
  * 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.
+ * 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' };
@@ -80,6 +100,9 @@ export async function runTransformUserInputHooks(hooks: LifecycleHooks[], text:
     if (next.kind === 'intercept') {
       return next;
     }
+    if (next.kind === 'continue') {
+      return next;
+    }
     if (next.kind === 'transform') {
       working = next.text;
       current = next;

package/src/index.ts

@@ -3,7 +3,7 @@ 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 { runDecorateMessageHooks, runTransformUserInputHooks } from './hooks';
 export type { MuConfigShape, MuHandle, StartMuOptions } from './host/index';
 export { startMu } from './host/index';
 export type {
@@ -13,6 +13,7 @@ export type {
   AgentSourceRegistry,
   BeforeToolExecResult,
   CommandContext,
+  InputInfoSegment,
   LifecycleHooks,
   MentionCompletion,
   MentionProvider,

package/src/plugin.ts

@@ -59,6 +59,12 @@ export interface MentionCompletion {
   label?: string;
   /** Secondary text shown dimly in the picker. */
   description?: string;
+  /**
+   * Optional grouping label rendered as a section header in the picker
+   * (e.g. "agents", "files"). When unset, completions are rendered without
+   * a group header. The host hides the header when only one group is shown.
+   */
+  category?: string;
 }
 
 export type MentionProvider = (partial: string) => MentionCompletion[] | Promise<MentionCompletion[]>;
@@ -96,6 +102,12 @@ export interface PluginRegistryView {
   getHooks: () => LifecycleHooks[];
   getSystemPrompts: () => Promise<string[]>;
   applySystemPromptTransforms: (prompt: string) => Promise<string>;
+  /**
+   * Provider registry handle (or `undefined` if the host didn't supply one).
+   * Exposed so plugins that re-issue LLM calls (e.g. the mu-agents subagent
+   * loop) can resolve the configured provider exactly like `runAgent` does.
+   */
+  getProviders: () => ProviderRegistry | undefined;
 }
 
 export interface PluginContext extends PluginExtras {
@@ -119,6 +131,13 @@ export interface PluginContext extends PluginExtras {
    * polling-based `Plugin.statusLine()` getter. Pass `[]` to clear.
    */
   setStatusLine?: (segments: StatusSegment[]) => void;
+  /**
+   * Push info chips into the host's input footer (e.g. "Coding" agent
+   * label). Replaces the segments previously pushed by *this* plugin. Pass
+   * `[]` to clear. Hosts that don't render an input footer are free to
+   * ignore the call.
+   */
+  setInputInfo?: (segments: InputInfoSegment[]) => void;
   /**
    * Host-provided graceful shutdown hook. When supplied, plugins should prefer
    * this over `process.exit(...)` so the host can deactivate plugins and restore
@@ -242,8 +261,18 @@ export type BeforeToolExecResult = ToolCall | ToolBlock;
  *   - `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.
+ *   - `continue` — the hook has appended the user message itself (e.g. via
+ *     `MessageBus.append` so it shows up live in the transcript). The host
+ *     should NOT push another user message but should still run a turn:
+ *     drain the injectNext queue and stream the LLM. Used by the subagent
+ *     `@`-mention dispatch path so the user's message lands first, the
+ *     subagent runs live, and the parent agent then takes a real turn.
  */
-export type UserInputTransform = { kind: 'pass' } | { kind: 'transform'; text: string } | { kind: 'intercept' };
+export type UserInputTransform =
+  | { kind: 'pass' }
+  | { kind: 'transform'; text: string }
+  | { kind: 'intercept' }
+  | { kind: 'continue' };
 
 export interface LifecycleHooks {
   beforeLlmCall?: (messages: ChatMessage[], config: ProviderConfig) => ChatMessage[] | Promise<ChatMessage[]>;
@@ -276,6 +305,14 @@ export interface LifecycleHooks {
    * cleanup; per-turn cleanup belongs in `afterLlmCall`.
    */
   afterAgentRun?: (reason: AgentEndReason) => void | Promise<void>;
+  /**
+   * Decorate a freshly built `ChatMessage` (user / assistant / tool) before
+   * it's appended to the transcript. Plugins typically use this to stamp
+   * `display.badge` / `display.color` (e.g. with the active agent name +
+   * color) or augment `meta`. Hooks compose left-to-right; later hooks see
+   * the prior hook's output. Should not change `role` or `content`.
+   */
+  decorateMessage?: (msg: ChatMessage) => ChatMessage | Promise<ChatMessage>;
 }
 
 export interface CommandContext {
@@ -315,6 +352,19 @@ export interface StatusSegment {
   dim?: boolean;
 }
 
+/**
+ * Info chip a plugin pushes into the input footer (e.g. active agent name).
+ * Aggregated across plugins by `PluginRegistry.getInputInfoSegments()` and
+ * surfaced to the host's input UI in registration order.
+ */
+export interface InputInfoSegment {
+  /** Stable key — used by the renderer for list reconciliation. */
+  key: string;
+  text: string;
+  color?: string;
+  bold?: boolean;
+}
+
 export interface Plugin {
   name: string;
   version?: string;

package/src/registry.ts

@@ -3,6 +3,7 @@ import type { ChannelRegistry } from './channel';
 import type {
   AgentLoopStrategy,
   AgentSourceRegistry,
+  InputInfoSegment,
   LifecycleHooks,
   MentionProvider,
   MessageBus,
@@ -73,6 +74,8 @@ export class PluginRegistry {
   private context: PluginContext;
   private statusSegmentsByPlugin: Map<string, StatusSegment[]> = new Map();
   private statusListeners: Set<StatusListener> = new Set();
+  private inputInfoByPlugin: Map<string, InputInfoSegment[]> = new Map();
+  private inputInfoListeners: Set<StatusListener> = new Set();
   private renderers: RendererEntry[] = [];
   private shortcuts: ShortcutEntry[] = [];
   private mentions: MentionEntry[] = [];
@@ -120,6 +123,9 @@ export class PluginRegistry {
     if (this.statusSegmentsByPlugin.delete(name)) {
       this.emitStatus();
     }
+    if (this.inputInfoByPlugin.delete(name)) {
+      this.emitInputInfo();
+    }
     this.dropPluginRegistrations(name);
   }
 
@@ -246,6 +252,24 @@ export class PluginRegistry {
     };
   }
 
+  /** Aggregate of every plugin's most recently pushed input-info segments, in registration order. */
+  getInputInfoSegments(): InputInfoSegment[] {
+    const segments: InputInfoSegment[] = [];
+    for (const plugin of this.plugins.values()) {
+      const pluginSegments = this.inputInfoByPlugin.get(plugin.name);
+      if (pluginSegments?.length) segments.push(...pluginSegments);
+    }
+    return segments;
+  }
+
+  /** Subscribe to input-info segment changes. Returns an unsubscribe fn. */
+  onInputInfoChange(listener: StatusListener): () => void {
+    this.inputInfoListeners.add(listener);
+    return () => {
+      this.inputInfoListeners.delete(listener);
+    };
+  }
+
   getAgentLoop(): AgentLoopStrategy | undefined {
     for (const plugin of this.plugins.values()) {
       if (plugin.agentLoop) {
@@ -319,8 +343,10 @@ export class PluginRegistry {
         getHooks: () => this.getHooks(),
         getSystemPrompts: () => this.getSystemPrompts(),
         applySystemPromptTransforms: (prompt) => this.applySystemPromptTransforms(prompt),
+        getProviders: () => this.getProviders(),
       },
       setStatusLine: (segments) => this.setStatusLine(pluginName, segments),
+      setInputInfo: (segments) => this.setInputInfo(pluginName, segments),
       registerMessageRenderer: (customType, renderer) => this.addRenderer(pluginName, customType, renderer),
       registerShortcut: (key, handler) => this.addShortcut(pluginName, key, handler),
       registerMentionProvider: (trigger, provider) => this.addMention(pluginName, trigger, provider),
@@ -349,12 +375,30 @@ export class PluginRegistry {
     this.emitStatus();
   }
 
+  private setInputInfo(pluginName: string, segments: InputInfoSegment[]): void {
+    if (segments.length === 0) {
+      const removed = this.inputInfoByPlugin.delete(pluginName);
+      if (removed) this.emitInputInfo();
+      return;
+    }
+    const prev = this.inputInfoByPlugin.get(pluginName);
+    if (prev && inputInfoEqual(prev, segments)) {
+      return;
+    }
+    this.inputInfoByPlugin.set(pluginName, segments);
+    this.emitInputInfo();
+  }
+
   private emitStatus(): void {
     for (const listener of this.statusListeners) {
       listener();
     }
   }
 
+  private emitInputInfo(): void {
+    for (const listener of this.inputInfoListeners) listener();
+  }
+
   private addRenderer(plugin: string, customType: string, renderer: MessageRenderer): () => void {
     const entry: RendererEntry = { plugin, customType, renderer };
     this.renderers.push(entry);
@@ -428,3 +472,13 @@ function segmentsEqual(a: StatusSegment[], b: StatusSegment[]): boolean {
   }
   return true;
 }
+
+function inputInfoEqual(a: InputInfoSegment[], b: InputInfoSegment[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].key !== b[i].key || a[i].text !== b[i].text || a[i].color !== b[i].color || a[i].bold !== b[i].bold) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/session.ts

@@ -22,8 +22,15 @@ export type SessionEvent =
   | { type: 'error'; message: string };
 
 export interface RunTurnOptions {
-  /** Pre-built user message to append before running the agent loop. */
-  userMessage: ChatMessage;
+  /**
+   * Pre-built user message to append before running the agent loop.
+   * Optional: when a plugin's `transformUserInput` returns `'continue'`
+   * the hook has already appended its own user message via
+   * `MessageBus.append`, and the host calls `runTurn` without a
+   * `userMessage` to drain the injectNext queue and stream the LLM
+   * without pushing a duplicate.
+   */
+  userMessage?: ChatMessage;
   /** Override config for this single turn (e.g. fresh model id). */
   config?: ProviderConfig;
   /** Override model for this single turn. */
@@ -159,8 +166,14 @@ class SessionImpl implements Session {
       } else if (e.type === 'usage') {
         this.emit({ type: 'usage', totalTokens: e.totalTokens, cachedTokens: e.cachedTokens ?? 0 });
       } else if (e.type === 'turn_end') {
+        // Clear the locally-tracked partial buffers AND notify subscribers,
+        // otherwise the host's `stream` state still holds the previous step's
+        // reasoning/content between agent loop iterations — visible as a
+        // stale "thinking…" block lingering after a tool call until the next
+        // step's first `content`/`reasoning` chunk overwrites it.
         partialText = '';
         partialReasoning = '';
+        this.emit({ type: 'stream_partial', text: '', reasoning: '' });
       }
     }
     return final;
@@ -175,7 +188,10 @@ class SessionImpl implements Session {
       throw new Error(`Session "${this.id}" already running a turn. Call abort() first or wait for completion.`);
     }
     if (options.baseMessages) this.messages = options.baseMessages.slice();
-    this.messages.push(options.userMessage);
+    // Skip the push when the caller didn't supply a userMessage — that
+    // happens when a `transformUserInput` hook returned `'continue'` and
+    // already appended the user's message itself (see `UserInputTransform`).
+    if (options.userMessage) this.messages.push(options.userMessage);
     if (this.queue.length) {
       this.messages.push(...this.queue);
       this.queue = [];

package/src/types/llm.ts

@@ -62,12 +62,17 @@ export interface ToolResultInfo {
  *  - `badge` is shown in a small box before the body (e.g. agent name)
  *  - `hidden` keeps the message in the transcript (sent to the LLM) but skips
  *    its on-screen rendering — useful for system reminders.
+ *  - `llmHidden` is the inverse: keep the message in the on-screen transcript
+ *    but strip it from the LLM payload right before the network call. Useful
+ *    for UI-only markers (subagent dispatch headers, status pings) that
+ *    plugins want users to see but the model shouldn't read as conversation.
  */
 export interface MessageDisplay {
   color?: string;
   prefix?: string;
   badge?: string;
   hidden?: boolean;
+  llmHidden?: boolean;
 }
 
 export interface ChatMessage {
@@ -104,4 +109,12 @@ export interface StreamOptions {
 
 export interface ApiModel {
   id: string;
+  /**
+   * Maximum input + output token window the provider advertises for this
+   * model. OpenAI itself doesn't expose this on `/models`; compat servers
+   * (llama.cpp, LM Studio, vLLM, Ollama's openai shim, ...) often do under
+   * names like `context_length`, `max_context_length`, or
+   * `max_position_embeddings`. Omitted when the provider doesn't report it.
+   */
+  contextLimit?: number;
 }