mulmoclaude 0.6.2 → 0.6.4

package/server/agent/stdioHttpShim.ts

@@ -0,0 +1,171 @@
+// stdio↔HTTP shim for the Docker-sandbox opt-in path (#1421 Phase B).
+//
+// The Docker sandbox image can't host arbitrary stdio MCP runtimes
+// (npx / python / …), so stdio servers are dropped by default
+// (server/agent/config.ts). A user can opt a specific server into
+// `hostExecInDocker` — the explicit, UI-acknowledged escape hatch:
+// the stdio server runs on the HOST behind `supergateway` (a
+// battle-tested stdio→SSE MCP bridge) and the sandboxed agent
+// reaches it over `host.docker.internal`.
+//
+// `supergateway` (rather than a hand-rolled adapter) is deliberate:
+// MCP transport correctness is delegated to a maintained tool — for
+// a sandbox-escaping feature, protocol-correct + battle-tested beats
+// zero-dependency.
+//
+// SECURITY: every started shim runs UNSANDBOXED with host
+// privileges. That is the acknowledged trade-off of the opt-in;
+// callers MUST gate on `spec.hostExecInDocker === true` and the UI
+// MUST surface the risk. This module never decides policy — it only
+// executes an already-authorized opt-in.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import type { Readable } from "node:stream";
+
+import { findAvailablePort } from "../utils/port.mjs";
+import { log } from "../system/logger/index.js";
+import { ONE_SECOND_MS } from "../utils/time.js";
+import type { McpStdioSpec } from "../system/config.js";
+
+export interface ShimHandle {
+  /** Host URL the (sandboxed) agent's MCP client connects to. */
+  url: string;
+  /** Tear down the gateway + its stdio child. Idempotent. */
+  close: () => void;
+}
+
+// Pinned: this is an UNSANDBOXED host-exec path, so `npx -y` must not
+// resolve a mutable upstream version on every run (supply-chain +
+// reproducibility). Bump deliberately after reviewing the diff.
+const SUPERGATEWAY_VERSION = "3.4.3";
+
+const SHIM_PORT_RANGE_START = 39_100;
+const SHIM_READY_TIMEOUT_MS = 15 * ONE_SECOND_MS;
+const SHIM_READY_POLL_MS = ONE_SECOND_MS / 4;
+
+// POSIX single-quote escaping. supergateway runs the `--stdio` value
+// through `spawn(..., { shell: true })`, so the string is parsed by a
+// shell — whitespace-only quoting would let metacharacters
+// (`$ ; | & ( )`, backticks, quotes) be expanded and diverge from the
+// non-shim `spawn(command, args)` path. Wrapping every token in single
+// quotes (and `'\''`-escaping embedded single quotes) neutralises ALL
+// shell metacharacters, which matters because this path runs
+// UNSANDBOXED on the host. This is POSIX-shell-specific; on Windows
+// the default shell is cmd.exe where single-quote semantics differ,
+// so `startStdioHttpShim` refuses to run there (safe default: drop)
+// rather than risk a misparse on a sandbox-escaping path.
+function shellQuote(token: string): string {
+  const escaped = token.replace(/'/g, "'\\''");
+  return `'${escaped}'`;
+}
+
+export function buildStdioCommand(spec: McpStdioSpec): string {
+  return [spec.command, ...(spec.args ?? [])].map(shellQuote).join(" ");
+}
+
+const SHIM_PROBE_TIMEOUT_MS = 2 * ONE_SECOND_MS;
+
+async function probeOnce(port: number): Promise<boolean> {
+  // Per-request timeout: a half-open TCP connection (port accepts but
+  // never responds) would otherwise hang past the overall deadline.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SHIM_PROBE_TIMEOUT_MS);
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/sse`, { method: "GET", signal: controller.signal });
+    // 405 / 400 = server is up but rejects a bare GET on the SSE
+    // endpoint — that still proves the gateway is listening.
+    return res.ok || res.status === 405 || res.status === 400;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function waitUntilListening(child: ChildProcess, port: number, hasSpawnFailed: () => boolean): Promise<boolean> {
+  const deadline = Date.now() + SHIM_READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    // Bail immediately on a dead/failed child instead of burning the
+    // full timeout: spawn 'error' can fire after the caller's initial
+    // check, so re-test the flag (and exit/signal) every iteration.
+    if (hasSpawnFailed() || child.exitCode !== null || child.signalCode !== null) return false;
+    if (await probeOnce(port)) return true;
+    await new Promise((resolve) => setTimeout(resolve, SHIM_READY_POLL_MS));
+  }
+  return false;
+}
+
+function drainToDebug(child: ChildProcess, serverId: string): void {
+  // supergateway / the wrapped server can be chatty. We never parse
+  // this output (readiness is an HTTP probe), but unread `pipe`
+  // buffers fill and block the child, so the streams MUST be
+  // consumed. Forward to debug so failures are still diagnosable.
+  const forward = (stream: Readable | null, channel: "stdout" | "stderr") => {
+    if (!stream) return;
+    stream.on("data", (chunk: Buffer) => {
+      log.debug("mcp-shim", `${channel}: ${chunk.toString().trimEnd()}`, { serverId });
+    });
+  };
+  forward(child.stdout, "stdout");
+  forward(child.stderr, "stderr");
+}
+
+/** Start a host-side stdio↔HTTP gateway for an opted-in stdio
+ *  server. Returns a handle, or `null` when the gateway failed to
+ *  come up (caller falls back to the safe default: drop the server).
+ *  Never throws — a shim failure must not abort the agent turn.
+ *
+ *  `workspacePath` is the chat workspace; the shim runs with it as
+ *  cwd so relative args / config-file discovery match the normal
+ *  (non-Docker) stdio execution semantics. */
+export async function startStdioHttpShim(serverId: string, spec: McpStdioSpec, workspacePath: string): Promise<ShimHandle | null> {
+  // Windows host: the shell escaping below is POSIX-only and
+  // supergateway runs `--stdio` via cmd.exe here, so refuse rather
+  // than risk a misparse on an UNSANDBOXED path. Falls through to the
+  // safe default (server dropped + logged by the caller).
+  if (process.platform === "win32") {
+    log.warn("mcp-shim", "host-exec stdio shim is unsupported on Windows — dropping server", { serverId });
+    return null;
+  }
+
+  const port = await findAvailablePort(SHIM_PORT_RANGE_START);
+  if (port === null) {
+    log.warn("mcp-shim", "no free port for stdio→http shim — dropping server", { serverId });
+    return null;
+  }
+
+  const child = spawn("npx", ["-y", `supergateway@${SUPERGATEWAY_VERSION}`, "--stdio", buildStdioCommand(spec), "--port", String(port)], {
+    // Run from the chat workspace (parity with the non-Docker stdio
+    // path) so relative args / config lookups resolve identically.
+    cwd: workspacePath,
+    // Merge the spec env so the stdio child sees its required vars
+    // (API keys etc.); inherit the host env for npx/node resolution.
+    env: { ...process.env, ...(spec.env ?? {}) },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  drainToDebug(child, serverId);
+  // Without an error listener a spawn failure (npx missing) would be
+  // an unhandled 'error' event → process crash. Same lesson as the
+  // claude-code backend's spawn guard.
+  let spawnFailed = false;
+  child.once("error", (err) => {
+    spawnFailed = true;
+    log.warn("mcp-shim", "supergateway spawn failed", { serverId, error: err instanceof Error ? err.message : String(err) });
+  });
+
+  const close = () => {
+    if (!child.killed) child.kill("SIGTERM");
+  };
+
+  const ready = !spawnFailed && (await waitUntilListening(child, port, () => spawnFailed));
+  if (!ready) {
+    close();
+    log.warn("mcp-shim", "stdio→http shim did not become ready — dropping server", { serverId, port });
+    return null;
+  }
+
+  log.info("mcp-shim", "stdio→http shim ready (host-exec, escapes sandbox)", { serverId, port });
+  // Loopback URL; the caller rewrites localhost→host.docker.internal
+  // for the in-container MCP config.
+  return { url: `http://127.0.0.1:${port}/sse`, close };
+}

package/server/agent/stream.ts

@@ -15,6 +15,11 @@ export type AgentEvent =
       type: typeof EVENT_TYPES.toolCallResult;
       toolUseId: string;
       content: string;
+      /** Anthropic's `tool_result` block carries `is_error: true` when
+       *  the MCP server (or other tool) reported an error. Surfaced
+       *  here so the failure monitor (#1353) can attribute repeated
+       *  errors to a specific MCP server and warn / notify. */
+      isError?: boolean;
     }
   | { type: typeof EVENT_TYPES.claudeSessionId; id: string };
 
@@ -27,6 +32,10 @@ export interface ClaudeContentBlock {
   content?: unknown;
   /** Text content — present in `text` type blocks. */
   text?: string;
+  /** Tool-result error flag from the Anthropic API. Present on
+   *  `tool_result` blocks when the tool itself reported failure
+   *  (MCP server returned an error, 401, ECONNREFUSED, …). */
+  is_error?: boolean;
 }
 
 export interface ClaudeMessage {
@@ -73,11 +82,13 @@ export function blockToEvent(block: ClaudeContentBlock): AgentEvent | null {
   if (block.type === "tool_result" && block.tool_use_id) {
     const raw = block.content;
     const content = typeof raw === "string" ? raw : raw === undefined ? "" : JSON.stringify(raw);
-    return {
+    const event: AgentEvent = {
       type: EVENT_TYPES.toolCallResult,
       toolUseId: block.tool_use_id,
       content,
     };
+    if (block.is_error === true) event.isError = true;
+    return event;
   }
   return null;
 }

package/server/api/routes/encore.ts

@@ -0,0 +1,55 @@
+// REST endpoint for the Encore plugin. Single POST dispatch route
+// with a `kind` discriminator — matches the accounting / scheduler
+// convention so the MCP bridge (which posts the tool args verbatim)
+// and the click-handler page (`src/plugins/encore/View.vue`) plug in
+// without translation.
+//
+// All business logic lives in `src/plugins/encore/server.ts`; this
+// file is just the Express adapter (request validation, error
+// mapping, logging).
+//
+// See plans/feat-encore-as-builtin.md.
+
+import { Router, Request, Response } from "express";
+
+import { dispatch, EncoreError, type EncoreDispatchBody } from "../../encore/dispatch.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { bindRoute } from "../../utils/router.js";
+import { log } from "../../system/logger/index.js";
+import { asyncHandler } from "../../utils/asyncHandler.js";
+
+const router = Router();
+
+interface EncoreErrorResponse {
+  error: string;
+  details?: unknown;
+}
+
+bindRoute(
+  router,
+  API_ROUTES.encore.dispatch,
+  asyncHandler<Request<object, unknown, EncoreDispatchBody>, Response<unknown | EncoreErrorResponse>>("encore", "encore dispatch failed", async (req, res) => {
+    const { body } = req;
+    if (!body || typeof body !== "object" || typeof body.kind !== "string") {
+      log.warn("encore", "POST dispatch: invalid body");
+      res.status(400).json({ error: "request body must be an object with a string `kind` field" });
+      return;
+    }
+    const { kind } = body;
+    log.info("encore", "POST dispatch: start", { kind });
+    try {
+      const result = await dispatch(body);
+      log.info("encore", "POST dispatch: ok", { kind, ok: result.ok });
+      res.json(result);
+    } catch (err) {
+      if (err instanceof EncoreError) {
+        log.warn("encore", "POST dispatch: error", { kind, status: err.status, message: err.message });
+        res.status(err.status).json({ error: err.message, details: err.details });
+        return;
+      }
+      throw err;
+    }
+  }),
+);
+
+export default router;

package/server/api/routes/files.ts

@@ -816,6 +816,22 @@ async function writeFileContent(absPath: string, content: string): Promise<void>
   }
 }
 
+// JSON config files are editable from the Files Explorer (#833 Phase
+// 1), but a hand-edit that breaks JSON syntax would corrupt a file the
+// app (or the agent) parses on read. Reject a malformed save before it
+// hits disk so the editor can surface the parser error inline. `.jsonl`
+// is intentionally excluded — each line is its own document, not one
+// JSON value, so `JSON.parse` of the whole file would always fail.
+function jsonSyntaxError(relPath: string, content: string): string | null {
+  if (!relPath.toLowerCase().endsWith(".json")) return null;
+  try {
+    JSON.parse(content);
+    return null;
+  } catch (err) {
+    return `Invalid JSON: ${errorMessage(err)}`;
+  }
+}
+
 // Write the body of an existing text file. Only text-classified files
 // (per `classify`) are editable — binary, image, audio, etc. are
 // refused so the endpoint can't be used to ship arbitrary uploads.
@@ -836,6 +852,12 @@ router.put(API_ROUTES.files.content, async (req: Request<object, unknown, WriteC
     else badRequest(res, resolved.message);
     return;
   }
+  const jsonError = jsonSyntaxError(relPath, content);
+  if (jsonError !== null) {
+    log.warn("files", "PUT content: invalid JSON", { pathPreview: previewSnippet(relPath) });
+    badRequest(res, jsonError);
+    return;
+  }
   try {
     await writeFileContent(resolved.absPath, content);
   } catch (err) {

package/server/api/routes/mulmo-script.ts

@@ -27,7 +27,8 @@ import { mulmoScriptSchema, type MulmoBeat, type MulmoImagePromptMedia } from "@
 import { slugify } from "../../utils/slug.js";
 import { resolveWithinRoot } from "../../utils/files/safe.js";
 import { errorMessage } from "../../utils/errors.js";
-import { badRequest, notFound, serverError } from "../../utils/httpError.js";
+import { badRequest, notFound, sendError, serverError } from "../../utils/httpError.js";
+import { depStatus } from "../../system/optionalDeps.js";
 import { getOptionalStringQuery, getSessionQuery } from "../../utils/request.js";
 import { log } from "../../system/logger/index.js";
 import { validateUpdateBeatBody, validateUpdateScriptBody } from "./mulmoScriptValidate.js";
@@ -37,6 +38,20 @@ import { publishGeneration } from "../../events/session-store/index.js";
 import { GENERATION_KINDS } from "../../../src/types/events.js";
 
 const router = Router();
+
+// mulmocast shells out to ffmpeg for movie / beat rendering. When
+// ffmpeg is absent the optional-deps probe (#1385) marks it
+// unavailable; intercept here with a clear 503 instead of letting
+// the library throw an opaque spawn ENOENT mid-stream. `undefined`
+// means the boot probe hasn't completed — assume available so a
+// brief startup window never blocks a render.
+function ffmpegUnavailable(res: Response): boolean {
+  if (depStatus("ffmpeg")?.available === false) {
+    sendError(res, 503, "ffmpeg is not installed — movie and beat rendering are unavailable. Install ffmpeg and restart the server.");
+    return true;
+  }
+  return false;
+}
 const storiesDir = path.resolve(WORKSPACE_PATHS.stories);
 
 // The downloadMovie handler expects "stories/<rel>" (historical
@@ -591,6 +606,7 @@ bindRoute(router, API_ROUTES.mulmoScript.renderBeat, async (req: Request<object,
     badRequest(res, "filePath and beatIndex are required");
     return;
   }
+  if (ffmpegUnavailable(res)) return;
 
   const key = String(beatIndex);
   publishGeneration(chatSessionId, GENERATION_KINDS.beatImage, filePath, key, false);
@@ -693,6 +709,8 @@ bindRoute(router, API_ROUTES.mulmoScript.generateMovie, async (req: Request<obje
     return;
   }
 
+  if (ffmpegUnavailable(res)) return;
+
   const absoluteFilePath = resolveStoryPath(filePath, res);
   if (!absoluteFilePath) return;
 

package/server/api/routes/schedulerHandlers.ts

@@ -28,6 +28,34 @@ export type SchedulerActionResult =
       jsonData: Record<string, unknown>;
     };
 
+// Coerces the untrusted `props` payload into a safe-to-store
+// object. Two responsibilities:
+//
+// 1. Non-object input (a number / string / array / null from
+//    untrusted JSON) becomes an empty props object — `"endDate"
+//    in 1` would otherwise throw a TypeError and surface as a
+//    500 via the asyncHandler.
+// 2. Non-string `endDate` (number / array / object) is dropped —
+//    downstream comparisons (`end < start`) only make sense for
+//    strings, and a stray number triggers a coercion bug.
+//
+// Notably we DO preserve malformed `endDate` STRINGS (e.g. "next
+// Friday", "2026-05-25" before a start of "2026-05-27"). The view
+// surfaces those as a "broken range" chip so the user/LLM gets
+// visible feedback instead of having the bad data silently erased.
+export function sanitizeProps(props: unknown): ScheduledItem["props"] {
+  if (typeof props !== "object" || props === null || Array.isArray(props)) {
+    return {};
+  }
+  const record = props as ScheduledItem["props"];
+  if (!("endDate" in record)) return record;
+  if (typeof record.endDate === "string") return record;
+  if (record.endDate === null) return record;
+  const next = { ...record };
+  Reflect.deleteProperty(next, "endDate");
+  return next;
+}
+
 export function sortItems(items: ScheduledItem[]): ScheduledItem[] {
   return [...items].sort((left, right) => {
     const leftDate = typeof left.props.date === "string" ? left.props.date : null;
@@ -57,7 +85,7 @@ export function handleAdd(items: ScheduledItem[], input: SchedulerActionInput):
     id: makeId("sched"),
     title: input.title,
     createdAt: Date.now(),
-    props: input.props ?? {},
+    props: sanitizeProps(input.props ?? {}),
   };
   const next = sortItems([...items, item]);
   return {
@@ -107,10 +135,11 @@ export function handleUpdate(items: ScheduledItem[], input: SchedulerActionInput
       jsonData: {},
     };
   }
+  const mergedProps = input.props !== undefined ? applyPropPatch(target.props, input.props) : target.props;
   const updated: ScheduledItem = {
     ...target,
     title: input.title !== undefined ? input.title : target.title,
-    props: input.props !== undefined ? applyPropPatch(target.props, input.props) : target.props,
+    props: sanitizeProps(mergedProps),
   };
   const next = sortItems(items.map((i) => (i.id === input.id ? updated : i)));
   return {
@@ -121,16 +150,35 @@ export function handleUpdate(items: ScheduledItem[], input: SchedulerActionInput
   };
 }
 
+// `replace` accepts an arbitrary array from untrusted JSON, so
+// every item needs the same shape narrowing the in-memory store
+// guarantees: a non-empty string `id` (the dispatch primary key
+// AND the input to the per-event colour-hash, both of which crash
+// or misbehave on non-strings), a string `title`, a numeric
+// `createdAt`, and a sanitised `props`. Non-object items are
+// dropped; objects with missing/malformed required fields get a
+// safe default (newly minted id, empty title, current timestamp)
+// rather than failing the whole replace.
+export function sanitizeItem(raw: unknown): ScheduledItem | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const obj = raw as Partial<ScheduledItem>;
+  const itemId = typeof obj.id === "string" && obj.id.length > 0 ? obj.id : makeId("sched");
+  const title = typeof obj.title === "string" ? obj.title : "";
+  const createdAt = typeof obj.createdAt === "number" && Number.isFinite(obj.createdAt) ? obj.createdAt : Date.now();
+  return { id: itemId, title, createdAt, props: sanitizeProps(obj.props) };
+}
+
 export function handleReplace(_items: ScheduledItem[], input: SchedulerActionInput): SchedulerActionResult {
   if (!Array.isArray(input.items)) {
     return { kind: "error", status: 400, error: "items array required" };
   }
-  const next = sortItems(input.items);
+  const sanitized = input.items.map(sanitizeItem).filter((item): item is ScheduledItem => item !== null);
+  const next = sortItems(sanitized);
   return {
     kind: "success",
     items: next,
     message: `Replaced all items (${next.length} total)`,
-    jsonData: { count: next.length },
+    jsonData: { count: next.length, dropped: input.items.length - next.length },
   };
 }
 

package/server/api/routes/sessions.ts

@@ -79,7 +79,18 @@ export interface SessionSummary {
   isBookmarked?: boolean;
   // Live state from the in-memory session store. Absent when the
   // session has no active entry in the store (i.e. idle / historical).
+  //
+  // `isRunning` is the BROAD predicate: agent turn live OR any
+  // background generation (image/audio/movie) still pending. Drives
+  // the sidebar "busy" indicator that must stay lit across nav.
+  //
+  // `liveIsRunning` is the NARROW predicate: exactly the
+  // `DELETE /api/sessions/:id` 409 gate (`getSession()?.isRunning`).
+  // Exposed for cleanup-style callers (e2e-live `waitForSessionIdle`)
+  // that need to poll "is DELETE accepted yet" without over-waiting
+  // on lingering pendingGenerations. See issue #1195.
   isRunning?: boolean;
+  liveIsRunning?: boolean;
   hasUnread?: boolean;
   statusMessage?: string;
 }
@@ -149,6 +160,10 @@ function buildSessionSummary(
     // "busy" even when the agent turn has ended, so the sidebar
     // indicator stays lit across view navigation.
     summary.isRunning = live.isRunning || Object.keys(live.pendingGenerations).length > 0;
+    // Narrow predicate — must stay byte-identical to the DELETE
+    // 409 gate (`getSession(sessionId)?.isRunning`) so a caller
+    // polling this can trust "false ⇒ DELETE will be accepted".
+    summary.liveIsRunning = live.isRunning;
     summary.statusMessage = live.statusMessage;
   }
   return summary;