mulmoterminal 1.11.1 → 2.0.0

package/README.md

@@ -2,6 +2,13 @@
 
 **Run a whole team of coding agents from your browser — and actually keep up with them.**
 
+### 📖 Documentation — **[receptron.github.io/mulmoterminal](https://receptron.github.io/mulmoterminal/)**
+
+- **User guide:** [English](https://receptron.github.io/mulmoterminal/guide/en/) — the grid
+  view, everyday workflows, the full feature list, configuration, and mobile push notifications.
+- **ユーザーガイド:** [日本語](https://receptron.github.io/mulmoterminal/guide/ja/) —
+  グリッドの使い方・日々のワークフロー・機能一覧・設定・スマホ通知の設定はこちら。
+
 ![MulmoTerminal — a grid of live Claude Code sessions, each color-coded by state, updating in real time](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/hero.gif)
 
 MulmoTerminal turns [Claude Code](https://claude.com/claude-code) (and OpenAI's **Codex**)
@@ -14,12 +21,6 @@ ping to your phone when a task finishes. One `npx` command, no Electron, no conf
 npx mulmoterminal        # starts on http://localhost:34567 and opens your browser
 ```
 
-- 📖 **User guide:** [English](https://receptron.github.io/mulmoterminal/guide/en/) — the
-  grid view, everyday workflows, the full feature list, configuration, and mobile push
-  notifications.
-- 📖 **ユーザーガイド:** [日本語](https://receptron.github.io/mulmoterminal/guide/ja/) —
-  グリッドの使い方・日々のワークフロー・機能一覧・設定・スマホ通知の設定はこちら。
-
 ![MulmoTerminal's grid view — four live Claude sessions running side by side, each in its own color-coded project](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-2x2-live.png)
 
 *The grid is a **cockpit for parallel agents** — here, four live Claude sessions, each in its own color-coded project. Every cell's header carries what you need to triage at a glance: **model · context %**, **token counts** (`⇡in ⇣out`), the **git branch / changes** chip, and an AI summary of what the agent is doing. A cell's **border color signals state** — working / done (blue), needs-you (amber — e.g. waiting on a permission), idle — with an attention chime so a stuck cell off-screen still pulls you back. Supervise many; only step in where you're called.*
@@ -78,6 +79,34 @@ asks the local server to open the OS file dialog and inserts the chosen path (wo
 browser, including Chrome). The path is inserted at the cursor — it is not submitted, so you
 can review it first.
 
+<a id="clicking-a-file-path"></a>
+
+**Clicking a file path** — the other direction. A path an agent *prints* becomes a link, and
+**what it opens is chosen by its extension**, so each kind arrives as the thing it is rather
+than as bytes (files within the session's working directory only):
+
+| A clicked … | opens as |
+|---|---|
+| `.md` `.markdown` | **rendered** markdown in a new tab — the same sandboxed `…/md` HTML the Files preview uses. It follows your system light/dark setting, since under the sandbox CSP it can't ask the app which theme is on |
+| `.json` | **indented** in a new tab (Chrome and Safari otherwise show one long line) |
+| `.csv` `.tsv` | a **table** in a new tab, with a sticky header that scrolls inside its own box |
+| source, config, logs, and `.txt` — 46 extensions | the app's own **Files** view (`/files?path=`), where CodeMirror highlights it, the tree is right there, and it can be edited |
+| everything else — images, PDF, SVG, HTML, video | raw bytes in a new tab, which the browser renders better than an editor would |
+
+Highlighting in the Files view covers the JS/TS family, JSON and Markdown (the modes
+`cmEditor.ts` bundles); other languages open as plain text.
+
+This set is **deliberately asymmetric** with the set the server serves as viewable text —
+`.md` goes to the rendered viewer rather than the Files view, `.txt` does the opposite, and
+dotfiles are server-only. The 45 extensions both sides agree on live in
+`common/sourceExtensions.ts`, each side adds its own extras, and
+`test/common/sourceExtensions.spec.ts` pins the asymmetry so it isn't "fixed" into symmetry.
+
+> **Changing this?** The routing table is `ROUTE_BY_EXTENSION` / `IN_APP_EXTENSIONS` in
+> `src/composables/terminalFilePathLinkProvider.ts`. Update this section, the
+> `docs/guide/{en,ja}/features.md` row, and the link table in `docs/terminal-notes.md`
+> together — all three went stale once already (#834).
+
 ---
 
 ## Install & run
@@ -413,10 +442,12 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `soundFile`  | Absolute path to a custom **attention sound** (played when a session needs attention). Empty/unset uses the built-in synthesized chime. |
 | `prRepos`    | `owner/repo` entries whose open PRs/issues the cross-repo **PRs & Issues** view aggregates (via your `gh` login). |
 | `launchers`  | `{ label, command }` entries offered in a grid cell's launcher besides Claude — a plain shell, `codex`, any interactive command. |
+| `quickCommands` | `{ label, text, agents? }` phrases the **phone** offers as chips on a session's terminal view. Tapping one puts `text` in the input box; it is not sent until you press send. `agents` (`"claude"` / `"codex"` / `"shell"`) scopes a chip to session kinds — omit it to offer the chip everywhere. Empty by default. |
 | `userMcpServers` | `{ id, url }` HTTP MCP servers merged into the **single-view** Claude session's `--mcp-config` (a `localhost` URL is reached over `host.docker.internal` in the Docker sandbox). Takes effect on the next session. |
 | `buttons`    | Header action buttons — see [Header buttons](#header-buttons). Omit to keep the defaults; set to replace them. |
 | `chips`      | Header info chips. Omit to keep the default set; `[]` hides all built-ins. |
-| `pushEnabled` | `true` to send a **Web Push** to your registered devices when a background task finishes. Off by default; only sends while the **RemoteHost** channel is connected (see below). |
+| `pushEnabled` | `true` to send a **Web Push** to your registered devices. Off by default; only sends while the **RemoteHost** channel is connected (see below). The master switch — `pushKinds` picks which moments. |
+| `pushKinds` | Which moments push: `"finished"` (a turn ended, ✅) and/or `"waiting"` (the agent stopped to ask — a permission prompt or a question, ❓, **once per prompt**). Omit to keep both; `[]` for none. A kind added in a later version stays off until you tick it. |
 | `worklogEnabled` | `true` to run the built-in **dev worklog** batch (see below). Off by default (each run spawns an LLM session, so it costs tokens). |
 | `worklogIntervalHours` | Worklog cadence in hours (default `6`, clamped to `1`–`168`). |
 | `terminalSubmit` | Which bytes Claude reads as **submit** vs **newline**: `"cr"` (default — Enter submits, Shift+Enter makes a newline) or `"esc-cr"` (for a Claude Code rebound the other way). Applies to the keyboard **and** the phone remote-view submit, for **Claude sessions only** (shell/codex keep plain Enter). See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#terminal-submit). |
@@ -781,7 +812,12 @@ Favorited collections get their own toolbar buttons.
   pages so you notice an off-screen cell that needs you.
 - **Zoom & filmstrip** — a cell's **⤢** enlarges one agent while the rest shrink to
   thumbnails in a bottom **filmstrip**; click a thumbnail to switch, **⤡** to return to the
-  grid — so you can flip between "see everything" and "focus on one" in a click.
+  grid — so you can flip between "see everything" and "focus on one" in a click. While
+  zoomed, keys you bind walk the enlargement along the on-screen order without reaching for
+  the mouse — **opt-in, nothing is bound by default**, since any bound key is taken from the
+  terminal underneath. Add a `keymap` to `~/.mulmoterminal/config.json`; see the
+  [guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#keymap)
+  for the syntax, the action list, and combinations a browser can never bind.
 
 ![Zoom — one agent enlarged, the others as a filmstrip along the bottom](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-zoom.png)
 
@@ -996,15 +1032,19 @@ same-origin-guarded.
 
 | Endpoint | Purpose |
 | -------- | ------- |
-| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `userMcpServers`, `providers`). |
+| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `quickCommands`, `userMcpServers`, `providers`). |
 | `GET /api/sound` · `/api/dir-sound?cwd=` · `/api/dir-config?cwd=` | Custom / per-directory attention sound + per-dir config. |
 | `GET /api/launch-options` | The Anthropic-compatible backends this server can reach, each with its models and — when it can't — the reason. Reports the **name** of the env var a key is read from, never the key. |
 | `GET /api/notifications`(`/history`) · `POST /api/notifications/:id/clear` | Notification feed. |
 | `POST /api/transcribe`(`/model`…) | Voice-input transcription (Whisper, macOS). |
 | `POST /api/translation` | Runtime UI-string translation. |
-| `GET /api/remote-host/status` · `POST /api/remote-host/{connect,disconnect}` | Companion phone-client link. |
+| `GET /api/remote-host/status` · `POST /api/remote-host/{connect,disconnect}` | Companion phone-client link. Each response carries the command channel's `health` (`online` / `reconnecting` / `offline`, plus the last listener error), so the toolbar shows a dropped channel instead of the last state it happened to fetch. |
 | `POST /api/open-dir` · `POST /api/pick-file` | Reveal a dir in Finder/Explorer; OS file-picker → path (`{ directory: true }` opens the folder picker — used by the launcher's Working-directory 📁 button). |
 
+The phone itself uses **none** of these routes — it reaches the host over Firestore command
+docs, not HTTP. Every command it can send, and the shapes it gets back, are in
+[`docs/remote-host-protocol.md`](docs/remote-host-protocol.md).
+
 ### WebSocket: `/ws` (terminal)
 
 A raw WebSocket carrying the terminal stream for one session. One PTY per
@@ -1277,6 +1317,10 @@ src/
   composables/                  useSessions, usePubSub, useGitStatus, useCost,
                                 useChatLauncher, useFilesView, useWikiBrowse,
                                 useCollectionBrowse, useNotifications, useVoiceInput, …
+common/           Shared by server/ and src/ — both tsconfigs include it, so a value or
+                  wire type either side decides from belongs HERE, never mirrored in both:
+                  dirChrome.ts, ghItems.ts, gitStatus.ts, launchOptions.ts, shortcuts.ts,
+                  sourceExtensions.ts, modelPresets.ts, modelIds.ts, theme*.ts, …
 vite.config.ts    Dev proxy for /ws (+ /ws/codex, /ws/launch, /ws/run), /ws/pubsub, /api, /artifacts
 vitest.config.ts  jsdom test environment
 ```

package/common/dirChrome.ts

@@ -18,3 +18,18 @@ export interface DirChrome {
   dotColor: string | null;
   buttonColor: string | null;
 }
+
+// "Nothing configured" — the base every DirConfig/PublicDirConfig empty spreads, so adding
+// a field above can't leave one side's default silently missing. Readonly because it is now
+// one object behind both sides' defaults, where it used to be a literal per file: a caller
+// that assigned it somewhere mutable would corrupt every later "no config here".
+export const EMPTY_DIR_CHROME: Readonly<DirChrome> = {
+  name: null,
+  badgeColor: null,
+  headerColor: null,
+  headerTextColor: null,
+  cellColor: null,
+  cellBorderColor: null,
+  dotColor: null,
+  buttonColor: null,
+};

package/common/firebaseConfig.ts

@@ -0,0 +1,15 @@
+// Web config for the shared `mulmoserver` Firebase project, used by the remote-host
+// command channel from BOTH sides: the server's session controller seeds its app with
+// it, and the browser's does the same.
+//
+// The values are NOT secrets — they identify the project to the client SDK, and access
+// is gated by Firestore security rules. Safe to commit. Firestore must be in Native mode.
+export const firebaseConfig = {
+  apiKey: "AIzaSyC5IrhcCtfVQ4nZeI89Owa7da_D-It0b9s",
+  authDomain: "mulmoserver.firebaseapp.com",
+  projectId: "mulmoserver",
+  storageBucket: "mulmoserver.firebasestorage.app",
+  messagingSenderId: "830257137330",
+  appId: "1:830257137330:web:5cb8db01ae61b5d161abab",
+  measurementId: "G-Y75JGK1G4T",
+} as const;

package/common/ghItems.ts

@@ -0,0 +1,43 @@
+// What GET /api/prs and GET /api/issues answer with — the wire shapes shared across the
+// build boundary so the server's `gh` aggregation and the PrsOverlay that renders it can't
+// drift. The normalizing/rollup logic stays server-side (git/ghItem.ts, git/prs.ts).
+
+/** The fields every `gh` list row shares: identity (number, url) and display text. */
+export interface GhItemBase {
+  number: number;
+  title: string;
+  author: string;
+  updatedAt: string;
+  url: string;
+}
+
+export type IssueItem = GhItemBase;
+
+/** Collapsed statusCheckRollup: any failure wins, else any unfinished check → pending. */
+export type CiState = "passing" | "failing" | "pending" | "none";
+
+export interface PrItem extends GhItemBase {
+  isDraft: boolean;
+  review: string | null; // gh reviewDecision (APPROVED / CHANGES_REQUESTED / REVIEW_REQUIRED / null)
+  ci: CiState;
+}
+
+export interface RepoPrs {
+  repo: string;
+  prs?: PrItem[];
+  error?: string;
+  // True when the repo has at least PR_LIMIT open PRs, so the list may be incomplete —
+  // surfaced in the UI so a truncated view isn't mistaken for full coverage.
+  truncated?: boolean;
+}
+
+export interface RepoIssues {
+  repo: string;
+  issues?: IssueItem[];
+  error?: string;
+  // True when the repo has more than ISSUE_LIMIT open issues, so the list is capped —
+  // the UI then links to the repo's issues page for the rest.
+  truncated?: boolean;
+  // The repo's GitHub issues page, used as the "see the rest" target when truncated.
+  url?: string;
+}

package/common/gitStatus.ts

@@ -0,0 +1,11 @@
+// What GET /api/git-status answers with — the wire shape shared across the build
+// boundary so the server's reader and the client's poller can't drift.
+export interface GitStatus {
+  repo: boolean;
+  branch: string | null; // null when detached or non-repo
+  detached: boolean;
+  dirty: number; // uncommitted entries (incl. untracked)
+  ahead: number; // commits on HEAD not on the upstream
+  behind: number; // commits on the upstream not on HEAD
+  upstream: boolean; // HEAD has a tracking branch (ahead/behind are meaningful)
+}

package/common/isRecord.ts

@@ -0,0 +1,13 @@
+import { isObject } from "graphai";
+
+// The guard both sides use before reading named fields off parsed JSON (config files, API
+// responses, JSONL transcripts, request bodies). It was hand-copied into 29 files before this.
+//
+// Arrays are excluded deliberately, and that is not a nicety: TypeScript itself refuses
+// `const r: Record<string, unknown> = []` ("index signature for type 'string' is missing"), so a
+// guard that narrows an array to Record is telling the compiler something untrue — and callers
+// that go on to `Object.entries()` the value would silently walk array indices as field names.
+//
+// graphai's own `isPlainObject` is exactly this (it also rejects Map/Date/class instances), but
+// it is not exported from the package root, so the array check stays here.
+export const isRecord = (value: unknown): value is Record<string, unknown> => isObject(value) && !Array.isArray(value);

package/common/keymap.ts

@@ -0,0 +1,158 @@
+// The user-defined keyboard shortcuts, in `~/.mulmoterminal/config.json` under `keymap`.
+//
+// There are NO defaults: an absent or empty `keymap` means the shortcuts are OFF. Every
+// binding is something the user opted into, because any key this claims is a key the
+// terminal underneath stops receiving — that trade is the user's to make, not ours.
+//
+// The server sanitizes and persists it; the browser matches keydowns against it. One
+// definition here so the accepted syntax can't drift between the two.
+//
+//   "keymap": { "zoom-next": "PageDown", "zoom-prev": "Shift+PageUp" }
+
+// Actions a key can be bound to. Adding one here is all it takes for the config to accept it.
+export const KEYMAP_ACTIONS = ["zoom-toggle", "zoom-next", "zoom-prev", "next-attention", "terminal-new", "terminal-new-adjacent", "terminal-close"] as const;
+export type KeymapAction = (typeof KEYMAP_ACTIONS)[number];
+
+export const isKeymapAction = (value: unknown): value is KeymapAction => typeof value === "string" && (KEYMAP_ACTIONS as readonly string[]).includes(value);
+
+// action -> binding string. Absent action = unbound = that shortcut does nothing.
+export type Keymap = Partial<Record<KeymapAction, string>>;
+
+// A parsed binding. `key` is matched against `KeyboardEvent.key` exactly as the browser
+// reports it, so it is case-sensitive for printable characters ("a" and "A" differ, the
+// latter implying Shift).
+export interface KeyBinding {
+  key: string;
+  shift: boolean;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+}
+
+// Modifier spellings accepted in a binding string, mapped to the flag they set. "Cmd",
+// "Command" and "Meta" are the same modifier; "Option" is macOS's name for Alt.
+const MODIFIERS: Record<string, keyof Omit<KeyBinding, "key">> = {
+  shift: "shift",
+  alt: "alt",
+  option: "alt",
+  ctrl: "ctrl",
+  control: "ctrl",
+  meta: "meta",
+  cmd: "meta",
+  command: "meta",
+};
+
+// Parse "Shift+PageUp" into its parts, or null when the string is malformed (empty, no
+// key left after the modifiers, an unknown modifier, or a duplicate one). Callers treat
+// null as "unbound" rather than throwing: a typo in a hand-edited config must cost the
+// user that one shortcut, never the app.
+export function parseKeyBinding(input: string): KeyBinding | null {
+  const parts = input.split("+").map((part) => part.trim());
+  if (parts.length === 0 || parts.some((part) => part === "")) return null;
+  const key = parts[parts.length - 1];
+  const binding: KeyBinding = { key, shift: false, alt: false, ctrl: false, meta: false };
+  for (const part of parts.slice(0, -1)) {
+    const flag = MODIFIERS[part.toLowerCase()];
+    if (!flag || binding[flag]) return null; // unknown, or named twice
+    binding[flag] = true;
+  }
+  // A lone modifier ("Shift") binds nothing usable.
+  return MODIFIERS[key.toLowerCase()] ? null : binding;
+}
+
+// The structural shape of a keydown a binding is matched against. A real KeyboardEvent
+// satisfies it, and so does a plain test object — no DOM dependency.
+export interface KeymapKeyEvent {
+  key: string;
+  shiftKey: boolean;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+}
+
+// Every modifier must match exactly, so a binding on "PageDown" does NOT fire for
+// Shift+PageDown — that keystroke stays with the terminal (xterm's scrollback) unless the
+// user binds it too.
+export const matchesBinding = (binding: KeyBinding, e: KeymapKeyEvent): boolean =>
+  e.key === binding.key && e.shiftKey === binding.shift && e.altKey === binding.alt && e.ctrlKey === binding.ctrl && e.metaKey === binding.meta;
+
+// The action this keydown is bound to, or null. Bindings that fail to parse are skipped.
+export function actionForKey(keymap: Keymap, e: KeymapKeyEvent): KeymapAction | null {
+  for (const action of KEYMAP_ACTIONS) {
+    const raw = keymap[action];
+    if (raw === undefined) continue;
+    const binding = parseKeyBinding(raw);
+    if (binding && matchesBinding(binding, e)) return action;
+  }
+  return null;
+}
+
+// What is wrong with one `keymap` entry. `fatal` separates a typo the user clearly meant to
+// work (a binding we cannot parse — the shortcut would silently never fire) from an action
+// name we simply do not know, which is what a config written for a NEWER version looks like
+// and must stay loadable.
+export interface KeymapProblem {
+  action: string;
+  binding: unknown;
+  reason: string;
+  fatal: boolean;
+}
+
+// Report everything wrong with a `keymap`, for a caller that wants to tell the user instead
+// of quietly dropping entries. Pure: the caller decides whether to warn, throw, or exit.
+export function validateKeymap(input: unknown): KeymapProblem[] {
+  if (input === undefined || input === null) return [];
+  if (typeof input !== "object" || Array.isArray(input)) {
+    return [{ action: "keymap", binding: input, reason: "`keymap` must be an object of action -> key binding", fatal: true }];
+  }
+  const entries = Object.entries(input as Record<string, unknown>);
+  const bound = new Map<string, { action: KeymapAction; binding: string }[]>();
+  const problems = entries.flatMap(([action, binding]): KeymapProblem[] => {
+    if (!isKeymapAction(action)) {
+      return [{ action, binding, reason: `unknown action (known: ${KEYMAP_ACTIONS.join(", ")})`, fatal: false }];
+    }
+    if (typeof binding !== "string") return [{ action, binding, reason: "binding must be a string", fatal: true }];
+    const parsed = parseKeyBinding(binding);
+    if (parsed === null) {
+      return [{ action, binding, reason: 'unparseable key binding — expected e.g. "PageDown" or "Shift+PageUp"', fatal: true }];
+    }
+    // Grouped as PARSED, since "Shift+PageUp" and "shift+pageup" are one keystroke.
+    const key = canonicalBinding(parsed);
+    bound.set(key, [...(bound.get(key) ?? []), { action, binding }]);
+    return [];
+  });
+  return [...problems, ...duplicateWarnings(bound)];
+}
+
+// Two actions on one keystroke: only one can fire, so the others silently never work.
+//
+// The winner is decided the way `actionForKey` decides it — first in KEYMAP_ACTIONS order —
+// NOT by which came first in the config file. Reporting the config-order winner would name
+// the wrong action whenever the two orders disagree, which is worse than not naming one.
+function duplicateWarnings(bound: Map<string, { action: KeymapAction; binding: string }[]>): KeymapProblem[] {
+  return [...bound.values()].flatMap((claims) => {
+    if (claims.length < 2) return [];
+    const byDispatch = [...claims].sort((a, b) => KEYMAP_ACTIONS.indexOf(a.action) - KEYMAP_ACTIONS.indexOf(b.action));
+    const [winner, ...losers] = byDispatch;
+    return losers.map(({ action, binding }) => ({
+      action,
+      binding,
+      reason: `same keystroke as \`${winner.action}\` — only \`${winner.action}\` will fire`,
+      fatal: false,
+    }));
+  });
+}
+
+// A binding's identity as a keystroke, for spotting two actions that claim the same one.
+const canonicalBinding = (b: KeyBinding): string => `${b.shift ? "S" : ""}${b.alt ? "A" : ""}${b.ctrl ? "C" : ""}${b.meta ? "M" : ""}|${b.key}`;
+
+// Keep only known actions bound to a parseable, non-empty string. Unknown keys and
+// malformed bindings are dropped rather than rejecting the whole map, matching how the
+// rest of the config treats one bad entry.
+export function sanitizeKeymap(input: unknown): Keymap {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return {};
+  const entries = Object.entries(input as Record<string, unknown>).filter(
+    (entry): entry is [KeymapAction, string] => isKeymapAction(entry[0]) && typeof entry[1] === "string" && parseKeyBinding(entry[1]) !== null,
+  );
+  return Object.fromEntries(entries);
+}

package/common/launchAgent.ts

@@ -0,0 +1,15 @@
+// What the phone may ask the grid to start in a session's directory (#831). The host
+// validates against this list and the grid turns each into a cell, so both sides read it.
+//
+// Deliberately NOT the configured `launchers` list: those are arbitrary user commands, and
+// the phone picks from a fixed set the host can name. "shell" is the OS default shell, the
+// same thing the header's new-terminal button opens.
+export const LAUNCH_AGENTS = ["shell", "claude", "codex"] as const;
+
+export type LaunchAgent = (typeof LAUNCH_AGENTS)[number];
+
+export const isLaunchAgent = (value: unknown): value is LaunchAgent => LAUNCH_AGENTS.some((agent) => agent === value);
+
+// The pub/sub channel the grid listens on for these requests. The grid is browser state, so
+// the host cannot open a cell itself — it asks whichever tab is connected.
+export const LAUNCH_TERMINAL_CHANNEL = "launch-terminal";

package/common/launchOptions.ts

@@ -0,0 +1,24 @@
+// What GET /api/launch-options answers with: the backends this server can actually reach
+// right now, each with the models it can run (#584). The wire shape lives here so the
+// server's decision (config/launch-options.ts) and the client's picker can't drift.
+import type { ModelPreset } from "./modelPresets.js";
+
+export interface LaunchProviderOption {
+  id: string;
+  label: string;
+  // False when this server cannot start a session on it as configured.
+  ready: boolean;
+  // Why not, in resolveProvider's own words. Absent when ready.
+  reason?: string;
+  // The env var this provider's key is read from — the help needs to name it, and it is
+  // the NAME, never the value.
+  tokenEnv: string;
+  models: ModelPreset[];
+}
+
+export interface LaunchOptions {
+  providers: LaunchProviderOption[];
+  // True when at least one provider can be launched on. The picker hides itself otherwise:
+  // with no reachable backend there is nothing to choose between, only setup to explain.
+  anyReady: boolean;
+}

package/common/pushKinds.ts

@@ -0,0 +1,21 @@
+// The kinds of Web Push a session can raise. The server decides which one a hook warrants and
+// the settings UI offers them as checkboxes, so the list is a value both sides read.
+
+// Every kind that exists.
+//   finished — the turn ended, output is waiting to be reviewed.
+//   waiting  — the agent is blocked on input (a permission prompt or a question), so answering
+//              from the phone unblocks real work. Fires once per prompt, which on a long task
+//              that asks repeatedly is what makes pushes feel frequent (#850).
+export const PUSH_KINDS = ["finished", "waiting"] as const;
+
+export type PushKind = (typeof PUSH_KINDS)[number];
+
+// What a config with no `pushKinds` gets. Deliberately a SEPARATE list from PUSH_KINDS, not a
+// copy of it: a kind added later must NOT start notifying people who never asked for it.
+//
+// That is exactly how this setting came to be needed — `waiting` was added in 36e9e72 and
+// every user with push on began receiving it, with no way to decline. Add a new kind to
+// PUSH_KINDS so it can be switched on, and leave it out of here so it stays opt-in.
+export const DEFAULT_PUSH_KINDS: PushKind[] = ["finished", "waiting"];
+
+export const isPushKind = (value: unknown): value is PushKind => PUSH_KINDS.some((kind) => kind === value);

package/common/quickCommands.ts

@@ -0,0 +1,13 @@
+import type { SessionAgent } from "./sessionAgent.js";
+
+// A phrase the user sends often, offered as a chip on the phone's terminal view (#830).
+// The server validates and stores it; the settings UI edits it — both decide from this
+// shape, so it is defined once here rather than mirrored on each side.
+//
+// `label` is the chip's face and `text` what it inserts, so a short chip can carry a long
+// sentence. `agents` scopes it to session kinds; omitted means every kind.
+export interface QuickCommand {
+  label: string;
+  text: string;
+  agents?: SessionAgent[];
+}

package/common/remoteHostHealth.ts

@@ -0,0 +1,30 @@
+// Health of the remote-host command channel, as reported by the server's resilient
+// runner and rendered by the toolbar control. Shared across the build boundary so the
+// two sides cannot drift on the state names.
+//
+//   online       — the Firestore subscription is up; the phone can reach this host
+//   reconnecting — it died and is being re-subscribed with backoff (self-healing)
+//   offline      — re-subscribing stopped helping, or nothing is connected at all;
+//                  recovering needs a re-auth from the browser's parked session
+
+import { isRecord } from "./isRecord.js";
+export const RUNNER_HEALTH_STATES = ["online", "reconnecting", "offline"] as const;
+export type RunnerHealthState = (typeof RUNNER_HEALTH_STATES)[number];
+
+export interface RunnerHealth {
+  state: RunnerHealthState;
+  /** Last listener error seen, for the popover and the log. Null before the first one. */
+  lastError: string | null;
+  /** ms epoch of the last state change, so the UI can say how long it has been down. */
+  changedAt: number;
+}
+
+export const isRunnerHealthState = (value: unknown): value is RunnerHealthState => RUNNER_HEALTH_STATES.some((state) => state === value);
+
+/** Narrows a parsed HTTP payload. The client renders whatever this accepts, so a
+ *  half-shaped health has to read as "no health reported" rather than as a state. */
+export const isRunnerHealth = (value: unknown): value is RunnerHealth =>
+  isRecord(value) &&
+  isRunnerHealthState(value.state) &&
+  (value.lastError === null || typeof value.lastError === "string") &&
+  typeof value.changedAt === "number";

package/common/sessionAgent.ts

@@ -0,0 +1,8 @@
+// What a remote-host session is running. The server decides it (from the PtyEntry, or from
+// what tmux says is in the pane) and the settings UI offers it as the scope for a quick
+// command, so the list of kinds is a value both sides read.
+export const SESSION_AGENTS = ["claude", "codex", "shell"] as const;
+
+// Null anywhere this appears means the host cannot tell — a session that outlived a restart
+// exists only in tmux, and nothing recorded what launched it. That is distinct from "shell".
+export type SessionAgent = (typeof SESSION_AGENTS)[number];

package/common/shortcuts.ts

@@ -0,0 +1,27 @@
+// Launcher shortcut (a pinned collection / feed), shared across the build boundary: the
+// server reads and writes `<workspace>/config/shortcuts.json`, the browser's store,
+// PinToggle and the toolbar launcher render it.
+//
+// MulmoClaude and MulmoTerminal SHARE that file — favoriting a collection in one app must
+// show up in the other — so the on-disk format is the contract: an OBJECT WRAPPER
+// `{ shortcuts: Shortcut[] }`, not a bare array, matching mulmoclaude/src/types/shortcuts.ts.
+// Keep this type in sync with MulmoClaude's.
+
+export const SHORTCUT_KINDS = ["collection", "feed"] as const;
+export type ShortcutKind = (typeof SHORTCUT_KINDS)[number];
+
+export interface Shortcut {
+  /** Which route family — drives the launcher's navigation target. */
+  kind: ShortcutKind;
+  /** The target collection / feed slug. */
+  slug: string;
+  /** Cached display label (user-named) — refreshed on reconcile. */
+  title: string;
+  /** Cached material-symbols glyph — refreshed on reconcile. */
+  icon: string;
+}
+
+/** True when two shortcuts target the same thing (the dedupe key). */
+export function sameShortcut(left: Pick<Shortcut, "kind" | "slug">, right: Pick<Shortcut, "kind" | "slug">): boolean {
+  return left.kind === right.kind && left.slug === right.slug;
+}

package/common/sourceExtensions.ts

@@ -0,0 +1,61 @@
+// Extensions a browser can only ever show as SOURCE — the code, style, config and log
+// files a terminal actually prints paths to.
+//
+// Both sides of the file-path link decide something from this set, and the two decisions
+// are different, so this is the shared CORE rather than either side's whole answer:
+//   - the server serves these as text/plain so they VIEW instead of downloading
+//     (backends/rawServingPlan.ts, which also covers docs, markup and dotfiles), and
+//   - the client opens these in the app's own Files view instead of a new tab
+//     (composables/terminalFilePathLinkProvider.ts, which also covers .txt).
+// Each side adds its own extras next to its import; anything that belongs to only one of
+// them does NOT belong here.
+//
+// Adding an extension changes what a clicked path DOES, which is documented — see the DOCS
+// block in composables/terminalFilePathLinkProvider.ts for the three files to update (#834).
+export const SOURCE_CODE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".py",
+  ".rb",
+  ".go",
+  ".rs",
+  ".java",
+  ".kt",
+  ".c",
+  ".h",
+  ".cpp",
+  ".cc",
+  ".hpp",
+  ".cs",
+  ".php",
+  ".swift",
+  ".scala",
+  ".lua",
+  ".sql",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".fish",
+  ".yml",
+  ".yaml",
+  ".toml",
+  ".ini",
+  ".cfg",
+  ".conf",
+  ".css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".xml",
+  ".jsonc",
+  ".log",
+  ".diff",
+  ".patch",
+] as const;

package/dist/assets/{abnfDiagram-VRR7QNED-RjiYivmv-Yx87EMvu.js → abnfDiagram-VRR7QNED-RjiYivmv-CMyzg2zY.js}

@@ -1 +1 @@
-import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DxEa8E3F-DfwxZrpZ.js";import"./chunk-WYO6CB5R-BlzOfotS-ozBfm4Ec.js";import"./chunk-VAUOI2AC-CS9QJ4yz-N2n8rUqR.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CMZRaeqt-zF0QMt5P.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};
+import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DxEa8E3F-D1ef8DoR.js";import"./chunk-WYO6CB5R-BlzOfotS-qckQG4MR.js";import"./chunk-VAUOI2AC-CS9QJ4yz-DviHNtmN.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CMZRaeqt-CG59XkeN.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};

package/dist/assets/architecture-TIHT7OUA-0NsD2xW1-3kpQCFcP.js

@@ -0,0 +1 @@
+import{f as e}from"./mermaid-parser.core-DxEa8E3F-D1ef8DoR.js";export{e as createArchitectureServices};