@hienlh/ppm 0.23.11 → 0.23.12

package/src/services/file-watcher.service.ts

@@ -1,13 +1,17 @@
+import { readFileSync } from "node:fs";
 import { WatchTree } from "./file-watcher/watch-tree.ts";
+import { inotifyAvailable } from "./file-watcher/linux-inotify.ts";
 
 const DEBOUNCE_MS = 500;
 /**
  * Directory budgets. These bound the directories PPM *covers*, which is not the same as
- * the inotify watches it holds: measured on Linux, watching a directory costs one
- * descriptor for it plus one for every file inside — 4 directories holding 600 files
+ * the inotify watches it holds: measured on Linux, watching a directory with `fs.watch` costs
+ * one descriptor for it plus one for every file inside — 4 directories holding 600 files
  * come to 604, recursive and non-recursive alike. So a directory cap bounds handles and
  * walk cost, not descriptors; what keeps PPM inside the machine-wide 524288 ceiling is
- * never registering `node_modules` in the first place.
+ * never registering `node_modules` in the first place. (Linux with glibc now watches through
+ * raw inotify instead, where a directory costs one watch and no descriptor — see
+ * `file-watcher/linux-inotify.ts`; the per-file cost is the `fs.watch` fallback's.)
  *
  * The per-project cap is hard. The total is best-effort: a tree keeps growing after
  * it starts, through `syncChildDir` -> `cover`, up to its own `maxDirs` — and on
@@ -28,6 +32,36 @@ const MAX_DIRS_TOTAL = 30_000;
  * watcher. A late project now gets a small budget and the truncation warning instead.
  */
 const MIN_DIRS_PER_PROJECT = 1_000;
+/**
+ * Raw inotify's caps. There a directory is one kernel watch and ~1.2 KB of heap, with no
+ * descriptor, and the caps above — sized for `fs.watch`'s per-file descriptors — cut
+ * nxsys-workspace off at 12,000 of its 28,684 directories, so a change past that point never
+ * arrived. Covering all of it measured 0.35 s with no pause over 2 ms, for 34 MB of heap
+ * against 13 MB at the old cap. What bounds this backend is `fs.inotify.max_user_watches`,
+ * which every program the user runs draws on (code-server alone held 308k of them here), so
+ * PPM takes at most a quarter of it — and a machine where that quarter is smaller than the
+ * `fs.watch` caps keeps those, which is what PPM already took there.
+ */
+const INOTIFY_MAX_DIRS_PER_PROJECT = 100_000;
+const INOTIFY_MAX_DIRS_TOTAL = 250_000;
+
+/** The per-project and total directory caps for a watching backend on a machine with this watch limit. */
+export function watchBudgets(rawInotify: boolean, maxUserWatches: number): { perProject: number; total: number } {
+  const total = rawInotify ? Math.min(INOTIFY_MAX_DIRS_TOTAL, Math.floor(maxUserWatches / 4)) : 0;
+  if (total <= MAX_DIRS_TOTAL) return { perProject: MAX_DIRS_PER_PROJECT, total: MAX_DIRS_TOTAL };
+  return { perProject: Math.min(INOTIFY_MAX_DIRS_PER_PROJECT, total), total };
+}
+
+let budgets: { perProject: number; total: number } | undefined;
+function hostBudgets(): { perProject: number; total: number } {
+  if (budgets) return budgets;
+  const rawInotify = inotifyAvailable();
+  let maxUserWatches = 0; // unreadable: keep the `fs.watch` caps
+  if (rawInotify) {
+    try { maxUserWatches = Number(readFileSync("/proc/sys/fs/inotify/max_user_watches", "utf8").trim()) || 0; } catch {}
+  }
+  return (budgets = watchBudgets(rawInotify, maxUserWatches));
+}
 
 type ChangeCallback = (projectName: string, path: string) => void;
 
@@ -60,7 +94,7 @@ export function onFileChange(cb: ChangeCallback): void {
  * reached so far. The walk hands the event loop back every few hundred directories, so its
  * count climbs for seconds — and a second project opened during one used to size its budget
  * against that unfinished number, which is how two projects starting together could each be
- * told there was room and overshoot `MAX_DIRS_TOTAL` between them. Over-counting is the safe
+ * told there was room and overshoot the total between them. Over-counting is the safe
  * direction: the reservation is released the moment the walk lands and reports its real size.
  */
 function totalCoveredDirs(): number {
@@ -110,10 +144,8 @@ export function startWatching(projectName: string, projectPath: string): Promise
     return existing.ready;
   }
 
-  const maxDirs = Math.max(
-    MIN_DIRS_PER_PROJECT,
-    Math.min(MAX_DIRS_PER_PROJECT, MAX_DIRS_TOTAL - totalCoveredDirs()),
-  );
+  const { perProject, total } = hostBudgets();
+  const maxDirs = Math.max(MIN_DIRS_PER_PROJECT, Math.min(perProject, total - totalCoveredDirs()));
   const entry: WatchEntry = {
     tree: new WatchTree({
       root: projectPath,

package/src/services/file.service.ts

@@ -13,12 +13,16 @@ import {
   removeEntrySync,
   renameEntrySync,
 } from "./fs-ops/fs-core-ops.ts";
-import type { FileNode, FileEntry, FileDirEntry } from "../types/project.ts";
+import type { FileNode, FileDirEntry, FileEntry } from "../types/project.ts";
+import type { IndexBuild } from "./file-index/index-walk.ts";
+import type { SearchKind } from "./file-index/index-search.ts";
 import {
   listDir as listDirImpl,
   listDirBatch as listDirBatchImpl,
   buildIndex as buildIndexImpl,
+  searchFileIndex,
   invalidateIndexCache,
+  markIndexStale,
   clearIndexCache,
 } from "./file-list-index.service.ts";
 
@@ -280,13 +284,19 @@ class FileService {
   }
 
   /**
-   * Build flat file index for palette/search (delegates to file-list-index.service).
-   * Cached per project; invalidated on file change via invalidateIndexCache().
+   * Build flat file index for palette/search (delegates to file-list-index.service), as the
+   * ready-to-send `/files/index` response. Cached per project; a file change marks it stale
+   * via markIndexStale().
    */
-  buildIndex(projectPath: string): FileEntry[] {
+  buildIndex(projectPath: string): Promise<IndexBuild> {
     return buildIndexImpl(projectPath);
   }
 
+  /** Search the flat file index on the server (delegates to file-list-index.service). */
+  searchIndex(projectPath: string, query: string, kind: SearchKind, limit: number): Promise<FileEntry[]> {
+    return searchFileIndex(projectPath, query, kind, limit);
+  }
+
   /** Block access to sensitive paths (.git/) */
   private blockSensitive(filePath: string): void {
     const normalized = normalize(filePath);
@@ -323,7 +333,8 @@ export class ValidationError extends Error {
 
 export const fileService = new FileService();
 
-// Wire file watcher → index cache invalidation
+// Wire file watcher → index staleness. Stale, not dropped: dropping made the next request walk
+// the whole project while it waited (see IndexEntry in file-list-index.service).
 // Dynamic import avoids circular dependency (file-watcher → chat.ts → file.service)
 import("./file-watcher.service.ts").then(({ onFileChange }) => {
   onFileChange((projectName) => {
@@ -332,7 +343,7 @@ import("./file-watcher.service.ts").then(({ onFileChange }) => {
       const { configService } = require("./config.service.ts");
       const projects = configService.get("projects") as Array<{ name: string; path: string }>;
       const project = projects.find((p: { name: string }) => p.name === projectName);
-      if (project) invalidateIndexCache(project.path);
+      if (project) markIndexStale(project.path);
     } catch {
       // Config not yet loaded or project not found — skip invalidation
     }

package/src/services/group-chat/group-chat.service.ts

@@ -327,7 +327,7 @@ class GroupChatService {
       // consumer-side signal guard halts the turn, so only permissionMode is
       // forwarded here.
       sendMessage: (pid, sid, prompt, opts) =>
-        chatService.sendMessage(pid, sid, prompt, { permissionMode: opts?.permissionMode, model: opts?.model, oneMContext: opts?.oneMContext }),
+        chatService.sendMessage(pid, sid, prompt, { permissionMode: opts?.permissionMode, model: opts?.model, oneMContext: opts?.oneMContext, origin: "group-chat" }),
     };
     return this.backendCache;
   }

package/src/services/jira-debug-session.service.ts

@@ -184,7 +184,7 @@ class JiraDebugSessionService {
 
       // bypassPermissions: automated debug sessions run without user approval (same as PPMBot)
       const opts = { permissionMode: "bypassPermissions" as PermissionMode };
-      const events = chatService.sendMessage(session.providerId, session.id, prompt, opts);
+      const events = chatService.sendMessage(session.providerId, session.id, prompt, { ...opts, origin: "jira" });
 
       let lastAssistantText = "";
       for await (const event of events) {

package/src/services/ppmbot/ppmbot-delegation.ts

@@ -43,7 +43,7 @@ export async function executeDelegation(
     });
 
     const opts = { permissionMode: "bypassPermissions" as PermissionMode };
-    const events = chatService.sendMessage(providerId, session.id, task.prompt, opts);
+    const events = chatService.sendMessage(providerId, session.id, task.prompt, { ...opts, origin: "ppmbot" });
 
     let fullText = "";
     let lastAssistantText = "";

package/src/services/ppmbot/ppmbot-service.ts

@@ -423,7 +423,7 @@ I'll answer directly or delegate to your project's AI.`;
         session.providerId,
         session.sessionId,
         fullMessage,
-        opts,
+        { ...opts, origin: "ppmbot" },
       );
 
       const result = await streamToTelegram(

package/src/services/project-content-search.service.ts

@@ -31,6 +31,43 @@ export async function resolveProjectSearchGrep(options: ResolverOptions = {}): P
   }
 }
 
+/** The program a search runs, and which one it is: their flags differ. */
+export interface ProjectSearchTool { kind: "rg" | "grep"; path: string }
+
+/**
+ * ripgrep when it is installed, GNU grep otherwise. ripgrep searches on every core, grep on one:
+ * on nxsys-workspace (181k entries) one query took grep 1.7 s — 11 s from a cold disk cache, past
+ * the timeout — and ripgrep 0.1 s, for the same 38,071 lines.
+ */
+export async function resolveProjectSearchTool(options: ResolverOptions = {}): Promise<ProjectSearchTool | undefined> {
+  const rg = (options.which ?? ((name: string) => Bun.which(name)))("rg");
+  if (rg) return { kind: "rg", path: rg };
+  const grep = await resolveProjectSearchGrep(options);
+  return grep ? { kind: "grep", path: grep } : undefined;
+}
+
+const EXCLUDED_DIRS = ["node_modules", ".git", "dist", ".next", "build", ".turbo", "coverage", "__pycache__"];
+const EXCLUDED_FILES = ["*.min.js", "*.map", "*.lock", "bun.lock"];
+
+/** Both print `path\0line:content` per match and exit 0 / 1 / 2 for match / none / error. */
+function searchArgs(kind: ProjectSearchTool["kind"], options: ProjectSearchOptions): string[] {
+  const matching = [...(options.caseSensitive ? [] : ["-i"]), ...(options.wholeWord ? ["-w"] : [])];
+  if (kind === "rg") {
+    // -uu searches ignored and hidden files, as grep -r does; a trailing slash makes a glob match
+    // directories only, as --exclude-dir does. --no-config: a user's RIPGREP_CONFIG_PATH could
+    // change the output format. ripgrep prints `\` on Windows, and results are keyed by `/` paths.
+    return ["--no-config", "-uu", "--no-heading", "--with-filename", "--line-number", "--null", "--max-count=5",
+      "--path-separator=/",
+      ...(options.regex ? [] : ["-F"]), ...matching,
+      ...EXCLUDED_DIRS.flatMap((dir) => ["-g", `!${dir}/`]), ...EXCLUDED_FILES.flatMap((file) => ["-g", `!${file}`]),
+      "--", options.query, "."];
+  }
+  // Long --null also works with BSD grep, where -Z means decompress.
+  return ["-rHn", "--null", "--max-count=5", "-I", options.regex ? "-E" : "-F", ...matching,
+    ...EXCLUDED_DIRS.flatMap((dir) => ["--exclude-dir", dir]), ...EXCLUDED_FILES.map((file) => `--exclude=${file}`),
+    "--", options.query, "."];
+}
+
 /** Convert glob pattern (VSCode-style) to RegExp for path filtering.
  *  - `*.ts`       → matches any .ts file in any directory
  *  - `src/**`     → matches any file under src/
@@ -57,17 +94,12 @@ export interface ProjectSearchOptions {
 }
 
 export async function searchProjectContent(projectPath: string, options: ProjectSearchOptions,
-  dependencies: { resolveGrep?: () => Promise<string | undefined>; timeoutMs?: number; maxBytes?: number } = {}) {
+  dependencies: { resolveTool?: () => Promise<ProjectSearchTool | undefined>; timeoutMs?: number; maxBytes?: number } = {}) {
   const empty = { results: [] as Array<{ file: string; matches: Array<{ lineNum: number; content: string }> }>, total: 0 };
   if (options.query.length < (options.regex ? 1 : 2)) return empty;
-  const executable = await (dependencies.resolveGrep ?? resolveProjectSearchGrep)();
-  if (!executable) throw new ProjectSearchError("Content search needs GNU grep. Install Git for Windows, or make grep available on PATH, then retry.", 503);
-  const excluded = ["node_modules", ".git", "dist", ".next", "build", ".turbo", "coverage", "__pycache__"];
-  // Long --null also works with BSD grep, where -Z means decompress.
-  const flags = ["-rHn", "--null", "--max-count=5", "-I", options.regex ? "-E" : "-F", ...(options.caseSensitive ? [] : ["-i"]), ...(options.wholeWord ? ["-w"] : [])];
-  const proc = Bun.spawn({ cmd: [executable, ...flags, ...excluded.flatMap((dir) => ["--exclude-dir", dir]),
-    "--exclude=*.min.js", "--exclude=*.map", "--exclude=*.lock", "--exclude=bun.lock", "--", options.query, "."],
-    cwd: projectPath, stdout: "pipe", stderr: "pipe" });
+  const tool = await (dependencies.resolveTool ?? resolveProjectSearchTool)();
+  if (!tool) throw new ProjectSearchError("Content search needs ripgrep or GNU grep. Install ripgrep or Git for Windows, or make grep available on PATH, then retry.", 503);
+  const proc = Bun.spawn({ cmd: [tool.path, ...searchArgs(tool.kind, options)], cwd: projectPath, stdout: "pipe", stderr: "pipe" });
   let failure: ProjectSearchError | undefined;
   let bytes = 0;
   const stop = (error: ProjectSearchError) => { failure ??= error; proc.kill(); };
@@ -93,7 +125,7 @@ export async function searchProjectContent(projectPath: string, options: Project
   finally { clearTimeout(timer); if (proc.exitCode === null) proc.kill(); }
   if (failure) throw failure;
   if (code !== 0 && code !== 1) {
-    const invalidPattern = options.regex && /regular expression|unmatched|unterminated|invalid range|trailing backslash|repetition/i.test(stderr);
+    const invalidPattern = options.regex && /regex parse error|regular expression|unmatched|unterminated|invalid range|trailing backslash|repetition/i.test(stderr);
     throw new ProjectSearchError(invalidPattern ? "Invalid regular expression. Check the pattern and retry." : "Content search failed. Check file permissions and the search tool, then retry.", invalidPattern ? 400 : 500);
   }
   if (code === 1) return empty;
@@ -114,6 +146,8 @@ export async function searchProjectContent(projectPath: string, options: Project
     matches.push({ lineNum: Number(record[1]), content: record[2]!.trimEnd() });
     files.set(file, matches);
   }
-  const results = Array.from(files, ([file, matches]) => ({ file, matches }));
+  // ripgrep prints files in whatever order its threads finish them, so sort for a stable list.
+  const results = Array.from(files, ([file, matches]) => ({ file, matches }))
+    .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
   return { results, total: results.reduce((sum, result) => sum + result.matches.length, 0) };
 }

package/src/services/proxy-agent-turn.ts

@@ -16,6 +16,7 @@ import { mkdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { providerRegistry } from "../providers/registry.ts";
 import { getPpmDir } from "./ppm-dir.ts";
+import { traceStream } from "./session-trace/trace-recorder.ts";
 import type { AIProvider, ChatEvent } from "../types/chat.ts";
 
 /**
@@ -190,14 +191,17 @@ export async function startAgentTurn(providerId: string, req: TurnRequest): Prom
       title: `[API] ${providerId}`,
     });
 
-    const events = provider.sendMessage(session.id, message, {
+    const opts = {
       permissionMode: PROXY_PERMISSION_MODE,
       ...(req.model ? { model: req.model } : {}),
       ...(req.imagePaths?.length ? { imagePaths: req.imagePaths } : {}),
-    });
+    };
+    const events = provider.sendMessage(session.id, message, opts);
 
     return {
-      events: withTimeout(events),
+      // Not through ChatService (no shared context, no design options), so it is traced here —
+      // outside the timeout, so a stalled turn is recorded as the failure it surfaces as.
+      events: traceStream({ sessionId: session.id, providerId: provider.id, origin: "proxy", message, opts }, withTimeout(events)),
       cleanup: async () => {
         try {
           // abortQuery is what kills the runtime; deleteSession alone may only drop

package/src/services/remote-desktop/mediamtx-catalog.ts

@@ -0,0 +1,89 @@
+/**
+ * What "install the WebRTC relay" downloads: one MediaMTX build per platform.
+ *
+ * MediaMTX is a single static Go binary (Pion underneath) that takes PPM's existing H.264
+ * over RTSP and serves it to a browser as WebRTC, **without re-encoding** — verified against
+ * v1.21.1: a 1920x1080 Main@4.0 stream pushed by ffmpeg arrived at the browser as
+ * `video/H264` at the same resolution. That is the whole reason this is a relay and not an
+ * encoder: every bit of PPM's per-platform capture, quality ladder, cursor flag and privacy
+ * mode keeps working unchanged, and only the transport moves off the WebSocket.
+ *
+ * Why a downloaded binary rather than a library: Bun has no WebRTC stack at all. The two
+ * in-process routes were both measured and rejected — GStreamer's `webrtcbin` segfaults
+ * PyGObject on GStreamer 1.28.7 + Python 3.14 (`gst_sdp_message_copy` walking a malformed
+ * emails array) *and* would put GStreamer + PyGObject on every Windows and macOS host, while
+ * `@roamhq/wrtc` only accepts raw i420 frames, i.e. it would throw away the hardware H.264
+ * encode PPM just did and encode again in software.
+ *
+ * Pure and parameterised so the whole matrix is unit-testable without touching `process.*` or
+ * the network. Every entry is pinned by tag AND by SHA-256, because this downloads an
+ * executable onto the user's machine.
+ */
+
+/** MediaMTX release the binaries come from. Bump this and every SHA-256 below together. */
+export const MEDIAMTX_VERSION = "1.21.1";
+
+const RELEASE_BASE = `https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}`;
+
+export interface MediamtxAsset {
+  /** Archive file name as published in the release. */
+  file: string;
+  url: string;
+  /** Lowercase hex, from the release's own `checksums.sha256`. */
+  sha256: string;
+  ext: "tar.gz" | "zip";
+}
+
+/**
+ * Keyed `<platform>-<arch>` in Node's own vocabulary, so a caller passes `process.platform`
+ * and `process.arch` straight through.
+ *
+ * `win32-arm64` is deliberately absent: the release publishes no Windows ARM build, and a
+ * missing row has to read as "not available for this host" rather than fall back to an amd64
+ * binary that would fail at spawn with nothing explaining why.
+ */
+const ASSETS: Record<string, MediamtxAsset> = {
+  "linux-x64": {
+    file: `mediamtx_v${MEDIAMTX_VERSION}_linux_amd64.tar.gz`,
+    url: `${RELEASE_BASE}/mediamtx_v${MEDIAMTX_VERSION}_linux_amd64.tar.gz`,
+    sha256: "653abc672a3e693f8d3b2717752492fdcfb8072291ec108d03d3dd857411b0ee",
+    ext: "tar.gz",
+  },
+  "linux-arm64": {
+    file: `mediamtx_v${MEDIAMTX_VERSION}_linux_arm64.tar.gz`,
+    url: `${RELEASE_BASE}/mediamtx_v${MEDIAMTX_VERSION}_linux_arm64.tar.gz`,
+    sha256: "6a3aa635fb60ea9b8d566ec306f0a42ff1b6b52a3942bc2baffbe55880d4c3dd",
+    ext: "tar.gz",
+  },
+  "darwin-x64": {
+    file: `mediamtx_v${MEDIAMTX_VERSION}_darwin_amd64.tar.gz`,
+    url: `${RELEASE_BASE}/mediamtx_v${MEDIAMTX_VERSION}_darwin_amd64.tar.gz`,
+    sha256: "be403a36d2225668ea695cbd2c784109bc23ef9a32f886837e43c920b6818813",
+    ext: "tar.gz",
+  },
+  "darwin-arm64": {
+    file: `mediamtx_v${MEDIAMTX_VERSION}_darwin_arm64.tar.gz`,
+    url: `${RELEASE_BASE}/mediamtx_v${MEDIAMTX_VERSION}_darwin_arm64.tar.gz`,
+    sha256: "25e20ed41611f1f3103b8359585210b29b11b69fa0d9e11bd11b92f7bbcb42ef",
+    ext: "tar.gz",
+  },
+  "win32-x64": {
+    file: `mediamtx_v${MEDIAMTX_VERSION}_windows_amd64.zip`,
+    url: `${RELEASE_BASE}/mediamtx_v${MEDIAMTX_VERSION}_windows_amd64.zip`,
+    sha256: "faa97974861eb75a68b5aa326c78e7e7a6f670b5ef191bace78e715130381f23",
+    ext: "zip",
+  },
+};
+
+/** The build for a host, or null when the release publishes none for it. */
+export function mediamtxAsset(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): MediamtxAsset | null {
+  return ASSETS[`${platform}-${arch}`] ?? null;
+}
+
+/** Every key the catalog knows, for tests and for the Settings pane's support copy. */
+export function mediamtxSupportedHosts(): string[] {
+  return Object.keys(ASSETS);
+}

package/src/services/remote-desktop/mediamtx-config.ts

@@ -0,0 +1,91 @@
+/**
+ * The MediaMTX config PPM generates for each run, and the one place the relay's exposure is
+ * decided.
+ *
+ * The archive ships its own `mediamtx.yml` that listens on every interface and turns on RTSP,
+ * RTMP, HLS, SRT, MoQ, an HTTP API, metrics and pprof. None of that is wanted, and MoQ in
+ * particular writes a self-signed `auto.crt`/`auto.key` beside itself on first start. PPM
+ * writes this file instead and passes it explicitly, so the shipped one is never read.
+ *
+ * Verified against v1.21.1: the generated config leaves exactly three sockets open —
+ *   127.0.0.1:<rtsp>  TCP   ffmpeg pushes the H.264 it already encoded
+ *   127.0.0.1:<whep>  TCP   WHEP signalling, reached only through PPM's authenticated proxy
+ *   *:<ice>           UDP   the media itself
+ *
+ * The UDP port is the one thing that cannot be confined to loopback: WebRTC media goes
+ * peer-to-peer, so a browser on the LAN or the tailnet has to be able to reach it. What
+ * protects it is the ICE credentials — a random ufrag/password minted per session and carried
+ * in the SDP, which only travels through the authenticated proxy. That is the standard WebRTC
+ * model, but it does mean the port answers to anyone who can reach it *and* already holds a
+ * session's SDP, so the path name is random per session too rather than a guessable "desktop".
+ */
+import { randomBytes } from "node:crypto";
+
+export interface MediamtxConfigOptions {
+  /** Loopback TCP port ffmpeg pushes RTSP to. */
+  rtspPort: number;
+  /** Loopback TCP port serving WHEP; PPM proxies to it. */
+  whepPort: number;
+  /** UDP port ICE media flows over. Bound on every interface by necessity. */
+  iceUdpPort: number;
+  /** Stream path, from `randomStreamPath()`. */
+  pathName: string;
+}
+
+/**
+ * An unguessable path per session. MediaMTX path names allow only word characters, so this is
+ * hex rather than base64url.
+ */
+export function randomStreamPath(): string {
+  return `s${randomBytes(16).toString("hex")}`;
+}
+
+/** Where ffmpeg pushes, and where the relay reads from. */
+export function rtspPublishUrl(rtspPort: number, pathName: string): string {
+  return `rtsp://127.0.0.1:${rtspPort}/${pathName}`;
+}
+
+/** The WHEP endpoint on the relay, which PPM proxies rather than exposes. */
+export function whepUrl(whepPort: number, pathName: string): string {
+  return `http://127.0.0.1:${whepPort}/${pathName}/whep`;
+}
+
+/**
+ * MediaMTX rejects unknown config keys outright (`json: unknown field "..."`), which is why
+ * every switch here is spelled out rather than trusted to default: a key that a future release
+ * renames fails loudly at start instead of silently leaving a listener open.
+ */
+export function buildMediamtxConfig(opts: MediamtxConfigOptions): string {
+  const { rtspPort, whepPort, iceUdpPort, pathName } = opts;
+  return [
+    "# Generated by PPM for one Remote Desktop session. Edits are overwritten on every start.",
+    "logLevel: warn",
+    "",
+    "# RTSP ingest: loopback only, TCP only. ffmpeg is the only thing that ever publishes.",
+    "rtsp: yes",
+    "rtspTransports: [tcp]",
+    `rtspAddress: 127.0.0.1:${rtspPort}`,
+    "",
+    "# WebRTC out. The signalling port stays on loopback and is reached through PPM's",
+    "# authenticated proxy; only the ICE/UDP port faces the network.",
+    "webrtc: yes",
+    `webrtcAddress: 127.0.0.1:${whepPort}`,
+    `webrtcLocalUDPAddress: :${iceUdpPort}`,
+    "webrtcIPsFromInterfaces: yes",
+    "",
+    "# Everything else off. MoQ also writes auto.crt/auto.key beside itself when left on.",
+    "rtmp: no",
+    "hls: no",
+    "srt: no",
+    "moq: no",
+    "api: no",
+    "metrics: no",
+    "pprof: no",
+    "playback: no",
+    "",
+    "paths:",
+    `  ${pathName}:`,
+    "    source: publisher",
+    "",
+  ].join("\n");
+}