mu-coding 0.4.0 → 0.8.0

package/src/sessions/index.ts

@@ -0,0 +1,183 @@
+import { createReadStream, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import type { ChatMessage } from 'mu-core';
+import { getDataDir } from '../config/index';
+import { getProjectId, getProjectName } from './project';
+
+function getProjectSessionsDir(): string {
+  return join(getDataDir(), 'sessions', getProjectId());
+}
+
+function getSortedSessionFiles(): string[] {
+  try {
+    const dir = getProjectSessionsDir();
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.jsonl'))
+      .sort()
+      .reverse();
+  } catch {
+    return [];
+  }
+}
+
+export interface SessionInfo {
+  path: string;
+  name: string;
+  date: Date;
+  messageCount: number;
+  preview: string;
+  project: string;
+}
+
+export function generateSessionPath(): string {
+  const dir = getProjectSessionsDir();
+  mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  return join(dir, `${ts}.jsonl`);
+}
+
+/**
+ * Persist `messages` as JSONL. Async to avoid blocking the event loop on
+ * large sessions; callers should `await` to apply backpressure.
+ */
+export async function saveSession(path: string, messages: ChatMessage[]): Promise<void> {
+  const content = messages.length > 0 ? `${messages.map((m) => JSON.stringify(m)).join('\n')}\n` : '';
+  await writeFile(path, content, 'utf-8');
+}
+
+export function loadSession(path: string): ChatMessage[] {
+  try {
+    const content = readFileSync(path, 'utf-8').trim();
+    if (!content) {
+      return [];
+    }
+    return content
+      .split('\n')
+      .map((line) => {
+        try {
+          return JSON.parse(line) as ChatMessage;
+        } catch {
+          return null;
+        }
+      })
+      .filter((msg): msg is ChatMessage => msg !== null);
+  } catch {
+    return [];
+  }
+}
+
+interface SessionPeek {
+  messageCount: number;
+  preview: string;
+}
+
+const PREVIEW_LENGTH = 80;
+const NO_USER_PREVIEW = '(no user message)';
+const EMPTY_PEEK: SessionPeek = { messageCount: 0, preview: '(empty)' };
+
+/**
+ * In-memory cache of session metadata, keyed by absolute path. Entries are
+ * invalidated when the file's mtime changes (a fresh `saveSession` after a
+ * new message bumps mtime). Lifetime is the process — no on-disk index.
+ */
+const peekCache = new Map<string, { mtimeMs: number; peek: SessionPeek }>();
+
+function extractUserPreview(line: string): string | null {
+  try {
+    const msg = JSON.parse(line) as ChatMessage;
+    if (msg && msg.role === 'user' && typeof msg.content === 'string') {
+      return msg.content.slice(0, PREVIEW_LENGTH).replace(/\n/g, ' ');
+    }
+  } catch {
+    // Skip malformed lines.
+  }
+  return null;
+}
+
+/**
+ * Stream a session file line-by-line so memory use is bounded regardless of
+ * file size, and we can stop expensive `JSON.parse` work as soon as we've
+ * captured the first user message.
+ */
+async function peekSessionStreaming(path: string): Promise<SessionPeek> {
+  return new Promise((resolve) => {
+    const stream = createReadStream(path, { encoding: 'utf-8', highWaterMark: 64 * 1024 });
+    const rl = createInterface({ input: stream });
+    let messageCount = 0;
+    let preview: string | null = null;
+
+    const finish = (): void => {
+      resolve({ messageCount, preview: preview ?? NO_USER_PREVIEW });
+    };
+
+    rl.on('line', (line) => {
+      if (!line) return;
+      messageCount++;
+      if (preview !== null) return;
+      preview = extractUserPreview(line);
+    });
+    rl.on('close', finish);
+    stream.on('error', () => resolve(EMPTY_PEEK));
+  });
+}
+
+async function peekSessionCached(path: string, mtimeMs: number): Promise<SessionPeek> {
+  const cached = peekCache.get(path);
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return cached.peek;
+  }
+  const peek = await peekSessionStreaming(path);
+  peekCache.set(path, { mtimeMs, peek });
+  return peek;
+}
+
+/** Test/maintenance helper — drop the in-memory peek cache. */
+export function clearSessionCache(): void {
+  peekCache.clear();
+}
+
+export function getLatestSession(): string | null {
+  const files = getSortedSessionFiles();
+  return files.length ? join(getProjectSessionsDir(), files[0]) : null;
+}
+
+/**
+ * Resolve session metadata for the picker. Each file is peeked concurrently
+ * (typically just a few hundred bytes per file), and successive picker opens
+ * hit the in-memory cache keyed by mtime.
+ */
+export async function listSessionsAsync(): Promise<SessionInfo[]> {
+  let dir: string;
+  try {
+    dir = getProjectSessionsDir();
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return [];
+  }
+  const files = getSortedSessionFiles();
+  const project = getProjectName();
+
+  const results = await Promise.all(
+    files.map(async (file) => {
+      const path = join(dir, file);
+      try {
+        const fileStat = await stat(path);
+        const peek = await peekSessionCached(path, fileStat.mtimeMs);
+        return {
+          path,
+          name: file.replace('.jsonl', ''),
+          date: fileStat.mtime,
+          messageCount: peek.messageCount,
+          preview: peek.preview,
+          project,
+        } satisfies SessionInfo;
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  return results.filter((s): s is SessionInfo => s !== null);
+}

package/src/sessions/peek.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Verifies the streaming `listSessionsAsync` end-to-end against a tmp data
+ * directory laid out exactly like a real `~/.local/share/mu/sessions/<proj>`.
+ * The cache is exercised by listing twice and confirming we get the same
+ * structural result without re-reading.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { clearSessionCache, listSessionsAsync } from './index';
+import { getProjectId } from './project';
+
+const PROJECT_ID = getProjectId();
+
+let tmpRoot: string;
+let sessionsDir: string;
+
+beforeAll(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'mu-peek-'));
+  process.env.XDG_DATA_HOME = tmpRoot;
+  sessionsDir = join(tmpRoot, 'mu', 'sessions', PROJECT_ID);
+  mkdirSync(sessionsDir, { recursive: true });
+});
+
+afterEach(() => {
+  clearSessionCache();
+});
+
+function writeSession(name: string, messages: Array<{ role: string; content: string }>): string {
+  const path = join(sessionsDir, name);
+  writeFileSync(path, `${messages.map((m) => JSON.stringify(m)).join('\n')}\n`);
+  return path;
+}
+
+describe('listSessionsAsync', () => {
+  it('captures message count and the first user preview', async () => {
+    writeSession('2026-01-01.jsonl', [
+      { role: 'user', content: 'hello world' },
+      { role: 'assistant', content: 'hi back' },
+      { role: 'user', content: 'a follow-up' },
+    ]);
+
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-01');
+    expect(entry).toBeDefined();
+    expect(entry?.messageCount).toBe(3);
+    expect(entry?.preview).toBe('hello world');
+  });
+
+  it('handles malformed lines without crashing', async () => {
+    writeSession('2026-01-02.jsonl', [{ role: 'user', content: 'ok' }]);
+    // Append a junk line outside the structured writer.
+    const broken = join(sessionsDir, '2026-01-03.jsonl');
+    writeFileSync(broken, '{"role":"user","content":"valid"}\n{not-json\n');
+
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-03');
+    expect(entry?.messageCount).toBe(2);
+    expect(entry?.preview).toBe('valid');
+  });
+
+  it('reports a placeholder when no user message is present', async () => {
+    writeSession('2026-01-04.jsonl', [{ role: 'assistant', content: 'no user here' }]);
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-04');
+    expect(entry?.preview).toBe('(no user message)');
+  });
+
+  it('truncates long previews to PREVIEW_LENGTH and replaces newlines', async () => {
+    const longMessage = `line one\n${'x'.repeat(200)}`;
+    writeSession('2026-01-05.jsonl', [{ role: 'user', content: longMessage }]);
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-05');
+    expect(entry?.preview).not.toContain('\n');
+    expect(entry?.preview.length).toBe(80);
+  });
+
+  it('serves cached results on the second call (same mtime)', async () => {
+    writeSession('2026-01-06.jsonl', [{ role: 'user', content: 'cached' }]);
+    const first = await listSessionsAsync();
+    const second = await listSessionsAsync();
+    const a = first.find((s) => s.name === '2026-01-06');
+    const b = second.find((s) => s.name === '2026-01-06');
+    expect(a?.preview).toBe(b?.preview);
+    expect(a?.messageCount).toBe(b?.messageCount);
+  });
+});

package/src/sessions/project.ts

@@ -0,0 +1,51 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+function findGitRoot(from: string): string | null {
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: from,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return root || null;
+  } catch {
+    return null;
+  }
+}
+
+// The project root is determined once per process — `process.cwd()` doesn't
+// move during a TUI session and shelling out to git on every save is wasteful.
+let cachedRoot: string | null = null;
+
+function getProjectRoot(): string {
+  if (cachedRoot !== null) {
+    return cachedRoot;
+  }
+  const cwd = process.cwd();
+  cachedRoot = findGitRoot(cwd) ?? cwd;
+  return cachedRoot;
+}
+
+let cachedId: string | null = null;
+let cachedName: string | null = null;
+
+export function getProjectId(): string {
+  if (cachedId !== null) {
+    return cachedId;
+  }
+  const root = getProjectRoot();
+  const hash = createHash('sha256').update(root).digest('hex').slice(0, 12);
+  const name = root.split('/').pop() || 'unknown';
+  cachedId = `${name}-${hash}`;
+  return cachedId;
+}
+
+export function getProjectName(): string {
+  if (cachedName !== null) {
+    return cachedName;
+  }
+  const root = getProjectRoot();
+  cachedName = root.split('/').pop() || root;
+  return cachedName;
+}

package/src/tui/channel/tuiChannel.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it, mock } from 'bun:test';
+import type { ChatMessage, PluginRegistry } from 'mu-core';
+import type { ShutdownFn } from '../../app/shutdown';
+import type { AppConfig } from '../../config/index';
+import type { HostMessageBus } from '../../runtime/messageBus';
+import type { InkUIService } from '../plugins/InkUIService';
+import { createTuiChannel } from './tuiChannel';
+
+// Stub renderApp by mocking the import surface. We can't actually mount Ink
+// in a non-TTY test environment, but we can verify the channel structure
+// and that the registry passed in has the methods the TUI subscribes to.
+const noop = (): void => {
+  /* stub */
+};
+
+const renderArgs: Array<{ registry: PluginRegistry; config: AppConfig }> = [];
+mock.module('../renderApp', () => ({
+  renderApp: (opts: { registry: PluginRegistry; config: AppConfig }) => {
+    renderArgs.push(opts);
+    return {
+      unmount: noop,
+      waitUntilExit: async () => {
+        /* stub */
+      },
+      rerender: noop,
+      cleanup: noop,
+      clear: noop,
+    };
+  },
+}));
+
+const fakeOpts = {
+  config: {} as AppConfig,
+  initialMessages: [] as ChatMessage[],
+  registry: {} as PluginRegistry,
+  messageBus: {} as HostMessageBus,
+  uiService: {} as InkUIService,
+  shutdown: (async () => {
+    /* test shutdown stub */
+  }) as ShutdownFn,
+};
+
+describe('createTuiChannel', () => {
+  it('exposes id="tui"', () => {
+    const ch = createTuiChannel(fakeOpts);
+    expect(ch.id).toBe('tui');
+  });
+
+  it('start is idempotent — second start is a no-op', async () => {
+    const ch = createTuiChannel(fakeOpts);
+    await ch.start();
+    await ch.start(); // should not throw / re-mount
+  });
+
+  it('stop without start is a no-op', async () => {
+    const ch = createTuiChannel(fakeOpts);
+    await ch.stop?.();
+  });
+
+  it('start → stop → start cycles cleanly', async () => {
+    const ch = createTuiChannel(fakeOpts);
+    await ch.start();
+    await ch.stop?.();
+    await ch.start();
+    await ch.stop?.();
+  });
+});
+
+describe('createTuiChannel — registry shape contract', () => {
+  it('forwards a registry that exposes the subscription methods the TUI relies on', async () => {
+    // Build a registry mock whose methods are all functions; the channel's
+    // `start()` calls renderApp which (in production) mounts components that
+    // immediately invoke onStatusChange / onRenderersChange / etc.
+    const stubFn = (): (() => void) => () => {
+      /* unsub */
+    };
+    const fakeRegistry: Record<string, unknown> = {
+      getTools: () => [],
+      getFilteredTools: async () => [],
+      getHooks: () => [],
+      getStatusSegments: () => new Map(),
+      onStatusChange: stubFn(),
+      getRenderers: () => [],
+      onRenderersChange: stubFn(),
+      getShortcuts: () => [],
+      onShortcutsChange: stubFn(),
+      getCommands: () => [],
+    };
+    const ch = createTuiChannel({ ...fakeOpts, registry: fakeRegistry as unknown as PluginRegistry });
+    renderArgs.length = 0;
+    await ch.start();
+    expect(renderArgs).toHaveLength(1);
+    const seen = renderArgs[0].registry as unknown as Record<string, unknown>;
+    for (const method of [
+      'onStatusChange',
+      'getStatusSegments',
+      'onRenderersChange',
+      'getRenderers',
+      'onShortcutsChange',
+      'getShortcuts',
+      'getCommands',
+    ]) {
+      expect(typeof seen[method]).toBe('function');
+    }
+    await ch.stop?.();
+  });
+});

package/src/tui/channel/tuiChannel.ts

@@ -0,0 +1,49 @@
+/**
+ * TUI Channel — wraps Ink rendering inside the mu-core `Channel` contract.
+ * `start()` mounts the app and captures the Ink instance; `stop()` unmounts
+ * it cleanly so `channels.stopAll()` restores the terminal.
+ */
+
+import type { Instance } from 'ink';
+import type { Channel, ChatMessage, PluginRegistry } from 'mu-core';
+import type { ShutdownFn } from '../../app/shutdown';
+import type { AppConfig } from '../../config/index';
+import type { HostMessageBus } from '../../runtime/messageBus';
+import type { InkUIService } from '../plugins/InkUIService';
+import { renderApp } from '../renderApp';
+
+export interface TuiChannelOptions {
+  config: AppConfig;
+  initialMessages?: ChatMessage[];
+  registry: PluginRegistry;
+  messageBus: HostMessageBus;
+  uiService: InkUIService;
+  shutdown: ShutdownFn;
+}
+
+export function createTuiChannel(opts: TuiChannelOptions): Channel {
+  let instance: Instance | null = null;
+  return {
+    id: 'tui',
+    async start() {
+      // Idempotent: re-starting after a stop remounts; re-starting while
+      // mounted is a no-op.
+      if (instance) return;
+      instance = renderApp(opts);
+    },
+    async stop() {
+      if (!instance) return;
+      try {
+        instance.unmount();
+        // Wait for Ink's exit promise so `stopAll()` callers know the
+        // terminal has been restored before they continue (e.g. emitting
+        // a final shutdown message to stdout).
+        await instance.waitUntilExit().catch(() => {
+          /* unmount-induced exit rejects with the cause; we don't care */
+        });
+      } finally {
+        instance = null;
+      }
+    },
+  };
+}

package/src/tui/{context/chat.ts → chat/ChatContext.ts}

@@ -1,5 +1,5 @@
 import { createContext, useContext } from 'react';
-import type { ChatContextValue } from '../useChat';
+import type { ChatContextValue } from './useChat';
 
 export const ChatContext = createContext<ChatContextValue | null>(null);
 

package/src/tui/chat/MessageRendererContext.ts

@@ -0,0 +1,44 @@
+import type { ChatMessage, PluginRegistry } from 'mu-core';
+import { createContext, type ReactNode, useContext, useEffect, useState } from 'react';
+
+/**
+ * Plugin renderers are typed `unknown` in mu-agents (kept renderer-agnostic);
+ * the host narrows to React at the boundary so renderer authors can return
+ * any `ReactNode`.
+ */
+type ReactMessageRenderer = (msg: ChatMessage) => ReactNode;
+
+type RendererMap = Map<string, ReactMessageRenderer>;
+
+const MessageRendererContext = createContext<RendererMap>(new Map());
+
+export const MessageRendererProvider = MessageRendererContext.Provider;
+
+/** Hook used by `MessageItem` to look up custom renderers by `customType`. */
+export function useMessageRenderer(customType: string | undefined): ReactMessageRenderer | undefined {
+  const map = useContext(MessageRendererContext);
+  if (!customType) return undefined;
+  return map.get(customType);
+}
+
+/**
+ * Track the registry's custom renderer set. Re-builds the map whenever a
+ * plugin registers or unregisters one. The cast from `unknown` to ReactNode
+ * happens here so descendant components stay strictly typed.
+ */
+export function useRegistryRenderers(registry: PluginRegistry): RendererMap {
+  const [map, setMap] = useState<RendererMap>(() => buildMap(registry));
+  useEffect(() => {
+    setMap(buildMap(registry));
+    return registry.onRenderersChange(() => setMap(buildMap(registry)));
+  }, [registry]);
+  return map;
+}
+
+function buildMap(registry: PluginRegistry): RendererMap {
+  const out: RendererMap = new Map();
+  for (const [customType, renderer] of registry.getRenderers()) {
+    out.set(customType, (msg) => renderer(msg) as ReactNode);
+  }
+  return out;
+}

package/src/tui/chat/ToolDisplayContext.ts

@@ -0,0 +1,33 @@
+import type { PluginRegistry, ToolDisplayHint } from 'mu-core';
+import { createContext, useContext, useMemo } from 'react';
+
+type ToolDisplayMap = Map<string, ToolDisplayHint>;
+
+const ToolDisplayContext = createContext<ToolDisplayMap>(new Map());
+
+export const ToolDisplayProvider = ToolDisplayContext.Provider;
+
+/** Hook used by tool renderers to look up rendering hints for a tool name. */
+export function useToolDisplay(name: string): ToolDisplayHint | undefined {
+  const map = useContext(ToolDisplayContext);
+  return map.get(name);
+}
+
+/**
+ * Build a lookup table from the registry, keyed by tool function name. Tools
+ * without a `display` hint are omitted; the renderer falls back to a generic
+ * preview block. Memoized on the registry reference — registration is
+ * effectively startup-only today, but the dependency makes the contract
+ * explicit if hot-loading lands later.
+ */
+export function useToolDisplayMap(registry: PluginRegistry): ToolDisplayMap {
+  return useMemo(() => {
+    const map: ToolDisplayMap = new Map();
+    for (const tool of registry.getTools()) {
+      if (tool.display) {
+        map.set(tool.definition.function.name, tool.display);
+      }
+    }
+    return map;
+  }, [registry]);
+}

package/src/tui/{useAbort.ts → chat/useAbort.ts}

@@ -1,4 +1,5 @@
 import { useCallback, useRef, useState } from 'react';
+import { restoreTerminal, type ShutdownFn } from '../../app/shutdown';
 
 function useDoublePress(timeoutMs: number) {
   const [warning, setWarning] = useState(false);
@@ -38,6 +39,7 @@ export function useAbort(
   controllerRef: React.RefObject<AbortController | null>,
   exit: () => void,
   timeoutMs: number,
+  shutdown?: ShutdownFn,
 ): AbortState {
   const { warning: quitWarning, confirm: onCtrlC } = useDoublePress(timeoutMs);
   const { warning: abortWarning, confirm: onEsc } = useDoublePress(timeoutMs);
@@ -48,14 +50,21 @@ export function useAbort(
       controllerRef.current = null;
       return;
     }
-    if (onCtrlC()) {
-      exit();
-      setTimeout(() => {
-        process.stdout.write('\x1b[<u');
-        process.exit(0);
-      }, 100);
+    if (!onCtrlC()) {
+      return;
+    }
+    // Restore the terminal first so even a hanging shutdown leaves a usable
+    // prompt, then unmount Ink (fires `useScroll`/etc. cleanups), then run
+    // the registry shutdown which `process.exit`s when complete.
+    restoreTerminal();
+    exit();
+    if (shutdown) {
+      void shutdown(0);
+    } else {
+      // Fallback for callers that didn't wire a shutdown function.
+      setTimeout(() => process.exit(0), 500);
     }
-  }, [streaming, onCtrlC, exit, controllerRef]);
+  }, [streaming, onCtrlC, exit, controllerRef, shutdown]);
 
   const handleEsc = useCallback(() => {
     if (!(streaming && controllerRef.current)) {

package/src/tui/chat/useAttachment.ts

@@ -0,0 +1,74 @@
+import type { ImageAttachment } from 'mu-core';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { readClipboardImage } from '../../utils/clipboard';
+
+const ERROR_TIMEOUT_MS = 3000;
+
+export interface AttachmentState {
+  attachment: ImageAttachment | null;
+  attachmentError: string | null;
+  onPaste: () => void;
+  clear: () => void;
+}
+
+export function useAttachment(): AttachmentState {
+  const [attachment, setAttachment] = useState<ImageAttachment | null>(null);
+  const [attachmentError, setAttachmentError] = useState<string | null>(null);
+  const errorTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelErrorTimer = useCallback(() => {
+    if (errorTimerRef.current) {
+      clearTimeout(errorTimerRef.current);
+      errorTimerRef.current = null;
+    }
+  }, []);
+
+  // Cancel any pending error-clear timer if the component unmounts.
+  useEffect(() => cancelErrorTimer, [cancelErrorTimer]);
+
+  const onPaste = useCallback(() => {
+    cancelErrorTimer();
+    const img = readClipboardImage();
+    if (img) {
+      setAttachment(img);
+      setAttachmentError(null);
+      return;
+    }
+    setAttachmentError('No image on clipboard');
+    errorTimerRef.current = setTimeout(() => {
+      setAttachmentError(null);
+      errorTimerRef.current = null;
+    }, ERROR_TIMEOUT_MS);
+  }, [cancelErrorTimer]);
+
+  const clear = useCallback(() => {
+    cancelErrorTimer();
+    setAttachment(null);
+    setAttachmentError(null);
+  }, [cancelErrorTimer]);
+
+  return { attachment, attachmentError, onPaste, clear };
+}
+
+type PickerKind = 'model' | 'sessions' | null;
+
+export interface TogglesState {
+  showModelPicker: boolean;
+  showSessionPicker: boolean;
+  onTogglePicker: () => void;
+  onToggleSessionPicker: () => void;
+}
+
+/**
+ * At most one picker is visible at a time. Toggling on a picker while the
+ * other is open swaps to the new one rather than stacking modals.
+ */
+export function useToggles(): TogglesState {
+  const [picker, setPicker] = useState<PickerKind>(null);
+  return {
+    showModelPicker: picker === 'model',
+    showSessionPicker: picker === 'sessions',
+    onTogglePicker: useCallback(() => setPicker((p) => (p === 'model' ? null : 'model')), []),
+    onToggleSessionPicker: useCallback(() => setPicker((p) => (p === 'sessions' ? null : 'sessions')), []),
+  };
+}