@rubytech/create-realagent 1.0.614 → 1.0.616

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

@@ -15,17 +15,22 @@
  * │     │                   │
  * │     ├──► original stderr (consumed by Claude Code — opaque)
  * │     │
- * │     ├──► mcp-{name}-stderr-{YYYY-MM-DD}.log    (raw chunks; Task 362)
+ * │     ├──► mcp-{name}-stderr-{YYYY-MM-DD}.log    (raw chunks, per-plugin)
  * │     │
- * │     └──► claude-agent-stream-{YYYY-MM-DD}.log  (per-line, prefixed; Task 524)
+ * │     └──► $STREAM_LOG_PATH                      (per-line, prefixed)
  * │           "[<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.
+ * $STREAM_LOG_PATH is set by the spawner (`getMcpServers` in `claude-agent.ts`)
+ * to the per-conversation stream log file. The MCP server code itself knows
+ * nothing about conversations — it just trusts the spawner's path. This is
+ * the scope boundary introduced by Task 532: the tee is attached per spawn,
+ * not per MCP-server process lifetime. Servers spawned for conversation A
+ * write to conversation A's file; servers for B write to B's file.
+ *
+ * Every decision is logged via `[mcp-tee-*]` markers on both the target file
+ * and the original stderr so an investigator can confirm from the stream log
+ * which tees were wired up, which were skipped, and why.
  */
 
 import {
@@ -33,7 +38,7 @@ import {
   createWriteStream,
   type WriteStream,
 } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, dirname } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 
 // Marker on process.stderr.write so repeat calls to initStderrTee() are
@@ -42,18 +47,23 @@ import { StringDecoder } from "node:string_decoder";
 const INIT_MARKER = Symbol.for("maxy.mcpStderrTee.installed");
 
 /**
- * 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).
+ * Patch process.stderr.write to tee to:
+ *   1. Per-server raw log (`mcp-<serverName>-stderr-<date>.log` under LOG_DIR).
+ *   2. The per-conversation stream log at `STREAM_LOG_PATH` — per-line, prefixed.
+ *   3. The original stderr (consumed by Claude Code) — always preserved.
  *
- * Reads LOG_DIR from environment. When absent (dev mode, tool discovery),
- * does nothing — stderr works as before with no markers emitted.
+ * LOG_DIR absent → skip per-server raw file (dev mode / tool discovery).
+ * STREAM_LOG_PATH absent → skip stream-log destination (older spawner or
+ *   standalone invocation). In both absent cases, stderr works unchanged —
+ *   a `[mcp-tee-skip]` marker is written to original stderr so the skip is
+ *   visible to journalctl-level readers.
  *
- * Safe to call once at MCP server module load. Not safe to call twice —
- * repeated calls would stack patches and double-log every chunk.
+ * Safe to call once at MCP server module load. Refused on second call to
+ * prevent stacking patches.
  */
 export function initStderrTee(serverName: string): void {
   const logDir = process.env.LOG_DIR;
-  if (!logDir) return; // Dev mode or tool discovery — stderr only
+  const streamLogPath = process.env.STREAM_LOG_PATH;
 
   // Refuse repeat patches — stacking them would double-log every chunk
   // and corrupt the re-entrancy guard (originalWrite would capture the
@@ -65,83 +75,61 @@ export function initStderrTee(serverName: string): void {
   // 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.
+  const tsPrefix = () => `[${new Date().toISOString()}]`;
+  const skipTee = (reason: string, destination: string) => {
+    originalWrite(`${tsPrefix()} [platform] [mcp-tee-skip] server=${serverName} destination=${destination} reason=${JSON.stringify(reason)}\n`);
+  };
+
+  // --- Destination 1: per-server raw file (optional, existing Task 362 behaviour)
   let perServerStream: WriteStream | undefined;
-  try {
-    mkdirSync(logDir, { recursive: true });
-    const date = new Date().toISOString().slice(0, 10);
-    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`,
+  if (logDir) {
+    try {
+      mkdirSync(logDir, { recursive: true });
+      const date = new Date().toISOString().slice(0, 10);
+      perServerStream = createWriteStream(
+        resolve(logDir, `mcp-${serverName}-stderr-${date}.log`),
+        { flags: "a" },
       );
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    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;
+      perServerStream.on("error", (err) => {
+        originalWrite(`${tsPrefix()} [platform] [mcp-tee-error] server=${serverName} destination=per-server reason=${JSON.stringify(err.message)}\n`);
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      skipTee(msg, "per-server");
+      perServerStream = undefined;
+    }
+  } else {
+    skipTee("LOG_DIR not set", "per-server");
   }
 
-  // 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.
+  // --- Destination 2: per-conversation stream log (Task 532)
   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`);
+  if (streamLogPath) {
     try {
-      const s = createWriteStream(path, { flags: "a" });
+      mkdirSync(dirname(streamLogPath), { recursive: true });
+      const s = createWriteStream(streamLogPath, { flags: "a" });
       s.on("error", (err) => {
-        originalWrite(
-          `[${new Date().toISOString()}] [platform] mcp stream tee stream-log write error server=${serverName} reason=${err.message}\n`,
-        );
+        originalWrite(`${tsPrefix()} [platform] [mcp-tee-error] server=${serverName} destination=stream-log reason=${JSON.stringify(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;
+      // Attach marker lands in the stream log itself so investigators can
+      // confirm per-conversation the tee was wired up.
+      s.write(`${tsPrefix()} [platform] [mcp-tee-attach] server=${serverName} streamLogPath=${streamLogPath}\n`);
     } 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;
+      skipTee(msg, "stream-log");
+      streamLogStream = undefined;
     }
-  };
+  } else {
+    skipTee("STREAM_LOG_PATH not set", "stream-log");
+  }
 
-  // Prime the stream log once so the startup marker appears immediately
-  // rather than waiting for the first stderr chunk.
-  openStreamLog();
+  // If neither tee target is available, leave stderr untouched — patching
+  // the writer to a no-op tee would still consume event-loop cycles on
+  // every write for zero observability gain.
+  if (!perServerStream && !streamLogStream) {
+    return;
+  }
 
   // Line buffer — accumulates characters written to stderr so complete
   // newline-terminated lines can be prefixed and emitted to the stream log.
@@ -156,6 +144,7 @@ export function initStderrTee(serverName: string): void {
   const utf8 = new StringDecoder("utf8");
 
   const emitCompleteLinesToStreamLog = (chunk: string): void => {
+    if (!streamLogStream) return;
     lineBuffer += chunk;
     let newlineIndex: number;
     // eslint-disable-next-line no-cond-assign
@@ -163,11 +152,8 @@ export function initStderrTee(serverName: string): void {
       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`,
-      );
+      if (streamLogStream.destroyed || streamLogStream.writableEnded) continue;
+      streamLogStream.write(`${tsPrefix()} [mcp:${serverName}] ${line}\n`);
     }
   };
 
@@ -179,17 +165,17 @@ export function initStderrTee(serverName: string): void {
     if (perServerStream && !perServerStream.destroyed) {
       perServerStream.write(chunk);
     }
-    // 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`,
-      );
+    // 2. Stream log — per-line, prefixed.
+    if (streamLogStream) {
+      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(`${tsPrefix()} [platform] [mcp-tee-emit-error] server=${serverName} reason=${JSON.stringify(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);
@@ -204,12 +190,11 @@ export function initStderrTee(serverName: string): void {
   // 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`,
-      );
+    if (streamLogStream && !streamLogStream.destroyed && !streamLogStream.writableEnded) {
+      if (lineBuffer.length > 0) {
+        streamLogStream.write(`${tsPrefix()} [mcp:${serverName}] ${lineBuffer}\n`);
+      }
+      streamLogStream.write(`${tsPrefix()} [platform] [mcp-tee-detach] server=${serverName} reason=process-before-exit\n`);
     }
     lineBuffer = "";
   });

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -938,13 +938,44 @@ server.tool("agent-list", "List all public (non-admin) agents with their full co
         };
     }
 });
-server.tool("logs-read", "Read recent logs. type=system: raw Claude stream-json. type=session: SSE events sent to client. type=error: Claude subprocess stderr. type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log (user messages, knowledge source, memory context, component events, responses). type=server: platform server log (session lifecycle, plugin loading, persistence, routing). type=mcp: MCP server stderr (Loop API calls, status codes, durations). type=vnc: consolidated VNC browser viewer lifecycle log (Xtigervnc/websockify/Chromium boot, HTTP viewer fetches, WebSocket upgrade decisions, proxy pipe open/close/bytes, MCP browser tool calls, client disconnect reasons, ensureVnc/ensureCdp recovery). For any 'browser' issue on the Pi this is the first-stop log. type=review: proactive log-review detector log (Task 385) — every scan cycle, rule match, suppression, rate-limit decision, admin-tool rule mutation, and watchdog event. Use this to audit whether the detector observed a known-bad condition. When sessionKey is provided, greps all log files (or just the specified type) for lines containing that session key and returns a unified timeline.", {
+server.tool("logs-read", "Read recent logs. Task 532: the stream logs (type=system/error/session/public) are now per-conversation — pass `conversationId` to retrieve a single conversation's log from first [spawn] to final [process-exit]. type=system: raw Claude stream-json + agent events + [tool-wait]/[tool-wait-diag]/[tool-wait-proc] telemetry + MCP server stderr via tee. type=session: SSE events sent to client. type=error: Claude subprocess stderr (raw — NODE_DEBUG HTTP/NET/UNDICI traces land in system via the stream tee, not here). type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log. type=server: platform server log. type=mcp: MCP server stderr (per-plugin raw). type=vnc: VNC browser viewer lifecycle. type=review: log-review detector decisions. sessionKey: grep legacy sessionKey-tagged lines across all logs (useful for pre-Task-532 artefacts). When conversationId is provided, reads the single per-conversation file for the requested type (or dumps all type files for that conversationId if type is omitted).", {
     type: z.enum(["system", "session", "error", "heartbeat", "public", "server", "mcp", "vnc", "review"]).optional(),
     lines: z.number().optional(),
     sessionKey: z.string().optional(),
-}, async ({ type, lines = 50, sessionKey }) => {
+    conversationId: z.string().optional(),
+}, async ({ type, lines = 50, sessionKey, conversationId }) => {
     try {
         const LOG_DIR = resolve(getAccountDir(), "logs");
+        // Task 532: conversationId mode — reads the exact per-conversation file.
+        // Precedes the sessionKey grep path because a conversationId is the
+        // tightest identity and answers single-conversation questions without
+        // a grep pass across every log file.
+        if (conversationId) {
+            if (!existsSync(LOG_DIR)) {
+                return { content: [{ type: "text", text: `Log directory does not exist: ${LOG_DIR}` }] };
+            }
+            const prefixMap = {
+                system: "claude-agent-stream",
+                error: "claude-agent-stderr",
+                session: "sse-events",
+                public: "public-agent-stream",
+            };
+            const resolvedType = type ?? "system";
+            const prefix = prefixMap[resolvedType];
+            if (!prefix) {
+                return {
+                    content: [{ type: "text", text: `type=${resolvedType} is not per-conversation. Valid per-conversation types: system, error, session, public. For platform-scoped types (server, vnc, review, heartbeat, mcp) omit conversationId.` }],
+                    isError: true,
+                };
+            }
+            const fileName = `${prefix}-${conversationId}.log`;
+            const filePath = resolve(LOG_DIR, fileName);
+            if (!existsSync(filePath)) {
+                return { content: [{ type: "text", text: `No log file found for conversationId=${conversationId} type=${resolvedType} at ${filePath}. If the conversation has not yet spawned a subprocess (first turn mid-init) the file will not exist.` }] };
+            }
+            const result = execFileSync("tail", ["-n", String(lines), filePath], { timeout: 5000 }).toString();
+            return { content: [{ type: "text", text: `# ${fileName}\n\n${result}` }] };
+        }
         if (!existsSync(LOG_DIR)) {
             return { content: [{ type: "text", text: `Log directory does not exist: ${LOG_DIR}` }] };
         }