@rubytech/taskmaster 1.0.94 → 1.0.96

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

@@ -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

@@ -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

@@ -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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.0.94",
+  "version": "1.0.96",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"
@@ -77,12 +77,66 @@
     "dist/filler/**",
     "dist/license/**"
   ],
+  "scripts": {
+    "dev": "node scripts/run-node.mjs",
+    "postinstall": "node scripts/postinstall.js",
+    "prepack": "pnpm build && pnpm ui:build",
+    "docs:list": "node scripts/docs-list.js",
+    "docs:bin": "node scripts/build-docs-list.mjs",
+    "docs:dev": "cd docs && mint dev",
+    "docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links",
+    "build": "tsc -p tsconfig.json && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts",
+    "plugins:sync": "node --import tsx scripts/sync-plugin-versions.ts",
+    "release:check": "node --import tsx scripts/release-check.ts",
+    "ui:install": "node scripts/ui.js install",
+    "ui:dev": "node scripts/ui.js dev",
+    "ui:build": "node scripts/ui.js build",
+    "start": "node scripts/run-node.mjs",
+    "taskmaster": "node scripts/run-node.mjs",
+    "gateway:watch": "node scripts/watch-node.mjs gateway --force",
+    "logs": "npx tsx scripts/session-viewer.ts",
+    "gateway:dev": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway",
+    "gateway:dev:reset": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway --reset",
+    "tui": "node scripts/run-node.mjs tui",
+    "tui:dev": "TASKMASTER_PROFILE=dev node scripts/run-node.mjs tui",
+    "taskmaster:rpc": "node scripts/run-node.mjs agent --mode rpc --json",
+    "lint": "oxlint --type-aware src test",
+    "lint:fix": "pnpm format:fix && oxlint --type-aware --fix src test",
+    "format": "oxfmt --check src test",
+    "format:fix": "oxfmt --write src test",
+    "test": "node scripts/test-parallel.mjs",
+    "test:watch": "vitest",
+    "test:ui": "pnpm --dir ui test",
+    "test:force": "node --import tsx scripts/test-force.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:live": "TASKMASTER_LIVE_TEST=1 vitest run --config vitest.live.config.ts",
+    "test:docker:onboard": "bash scripts/e2e/onboard-docker.sh",
+    "test:docker:gateway-network": "bash scripts/e2e/gateway-network-docker.sh",
+    "test:docker:live-models": "bash scripts/test-live-models-docker.sh",
+    "test:docker:live-gateway": "bash scripts/test-live-gateway-models-docker.sh",
+    "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
+    "test:docker:doctor-switch": "bash scripts/e2e/doctor-install-switch-docker.sh",
+    "test:docker:plugins": "bash scripts/e2e/plugins-docker.sh",
+    "test:docker:cleanup": "bash scripts/test-cleanup-docker.sh",
+    "test:docker:all": "pnpm test:docker:live-models && pnpm test:docker:live-gateway && pnpm test:docker:onboard && pnpm test:docker:gateway-network && pnpm test:docker:qr && pnpm test:docker:doctor-switch && pnpm test:docker:plugins && pnpm test:docker:cleanup",
+    "test:all": "pnpm lint && pnpm build && pnpm test && pnpm test:e2e && pnpm test:live && pnpm test:docker:all",
+    "test:install:e2e": "bash scripts/test-install-sh-e2e-docker.sh",
+    "test:install:smoke": "bash scripts/test-install-sh-docker.sh",
+    "test:install:e2e:openai": "TASKMASTER_E2E_MODELS=openai bash scripts/test-install-sh-e2e-docker.sh",
+    "test:install:e2e:anthropic": "TASKMASTER_E2E_MODELS=anthropic bash scripts/test-install-sh-e2e-docker.sh",
+    "protocol:gen": "node --import tsx scripts/protocol-gen.ts",
+    "protocol:check": "pnpm protocol:gen && git diff --exit-code -- dist/protocol.schema.json",
+    "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh",
+    "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500"
+  },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "engines": {
     "node": ">=22.12.0"
   },
+  "packageManager": "pnpm@10.23.0",
   "dependencies": {
     "@agentclientprotocol/sdk": "0.13.1",
     "@aws-sdk/client-bedrock": "^3.975.0",
@@ -172,6 +226,14 @@
     "vitest": "^4.0.18",
     "wireit": "^0.14.12"
   },
+  "pnpm": {
+    "minimumReleaseAge": 2880,
+    "overrides": {
+      "@sinclair/typebox": "0.34.47",
+      "hono": "4.11.4",
+      "tar": "7.5.4"
+    }
+  },
   "vitest": {
     "coverage": {
       "provider": "v8",
@@ -200,57 +262,5 @@
       "**/vendor/**",
       "dist/Taskmaster.app/**"
     ]
-  },
-  "scripts": {
-    "dev": "node scripts/run-node.mjs",
-    "postinstall": "node scripts/postinstall.js",
-    "docs:list": "node scripts/docs-list.js",
-    "docs:bin": "node scripts/build-docs-list.mjs",
-    "docs:dev": "cd docs && mint dev",
-    "docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links",
-    "build": "tsc -p tsconfig.json && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts",
-    "plugins:sync": "node --import tsx scripts/sync-plugin-versions.ts",
-    "release:check": "node --import tsx scripts/release-check.ts",
-    "ui:install": "node scripts/ui.js install",
-    "ui:dev": "node scripts/ui.js dev",
-    "ui:build": "node scripts/ui.js build",
-    "start": "node scripts/run-node.mjs",
-    "taskmaster": "node scripts/run-node.mjs",
-    "gateway:watch": "node scripts/watch-node.mjs gateway --force",
-    "logs": "npx tsx scripts/session-viewer.ts",
-    "gateway:dev": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway",
-    "gateway:dev:reset": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway --reset",
-    "tui": "node scripts/run-node.mjs tui",
-    "tui:dev": "TASKMASTER_PROFILE=dev node scripts/run-node.mjs tui",
-    "taskmaster:rpc": "node scripts/run-node.mjs agent --mode rpc --json",
-    "lint": "oxlint --type-aware src test",
-    "lint:fix": "pnpm format:fix && oxlint --type-aware --fix src test",
-    "format": "oxfmt --check src test",
-    "format:fix": "oxfmt --write src test",
-    "test": "node scripts/test-parallel.mjs",
-    "test:watch": "vitest",
-    "test:ui": "pnpm --dir ui test",
-    "test:force": "node --import tsx scripts/test-force.ts",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:live": "TASKMASTER_LIVE_TEST=1 vitest run --config vitest.live.config.ts",
-    "test:docker:onboard": "bash scripts/e2e/onboard-docker.sh",
-    "test:docker:gateway-network": "bash scripts/e2e/gateway-network-docker.sh",
-    "test:docker:live-models": "bash scripts/test-live-models-docker.sh",
-    "test:docker:live-gateway": "bash scripts/test-live-gateway-models-docker.sh",
-    "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
-    "test:docker:doctor-switch": "bash scripts/e2e/doctor-install-switch-docker.sh",
-    "test:docker:plugins": "bash scripts/e2e/plugins-docker.sh",
-    "test:docker:cleanup": "bash scripts/test-cleanup-docker.sh",
-    "test:docker:all": "pnpm test:docker:live-models && pnpm test:docker:live-gateway && pnpm test:docker:onboard && pnpm test:docker:gateway-network && pnpm test:docker:qr && pnpm test:docker:doctor-switch && pnpm test:docker:plugins && pnpm test:docker:cleanup",
-    "test:all": "pnpm lint && pnpm build && pnpm test && pnpm test:e2e && pnpm test:live && pnpm test:docker:all",
-    "test:install:e2e": "bash scripts/test-install-sh-e2e-docker.sh",
-    "test:install:smoke": "bash scripts/test-install-sh-docker.sh",
-    "test:install:e2e:openai": "TASKMASTER_E2E_MODELS=openai bash scripts/test-install-sh-e2e-docker.sh",
-    "test:install:e2e:anthropic": "TASKMASTER_E2E_MODELS=anthropic bash scripts/test-install-sh-e2e-docker.sh",
-    "protocol:gen": "node --import tsx scripts/protocol-gen.ts",
-    "protocol:check": "pnpm protocol:gen && git diff --exit-code -- dist/protocol.schema.json",
-    "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh",
-    "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500"
   }
-}
+}

package/taskmaster-docs/USER-GUIDE.md

@@ -137,7 +137,7 @@ After setup, you'll see a navigation bar at the top of the screen linking to all
 | **Setup** | Check connection status, reconnect services, link WhatsApp, manage API keys, toggle public messages |
 | **Chat** | Talk to your admin assistant directly — the preferred way to manage your business |
 | **Admins** | Choose which phone numbers get admin access (see "Two Assistants" below) |
-| **Customers** | Manage verified customer records (payment status, account details) that your assistant can look up but not change |
+| **Contacts** | Manage verified contact records (payment status, account details) that your assistant can look up but not change |
 | **Files** | Browse and manage your assistant's knowledge files and memory |
 | **Browser** | See what the assistant sees when it browses the web for you |
 | **Advanced** | View events (automated tasks), sessions, skills, and logs |