crawlforge-mcp-server 6.1.0 → 6.3.0

package/src/schemas/toolOutputSchemas.js

@@ -332,7 +332,7 @@ const searchWebShape = {
 // ── extract_structured ───────────────────────────────────────────────────────
 
 const extractStructuredShape = {
-  success: z.boolean().optional().describe('False when the extraction errored or a required field came back missing or empty'),
+  success: z.boolean().optional().describe('False when the extraction errored, or a required field came back missing, empty, or in the wrong shape'),
   url: z.string().optional(),
   data: z.record(z.unknown()).optional().describe('Extracted fields matching the requested schema'),
   extraction_method: z.string().optional().describe('"llm" | "css_fallback" | "keyword_fallback" | "none"'),

package/src/skills/agent-skills/crawlforge-change-tracking/SKILL.md

@@ -68,7 +68,14 @@ CLI: `crawlforge track https://example.com --selector ".price" --threshold 1`.
 
 ## Scheduled monitoring & notifications
 
-Run continuous monitoring with webhooks instead of polling manually:
+`create_scheduled_monitor` repeats `compare` on a schedule and notifies on
+change. It comes in two kinds.
+
+**Local** (default): persisted in `~/.crawlforge/monitors/`; fires in-process
+only while this MCP server runs (missed runs catch up on restart; `crawlforge
+monitor:run-due` from system cron guarantees firing). Notifies by webhook or
+Slack — never email. `goal` (plain-English LLM judge) and
+`notificationThreshold` apply to local monitors only.
 
 ```json
 {
@@ -76,19 +83,47 @@ Run continuous monitoring with webhooks instead of polling manually:
   "params": {
     "url": "https://example.com/pricing",
     "operation": "create_scheduled_monitor",
-    "monitoringOptions": {
-      "enabled": true,
-      "interval": 300000,
-      "notificationThreshold": "moderate",
-      "enableWebhook": true,
-      "webhookUrl": "https://my-site.com/notify"
+    "scheduledMonitorOptions": { "interval": 1800000, "notificationThreshold": "moderate" },
+    "notificationOptions": { "webhook": { "enabled": true, "url": "https://my-site.com/notify" } }
+  }
+}
+```
+
+**Hosted** (`scheduledMonitorOptions.hosted: true`): registered with
+CrawlForge's hosted monitors API under your API key; nothing is created locally
+and this process never fetches the page. CrawlForge's own scheduler runs every
+check whether or not this process is alive, records it, and notifies by email
+and signed webhook on every changed, new, blocked or errored page. Passing
+`goal` or `notificationThreshold` adds a `warnings` entry.
+
+```json
+{
+  "tool": "track_changes",
+  "params": {
+    "url": "https://example.com/pricing",
+    "operation": "create_scheduled_monitor",
+    "trackingOptions": { "customSelectors": [".price"] },
+    "scheduledMonitorOptions": { "hosted": true, "interval": 21600000 },
+    "notificationOptions": {
+      "email": { "enabled": true, "recipients": ["you@example.com"] },
+      "webhook": { "enabled": true, "url": "https://my-site.com/notify" }
     }
   }
 }
 ```
 
-CLI (runs until Ctrl+C):
-`crawlforge monitor https://example.com --interval 60 --webhook https://my-site.com/notify`.
+Hosted mapping: each `customSelectors` entry becomes a target selector on the
+URL; `schedule` (cron) passes through, otherwise `interval` becomes a cron of
+5–60 minutes dividing 60, whole hours dividing 24, or daily — other values
+round to the nearest and `warnings` says what they became. Up to 5 email
+recipients. `webhook.signingSecret` (16–128 chars) becomes the webhook secret;
+omit it and the response returns a generated `webhookSecret`. The response's
+`monitor` carries the hosted `id`, `nextRunAt`, `estimatedCreditsPerMonth` and
+a `dashboardUrl` for managing it.
+
+CLI: `crawlforge monitor:create <url> --every 1800 --webhook <url>` (local) or
+`crawlforge monitor:create <url> --hosted --email you@example.com` (hosted);
+`monitor:list` shows both kinds and `monitor:stop <id>` removes either.
 
 ## Other operations
 
@@ -99,10 +134,12 @@ CLI (runs until Ctrl+C):
 | `monitor` | One monitoring pass. |
 | `get_history` | Retrieve past change records (`queryOptions`). |
 | `get_stats` | Summary statistics for a tracked URL. |
-| `create_scheduled_monitor` / `stop_scheduled_monitor` | Manage cron-style monitors. |
+| `create_scheduled_monitor` | Recurring `compare` + notify; local by default, `scheduledMonitorOptions.hosted: true` for a CrawlForge-run monitor (see above). |
+| `list_scheduled_monitors` | Local monitors (`hosted: false`) then hosted ones (`hosted: true`), with `localCount`/`hostedCount`; `hostedError` if the website is unreachable. |
+| `stop_scheduled_monitor` | By `scheduledMonitorOptions.monitorId`: stops a local monitor, or deletes the hosted one with that id. By `url` alone: stops every local monitor on it and deletes hosted monitors whose targets are all that exact URL. |
 | `get_dashboard` | Aggregate status, recent alerts, trends. |
 | `export_history` | Export change history as `json` or `csv`. |
-| `create_alert_rule` | Conditional alerts (webhook / email / slack). |
+| `create_alert_rule` | Conditional alerts fired from `compare` (webhook / slack; the email action is not sent by a local process — use a hosted monitor for email). |
 | `generate_trend_report` | Trend analysis over time. |
 | `get_monitoring_templates` | List built-in monitoring presets. |
 
@@ -111,6 +148,8 @@ against the baseline without re-fetching.
 
 ## Cost note
 
-`track_changes` = 3 credits per call. A typical watch is one `create_baseline`
-plus periodic `compare` calls; scheduled monitors run server-side and notify via
-webhook/Slack so you don't pay for manual polling loops.
+`track_changes` = 3 credits per call, except that creating a hosted monitor or
+stopping a hosted-only one charges 0 (3 is the projected ceiling). A typical
+watch is one `create_baseline` plus periodic `compare` calls, or one scheduled
+monitor. Each hosted check bills 3 credits per compared target to your account;
+blocked and errored targets are free.

package/src/tools/extract/extractStructured.js

@@ -12,6 +12,7 @@ import { CRAWLFORGE_USER_AGENT } from '../../utils/fetchIdentity.js';
 import { fetchAndParse, flattenBodyText } from './_fetchAndParse.js';
 import { extractMainContent } from '../scrape/_mainContent.js';
 import { verifyNumericProvenance } from '../../utils/provenance.js';
+import { validateAgainstSchema, validateFieldsAgainstSchema } from '../../utils/schemaValidate.js';
 
 // Semantic element selectors for well-known field names, tried as a last
 // resort in the CSS fallback so common fields (e.g. "title") still resolve when
@@ -394,7 +395,21 @@ export class ExtractStructuredTool {
       const missingRequired = (schema.required || []).filter(
         (field) => isEmptyValue((extractionResult.data || {})[field])
       );
-      const failedRequired = extractionResult.valid !== true && missingRequired.length > 0;
+      // Same reasoning for a required field that arrived in the wrong shape:
+      // `{countries: ["a stray line of page text"]}` for an array of objects
+      // is a failed extraction too, and it is neither missing nor empty, so
+      // the check above waves it through (R19). Re-validated per field rather
+      // than parsed out of the error strings.
+      const invalidRequired = extractionResult.valid !== true
+        ? (schema.required || []).filter((field) => {
+            if (missingRequired.includes(field)) return false;
+            const fieldSchema = schema.properties?.[field];
+            if (!fieldSchema) return false;
+            return validateAgainstSchema((extractionResult.data || {})[field], fieldSchema).valid !== true;
+          })
+        : [];
+      const failedRequired = extractionResult.valid !== true
+        && (missingRequired.length > 0 || invalidRequired.length > 0);
 
       return {
         success: !failedRequired,
@@ -405,7 +420,12 @@ export class ExtractStructuredTool {
         schema_used: schema,
         processingTime: Date.now() - startTime,
         ...(failedRequired
-          ? { error: `Required field(s) missing or empty: ${missingRequired.join(', ')}` }
+          ? {
+              error: `Required field(s) ${[
+                missingRequired.length ? `missing or empty: ${missingRequired.join(', ')}` : '',
+                invalidRequired.length ? `wrong shape: ${invalidRequired.join(', ')}` : ''
+              ].filter(Boolean).join('; ')}`
+            }
           : {}),
         validation: {
           valid: extractionResult.valid || false,
@@ -566,18 +586,15 @@ export class ExtractStructuredTool {
       return null; // No fields found via CSS, let keyword fallback handle it
     }
 
-    // Validate required fields
-    const errors = [];
-    const required = schema.required || [];
-    for (const field of required) {
-      if (!(field in extracted)) {
-        errors.push(`Missing required field: ${field}`);
-      }
-    }
+    // Validate the extracted fields. This used to check only that each
+    // required key was present, which is why a fallback that swept three
+    // stray <p> elements into an array-of-objects field reported valid: true
+    // (R19) — presence says nothing about shape.
+    const { valid, errors } = validateFieldsAgainstSchema(extracted, schema);
 
     return {
       data: extracted,
-      valid: errors.length === 0,
+      valid,
       validationErrors: errors,
       extractionNotes: ['Used CSS selector fallback extraction']
     };

package/src/tools/extract/extractWithLlm.js

@@ -7,11 +7,11 @@
  * Pass provider: "openai" | "anthropic" with the matching API key to use a cloud model.
  */
 
-import { z } from 'zod';
 import { fetchAndParse } from './_fetchAndParse.js';
 import { ollamaBaseUrl, ollamaHeaders, selectOllamaModel } from '../../utils/ollamaConfig.js';
 import { verifyNumericProvenance } from '../../utils/provenance.js';
 import { extractionFormat } from '../../utils/extractionFormat.js';
+import { validateAgainstSchema } from '../../utils/schemaValidate.js';
 import { fenceUntrusted } from '../../utils/untrustedContent.js';
 // D1.3: SamplingClient for MCP sampling fallback (lazy — only imported if needed)
 let _SamplingClient = null;
@@ -173,48 +173,6 @@ function buildInputSchema(schema) {
   return format === 'json' ? { type: 'object', properties: {}, additionalProperties: true } : format;
 }
 
-/**
- * Build a zod validator from a JSON-Schema-like hint. Best-effort: unknown
- * shapes fall back to `z.any()` so validation never rejects on constructs the
- * converter does not understand.
- */
-function jsonSchemaToZod(schema) {
-  if (!schema || typeof schema !== 'object') return z.any();
-
-  // Flat hint map (no `type`/`properties`) → treat values as field hints.
-  const isJsonSchema = schema.type || schema.properties || schema.items;
-  if (!isJsonSchema) {
-    const shape = {};
-    for (const [key, val] of Object.entries(schema)) {
-      shape[key] = jsonSchemaToZod(typeof val === 'string' ? { type: val } : val).nullable().optional();
-    }
-    return z.object(shape).passthrough();
-  }
-
-  switch (schema.type) {
-    case 'string': return z.string();
-    case 'number':
-    case 'integer': return z.number();
-    case 'boolean': return z.boolean();
-    case 'null': return z.null();
-    case 'array': return z.array(schema.items ? jsonSchemaToZod(schema.items) : z.any());
-    case 'object': {
-      const shape = {};
-      const required = Array.isArray(schema.required) ? schema.required : [];
-      for (const [key, val] of Object.entries(schema.properties || {})) {
-        const field = jsonSchemaToZod(val);
-        // The model is told to answer null for a field the content never
-        // states, so null is the honest answer for a field the schema does
-        // not require — not a type violation. A required field stays strict:
-        // null there is exactly what the caller needs to hear about.
-        shape[key] = required.includes(key) ? field : field.nullable().optional();
-      }
-      return z.object(shape).passthrough();
-    }
-    default: return z.any();
-  }
-}
-
 /** JSON Schema type keywords, used to spot a type declaration posing as a value. */
 const SCHEMA_TYPE_KEYWORDS = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array', 'null']);
 
@@ -281,25 +239,6 @@ function hasNoExtractableData(parsed) {
   return Object.values(parsed).every(hasNoExtractableData);
 }
 
-/**
- * Validate parsed output against the schema hint.
- * @returns {{ valid: boolean, errors: string[] }}
- */
-function validateAgainstSchema(parsed, schema) {
-  try {
-    const validator = jsonSchemaToZod(schema);
-    const result = validator.safeParse(parsed);
-    if (result.success) return { valid: true, errors: [] };
-    return {
-      valid: false,
-      errors: result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
-    };
-  } catch {
-    // Converter failure should not block extraction — treat as unvalidated.
-    return { valid: true, errors: [] };
-  }
-}
-
 // ── OpenAI call ───────────────────────────────────────────────────────────────
 
 async function callOpenAI({ apiKey, model, systemMessage, userMessage, maxTokens }) {

package/src/tools/research/deepResearch.js

@@ -451,8 +451,9 @@ export class DeepResearchTool {
    * Format research results according to output preferences
    */
   formatResults(results, params) {
-    // Raw evidence mode (no LLM configured): apply lightweight formatting so
-    // outputFormat is not silently ignored, and rank sources by credibility.
+    // Raw evidence mode (no LLM configured, or the token budget ran out
+    // mid-run): apply lightweight formatting so outputFormat is not silently
+    // ignored, and rank sources by credibility. `results.note` says which.
     if (results.synthesisMode === 'raw_evidence') {
       const rankedSources = (results.sources || [])
         .slice()

package/src/tools/tracking/trackChanges/hosted.js

@@ -0,0 +1,176 @@
+/**
+ * TrackChanges — hosted monitors (Phase 6.1).
+ *
+ * `scheduledMonitorOptions.hosted: true` registers a monitor with the
+ * website's /api/v1/monitors instead of the local MonitorStore. The website's
+ * cron then fetches, compares, bills the account and sends the notifications
+ * (email, signed webhooks), so the monitor fires whether or not this process
+ * is alive. This module is the thin client; index.js decides when to use it
+ * and shapes the tool results.
+ *
+ * These calls go to our own configured backend (AuthManager.apiEndpoint, from
+ * CRAWLFORGE_API_URL through endpointGuard), not to a caller-supplied URL, so
+ * they use bare fetch with the X-API-Key header exactly as AuthManager does.
+ * The SSRF guard is for pages a caller names; the endpoint is legitimately
+ * localhost in development.
+ */
+import authManager from '../../../core/AuthManager.js';
+
+const HOSTED_TIMEOUT_MS = 30_000;
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+
+export const HOSTED_FIRING_GUARANTEE_NOTE =
+  "Runs from CrawlForge's scheduler whether or not this process is alive. Each check bills " +
+  '3 credits per compared target from the account; blocked and errored targets are free.';
+
+export const NO_KEY_MESSAGE =
+  'hosted monitors need a CrawlForge API key — run `crawlforge-setup` or `crawlforge login`';
+
+/**
+ * The endpoint and key the hosted calls authenticate with, from the sources
+ * the server and the CLI already use: CRAWLFORGE_API_KEY (the CLI's preAction
+ * hook fills it from --api-key or the stored config), then the key AuthManager
+ * loaded at startup, then the stored config read directly — the server skips
+ * loading it in creator mode, and a hosted monitor is billed to an account
+ * either way. No network: initialize() would re-validate the key.
+ */
+export async function resolveHostedCredentials() {
+  let apiKey = process.env.CRAWLFORGE_API_KEY || authManager.getConfig()?.apiKey;
+  if (!apiKey) {
+    try {
+      await authManager.loadConfig();
+      apiKey = authManager.getConfig()?.apiKey;
+    } catch {
+      /* no stored config */
+    }
+  }
+  if (!apiKey) throw new Error(NO_KEY_MESSAGE);
+  return { endpoint: authManager.apiEndpoint, apiKey };
+}
+
+// resolveApiEndpoint keeps a trailing slash on the configured endpoint; joined
+// to an absolute path that is `//api/...`, a redirect on every call and a
+// dashboard link with a double slash.
+const base = (endpoint) => String(endpoint).replace(/\/+$/, '');
+
+async function request(method, pathname, creds, body) {
+  const response = await fetch(`${base(creds.endpoint)}${pathname}`, {
+    method,
+    headers: {
+      'X-API-Key': creds.apiKey,
+      ...(body ? { 'Content-Type': 'application/json' } : {})
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(HOSTED_TIMEOUT_MS)
+  });
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+    /* no JSON body */
+  }
+  if (!response.ok) {
+    // `{ error: { code, message, details? } }` from the monitors API; the
+    // API-key middleware's 401 is the same envelope. The website's own words
+    // reach the caller so a validation or robots refusal is readable.
+    const err = payload?.error;
+    const code = err?.code || `HTTP_${response.status}`;
+    const message = (typeof err === 'string' ? err : err?.message) || response.statusText || 'request failed';
+    const details = err?.details !== undefined ? ` ${JSON.stringify(err.details)}` : '';
+    const failure = new Error(`${code}: ${message}${details}`);
+    failure.code = code;
+    failure.status = response.status;
+    throw failure;
+  }
+  return payload?.data;
+}
+
+export function createHostedMonitor(input, creds) {
+  return request('POST', '/api/v1/monitors', creds, input);
+}
+
+export async function listHostedMonitors(creds) {
+  // An account holds at most 50 monitors, so one page is the whole list.
+  return (await request('GET', '/api/v1/monitors?limit=100', creds)) ?? [];
+}
+
+export function deleteHostedMonitor(id, creds) {
+  return request('DELETE', `/api/v1/monitors/${encodeURIComponent(id)}`, creds);
+}
+
+// The cron slots the website accepts: consecutive runs at least 5 minutes
+// apart. For a `*/N` minute step that means N must divide 60 (`*/7` has a
+// 4-minute gap at the top of every hour); for an hour step, H must divide 24.
+const SLOTS = [
+  ...[5, 6, 10, 12, 15, 20, 30].map((m) => ({ ms: m * MINUTE, cron: `*/${m} * * * *` })),
+  { ms: HOUR, cron: '0 * * * *' },
+  ...[2, 3, 4, 6, 8, 12].map((h) => ({ ms: h * HOUR, cron: `0 */${h} * * *` })),
+  { ms: 24 * HOUR, cron: '0 0 * * *' }
+];
+
+/**
+ * The hosted schedule for a polling interval in ms.
+ * @returns {{ cron: string, effectiveIntervalMs: number, adjusted: boolean }}
+ *   `adjusted` is true when the interval was not an accepted slot and the
+ *   nearest one was used; a tie goes to the longer interval (fewer billed checks).
+ */
+export function intervalToCron(ms) {
+  let best = SLOTS[0];
+  for (const slot of SLOTS) {
+    const d = Math.abs(slot.ms - ms);
+    const bestD = Math.abs(best.ms - ms);
+    if (d < bestD || (d === bestD && slot.ms > best.ms)) best = slot;
+  }
+  return { cron: best.cron, effectiveIntervalMs: best.ms, adjusted: best.ms !== ms };
+}
+
+export function formatInterval(ms) {
+  return ms % HOUR === 0 ? `${ms / HOUR} h` : `${Math.round(ms / MINUTE)} min`;
+}
+
+const parseIso = (iso) => (iso ? Date.parse(iso) || null : null);
+
+export function hostedDashboardUrl(endpoint, id) {
+  return `${base(endpoint)}/dashboard/monitors/${id}`;
+}
+
+/** The `monitor` a hosted create_scheduled_monitor returns. */
+export function createdHostedMonitor(record, endpoint) {
+  return {
+    id: record.id,
+    hosted: true,
+    name: record.name,
+    targets: record.targets,
+    schedule: record.schedule_cron,
+    timezone: record.timezone,
+    notifyEmails: record.notify_emails,
+    webhookUrl: record.webhook_url,
+    webhookSecret: record.webhook_secret,
+    status: record.status,
+    nextRunAt: parseIso(record.next_run_at),
+    estimatedCreditsPerMonth: record.estimated_credits_per_month,
+    dashboardUrl: hostedDashboardUrl(endpoint, record.id)
+  };
+}
+
+/** A hosted monitor as list_scheduled_monitors shows it, beside the local ones. */
+export function listedHostedMonitor(record, endpoint) {
+  const active = record.status === 'active';
+  return {
+    id: record.id,
+    hosted: true,
+    url: record.targets?.[0]?.url,
+    targets: record.targets,
+    name: record.name,
+    schedule: record.schedule_cron,
+    timezone: record.timezone,
+    enabled: active,
+    nextDueAt: parseIso(record.next_run_at),
+    lastCheckAt: parseIso(record.last_check_at),
+    lastCheck: record.last_check ?? null,
+    estimatedCreditsPerMonth: record.estimated_credits_per_month,
+    dashboardUrl: hostedDashboardUrl(endpoint, record.id),
+    scheduled: active
+  };
+}

package/src/tools/tracking/trackChanges/index.js

@@ -21,10 +21,18 @@ import SnapshotManager from '../../../core/SnapshotManager.js';
 import CacheManager from '../../../core/cache/CacheManager.js';
 import { MonitorStore } from '../../../core/MonitorStore.js';
 import { MonitorScheduler } from '../../../core/MonitorScheduler.js';
+import { setActualCost } from '../../../server/requestContext.js';
 import { TrackChangesSchema } from './schema.js';
 import { fetchContent, mergeHistoryData, matchesSignificanceFilter, calculateAverageInterval, calculateSignificanceDistribution } from './differ.js';
 import { performMonitoringCheck, stopMonitor } from './monitor.js';
 import { sendNotifications } from './notifier.js';
+import {
+  HOSTED_FIRING_GUARANTEE_NOTE, createHostedMonitor, createdHostedMonitor, deleteHostedMonitor,
+  formatInterval, intervalToCron, listHostedMonitors, listedHostedMonitor, resolveHostedCredentials
+} from './hosted.js';
+
+// server.js spreads this into the registered inputSchema (G5: one declaration).
+export { TRACK_CHANGES_INPUT_SHAPE } from './schema.js';
 
 export class TrackChangesTool extends EventEmitter {
   constructor(options = {}) {
@@ -42,6 +50,9 @@ export class TrackChangesTool extends EventEmitter {
       enableRealTimeMonitoring: true,
       maxConcurrentMonitors: 50,
       defaultPollingInterval: 300000,
+      // The key and endpoint hosted monitors authenticate with; tests inject
+      // a stub so nothing reads ~/.crawlforge or reaches the website.
+      resolveHostedCredentials,
       ...options
     };
 
@@ -404,6 +415,9 @@ export class TrackChangesTool extends EventEmitter {
         );
       }
     }
+    if (opts.hosted) {
+      return this._createHostedMonitor({ url, opts, preset, trackingOptions, notificationOptions });
+    }
     // Precedence: scheduledMonitorOptions > preset > monitoringOptions. The
     // schema fills monitoringOptions.interval/notificationThreshold with
     // defaults, so they cannot sit above a preset without always winning.
@@ -423,25 +437,127 @@ export class TrackChangesTool extends EventEmitter {
     };
   }
 
+  /**
+   * Hosted (6.1): the website's /api/v1/monitors owns the monitor — its cron
+   * fetches, compares, bills and notifies — so nothing is stored or fetched
+   * here. The interval precedence matches the local path except that
+   * monitoringOptions.interval (schema-defaulted to 5 min) is not consulted:
+   * a hosted check is billed, and the website's own default is hourly.
+   */
+  async _createHostedMonitor({ url, opts, preset, trackingOptions, notificationOptions }) {
+    const creds = await this.options.resolveHostedCredentials();
+    const warnings = [];
+    let scheduleCron = opts.schedule;
+    const interval = opts.interval ?? preset?.frequency;
+    if (!scheduleCron && interval) {
+      const slot = intervalToCron(interval);
+      scheduleCron = slot.cron;
+      if (slot.adjusted) {
+        warnings.push(
+          `interval ${formatInterval(interval)} is not a hosted schedule slot; the monitor runs every ` +
+          `${formatInterval(slot.effectiveIntervalMs)} (${slot.cron}). Hosted runs are at least 5 minutes apart ` +
+          'and divide the hour or the day evenly.'
+        );
+      }
+    }
+    if (opts.goal ?? preset?.goal) {
+      warnings.push('goal is judged by the local goal judge only and is not applied to a hosted monitor, which notifies on every changed, new, blocked or errored page');
+    }
+    if (opts.notificationThreshold) {
+      warnings.push('notificationThreshold has no effect on a hosted monitor; hosted checks have no significance threshold');
+    }
+
+    const tracking = preset ? { ...preset.options, ...(trackingOptions || {}) } : (trackingOptions || {});
+    const selectors = tracking.customSelectors || [];
+    const email = notificationOptions?.email;
+    const webhook = notificationOptions?.webhook;
+    const secret = webhook?.signingSecret;
+    const record = await createHostedMonitor({
+      name: opts.name || new URL(url).host.slice(0, 80),
+      targets: selectors.length ? selectors.map((selector) => ({ url, selector })) : [{ url }],
+      ...(scheduleCron ? { schedule_cron: scheduleCron } : {}),
+      timezone: 'UTC',
+      ...(email?.enabled && email.recipients?.length ? { notify_emails: email.recipients } : {}),
+      ...(webhook?.enabled && webhook.url ? { webhook_url: webhook.url } : {}),
+      // A secret outside 16-128 chars is left out so the website generates one.
+      ...(webhook?.enabled && webhook.url && secret?.length >= 16 && secret.length <= 128 ? { webhook_secret: secret } : {}),
+      status: 'active'
+    }, creds);
+    // Nothing ran on this machine and the monitors API is free (G4).
+    setActualCost(0);
+    return {
+      success: true, operation: 'create_scheduled_monitor', url, hosted: true,
+      ...(preset ? { templateId: preset.id } : {}),
+      monitor: createdHostedMonitor(record, creds.endpoint),
+      firingGuarantee: HOSTED_FIRING_GUARANTEE_NOTE,
+      ...(warnings.length ? { warnings } : {}),
+      timestamp: Date.now()
+    };
+  }
+
   async stopScheduledMonitor(params) {
     const { url, scheduledMonitorOptions } = params;
     const monitorId = scheduledMonitorOptions?.monitorId;
     if (monitorId) {
-      const result = await this.scheduler.stopMonitor(monitorId);
-      if (!result.stopped) {
-        return { success: false, operation: 'stop_scheduled_monitor', monitorId, stopped: false, error: `No scheduled monitor found with id ${monitorId}`, timestamp: Date.now() };
+      if (!this.monitorStore._loaded) await this.monitorStore.load();
+      if (this.monitorStore.get(monitorId)) {
+        await this.scheduler.stopMonitor(monitorId);
+        return { success: true, operation: 'stop_scheduled_monitor', monitorId, stopped: true, timestamp: Date.now() };
       }
-      return { success: true, operation: 'stop_scheduled_monitor', monitorId, stopped: true, timestamp: Date.now() };
+      // Not in the local store: it may be hosted.
+      try {
+        await deleteHostedMonitor(monitorId, await this.options.resolveHostedCredentials());
+      } catch (error) {
+        const reason = error.status === 404 ? '' : ` (hosted lookup failed: ${error.message})`;
+        return { success: false, operation: 'stop_scheduled_monitor', monitorId, stopped: false, error: `No scheduled monitor found with id ${monitorId}${reason}`, timestamp: Date.now() };
+      }
+      // Nothing ran on this machine and the monitors API is free (G4).
+      setActualCost(0);
+      return { success: true, operation: 'stop_scheduled_monitor', monitorId, stopped: true, hosted: true, timestamp: Date.now() };
     }
     if (!url) throw new Error('stop_scheduled_monitor requires a url or scheduledMonitorOptions.monitorId');
     const result = await this.scheduler.stopByUrl(url);
-    return { success: true, operation: 'stop_scheduled_monitor', url, stoppedMonitors: result.stopped, timestamp: Date.now() };
+    // Only a hosted monitor whose every target is this URL — never a
+    // multi-target monitor that merely includes it.
+    let stoppedHosted = 0;
+    let hostedError = null;
+    try {
+      const creds = await this.options.resolveHostedCredentials();
+      for (const m of await listHostedMonitors(creds)) {
+        if (m.targets?.length && m.targets.every((t) => t.url === url)) {
+          await deleteHostedMonitor(m.id, creds);
+          stoppedHosted++;
+        }
+      }
+    } catch (error) {
+      hostedError = error.message;
+    }
+    return {
+      success: true, operation: 'stop_scheduled_monitor', url, stoppedMonitors: result.stopped, stoppedHosted,
+      ...(hostedError ? { hostedError } : {}),
+      timestamp: Date.now()
+    };
   }
 
   async listScheduledMonitors() {
     if (!this.monitorStore._loaded) await this.monitorStore.load();
-    const monitors = this.scheduler.list();
-    return { success: true, operation: 'list_scheduled_monitors', monitors, count: monitors.length, timestamp: Date.now() };
+    const local = this.scheduler.list().map((m) => ({ ...m, hosted: false }));
+    // The local list never fails because the website is unreachable.
+    let hosted = [];
+    let hostedError = null;
+    try {
+      const creds = await this.options.resolveHostedCredentials();
+      hosted = (await listHostedMonitors(creds)).map((r) => listedHostedMonitor(r, creds.endpoint));
+    } catch (error) {
+      hostedError = error.message;
+    }
+    const monitors = [...local, ...hosted];
+    return {
+      success: true, operation: 'list_scheduled_monitors', monitors,
+      count: monitors.length, localCount: local.length, hostedCount: hosted.length,
+      ...(hostedError ? { hostedError } : {}),
+      timestamp: Date.now()
+    };
   }
 
   async getMonitoringDashboard(params) {

package/src/tools/tracking/trackChanges/notifier.js

@@ -79,12 +79,13 @@ export async function sendWebhookNotification(url, changeResult, webhookConfig,
 }
 
 export async function sendEmailNotification(url, changeResult, emailConfig, emitter) {
-  // Email integration placeholder — requires external service
-  emitter?.emit('notificationSent', {
+  // This process has no mail service. Until 6.2.0 this emitted
+  // notificationSent { success: true } for a message that was never sent.
+  // Email is sent by the website's cron for hosted monitors.
+  emitter?.emit('notificationError', {
     type: 'email',
     url,
-    success: true,
-    note: 'Email notifications require external service integration'
+    error: 'Local monitors do not send email; create the monitor with scheduledMonitorOptions.hosted: true (or in the website dashboard) for email notifications'
   });
 }