mulmoclaude 0.3.0 → 0.5.0

package/server/agent/mcp-server.ts

@@ -11,10 +11,12 @@ import { errorMessage } from "../utils/errors.js";
 import { isNonEmptyString, isRecord } from "../utils/types.js";
 import { API_ROUTES } from "../../src/config/apiRoutes.js";
 import { env } from "../system/env.js";
-import { extractFetchError } from "../utils/fetch.js";
+import { extractFetchError, fetchWithTimeout } from "../utils/fetch.js";
+import { ONE_MINUTE_MS, ONE_SECOND_MS } from "../utils/time.js";
 import { safeResponseText } from "../utils/http.js";
 import { readTextSafeSync } from "../utils/files/safe.js";
 import { WORKSPACE_PATHS } from "../workspace/paths.js";
+import { makeUuid } from "../utils/id.js";
 
 type JsonRpcId = string | number | null;
 
@@ -112,6 +114,25 @@ const ALL_TOOLS: Record<string, ToolDef> = {
 
 const tools = PLUGIN_NAMES.map((name) => ALL_TOOLS[name]).filter(Boolean);
 
+// MCP tools (e.g. readXPost, searchX) call external APIs through their
+// own handlers. The bridge timeout must exceed those inner timeouts
+// plus a small buffer for JSON parsing / HTTP round-trip, otherwise the
+// bridge aborts before the handler can return a formatted error.
+// Currently the slowest inner timeout is the X API (20 s); 30 s gives
+// 10 s of headroom and still lands well inside the MCP client's own
+// 30-60 s tool-call window.
+const MCP_TOOL_BRIDGE_TIMEOUT_MS = 30 * ONE_SECOND_MS;
+
+// Plugin tools (e.g. presentDocument, openCanvas) may invoke generative
+// AI — image generation routinely takes 10–30 s per call, video can run
+// for several minutes, and a single tool invocation can fan out to
+// multiple parallel generations. The bridge MUST stay out of the way:
+// set a ceiling far above any realistic completion time so the limiting
+// factor is the agent SDK's own tool-call window, never this fetch.
+// Pick 20 minutes — long enough for batch image gen + future video gen,
+// short enough that a truly wedged Express handler still surfaces.
+const PLUGIN_BRIDGE_TIMEOUT_MS = 20 * ONE_MINUTE_MS;
+
 function respond(msg: unknown): void {
   process.stdout.write(JSON.stringify(msg) + "\n");
 }
@@ -130,8 +151,42 @@ function respond(msg: unknown): void {
 // Pass `allowHttpError: true` for callers that want to inspect the
 // response themselves (e.g. /api/mcp-tools/* which has its own
 // status-aware result handling).
+//
+// =====================================================================
+// TIMEOUT POLICY — read this before adding a new bridge call
+// =====================================================================
+// The default `timeoutMs` from `fetchWithTimeout` is 10 s, sized for
+// healthy localhost round-trips. THAT IS TOO SHORT for any handler
+// that fans out to generative AI (image / video / model calls) or
+// hits a slow external API. Whenever the downstream handler can
+// legitimately take longer than ~5 s, the caller MUST pass an
+// explicit `timeoutMs` that comfortably exceeds the worst realistic
+// completion time:
+//
+//   - Generative AI plugins (presentDocument, openCanvas, …)
+//     → use `PLUGIN_BRIDGE_TIMEOUT_MS` (20 min). Image batches and
+//       future video generation MUST NOT be limited by the bridge.
+//   - External-API MCP tools (readXPost, searchX, …)
+//     → use `MCP_TOOL_BRIDGE_TIMEOUT_MS` (30 s) or a custom value
+//       larger than the inner API's own timeout.
+//   - Pure server-state RPCs (toolResult push, role switch, …)
+//     → default 10 s is fine; these are local JSON round-trips.
+//
+// On EVERY failure (timeout, abort, connection reset, HTTP 5xx) this
+// function MUST emit an error log to stderr. Silent timeouts are the
+// exact failure mode that hid the original bug — the server kept
+// generating images, the bridge gave up at 10 s, and the user saw
+// "tool failed" with no trace in the logs. If you change the catch
+// block below, keep the log emission.
+// =====================================================================
 interface PostJsonOpts {
   allowHttpError?: boolean;
+  // Override the default bridge-call timeout. Needed when the
+  // downstream handler itself does slow work (e.g. /api/mcp-tools/*
+  // that hits an external API): the bridge must wait long enough for
+  // the handler's own timeout to fire, otherwise the outer abort
+  // preempts a formatted error.
+  timeoutMs?: number;
 }
 
 async function postJson(path: string, body: unknown, opts: PostJsonOpts = {}): Promise<Response> {
@@ -141,18 +196,33 @@ async function postJson(path: string, body: unknown, opts: PostJsonOpts = {}): P
   // The path arg is used as-is because all current call sites pass
   // hardcoded literals.
   let res: Response;
+  const startedAt = Date.now();
   try {
-    res = await fetch(`${BASE_URL}${path}?session=${encodeURIComponent(SESSION_ID)}`, {
+    res = await fetchWithTimeout(`${BASE_URL}${path}?session=${encodeURIComponent(SESSION_ID)}`, {
       method: "POST",
       headers: { "Content-Type": "application/json", ...AUTH_HEADER },
       body: JSON.stringify(body),
+      timeoutMs: opts.timeoutMs,
     });
   } catch (err) {
+    // `fetchWithTimeout` throws a DOMException("TimeoutError") when
+    // the timer fires; surface that case explicitly so the operator
+    // can tell "timeout vs. connection error" at a glance.
+    const elapsedMs = Date.now() - startedAt;
+    const isTimeout = err instanceof DOMException && err.name === "TimeoutError";
+    const kind = isTimeout ? "TIMEOUT" : "NETWORK";
+    console.error(`[mcp-bridge] ${kind} ${path} after ${elapsedMs}ms (timeoutMs=${opts.timeoutMs ?? "default"}): ${errorMessage(err)}`);
     throw new Error(`Network error calling ${path}: ${errorMessage(err)}`);
   }
   if (!opts.allowHttpError && !res.ok) {
     const errBody = await safeResponseText(res, 500);
     const detail = errBody ? `: ${errBody}` : "";
+    // Mirror the network/timeout error path above — log to stderr so
+    // an HTTP 4xx/5xx from the server never hides from the bridge
+    // operator. Without this, the thrown Error propagates silently
+    // to the MCP caller and the log stream shows nothing.
+    const elapsedMs = Date.now() - startedAt;
+    console.error(`[mcp-bridge] HTTP ${res.status} ${path} after ${elapsedMs}ms${detail}`);
     throw new Error(`HTTP ${res.status} calling ${path}${detail}`);
   }
   return res;
@@ -176,7 +246,7 @@ async function fetchSkillsList(): Promise<{ name: string }[]> {
   const url = `${BASE_URL}/api/skills?session=${encodeURIComponent(SESSION_ID)}`;
   let res: Response;
   try {
-    res = await fetch(url, { headers: AUTH_HEADER });
+    res = await fetchWithTimeout(url, { headers: AUTH_HEADER });
   } catch (err) {
     throw new Error(`Network error calling /api/skills: ${errorMessage(err)}`);
   }
@@ -192,7 +262,7 @@ async function pushSkillsListResult(message: string): Promise<void> {
   const skills = await fetchSkillsList();
   await postJson(API_ROUTES.agent.internal.toolResult, {
     toolName: "manageSkills",
-    uuid: crypto.randomUUID(),
+    uuid: makeUuid(),
     title: "Skills",
     message,
     data: { skills },
@@ -204,7 +274,7 @@ async function handleManageSkillsList(): Promise<string> {
   const suffix = skills.length === 1 ? "" : "s";
   await postJson(API_ROUTES.agent.internal.toolResult, {
     toolName: "manageSkills",
-    uuid: crypto.randomUUID(),
+    uuid: makeUuid(),
     title: "Skills",
     message: `Found ${skills.length} skill${suffix}.`,
     data: { skills },
@@ -237,7 +307,7 @@ async function handleManageSkillsUpdate(args: Record<string, unknown>): Promise<
   const url = `${BASE_URL}/api/skills/${encodeURIComponent(name)}?session=${encodeURIComponent(SESSION_ID)}`;
   let res: Response;
   try {
-    res = await fetch(url, {
+    res = await fetchWithTimeout(url, {
       method: "PUT",
       headers: { ...AUTH_HEADER, "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -260,7 +330,7 @@ async function handleManageSkillsDelete(args: Record<string, unknown>): Promise<
   const url = `/api/skills/${encodeURIComponent(name)}?session=${encodeURIComponent(SESSION_ID)}`;
   let res: Response;
   try {
-    res = await fetch(`${BASE_URL}${url}`, {
+    res = await fetchWithTimeout(`${BASE_URL}${url}`, {
       method: "DELETE",
       headers: AUTH_HEADER,
     });
@@ -290,7 +360,7 @@ async function handleToolCall(name: string, args: Record<string, unknown>): Prom
     if (args.action === "list" && result.success) {
       await postJson(API_ROUTES.agent.internal.toolResult, {
         toolName: "manageRoles",
-        uuid: crypto.randomUUID(),
+        uuid: makeUuid(),
         ...result,
       });
     }
@@ -303,10 +373,14 @@ async function handleToolCall(name: string, args: Record<string, unknown>): Prom
   // Pure MCP tools — call via /api/mcp-tools/:tool, return text directly
   // (no frontend push). Opt out of postJson's HTTP error throw because
   // we want to surface the JSON error body to the caller as a string.
+  // The tool handler may hit a slow external API (e.g. X), so pass a
+  // longer bridge timeout than the default 10 s used for localhost
+  // roundtrips — see MCP_TOOL_BRIDGE_TIMEOUT_MS.
   const mcpTool = mcpTools.find((toolDef) => toolDef.definition.name === name);
   if (mcpTool) {
     const res = await postJson(`/api/mcp-tools/${name}`, args, {
       allowHttpError: true,
+      timeoutMs: MCP_TOOL_BRIDGE_TIMEOUT_MS,
     });
     const json = await res.json();
     if (!res.ok) return `Error: ${json.error ?? res.status}`;
@@ -316,13 +390,17 @@ async function handleToolCall(name: string, args: Record<string, unknown>): Prom
   const tool = tools.find((toolDef) => toolDef.name === name);
   if (!tool) throw new Error(`Unknown tool: ${name}`);
 
-  const res = await postJson(tool.endpoint!, args);
+  // Plugin handlers can fan out to generative AI (image batches via
+  // presentDocument, future video). The bridge MUST wait long enough
+  // for the slowest realistic completion — see PLUGIN_BRIDGE_TIMEOUT_MS
+  // and the timeout-policy comment on `postJson`.
+  const res = await postJson(tool.endpoint!, args, { timeoutMs: PLUGIN_BRIDGE_TIMEOUT_MS });
   const result = await res.json();
 
   // Push visual ToolResult to the frontend via the session
   await postJson(API_ROUTES.agent.internal.toolResult, {
     toolName: name,
-    uuid: crypto.randomUUID(),
+    uuid: makeUuid(),
     ...result,
   });
 

package/server/agent/mcp-tools/index.ts

@@ -1,5 +1,6 @@
 import { Router, Request, Response } from "express";
 import { readXPost, searchX } from "./x.js";
+import { notify } from "./notify.js";
 import { errorMessage } from "../../utils/errors.js";
 import { notFound, sendError, serverError } from "../../utils/httpError.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
@@ -15,9 +16,9 @@ export interface McpTool {
   handler: (args: Record<string, unknown>) => Promise<string>;
 }
 
-export const mcpTools: McpTool[] = [readXPost, searchX];
+export const mcpTools: McpTool[] = [readXPost, searchX, notify];
 
-const toolMap = new Map(mcpTools.map((t) => [t.definition.name, t]));
+const toolMap = new Map(mcpTools.map((tool) => [tool.definition.name, tool]));
 
 export function isMcpToolEnabled(tool: McpTool): boolean {
   return (tool.requiredEnv ?? []).every((key) => !!process.env[key]);
@@ -34,11 +35,11 @@ interface McpToolParams {
 // GET /api/mcp-tools — returns { name, enabled, requiredEnv } for each tool (used by the role builder UI)
 mcpToolsRouter.get(API_ROUTES.mcpTools.list, (_req: Request, res: Response) => {
   res.json(
-    mcpTools.map((t) => ({
-      name: t.definition.name,
-      enabled: isMcpToolEnabled(t),
-      requiredEnv: t.requiredEnv ?? [],
-      prompt: t.prompt,
+    mcpTools.map((tool) => ({
+      name: tool.definition.name,
+      enabled: isMcpToolEnabled(tool),
+      requiredEnv: tool.requiredEnv ?? [],
+      prompt: tool.prompt,
     })),
   );
 });

package/server/agent/mcp-tools/notify.ts

@@ -0,0 +1,76 @@
+// `notify` MCP tool — exposes the server's notification bus to the
+// agent so the user can ask "通知して" / "monitor the build and tell
+// me when it's done" and the agent has a direct way to fire.
+//
+// Calls `publishNotification` with `kind: "push"`, which fans out
+// to:
+//   - Web bell
+//   - Bridge (if a transportId is supplied — N/A from this entry
+//     point)
+//   - macOS Reminders (#789, on darwin unless the user has set
+//     DISABLE_MACOS_REMINDER_NOTIFICATIONS=1)
+//
+// No active-user gate. If the user asks for a notification, fire it.
+//
+// `body` is optional and only forwarded when non-empty. `title` is
+// required and trimmed.
+//
+// `publishNotification` is injected via `makeNotifyTool({ publish })`
+// (#803) so unit tests can pass a mock and stay free of macOS / bell
+// side effects. The default singleton `notify` wires the real
+// implementation.
+
+import { publishNotification } from "../../events/notifications.js";
+import { NOTIFICATION_KINDS } from "../../../src/types/notification.js";
+
+export type NotifyPublishFn = typeof publishNotification;
+
+export interface NotifyToolDeps {
+  publish: NotifyPublishFn;
+}
+
+export function makeNotifyTool(deps: NotifyToolDeps) {
+  return {
+    definition: {
+      name: "notify",
+      description:
+        "Send the user a push-style notification (web bell + macOS Reminders if MACOS_REMINDER_NOTIFICATIONS=1 + bridge). Use to report completion of long-running tasks, surface monitoring results, or proactively notify the user when they may be away from the keyboard.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string",
+            description: "Short notification headline. Keep it concise — emojis OK.",
+          },
+          body: {
+            type: "string",
+            description: "Optional longer detail line. Omit when the title is self-explanatory.",
+          },
+        },
+        required: ["title"],
+      },
+    },
+
+    prompt:
+      "Use the `notify` MCP tool — NOT a user-installed `/notify` skill — when the user asks for a notification ('通知して' / 'remind me' / 'tell me when …') or when reporting completion of a long-running task / monitoring summary / scheduled reminder firing. " +
+      "This is the canonical built-in notification path: it fans out to the web bell, any active bridge transport, and macOS Reminders (when MACOS_REMINDER_NOTIFICATIONS=1 + darwin), and has NO active-user suppression — if the user asks for a notification, fire one. " +
+      "After firing, briefly tell the user you sent the notification.",
+
+    async handler(args: Record<string, unknown>): Promise<string> {
+      const title = typeof args.title === "string" ? args.title.trim() : "";
+      if (!title) return "notify: `title` is required (non-empty string).";
+      const bodyRaw = typeof args.body === "string" ? args.body.trim() : "";
+      const body = bodyRaw.length > 0 ? bodyRaw : undefined;
+
+      deps.publish({
+        kind: NOTIFICATION_KINDS.push,
+        title,
+        body,
+      });
+      return body ? `Notification sent: ${title}\n${body}` : `Notification sent: ${title}`;
+    },
+  };
+}
+
+// Production singleton wired with the real publishNotification.
+export const notify = makeNotifyTool({ publish: publishNotification });

package/server/agent/mcp-tools/x.ts

@@ -1,8 +1,17 @@
 import { errorMessage } from "../../utils/errors.js";
+import { fetchWithTimeout } from "../../utils/fetch.js";
 import { safeResponseText } from "../../utils/http.js";
+import { toUtcIsoDate } from "../../utils/date.js";
+import { ONE_SECOND_MS } from "../../utils/time.js";
 import { env } from "../../system/env.js";
 
 const X_API_BASE = "https://api.twitter.com/2";
+
+// X API can stall under rate limit — a 10 s default (used for internal
+// localhost calls) would produce false timeouts. 20 s gives enough
+// headroom for a slow but real response while still bailing long
+// before the MCP client's tool-call timeout fires.
+const X_API_TIMEOUT_MS = 20 * ONE_SECOND_MS;
 const TWEET_FIELDS = "tweet.fields=created_at,author_id,public_metrics,entities";
 const EXPANSIONS = "expansions=author_id";
 const USER_FIELDS = "user.fields=name,username";
@@ -38,8 +47,9 @@ async function fetchX(path: string): Promise<XApiResponse> {
 
   let response: Response;
   try {
-    response = await fetch(`${X_API_BASE}${path}`, {
+    response = await fetchWithTimeout(`${X_API_BASE}${path}`, {
       headers: { Authorization: `Bearer ${token}` },
+      timeoutMs: X_API_TIMEOUT_MS,
     });
   } catch (err) {
     throw new Error(`Network error calling X API: ${errorMessage(err)}`);
@@ -56,7 +66,7 @@ async function fetchX(path: string): Promise<XApiResponse> {
 }
 
 function formatTweet(tweet: XTweet, author?: XUser, url?: string): string {
-  const date = tweet.created_at ? new Date(tweet.created_at).toISOString().split("T")[0] : "";
+  const date = tweet.created_at ? toUtcIsoDate(new Date(tweet.created_at)) : "";
   const dateSuffix = date ? ` · ${date}` : "";
   const byline = author ? `@${author.username} (${author.name})${dateSuffix}` : date;
   const metrics = tweet.public_metrics

package/server/agent/plugin-names.ts

@@ -5,7 +5,8 @@
  */
 
 import TodoDef from "../../src/plugins/todo/definition.js";
-import SchedulerDef from "../../src/plugins/scheduler/definition.js";
+import ManageCalendarDef from "../../src/plugins/scheduler/calendarDefinition.js";
+import ManageAutomationsDef from "../../src/plugins/scheduler/automationsDefinition.js";
 import PresentMulmoScriptDef from "../../src/plugins/presentMulmoScript/definition.js";
 import ManageRolesDef from "../../src/plugins/manageRoles/definition.js";
 import ManageSkillsDef from "../../src/plugins/manageSkills/definition.js";
@@ -18,7 +19,7 @@ import SpreadsheetDef from "../../src/plugins/spreadsheet/definition.js";
 import { TOOL_DEFINITION as MindMapDef } from "@gui-chat-plugin/mindmap";
 import GenerateImageDef from "../../src/plugins/generateImage/definition.js";
 import { TOOL_DEFINITION as QuizDef } from "@mulmochat-plugin/quiz";
-import { TOOL_DEFINITION as FormDef } from "@mulmochat-plugin/form";
+import { TOOL_DEFINITION as FormDef } from "../../src/plugins/presentForm/definition.js";
 import CanvasDef from "../../src/plugins/canvas/definition.js";
 import EditImageDef from "../../src/plugins/editImage/definition.js";
 import { TOOL_DEFINITION as Present3DDef } from "@gui-chat-plugin/present3d";
@@ -27,7 +28,11 @@ import { API_ROUTES } from "../../src/config/apiRoutes.js";
 /** Maps plugin tool name → REST API endpoint. */
 export const TOOL_ENDPOINTS: Record<string, string> = {
   [TodoDef.name]: API_ROUTES.todos.dispatch,
-  [SchedulerDef.name]: API_ROUTES.scheduler.base,
+  // Both halves of the former manageScheduler share the same backend
+  // endpoint (#824 / PR #758). Server-side dispatch routes per-action
+  // via TASK_ACTIONS, so one route happily handles both tool names.
+  [ManageCalendarDef.name]: API_ROUTES.scheduler.base,
+  [ManageAutomationsDef.name]: API_ROUTES.scheduler.base,
   [MarkdownDef.name]: API_ROUTES.plugins.presentDocument,
   [SpreadsheetDef.name]: API_ROUTES.plugins.presentSpreadsheet,
   [MindMapDef.name]: API_ROUTES.plugins.mindmap,
@@ -49,7 +54,8 @@ export const TOOL_ENDPOINTS: Record<string, string> = {
 /** All ToolDefinition objects for package and local plugins. */
 export const PLUGIN_DEFS = [
   TodoDef,
-  SchedulerDef,
+  ManageCalendarDef,
+  ManageAutomationsDef,
   PresentMulmoScriptDef,
   MarkdownDef,
   SpreadsheetDef,

package/server/agent/prompt.ts

@@ -7,6 +7,8 @@ import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../workspace/paths.js";
 import { getCachedCustomDirs, buildCustomDirsPrompt } from "../workspace/custom-dirs.js";
 import { TOOL_NAMES } from "../../src/config/toolNames.js";
 import { getCachedReferenceDirs, buildReferenceDirsPrompt } from "../workspace/reference-dirs.js";
+import { log } from "../system/logger/index.js";
+import { toLocalIsoDate } from "../utils/date.js";
 
 export const SYSTEM_PROMPT = `You are MulmoClaude, a versatile assistant app with rich visual output.
 
@@ -242,6 +244,35 @@ export function buildNewsConciergeContext(role: Role): string | null {
   return NEWS_CONCIERGE_PROMPT;
 }
 
+// Single-paragraph prompts up to this length collapse into a compact
+// `- **name**: body` bullet instead of the old `### name\n\n body`
+// heading. Saves ~25 chars of heading overhead per plugin and keeps the
+// whole "Plugin Instructions" block scannable. Multi-paragraph or
+// longer prompts keep the heading form so the structure is preserved.
+const PLUGIN_COMPACT_MAX_CHARS = 400;
+
+export function formatPluginSection(name: string, prompt: string): string {
+  // Normalize CRLF → LF first: a prompt authored on Windows would
+  // otherwise hide its paragraph break inside `\r\n\r\n` and the
+  // `includes("\n\n")` check would falsely classify it as single-paragraph,
+  // collapsing a multi-paragraph prompt into one bullet.
+  const normalized = prompt.replace(/\r\n/g, "\n");
+  const trimmed = normalized.trim();
+  const isSingleParagraph = !trimmed.includes("\n\n");
+  if (isSingleParagraph && trimmed.length <= PLUGIN_COMPACT_MAX_CHARS) {
+    // Flatten any single newlines inside the paragraph so the bullet
+    // stays on one visual line. Split-join avoids the super-linear
+    // backtracking that `\s*\n\s*` would bring (sonarjs/slow-regex).
+    const oneLine = trimmed
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .join(" ");
+    return `- **${name}**: ${oneLine}`;
+  }
+  return `### ${name}\n\n${trimmed}`;
+}
+
 export function buildPluginPromptSections(role: Role): string[] {
   // Widen to Set<string> so the `.has()` checks accept arbitrary
   // definition names (PLUGIN_DEFS entries and MCP tool names are
@@ -268,7 +299,7 @@ export function buildPluginPromptSections(role: Role): string[] {
 
   // MCP tool prompts override definition prompts if both exist
   const merged = { ...defPrompts, ...mcpToolPrompts };
-  return Object.entries(merged).map(([name, prompt]) => `### ${name}\n\n${prompt}`);
+  return Object.entries(merged).map(([name, prompt]) => formatPluginSection(name, prompt));
 }
 
 export interface SystemPromptParams {
@@ -279,6 +310,61 @@ export interface SystemPromptParams {
    *  environment has no such guarantees, so without Docker we stay
    *  silent. */
   useDocker: boolean;
+  /** IANA timezone from the user's browser (e.g. "Asia/Tokyo"). When
+   *  present, drives the time-section instruction that tells the
+   *  agent to interpret bare times in that zone without asking the
+   *  user every turn. Missing or invalid values fall back to
+   *  server-local date only. */
+  userTimezone?: string;
+}
+
+// Accept IANA-looking strings only. Anything else (including
+// line-break injection attempts from a malicious client) is rejected
+// and the prompt falls back to the server-local form.
+const IANA_TZ_RE = /^[A-Za-z][A-Za-z0-9_+/-]{0,63}$/;
+function sanitizeUserTimezone(zoneId: string | undefined): string | undefined {
+  if (typeof zoneId !== "string") return undefined;
+  if (!IANA_TZ_RE.test(zoneId)) return undefined;
+  try {
+    // Throws a RangeError if the zone isn't recognized by the ICU
+    // data on this runtime.
+    new Intl.DateTimeFormat("en-US", { timeZone: zoneId });
+    return zoneId;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatDateInTimezone(date: Date, zoneId: string): string | null {
+  try {
+    // en-CA gives us YYYY-MM-DD directly, matching the rest of the
+    // workspace's date convention.
+    return new Intl.DateTimeFormat("en-CA", {
+      timeZone: zoneId,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(date);
+  } catch {
+    return null;
+  }
+}
+
+// Compact prompt section that tells the agent (a) today's date in the
+// user's zone and (b) not to pester the user about timezones for every
+// bare time expression. Falls back to server-local date (previous
+// behaviour) when the browser didn't give us a valid zone.
+export function buildTimeSection(now: Date, userTimezone: string | undefined): string {
+  const sanitized = sanitizeUserTimezone(userTimezone);
+  if (!sanitized) {
+    return `Today's date: ${toLocalIsoDate(now)}`;
+  }
+  const today = formatDateInTimezone(now, sanitized) ?? toLocalIsoDate(now);
+  return `## Time & Timezone
+
+The user's browser timezone is ${sanitized}. Today's date in that timezone is ${today}.
+
+When the user mentions a time without explicitly naming a city or timezone, assume their local timezone (${sanitized}) and proceed — do NOT ask for clarification. Only confirm when the user explicitly mentions another location or timezone (e.g. "3pm in New York", "JST", "UTC+5").`;
 }
 
 // Mirror the tool set installed by Dockerfile.sandbox. Kept here so a
@@ -295,7 +381,47 @@ The bash tool runs inside a Docker sandbox. The following tools are guaranteed p
 
 Runtime \`pip install\` / \`apt install\` are not available (no network-installed deps by design). Work within the list above; if something is missing, say so rather than attempting to install it.`;
 
-function buildInlinedHelpFiles(rolePrompt: string, workspacePath: string): string[] {
+// Files ≤ this threshold stay inlined verbatim; above it, only a short
+// summary + pointer reaches the system prompt and the full content is
+// fetched on demand via the Read tool. 2000 chars keeps today's small
+// helps (github.md ~1.2K, spreadsheet.md ~1.4K) inline, while wiki.md /
+// mulmoscript.md / telegram.md (4–7K each) switch to summary mode. See
+// plans/done/feat-help-pointer-threshold.md and issue #487.
+const HELP_INLINE_THRESHOLD_CHARS = 2000;
+const HELP_SUMMARY_PARAGRAPH_CAP = 200;
+
+// Pull a short, prompt-friendly summary from a help file:
+// - first H1 heading (identifies the file)
+// - first non-empty, non-heading paragraph, truncated to ~200 chars
+// No frontmatter required — the goal is zero ceremony for help authors.
+export function summarizeHelpContent(content: string): string {
+  const lines = content.split("\n");
+  const heading = lines
+    .find((line) => /^#\s+\S/.test(line))
+    ?.replace(/^#\s+/, "")
+    .trim();
+
+  let paragraph = "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      if (paragraph) break;
+      continue;
+    }
+    paragraph = paragraph ? `${paragraph} ${trimmed}` : trimmed;
+    if (paragraph.length >= HELP_SUMMARY_PARAGRAPH_CAP) break;
+  }
+  if (paragraph.length > HELP_SUMMARY_PARAGRAPH_CAP) {
+    paragraph = paragraph.slice(0, HELP_SUMMARY_PARAGRAPH_CAP).trimEnd() + "…";
+  }
+
+  const parts: string[] = [];
+  if (heading) parts.push(heading);
+  if (paragraph) parts.push(paragraph);
+  return parts.join(" — ");
+}
+
+export function buildInlinedHelpFiles(rolePrompt: string, workspacePath: string): string[] {
   // Match either legacy `helps/<name>.md` or post-#284
   // `config/helps/<name>.md` references in role prompts. Both
   // resolve to the same on-disk file under `config/helps/`.
@@ -310,10 +436,17 @@ function buildInlinedHelpFiles(rolePrompt: string, workspacePath: string): strin
       const fullPath = join(workspacePath, WORKSPACE_DIRS.helps, name);
       if (!existsSync(fullPath)) return null;
       const content = readFileSync(fullPath, "utf-8").trim();
-      // Keep the heading anchored to the canonical post-#284 path
-      // so the LLM reading the inlined block can't accidentally
-      // Read() the stale legacy location.
-      return content ? `### ${WORKSPACE_DIRS.helps}/${name}\n\n${content}` : null;
+      if (!content) return null;
+      // Keep the heading anchored to the canonical post-#284 path so
+      // the LLM can't accidentally Read() the stale legacy location.
+      const canonicalPath = `${WORKSPACE_DIRS.helps}/${name}`;
+      const header = `### ${canonicalPath}`;
+      if (content.length <= HELP_INLINE_THRESHOLD_CHARS) {
+        return `${header}\n\n${content}`;
+      }
+      const summary = summarizeHelpContent(content);
+      const pointer = `Detailed reference: use Read on \`${canonicalPath}\` when you need the full content.`;
+      return summary ? `${header}\n\n${summary}\n\n${pointer}` : `${header}\n\n${pointer}`;
     })
     .filter((section): section is string => section !== null);
 }
@@ -328,27 +461,55 @@ export function headingSection(heading: string, items: string[]): string | null
   return `## ${heading}\n\n${items.join("\n\n")}`;
 }
 
+// Named sections so buildSystemPrompt can log a size breakdown
+// without inventing labels at the call site.
+interface NamedSection {
+  name: string;
+  content: string | null;
+}
+
+// System prompt above this total size gets a warning in the log —
+// 20K chars is ~5K tokens, a noticeable slice of the context budget
+// and a useful early-warning threshold. Doesn't block, just flags.
+const SYSTEM_PROMPT_WARN_THRESHOLD_CHARS = 20000;
+
 export function buildSystemPrompt(params: SystemPromptParams): string {
-  const { role, workspacePath, useDocker } = params;
-
-  // Every section builder returns either its content or null. The
-  // orchestrator just filters out nulls and joins — no per-section
-  // `...(cond ? [x] : [])` ceremony at the bottom.
-  const sections: Array<string | null> = [
-    SYSTEM_PROMPT,
-    role.prompt,
-    `Workspace directory: ${workspacePath}`,
-    `Today's date: ${new Date().toISOString().split("T")[0]}`,
-    buildMemoryContext(workspacePath),
-    useDocker ? SANDBOX_TOOLS_HINT : null,
-    buildWikiContext(workspacePath),
-    buildSourcesContext(workspacePath),
-    buildNewsConciergeContext(role),
-    buildCustomDirsPrompt(getCachedCustomDirs()),
-    buildReferenceDirsPrompt(getCachedReferenceDirs(), useDocker),
-    headingSection("Reference Files", buildInlinedHelpFiles(role.prompt, workspacePath)),
-    headingSection("Plugin Instructions", buildPluginPromptSections(role)),
+  const { role, workspacePath, useDocker, userTimezone } = params;
+
+  const sections: NamedSection[] = [
+    { name: "base", content: SYSTEM_PROMPT },
+    { name: "role", content: role.prompt },
+    { name: "workspace", content: `Workspace directory: ${workspacePath}` },
+    { name: "time", content: buildTimeSection(new Date(), userTimezone) },
+    { name: "memory", content: buildMemoryContext(workspacePath) },
+    { name: "sandbox", content: useDocker ? SANDBOX_TOOLS_HINT : null },
+    { name: "wiki", content: buildWikiContext(workspacePath) },
+    { name: "sources", content: buildSourcesContext(workspacePath) },
+    { name: "news-concierge", content: buildNewsConciergeContext(role) },
+    { name: "custom-dirs", content: buildCustomDirsPrompt(getCachedCustomDirs()) },
+    { name: "reference-dirs", content: buildReferenceDirsPrompt(getCachedReferenceDirs(), useDocker) },
+    { name: "helps", content: headingSection("Reference Files", buildInlinedHelpFiles(role.prompt, workspacePath)) },
+    { name: "plugins", content: headingSection("Plugin Instructions", buildPluginPromptSections(role)) },
   ];
 
-  return sections.filter((section): section is string => section !== null).join("\n\n");
+  const kept = sections.filter((section): section is NamedSection & { content: string } => section.content !== null);
+  const result = kept.map((section) => section.content).join("\n\n");
+
+  // Log a size breakdown so prompt-bloat regressions show up in
+  // normal run logs. Warn tier fires for outright large prompts;
+  // the debug tier gives the per-section counts for when the
+  // warning hits (or just when someone wants a baseline).
+  const breakdown = kept.map((section) => `${section.name}=${section.content.length}`).join(" ");
+  const total = result.length;
+  log.debug("prompt", "system-prompt size", { total, breakdown, roleId: role.id });
+  if (total >= SYSTEM_PROMPT_WARN_THRESHOLD_CHARS) {
+    log.warn("prompt", "system-prompt exceeds warn threshold", {
+      total,
+      threshold: SYSTEM_PROMPT_WARN_THRESHOLD_CHARS,
+      breakdown,
+      roleId: role.id,
+    });
+  }
+
+  return result;
 }