@mulmoclaude/core 1.4.0 → 1.6.0

package/assets/helps/bug-report-faq.md

@@ -0,0 +1,130 @@
+# Bug-report FAQ — check these before calling it a bug
+
+This file is an **index, not an answer sheet**. It never states a value ("the default is off"), only
+where today's truth lives, because the agent reads the real thing at run time. Values rot silently;
+a config key or a file path cannot — rename one and the implementation stops working, so it gets
+fixed.
+
+Each entry's `configKey:` / `source:` / `help:` lines are **verified by CI**: a key that no longer
+exists, or a path that moved, fails the test rather than misleading a user months later.
+
+Read in this order, because only the first two are available to every user:
+
+1. **`configKey:`** — the live value, from `config/settings.json` in the workspace. Absent from the
+   file means the setting is at its default, which is the answer to most entries here.
+2. **`help:`** — another page in `config/helps/`, always present.
+3. **`source:`** — a path in the MulmoClaude **repository**. Only readable when running from a clone
+   (`yarn dev`); an `npx mulmoclaude` user has no repo, so never tell them to open one. It is listed
+   so CI can prove the pointer is still real, and for whoever ends up fixing the code.
+
+Entry format:
+
+```
+## The symptom, in the words a user would say
+
+configKey: <a key in config/settings.json>   (optional, repeatable)
+source: <path in the MulmoClaude repo>       (optional, repeatable)
+help: <another page in config/helps/>        (optional, repeatable)
+
+What to check. Never what the value is.
+```
+
+Maintained by hand, in the repo. This file is the source of truth; the issue tracker is the inbox.
+
+---
+
+## Voice input does nothing, or the mic button is disabled
+
+configKey: voiceInput
+source: packages/core/src/whisper
+help: error-recovery.md
+
+Read `voiceInput` from the live settings — a key absent from the file has never been touched, and
+turning it on is what triggers the model download. Three separate conditions gate the mic button:
+platform capability, the opt-in, and whether the model finished downloading. `GET /api/health`
+reports all three as `voiceInput`, so check it before deciding which one is missing — "on but still
+greyed out" is a different question from "never turned on".
+
+## I don't get a notification when a task finishes
+
+configKey: pushEnabled
+source: server/agent/webPush.ts
+help: remote-host.md
+
+Two conditions must hold at once, so read both before calling it a bug. `pushEnabled` in the live
+settings is the user's opt-in. The RemoteHost channel must also be connected — that connection is
+what supplies the Firebase auth, so with the phone link down the send is a no-op by design. A user
+who never connected a phone has nothing to receive the push regardless of the setting.
+
+## My chats never get titles or summaries
+
+configKey: chatIndex
+source: server/workspace/chat-index/indexer.ts
+
+Read `chatIndex` — it names the model the background summarizer spawns, and the summarizer does
+nothing until it does. One exception worth knowing before calling it a bug: sessions that didn't
+originate from the user (`system`, `scheduler`) are always skipped whatever the setting says, so a
+scheduled task's chat having no title is expected.
+
+## The journal / daily summary is empty
+
+configKey: journal
+source: server/workspace/journal/index.ts
+
+Read `journal` first — it gates the archivist that summarizes chat sessions into `journal/*.md`,
+and when it is not enabling a run the archivist short-circuits before the interval gate is even
+consulted. Neither the turn-end hook nor the hourly scheduled task will have written anything, so
+an empty journal is not evidence of a scheduler fault.
+
+## Gmail / Google Calendar / Notion tools don't show up for the agent
+
+configKey: extraAllowedTools
+source: server/agent/config.ts
+
+Connector tools reach the agent only when their MCP prefix is listed in `extraAllowedTools` — the
+list is appended to the base allowed-tools set on every spawn. Check the live value for the
+expected `mcp__…` prefix, and remember the connector must also be linked on the Claude side. A tool
+that is linked but unlisted is configuration, not a bug.
+
+## A skill I saved isn't callable
+
+source: server/workspace/hooks/handlers/skillBridge.ts
+source: server/workspace/skills/discovery.ts
+help: collection-skills.md
+
+Skills are authored at `data/skills/<slug>/SKILL.md` and mirrored into `.claude/skills/<slug>/` by a
+hook — agents must not write the latter directly. If the staging file exists but the mirror doesn't,
+the hook is the thing to look at. Bundled `mc-*` presets are a different case: they land in the
+catalog (`data/skills/catalog/preset/`) and are **not** active until the user stars one, so "the
+preset skill doesn't respond" is usually "it was never activated".
+
+## I edited an mc-* skill and my changes came back reverted
+
+source: packages/core/src/workspace-setup/sync.ts
+
+Working as designed: `mc-*` presets are launcher-managed factory defaults, refreshed from the
+shipped copy on every server boot so bug fixes and renames actually reach an already-starred copy.
+Any file it overwrites is first saved next to it as `<file>.bak.<timestamp>`, so the user's edits
+are recoverable — point them at that instead of re-typing. To keep changes permanently, copy the
+skill to a new non-`mc-` slug.
+
+## The agent can't use git / gh / ssh
+
+help: error-recovery.md
+help: sandbox.md
+
+The agent's Docker sandbox exposes no host SSH agent and no `gh` config unless the user opted them
+in at start-up. `GET /api/sandbox` reports whether the sandbox is active and which config mounts it
+was started with — read that rather than assuming either way. This is the single most common "it's
+broken" report and it is configuration. `error-recovery.md` has the exact flags and the
+verification commands; don't restate them from memory.
+
+## A collection's custom view is blank
+
+help: custom-view.md
+help: custom-view-remote.md
+
+Desktop and phone views have **incompatible runtime contracts** — a desktop view fetches its own
+records with an injected token, while a `target: "mobile"` view gets them over a postMessage bridge
+and cannot `fetch` at all. A view authored against the wrong contract renders empty with no error.
+Check which target it is registered as before treating it as a rendering fault.

package/assets/helps/error-recovery.md

@@ -1,10 +1,15 @@
-# Error recovery — when a tool call fails
+# Error recovery — when a tool call fails, or the user says something is broken
 
 This is the lookup the agent reads BEFORE asking the user a clarifying
 question or giving up on a failing tool call. Each section is keyed by
 the error message you'd see in tool output, with the cause and the
 documented fix.
 
+It has a second entry point. When the **user** reports that MulmoClaude is
+broken / weird / not working — nothing has failed in tool output, they are
+just describing a symptom — start at **§ The user says MulmoClaude is
+broken** below instead of scanning the error-keyed sections.
+
 Cite the section you used in your reply so the user can follow up
 (e.g. "Per `config/helps/error-recovery.md` § gh-auth / SSH …").
 
@@ -13,6 +18,134 @@ If no section here matches, list the workspace's other help files
 area (`sandbox.md`, `github.md`, `collection-skills.md`, etc.) before
 falling back to asking the user.
 
+## The user says MulmoClaude is broken
+
+**The goal is that the user ends up unblocked, not that an issue gets filed.**
+An issue is what's left after the first three steps fail to explain the
+behaviour. Work them in order and stop the moment the user is unblocked.
+
+Rules that hold in every step:
+
+- **Never assert "that's by design" from memory.** Say it only with a reason
+  attached: a config key, a help page, an implementation file.
+  `bug-report-faq.md` is an index of where to look — it deliberately contains
+  no values.
+- **Read the real thing.** Current values come from the workspace's
+  `config/settings.json` or `GET /api/health`, never from recollection.
+- **"I don't know" is an allowed answer.** If a step can't decide, say so and
+  go to the next one. Never close the conversation by guessing.
+- **Nothing leaves the machine before the user has seen it in full** and agreed.
+- Reply in the language the user writes in.
+
+### Step 1 — Hear the symptom (collect nothing yet)
+
+Call `presentForm` once with the questions below rather than asking in prose —
+a user who is already frustrated should be clicking, not composing.
+
+- **What kind** — display looks wrong / input doesn't work / the agent won't
+  answer / a tool keeps failing / phone or remote features / something else
+- **Where** — chat / a collection / the wiki / files / settings / the phone app
+- **How often** — every time / sometimes / once
+- **Since when** — after an update / it always did this / not sure
+- **What did you expect, and what happened instead?** (free text, required —
+  these two sentences are what the next step is judged against)
+
+### Step 2 — Is it configuration, or by design? (this is the actual job)
+
+1. Read `config/helps/bug-report-faq.md` and find the entry closest to the
+   symptom.
+2. Follow its pointers to the **real values** — `config/settings.json` for a
+   `configKey`, the named help page for a `help`. A setting absent from the file
+   is at its default, which is the answer to most entries there.
+3. If that explains the gap between expected and actual, **say why, show the
+   fix, and stop.** Cite what you checked.
+4. If nothing explains it, go to Step 3. Do not stretch a FAQ entry to cover a
+   symptom it doesn't cover.
+
+### Step 3 — Is it already known?
+
+Search the existing issues before opening anything:
+
+```bash
+gh issue list --repo receptron/mulmoclaude --state all --limit 20 --search "<symptom keywords>"
+```
+
+`gh` is **not available by default** — the agent runs in a credential-free
+sandbox (see § gh / git / SSH errors inside the sandbox). Don't spend turns
+fighting it: hand the user the search URL instead.
+
+`https://github.com/receptron/mulmoclaude/issues?q=voice+input+disabled` — build
+the `q=` value percent-encoded (space → `+` or `%20`, `#` → `%23`), or the link
+breaks on the first symptom that contains one.
+
+- **Closed and fixed** → compare their version against the release that fixed
+  it. If they're simply behind, tell them to update and stop.
+- **Open** → do not open a second one. Offer to add this user's environment and
+  repro steps as a comment; a second reproduction is worth more than a duplicate.
+- **Nothing found** → Step 4.
+
+### Step 4 — File it
+
+Only now collect details. Fetch the environment report from the server, from the
+workspace root:
+
+```bash
+curl -s -H "Authorization: Bearer $(cat .session-token)" \
+  "http://${MULMOCLAUDE_HOST:-127.0.0.1}:$(cat .server-port)/api/diagnostics/report"
+```
+
+Three parts of that command are load-bearing, and dropping any one returns
+nothing useful:
+
+- **The bearer header.** Every `/api/*` route requires it; without it the reply
+  is a 401, not a report. The token is regenerated each startup and lives in
+  `.session-token` at the workspace root.
+- **`$MULMOCLAUDE_HOST`.** In the default Docker sandbox `localhost` is the
+  container, not the machine running the server — the variable is set to
+  `host.docker.internal` there and unset on a host-mode run, hence the fallback.
+- **`.server-port`.** The port is chosen at startup; there is no fixed default
+  to hardcode.
+
+Keep the token inside the command substitution: never echo it, never let it
+reach the report body, and if you quote the command in the issue, quote it in
+the `$(cat …)` form above rather than with the value expanded.
+
+**The server does the redaction, not you.** It prints values only for
+allow-listed settings and withholds everything else, including the plaintext
+Google Maps key and every MCP server's `env` / `headers`. Paste what it returns
+verbatim — do not "help" by adding values you read elsewhere, and do not
+re-type a secret you happened to see in a file.
+
+Ask the user for what the host cannot see: the browser and its version, any red
+errors in the browser console, and a screenshot if the symptom is visual. Say
+before they attach one that a screenshot can carry file paths and chat text.
+
+Report body:
+
+```markdown
+## What happened
+## What I expected
+## Steps to reproduce
+1.
+## Environment
+(paste the diagnostics report here)
+## Attachments
+```
+
+Show the whole thing, get an explicit yes, then post it — `gh issue create
+--repo receptron/mulmoclaude --title "<title>" --body-file <file>` when `gh`
+works, otherwise print the markdown for copy-paste plus
+`https://github.com/receptron/mulmoclaude/issues/new`.
+
+### When Step 2 resolved it
+
+A question that took an agent to answer is a signal about the product: the UI
+failed to say something. Offer to post it as an issue titled with the question
+as the user asked it, noting what the answer turned out to be and **where it was
+checked**. Open the body with a line saying the answer came from this lookup and
+is awaiting maintainer review — it is a draft, not documentation. Never edit
+`bug-report-faq.md` yourself.
+
 ## gh / git / SSH errors inside the sandbox
 
 ### Symptoms

package/assets/helps/index.md

@@ -67,7 +67,8 @@ See [Wiki](config/helps/wiki.md) for details on how it works.
 - [Spreadsheet](config/helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
 - [presentHtml](config/helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
 - [Sandbox](config/helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
-- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (gh/git/SSH inside the sandbox, Marp PDF, registry import, build/workspace, plugin runtime) before asking the user
+- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (gh/git/SSH in the sandbox, Marp PDF, registry import, build/workspace, plugin runtime), plus the four-step triage for when a user reports something broken
+- [Bug-report FAQ](config/helps/bug-report-faq.md) — symptoms that turn out to be configuration or by design (voice input, push, chat titles, journal, connector tools, preset skills, custom views); says where to read the live value, never what it is
 - [Telegram Bridge](config/helps/telegram.md) — how to talk to MulmoClaude from the Telegram app: creating a bot, starting the bridge, allowlisting chat IDs, commands, and troubleshooting
 - [Remote host](config/helps/remote-host.md) — drive MulmoClaude from a phone at mulmoserver.web.app: Google sign-in connect, host online vs. offline (queued chats, 7-day expiry), photo attachments, and the security model
 - [Feeds](config/helps/feeds.md) — register a self-refreshing data feed (RSS/Atom/JSON) by authoring `feeds/<slug>/schema.json`: schema shape, the `ingest` block, raw-item field mapping, and `maxItems` retention

package/dist/google/index.cjs

@@ -1179,6 +1179,7 @@ var TASKS_BASE_URL = "https://tasks.googleapis.com/tasks/v1";
 var TASKS_API_LABEL = "Google Tasks API";
 var DEFAULT_TASK_LIST_ID = "@default";
 var TASK_STATUS_COMPLETED = "completed";
+var TASK_STATUS_NEEDS_ACTION = "needsAction";
 var MAX_TASK_LISTS = 50;
 var toTaskListSummary = (value) => {
 	const record = asRecord(value);
@@ -1226,8 +1227,9 @@ async function createTask(accessToken, input) {
 }
 /** PATCH body for a task edit — only the fields the caller supplied. As with
 *  events, `undefined` means "leave as is" and `""` means "clear it", so the
-*  two must stay distinct. `status` is deliberately absent: `completeTask`
-*  owns that transition, and two ways to set it would drift apart. */
+*  two must stay distinct. `status` is deliberately absent: `completeTask` /
+*  `uncompleteTask` own that transition, and two ways to set it would drift
+*  apart. */
 var buildTaskPatch = (input) => ({
 	...input.title !== void 0 ? { title: input.title } : {},
 	...input.notes !== void 0 ? { notes: input.notes } : {},
@@ -1245,6 +1247,25 @@ async function completeTask(accessToken, input) {
 		body: JSON.stringify({ status: TASK_STATUS_COMPLETED })
 	}));
 }
+/** Send a completed task back to the to-do list.
+*
+*  Its own function rather than a flag on `completeTask`, and deliberately not
+*  a `status` field on `updateTask`: one kind per target state keeps the name
+*  honest and leaves exactly one code path setting each value.
+*
+*  The patch carries `status` alone — mirroring `completeTask`, which also
+*  sets only `status` and lets Google fill in the `completed` timestamp. Note
+*  that whether Google *clears* that timestamp on the way back is its
+*  behaviour, not ours, and is unverified here: `TaskSummary` doesn't carry
+*  `completed`, so nothing in this codebase would show a stale one. If a
+*  reopened task ever displays a completion date in Google's own UI, this is
+*  the place to add `completed: null` to the patch. */
+async function uncompleteTask(accessToken, input) {
+	return toTaskSummary(await googleRequest(TASKS_API_LABEL, accessToken, tasksUrl(input.taskListId, `/${encodeURIComponent(input.taskId)}`), {
+		method: "PATCH",
+		body: JSON.stringify({ status: TASK_STATUS_NEEDS_ACTION })
+	}));
+}
 async function deleteTask(accessToken, input) {
 	await googleRequest(TASKS_API_LABEL, accessToken, tasksUrl(input.taskListId, `/${encodeURIComponent(input.taskId)}`), { method: "DELETE" });
 }
@@ -1423,6 +1444,7 @@ exports.toDriveFileSummary = toDriveFileSummary;
 exports.toEventSummary = toEventSummary;
 exports.toTaskListSummary = toTaskListSummary;
 exports.toTaskSummary = toTaskSummary;
+exports.uncompleteTask = uncompleteTask;
 exports.unlinkGoogle = unlinkGoogle;
 exports.unsyncedGroups = unsyncedGroups;
 exports.updateCalendarEvent = updateCalendarEvent;