crawlforge-mcp-server 6.0.0 → 6.2.0

package/src/tools/advanced/batchScrape/index.js

@@ -83,41 +83,51 @@ export class BatchScrapeTool extends EventEmitter {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     try {
       const validated = BatchScrapeSchema.parse(params);
-      this.stats.totalBatches++;
       const batchId = this._generateBatchId();
-      const startTime = Date.now();
-
-      this._log('info', `Starting batch scrape ${batchId} with ${validated.urls.length} URLs in ${validated.mode} mode`);
-
-      const urlConfigs = this._normalizeUrlConfigs(validated.urls, validated);
 
-      let webhookConfig = null;
-      if (validated.webhook && this.enableWebhookNotifications) {
-        webhookConfig = this._registerWebhook(validated.webhook, batchId);
-      }
-
-      // D1.4: Elicitation — warn when batch is large in sync mode
-      if (validated.mode === 'sync' && urlConfigs.length > 25) {
-        const proceed = await this._elicitation.confirm(
-          `batch_scrape (sync mode) will fetch ${urlConfigs.length} URLs synchronously. This may take a while and consume significant credits.`,
+      // D1.4: Elicitation — warn when batch is large in sync mode. An
+      // unanswered gate returns an input-required result the SDK answers by
+      // re-entering this handler from the top, so it runs before anything that
+      // leaves a trace: below it are the batch counter and the webhook
+      // registration, which a second entry would repeat (a second webhook
+      // registration for one batch). The count comes from validated.urls,
+      // which _normalizeUrlConfigs maps one-for-one.
+      if (validated.mode === 'sync' && validated.urls.length > 25) {
+        const gate = this._elicitation.confirm(
+          ctx,
+          'batch_scrape:large_sync',
+          `batch_scrape (sync mode) will fetch ${validated.urls.length} URLs synchronously. This may take a while and consume significant credits.`,
           {
-            url_count: urlConfigs.length,
+            url_count: validated.urls.length,
             mode: 'sync',
             suggestion: 'Consider using mode:"async" for large batches.',
           }
         );
-        if (!proceed) {
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
           return {
             batchId, mode: 'sync', success: false,
             error: 'Batch scrape cancelled by user (elicitation declined).',
-            totalUrls: urlConfigs.length,
+            totalUrls: validated.urls.length,
           };
         }
       }
 
+      this.stats.totalBatches++;
+      const startTime = Date.now();
+
+      this._log('info', `Starting batch scrape ${batchId} with ${validated.urls.length} URLs in ${validated.mode} mode`);
+
+      const urlConfigs = this._normalizeUrlConfigs(validated.urls, validated);
+
+      let webhookConfig = null;
+      if (validated.webhook && this.enableWebhookNotifications) {
+        webhookConfig = this._registerWebhook(validated.webhook, batchId);
+      }
+
       if (validated.mode === 'sync') {
         return await this._processBatchSync(batchId, urlConfigs, validated, webhookConfig, startTime);
       } else {

package/src/tools/agent/agent.js

@@ -35,16 +35,21 @@ export class AgentTool {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     const validated = AgentInputSchema.parse(params);
 
-    // Request confirmation before a pro run (expensive)
+    // Request confirmation before a pro run (expensive). An unanswered gate
+    // returns an input-required result the SDK answers by re-entering this
+    // handler from the top, so nothing above it may fetch or leave a trace.
     if (validated.model === 'pro') {
-      const proceed = await this._elicitation.confirm(
+      const gate = this._elicitation.confirm(
+        ctx,
+        'agent:pro_model',
         'agent tool: pro model uses ResearchOrchestrator and may incur significant costs.',
         { model: 'pro', maxUrls: validated.maxUrls, note: 'External LLM API costs billed separately if keys are set.' }
       );
-      if (!proceed) {
+      if (gate.status === 'ask') return gate.result;
+      if (gate.status === 'cancelled') {
         return {
           success: false,
           cancelled: true,

package/src/tools/crawl/crawlDeep.js

@@ -117,7 +117,7 @@ export class CrawlDeepTool {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     try {
       const validated = CrawlDeepSchema.parse(params);
 
@@ -147,9 +147,14 @@ export class CrawlDeepTool {
         if (cached) return { ...cached, cached: true };
       }
 
-      // D1.4: Elicitation — warn when max_pages is very high
+      // D1.4: Elicitation — warn when max_pages is very high. An unanswered
+      // gate returns an input-required result the SDK answers by re-entering
+      // this handler from the top; everything above is the clamp arithmetic and
+      // a cache read, so a second entry fetches nothing and leaves no trace.
       if (effectiveMaxPages > 500) {
-        const proceed = await this._elicitation.confirm(
+        const gate = this._elicitation.confirm(
+          ctx,
+          'crawl_deep:max_pages',
           `crawl_deep will crawl up to ${effectiveMaxPages} pages from ${validated.url}. Large crawls consume many credits.`,
           {
             url: validated.url,
@@ -157,7 +162,8 @@ export class CrawlDeepTool {
             max_depth: effectiveMaxDepth,
           }
         );
-        if (!proceed) {
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
           return {
             success: false,
             error: 'Crawl cancelled by user (elicitation declined).',

package/src/tools/extract/extractStructured.js

@@ -174,36 +174,78 @@ export class ExtractStructuredTool {
    * @param {Object} params - Extraction parameters
    * @returns {Promise<Object>} Extraction result
    */
-  async execute(params) {
+  async execute(params, ctx) {
     const startTime = Date.now();
 
     try {
       const validated = ExtractStructuredSchema.parse(params);
       const { url, schema, prompt, llmConfig, fallbackToSelectors, selectorHints, respect_robots, user_agent, verify_numbers } = validated;
 
-      // Step 1: Fetch and parse — shared helper strips scripts/styles/iframes/svgs
-      const { html, $, textContent, warnings } = await fetchAndParse(url, {
-        userAgent: user_agent || this.userAgent,
-        respectRobots: respect_robots,
-        tool: 'extract_structured'
-      });
-
-      // What the model reads — see shownText().
-      const shown = shownText($, html, url, textContent);
-
-      // Step 3: Try LLM extraction first
       let extractionResult = null;
       let extractionMethod = 'llm';
       let llmErrorMessage = null;
       let llmAvailable = false;
+      let llm = null;
 
+      // Step 0: LLM readiness, resolved before the fetch so the D1.4 gate below
+      // can ask before any network work — an unanswered gate returns an
+      // input-required result the SDK answers by re-entering this handler from
+      // the top, and everything above the gate runs a second time.
       try {
-        const llm = this._ensureLLMManager(llmConfig || {});
+        llm = this._ensureLLMManager(llmConfig || {});
         // ready() probes Ollama, which has no API key to gate on. isAvailable()
         // alone reported false on any machine without a cloud key, so a running
         // local Ollama was never used.
         llmAvailable = await llm.ready();
-        if (llmAvailable) {
+      } catch (llmError) {
+        // No usable LLM — this falls through to the CSS fallback. Keep the
+        // message so callers can tell "LLM broken" apart from "no LLM
+        // configured".
+        llmErrorMessage = llmError.message;
+      }
+
+      // D1.4: no LLM configured and the schema demands more than 3 required
+      // fields — confirm before running the lower-fidelity CSS fallback. With
+      // no LLM, step 3 extracts nothing, so landing on that fallback is already
+      // settled here, before the page is fetched.
+      const requiredCount = (schema.required || []).length;
+      if (fallbackToSelectors !== false && !llmAvailable && requiredCount > 3) {
+        const gate = this._elicitation.confirm(
+          ctx,
+          'extract_structured:no_llm_required_fields',
+          `No LLM provider is configured and the requested schema has ${requiredCount} required fields. ` +
+          `extract_structured will fall back to lower-fidelity CSS selector extraction, which may miss required fields.`,
+          { url, required_fields: requiredCount }
+        );
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
+          return {
+            success: false,
+            url,
+            data: {},
+            extraction_method: 'none',
+            confidence: 0,
+            schema_used: schema,
+            processingTime: Date.now() - startTime,
+            error: 'Extraction cancelled by user (elicitation declined).',
+            validation: { valid: false, errors: ['Extraction cancelled by user (elicitation declined).'] }
+          };
+        }
+      }
+
+      // Step 1: Fetch and parse — shared helper strips scripts/styles/iframes/svgs
+      const { html, $, textContent, warnings } = await fetchAndParse(url, {
+        userAgent: user_agent || this.userAgent,
+        respectRobots: respect_robots,
+        tool: 'extract_structured'
+      });
+
+      // What the model reads — see shownText().
+      const shown = shownText($, html, url, textContent);
+
+      // Step 3: Try LLM extraction first (readiness resolved in step 0)
+      if (llmAvailable) {
+        try {
           const result = await llm.extractStructured(shown, schema, {
             prompt: prompt || '',
             maxContentLength: SHOWN_TEXT_BUDGET
@@ -218,12 +260,11 @@ export class ExtractStructuredTool {
           } else {
             llmErrorMessage = result?.error || 'LLM did not return usable JSON';
           }
+        } catch (llmError) {
+          // LLM failed — will fall through to CSS fallback.
+          extractionResult = null;
+          llmErrorMessage = llmError.message;
         }
-      } catch (llmError) {
-        // LLM failed — will fall through to CSS fallback. Keep the message so
-        // callers can tell "LLM broken" apart from "no LLM configured".
-        extractionResult = null;
-        llmErrorMessage = llmError.message;
       }
 
       // Step 3b (3.4): numeric provenance. Only the LLM path invents numbers —
@@ -318,31 +359,9 @@ export class ExtractStructuredTool {
         if (guarded.checked.skipped) provenance.skipped = guarded.checked.skipped;
       }
 
-      // Step 4: CSS selector fallback if LLM unavailable or failed
+      // Step 4: CSS selector fallback if LLM unavailable or failed (the D1.4
+      // confirmation for this path is gated above, before the fetch)
       if (!extractionResult && fallbackToSelectors !== false) {
-        // D1.4: no LLM configured and the schema demands more than 3 required
-        // fields — confirm before running the lower-fidelity CSS fallback.
-        const requiredCount = (schema.required || []).length;
-        if (!llmAvailable && requiredCount > 3) {
-          const proceed = await this._elicitation.confirm(
-            `No LLM provider is configured and the requested schema has ${requiredCount} required fields. ` +
-            `extract_structured will fall back to lower-fidelity CSS selector extraction, which may miss required fields.`,
-            { url, required_fields: requiredCount }
-          );
-          if (!proceed) {
-            return {
-              success: false,
-              url,
-              data: {},
-              extraction_method: 'none',
-              confidence: 0,
-              schema_used: schema,
-              processingTime: Date.now() - startTime,
-              error: 'Extraction cancelled by user (elicitation declined).',
-              validation: { valid: false, errors: ['Extraction cancelled by user (elicitation declined).'] }
-            };
-          }
-        }
         extractionResult = this._cssExtraction($, schema, selectorHints || {});
         extractionMethod = 'css_fallback';
       }

package/src/tools/research/deepResearch.js

@@ -115,7 +115,7 @@ export class DeepResearchTool {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     try {
       const validated = DeepResearchSchema.parse(params);
       const sessionId = this.generateSessionId();
@@ -137,10 +137,15 @@ export class DeepResearchTool {
       }
 
       // D1.4: Elicitation — warn user if projected cost exceeds 50 credits
-      // deep_research costs approximately 1 credit per URL; maxUrls > 50 → confirm
+      // deep_research costs approximately 1 credit per URL; maxUrls > 50 → confirm.
+      // An unanswered gate returns an input-required result the SDK answers by
+      // re-entering this handler from the top, so it sits above the session
+      // registration below — a second entry would otherwise leak a session.
       if (validated.maxUrls > 50) {
         const projectedCredits = validated.maxUrls;
-        const proceed = await this._elicitation.confirm(
+        const gate = this._elicitation.confirm(
+          ctx,
+          'deep_research:max_urls',
           `deep_research will scan up to ${validated.maxUrls} URLs, projecting ~${projectedCredits} credits.`,
           {
             topic: validated.topic,
@@ -148,7 +153,8 @@ export class DeepResearchTool {
             max_urls: validated.maxUrls,
           }
         );
-        if (!proceed) {
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
           return {
             success: false,
             error: 'Research cancelled by user before starting (elicitation declined).',

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