@rubytech/create-maxy 1.0.610 → 1.0.612

package/payload/platform/lib/mcp-stderr-tee/src/index.ts

@@ -1,51 +1,216 @@
 /**
- * MCP server stderr tee — writes console.error output to both stderr
- * (for Claude Code) and a dated log file (for logs-read.sh retrieval).
+ * MCP server stderr tee — dual-destination log capture.
  *
- * Claude Code spawns MCP servers as child processes and consumes their
- * stderr internally. The platform cannot intercept at the spawn level.
- * Each server must tee its own stderr to the account's log directory.
+ * Claude Code spawns MCP servers as child processes and consumes their stderr
+ * internally. The platform cannot intercept at the spawn level. Each server
+ * must tee its own stderr so diagnostic output is retrievable.
+ *
+ * ┌─────────────────────────┐
+ * │ MCP server process      │
+ * │                         │
+ * │ console.error("[x] ..") │
+ * │           │             │
+ * │           ▼             │
+ * │ patched stderr.write()  │
+ * │     │                   │
+ * │     ├──► original stderr (consumed by Claude Code — opaque)
+ * │     │
+ * │     ├──► mcp-{name}-stderr-{YYYY-MM-DD}.log    (raw chunks; Task 362)
+ * │     │
+ * │     └──► claude-agent-stream-{YYYY-MM-DD}.log  (per-line, prefixed; Task 524)
+ * │           "[<iso>] [mcp:{name}] <line>"
+ * │           rotates on date boundary
+ * └─────────────────────────┘
+ *
+ * The stream-log destination puts MCP diagnostic lines in the same file the
+ * platform already writes agent events to, so a single logs-read returns a
+ * complete session timeline. The per-server file is retained unchanged —
+ * it remains the grep-one-plugin surface.
  */
 
-import { mkdirSync, createWriteStream, type WriteStream } from "node:fs";
+import {
+  mkdirSync,
+  createWriteStream,
+  type WriteStream,
+} from "node:fs";
 import { resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+// Marker on process.stderr.write so repeat calls to initStderrTee() are
+// detected at runtime, not just warned about in the docstring. A second
+// call would stack patches and double-log every chunk.
+const INIT_MARKER = Symbol.for("maxy.mcpStderrTee.installed");
 
 /**
- * Patch process.stderr.write to tee output to a dated log file.
+ * Patch process.stderr.write to tee to both a per-server raw log and the
+ * unified claude-agent-stream log (with a [mcp:<serverName>] prefix).
  *
  * Reads LOG_DIR from environment. When absent (dev mode, tool discovery),
- * does nothing — stderr continues to work as before.
+ * does nothing — stderr works as before with no markers emitted.
  *
- * Log file: {LOG_DIR}/mcp-{serverName}-stderr-YYYY-MM-DD.log (append mode)
+ * Safe to call once at MCP server module load. Not safe to call twice —
+ * repeated calls would stack patches and double-log every chunk.
  */
 export function initStderrTee(serverName: string): void {
   const logDir = process.env.LOG_DIR;
   if (!logDir) return; // Dev mode or tool discovery — stderr only
 
-  let logStream: WriteStream;
+  // Refuse repeat patches — stacking them would double-log every chunk
+  // and corrupt the re-entrancy guard (originalWrite would capture the
+  // already-patched function on the second call).
+  if ((process.stderr.write as unknown as { [k: symbol]: boolean })[INIT_MARKER]) return;
+
+  // Keep a direct reference to the unpatched writer. All diagnostic output
+  // from inside this module MUST go through originalWrite to avoid
+  // re-entering the patched writer (which would recurse on a tee failure).
+  const originalWrite = process.stderr.write.bind(process.stderr);
+
+  // Per-server raw-chunk file (Task 362). Opened once, never rotated —
+  // preserves existing behaviour.
+  let perServerStream: WriteStream | undefined;
   try {
     mkdirSync(logDir, { recursive: true });
     const date = new Date().toISOString().slice(0, 10);
-    logStream = createWriteStream(
+    perServerStream = createWriteStream(
       resolve(logDir, `mcp-${serverName}-stderr-${date}.log`),
       { flags: "a" },
     );
+    perServerStream.on("error", (err) => {
+      originalWrite(
+        `[${new Date().toISOString()}] [platform] mcp stream tee per-server write error server=${serverName} reason=${err.message}\n`,
+      );
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(
-      `[${serverName}] WARNING: log file tee failed (${msg}), stderr only\n`,
+    originalWrite(
+      `[${new Date().toISOString()}] [platform] mcp stream tee disabled reason=${msg} server=${serverName} destination=per-server\n`,
     );
+    // If the per-server file can't be opened, the LOG_DIR itself is likely
+    // unusable — give up on the whole tee rather than half-install it.
     return;
   }
 
-  const originalWrite = process.stderr.write.bind(process.stderr);
+  // Stream-log destination (Task 524). Lazily re-opened on date boundary so
+  // a long-lived MCP server started yesterday routes today's output into
+  // today's stream-log file, matching the platform's rotation semantics.
+  let streamLogStream: WriteStream | undefined;
+  let streamLogDate = ""; // YYYY-MM-DD the current stream was opened for
+  let streamLogDisabledReason: string | undefined;
+
+  const openStreamLog = (): WriteStream | undefined => {
+    const today = new Date().toISOString().slice(0, 10);
+    if (streamLogStream && streamLogDate === today) return streamLogStream;
+
+    // Date boundary crossed (or first open). Close the old stream before
+    // opening the new one so the file descriptor is released. Also clear
+    // any prior disabled reason — the previous failure may have been
+    // transient (EMFILE, ENOSPC), and the new day's path is fresh.
+    if (streamLogStream && streamLogDate !== today) {
+      try { streamLogStream.end(); } catch { /* ignore */ }
+      streamLogStream = undefined;
+      streamLogDisabledReason = undefined;
+    }
+
+    if (streamLogDisabledReason) return undefined;
+
+    const path = resolve(logDir, `claude-agent-stream-${today}.log`);
+    try {
+      const s = createWriteStream(path, { flags: "a" });
+      s.on("error", (err) => {
+        originalWrite(
+          `[${new Date().toISOString()}] [platform] mcp stream tee stream-log write error server=${serverName} reason=${err.message}\n`,
+        );
+      });
+      streamLogStream = s;
+      streamLogDate = today;
+      // Startup marker lands in the stream log itself so investigators reading
+      // a session's stream-log file can confirm the tee was wired up.
+      s.write(
+        `[${new Date().toISOString()}] [platform] attaching mcp stream tee for server=${serverName} logPath=${path}\n`,
+      );
+      return s;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      streamLogDisabledReason = msg;
+      const line = `[${new Date().toISOString()}] [platform] mcp stream tee disabled reason=${msg} server=${serverName} destination=stream-log\n`;
+      originalWrite(line);
+      if (perServerStream && !perServerStream.destroyed) perServerStream.write(line);
+      return undefined;
+    }
+  };
+
+  // Prime the stream log once so the startup marker appears immediately
+  // rather than waiting for the first stderr chunk.
+  openStreamLog();
+
+  // Line buffer — accumulates characters written to stderr so complete
+  // newline-terminated lines can be prefixed and emitted to the stream log.
+  // Partial chunks are held until a newline arrives (or beforeExit flushes).
+  let lineBuffer = "";
+
+  // StringDecoder buffers trailing UTF-8 continuation bytes across chunks.
+  // Without it, a multi-byte codepoint that straddles a write boundary would
+  // render as two U+FFFD replacement characters in the stream log. Only
+  // matters when a caller writes Uint8Array chunks directly — console.error
+  // produces strings — but plugins piping child-process stderr can hit this.
+  const utf8 = new StringDecoder("utf8");
+
+  const emitCompleteLinesToStreamLog = (chunk: string): void => {
+    lineBuffer += chunk;
+    let newlineIndex: number;
+    // eslint-disable-next-line no-cond-assign
+    while ((newlineIndex = lineBuffer.indexOf("\n")) !== -1) {
+      const line = lineBuffer.slice(0, newlineIndex);
+      lineBuffer = lineBuffer.slice(newlineIndex + 1);
+      if (line.length === 0) continue; // skip blank lines
+      const stream = openStreamLog();
+      if (!stream || stream.destroyed || stream.writableEnded) continue;
+      stream.write(
+        `[${new Date().toISOString()}] [mcp:${serverName}] ${line}\n`,
+      );
+    }
+  };
+
   process.stderr.write = (
     chunk: string | Uint8Array,
     ...args: unknown[]
   ): boolean => {
-    if (!logStream.destroyed) {
-      logStream.write(chunk);
+    // 1. Per-server raw file — preserves Task 362 behaviour (no prefix).
+    if (perServerStream && !perServerStream.destroyed) {
+      perServerStream.write(chunk);
     }
-    return (originalWrite as Function)(chunk, ...args);
+    // 2. Stream log — per-line, prefixed, date-rotating.
+    try {
+      const text = typeof chunk === "string"
+        ? chunk
+        : utf8.write(Buffer.from(chunk));
+      emitCompleteLinesToStreamLog(text);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      originalWrite(
+        `[${new Date().toISOString()}] [platform] mcp stream tee emit error server=${serverName} reason=${msg}\n`,
+      );
+    }
+    // 3. Original stderr — Claude Code still gets what it's always got.
+    return (originalWrite as (chunk: string | Uint8Array, ...a: unknown[]) => boolean)(chunk, ...args);
   };
+  // Mark the patch so a second initStderrTee() call is refused at the top.
+  (process.stderr.write as unknown as { [k: symbol]: boolean })[INIT_MARKER] = true;
+
+  // Flush any trailing unterminated segment on graceful event-loop drain.
+  // `beforeExit` fires only when the event loop is empty — it does NOT run
+  // on SIGTERM, SIGKILL, or explicit process.exit(). Acceptable: console.error
+  // always terminates with \n, so the buffer is effectively always empty at
+  // shutdown anyway. This hook exists for the rare caller that uses
+  // process.stderr.write without a trailing newline.
+  process.on("beforeExit", () => {
+    if (lineBuffer.length === 0) return;
+    const stream = openStreamLog();
+    if (stream && !stream.destroyed && !stream.writableEnded) {
+      stream.write(
+        `[${new Date().toISOString()}] [mcp:${serverName}] ${lineBuffer}\n`,
+      );
+    }
+    lineBuffer = "";
+  });
 }

package/payload/platform/plugins/admin/PLUGIN.md

@@ -52,15 +52,15 @@ Tools are available via the `admin` MCP server.
 
 | Task | When to use | Reference |
 |------|-------------|-----------|
-| Manage public agents | User asks to create, edit, clone, list, preview, or delete a public agent | `skills/public-agent-manager/skill.md` |
+| Manage public agents | User asks to create, edit, clone, list, preview, or delete a public agent | `skills/public-agent-manager/SKILL.md` |
 | Create a new skill | User asks to create, add, or teach the agent a new capability | `skills/skill-builder/SKILL.md` |
 | Review stream logs | Admin asks to review, diagnose, or analyse a Claude agent stream log | `skills/stream-log-review/SKILL.md` |
 | Set up business profile | Admin asks to set up, complete, or update business operational data | `skills/business-profile/SKILL.md` |
 | Generate a QR code | User asks to generate, create, or make a QR code from a URL, Wi-Fi details, contact, or text | `skills/qr-code/SKILL.md` |
 | Timezone queries | User asks for the time in another city, timezone conversion, UTC offset, or DST status | `skills/datetime/SKILL.md` |
 | Manage access grants | Admin asks to invite visitors, revoke or extend access, list who has access, or set an agent's access mode | `skills/access-manager/SKILL.md` |
-| Manage plugins and settings | User asks to install, enable, disable, or configure plugins, or change account settings | `skills/plugin-management/skill.md` |
-| Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/skill.md` |
+| Manage plugins and settings | User asks to install, enable, disable, or configure plugins, or change account settings | `skills/plugin-management/SKILL.md` |
+| Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/SKILL.md` |
 | Generate print-quality PDF | User asks to create a PDF document, one-pager, brochure, or any HTML intended for print/download | `skills/a4-print-documents/SKILL.md` |
 
 ## Hooks

package/payload/platform/plugins/admin/skills/plugin-management/{skill.md → SKILL.md}

@@ -55,7 +55,7 @@ Call `premium-deliver` with `pluginName` set to the plugin name. The tool handle
 - Scans for public agent templates
 - Returns a structured result with per-sub-plugin status and available templates
 
-Report the tool's result to the user. If templates are found, present them and ask whether the user wants to create any now. For template creation, load the public agent management skill via `plugin-read` from `admin/skills/public-agent-manager/skill.md` and follow the "Create from Template" instructions, passing the template directory path from the tool's result.
+Report the tool's result to the user. If templates are found, present them and ask whether the user wants to create any now. For template creation, load the public agent management skill via `plugin-read` from `admin/skills/public-agent-manager/SKILL.md` and follow the "Create from Template" instructions, passing the template directory path from the tool's result.
 
 If the delivered plugin has specialist agents (files in `agents/` with the `{plugin-name}--{agent-name}.md` naming convention, distinct from template directories), load the specialist management skill and follow the premium plugin agent activation instructions.
 

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -87,3 +87,23 @@ Maxy handles the installation or removal. If the plugin requires any setup (API
 ## Viewing Your Plugins
 
 Ask Maxy: "What plugins do I have?" or "List my plugins."
+
+## MCP Plugin Observability (for plugin authors)
+
+Every `console.error` line from a plugin's MCP server can be teed into the unified agent stream log so a single `logs-read` call returns the full session timeline — agent events and plugin diagnostics interleaved in chronological order.
+
+**Opt-in (one line at the top of the MCP server's entry file):**
+
+```typescript
+import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("your-plugin-name");
+```
+
+After this, every `console.error("[your-tool] ...")` from any tool in the plugin appears as `[<iso-ts>] [mcp:your-plugin-name] [your-tool] ...` in `claude-agent-stream-YYYY-MM-DD.log`, alongside the usual agent events. The raw per-server file `mcp-your-plugin-name-stderr-YYYY-MM-DD.log` is still produced for deep-dive grep.
+
+**Retrieve MCP diagnostic lines for a session:**
+
+- All servers: `logs-read { type: "system" }` → grep `[mcp:<name>]` on the returned stream log.
+- One server raw feed: `logs-read { type: "mcp" }` → `mcp-<name>-stderr-*.log`.
+
+**Tee-state markers** land in the stream log too — `[platform] attaching mcp stream tee for server=<name> logPath=…` when the tee wires up, `[platform] mcp stream tee disabled reason=… server=<name>` when it bails (missing `LOG_DIR`, unwritable path, etc.). If a server invoked tools but no `[mcp:<name>]` lines appear, look for the disabled marker first.

package/payload/platform/plugins/sales/references/faq.md

@@ -18,16 +18,6 @@ ChatGPT helps you think and write. Siri and Alexa respond to commands. Maxy runs
 
 The comparison that matters isn't Maxy vs ChatGPT. It's Maxy vs hiring someone — or vs doing it all yourself.
 
-## How does Maxy earn more responsibility?
-
-Through the Earned Autonomy model. Maxy tracks your demonstrated competence with each capability independently, progressing through three stages:
-
-- **Assist** — Maxy shows its work, explains its approach, asks before acting
-- **Augment** — Maxy handles things normally, flags exceptions only
-- **Orchestrate** — Maxy executes without explanation, escalates only when genuinely unusual
-
-You never configure this. Maxy observes and adjusts. Tell it "I know how to do this" to advance, or "explain this again" to step back. You're always in control.
-
 ## Can Maxy create documents?
 
 Yes. Describe what you need — a quote, a proposal, an invoice, a report, a flyer, a compliance document — and Maxy generates it as a professional A4 PDF. Review it in the conversation, download it, or deliver it directly to a customer via WhatsApp or email. Quotes, proposals, invoices, reports, marketing materials, compliance documents — all created through conversation.

package/payload/platform/plugins/sales/references/pricing.md

@@ -12,7 +12,6 @@ Includes:
 - Manages your picture — daily briefings, overdue items, proactive reminders
 - WhatsApp, Telegram, web, and email access
 - Memory and context across conversations
-- Earned Autonomy — Maxy earns the right to handle more as trust builds
 - Your data stays on your device. Always.
 
 Hardware required: Maxy Pi (from £250, one-time purchase) or your own Linux machine