@rubytech/create-realagent 1.0.406

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

@@ -0,0 +1,58 @@
+# Telegram Guide
+
+## What the Telegram Plugin Does
+
+The Telegram plugin connects Maxy to a Telegram bot. Once set up, you can:
+
+- Send messages to individuals or groups via Maxy ("Send a message to the team: standup in 10 minutes")
+- Receive messages from your Telegram bot and have Maxy respond
+- Use Telegram as a channel for Maxy notifications and alerts
+
+## Setup
+
+### Step 1: Create a Telegram bot
+
+1. Open Telegram and search for `@BotFather`
+2. Send `/newbot` and follow the prompts to choose a name and username
+3. BotFather will give you a token — it looks like `123456789:ABCdefGhijklMNOpqrstUVWxyz`
+4. Keep this token — you'll need it in the next step
+
+### Step 2: Connect the plugin
+
+Tell Maxy: "Set up Telegram" or "Configure the Telegram bot."
+
+Maxy will ask for your bot token, then save it and activate the plugin. The bot is now connected.
+
+### Step 3: Start the bot
+
+In Telegram, open your bot and send `/start`. The bot is now active and listening.
+
+## Sending Messages via Maxy
+
+Once connected, tell Maxy to send messages on your behalf:
+
+- "Send a Telegram message to John: I'll be 10 minutes late"
+- "Message the team channel: server maintenance at 11pm"
+- "Tell Sarah via Telegram that the proposal is ready"
+
+Maxy needs a chat ID or username to target a specific person or group. For groups, you'll need to add the bot to the group first.
+
+## Getting a Chat ID
+
+To message a specific person or group, Maxy needs their chat ID. The easiest way:
+
+1. Have the person (or yourself) send any message to your bot
+2. Ask Maxy: "What chat IDs have messaged the bot recently?"
+3. Maxy will look up the message history and show you the IDs
+
+## Message History
+
+Ask Maxy: "What messages has the bot received?" or "Show recent Telegram activity."
+
+## Troubleshooting
+
+**Bot not responding:** Check that the bot token is correct — ask Maxy "What's my Telegram bot token configured as?" and verify it matches BotFather.
+
+**Can't send to a group:** The bot must be a member of the group. Add it via the group settings in Telegram, then try again.
+
+**Messages not arriving:** Make sure the bot hasn't been blocked. Try sending `/start` to the bot directly.

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -0,0 +1,88 @@
+# Troubleshooting
+
+## Agent Not Responding
+
+**Symptom:** You send a message and nothing comes back, or the response never arrives.
+
+**Check:**
+1. Ask Maxy: "Check system status" — the `system-status` tool will report whether all services are running
+2. Check the platform logs: ask Maxy "Show me the recent logs"
+3. If the admin agent itself won't start: restart the platform (see below)
+
+**Common causes:**
+- Claude API connectivity issue — check your Claude OAuth connection is still valid
+- Platform process has stopped — restart it
+- Network issue if accessing remotely — check your Cloudflare tunnel is running
+
+---
+
+## Memory Not Working
+
+**Symptom:** Maxy doesn't remember things you've told it, or search returns nothing.
+
+**Check:**
+1. Ask Maxy: "Check the Neo4j connection"
+2. Ask Maxy: "Search memory for [something you know was stored]"
+
+**Common causes:**
+- Neo4j service stopped — restart the platform, which restarts Neo4j
+- Memory index is stale — ask Maxy: "Reindex memory"
+
+---
+
+## Telegram Bot Not Receiving Messages
+
+**Symptom:** You send a message to the bot and nothing happens.
+
+**Check:**
+1. Confirm the bot token is correct: ask Maxy "What Telegram bot token is configured?"
+2. Verify the bot is running: send `/start` to the bot in Telegram
+3. Check the MCP server logs: ask Maxy "Show Telegram plugin logs"
+
+**Common causes:**
+- Bot token changed (if you regenerated it in BotFather) — update it by telling Maxy "Update my Telegram bot token"
+- Webhook not connected — restart the platform
+
+---
+
+## Plugin Errors
+
+**Symptom:** A tool fails with an error, or a plugin says it can't connect.
+
+**Check:**
+1. Ask Maxy: "Show me recent errors"
+2. Ask Maxy: "Restart the [plugin name] plugin"
+
+**Common causes:**
+- Missing environment variable (API key, token) — the error message will name it; ask Maxy to help configure it
+- MCP server crashed — restarting the platform restarts all MCP servers
+
+---
+
+## Restarting the Platform
+
+From the admin interface, ask Maxy: "Restart the platform."
+
+If Maxy itself isn't responding (the page loads but the agent won't connect), try refreshing the browser. If the page itself won't load, the platform process may have stopped — power-cycle the Raspberry Pi by unplugging and reconnecting power, then wait a minute for services to restart automatically.
+
+---
+
+## Checking Logs
+
+Ask Maxy: "Show me the logs" or "Show errors from the last hour."
+
+For specific plugin logs: "Show Telegram logs" or "Show contacts plugin logs."
+
+Maxy has access to all platform logs and can filter them for you.
+
+---
+
+## Cloudflare Tunnel Down (Remote Access Broken)
+
+**Symptom:** You can reach Maxy on your local network but not via your public domain.
+
+**Check:** Ask Maxy "Check the Cloudflare tunnel status."
+
+**Fix:** Ask Maxy "Restart the Cloudflare tunnel."
+
+If the tunnel won't reconnect, re-run the Cloudflare setup: ask Maxy "Reconnect Cloudflare."

package/payload/platform/plugins/documents/mcp/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/plugins/documents/mcp/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,98 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import QRCode from "qrcode";
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "maxy-documents",
+    version: "0.1.0",
+});
+server.tool("qr-generate", "Generate a QR code from text or a URL. Returns the QR code as a data URI (PNG) or saves to a file path.", {
+    data: z.string().describe("The text or URL to encode in the QR code"),
+    outputPath: z
+        .string()
+        .optional()
+        .describe("File path to save the PNG. If omitted, returns a data URI."),
+    width: z.number().optional().describe("Width in pixels (default 300)"),
+}, async ({ data, outputPath, width }) => {
+    try {
+        const options = { width: width ?? 300, margin: 2 };
+        if (outputPath) {
+            await QRCode.toFile(outputPath, data, options);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `QR code saved to ${outputPath}`,
+                    },
+                ],
+            };
+        }
+        const dataUri = await QRCode.toDataURL(data, options);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `QR code generated for: ${data}`,
+                },
+                {
+                    type: "image",
+                    data: dataUri.replace(/^data:image\/png;base64,/, ""),
+                    mimeType: "image/png",
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `QR generation failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("document-ingest", "DEPRECATED — use memory-ingest-extract + memory-ingest (in the memory MCP server) instead. " +
+    "This tool has been replaced by a hierarchical ingestion pipeline with LLM-generated summaries.", {
+    attachmentId: z.string().uuid().describe("UUID of the attachment"),
+    accountId: z.string().describe("Account this attachment belongs to"),
+    storagePath: z.string().describe("Absolute path to the stored file on disk"),
+    filename: z.string().describe("Original filename as uploaded"),
+    mimeType: z.string().describe("MIME type of the file"),
+    sizeBytes: z.number().int().describe("File size in bytes"),
+}, async () => ({
+    content: [{
+            type: "text",
+            text: "document-ingest is deprecated. Use memory-ingest-extract to extract text, then memory-ingest to store the document hierarchy with LLM-generated summaries. Both tools are in the memory MCP server.",
+        }],
+    isError: true,
+}));
+server.tool("document-create-pdf", "Generate a PDF document from markdown or HTML content", {
+    content: z.string(),
+    format: z.enum(["markdown", "html"]).optional(),
+    title: z.string().optional(),
+}, async () => ({
+    content: [
+        {
+            type: "text",
+            text: "PDF generation is not available in Phase 0. This capability will be added in Phase 1.",
+        },
+    ],
+}));
+server.tool("document-list", "List documents for an account", {
+    accountId: z.string().optional(),
+    type: z.string().optional(),
+}, async () => ({
+    content: [
+        {
+            type: "text",
+            text: "Document management is not available in Phase 0. This capability will be added in Phase 1.",
+        },
+    ],
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/documents/mcp/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,222 @@
+---
+name: email
+description: "Email — dedicated email account. Retrieval: email-graph-query for stored email history, recall, and search ('what emails are in memory?', 'emails about X', 'what did Y send?'); email-read / email-search for live IMAP inbox. Sending: email-send (new), email-reply (threaded). Config: email-setup, email-status, email-auto-respond-config, email-otp-extract."
+icon: 📧
+tools:
+  - email-setup
+  - email-read
+  - email-send
+  - email-reply
+  - email-search
+  - email-graph-query
+  - email-otp-extract
+  - email-status
+  - email-auto-respond-config
+always: false
+embed: ["admin"]
+metadata: {"taskmaster":{"optional":true,"recommended":true}}
+---
+
+# Email
+
+Manages the agent's own dedicated email account — IMAP for reading, SMTP for sending. Admin agent only.
+
+## Setup
+
+Collect email credentials via a form. Render this `form` component with `render-component`:
+
+**Fields:**
+
+| name | label | type | required | placeholder |
+|------|-------|------|----------|-------------|
+| `email` | Email address | text | yes | user@example.com |
+| `password` | Password | text | yes | App password or account password |
+| `imapHost` | IMAP host | text | yes | imap.example.com |
+| `imapPort` | IMAP port | number | yes | 993 |
+| `imapSecurity` | IMAP security | select | yes | Options: `tls` (default), `starttls` |
+| `smtpHost` | SMTP host | text | yes | smtp.example.com |
+| `smtpPort` | SMTP port | number | yes | 587 |
+| `smtpSecurity` | SMTP security | select | yes | Options: `tls`, `starttls` (default) |
+| `agentAddress` | Agent email address (if different from login) | text | no | agent@yourdomain.com |
+
+The `agentAddress` field is for catchall/alias setups where the authentication email differs from the address the agent operates as. Leave empty when they're the same.
+
+After form submission, pass all fields to `email-setup`. On success, confirm "credentials stored" and the inbox count. On failure, relay the diagnostic — the tool returns specific guidance (wrong password, connection refused, TLS mismatch).
+
+The agent never displays stored passwords. Never name or recommend specific email providers — the form collects the standard fields every provider gives its users.
+
+## Reading and Searching
+
+`email-read` and `email-search` return message metadata only: UID, sender, subject, and date. Body content is not included — present results as a message list without commenting on missing bodies.
+
+### Pagination
+
+Both tools return up to 50 messages per request (default 20). When more messages exist beyond the returned set, the response includes a `next_before_uid` value. Pass this value as the `before_uid` parameter on the next call to retrieve the next page of older messages. When `next_before_uid` is absent, all matching messages have been returned.
+
+### Folders
+
+Both tools accept a `folder` parameter: `"inbox"` (default) or `"sent"`. The Sent folder is discovered automatically via the IMAP server's special-use flags — no folder name guessing required.
+
+### Filtering
+
+Both tools support filtering by:
+- `sender` — sender address or domain
+- `to` — recipient address
+- `since` / `before` — ISO date range
+- `email-read` additionally supports `subjectPattern` (regex)
+- `email-search` additionally supports `subject` (text) and `body` (keyword)
+
+## Replying
+
+`email-reply` sends a reply to an existing email, threaded correctly in the recipient's mail client.
+
+The tool accepts the `messageId` of the email being replied to (visible in `email-read` output as the `Message-ID` field). It looks up the original email in the graph, sets `In-Reply-To` and `References` headers, derives the recipient from the original sender, and prepends `Re:` to the subject (stripping duplicate prefixes).
+
+- **Reply to sender:** Default behaviour — replies to the original sender only.
+- **Reply all:** Set `replyAll: true` to include all original recipients (TO + CC). The agent's own address is automatically excluded from the recipient list.
+- **Threading:** The reply appears in the same conversation thread in Gmail, Apple Mail, Outlook, and other RFC 2822-compliant clients.
+- **Prerequisite:** The original email must exist in the graph (stored by the background polling job). If the email hasn't been fetched yet, the tool returns a clear error.
+
+Use `email-reply` when responding to a received email. Use `email-send` for new outbound messages.
+
+## Alias Support
+
+When `agentAddress` is set and differs from the auth email:
+
+- **Sending:** emails are sent with the agent address as the From header. SMTP authentication still uses the auth email.
+- **Reading/searching:** only emails whose TO header contains the agent address are returned. The agent ignores emails to other addresses on the same mailbox.
+- **OTP extraction:** only OTPs addressed to the agent address are found.
+- **Status:** reports both the agent address and the auth email.
+
+When `agentAddress` is not set or matches the auth email, all tools behave as before — no filtering, From header uses the auth email.
+
+## Email Persistence
+
+Emails are automatically polled from IMAP and stored as `Email` nodes in the graph. This happens via a background cron job — no manual triggering needed.
+
+- **Polling:** After `email-setup` completes, the platform polls IMAP at the configured interval (default: every 5 minutes). Only emails addressed TO the agent's `agentAddress` are stored.
+- **Deduplication:** Each email is identified by its Message-ID header. Re-polling the same messages does not create duplicates, even if the agent's email address changes between poll cycles. A composite unique constraint on `(messageId, accountId)` provides database-level enforcement.
+- **Semantic search:** Stored emails are vector-indexed (subject + body preview), enabling natural-language search over email history via `email-graph-query`.
+- **Isolation:** Each agent sees only emails addressed to its own bound email address, even when sharing a catchall mailbox.
+
+## Email Threading
+
+Emails are linked into conversation threads via `REPLY_TO` graph edges. When an email has an `In-Reply-To` header, the platform looks up the parent email by `Message-ID` within the same account and creates an edge. Thread linking happens automatically during the polling cron job.
+
+- **Out-of-order delivery:** If a reply arrives before its parent, the edge is created later when the parent is stored (orphan back-fill).
+- **Thread context:** `email-read` and `email-search` include `Thread-Depth` (number of hops to the thread root) and `Thread-ID` (emailId of the root message) for any email that is part of a thread. Root emails (no parent) have no thread fields.
+- **Scope:** Thread edges never cross account boundaries — parent lookups are always scoped to the same account.
+
+## Auto-Respond Audit Trail
+
+When auto-respond sends a reply, the outbound message is stored as an `Email` node with `direction: "outbound"` and a `REPLY_TO` edge to the original inbound email. This creates a queryable audit trail of every automated reply — what the agent said, when, and to whom.
+
+Outbound email nodes have the same properties as inbound emails (subject, bodyPreview, fromAddress, toAddresses, timestamps) plus the `direction` property. They appear in thread traversals alongside inbound messages.
+
+### Agent-Email Binding
+
+Each email address is bound to exactly one agent. Each agent can have at most one email address. This is enforced during `email-setup`:
+
+- The `agentSlug` parameter identifies which agent owns this email address (defaults to `"admin"`)
+- If the address is already bound to a different agent, setup fails with a clear error naming the conflicting agent
+- The binding is on `agentAddress` (the identity the agent presents), not the auth email
+
+### Email Retrieval Paths
+
+Three retrieval paths exist for email data — each scoped to a different purpose:
+
+- **Live inbox** (`email-read`, `email-search`) — queries IMAP directly. Use for checking the inbox, reading recent messages, browsing folders, and real-time inbox state. Requires IMAP connectivity.
+- **Graph list/search** (`email-graph-query`) — queries stored Email nodes in Neo4j. Use for email history, recall, and semantic search ("what emails are in memory?", "find emails about cabbages", "what did Sarah send about the contract?"). Works without IMAP. Supports date/sender/direction filters and natural-language semantic matching.
+- **General knowledge** (`memory-search`) — searches the entire knowledge graph across all node types. Use when the user's question spans all memory, not just emails ("what do you know about contract renewals?").
+
+When the user asks about stored emails, email history, or email recall — use `email-graph-query`. When they ask to check the inbox or read specific recent messages — use the IMAP tools. When the question is broader than emails — use `memory-search`.
+
+## Inbound Email Screening
+
+Every inbound email is classified by Claude Haiku before entering Neo4j. The classifier examines `fromAddress`, `fromName`, `subject`, and the first 1024 characters of `bodyPreview`.
+
+### Verdicts
+
+| Verdict | Stored? | Embedding? | Auto-respond? | Graph query? |
+|---------|---------|------------|---------------|--------------|
+| `clean` | Yes | Yes | Yes | Yes |
+| `suspicious` | Yes (with `screeningReason`) | Yes | No | Yes |
+| `discarded` | Yes (with `screeningReason`) | No | No | No (list mode) |
+
+- **clean** — legitimate personal or business correspondence
+- **suspicious** — phishing indicators (urgency + credential requests, mismatched sender), prompt injection patterns, or classification failure (safe default)
+- **discarded** — obvious spam, marketing bulk mail, auto-generated notifications with no actionable content
+
+### Prompt injection flag
+
+When `promptInjectionFlag` is true (body contains instruction-like patterns targeting an AI agent), auto-respond skips the email entirely regardless of verdict. No reply is generated. The email is visible in Neo4j for admin review.
+
+### Failure handling
+
+If the Haiku API is unavailable (network, rate limit, auth failure), the email defaults to `suspicious`. The entire fetch batch is never blocked — each email is classified independently. API key absence causes all emails in the batch to default to `suspicious`.
+
+### Logs
+
+Classification verdicts are logged to `~/.maxy/logs/email-fetch.log` with per-email detail (fromAddress, verdict, reason, promptInjectionRisk) and batch summaries.
+
+## Security
+
+- Credentials stored as a file with restricted permissions — never in conversation
+- IMAP and SMTP connections require TLS or STARTTLS — plaintext is rejected
+- Only the agent's own dedicated account is accessed — never the user's personal email
+- Email nodes have `scope: "admin"` — never visible to public agents
+- Inbound emails are classified by Haiku before storage — prompt injection and phishing are flagged
+
+## Auto-Respond
+
+When enabled, a public agent automatically replies to incoming emails. A cron job polls the inbox for new messages and generates replies via the assigned agent.
+
+### Setup
+
+To enable auto-respond, call `email-auto-respond-config` with `enabled: true`. The tool requires an `agentSlug` — render a `single-select` component with available public agents so the admin can choose which agent handles responses. The tool returns the agent list when called without a slug.
+
+When called without an `agentSlug`, the tool returns available agents. Present these as a `single-select` component for the admin to choose from, then call the tool again with the selected slug.
+
+### Configuration
+
+- `enabled` — `true` to enable, `false` to disable
+- `agentSlug` — slug of the public agent that responds (required when enabling)
+- `pollIntervalMinutes` — how often to check for new emails (default: 5, range: 1–60)
+- `hourlyLimit` — maximum auto-replies per clock hour UTC (default: 20, range: 1–1000)
+- `dailyLimit` — maximum auto-replies per calendar day UTC (default: 100, range: 1–10000)
+
+### Behaviour
+
+- The cron job runs every minute. Each account's poll is skipped if the configured interval hasn't elapsed since the last poll.
+- Only emails addressed TO the agent's email address are processed (alias filtering applies).
+- Auto-replies, mailing list messages, and emails from the agent's own address are automatically skipped (RFC 3834 loop prevention).
+- Outgoing replies include `In-Reply-To` and `References` headers for correct threading, and `Auto-Submitted: auto-replied` to prevent loops with other auto-responders.
+- The subject line carries a single `Re:` prefix (no doubling).
+
+### Rate Limiting
+
+Per-account send caps prevent runaway auto-replies from spam waves, mailing list explosions, or deliberate attacks. Two independent limits:
+
+- **Hourly limit** (default 20) — resets at each UTC clock-hour boundary
+- **Daily limit** (default 100) — resets at midnight UTC
+
+When either limit is reached, remaining emails in the poll cycle are skipped (not replied to). Auto-respond is **not** disabled — counters reset naturally at the next boundary. A medium-priority admin Task is created to notify the admin.
+
+Within a single poll cycle, only one auto-reply is sent per unique sender address. This prevents reply storms when an automated sender delivers multiple messages. Sender deduplication is case-insensitive.
+
+### Circuit Breaker
+
+After 3 consecutive failures (IMAP errors, API failures, SMTP rejections), auto-respond is automatically disabled and a high-priority Task is created for the admin. The admin sees this task at the start of their next session and can re-enable auto-respond after resolving the issue.
+
+### Disabling
+
+Call `email-auto-respond-config` with `enabled: false`. This clears the agent assignment and resets the failure counter.
+
+## OTP Integration
+
+Other skills call `email-otp-extract` during service authentication (Anthropic OAuth, Cloudflare setup) with:
+- `sender` — expected sender domain
+- `subject_pattern` — optional regex for subject line
+- `timeout` — how long to poll (default 60s)
+
+The tool polls at short intervals, extracts the verification code, and returns it. On timeout, it returns a clear failure so the calling skill can ask the user to check manually.

package/payload/platform/plugins/email/mcp/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/plugins/email/mcp/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}