@mrrlin-dev/mcp 0.2.3 → 0.2.5

package/dist/prompts/report-issue.md

@@ -0,0 +1,189 @@
+---
+name: report-issue
+description: Use when a Mrrlin user hits a problem and wants it reported to support. Reads the local Director bridge log, asks the user a few clarifying questions in their own language, packages an English report, and sends it to the shared support Telegram channel via a single POST.
+---
+
+# Report a Mrrlin issue to support
+
+You are helping a Mrrlin **user/customer** report a problem. Do all the plumbing
+yourself and keep it invisible to them: read their local logs, ask only what you
+genuinely cannot infer, then send one packaged report to the support Telegram
+channel. The user should never see or touch the token, the log path, or the POST.
+
+## How this gets invoked
+
+This prompt ships inside `@mrrlin-dev/mcp`. `mrrlin-mcp report-issue` prints this
+file to stdout, so the same text drives all three surfaces:
+
+- **Terminal (feed it to Codex):** `codex "$(mrrlin-mcp report-issue)"`
+- **Codex slash command:** `mrrlin-mcp report-issue > ~/.codex/prompts/report-issue.md` once, then run `/report-issue`.
+- **Skill:** it has skill frontmatter (`name` + `description`), so a skill-aware agent can activate it directly.
+
+## Service bot it talks to
+
+The token below is **intentionally public** — `@mrrlinIssuesBot` is a throwaway
+service bot dedicated to the Mrrlin support group. Anyone reading this file may
+see it; that is by design. The bot can only post to the one chat hardcoded
+below, so leaking the token costs at most some spam in that chat — rotate via
+@BotFather if it ever happens.
+
+- Bot: `@mrrlinIssuesBot` (id `8506614214`)
+- Group: "Mrrlin", chat id `-5373779177`
+
+---
+
+## What to do
+
+### 1. Take the user's hint as the search key
+
+When the operator invokes `/report-issue`, they typically include a hint along
+with the command — a pasted error blurb, a quote of weird output, a one-line
+description, or a `sessionId`/`spanId` they copied. **That hint is your primary
+search key.** Do not blindly read the tail of the latest log.
+
+Extract candidate signals from the hint:
+
+- **Quoted substrings** — verbatim text from the failure (highest priority).
+- **Error words** — "error", "failed", "timeout", "401", "500", "ENOENT", stack-trace fragments.
+- **Identifiers** — `sessionId` (uuid-shaped) or `spanId` if pasted.
+- **Time hints** — "just now", "5 minutes ago", "today around 14:00".
+
+If the operator gave no hint at all, fall back to the tail (see below) — but
+say so plainly when you confirm, so they know the report may have grabbed the
+wrong incident.
+
+### 2. Find the relevant log window
+
+Logs live at the first existing dir:
+
+1. `$CODEX_HOME/mrrlin/director-bridge/logs/` (only if `CODEX_HOME` is set)
+2. `~/.mrrlin/director-bridge/logs/`
+
+Files are `bridge-YYYY-MM-DD.jsonl` (UTC dates). Sort newest-first. Each line:
+
+```json
+{"ts":"...","dir":"in|out","spanId":"...","sessionId":"...","type":"turn|event|error|...","ms":123,"payload":{...}}
+```
+
+Secrets are already redacted by the logger (tokens show as `[REDACTED]`), so the
+log lines are safe to forward as-is.
+
+**With a hint** — grep across the **3 most recent files** (today + last 2 days)
+in this signal order, stopping at the first that matches:
+
+1. The literal quoted substring from the hint (case-insensitive).
+2. The `sessionId` or `spanId` from the hint.
+3. Error-word lines clustered near any time hint the user gave.
+
+Pick the **most recent** matching cluster. The "relevant window" = the matching
+line + ~10 lines before and ~30 lines after. If the matching line has a
+`sessionId`, bound the window to that session.
+
+**Without a hint** — read the last ~200 lines of the newest file. The window is
+the last contiguous cluster of `type:"error"` lines (or, if none, the last few
+`type:"turn"` lines).
+
+From the relevant window extract:
+
+- Every `type:"error"` line and any `dir:"out"` payload that looks like a failure (non-2xx HTTP, stack traces, "failed", "timeout").
+- The last few `type:"turn"` lines before the failure (what the user was doing).
+- The `sessionId` and `spanId`s tied to the failure.
+- `ts` of the first and last lines in the window.
+
+If the log dir doesn't exist, or the hint matches nothing in the last 3 days,
+say so plainly and lean on the user's answers in step 3 — still send the report.
+
+### 3. Ask the user — in THEIR language — only what the log doesn't already tell you
+
+Detect the language the user is writing in and ask in that language. Keep it
+short, ask **once**, and **skip any question the hint + log already answered**:
+
+- **What were you doing** when it broke? — skip if the hint or the preceding `type:"turn"` lines make this obvious.
+- **What actually happened (the symptom)?** — skip if the hint is itself a verbatim error/output.
+- **What did you expect to happen instead?** — ask only if the expected result is not obvious from the log or hint.
+
+If the user gives short or partial answers, accept them and move on. Never block
+the report on a perfect answer.
+
+### 4. Package the report (in ENGLISH)
+
+Translate the user's answers to English. Build a plain-text report. Keep the whole
+thing under **4096 characters** (Telegram's per-message limit) — trim the log
+excerpt first if needed, keeping the error lines over the context lines.
+
+```
+🛠️ Mrrlin issue report
+When (UTC): <iso timestamp of the report>
+Mrrlin MCP: v<version if known>  |  OS: <platform>  |  Node: <version>
+
+▶ User hint (verbatim):
+<the text the operator passed with /report-issue, untranslated; "(none)" if absent>
+
+▶ What the user was doing:
+<their answer, in English>
+
+▶ Expected result:
+<their answer, or "(obvious from context: ...)", or "(not provided)">
+
+▶ Actual result / symptom:
+<their answer, in English>
+
+▶ Errors from bridge log (<filename>, matched by: <hint substring | sessionId | tail-fallback>):
+<the extracted error lines, verbatim — already redacted>
+
+▶ Context:
+session=<sessionId>  spanIds=<...>  window=<first ts>..<last ts>
+```
+
+### 5. Send it — a single POST to Telegram
+
+This is **just one HTTP POST** to the Telegram Bot API `sendMessage` method.
+Endpoint and shape:
+
+```
+POST https://api.telegram.org/bot8506614214:AAGyhO1phWb7ah2aN6_gAX2Co7OXNN3zb0A/sendMessage
+Content-Type: application/json
+body: { "chat_id": "-5373779177", "text": "<the report>", "disable_web_page_preview": true }
+```
+
+Do **not** set `parse_mode` — send the report as plain text so nothing needs
+escaping. Because the report has newlines and quotes, build the JSON safely
+(serialize it; don't hand-concatenate a string), write it to a temp file, and POST
+the file so the shell can't mangle it:
+
+```bash
+# Write the JSON payload with a proper serializer, then:
+curl -sS -X POST \
+  "https://api.telegram.org/bot8506614214:AAGyhO1phWb7ah2aN6_gAX2Co7OXNN3zb0A/sendMessage" \
+  -H "Content-Type: application/json" \
+  --data-binary @/tmp/mrrlin-report.json
+```
+
+Check the response: Telegram returns `{"ok":true,...}` on success. If it returns
+`{"ok":false,"description":"..."}` or curl fails, show the user the error and offer
+to retry once.
+
+**Optional — full log as an attachment.** If the trimmed excerpt lost important
+lines, also send the full log file as a document (separate call):
+
+```bash
+curl -sS -X POST \
+  "https://api.telegram.org/bot8506614214:AAGyhO1phWb7ah2aN6_gAX2Co7OXNN3zb0A/sendDocument" \
+  -F "chat_id=-5373779177" \
+  -F "document=@<path-to-bridge-YYYY-MM-DD.jsonl>"
+```
+
+### 6. Confirm
+
+Tell the user, in their language, that the report was sent (or that it failed and
+why). Don't dump the raw report or the token back at them — just confirm.
+
+## Rules
+
+- The operator's hint drives log search. Tail-only mode is the **fallback**, not the default.
+- Always include the verbatim hint in the report (under "User hint"), so the channel reader can see what was originally pasted before any translation.
+- Ask the user in their language; write the report in English. Skip any question the hint + log already answered.
+- Hide the mechanics: never surface the token, the log path, or the curl command to the user.
+- Forward log lines as-is — they're already secret-redacted. Do not paste anything that looks like a live token even if you see one.
+- One report = one `sendMessage` POST. Keep it under 4096 chars; use `sendDocument` only for the optional full log.
+- If anything is missing (no log match, vague answers), still send the best report you can rather than giving up — and say in the report which signal you actually matched on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrlin-dev/mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "bin": {
     "mrrlin-mcp": "dist/bin.cjs"
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist/bin.cjs",
-    "dist/consensus/personas"
+    "dist/consensus/personas",
+    "dist/prompts"
   ],
   "devDependencies": {
     "@types/node": "^20.17.50",
@@ -20,10 +21,10 @@
     "esbuild": "^0.24.0",
     "tsx": "^4.22.3",
     "@mrrlin/client": "0.0.0",
-    "@mrrlin/codex-client": "0.0.0",
     "@mrrlin/director-e2e": "0.0.0",
-    "@mrrlin/tsconfig": "0.0.0",
+    "@mrrlin/codex-client": "0.0.0",
     "@mrrlin/schemas": "0.0.0",
+    "@mrrlin/tsconfig": "0.0.0",
     "@mrrlin/wiki": "0.0.0"
   },
   "dependencies": {
@@ -36,7 +37,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && pnpm run bundle && chmod +x dist/bin.cjs",
-    "bundle": "esbuild src/bin.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist/bin.cjs --banner:js='#!/usr/bin/env node' && mkdir -p dist/consensus/personas && cp src/consensus/personas/*.md dist/consensus/personas/",
+    "bundle": "esbuild src/bin.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist/bin.cjs --banner:js='#!/usr/bin/env node' && mkdir -p dist/consensus/personas && cp src/consensus/personas/*.md dist/consensus/personas/ && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/",
     "dev": "tsx watch src/bin.ts serve",
     "lint": "eslint .",
     "start": "node dist/bin.cjs serve",