mulmoclaude 0.1.0

package/src/utils/role/plugins.ts

@@ -0,0 +1,12 @@
+// Pure helpers for role → plugin queries.
+// Takes the role list as a parameter for testability.
+
+import type { Role } from "../../config/roles";
+import { TOOL_NAMES, type ToolName } from "../../config/toolNames";
+
+const GEMINI_PLUGINS = new Set<ToolName>([TOOL_NAMES.generateImage, TOOL_NAMES.presentDocument]);
+
+/** Whether the given role uses any plugin that requires a Gemini API key. */
+export function needsGemini(roles: Role[], roleId: string): boolean {
+  return (roles.find((r) => r.id === roleId)?.availablePlugins ?? []).some((p) => GEMINI_PLUGINS.has(p));
+}

package/src/utils/session/mergeSessions.ts

@@ -0,0 +1,103 @@
+// Pure helper: merge the two views of "sessions" that the sidebar
+// history pane shows — live in-memory sessions (from `sessionMap`)
+// and server-persisted summaries (from `/api/sessions`). Extracted
+// from `src/App.vue` as part of the cognitive-complexity refactor
+// tracked in #175.
+//
+// The merge is deterministic given the inputs: the test suite pins
+// every edge case we've hit (live-only, server-only, overlap,
+// server-side AI title vs local first-user-message, sort tie-breaks).
+
+import { isUserTextResponse } from "../tools/result";
+import type { SessionSummary, ActiveSession } from "../../types/session";
+
+// Build the summary shape the sidebar expects for a single live
+// session. Server-side data (AI-generated title, summary,
+// keywords) takes precedence over the local first-user-message
+// heuristic — otherwise opening an indexed session in a new tab
+// would regress the sidebar row to the raw first message.
+function buildLiveSummary(live: ActiveSession, serverEntry: SessionSummary | undefined): SessionSummary {
+  const firstUserMsg = live.toolResults.find(isUserTextResponse);
+  const preview = serverEntry?.preview || (firstUserMsg?.message ?? "");
+  const base: SessionSummary = {
+    id: live.id,
+    roleId: live.roleId,
+    startedAt: live.startedAt,
+    updatedAt: live.updatedAt,
+    preview,
+  };
+  // Fold every in-memory signal into isRunning so the sidebar spinner
+  // reacts as fast as the fastest source:
+  //   - serverEntry.isRunning: authoritative but arrives on a /api/sessions
+  //     refetch
+  //   - live.isRunning: mirrored from the server via refreshSessionStates;
+  //     may be ahead during the refetch window, and covers live-only
+  //     sessions with no serverEntry yet
+  //   - live.pendingGenerations: updates on the socket round-trip of a
+  //     generationStarted event, before any REST refetch
+  // OR them so any one is enough. `live.isRunning` is always defined on
+  // an ActiveSession, so the summary always carries a boolean here.
+  const pending = live.pendingGenerations ?? {};
+  const isRunning = !!serverEntry?.isRunning || live.isRunning || Object.keys(pending).length > 0;
+  // Carry summary / keywords ONLY if the server already has them.
+  // Object-spread with a conditional object keeps us from adding
+  // `undefined` values that would otherwise show up as explicit
+  // `summary: undefined` in a later shallow-copy.
+  return {
+    ...base,
+    ...(serverEntry?.summary !== undefined && { summary: serverEntry.summary }),
+    ...(serverEntry?.keywords !== undefined && {
+      keywords: serverEntry.keywords,
+    }),
+    isRunning,
+    ...(serverEntry?.hasUnread !== undefined && {
+      hasUnread: serverEntry.hasUnread,
+    }),
+    ...(serverEntry?.statusMessage !== undefined && {
+      statusMessage: serverEntry.statusMessage,
+    }),
+  };
+}
+
+// Compare two summaries for sort order. Newest `updatedAt` wins;
+// if updatedAt ties (same second-granularity mtime on two
+// server-only rows, say), fall back to `startedAt`. Exported so
+// tests can exercise the tie-break directly.
+export function compareSessionsByRecency(left: SessionSummary, right: SessionSummary): number {
+  const byUpdated = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+  if (byUpdated !== 0) return byUpdated;
+  return Date.parse(right.startedAt) - Date.parse(left.startedAt);
+}
+
+// Merge live sessions (in-memory, still editable) with server
+// summaries (from /api/sessions). Live sessions always win for
+// the same id — we prefer the local state we know is current —
+// but pull over the server's AI title / summary / keywords when
+// present. Pure, returns a new array; does not mutate inputs.
+export function mergeSessionLists(liveSessions: readonly ActiveSession[], serverSessions: readonly SessionSummary[]): SessionSummary[] {
+  const liveIds = new Set(liveSessions.map((session) => session.id));
+  const serverById = new Map<string, SessionSummary>(serverSessions.map((session) => [session.id, session]));
+  const liveSummaries = liveSessions.map((live) => buildLiveSummary(live, serverById.get(live.id)));
+  const serverOnly = serverSessions.filter((session) => !liveIds.has(session.id));
+  return [...liveSummaries, ...serverOnly].sort(compareSessionsByRecency);
+}
+
+// Apply a server-sent diff to the client's cached session list
+// (see issue #205). `diff` holds rows the server says have changed
+// since the client's last cursor — each replaces any existing row
+// with the same id, or is prepended if new. `deletedIds` removes
+// rows the server has forgotten; always empty today (no
+// session-delete code path exists) but the shape is plumbed through
+// so populating it becomes a server-only change later.
+//
+// Pure; returns a new array sorted by the same recency rule
+// `mergeSessionLists` uses, so the two are interchangeable at call
+// sites that don't care which they got.
+export function applySessionDiff(cache: readonly SessionSummary[], diff: readonly SessionSummary[], deletedIds: readonly string[]): SessionSummary[] {
+  const deleted = new Set(deletedIds);
+  const diffById = new Map<string, SessionSummary>(diff.map((session) => [session.id, session]));
+  const kept = cache.filter((session) => !deleted.has(session.id)).map((session) => diffById.get(session.id) ?? session);
+  const existingIds = new Set(kept.map((session) => session.id));
+  const added = diff.filter((session) => !existingIds.has(session.id));
+  return [...kept, ...added].sort(compareSessionsByRecency);
+}

package/src/utils/session/seedRoleDefault.ts

@@ -0,0 +1,35 @@
+// Seed a synthetic tool result when switching to a role that has a
+// "default view". Extracted from App.vue so the component stays lean.
+
+import { v4 as uuidv4 } from "uuid";
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import type { ActiveSession } from "../../types/session";
+import { BUILTIN_ROLE_IDS } from "../../config/roles";
+import { apiGet } from "../api";
+import { API_ROUTES } from "../../config/apiRoutes";
+import { pushResult, pushErrorMessage } from "./sessionHelpers";
+
+export async function maybeSeedRoleDefault(session: ActiveSession): Promise<void> {
+  if (session.roleId !== BUILTIN_ROLE_IDS.sourceManager) return;
+  // Pre-fetch guard: skip the network call entirely if the session
+  // already has content (user typed fast, or a previous seed ran).
+  if (session.toolResults.length > 0) return;
+  const response = await apiGet<{ sources?: unknown[] }>(API_ROUTES.sources.list);
+  if (!response.ok) {
+    if (session.toolResults.length === 0) {
+      const detail = response.status === 0 ? response.error : `HTTP ${response.status}`;
+      pushErrorMessage(session, `Could not preload sources (${detail}). Ask Claude to list them, or check the server log.`);
+    }
+    return;
+  }
+  const result: ToolResultComplete = {
+    uuid: uuidv4(),
+    toolName: "manageSource",
+    message: "Loaded source registry.",
+    title: "Information sources",
+    data: { sources: response.data.sources ?? [] },
+  };
+  if (session.toolResults.length > 0) return;
+  pushResult(session, result);
+  session.selectedResultUuid = result.uuid;
+}

package/src/utils/session/sessionEntries.ts

@@ -0,0 +1,121 @@
+// Pure helpers for reconstructing an `ActiveSession`'s runtime
+// shape from the `/api/sessions/:id` JSONL payload. Extracted from
+// `src/App.vue#loadSession` so the parse / select / timestamp-
+// resolution logic is unit-testable without mocking `fetch`.
+//
+// Tracks #175.
+
+import { makeTextResult } from "../tools/result";
+import { isTextEntry, isToolResultEntry, type ActiveSession, type SessionEntry, type SessionSummary } from "../../types/session";
+import { EVENT_TYPES } from "../../types/events";
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+
+// Walk the server's session entries and produce the flat
+// `toolResults` array the client keeps in `ActiveSession`. Drops
+// `session_meta` rows (they're metadata, not a result), converts
+// text entries into tool-result-shaped envelopes via
+// `makeTextResult`, and passes tool_result entries through verbatim.
+export function parseSessionEntries(entries: readonly SessionEntry[]): ToolResultComplete[] {
+  const out: ToolResultComplete[] = [];
+  for (const entry of entries) {
+    if (entry.type === EVENT_TYPES.sessionMeta) continue;
+    if (isTextEntry(entry)) {
+      out.push(makeTextResult(entry.message, entry.source));
+    } else if (isToolResultEntry(entry)) {
+      out.push(entry.result);
+    }
+  }
+  return out;
+}
+
+// Pick the `selectedResultUuid` the session should restore to.
+// Rules:
+//   1. If the URL carries `?result=<uuid>` AND that uuid actually
+//      exists in the loaded list, honour it verbatim. This lets
+//      bookmarks restore the exact result the user was viewing.
+//   2. Otherwise fall back to the heuristic: the most recent
+//      non-text tool result (images, wiki pages, etc. carry more
+//      visual information than bare text).
+//   3. If there are no non-text results, use the last result of
+//      any kind.
+//   4. If the list is empty, return null.
+export function resolveSelectedUuid(toolResults: readonly ToolResultComplete[], urlResult: string | null): string | null {
+  if (urlResult && toolResults.some((result) => result.uuid === urlResult)) {
+    return urlResult;
+  }
+  // Iterate backwards for the "last non-text" lookup so callers
+  // don't pay for an intermediate reverse copy.
+  for (let i = toolResults.length - 1; i >= 0; i--) {
+    if (toolResults[i].toolName !== "text-response") {
+      return toolResults[i].uuid;
+    }
+  }
+  const last = toolResults[toolResults.length - 1];
+  return last?.uuid ?? null;
+}
+
+// Decide the `startedAt` / `updatedAt` to seed the in-memory
+// ActiveSession with. We prefer the server summary's timestamps
+// so the restored session keeps its existing sidebar ordering;
+// we fall through to the current clock only if the server
+// summary is missing (e.g. freshly-created session that hasn't
+// round-tripped through `/api/sessions` yet).
+//
+// Keeping this logic named lets the test suite pin the
+// "updatedAt missing → fall back to startedAt" rule explicitly,
+// which was previously a fragile `??` chain buried in loadSession.
+export function resolveSessionTimestamps(serverSummary: SessionSummary | undefined, nowIso: string): { startedAt: string; updatedAt: string } {
+  const startedAt = serverSummary?.startedAt ?? nowIso;
+  const updatedAt = serverSummary?.updatedAt ?? startedAt;
+  return { startedAt, updatedAt };
+}
+
+// Spread toolResults evenly between startedAt and updatedAt to
+// approximate per-entry timestamps for sessions loaded from disk.
+// Real-time results will overwrite with Date.now() via pushResult.
+export function interpolateTimestamps(toolResults: readonly ToolResultComplete[], startedAt: string, updatedAt: string): Map<string, number> {
+  const timestamps = new Map<string, number>();
+  const startMs = new Date(startedAt).getTime();
+  const endMs = new Date(updatedAt).getTime();
+  toolResults.forEach((result, i) => {
+    const frac = toolResults.length > 1 ? i / (toolResults.length - 1) : 0;
+    timestamps.set(result.uuid, startMs + (endMs - startMs) * frac);
+  });
+  return timestamps;
+}
+
+// Build an ActiveSession from server-fetched entries + metadata.
+// Pure — the caller is responsible for inserting into sessionMap
+// and subscribing.
+export function buildLoadedSession(opts: {
+  id: string;
+  entries: readonly SessionEntry[];
+  defaultRoleId: string;
+  urlResult: string | null;
+  serverSummary: SessionSummary | undefined;
+  nowIso: string;
+}): ActiveSession {
+  const { id, entries, defaultRoleId, urlResult, serverSummary, nowIso } = opts;
+  const meta = entries.find((entry) => entry.type === EVENT_TYPES.sessionMeta);
+  const roleId = meta?.roleId ?? defaultRoleId;
+  const toolResults = parseSessionEntries(entries);
+  const selectedResultUuid = resolveSelectedUuid(toolResults, urlResult);
+  const { startedAt, updatedAt } = resolveSessionTimestamps(serverSummary, nowIso);
+  const resultTimestamps = interpolateTimestamps(toolResults, startedAt, updatedAt);
+
+  return {
+    id,
+    roleId,
+    toolResults,
+    resultTimestamps,
+    isRunning: serverSummary?.isRunning ?? false,
+    statusMessage: serverSummary?.statusMessage ?? "",
+    toolCallHistory: [],
+    selectedResultUuid,
+    hasUnread: serverSummary?.hasUnread ?? false,
+    startedAt,
+    updatedAt,
+    runStartIndex: toolResults.length,
+    pendingGenerations: {},
+  };
+}

package/src/utils/session/sessionFactory.ts

@@ -0,0 +1,22 @@
+// Pure factory for creating a blank ActiveSession.
+
+import type { ActiveSession } from "../../types/session";
+
+export function createEmptySession(id: string, roleId: string): ActiveSession {
+  const now = new Date().toISOString();
+  return {
+    id,
+    roleId,
+    toolResults: [],
+    resultTimestamps: new Map(),
+    isRunning: false,
+    statusMessage: "",
+    toolCallHistory: [],
+    selectedResultUuid: null,
+    hasUnread: false,
+    startedAt: now,
+    updatedAt: now,
+    runStartIndex: 0,
+    pendingGenerations: {},
+  };
+}

package/src/utils/session/sessionHelpers.ts

@@ -0,0 +1,99 @@
+// Pure session-mutation helpers extracted from App.vue.
+// These operate on ActiveSession objects directly — no Vue
+// reactivity, no imports from the component.
+
+import { v4 as uuidv4 } from "uuid";
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import type { ActiveSession } from "../../types/session";
+import { makeTextResult } from "../tools/result";
+import { shouldSelectAssistantText } from "../agent/toolCalls";
+
+/** Push a result and record its timestamp in one place. */
+export function pushResult(session: ActiveSession, result: ToolResultComplete): void {
+  session.toolResults.push(result);
+  session.resultTimestamps.set(result.uuid, Date.now());
+}
+
+/** Surface a server/transport error as a visible card in the session. */
+export function pushErrorMessage(session: ActiveSession, message: string): void {
+  const text = `[Error] ${message}`;
+  const errorResult: ToolResultComplete = {
+    uuid: uuidv4(),
+    toolName: "text-response",
+    message: text,
+    title: "Error",
+    data: { text, role: "assistant", transportKind: "text-rest" },
+  };
+  pushResult(session, errorResult);
+  session.selectedResultUuid = errorResult.uuid;
+}
+
+/** Append the user's message so it renders immediately. */
+export function beginUserTurn(session: ActiveSession, message: string): void {
+  session.updatedAt = new Date().toISOString();
+  pushResult(session, makeTextResult(message, "user"));
+  session.runStartIndex = session.toolResults.length;
+}
+
+/** Append text to the last assistant text-response if one exists.
+ *  Returns true if appended, false if a new card is needed. */
+export function appendToLastAssistantText(session: ActiveSession, text: string): boolean {
+  const last = session.toolResults[session.toolResults.length - 1];
+  const lastData = last?.data as { role?: string; text?: string } | undefined;
+  if (last?.toolName !== "text-response" || lastData?.role !== "assistant") {
+    return false;
+  }
+  lastData.text = (lastData.text ?? "") + text;
+  last.message = (last.message ?? "") + text;
+  return true;
+}
+
+/** Check if an incoming user text event is a duplicate of the last
+ *  user message (sent by this tab via beginUserTurn). */
+function isDuplicateUserText(session: ActiveSession, message: string): boolean {
+  const last = session.toolResults[session.toolResults.length - 1];
+  const lastData = last?.data as { role?: string; text?: string } | undefined;
+  return last?.toolName === "text-response" && lastData?.role === "user" && lastData?.text === message;
+}
+
+/** Handle an incoming text event (user or assistant) from the
+ *  agent's SSE/pubsub stream. Deduplicates user messages,
+ *  streams assistant text into the last card, and selects the
+ *  result when appropriate. */
+export function applyTextEvent(session: ActiveSession, message: string, source: "user" | "assistant"): void {
+  if (source === "user") {
+    if (!isDuplicateUserText(session, message)) {
+      pushResult(session, makeTextResult(message, "user"));
+      session.runStartIndex = session.toolResults.length;
+    }
+    return;
+  }
+  if (appendToLastAssistantText(session, message)) return;
+  const textResult = makeTextResult(message, "assistant");
+  pushResult(session, textResult);
+  if (shouldSelectAssistantText(session.toolResults, session.runStartIndex)) {
+    session.selectedResultUuid = textResult.uuid;
+  }
+}
+
+/** In-place update a result that was re-emitted by a plugin view
+ *  (e.g. after the user edits a chart config). */
+export function updateResult(session: ActiveSession, updatedResult: ToolResultComplete): void {
+  const index = session.toolResults.findIndex((r) => r.uuid === updatedResult.uuid);
+  if (index !== -1) {
+    Object.assign(session.toolResults[index], updatedResult);
+  }
+}
+
+/** Handle an incoming tool_result event: upsert into the session's
+ *  result list. Selects the result only on insert; in-place updates
+ *  preserve the user's current selection. */
+export function applyToolResultToSession(session: ActiveSession, result: ToolResultComplete): void {
+  const idx = session.toolResults.findIndex((r) => r.uuid === result.uuid);
+  if (idx >= 0) {
+    session.toolResults[idx] = result;
+  } else {
+    pushResult(session, result);
+    session.selectedResultUuid = result.uuid;
+  }
+}

package/src/utils/tools/dedup.ts

@@ -0,0 +1,17 @@
+// Deduplicate consecutive tool results that represent "full-state
+// refreshes" (e.g. a wiki page re-render after an edit). When two
+// adjacent results have the same toolName and both carry
+// `updating: true`, only the later one is kept. Text-response
+// cards are never collapsed — each is a distinct message.
+
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+
+export function deduplicateResults(all: ToolResultComplete[]): ToolResultComplete[] {
+  return all.filter((r, i) => {
+    if (r.toolName === "text-response") return true;
+    const next = all[i + 1];
+    if (!next) return true;
+    if (next.toolName !== r.toolName) return true;
+    return !(r.updating === true && next.updating === true);
+  });
+}

package/src/utils/tools/mcp.ts

@@ -0,0 +1,33 @@
+// Pure helpers for the MCP-tool sidebar state. The composable in
+// src/composables/useMcpTools wires these up to a Vue ref + a fetch
+// against /api/mcp-tools; here we keep just the rules so they can
+// be unit-tested without Vue or fetch.
+
+export interface ToolDefinitionMetadata {
+  description?: string;
+}
+
+// Filter a role's plugin list down to the tools that are still
+// enabled — i.e. not in the disabled set.
+export function availableToolsFor(rolePlugins: string[], disabled: Set<string>): string[] {
+  return rolePlugins.filter((name) => !disabled.has(name));
+}
+
+// Build a name → description map for the tools the current role can
+// see. Prefers the bundled tool definition's `description`, falling
+// back to the MCP tool's prompt when the bundled one is missing.
+// `getDefinition` is injected so tests can stub the local plugin
+// lookup without importing src/tools.
+export function toolDescriptionsFor(
+  rolePlugins: string[],
+  getDefinition: (name: string) => ToolDefinitionMetadata | null,
+  mcpDescriptions: Record<string, string>,
+): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const name of rolePlugins) {
+    const def = getDefinition(name);
+    const desc = def?.description ?? mcpDescriptions[name];
+    if (desc) map[name] = desc;
+  }
+  return map;
+}

package/src/utils/tools/pendingCalls.ts

@@ -0,0 +1,16 @@
+// Pure logic for "is this tool call still considered pending right
+// now?" — extracted so it can be unit-tested without spinning up a
+// Vue reactive scope. The composable in src/composables/usePendingCalls
+// pairs this with the timing / interval bookkeeping.
+
+import type { ToolCallHistoryItem } from "../../types/toolCallHistory";
+
+// A freshly-resolved call is held visible for this many milliseconds
+// after its result lands, so the spinner / loading row does not flash
+// off the screen if the response was very fast.
+export const PENDING_MIN_MS = 500;
+
+export function isCallStillPending(call: ToolCallHistoryItem, nowMs: number): boolean {
+  if (call.result === undefined && call.error === undefined) return true;
+  return nowMs < call.timestamp + PENDING_MIN_MS;
+}

package/src/utils/tools/result.ts

@@ -0,0 +1,40 @@
+// Pure helpers for `ToolResultComplete` shapes used across the
+// frontend. Kept dependency-free of Vue / DOM so they are trivially
+// unit-testable from `node:test`.
+
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import { v4 as uuidv4 } from "uuid";
+import { isRecord } from "../types";
+
+// Type guard: a text-response entry whose `data.role` is `"user"`.
+// Used by App.vue to find the first user message in a live session
+// when building the merged history list.
+export function isUserTextResponse(r: ToolResultComplete): boolean {
+  if (r.toolName !== "text-response") return false;
+  const data = r.data;
+  if (!isRecord(data)) return false;
+  return data.role === "user";
+}
+
+// Pull out the optional base64 image attached to a tool result, if
+// any. Returns `undefined` for results that have no `data.imageData`
+// or where it isn't a string.
+export function extractImageData(result: ToolResultComplete | undefined): string | undefined {
+  const data = result?.data;
+  if (isRecord(data) && typeof data.imageData === "string") {
+    return data.imageData;
+  }
+  return undefined;
+}
+
+// Build a synthetic text-response result for either a user or
+// assistant turn. Used by sendMessage and the chat history UI.
+export function makeTextResult(text: string, role: "user" | "assistant"): ToolResultComplete {
+  return {
+    uuid: uuidv4(),
+    toolName: "text-response",
+    message: text,
+    title: role === "user" ? "You" : "Assistant",
+    data: { text, role, transportKind: "text-rest" },
+  };
+}

package/src/utils/types.ts

@@ -0,0 +1,44 @@
+// Shared runtime type guards for the Vue frontend (#520).
+// Same API as server/utils/types.ts — kept in sync manually
+// until a shared packages/types workspace is introduced.
+
+/** Narrow `unknown` to a plain object (not null, not array). */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Narrow `unknown` to any object (not null, arrays allowed). */
+export function isObj(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** Non-empty string after trimming whitespace. */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/** Record whose values are all strings. */
+export function isStringRecord(value: unknown): value is Record<string, string> {
+  if (!isRecord(value)) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+
+/** String array (every element is a string). */
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/** Error-like object with a `code` property. */
+export function isErrorWithCode(value: unknown): value is { code: string; message?: string } {
+  return isRecord(value) && typeof value.code === "string";
+}
+
+/** Check that a record has a specific key with a string value. */
+export function hasStringProp<K extends string>(value: unknown, key: K): value is Record<K, string> & Record<string, unknown> {
+  return isRecord(value) && typeof value[key] === "string";
+}
+
+/** Check that a record has a specific key with a number value. */
+export function hasNumberProp<K extends string>(value: unknown, key: K): value is Record<K, number> & Record<string, unknown> {
+  return isRecord(value) && typeof value[key] === "number";
+}