@rubytech/create-realagent 1.0.610 → 1.0.612

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.610",
+  "version": "1.0.612",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/knowledge/maxy.md

@@ -1,6 +1,8 @@
 # Maxy
 
-AI for Elite Operators. Not a productivity tool. An operations layer.
+**Time. Knowledge. Money.** Folk wisdom: if you're short on one, you use the other two to get it. Most productivity systems ignore the middle variable. Maxy doesn't. Your business lives in an ontological substrate — a knowledge graph only AI can create and interpret at useful scale. The outcome is time.
+
+Not a productivity tool. An operations layer. AI for elite operators.
 
 Maxy does three things, continuously, across every session:
 
@@ -20,8 +22,10 @@ Your data never leaves your premises. GDPR compliant. EU AI Act compliant.
 |---|---|
 | **Company** | Rubytech LLC |
 | **Product** | Maxy |
-| **Title** | AI for Elite Operators |
-| **Thesis** | Not a productivity tool. An operations layer. |
+| **Tagline** | Time. Knowledge. Money. |
+| **Positioning** | AI for elite operators. Not a productivity tool — an operations layer. |
+| **Thesis** | Knowledge is the underweighted variable in the time/knowledge/money equation. At business scale, only AI can create and interpret it. |
+| **Operating philosophy** | Calibrate. Prevent. Compress. |
 | **Domains** | getmaxy.com (marketing), maxy.bot (product), maxy.chat (alias) |
 | **Stage** | Pre-launch. Building the waitlist. Currently in internal testing (dog-fooding) — Maxy is selling Maxy. |
 
@@ -45,23 +49,49 @@ The public-facing agent greets visitors warmly and demonstrates capability immed
 
 ---
 
-## Earned Autonomy — how Maxy grows with you
+## The equation
+
+Folk wisdom says if you're short on one of time, knowledge, or money, you use the other two to get it. Most systems built for productive people ignore the middle variable. They treat knowledge as a database to query, not the substrate everything else runs on.
+
+Maxy doesn't. Your business — every customer, every commitment, every process, every standard — lives in an ontological substrate. That is not marketing language for "database". It is the ground truth the system reasons against, designed to hold knowledge at a scale and complexity only AI is capable of creating and interpreting. No human can hand-model every customer relationship, every commitment, every workflow dependency at the fidelity this requires — which is why the substrate is the foundation of Maxy, not a side-effect of the application layer.
+
+The outcome: time, given back to you. Time you use to apply what you know, earn money, or simply live.
+
+---
+
+## Why nothing worked
+
+Every tool you tried stored data. None of them modelled relationships. Your CRM couldn't see your calendar. Your calendar couldn't see your commitments. Your project tracker didn't know who the client was, what you'd promised them, or which tasks depended on which. Each tool was a silo pretending to be a system.
 
-Maxy earns the right to handle your operations — it doesn't assume it. Like a new Operations Manager joining your business, Maxy starts by learning how you work and proving it can be trusted. Earned autonomy is the mechanism; the three-question operating philosophy — calibrate, prevent, compress — is the purpose it serves. Every capability — scheduling, documents, contacts, workflows — is tracked independently. You might be an expert at creating invoices in Maxy but new to workflows. Maxy adapts to each one.
+Connected data alone isn't enough. What matters is an AI that can reason across all of it — surfacing insights you didn't ask for, catching commitments before they slip, and acting on the full picture of your operations without being told where to look.
 
-This is the **Earned Autonomy** model, and it works in three stages:
+The implementation layer wasn't multiplying you. It was fractioning you.
 
-**Assist** — when you first use a capability, Maxy shows its work. It explains which tools it's using and why, walks you through the relevant parts of the skill, shows drafts before acting, and asks before making choices you haven't specified. You see exactly what's happening and learn how it works.
+- Researchers who summarised instead of synthesised.
+- Coordinators who managed process without understanding context.
+- Product requirements articulated through layers of PMs and developers — time-consuming, expensive, and never the product conceived in the architect's mind.
 
-**Augment** — once you've demonstrated you're comfortable (a few tasks completed without corrections), Maxy handles things normally. It flags exceptions or unusual situations but skips the basics — you know how this works in Maxy.
+Maxy collapses that layer. One operator. The output of a team. Zero dilution.
+
+---
 
-**Orchestrate** — after sustained, consistent use, Maxy executes without explanation. It escalates only when the situation is genuinely unusual or requires a decision you haven't pre-authorised. The admin overhead disappears.
+## The operating philosophy — Calibrate. Prevent. Compress.
 
-You never configure any of this. Maxy observes — watching you succeed, noticing when you need guidance, learning when you correct its approach. The transitions happen automatically based on what you've demonstrated. If you want to accelerate, say "I know how to do this" and Maxy advances. If you want more transparency, say "explain this again" and Maxy steps back. You're always in control, but you shouldn't have to think about it.
+Every session, Maxy is doing three things — not as tasks to complete, but as the lens through which it approaches every interaction.
 
-Your preferences are separate from your competence. A preference is "I like terse responses." Competence is "this user has successfully created 4 invoices without guidance." You can be an expert who likes educational explanations, or a novice who wants brief responses. Maxy respects both independently.
+1. **Calibrate what excellence means here.** Learn your standards — what good looks like in your work, your decisions, your outcomes — and hold you to them. Session 300 is more precise than session 3.
+2. **Prevent what used to go wrong.** Learn the failure patterns from before — what fell through the cracks, what kept breaking, what frustrated you. Break those patterns, not just record them.
+3. **Compress what takes months to learn.** The rhythms, instincts, and patterns that humans build only through sustained repetition — encoded from the first instance. The benefit of experience, immediately.
 
-You already do the thinking. Now the rest keeps up.
+Every capability below — the five roles, the graph, the workflows — serves this triumvirate. When in doubt about whether a feature belongs, ask whether it calibrates, prevents, or compresses. If it does none, it does not belong.
+
+---
+
+## How Maxy works for you
+
+Maxy learns your preferences from conversation — never from questionnaires or onboarding forms. When you reveal something about how you like to work, Maxy stores it with a confidence score that strengthens when reinforced and fades when contradicted. You can always override: "remember this", "forget that", or simply contradict it in the moment.
+
+Your thinking sets you apart. Now the rest doesn't hold you back.
 
 ### Your business, understood
 
@@ -101,31 +131,55 @@ Connect Maxy to new capabilities by asking — finance tracking, home management
 
 ---
 
-## What changes — the four roles in action
+## Five roles. One operator. Zero dilution.
 
-### Follows through — Joel's invoice
+Every hour you spend on admin, scheduling, research, or content is an hour not spent on the work only you can do. Maxy dispatches five roles on your behalf — you never configure or manage them. Each admin role has a public-facing counterpart that can be enabled for customer-facing work. You may see activity like "Dispatching personal-assistant..." in the chat timeline when this happens.
 
-Joel bought a Pi on a colleague's card. Promised to forward the VAT invoice when it arrived. Normally — forgotten. Instead, he told Maxy. One conversation. Nothing more to do. Maxy checked the order daily. When the invoice appeared, it sent it directly to the right email address and closed the task. Joel hasn't thought about it since. This is not a feature demonstration. This is how Maxy works.
+| Admin role | What it does | Public counterpart |
+|---|---|---|
+| **Project Manager** | Projects, tasks, dependencies, sessions, lifecycle | Client Onboarding — qualification, requirements, 24/7 intake |
+| **Personal Assistant** | Scheduling, admin, messaging, browser automation, briefings | Support — FAQ, knowledge base, triage |
+| **Research Assistant** | Web search, knowledge management, citations, visuals | Booking — scheduling, availability, confirmations |
+| **Content Producer** | Documents, PDFs, ingestion, image generation | Sales Enquiry — lead qualification, pricing, proposals |
+| **Coach** | Accountability, patterns, progress, reviews | Maxy — generalist, 24/7 public agent |
 
-### Responds — customer enquiry at 10pm
+Roles are installed during setup and listed when Maxy introduces itself. Some premium plugins add their own specialists on top (e.g. a manuscript reviewer for writer-craft, a listings specialist for Pro Real Estate). Roles installed mid-session become active from the next session.
 
-A customer enquiry comes in at 10pm. You don't see it until morning. They've already called your competitor. With Maxy: answered immediately with your services, availability, and pricing. The meeting was booked before breakfast.
+### The roles in action
 
-### Handles finances — end of week admin
+**Follows through — Joel's invoice.** Joel bought a Pi on a colleague's card. Promised to forward the VAT invoice when it arrived. Normally — forgotten. Instead, he told Maxy. One conversation. Nothing more to do. Maxy checked the order daily. When the invoice appeared, it sent it directly to the right email address and closed the task. Joel hasn't thought about it since. This is the Personal Assistant and Project Manager working together. This is how Maxy works.
 
-End of week — two hours typing up quotes, chasing unpaid invoices, updating the spreadsheet you pretend is a CRM. With Maxy: quotes generated on site. Invoices sent automatically. Customer profile is a conversation away.
+**Responds — customer enquiry at 10pm.** A customer enquiry comes in at 10pm. You don't see it until morning. They've already called your competitor. With Maxy: the public Sales Enquiry agent answers immediately with your services, availability, and pricing. The meeting is booked before breakfast.
 
-### Manages your picture — weekend coordination
+**Handles finances — end of week admin.** End of week — two hours typing up quotes, chasing unpaid invoices, updating the spreadsheet you pretend is a CRM. With Maxy: Content Producer generates the quote on site. Personal Assistant sends it and chases it. Customer profile is a conversation away.
 
-Sunday spent coordinating next week — kids, dentist, groceries, car service. With Maxy: already sorted. Dentist confirmed, groceries listed, car booked.
+**Manages your picture — weekend coordination.** Sunday spent coordinating next week — kids, dentist, groceries, car service. With Maxy: already sorted. Dentist confirmed, groceries listed, car booked. One conversation, five roles, done.
 
 ---
 
 ## How it works
 
-A private device on your network holds your full operational context in a local knowledge graph. A seven-layer architecture from device to interface, with an ontological substrate that connects every entity in your operation.
+A private device on your network holds your full operational context in a seven-layer architecture, grounded in a local knowledge graph that connects every entity in your operation.
+
+### The seven layers
+
+1. **Device** — Raspberry Pi 5 or a Linux mini PC on your premises. This is the system boundary. Nothing but LLM prompts and responses crosses it.
+2. **Ontological substrate** — Neo4j graph database and vector embeddings. Not a data store bolted onto an LLM — the ground truth the entire system reasons against. Entity relationships, customer history, document knowledge, and agent memory all live here. Vector embeddings enable semantic retrieval; graph relationships enable context traversal.
+3. **Intelligence** — Claude (via the Anthropic API) handles language understanding, synthesis, and generation. Maxy handles everything else: tool routing, knowledge scoping, and workflow execution. The split is deliberate.
+4. **Plugins and capabilities** — the plugin manifest is Maxy's domain ontology. It defines which tools belong to which domain, which skills are available to which agent, and which capabilities are active. When a request arrives, the agent resolves the relevant domain and operates within that boundary — it cannot invoke a tool outside its resolved domain.
+5. **Execution** — Projects, Tasks, and Workflows. Projects are first-class graph entities, grounded in PMBOK 7th Edition and APM Body of Knowledge 5th Edition, adapted for conversational use. Dependency tracking (BLOCKS) and conflict detection (AFFECTS) are graph-native — task sequencing follows graph-defined rules, not model discretion.
+6. **Agents** — three tiers with formally separated access. Admin (owner-facing, full graph access, full tool access). Public (customer-facing, scoped to public knowledge only). Specialist sub-agents (domain-specific execution dispatched by the admin agent). Agents cannot escalate their own permissions.
+7. **Interfaces** — WhatsApp, Web Chat, Telegram, Email. All channels share the same underlying graph. A customer conversation on WhatsApp and a task created via the web interface exist in the same knowledge space. Channel is irrelevant; context is always whole.
+
+### The design principle
+
+**Deterministic where correctness matters. LLM where judgement matters.**
 
-The interface is conversation. Web chat, WhatsApp, Telegram. The same way you briefed a team, except this one retains everything, connects everything, and executes without being managed. No dashboards. No workflows to configure.
+Tool routing, data access, workflow sequencing, and capability boundaries follow formal rules. The model cannot override them. Language understanding, synthesis, and contextual response generation are handled by Claude — applied to grounded, locally-held data. This places Maxy at L2–L3 of the neurosymbolic coupling maturity model (Tuan, 2026): ontology-constrained tool discovery and knowledge-grounded reasoning, rather than the prompt-injection approach common in competing architectures.
+
+### The interface
+
+Conversation. Web chat, WhatsApp, Telegram. The same way you briefed a team, except this one retains everything, connects everything, and executes without being managed. No dashboards. No workflows to configure.
 
 Plug in the device, open your browser, set a PIN, connect your Claude account, and start talking. Fully operational within 15 minutes.
 
@@ -207,6 +261,24 @@ Maxy runs on any Linux machine with 16 GB or more of RAM. Your own hardware or a
 
 ---
 
+## Security and accountability
+
+Privacy by architecture is the starting point. Three structural features back it up.
+
+### Inbound message screening
+
+Every inbound message — regardless of channel (web chat, WhatsApp, Telegram, email) — passes through a centralised screening gateway before reaching the agent. The gateway detects prompt injection patterns, classifies intent, assigns a safety verdict (CLEAN / SUSPICIOUS / DISCARD), and rewrites queries for retrieval. Unsafe messages on public channels are refused without agent invocation. Admin messages receive advisory screening only — flagged, never blocked.
+
+### Agent action audit trail
+
+Every tool invocation by the admin agent produces a durable audit record in the knowledge graph — tool name, input, output, timestamp, and originating conversation. Records persist indefinitely and are queryable in conversation. Ask Maxy "what tools ran in the last session?" to review. This is not a debug log — it is a first-class data structure designed for accountability and operational review.
+
+### AI content provenance
+
+When your public agent sends a message to someone — by email, WhatsApp, Telegram, or SMS — the platform automatically includes a brief disclosure that the content was generated by AI. Emails include an `X-AI-Generated` header and a footer line. WhatsApp and Telegram messages have a short line appended. This is transparent and cannot be turned off. Messages you write yourself (typing directly in WhatsApp) are not marked — the disclosure applies only to content composed by the AI agent.
+
+---
+
 ## Privacy and data sovereignty
 
 ### Your data stays on your premises
@@ -215,7 +287,7 @@ All data is stored on the device on your premises. It never goes to a cloud serv
 
 ### What leaves the device
 
-Only LLM prompts — the messages you send to Maxy — leave the device. They are sent to Claude (Anthropic's AI) for processing and are subject to Anthropic's privacy policy. Anthropic does not use your conversations to train their models.
+Only LLM prompts — the messages you send to Maxy — leave the device. They are sent to Claude (Anthropic's AI) for processing under Anthropic's zero-retention API terms and are subject to Anthropic's privacy policy. Anthropic does not use your conversations to train their models.
 
 ### What stays on the device
 
@@ -223,7 +295,12 @@ Everything else. Your contacts, your documents, your conversation history, your
 
 ### GDPR compliance
 
-Maxy is GDPR compliant by default. Your data lives on your premises, not ours. Unlike cloud solutions, where compliance is a configuration option you have to get right, with Maxy compliance is the architecture. There is no grey area.
+Maxy is GDPR compliant by default. Your data lives on your premises, not ours. Compliance is the architecture, not a configuration option. Data subject rights are exercised through the same conversational interface used for everything else — no support tickets, no dashboards, no waiting.
+
+- **Right of access (Article 15):** ask Maxy to export all data held on a contact. The export gathers the person record, access credentials, conversation history, and emails into a single structured document that can be handed directly to the data subject.
+- **Right to erasure (Article 17):** ask Maxy to delete all data held on a contact. Maxy shows a preview of what would be removed, confirms with you, then performs a full cascade deletion across all data stores. A deletion receipt is returned listing exactly what was removed.
+
+On-premises deployment means the data controller is also the data processor — no third-party data sharing, no processor agreements to review.
 
 ### Cancellation
 
@@ -332,7 +409,7 @@ Claude Desktop, Claude Code, and Perplexity are AI tools that make you more prod
 
 Maxy is a business and personal operating system that grows with you. It starts by helping — learning your customers, your processes, your way of working. As it proves itself, it takes on more. It answers your customers at 3am. It delivers your morning briefing with your pipeline status, your overdue follow-ups, and your day's appointments before you've opened your laptop. It generates invoices, tracks deals through stages, prepares meeting packs, and runs workflows you've defined — all on a device you own, with data that never leaves your premises, exported in open standards you control.
 
-You already do the thinking. Now the rest keeps up. The others make you faster. Maxy makes your business run.
+Your thinking sets you apart. Now the rest doesn't hold you back. The others make you faster. Maxy makes your business run.
 
 ---
 
@@ -348,13 +425,13 @@ You do not need to install any software, configure any settings, or have any tec
 
 ## Setup
 
-1. Plug in your Maxy device and connect it to Wi-Fi.
+1. Plug in your Maxy device. If there's no ethernet cable and no WiFi configured, the device creates a temporary network called **Maxy-Setup** — connect your phone to it, pick your home WiFi from the setup page, and enter the password. The temporary network disappears and your phone reconnects to your home network.
 2. Open a browser on any device and go to maxy.local.
 3. Set a PIN — this protects your admin chat.
 4. Connect your Claude account — follow the on-screen steps to link your Anthropic subscription.
 5. Start talking — tell Maxy about yourself, your business, your customers.
 
-Fully operational in under 15 minutes. No software downloads, no configuration files, no training courses.
+Fully operational in under 15 minutes. No software downloads, no configuration files, no training courses. Setup is resumable — if you close the browser mid-onboarding, Maxy picks up where you left off.
 
 ---
 
@@ -362,7 +439,7 @@ Fully operational in under 15 minutes. No software downloads, no configuration f
 
 ### Web chat
 
-Your primary interface. Open a browser on any device — phone, tablet, laptop — and talk to Maxy. Works on your local network at maxy.local, or from anywhere via your custom domain.
+Your primary interface. Open a browser on any device — phone, tablet, laptop — and talk to Maxy. Works on your local network at maxy.local, or from anywhere via your custom domain. Voice notes are supported when the input is empty — tap the microphone, speak, tap send. Voice recording requires a secure connection (HTTPS), so use your custom domain rather than the local address when recording.
 
 ### Telegram
 
@@ -578,7 +655,7 @@ We're building the waitlist now. Leave your name and email and we'll be in touch
 
 ### What about GDPR?
 
-Maxy is GDPR compliant by default. All data is stored on your device, on your premises. There is no cloud processing of your personal data. Unlike cloud-based tools where GDPR compliance requires careful configuration, with Maxy it's the architecture.
+Maxy is GDPR compliant by default. All data is stored on your device, on your premises. There is no cloud processing of your personal data — compliance is the architecture, not a configuration option. Data subject rights (Article 15 access, Article 17 erasure) are exercised through conversation: ask Maxy to export or delete all data held on a contact, and it does, with a confirmation gate and a deletion receipt.
 
 ### Can I use my own computer instead of the Pi?
 
@@ -636,14 +713,6 @@ Yes. Connect WhatsApp or Telegram for mobile access. Pro users also get a custom
 
 Yes. Key information from each conversation is stored in a local graph database on your device. When you start a new session, Maxy knows your business, your customers, your preferences, and what was discussed previously. Long conversations are automatically summarised so nothing is lost.
 
-### How does Maxy know when to stop explaining things?
-
-This is the Earned Autonomy model. Maxy tracks your demonstrated competence with each capability independently, progressing through three stages: Assist (shows its work), Augment (handles things normally, flags exceptions), and Orchestrate (executes without explanation). The first time you create an invoice, Maxy walks you through its tools and approach. After a few successful invoices without corrections, it stops explaining and just does it. If it gets something wrong and you correct it, it steps back and shows more of its work again. You can also tell Maxy directly — "I know how to do this" advances it, "explain this again" resets it. This happens per capability — Maxy might handle your scheduling silently while still walking you through a new feature.
-
-### What's the difference between my preferences and my competence?
-
-Preferences are how you like things — terse responses, formal tone, specific workflows. Competence is what you can do in Maxy — whether you need guidance on creating an invoice or you've done it dozens of times. They're tracked separately and work independently. You can be an expert who likes detailed educational explanations, or a novice who prefers brief responses. Maxy respects both.
-
 ### What happens if my conversation gets really long?
 
 Nothing bad. Maxy automatically archives older parts of the conversation to your local memory as the session grows, keeping the active conversation responsive. You can keep talking for as long as you need — there's no message limit, no cut-off, and no point where you have to start over. Archived messages are still available; Maxy retrieves them when they're relevant.

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

@@ -1,18 +1,41 @@
 /**
- * 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.
  */
 /**
- * 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 declare function initStderrTee(serverName: string): void;
 //# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/mcp-stderr-tee/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CA8BtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAkKtD"}

package/payload/platform/lib/mcp-stderr-tee/dist/index.js

@@ -1,45 +1,193 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initStderrTee = initStderrTee;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_string_decoder_1 = require("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.
  */
 function initStderrTee(serverName) {
     const logDir = process.env.LOG_DIR;
     if (!logDir)
         return; // Dev mode or tool discovery — stderr only
-    let logStream;
+    // 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[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;
     try {
         (0, node_fs_1.mkdirSync)(logDir, { recursive: true });
         const date = new Date().toISOString().slice(0, 10);
-        logStream = (0, node_fs_1.createWriteStream)((0, node_path_1.resolve)(logDir, `mcp-${serverName}-stderr-${date}.log`), { flags: "a" });
+        perServerStream = (0, node_fs_1.createWriteStream)((0, node_path_1.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;
+    let streamLogDate = ""; // YYYY-MM-DD the current stream was opened for
+    let streamLogDisabledReason;
+    const openStreamLog = () => {
+        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 = (0, node_path_1.resolve)(logDir, `claude-agent-stream-${today}.log`);
+        try {
+            const s = (0, node_fs_1.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 node_string_decoder_1.StringDecoder("utf8");
+    const emitCompleteLinesToStreamLog = (chunk) => {
+        lineBuffer += chunk;
+        let newlineIndex;
+        // 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, ...args) => {
-        if (!logStream.destroyed) {
-            logStream.write(chunk);
+        // 1. Per-server raw file — preserves Task 362 behaviour (no prefix).
+        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`);
+        }
+        // 3. Original stderr — Claude Code still gets what it's always got.
         return originalWrite(chunk, ...args);
     };
+    // Mark the patch so a second initStderrTee() call is refused at the top.
+    process.stderr.write[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 = "";
+    });
 }
 //# sourceMappingURL=index.js.map

package/payload/platform/lib/mcp-stderr-tee/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAaH,sCA8BC;AAzCD,qCAAyE;AACzE,yCAAoC;AAEpC;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,UAAkB;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,2CAA2C;IAEhE,IAAI,SAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,IAAA,mBAAS,EAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,SAAS,GAAG,IAAA,2BAAiB,EAC3B,IAAA,mBAAO,EAAC,MAAM,EAAE,OAAO,UAAU,WAAW,IAAI,MAAM,CAAC,EACvD,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,UAAU,mCAAmC,GAAG,kBAAkB,CACvE,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,CACrB,KAA0B,EAC1B,GAAG,IAAe,EACT,EAAE;QACX,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;YACzB,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,OAAQ,aAA0B,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}