mulmoclaude 0.1.0

package/src/types/events.ts

@@ -0,0 +1,16 @@
+// Single source of truth: @mulmobridge/protocol.
+//
+// This file re-exports so that ~30 server/frontend files that import
+// from "../../src/types/events.js" keep working without a mass rename.
+// New code should import directly from "@mulmobridge/protocol" when
+// it's in a package-eligible module (chat-service, bridges).
+
+export {
+  EVENT_TYPES,
+  type EventType,
+  GENERATION_KINDS,
+  type GenerationKind,
+  type GenerationEvent,
+  type PendingGeneration,
+  generationKey,
+} from "@mulmobridge/protocol";

package/src/types/fileTree.ts

@@ -0,0 +1,13 @@
+// TreeNode type — shared between FileTree.vue, FilesView.vue,
+// and composables (useFileTree, useFileSelection).
+// Extracted from FileTree.vue so .ts files can import it without
+// depending on a .vue module (which tsc can't resolve).
+
+export interface TreeNode {
+  name: string;
+  path: string;
+  type: "file" | "dir";
+  size?: number;
+  modifiedMs?: number;
+  children?: TreeNode[];
+}

package/src/types/notification.ts

@@ -0,0 +1,67 @@
+// Notification payload — shared by server (publish) and frontend (subscribe).
+
+export const NOTIFICATION_KINDS = {
+  todo: "todo",
+  scheduler: "scheduler",
+  agent: "agent",
+  journal: "journal",
+  push: "push",
+  bridge: "bridge",
+} as const;
+
+export type NotificationKind = (typeof NOTIFICATION_KINDS)[keyof typeof NOTIFICATION_KINDS];
+
+export const NOTIFICATION_ICONS: Record<NotificationKind, string> = {
+  todo: "check_circle",
+  scheduler: "event",
+  agent: "smart_toy",
+  journal: "auto_stories",
+  push: "notifications",
+  bridge: "chat",
+};
+
+export const NOTIFICATION_ACTION_TYPES = {
+  navigate: "navigate",
+  none: "none",
+} as const;
+
+export type NotificationActionType = (typeof NOTIFICATION_ACTION_TYPES)[keyof typeof NOTIFICATION_ACTION_TYPES];
+
+export const NOTIFICATION_VIEWS = {
+  todos: "todos",
+  scheduler: "scheduler",
+  files: "files",
+  chat: "chat",
+} as const;
+
+export type NotificationView = (typeof NOTIFICATION_VIEWS)[keyof typeof NOTIFICATION_VIEWS];
+
+export const NOTIFICATION_PRIORITIES = {
+  normal: "normal",
+  high: "high",
+} as const;
+
+export type NotificationPriority = (typeof NOTIFICATION_PRIORITIES)[keyof typeof NOTIFICATION_PRIORITIES];
+
+export type NotificationAction =
+  | {
+      type: typeof NOTIFICATION_ACTION_TYPES.navigate;
+      view: NotificationView;
+      path?: string;
+      sessionId?: string;
+      itemId?: string;
+    }
+  | { type: typeof NOTIFICATION_ACTION_TYPES.none };
+
+export interface NotificationPayload {
+  id: string;
+  kind: NotificationKind;
+  title: string;
+  body?: string;
+  icon?: string;
+  action: NotificationAction;
+  firedAt: string;
+  priority: NotificationPriority;
+  sessionId?: string;
+  transportId?: string;
+}

package/src/types/session.ts

@@ -0,0 +1,116 @@
+// Per-session client-side state and the on-disk envelope shapes
+// returned by the server's session routes.
+
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import { EVENT_TYPES, type PendingGeneration } from "./events";
+import type { ToolCallHistoryItem } from "./toolCallHistory";
+
+// ── Session origin (#486) ───────────────────────────────────
+
+export const SESSION_ORIGINS = {
+  human: "human",
+  scheduler: "scheduler",
+  skill: "skill",
+  bridge: "bridge",
+} as const;
+
+export type SessionOrigin = (typeof SESSION_ORIGINS)[keyof typeof SESSION_ORIGINS];
+
+const VALID_ORIGINS: ReadonlySet<string> = new Set(Object.values(SESSION_ORIGINS));
+
+export function isSessionOrigin(value: unknown): value is SessionOrigin {
+  return typeof value === "string" && VALID_ORIGINS.has(value);
+}
+
+// Server `/api/sessions` summary. Optional `summary` and `keywords`
+// are populated by the chat indexer (#123) when present.
+//
+// `updatedAt` is the most recent activity timestamp — taken from the
+// jsonl file's mtime on the server side and bumped whenever the
+// client appends a message in-memory. Used for the "most recently
+// touched" sort order in the session history sidebar (users expect
+// active sessions to float to the top, not to stay pinned in
+// creation order).
+export interface SessionSummary {
+  id: string;
+  roleId: string;
+  startedAt: string;
+  updatedAt: string;
+  preview: string;
+  summary?: string;
+  keywords?: string[];
+  /** Where this session originated. Missing = "human" (backward compat). */
+  origin?: SessionOrigin;
+  // Live state from the server session store (present when the
+  // session has an active in-memory entry on the server).
+  isRunning?: boolean;
+  hasUnread?: boolean;
+  statusMessage?: string;
+}
+
+// One line of a session jsonl as returned by `/api/sessions/:id`.
+// Generic envelope; concrete narrowed shapes below.
+export interface SessionEntry {
+  type?: string;
+  source?: string;
+  roleId?: string;
+  message?: string;
+  result?: ToolResultComplete;
+}
+
+export interface TextEntry extends SessionEntry {
+  source: "user" | "assistant";
+  type: typeof EVENT_TYPES.text;
+  message: string;
+}
+
+export interface ToolResultEntry extends SessionEntry {
+  source: "tool";
+  type: typeof EVENT_TYPES.toolResult;
+  result: ToolResultComplete;
+}
+
+export const isTextEntry = (e: SessionEntry): e is TextEntry =>
+  (e.source === "user" || e.source === "assistant") && e.type === EVENT_TYPES.text && typeof e.message === "string";
+
+export const isToolResultEntry = (e: SessionEntry): e is ToolResultEntry => e.source === "tool" && e.type === EVENT_TYPES.toolResult && e.result !== undefined;
+
+// In-memory session held in `sessionMap`. PR #88 introduced this so
+// multiple chats can run concurrently — `id` matches the `chatSessionId`
+// the server uses for the on-disk jsonl.
+export interface ActiveSession {
+  id: string;
+  roleId: string;
+  toolResults: ToolResultComplete[];
+  /** UUID → epoch ms. Recorded when each result is added to the
+   *  session — either from a real-time pubsub event or from
+   *  loading a saved session. For saved sessions, the session's
+   *  `startedAt` is used as a baseline (individual per-entry
+   *  timestamps aren't persisted in the JSONL yet). */
+  resultTimestamps: Map<string, number>;
+  isRunning: boolean;
+  statusMessage: string;
+  toolCallHistory: ToolCallHistoryItem[];
+  selectedResultUuid: string | null;
+  hasUnread: boolean;
+  startedAt: string;
+  // Bumped whenever the user sends a new message in this session.
+  // Used by `mergedSessions` to sort the sidebar history list by
+  // "most recently touched" rather than "created first".
+  updatedAt: string;
+  // Index into `toolResults` at which the current run's outputs begin.
+  // Rewritten on every user turn by `beginUserTurn`; consumed by
+  // `shouldSelectAssistantText` to decide whether a trailing text
+  // reply should become the selected canvas result. Lives on the
+  // session (not on the subscription closure) so updates on turn N+1
+  // are visible to the reused subscription callback.
+  runStartIndex: number;
+  /**
+   * In-flight background generations triggered by a plugin view (e.g.
+   * MulmoScript image/audio/movie renders). Keyed by
+   * `generationKey(kind, filePath, key)` (opaque identity, not parsed
+   * back); the value carries the decomposed (kind, filePath, key) so
+   * views read those fields directly. Empty map = no background work.
+   */
+  pendingGenerations: Record<string, PendingGeneration>;
+}

package/src/types/sse.ts

@@ -0,0 +1,90 @@
+// Server-sent events delivered by `POST /api/agent`. The frontend
+// reads these off the SSE stream and dispatches into the active
+// session's state.
+
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import { EVENT_TYPES, type GenerationKind } from "./events";
+
+export interface SseToolCall {
+  type: typeof EVENT_TYPES.toolCall;
+  toolUseId: string;
+  toolName: string;
+  args: unknown;
+}
+
+export interface SseToolCallResult {
+  type: typeof EVENT_TYPES.toolCallResult;
+  toolUseId: string;
+  content: string;
+}
+
+export interface SseStatus {
+  type: typeof EVENT_TYPES.status;
+  message: string;
+}
+
+export interface SseSwitchRole {
+  type: typeof EVENT_TYPES.switchRole;
+  roleId: string;
+}
+
+export interface SseText {
+  type: typeof EVENT_TYPES.text;
+  message: string;
+  source?: "user" | "assistant";
+}
+
+export interface SseToolResult {
+  type: typeof EVENT_TYPES.toolResult;
+  result: ToolResultComplete;
+}
+
+export interface SseRolesUpdated {
+  type: typeof EVENT_TYPES.rolesUpdated;
+}
+
+export interface SseError {
+  type: typeof EVENT_TYPES.error;
+  message: string;
+}
+
+/** Sent on the session channel when the agent run finishes. */
+export interface SseSessionFinished {
+  type: typeof EVENT_TYPES.sessionFinished;
+}
+
+/**
+ * Plugin-initiated background work (e.g. MulmoScript image / audio /
+ * movie render) started. The client records this in
+ * `session.pendingGenerations` so the sidebar busy indicator stays
+ * lit even when the originating view isn't mounted.
+ */
+export interface SseGenerationStarted {
+  type: typeof EVENT_TYPES.generationStarted;
+  kind: GenerationKind;
+  filePath: string;
+  key: string;
+}
+
+/** Companion event to `SseGenerationStarted` — the work completed
+ *  (or failed; `error` populated). */
+export interface SseGenerationFinished {
+  type: typeof EVENT_TYPES.generationFinished;
+  kind: GenerationKind;
+  filePath: string;
+  key: string;
+  error?: string;
+}
+
+export type SseEvent =
+  | SseToolCall
+  | SseToolCallResult
+  | SseStatus
+  | SseSwitchRole
+  | SseText
+  | SseToolResult
+  | SseRolesUpdated
+  | SseError
+  | SseSessionFinished
+  | SseGenerationStarted
+  | SseGenerationFinished;

package/src/types/toolCallHistory.ts

@@ -0,0 +1,13 @@
+// One row of the right-side tool-call history pane. Lifted out of
+// `src/components/RightSidebar.vue` so non-component code (the
+// session domain types, the pending-calls helper, etc.) can refer
+// to it without depending on a Vue file.
+
+export interface ToolCallHistoryItem {
+  toolUseId: string;
+  toolName: string;
+  args: unknown;
+  timestamp: number;
+  result?: string;
+  error?: string;
+}

package/src/utils/agent/eventDispatch.ts

@@ -0,0 +1,74 @@
+// Pure dispatcher: maps an SseEvent into mutations on an ActiveSession
+// via the AgentEventContext adapter. No Vue refs, no component scope.
+
+import type { ActiveSession } from "../../types/session";
+import type { SseEvent } from "../../types/sse";
+import { EVENT_TYPES, generationKey } from "../../types/events";
+import { findPendingToolCall, toToolCallEntry } from "./toolCalls";
+import { pushErrorMessage, applyTextEvent, applyToolResultToSession } from "../session/sessionHelpers";
+
+export interface AgentEventContext {
+  session: ActiveSession;
+  setCurrentRoleId: (roleId: string) => void;
+  onRoleChange: () => void;
+  refreshRoles: () => Promise<void>;
+  scrollSidebarToBottom: () => void;
+  onGenerationsDrained: () => void;
+}
+
+export async function applyAgentEvent(event: SseEvent, ctx: AgentEventContext): Promise<void> {
+  const { session } = ctx;
+  switch (event.type) {
+    case EVENT_TYPES.toolCall:
+      session.toolCallHistory.push(toToolCallEntry(event));
+      ctx.scrollSidebarToBottom();
+      return;
+    case EVENT_TYPES.toolCallResult: {
+      const entry = findPendingToolCall(session.toolCallHistory, event.toolUseId);
+      if (entry) entry.result = event.content;
+      ctx.scrollSidebarToBottom();
+      return;
+    }
+    case EVENT_TYPES.status:
+      session.statusMessage = event.message;
+      return;
+    case EVENT_TYPES.switchRole:
+      setTimeout(() => {
+        ctx.setCurrentRoleId(event.roleId);
+        ctx.onRoleChange();
+      }, 0);
+      return;
+    case EVENT_TYPES.rolesUpdated:
+      await ctx.refreshRoles();
+      return;
+    case EVENT_TYPES.text:
+      applyTextEvent(session, event.message, event.source ?? "assistant");
+      return;
+    case EVENT_TYPES.toolResult:
+      applyToolResultToSession(session, event.result);
+      return;
+    case EVENT_TYPES.error:
+      console.error("[agent] error event:", event.message);
+      pushErrorMessage(session, event.message);
+      return;
+    case EVENT_TYPES.sessionFinished:
+      return;
+    case EVENT_TYPES.generationStarted: {
+      const mapKey = generationKey(event.kind, event.filePath, event.key);
+      session.pendingGenerations[mapKey] = {
+        kind: event.kind,
+        filePath: event.filePath,
+        key: event.key,
+      };
+      return;
+    }
+    case EVENT_TYPES.generationFinished: {
+      const mapKey = generationKey(event.kind, event.filePath, event.key);
+      delete session.pendingGenerations[mapKey];
+      if (Object.keys(session.pendingGenerations).length === 0) {
+        ctx.onGenerationsDrained();
+      }
+      return;
+    }
+  }
+}

package/src/utils/agent/request.ts

@@ -0,0 +1,55 @@
+// Request-body construction and dispatch for `POST /api/agent`.
+
+import type { Role } from "../../config/roles";
+import { API_ROUTES } from "../../config/apiRoutes";
+import { apiFetchRaw } from "../api";
+
+export interface AgentRequestBodyParams {
+  message: string;
+  role: Role;
+  chatSessionId: string;
+  selectedImageData?: string;
+}
+
+export interface AgentRequestBody {
+  message: string;
+  roleId: string;
+  chatSessionId: string;
+  selectedImageData: string | undefined;
+}
+
+export function buildAgentRequestBody(params: AgentRequestBodyParams): AgentRequestBody {
+  return {
+    message: params.message,
+    roleId: params.role.id,
+    chatSessionId: params.chatSessionId,
+    selectedImageData: params.selectedImageData,
+  };
+}
+
+/** POST the agent request body and return the response.
+ *  On network or HTTP error, returns a descriptive error string
+ *  instead. The caller decides how to surface it. */
+export async function postAgentRun(body: AgentRequestBody): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    const response = await apiFetchRaw(API_ROUTES.agent.run, {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!response.ok) {
+      const errBody = await response.text().catch(() => "");
+      return {
+        ok: false,
+        error: `Server error ${response.status}: ${errBody.slice(0, 200)}`,
+      };
+    }
+    return { ok: true };
+  } catch (e) {
+    console.error("[agent] fetch error:", e);
+    return {
+      ok: false,
+      error: e instanceof Error ? e.message : "Connection error.",
+    };
+  }
+}

package/src/utils/agent/toolCalls.ts

@@ -0,0 +1,62 @@
+// Pure helpers for the agent's tool-call history manipulation
+// pulled out of `src/App.vue#sendMessage`. Each function is
+// single-purpose, testable in isolation, and side-effect-free.
+//
+// Extracted as part of the cognitive-complexity refactor tracked
+// in #175.
+
+import type { ToolCallHistoryItem } from "../../types/toolCallHistory";
+import type { SseToolCall } from "../../types/sse";
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+
+// Convert an SSE tool_call event into a ToolCallHistoryItem ready
+// to push onto a session's toolCallHistory. Pure.
+export function toToolCallEntry(event: SseToolCall): ToolCallHistoryItem {
+  return {
+    toolUseId: event.toolUseId,
+    toolName: event.toolName,
+    args: event.args,
+    timestamp: Date.now(),
+  };
+}
+
+// When an SSE `tool_call_result` event arrives, the server tells
+// us which tool call it belongs to via `toolUseId`. Find the most
+// recent matching history entry that's still **pending** (no
+// result, no error) and return it so the caller can attach the
+// payload.
+//
+// Newest-first: scanning in reverse is intentional — two calls to
+// the same tool within one run would otherwise attach the new
+// result to the earlier entry. Reverse scan always picks the
+// freshest pending entry, matching the server's LIFO ordering.
+//
+// Returns `undefined` when no pending call matches (race / retry /
+// late-arriving event). Pure.
+export function findPendingToolCall(history: readonly ToolCallHistoryItem[], toolUseId: string): ToolCallHistoryItem | undefined {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const entry = history[i];
+    if (entry.toolUseId === toolUseId && entry.result === undefined && entry.error === undefined) {
+      return entry;
+    }
+  }
+  return undefined;
+}
+
+// Decide whether a newly-arrived assistant text message should
+// become the selected canvas result. Rule: yes, iff no plugin
+// tool result has landed during this run. A plugin result — e.g.
+// an image, a todo list update — is visually richer than a bare
+// text response and should stay selected once emitted.
+//
+// `runStartIndex` is the index into `toolResults` at which the
+// current run's outputs begin. Results before that index belong
+// to previous turns and don't count.
+//
+// Pure — returns a boolean for the caller to act on.
+export function shouldSelectAssistantText(toolResults: readonly ToolResultComplete[], runStartIndex: number): boolean {
+  for (let i = runStartIndex; i < toolResults.length; i++) {
+    if (toolResults[i].toolName !== "text-response") return false;
+  }
+  return true;
+}