mu-core 0.8.0

package/src/session.ts

@@ -0,0 +1,227 @@
+/**
+ * Session — owns the message history for a conversation context, runs the
+ * agent loop on submit, and emits events to subscribers (TUI, persistence,
+ * HTTP relay, …).
+ *
+ * Multi-session: channels emit a `sessionId`; SessionManager lazily
+ * instantiates a Session per key. mu-coding uses 'tui'; Arya uses
+ * `telegram:${chatId}`, etc.
+ */
+
+import { runAgent } from './agent';
+import type { ChannelResponder, InboundMessage } from './channel';
+import type { PluginRegistry } from './registry';
+import type { ChatMessage, ProviderConfig } from './types/llm';
+
+export type SessionEvent =
+  | { type: 'messages_changed'; messages: ChatMessage[] }
+  | { type: 'stream_partial'; text: string; reasoning?: string }
+  | { type: 'stream_started' }
+  | { type: 'stream_ended' }
+  | { type: 'usage'; totalTokens: number; cachedTokens: number }
+  | { type: 'error'; message: string };
+
+export interface RunTurnOptions {
+  /** Pre-built user message to append before running the agent loop. */
+  userMessage: ChatMessage;
+  /** Override config for this single turn (e.g. fresh model id). */
+  config?: ProviderConfig;
+  /** Override model for this single turn. */
+  model?: string;
+  /** Override registry for this single turn (rare). */
+  registry?: PluginRegistry;
+  /**
+   * Synthetic messages already in state that should NOT be re-appended (the
+   * caller updated React state imperatively). When omitted, Session works
+   * off its own tracked transcript.
+   */
+  baseMessages?: ChatMessage[];
+}
+
+export interface Session {
+  readonly id: string;
+  getMessages: () => ChatMessage[];
+  setMessages: (messages: ChatMessage[]) => void;
+  submit: (input: InboundMessage, responder: ChannelResponder) => Promise<void>;
+  /**
+   * Lower-level entry point used by hosts that pre-process the user input
+   * (transformUserInput hooks, attachments). Appends the message, drains
+   * the next-turn queue, runs the agent loop, and emits events.
+   */
+  runTurn: (options: RunTurnOptions) => Promise<ChatMessage[] | null>;
+  abort: () => void;
+  appendSynthetic: (msg: ChatMessage) => void;
+  queueForNextTurn: (msg: ChatMessage) => void;
+  subscribe: (listener: (event: SessionEvent) => void) => () => void;
+}
+
+export interface SessionInit {
+  initialMessages?: ChatMessage[];
+  systemPrompt?: string;
+}
+
+export interface SessionManager {
+  getOrCreate: (key: string, init?: SessionInit) => Session;
+  get: (key: string) => Session | undefined;
+  list: () => Session[];
+  close: (key: string) => Promise<void>;
+}
+
+export interface CreateSessionManagerOptions {
+  registry: PluginRegistry;
+  config: ProviderConfig;
+  model: string;
+}
+
+class SessionImpl implements Session {
+  readonly id: string;
+  private messages: ChatMessage[] = [];
+  private queue: ChatMessage[] = [];
+  private listeners = new Set<(e: SessionEvent) => void>();
+  private abortCtl: AbortController | null = null;
+  private systemPrompt?: string;
+
+  constructor(
+    id: string,
+    private registry: PluginRegistry,
+    private config: ProviderConfig,
+    private model: string,
+    init?: SessionInit,
+  ) {
+    this.id = id;
+    this.systemPrompt = init?.systemPrompt;
+    if (init?.initialMessages) this.messages = init.initialMessages.slice();
+  }
+
+  getMessages(): ChatMessage[] {
+    return this.messages.slice();
+  }
+
+  setMessages(messages: ChatMessage[]): void {
+    this.messages = messages.slice();
+    this.emit({ type: 'messages_changed', messages: this.messages.slice() });
+  }
+
+  subscribe(listener: (event: SessionEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(event: SessionEvent): void {
+    for (const fn of this.listeners) {
+      try {
+        fn(event);
+      } catch {
+        // listeners must not break the session
+      }
+    }
+  }
+
+  appendSynthetic(msg: ChatMessage): void {
+    this.messages.push(msg);
+    this.emit({ type: 'messages_changed', messages: this.messages.slice() });
+  }
+
+  queueForNextTurn(msg: ChatMessage): void {
+    this.queue.push(msg);
+  }
+
+  abort(): void {
+    if (this.abortCtl) this.abortCtl.abort();
+  }
+
+  async submit(input: InboundMessage, _responder: ChannelResponder): Promise<void> {
+    if (input.text === undefined) return;
+    const userMsg: ChatMessage = { role: 'user', content: input.text };
+    await this.runTurn({ userMessage: userMsg });
+  }
+
+  private async consumeAgentEvents(
+    cfg: ProviderConfig,
+    model: string,
+    registry: PluginRegistry,
+    signal: AbortSignal,
+  ): Promise<ChatMessage[] | null> {
+    let final: ChatMessage[] | null = null;
+    let partialText = '';
+    let partialReasoning = '';
+    for await (const e of runAgent(this.messages, cfg, model, signal, registry)) {
+      if (e.type === 'content') {
+        partialText = e.text;
+        this.emit({ type: 'stream_partial', text: partialText, reasoning: partialReasoning });
+      } else if (e.type === 'reasoning') {
+        partialReasoning = e.text;
+        this.emit({ type: 'stream_partial', text: partialText, reasoning: partialReasoning });
+      } else if (e.type === 'messages') {
+        this.messages = e.messages.slice();
+        final = this.messages.slice();
+        this.emit({ type: 'messages_changed', messages: this.messages.slice() });
+      } else if (e.type === 'usage') {
+        this.emit({ type: 'usage', totalTokens: e.totalTokens, cachedTokens: e.cachedTokens ?? 0 });
+      } else if (e.type === 'turn_end') {
+        partialText = '';
+        partialReasoning = '';
+      }
+    }
+    return final;
+  }
+
+  async runTurn(options: RunTurnOptions): Promise<ChatMessage[] | null> {
+    // Re-entrance guard. Concurrent `runTurn` calls would overwrite
+    // `abortCtl` (orphaning the previous abort controller) and append two
+    // user messages onto the same transcript, racing the agent loop. Hosts
+    // are responsible for not interleaving turns; the SDK enforces it.
+    if (this.abortCtl !== null) {
+      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);
+    if (this.queue.length) {
+      this.messages.push(...this.queue);
+      this.queue = [];
+    }
+    this.emit({ type: 'messages_changed', messages: this.messages.slice() });
+    this.emit({ type: 'stream_started' });
+    this.abortCtl = new AbortController();
+    const cfg: ProviderConfig = { ...(options.config ?? this.config) };
+    if (this.systemPrompt) cfg.systemPrompt = this.systemPrompt;
+    const model = options.model ?? this.model;
+    const registry = options.registry ?? this.registry;
+    try {
+      return await this.consumeAgentEvents(cfg, model, registry, this.abortCtl.signal);
+    } catch (err) {
+      this.emit({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+      return null;
+    } finally {
+      this.abortCtl = null;
+      this.emit({ type: 'stream_ended' });
+    }
+  }
+}
+
+export function createSessionManager(opts: CreateSessionManagerOptions): SessionManager {
+  const sessions = new Map<string, SessionImpl>();
+  return {
+    getOrCreate(key, init) {
+      let s = sessions.get(key);
+      if (!s) {
+        s = new SessionImpl(key, opts.registry, opts.config, opts.model, init);
+        sessions.set(key, s);
+      }
+      return s;
+    },
+    get(key) {
+      return sessions.get(key);
+    },
+    list() {
+      return Array.from(sessions.values());
+    },
+    async close(key) {
+      const s = sessions.get(key);
+      if (s) {
+        s.abort();
+        sessions.delete(key);
+      }
+    },
+  };
+}

package/src/types/llm.ts

@@ -0,0 +1,107 @@
+export interface ProviderConfig {
+  baseUrl: string;
+  model?: string;
+  maxTokens: number;
+  temperature: number;
+  streamTimeoutMs: number;
+  systemPrompt?: string;
+  /**
+   * Provider id to dispatch streaming through (`'openai'` by default).
+   * Resolved by the registry's `ProviderRegistry`. Lets a single host run
+   * multiple providers concurrently (e.g. coding via openai-compat,
+   * vision via a different API).
+   */
+  providerId?: string;
+}
+
+export interface Usage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  /** Subset of `promptTokens` that hit the prompt cache, when reported by the
+   *  server (OpenAI: `usage.prompt_tokens_details.cached_tokens`; llama.cpp
+   *  newer builds expose the same field). Undefined or 0 when unsupported. */
+  cachedPromptTokens?: number;
+}
+
+export interface ImageAttachment {
+  data: string; // base64 encoded
+  mimeType: string; // e.g. 'image/jpeg'
+  name: string; // filename for display
+}
+
+export interface ToolCall {
+  id: string;
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+export interface ToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
+export interface ToolResultInfo {
+  name: string;
+  content: string;
+  error?: boolean;
+}
+
+/**
+ * Optional rendering hints carried alongside a ChatMessage. Lets plugins (and
+ * the host) tweak how a message is presented without committing to a fully
+ * custom renderer:
+ *  - `color` overrides the role-default text/border color (e.g. agent color)
+ *  - `prefix` is rendered inline before the content (e.g. `│ ` colored bar)
+ *  - `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.
+ */
+export interface MessageDisplay {
+  color?: string;
+  prefix?: string;
+  badge?: string;
+  hidden?: boolean;
+}
+
+export interface ChatMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  reasoning?: string;
+  images?: ImageAttachment[];
+  toolCalls?: ToolCall[];
+  toolCallId?: string;
+  toolResult?: ToolResultInfo;
+  toolCallArgs?: Record<string, string>;
+  /**
+   * Tag used by plugins to route this message to a custom renderer registered
+   * with `PluginContext.ui.registerMessageRenderer`. When set and the renderer
+   * is found, the renderer takes precedence over the role-default renderer.
+   */
+  customType?: string;
+  /** Free-form bag for plugin-private state (e.g. agent name, sub-agent id). */
+  meta?: Record<string, unknown>;
+  /** Lightweight display tweaks; see `MessageDisplay`. */
+  display?: MessageDisplay;
+}
+
+export type StreamChunk =
+  | { type: 'reasoning'; text: string }
+  | { type: 'content'; text: string }
+  | { type: 'tool_call'; toolCall: ToolCall };
+
+export interface StreamOptions {
+  signal?: AbortSignal;
+  onUsage?: (usage: Usage) => void;
+  tools?: ToolDefinition[];
+}
+
+export interface ApiModel {
+  id: string;
+}

package/src/ui.ts

@@ -0,0 +1,49 @@
+/**
+ * UIService is the host-supplied bridge that lets plugins prompt the user,
+ * surface notifications, and pin status text without coupling to a specific
+ * renderer (Ink, plain console, etc.). The TUI host (mu-coding) implements
+ * this with `InkUIService`; CLI / single-shot hosts can use `ConsoleUIService`.
+ *
+ * Plugins receive a `UIService` either directly through their own factory
+ * config or via `PluginContext.ui` when one is provided.
+ */
+export type UINotifyLevel = 'info' | 'success' | 'warning' | 'error';
+
+export interface UIService {
+  notify: (message: string, level?: UINotifyLevel) => void;
+  confirm: (title: string, message: string) => Promise<boolean>;
+  select: (title: string, options: string[]) => Promise<string | null>;
+  input: (title: string, placeholder?: string) => Promise<string | null>;
+  setStatus: (key: string, text: string) => void;
+  clearStatus: (key: string) => void;
+}
+
+/**
+ * Fallback UIService for non-interactive (single-shot) mode.
+ * Routes notifications to stderr; auto-resolves prompts in deterministic ways
+ * so non-interactive runs never block.
+ */
+export class ConsoleUIService implements UIService {
+  notify(message: string, level?: UINotifyLevel): void {
+    const prefix = level === 'error' ? '[ERROR]' : level === 'warning' ? '[WARN]' : '[INFO]';
+    console.error(`${prefix} ${message}`);
+  }
+  async confirm(_title: string, message: string): Promise<boolean> {
+    console.error(`[CONFIRM] ${message} (auto-accepting in non-interactive mode)`);
+    return true;
+  }
+  async select(_title: string, options: string[]): Promise<string | null> {
+    console.error('[SELECT] Auto-selecting first option in non-interactive mode');
+    return options[0] ?? null;
+  }
+  async input(_title: string, _placeholder?: string): Promise<string | null> {
+    console.error('[INPUT] Cannot prompt in non-interactive mode');
+    return null;
+  }
+  setStatus(_key: string, _text: string): void {
+    /* no-op in console mode */
+  }
+  clearStatus(_key: string): void {
+    /* no-op in console mode */
+  }
+}