npm - @rubytech/taskmaster - Versions diffs - 1.0.94 → 1.0.95 - Mend

@rubytech/taskmaster 1.0.94 → 1.0.95

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

package/dist/agents/taskmaster-tools.js +4 -4
package/dist/agents/tool-policy.js +2 -2
package/dist/agents/tools/contact-lookup-tool.js +45 -0
package/dist/agents/tools/contact-update-tool.js +68 -0
package/dist/agents/tools/memory-tool.js +10 -3
package/dist/build-info.json +3 -3
package/dist/cli/provision-seed.js +2 -2
package/dist/control-ui/assets/{index-B7exVNNa.css → index-BWth4bv5.css} +1 -1
package/dist/control-ui/assets/{index-DfQL37PU.js → index-Bem0-Ojd.js} +220 -220
package/dist/control-ui/assets/index-Bem0-Ojd.js.map +1 -0
package/dist/control-ui/index.html +2 -2
package/dist/gateway/chat-sanitize.js +121 -5
package/dist/gateway/media-http.js +120 -0
package/dist/gateway/public-chat-api.js +5 -3
package/dist/gateway/server-http.js +3 -0
package/dist/gateway/server-methods/chat.js +5 -3
package/dist/infra/heartbeat-infra-alert.js +143 -0
package/dist/infra/heartbeat-runner.js +13 -0
package/dist/memory/manager.js +15 -8
package/extensions/diagnostics-otel/node_modules/.bin/acorn +0 -0
package/extensions/googlechat/node_modules/.bin/taskmaster +0 -0
package/extensions/line/node_modules/.bin/taskmaster +0 -0
package/extensions/matrix/node_modules/.bin/markdown-it +0 -0
package/extensions/matrix/node_modules/.bin/taskmaster +0 -0
package/extensions/memory-lancedb/node_modules/.bin/arrow2csv +0 -0
package/extensions/memory-lancedb/node_modules/.bin/openai +0 -0
package/extensions/msteams/node_modules/.bin/taskmaster +0 -0
package/extensions/nostr/node_modules/.bin/taskmaster +0 -0
package/extensions/nostr/node_modules/.bin/tsc +0 -0
package/extensions/nostr/node_modules/.bin/tsserver +0 -0
package/extensions/zalo/node_modules/.bin/taskmaster +0 -0
package/extensions/zalouser/node_modules/.bin/taskmaster +0 -0
package/package.json +64 -54
package/scripts/install.sh +0 -0
package/taskmaster-docs/USER-GUIDE.md +1 -1
package/dist/control-ui/assets/index-DfQL37PU.js.map +0 -1
package/templates/.DS_Store +0 -0
package/templates/customer/.DS_Store +0 -0
package/templates/customer/agents/.DS_Store +0 -0
package/templates/taskmaster/.gitignore +0 -1

package/dist/control-ui/index.html CHANGED Viewed

@@ -6,8 +6,8 @@
     <title>Taskmaster Control</title>
     <meta name="color-scheme" content="dark light" />
     <link rel="icon" type="image/png" href="./favicon.png" />
-    <script type="module" crossorigin src="./assets/index-DfQL37PU.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-B7exVNNa.css">
+    <script type="module" crossorigin src="./assets/index-Bem0-Ojd.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BWth4bv5.css">
   </head>
   <body>
     <taskmaster-app></taskmaster-app>

package/dist/gateway/chat-sanitize.js CHANGED Viewed

@@ -119,13 +119,18 @@ export function stripEnvelopeFromMessages(messages) {
     return changed ? next : messages;
 }
 // ---------------------------------------------------------------------------
-// Base64 image stripping
+// Base64 image stripping & media URL references
 // ---------------------------------------------------------------------------
-// Images must be stored as physical files on disk and referenced by path —
-// never as inline base64 in transcripts or chat history responses.
-// These functions remove base64 data from image content blocks wherever
-// they appear (user, assistant, tool messages).
+// Images are stored as physical files on disk and referenced by path.
+// When sending chat history to the UI, base64 image data is replaced with
+// URL references to the /api/media endpoint. The UI renders these as <img>.
+//
+// Flow:
+// 1. Extract file paths from [media attached: /path (type)] text annotations
+// 2. Remove base64 image blocks from content
+// 3. Add { type: "image", url: "/api/media?path=..." } blocks
 // ---------------------------------------------------------------------------
+import nodePath from "node:path";
 function isBase64ImageBlock(block) {
     if (!block || typeof block !== "object")
         return false;
@@ -148,6 +153,33 @@ function isBase64ImageBlock(block) {
     }
     return false;
 }
+// Pattern: [media attached: /path (mime/type)] or [media attached 1/2: /path (mime/type) | url]
+const MEDIA_PATH_PATTERN = /\[media attached(?:\s+\d+\/\d+)?:\s*(.+?)\s*\(([^)]+)\)(?:\s*\|[^\]]+)?\]/gi;
+/**
+ * Parse [media attached: ...] annotations from text to extract file paths.
+ */
+function extractMediaRefs(text) {
+    if (!text.includes("[media attached"))
+        return [];
+    const refs = [];
+    let match;
+    MEDIA_PATH_PATTERN.lastIndex = 0;
+    while ((match = MEDIA_PATH_PATTERN.exec(text)) !== null) {
+        const absPath = match[1]?.trim();
+        const mimeType = match[2]?.trim();
+        if (absPath && mimeType) {
+            refs.push({ absPath, mimeType });
+        }
+    }
+    return refs;
+}
+function mediaRefToUrl(ref, workspaceRoot) {
+    const relPath = nodePath.relative(workspaceRoot, ref.absPath);
+    // Must stay within workspace (no ../ escapes)
+    if (relPath.startsWith("..") || nodePath.isAbsolute(relPath))
+        return null;
+    return `/api/media?path=${encodeURIComponent(relPath)}`;
+}
 function stripBase64FromContentBlocks(content) {
     let changed = false;
     const next = content.map((block) => {
@@ -193,3 +225,87 @@ export function stripBase64ImagesFromMessages(messages) {
     });
     return changed ? next : messages;
 }
+// ---------------------------------------------------------------------------
+// Combined media sanitization for chat display
+// ---------------------------------------------------------------------------
+/**
+ * Sanitize media in chat messages for UI display.
+ * - Extracts file paths from [media attached: ...] text annotations
+ * - Removes base64 image blocks
+ * - Creates URL-based image references for the /api/media endpoint
+ *
+ * Must be called BEFORE stripEnvelopeFromMessages (which strips annotations).
+ */
+export function sanitizeMediaForChat(messages, workspaceRoot) {
+    if (messages.length === 0 || !workspaceRoot) {
+        // No workspace context — fall back to plain base64 stripping
+        return stripBase64ImagesFromMessages(messages);
+    }
+    let changed = false;
+    const next = messages.map((message) => {
+        const result = sanitizeMessageMedia(message, workspaceRoot);
+        if (result !== message)
+            changed = true;
+        return result;
+    });
+    return changed ? next : messages;
+}
+function sanitizeMessageMedia(message, workspaceRoot) {
+    if (!message || typeof message !== "object")
+        return message;
+    const entry = message;
+    // Collect media refs from text content (works for both string and array content)
+    const mediaRefs = extractMediaRefsFromMessage(entry);
+    // Build URL-based image blocks from annotations
+    const imageBlocks = [];
+    for (const ref of mediaRefs) {
+        const url = mediaRefToUrl(ref, workspaceRoot);
+        if (url) {
+            imageBlocks.push({ type: "image", url });
+        }
+    }
+    if (!Array.isArray(entry.content)) {
+        // String content — no base64 blocks to strip, just add image blocks if found
+        if (imageBlocks.length === 0)
+            return message;
+        const textContent = typeof entry.content === "string" ? entry.content : "";
+        return {
+            ...entry,
+            content: [{ type: "text", text: textContent }, ...imageBlocks],
+        };
+    }
+    // Array content — remove base64 image blocks, add URL-based ones
+    let didChange = false;
+    const filtered = entry.content.filter((block) => {
+        if (isBase64ImageBlock(block)) {
+            didChange = true;
+            return false;
+        }
+        return true;
+    });
+    if (imageBlocks.length > 0) {
+        didChange = true;
+        filtered.push(...imageBlocks);
+    }
+    if (!didChange)
+        return message;
+    return { ...entry, content: filtered };
+}
+function extractMediaRefsFromMessage(entry) {
+    if (typeof entry.content === "string") {
+        return extractMediaRefs(entry.content);
+    }
+    if (Array.isArray(entry.content)) {
+        const refs = [];
+        for (const block of entry.content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string") {
+                refs.push(...extractMediaRefs(b.text));
+            }
+        }
+        return refs;
+    }
+    return [];
+}

package/dist/gateway/media-http.js ADDED Viewed

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveAgentWorkspaceRoot } from "../agents/agent-scope.js";
+// ---------------------------------------------------------------------------
+// Workspace media file endpoint
+// ---------------------------------------------------------------------------
+// Serves image files from the workspace root so that chat history can display
+// inline images by URL instead of embedding base64 data in WebSocket messages.
+//
+// Route:  GET /api/media?path=<workspace-relative-path>
+// ---------------------------------------------------------------------------
+const ALLOWED_IMAGE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".heic",
+    ".heif",
+    ".bmp",
+    ".tiff",
+    ".tif",
+    ".pdf",
+]);
+function contentType(ext) {
+    switch (ext) {
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        case ".heic":
+            return "image/heic";
+        case ".heif":
+            return "image/heif";
+        case ".bmp":
+            return "image/bmp";
+        case ".tiff":
+        case ".tif":
+            return "image/tiff";
+        case ".pdf":
+            return "application/pdf";
+        default:
+            return "application/octet-stream";
+    }
+}
+function isSafeRelativePath(relPath) {
+    if (!relPath)
+        return false;
+    const normalized = path.posix.normalize(relPath);
+    if (normalized.startsWith("../") || normalized === "..")
+        return false;
+    if (normalized.includes("\0"))
+        return false;
+    return true;
+}
+export function resolveWorkspaceRoot(config) {
+    return resolveAgentWorkspaceRoot(config, "admin");
+}
+export function handleMediaRequest(req, res, opts) {
+    const urlObj = new URL(req.url ?? "/", "http://localhost");
+    if (urlObj.pathname !== "/api/media")
+        return false;
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        res.statusCode = 405;
+        res.setHeader("Allow", "GET, HEAD");
+        res.end();
+        return true;
+    }
+    const relPath = urlObj.searchParams.get("path") ?? "";
+    if (!relPath || !isSafeRelativePath(relPath)) {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return true;
+    }
+    const ext = path.extname(relPath).toLowerCase();
+    if (!ALLOWED_IMAGE_EXTENSIONS.has(ext)) {
+        res.statusCode = 403;
+        res.end("Forbidden");
+        return true;
+    }
+    const workspaceRoot = resolveWorkspaceRoot(opts.config);
+    const filePath = path.resolve(workspaceRoot, relPath);
+    // Boundary check: must stay within workspace
+    if (!filePath.startsWith(workspaceRoot + path.sep) && filePath !== workspaceRoot) {
+        res.statusCode = 403;
+        res.end("Forbidden");
+        return true;
+    }
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return true;
+    }
+    if (!stat.isFile()) {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return true;
+    }
+    res.statusCode = 200;
+    res.setHeader("Content-Type", contentType(ext));
+    res.setHeader("Content-Length", stat.size);
+    res.setHeader("Cache-Control", "private, max-age=86400");
+    if (req.method === "HEAD") {
+        res.end();
+    }
+    else {
+        const stream = fs.createReadStream(filePath);
+        stream.pipe(res);
+    }
+    return true;
+}

package/dist/gateway/public-chat-api.js CHANGED Viewed

@@ -36,7 +36,8 @@ import { requestOtp, verifyOtp } from "./public-chat/otp.js";
 import { deliverOtp } from "./public-chat/deliver-otp.js";
 import { buildPublicSessionKey, resolvePublicAgentId } from "./public-chat/session.js";
 import { loadSessionEntry, readSessionMessages } from "./session-utils.js";
-import { stripBase64ImagesFromMessages, stripEnvelopeFromMessages } from "./chat-sanitize.js";
+import { sanitizeMediaForChat, stripEnvelopeFromMessages } from "./chat-sanitize.js";
+import { resolveWorkspaceRoot } from "./media-http.js";
 import { readJsonBodyOrError, sendInvalidRequest, sendJson, sendMethodNotAllowed, setSseHeaders, writeDone, } from "./http-common.js";
 // ---------------------------------------------------------------------------
 // Helpers
@@ -597,7 +598,7 @@ async function handleChatHistory(req, res) {
         sendInvalidRequest(res, "X-Session-Key header required");
         return;
     }
-    const { storePath, entry } = loadSessionEntry(sessionKey);
+    const { cfg, storePath, entry } = loadSessionEntry(sessionKey);
     const sessionId = entry?.sessionId;
     let rawMessages = [];
     if (entry && storePath) {
@@ -620,7 +621,8 @@ async function handleChatHistory(req, res) {
     const limitParam = url.searchParams.get("limit");
     const requested = limitParam ? Math.min(10_000, Math.max(1, Number(limitParam) || 5000)) : 5000;
     const messages = rawMessages.length > requested ? rawMessages.slice(-requested) : rawMessages;
-    const sanitized = stripEnvelopeFromMessages(stripBase64ImagesFromMessages(messages));
+    const workspaceRoot = resolveWorkspaceRoot(cfg);
+    const sanitized = stripEnvelopeFromMessages(sanitizeMediaForChat(messages, workspaceRoot));
     sendJson(res, 200, {
         session_key: sessionKey,
         messages: sanitized,

package/dist/gateway/server-http.js CHANGED Viewed

@@ -13,6 +13,7 @@ import { extractHookToken, getHookChannelError, normalizeAgentPayload, normalize
 import { applyHookMappings } from "./hooks-mapping.js";
 import { handleOpenAiHttpRequest } from "./openai-http.js";
 import { handleOpenResponsesHttpRequest } from "./openresponses-http.js";
+import { handleMediaRequest } from "./media-http.js";
 import { handleToolsInvokeHttpRequest } from "./tools-invoke-http.js";
 function sendJson(res, status, body) {
     res.statusCode = status;
@@ -226,6 +227,8 @@ export function createGatewayHttpServer(opts) {
                 }))
                     return;
             }
+            if (handleMediaRequest(req, res, { config: configSnapshot }))
+                return;
             if (canvasHost) {
                 if (await handleA2uiHttpRequest(req, res))
                     return;

package/dist/gateway/server-methods/chat.js CHANGED Viewed

@@ -15,7 +15,8 @@ import { INTERNAL_MESSAGE_CHANNEL } from "../../utils/message-channel.js";
 import { abortChatRunById, abortChatRunsForSessionKey, isChatStopCommandText, resolveChatRunExpiresAtMs, } from "../chat-abort.js";
 import { ErrorCodes, errorShape, formatValidationErrors, validateChatAbortParams, validateChatHistoryParams, validateChatInjectParams, validateChatSendParams, } from "../protocol/index.js";
 import { loadSessionEntry, readSessionMessages, resolveSessionModelRef } from "../session-utils.js";
-import { stripBase64ImagesFromMessages, stripEnvelopeFromMessages } from "../chat-sanitize.js";
+import { sanitizeMediaForChat, stripEnvelopeFromMessages } from "../chat-sanitize.js";
+import { resolveWorkspaceRoot } from "../media-http.js";
 import { formatForLog } from "../ws-log.js";
 function resolveTranscriptPath(params) {
     const { sessionId, storePath, sessionFile } = params;
@@ -189,8 +190,9 @@ export const chatHandlers = {
         const requested = typeof limit === "number" ? limit : defaultLimit;
         const max = Math.min(hardMax, requested);
         const messages = rawMessages.length > max ? rawMessages.slice(-max) : rawMessages;
-        const withoutBase64 = stripBase64ImagesFromMessages(messages);
-        const sanitized = preserveEnvelopes ? withoutBase64 : stripEnvelopeFromMessages(withoutBase64);
+        const workspaceRoot = resolveWorkspaceRoot(cfg);
+        const withMediaUrls = sanitizeMediaForChat(messages, workspaceRoot);
+        const sanitized = preserveEnvelopes ? withMediaUrls : stripEnvelopeFromMessages(withMediaUrls);
         // Diagnostic: log resolution details so we can trace "lost history" reports.
         const prevCount = entry?.previousSessions?.length ?? 0;
         context.logGateway.info(`chat.history: sessionKey=${sessionKey} resolvedSessionId=${sessionId ?? "none"} storePath=${storePath ?? "none"} entryExists=${!!entry} previousSessions=${prevCount} rawMessages=${rawMessages.length} sent=${sanitized.length}`);

package/dist/infra/heartbeat-infra-alert.js ADDED Viewed

@@ -0,0 +1,143 @@
+import { describeFailoverError } from "../agents/failover-error.js";
+import { getChannelPlugin } from "../channels/plugins/index.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { deliverOutboundPayloads } from "./outbound/deliver.js";
+const log = createSubsystemLogger("gateway/heartbeat-infra-alert");
+const COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6 hours
+const CONSECUTIVE_FAILURE_THRESHOLD = 3;
+const MESSAGES = {
+    auth: "Your AI assistant is offline because the API key is invalid or has expired. Open the control panel and go to Settings > API Keys to update it.",
+    billing: "Your AI assistant is offline because of a billing issue with the AI provider. Check your AI provider account.",
+    repeated: (n) => `Your AI assistant has failed to respond ${n} times in a row.`,
+};
+// In-memory cooldown map: category → last-sent timestamp.
+// Resets on gateway restart — correct: admin may have restarted to fix the issue.
+const cooldowns = new Map();
+// Consecutive non-auth/billing failure counter. Resets when an auth/billing
+// alert fires or when the heartbeat succeeds (caller responsibility via resetConsecutiveFailures).
+let consecutiveUnknownFailures = 0;
+function isCooledDown(category, nowMs) {
+    const lastSent = cooldowns.get(category);
+    if (typeof lastSent !== "number")
+        return false;
+    return nowMs - lastSent < COOLDOWN_MS;
+}
+function resolveAlertMessage(category, count) {
+    const template = MESSAGES[category];
+    if (typeof template === "function")
+        return template(count ?? 0);
+    return template;
+}
+/**
+ * Attempt to send an infra alert to the admin when a heartbeat fails due to
+ * auth, billing, or repeated unknown errors. Uses deliverOutboundPayloads
+ * directly — no agent involvement.
+ *
+ * Returns true if an alert was sent, false if suppressed or skipped.
+ * Never throws.
+ */
+export async function maybeAlertAdmin(ctx) {
+    try {
+        const { cfg, delivery, err, deps } = ctx;
+        const nowMs = ctx.nowMs ?? Date.now();
+        // No delivery target — can't alert.
+        if (delivery.channel === "none" || !delivery.to)
+            return false;
+        const classified = describeFailoverError(err);
+        const reason = classified.reason;
+        // Auth or billing: send targeted alert.
+        if (reason === "auth" || reason === "billing") {
+            // Reset consecutive unknown failures — we have a specific diagnosis.
+            consecutiveUnknownFailures = 0;
+            const category = reason;
+            if (isCooledDown(category, nowMs)) {
+                log.debug("infra alert suppressed (cooldown)", { category });
+                return false;
+            }
+            // Check channel readiness before attempting delivery.
+            const plugin = getChannelPlugin(delivery.channel);
+            if (plugin?.heartbeat?.checkReady) {
+                const readiness = await plugin.heartbeat.checkReady({
+                    cfg,
+                    accountId: delivery.accountId,
+                    deps,
+                });
+                if (!readiness.ok) {
+                    log.info("infra alert skipped: channel not ready", {
+                        category,
+                        reason: readiness.reason,
+                    });
+                    return false;
+                }
+            }
+            const message = resolveAlertMessage(category);
+            await deliverOutboundPayloads({
+                cfg,
+                channel: delivery.channel,
+                to: delivery.to,
+                accountId: delivery.accountId,
+                payloads: [{ text: message }],
+                deps,
+            });
+            cooldowns.set(category, nowMs);
+            log.info("infra alert sent", { category, to: delivery.to });
+            return true;
+        }
+        // Non-auth/billing: track consecutive failures.
+        consecutiveUnknownFailures += 1;
+        if (consecutiveUnknownFailures >= CONSECUTIVE_FAILURE_THRESHOLD) {
+            const category = "repeated";
+            if (isCooledDown(category, nowMs)) {
+                log.debug("infra alert suppressed (cooldown)", { category });
+                return false;
+            }
+            const plugin = getChannelPlugin(delivery.channel);
+            if (plugin?.heartbeat?.checkReady) {
+                const readiness = await plugin.heartbeat.checkReady({
+                    cfg,
+                    accountId: delivery.accountId,
+                    deps,
+                });
+                if (!readiness.ok) {
+                    log.info("infra alert skipped: channel not ready", {
+                        category,
+                        reason: readiness.reason,
+                    });
+                    return false;
+                }
+            }
+            const message = resolveAlertMessage(category, consecutiveUnknownFailures);
+            await deliverOutboundPayloads({
+                cfg,
+                channel: delivery.channel,
+                to: delivery.to,
+                accountId: delivery.accountId,
+                payloads: [{ text: message }],
+                deps,
+            });
+            cooldowns.set(category, nowMs);
+            log.info("infra alert sent", {
+                category,
+                consecutiveFailures: consecutiveUnknownFailures,
+                to: delivery.to,
+            });
+            return true;
+        }
+        return false;
+    }
+    catch (alertErr) {
+        log.error("infra alert delivery failed", {
+            error: alertErr instanceof Error ? alertErr.message : String(alertErr),
+        });
+        return false;
+    }
+}
+/** Reset consecutive unknown failure counter. Call when heartbeat succeeds. */
+export function resetConsecutiveFailures() {
+    consecutiveUnknownFailures = 0;
+}
+/** Reset all cooldowns and counters. Exposed for testing. */
+export function resetAlertCooldowns() {
+    cooldowns.clear();
+    consecutiveUnknownFailures = 0;
+}

package/dist/infra/heartbeat-runner.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveAgentConfig, resolveAgentWorkspaceDir, resolveDefaultAgentId, } from "../agents/agent-scope.js";
+import { describeFailoverError } from "../agents/failover-error.js";
 import { resolveUserTimezone } from "../agents/date-time.js";
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { DEFAULT_HEARTBEAT_FILENAME } from "../agents/workspace.js";
@@ -19,6 +20,7 @@ import { defaultRuntime } from "../runtime.js";
 import { resolveAgentBoundAccountId } from "../routing/bindings.js";
 import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
 import { emitHeartbeatEvent, resolveIndicatorType } from "./heartbeat-events.js";
+import { maybeAlertAdmin, resetConsecutiveFailures } from "./heartbeat-infra-alert.js";
 import { resolveHeartbeatVisibility } from "./heartbeat-visibility.js";
 import { requestHeartbeatNow, setHeartbeatWakeHandler, } from "./heartbeat-wake.js";
 import { deliverOutboundPayloads } from "./outbound/deliver.js";
@@ -418,6 +420,7 @@ export async function runHeartbeatOnce(opts) {
     };
     try {
         const replyResult = await getReplyFromConfig(ctx, { isHeartbeat: true }, cfg);
+        resetConsecutiveFailures();
         const replyPayload = resolveHeartbeatReplyPayload(replyResult);
         const includeReasoning = heartbeat?.includeReasoning === true;
         const reasoningPayloads = includeReasoning
@@ -597,12 +600,22 @@ export async function runHeartbeatOnce(opts) {
     }
     catch (err) {
         const reason = formatErrorMessage(err);
+        const classified = describeFailoverError(err);
+        let infraAlertSent = false;
+        try {
+            infraAlertSent = await maybeAlertAdmin({ cfg, delivery, err, deps: opts.deps });
+        }
+        catch {
+            // Never let alert delivery crash the heartbeat runner.
+        }
         emitHeartbeatEvent({
             status: "failed",
             reason,
             durationMs: Date.now() - startedAt,
             channel: delivery.channel !== "none" ? delivery.channel : undefined,
             indicatorType: visibility.useIndicator ? resolveIndicatorType("failed") : undefined,
+            failureReason: classified.reason,
+            infraAlertSent,
         });
         log.error(`heartbeat failed: ${reason}`, { error: reason });
         return { status: "failed", reason };

package/dist/memory/manager.js CHANGED Viewed

@@ -588,19 +588,26 @@ export class MemoryIndexManager {
         return { path: relPath, bytesWritten: Buffer.byteLength(params.content, "utf-8") };
     }
     /**
-     * Save media (binary) to a user's memory folder with session-scoped access control.
-     * Copies from a source path (e.g., inbound media) to the user's media folder.
+     * Save media (binary) to a memory folder with session-scoped access control.
+     * Copies from a source path (e.g., inbound media) to the destination folder.
+     * When destFolder is omitted, defaults to memory/users/{peer}/media/.
      * Returns the destination path relative to workspace.
      */
     async writeMedia(params) {
-        // Resolve session context to get user folder
         const sessionCtx = params.sessionContext ?? parseSessionContext(params.sessionKey);
-        const peer = sessionCtx.peer;
-        if (!peer) {
-            throw new Error("session context required (peer not found)");
+        let relPath;
+        if (params.destFolder) {
+            // Explicit folder — use as-is (scope checking enforces access)
+            relPath = `${params.destFolder}/${params.destFilename}`;
+        }
+        else {
+            // Default: memory/users/{peer}/media/{filename}
+            const peer = sessionCtx.peer;
+            if (!peer) {
+                throw new Error("session context required (peer not found)");
+            }
+            relPath = `memory/users/${peer}/media/${params.destFilename}`;
         }
-        // Build destination path: memory/users/{peer}/media/{filename}
-        const relPath = `memory/users/${peer}/media/${params.destFilename}`;
         // Apply scope filtering before writing (uses "write" scope)
         const scope = this.settings.scope;
         if (scope) {