@ainyc/canonry 5.1.1 → 5.1.3

package/dist/{chunk-ZWVXUPLP.js → chunk-5ZOLPHTO.js}

@@ -15,8 +15,9 @@ import {
   loadConfig,
   loadConfigRaw,
   resolveOperatorApiKeyIds,
+  runWithUsageTags,
   saveConfigPatch
-} from "./chunk-MEQGGODM.js";
+} from "./chunk-AEE5DGTE.js";
 import {
   CC_CACHE_DIR,
   DUCKDB_SPEC,
@@ -167,9 +168,10 @@ import {
   siteCrawlSnapshots,
   toAlertView,
   usageCounters
-} from "./chunk-LHHJVGH7.js";
+} from "./chunk-EBUX3C5H.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
+  AGENT_NONE,
   AGENT_PROVIDER_IDS,
   AI_ENGINE_DOMAINS,
   AI_ENGINE_SELF_DOMAINS,
@@ -177,6 +179,7 @@ import {
   AdsCampaignBiddingTypes,
   AgentProviderIds,
   BacklinkSources,
+  CANONRY_NPM_PACKAGE_URL,
   CITED_URL_CAPTURE_VERSION,
   CcReleaseSyncStatuses,
   DEFAULT_VIEWER_RESEARCH_DAILY_RUN_LIMIT,
@@ -237,6 +240,7 @@ import {
   classifyProviderErrorMessages,
   classifyTemplateLinkEdge,
   cloudflareQueueNameSchema,
+  compareSemver,
   computeBacklinkSummaryMetrics,
   contentActionLabel,
   contentBriefDtoSchema,
@@ -247,6 +251,7 @@ import {
   deriveIndexCoverage,
   deriveSiteHealthState,
   describeError,
+  detectAgentRuntime,
   determineAnswerMentioned,
   dollarsToMicros,
   effectiveBrandNames,
@@ -276,13 +281,16 @@ import {
   isAgentProviderId,
   isBrowserProvider,
   isGhostTelemetryEvent,
+  isInstallMethod,
   isReadOnlyKey,
   isRetryableHttpError,
   isSelfLink,
+  isStrictSemver,
   isVertexGroundingRedirect,
   mapWithConcurrency,
   maskTelemetryAnonymousId,
   nextScheduleUpdatedAt,
+  normalizeAgentSlug,
   normalizeIdTokens,
   normalizeMeasurementExecutionQueryText,
   normalizeServedModel,
@@ -309,10 +317,22 @@ import {
   templateLinkUbiquityAvailable,
   textContainsBrandAlias,
   textContainsDomain,
+  updateCheckEnvOptOut,
+  upgradeCaveatFor,
+  upgradeCommandFor,
+  usageSurfaceSchema,
   validationError,
   winnabilityClassLabel,
   withRetry
-} from "./chunk-3DL3KV6C.js";
+} from "./chunk-MMSPU72Z.js";
+
+// src/runtime-context.ts
+function cliRuntimeContext(env = process.env, stdio = process) {
+  return {
+    agent: detectAgentRuntime(env),
+    interactive: Boolean(stdio.stdin.isTTY && stdio.stdout.isTTY)
+  };
+}
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -343,7 +363,8 @@ function trackCliCommandFinished(input) {
       command: input.command,
       success: input.success,
       duration_bucket: bucketCliCommandDuration(input.durationMs),
-      ...input.setupState ? { setup_state: input.setupState } : {}
+      ...input.setupState ? { setup_state: input.setupState } : {},
+      ...cliRuntimeContext()
     },
     input.errorCode ? { errorCode: input.errorCode } : void 0
   );
@@ -418,7 +439,8 @@ function getOrCreateAnonymousId() {
     try {
       const config = loadConfig();
       if (config.anonymousId) return config.anonymousId;
-      const id = crypto.randomUUID();
+      const carried = preConfigAnonymousId?.configPath === getConfigPath() ? preConfigAnonymousId.id : void 0;
+      const id = carried ?? crypto.randomUUID();
       config.anonymousId = id;
       try {
         saveConfigPatch(config);
@@ -430,8 +452,11 @@ function getOrCreateAnonymousId() {
       return getDeterministicAnonymousId();
     }
   }
-  return getDeterministicAnonymousId();
+  const fallback = getDeterministicAnonymousId();
+  if (fallback) preConfigAnonymousId = { configPath: getConfigPath(), id: fallback };
+  return fallback;
 }
+var preConfigAnonymousId;
 function readEnvAnonymousId() {
   const raw = process.env[ANON_ID_ENV_VAR]?.trim();
   if (!raw) return void 0;
@@ -506,10 +531,19 @@ function detectAndTrackUpgrade() {
   trackEvent("cli.upgraded", { fromVersion: lastSeen, toVersion: VERSION });
 }
 function trackEvent(event, properties, options) {
-  if (!isTelemetryEnabled()) return;
-  if (shouldDropTelemetryEvent(event, properties)) return;
+  void deliverEvent(event, properties, options);
+}
+function setTelemetryPreference(enabled, method) {
+  loadConfig();
+  const announce = !enabled && isTelemetryEnabled();
+  saveConfigPatch({ telemetry: enabled });
+  return announce ? deliverEvent("telemetry.disabled", { method }, void 0, { preferenceChecked: true }) : Promise.resolve();
+}
+function deliverEvent(event, properties, options, delivery = {}) {
+  if (!delivery.preferenceChecked && !isTelemetryEnabled()) return Promise.resolve();
+  if (shouldDropTelemetryEvent(event, properties)) return Promise.resolve();
   const anonymousId = getOrCreateAnonymousId();
-  if (!anonymousId) return;
+  if (!anonymousId) return Promise.resolve();
   const payload = {
     eventId: options?.eventId ?? crypto.randomUUID(),
     anonymousId,
@@ -529,60 +563,59 @@ function trackEvent(event, properties, options) {
   const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
   timeout.unref();
   try {
-    void fetch(TELEMETRY_ENDPOINT, {
+    return fetch(TELEMETRY_ENDPOINT, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload),
       signal: controller.signal
-    }).catch(() => {
-    }).finally(() => clearTimeout(timeout));
+    }).then(() => void 0, () => void 0).finally(() => clearTimeout(timeout));
   } catch {
     clearTimeout(timeout);
+    return Promise.resolve();
   }
 }
 
 // src/update-check.ts
+import fs from "fs";
 import { createRequire as createRequire2 } from "module";
+import { fileURLToPath } from "url";
 var _require2 = createRequire2(import.meta.url);
 var { version: PKG_VERSION } = _require2("../package.json");
 var PKG_NAME = "@canonry/canonry";
 var NPM_DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${PKG_NAME}/dist-tags`;
-var NPM_PACKAGE_URL = `https://www.npmjs.com/package/${PKG_NAME}`;
+var NPM_PACKAGE_URL = CANONRY_NPM_PACKAGE_URL;
 var FETCH_TIMEOUT_MS = 1500;
-function isUpdateCheckEnabled() {
-  if (process.env.CANONRY_DISABLE_UPDATE_CHECK === "1") return false;
-  if (process.env.DO_NOT_TRACK === "1") return false;
-  if (process.env.CI) return false;
-  if (!configExists()) return true;
+var CONTAINER_MARKERS = ["/.dockerenv", "/run/.containerenv"];
+function detectInstallMethod(opts) {
+  const declared = (opts?.env ?? process.env).CANONRY_INSTALL_METHOD;
+  if (isInstallMethod(declared)) return declared;
+  let modulePath = opts?.modulePath ?? fileURLToPath(import.meta.url);
   try {
-    const raw = loadConfigRaw();
-    return raw?.updateCheck !== false;
+    modulePath = fs.realpathSync(modulePath);
   } catch {
-    return true;
   }
+  if (modulePath.replace(/\\/g, "/").includes("/Cellar/canonry/")) return "homebrew";
+  const exists = opts?.exists ?? fs.existsSync;
+  if (CONTAINER_MARKERS.some((marker) => exists(marker))) return "docker";
+  return "npm";
 }
-function compareSemver(a, b) {
-  const parse = (v) => {
-    const core = v.split(/[-+]/)[0];
-    if (!core) return null;
-    const parts = core.split(".");
-    if (parts.length < 3) return null;
-    const nums = [];
-    for (let i = 0; i < 3; i++) {
-      const n = Number(parts[i]);
-      if (!Number.isInteger(n) || n < 0) return null;
-      nums.push(n);
-    }
-    return [nums[0], nums[1], nums[2]];
-  };
-  const pa = parse(a);
-  const pb = parse(b);
-  if (!pa || !pb) return 0;
-  for (let i = 0; i < 3; i++) {
-    if (pa[i] > pb[i]) return 1;
-    if (pa[i] < pb[i]) return -1;
+var detectedInstallMethod;
+function currentInstallMethod() {
+  detectedInstallMethod ??= detectInstallMethod();
+  return detectedInstallMethod;
+}
+function isUpdateCheckEnabled() {
+  return updateCheckDisabledReason() === null;
+}
+function updateCheckDisabledReason() {
+  const envOptOut = updateCheckEnvOptOut(process.env);
+  if (envOptOut) return envOptOut;
+  if (!configExists()) return null;
+  try {
+    return loadConfigRaw()?.updateCheck === false ? "config" : null;
+  } catch {
+    return null;
   }
-  return 0;
 }
 async function fetchLatestVersion(opts) {
   const controller = new AbortController();
@@ -595,7 +628,7 @@ async function fetchLatestVersion(opts) {
     });
     if (!res.ok) return null;
     const data = await res.json();
-    if (typeof data.latest !== "string") return null;
+    if (typeof data.latest !== "string" || !isStrictSemver(data.latest)) return null;
     return data.latest;
   } catch {
     return null;
@@ -603,13 +636,15 @@ async function fetchLatestVersion(opts) {
     clearTimeout(timeout);
   }
 }
-function buildUpdateAvailable(current, latest) {
+function buildUpdateAvailable(current, latest, installMethod = currentInstallMethod()) {
+  if (!isStrictSemver(latest)) return null;
   if (compareSemver(latest, current) <= 0) return null;
   return {
     current,
     latest,
     url: NPM_PACKAGE_URL,
-    upgradeCommand: `npm install -g ${PKG_NAME}`
+    upgradeCommand: upgradeCommandFor(installMethod),
+    installMethod
   };
 }
 async function checkLatestVersionForCli(opts) {
@@ -647,6 +682,45 @@ async function checkLatestVersionForCli(opts) {
   }
   return buildUpdateAvailable(PKG_VERSION, latest);
 }
+function readCachedUpdateAvailable() {
+  if (!isUpdateCheckEnabled()) return null;
+  if (!configExists()) return null;
+  try {
+    const cachedLatest = loadConfigRaw()?.lastKnownLatestVersion;
+    if (typeof cachedLatest !== "string") return null;
+    return buildUpdateAvailable(PKG_VERSION, cachedLatest);
+  } catch {
+    return null;
+  }
+}
+var UPDATE_AVAILABLE_NOTICE_CODE = "UPDATE_AVAILABLE";
+function formatUpdateNotice(update, opts) {
+  const caveat = upgradeCaveatFor(update.installMethod);
+  if (opts.format === "json" || opts.format === "jsonl") {
+    return `${JSON.stringify({
+      notice: {
+        code: UPDATE_AVAILABLE_NOTICE_CODE,
+        current: update.current,
+        latest: update.latest,
+        installMethod: update.installMethod,
+        upgradeCommand: update.upgradeCommand,
+        url: update.url,
+        ...caveat ? { note: caveat } : {}
+      }
+    })}
+`;
+  }
+  if (opts.interactive) {
+    return `
+\u2192 canonry ${update.latest} is available (you have ${update.current}).
+  Upgrade: ${update.upgradeCommand}
+` + (caveat ? `  ${caveat}
+` : "") + "\n";
+  }
+  const upgrade = update.installMethod === "docker" ? `Upgrade: ${update.upgradeCommand}.` : `Upgrade with \`${update.upgradeCommand}\`, then restart any running \`canonry serve\`.`;
+  return `[canonry] ${UPDATE_AVAILABLE_NOTICE_CODE}: canonry ${update.latest} is available (installed ${update.current}). ${upgrade} ${caveat ? `${caveat} ` : ""}Silence with CANONRY_DISABLE_UPDATE_CHECK=1.
+`;
+}
 var memoryCache = null;
 var inFlight = null;
 function startBackgroundRefresh(getNow) {
@@ -673,6 +747,22 @@ function checkLatestVersionForServer(opts) {
   if (!memoryCache || !memoryCache.latest) return null;
   return buildUpdateAvailable(PKG_VERSION, memoryCache.latest);
 }
+function getServerUpdateStatus(opts) {
+  const installMethod = currentInstallMethod();
+  const base = { current: PKG_VERSION, installMethod, upgradeCommand: upgradeCommandFor(installMethod), url: NPM_PACKAGE_URL };
+  const disabledBy = updateCheckDisabledReason();
+  if (disabledBy) return { ...base, enabled: false, disabledBy, latest: null };
+  checkLatestVersionForServer(opts);
+  let latest = memoryCache?.latest ?? null;
+  if (!latest && configExists()) {
+    try {
+      const cached = loadConfigRaw()?.lastKnownLatestVersion;
+      if (typeof cached === "string") latest = cached;
+    } catch {
+    }
+  }
+  return { ...base, enabled: true, latest: latest && isStrictSemver(latest) ? latest : null };
+}
 
 // src/google-marketing-runtime.ts
 import crypto3 from "crypto";
@@ -3443,9 +3533,9 @@ function createGoogleMarketingRuntime(options) {
 // src/server.ts
 import { createRequire as createRequire4 } from "module";
 import crypto27 from "crypto";
-import fs7 from "fs";
+import fs8 from "fs";
 import path8 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { and as and20, eq as eq26 } from "drizzle-orm";
 import Fastify from "fastify";
 import os4 from "os";
@@ -5366,12 +5456,12 @@ function sleep2(ms) {
 }
 
 // ../provider-cdp/src/screenshot.ts
-import fs from "fs";
+import fs2 from "fs";
 import path from "path";
 async function captureElementScreenshot(client, selector, outputPath) {
   const dir = path.dirname(outputPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
   }
   let clip;
   try {
@@ -5405,7 +5495,7 @@ async function captureElementScreenshot(client, selector, outputPath) {
   }
   const { data } = await client.Page.captureScreenshot(screenshotParams);
   const buffer = Buffer.from(data, "base64");
-  fs.writeFileSync(outputPath, buffer);
+  fs2.writeFileSync(outputPath, buffer);
   return outputPath;
 }
 
@@ -6280,13 +6370,93 @@ function removeWordpressConnection(config, projectName) {
   return true;
 }
 
+// src/usage-telemetry.ts
+var API_REQUEST_BUCKET_CAPACITY = 20;
+var API_REQUEST_REFILL_PER_MS = 1 / 1e4;
+var MAX_TRACKED_MCP_SESSIONS = 2e3;
+var MAX_ROUTE_LENGTH = 200;
+var SKIPPED_ROUTE_PATTERN = /(?:^|\/)(?:health|openapi\.json|telemetry)(?:\/|$)/;
+var MCP_CALL_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var MCP_TOOL_PATTERN = /^[a-z][a-z0-9_]{0,79}$/;
+function classifyUsageSurface(info) {
+  const labelled = usageSurfaceSchema.safeParse(info.usageLabels.surface);
+  if (labelled.success) return labelled.data;
+  const ua = info.userAgent ?? "";
+  if (ua.startsWith("canonry-cli")) return "cli";
+  if (ua.startsWith("canonry-mcp/")) return "mcp-http";
+  if (ua === "canonry-mcp") return "mcp-stdio";
+  if (ua.startsWith("Mozilla/")) return "dashboard";
+  return "api";
+}
+function statusClass(statusCode) {
+  if (statusCode >= 500) return "5xx";
+  if (statusCode >= 400) return "4xx";
+  if (statusCode >= 300) return "3xx";
+  return "2xx";
+}
+function createApiUsageTelemetry(options = {}) {
+  const emit = options.emit ?? trackEvent;
+  const now = options.now ?? Date.now;
+  let tokens = API_REQUEST_BUCKET_CAPACITY;
+  let refilledAt = now();
+  let droppedBefore = 0;
+  const seenSessions = /* @__PURE__ */ new Set();
+  const takeToken = () => {
+    const at = now();
+    tokens = Math.min(API_REQUEST_BUCKET_CAPACITY, tokens + (at - refilledAt) * API_REQUEST_REFILL_PER_MS);
+    refilledAt = at;
+    if (tokens < 1) return false;
+    tokens -= 1;
+    return true;
+  };
+  return (info) => {
+    if (info.method === "OPTIONS" || info.method === "HEAD") return;
+    if (SKIPPED_ROUTE_PATTERN.test(info.route)) return;
+    const surface = classifyUsageSurface(info);
+    if (surface === "cli" || surface === "dashboard") return;
+    const labels = info.usageLabels;
+    const mcpClient = normalizeAgentSlug(labels.mcpClient);
+    const detected = normalizeAgentSlug(labels.agent);
+    const agent = detected && detected !== AGENT_NONE ? detected : mcpClient ?? detected ?? AGENT_NONE;
+    const mcpTool = labels.mcpTool && MCP_TOOL_PATTERN.test(labels.mcpTool) ? labels.mcpTool : void 0;
+    const mcpCallId = labels.mcpCall && MCP_CALL_ID_PATTERN.test(labels.mcpCall) ? labels.mcpCall.toLowerCase() : void 0;
+    const isMcp = surface === "mcp-stdio" || surface === "mcp-http";
+    if (isMcp && mcpTool && info.actorSession && !seenSessions.has(info.actorSession)) {
+      if (seenSessions.size >= MAX_TRACKED_MCP_SESSIONS) {
+        const oldest = seenSessions.values().next().value;
+        if (oldest !== void 0) seenSessions.delete(oldest);
+      }
+      seenSessions.add(info.actorSession);
+      emit("mcp.session.started", { surface, agent, ...mcpClient ? { mcpClient } : {} }, { source: "cli-server" });
+    }
+    if (!takeToken()) {
+      droppedBefore += 1;
+      return;
+    }
+    const properties = {
+      surface,
+      agent,
+      method: info.method,
+      route: info.route.slice(0, MAX_ROUTE_LENGTH),
+      statusClass: statusClass(info.statusCode),
+      durationBucket: bucketCliCommandDuration(info.durationMs),
+      ...mcpClient ? { mcpClient } : {},
+      ...mcpTool ? { mcpTool } : {},
+      ...mcpCallId ? { mcpCallId } : {},
+      ...droppedBefore > 0 ? { droppedBefore } : {}
+    };
+    droppedBefore = 0;
+    emit("api.request", properties, { source: "cli-server" });
+  };
+}
+
 // src/instance-identity.ts
 function nonBlank(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : void 0;
 }
 function resolveBuildCommit(env = process.env) {
-  const embedded = true ? "2c66fea459e20ff285096090dbc6a6ee788c4c00" : void 0;
+  const embedded = true ? "1f10658e1c5f2b615dfbee110d3f8cf68dbfbda9" : void 0;
   return nonBlank(embedded) ?? nonBlank(env.CANONRY_COMMIT);
 }
 function resolveInstanceIdentity(env = process.env) {
@@ -6298,7 +6468,7 @@ function resolveInstanceIdentity(env = process.env) {
 
 // src/job-runner.ts
 import crypto6 from "crypto";
-import fs2 from "fs";
+import fs3 from "fs";
 import path3 from "path";
 import os3 from "os";
 import { and as and2, eq as eq2, inArray, ne, sql as sql2 } from "drizzle-orm";
@@ -6866,12 +7036,12 @@ var JobRunner = class {
               allBrandNames
             );
             let screenshotRelPath = null;
-            if (raw.screenshotPath && fs2.existsSync(raw.screenshotPath)) {
+            if (raw.screenshotPath && fs3.existsSync(raw.screenshotPath)) {
               const snapshotId = crypto6.randomUUID();
               const screenshotDir = path3.join(os3.homedir(), ".canonry", "screenshots", runId);
-              if (!fs2.existsSync(screenshotDir)) fs2.mkdirSync(screenshotDir, { recursive: true });
+              if (!fs3.existsSync(screenshotDir)) fs3.mkdirSync(screenshotDir, { recursive: true });
               const destPath = path3.join(screenshotDir, `${snapshotId}.png`);
-              fs2.renameSync(raw.screenshotPath, destPath);
+              fs3.renameSync(raw.screenshotPath, destPath);
               screenshotRelPath = `${runId}/${snapshotId}.png`;
               this.db.insert(querySnapshots).values({
                 id: snapshotId,
@@ -7024,11 +7194,11 @@ var JobRunner = class {
             );
             const snapshotId = crypto6.randomUUID();
             let screenshotRelPath = null;
-            if (raw.screenshotPath && fs2.existsSync(raw.screenshotPath)) {
+            if (raw.screenshotPath && fs3.existsSync(raw.screenshotPath)) {
               const screenshotDir = path3.join(os3.homedir(), ".canonry", "screenshots", runId);
-              if (!fs2.existsSync(screenshotDir)) fs2.mkdirSync(screenshotDir, { recursive: true });
+              if (!fs3.existsSync(screenshotDir)) fs3.mkdirSync(screenshotDir, { recursive: true });
               const destPath = path3.join(screenshotDir, `${snapshotId}.png`);
-              fs2.renameSync(raw.screenshotPath, destPath);
+              fs3.renameSync(raw.screenshotPath, destPath);
               screenshotRelPath = `${runId}/${snapshotId}.png`;
             }
             this.db.insert(querySnapshots).values({
@@ -9588,7 +9758,7 @@ function computeSummary(rows) {
 
 // src/backlink-extract.ts
 import crypto16 from "crypto";
-import fs3 from "fs";
+import fs4 from "fs";
 import { and as and9, desc as desc5, eq as eq11 } from "drizzle-orm";
 var log11 = createLogger("BacklinkExtract");
 function defaultDeps3() {
@@ -9617,7 +9787,7 @@ async function executeBacklinkExtract(db, runId, projectId, opts = {}) {
     if (!sync.vertexPath || !sync.edgesPath) {
       throw new Error(`Release ${sync.release} is missing cached file paths`);
     }
-    if (!fs3.existsSync(sync.vertexPath) || !fs3.existsSync(sync.edgesPath)) {
+    if (!fs4.existsSync(sync.vertexPath) || !fs4.existsSync(sync.edgesPath)) {
       throw new Error(
         `Cache for release ${sync.release} is missing from disk (expected at ${sync.vertexPath}). The sync record exists in the database, but the ~16 GB dump was deleted or never present on this machine. Re-sync this release from the Backlinks admin page to restore the cache.`
       );
@@ -12212,7 +12382,7 @@ function readStoredGroundingSources(rawResponse) {
   return result;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-7XX5ZRYE.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-25NQCETC.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);
@@ -13947,7 +14117,7 @@ import crypto25 from "crypto";
 import { eq as eq21 } from "drizzle-orm";
 
 // src/agent/session.ts
-import fs6 from "fs";
+import fs7 from "fs";
 import path7 from "path";
 import { Agent } from "@mariozechner/pi-agent-core";
 import { registerBuiltInApiProviders } from "@mariozechner/pi-ai";
@@ -14191,25 +14361,25 @@ function buildAgentProvidersResponse(config) {
 }
 
 // src/agent/skill-paths.ts
-import fs4 from "fs";
+import fs5 from "fs";
 import path5 from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 function resolveAeroSkillDir(pkgDir) {
-  const here = pkgDir ?? path5.dirname(fileURLToPath(import.meta.url));
+  const here = pkgDir ?? path5.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
     path5.join(here, "../assets/agent-workspace/skills/aero"),
     path5.join(here, "../../assets/agent-workspace/skills/aero"),
     path5.join(here, "../../../../skills/aero")
   ];
   for (const candidate of candidates) {
-    if (fs4.existsSync(path5.join(candidate, "SKILL.md"))) return candidate;
+    if (fs5.existsSync(path5.join(candidate, "SKILL.md"))) return candidate;
   }
   throw new Error(`Aero skill not found. Searched:
   ${candidates.join("\n  ")}`);
 }
 
 // src/agent/skill-tools.ts
-import fs5 from "fs";
+import fs6 from "fs";
 import path6 from "path";
 import { Type } from "@sinclair/typebox";
 var MAX_DOC_CHARS = 2e4;
@@ -14232,12 +14402,12 @@ function parseDescription(body) {
 }
 function scanSkillDocs(skillDir) {
   const refsDir = path6.join(skillDir ?? resolveAeroSkillDir(), "references");
-  if (!fs5.existsSync(refsDir)) return [];
+  if (!fs6.existsSync(refsDir)) return [];
   const entries = [];
-  for (const file of fs5.readdirSync(refsDir)) {
+  for (const file of fs6.readdirSync(refsDir)) {
     if (!file.endsWith(".md")) continue;
     const filePath = path6.join(refsDir, file);
-    const body = fs5.readFileSync(filePath, "utf-8");
+    const body = fs6.readFileSync(filePath, "utf-8");
     entries.push({
       slug: file.replace(/\.md$/, ""),
       description: parseDescription(body),
@@ -14281,7 +14451,7 @@ function buildReadSkillDocTool() {
         });
       }
       const filePath = path6.join(skillDir, "references", `${match.slug}.md`);
-      const content = fs5.readFileSync(filePath, "utf-8");
+      const content = fs6.readFileSync(filePath, "utf-8");
       if (content.length > MAX_DOC_CHARS) {
         return textResult({
           slug: match.slug,
@@ -14306,6 +14476,7 @@ import { Type as Type3 } from "@sinclair/typebox";
 
 // src/agent/mcp-to-agent-tool.ts
 import { Type as Type2 } from "@sinclair/typebox";
+import { randomUUID } from "crypto";
 var MAX_TOOL_RESULT_CHARS = 2e4;
 var TRUNCATION_NOTE = "... (truncated \u2014 result too large)";
 function serializeResult(value) {
@@ -14455,7 +14626,7 @@ function mcpToAgentTool(tool, ctx) {
   const parameters = Type2.Unsafe(visibleSchema);
   const execute = async (_toolCallId, params) => {
     const handlerInput = hadProject ? { ...params, project: ctx.projectName } : params;
-    const result = await tool.handler(ctx.client, handlerInput);
+    const result = await runWithUsageTags(ctx.client, { mcpTool: tool.name, mcpCall: randomUUID() }, () => tool.handler(ctx.client, handlerInput));
     return textResult2(result);
   };
   return {
@@ -14941,9 +15112,9 @@ function ensureBuiltinsRegistered() {
 }
 function loadAeroSystemPrompt(pkgDir) {
   const skillDir = resolveAeroSkillDir(pkgDir);
-  const skillBody = fs6.readFileSync(path7.join(skillDir, "SKILL.md"), "utf-8");
+  const skillBody = fs7.readFileSync(path7.join(skillDir, "SKILL.md"), "utf-8");
   const soulPath = path7.join(skillDir, "soul.md");
-  const base = fs6.existsSync(soulPath) ? `${fs6.readFileSync(soulPath, "utf-8").trimEnd()}
+  const base = fs7.existsSync(soulPath) ? `${fs7.readFileSync(soulPath, "utf-8").trimEnd()}
 
 ---
 
@@ -14956,7 +15127,7 @@ function appendSystemPromptExtras(base, env = process.env) {
   const filePath = env.AERO_SYSTEM_PROMPT_FILE?.trim();
   if (filePath) {
     try {
-      fileBody = fs6.readFileSync(filePath, "utf-8").trim();
+      fileBody = fs7.readFileSync(filePath, "utf-8").trim();
     } catch {
       fileBody = "";
     }
@@ -15969,6 +16140,7 @@ function registerMcpHttpRoutes(scope, opts) {
     const client = new ApiClient(opts.selfApiUrl, sessionKey?.raw ?? bearer, {
       skipProbe: true,
       clientName: `canonry-mcp/${PACKAGE_VERSION}`,
+      surface: "mcp-http",
       // Correlation only: this is never accepted as caller identity or authority.
       actorSession: crypto26.randomUUID()
     });
@@ -15979,7 +16151,8 @@ function registerMcpHttpRoutes(scope, opts) {
         credentialScopes: scopes,
         operator: request.operatorAccess === true,
         tiers: segment.tiers,
-        clientFactory: () => client
+        clientFactory: () => client,
+        updateAvailable: opts.getUpdateAvailable
       });
     } catch (error) {
       if (sessionKey) revokeSessionKey(opts.db, sessionKey.id);
@@ -17723,7 +17896,7 @@ function cloneGtmConfig(config) {
 function createGoogleMarketingConfigCredentialStore(input) {
   const persistConfigPatch = input.saveConfigPatch ?? saveConfigPatch;
   const env = input.env ?? process.env;
-  const randomUUID = input.randomUUID ?? crypto27.randomUUID;
+  const randomUUID2 = input.randomUUID ?? crypto27.randomUUID;
   const snapshot = () => ({
     googleAds: cloneGoogleAdsConfig(input.config.googleAds),
     gtm: cloneGtmConfig(input.config.gtm)
@@ -17771,7 +17944,7 @@ function createGoogleMarketingConfigCredentialStore(input) {
           upsertGoogleAdsConnection(input.config, {
             projectId: project.id,
             projectName: project.name,
-            credentialGeneration: randomUUID(),
+            credentialGeneration: randomUUID2(),
             ...credential.accessToken ? { accessToken: credential.accessToken } : {},
             refreshToken: credential.refreshToken ?? null,
             tokenExpiresAt: credential.expiresAt ?? null,
@@ -17783,7 +17956,7 @@ function createGoogleMarketingConfigCredentialStore(input) {
           upsertGtmConnection(input.config, {
             projectId: project.id,
             projectName: project.name,
-            credentialGeneration: randomUUID(),
+            credentialGeneration: randomUUID2(),
             ...credential.accessToken ? { accessToken: credential.accessToken } : {},
             refreshToken: credential.refreshToken ?? null,
             tokenExpiresAt: credential.expiresAt ?? null,
@@ -17896,6 +18069,10 @@ async function createServer(opts) {
   const notifier = new Notifier(opts.db, serverUrl);
   const intelligenceService = new IntelligenceService(opts.db);
   const aeroClient = new ApiClient(opts.config.apiUrl, opts.config.apiKey, {
+    skipProbe: true,
+    surface: "aero"
+  });
+  const schedulerClient = new ApiClient(opts.config.apiUrl, opts.config.apiKey, {
     skipProbe: true
   });
   const agentEnabled = resolveAgentEnabled(process.env, opts.config);
@@ -18028,7 +18205,7 @@ async function createServer(opts) {
     });
   };
   const orphanedOpenClawDir = path8.join(os4.homedir(), ".openclaw-aero");
-  if (fs7.existsSync(orphanedOpenClawDir)) {
+  if (fs8.existsSync(orphanedOpenClawDir)) {
     app.log.warn(
       { path: orphanedOpenClawDir },
       "OpenClaw gateway is no longer used. Remove ~/.openclaw-aero/ manually to reclaim the directory."
@@ -18336,7 +18513,7 @@ async function createServer(opts) {
     getRunnableProviderNames: () => registry.getAll().map((provider) => provider.adapter.name),
     getEffectiveProviderModels: () => effectiveProviderModels(registry),
     onTrafficSyncRequested: (projectName, sourceId) => {
-      aeroClient.trafficSync(projectName, sourceId).catch((err) => {
+      schedulerClient.trafficSync(projectName, sourceId).catch((err) => {
         app.log.error(
           {
             projectName,
@@ -18356,7 +18533,7 @@ async function createServer(opts) {
     onDoctorRequested: (projectName) => {
       void (async () => {
         try {
-          const report = await aeroClient.runDoctor({ project: projectName });
+          const report = await schedulerClient.runDoctor({ project: projectName });
           const project = opts.db.select().from(projects).where(eq26(projects.name, projectName)).get();
           if (!project) {
             app.log.warn({ projectName }, "doctor schedule fired for an unknown project");
@@ -18372,7 +18549,7 @@ async function createServer(opts) {
       })();
     },
     onDataRefreshRequested: (projectName) => {
-      void refreshAllIntegrations(aeroClient, projectName);
+      void refreshAllIntegrations(schedulerClient, projectName);
     },
     onBacklinksSyncRequested: (projectName) => {
       void (async () => {
@@ -18397,7 +18574,7 @@ async function createServer(opts) {
           );
           return;
         }
-        aeroClient.backlinksTriggerSync(probed.release).catch((err) => {
+        schedulerClient.backlinksTriggerSync(probed.release).catch((err) => {
           app.log.error(
             {
               projectName,
@@ -18898,6 +19075,9 @@ async function createServer(opts) {
   await app.register(apiRoutes, {
     db: opts.db,
     routePrefix: apiPrefix,
+    // Agent-surface usage (MCP, Aero, raw API). CLI and dashboard requests are
+    // measured elsewhere and skipped inside.
+    onRequestCompleted: createApiUsageTelemetry(),
     skipAuth: false,
     sessionCookieName: SESSION_COOKIE_NAME,
     resolveSessionApiKeyId,
@@ -18935,7 +19115,7 @@ async function createServer(opts) {
       const configPath = getConfigPath();
       return {
         databasePath: opts.config.database,
-        configPath: fs7.existsSync(configPath) ? configPath : null
+        configPath: fs8.existsSync(configPath) ? configPath : null
       };
     })(),
     // Snapshot the bundled skill trees (version + file hashes) so the
@@ -18950,6 +19130,8 @@ async function createServer(opts) {
       }
     })(),
     getAgentPluginState: opts.getAgentPluginState,
+    // Powers the `canonry.version.current` doctor check. Non-blocking.
+    getUpdateStatus: () => getServerUpdateStatus(),
     // Local canonry serve runs on the operator's machine, where pointing a
     // webhook at localhost (Discord test container, Pipedream-mock dev server,
     // etc.) is a legitimate workflow. Default to allowing it for the local
@@ -18968,7 +19150,13 @@ async function createServer(opts) {
     credentials: credentialChecker,
     oauthResourceUrl: publicOrigin ? `${publicOrigin}${`${basePath ?? "/"}api/v1/mcp`.replace("//", "/")}` : void 0,
     registerAuthenticatedRoutes: async (scope) => {
-      registerMcpHttpRoutes(scope, { selfApiUrl: opts.config.apiUrl, issuer: publicOrigin, db: opts.db });
+      registerMcpHttpRoutes(scope, {
+        selfApiUrl: opts.config.apiUrl,
+        issuer: publicOrigin,
+        db: opts.db,
+        // Same non-blocking cache as /health, so hosted agents see the notice too.
+        getUpdateAvailable: () => checkLatestVersionForServer()
+      });
       registerOAuthAdminRoutes(scope, { db: opts.db });
       if (!sessionRegistry) return;
       registerAgentRoutes(scope, { db: opts.db, sessionRegistry });
@@ -19428,9 +19616,7 @@ async function createServer(opts) {
     listOperationalLogs: (query) => operationalLogs.list(query),
     getTelemetryStatus,
     setTelemetryEnabled: (enabled) => {
-      const config = loadConfig();
-      config.telemetry = enabled;
-      saveConfigPatch(config);
+      void setTelemetryPreference(enabled, "api");
       opts.config.telemetry = enabled;
     },
     recordOnboardingEvent: (event) => {
@@ -19513,9 +19699,9 @@ async function createServer(opts) {
       return snapshotService.createReport(input);
     }
   });
-  const dirname = path8.dirname(fileURLToPath2(import.meta.url));
+  const dirname = path8.dirname(fileURLToPath3(import.meta.url));
   const assetsDir = opts.assetsDir ?? path8.join(dirname, "..", "assets");
-  if (fs7.existsSync(assetsDir)) {
+  if (fs8.existsSync(assetsDir)) {
     const indexPath = path8.join(assetsDir, "index.html");
     const injectConfig = (html, projectTabsOverride, themeOverride, renderTokenOverride) => {
       const clientConfig = {};
@@ -19589,8 +19775,8 @@ async function createServer(opts) {
       }
     });
     const serveIndex = (_request, reply) => {
-      if (fs7.existsSync(indexPath)) {
-        const html = fs7.readFileSync(indexPath, "utf-8");
+      if (fs8.existsSync(indexPath)) {
+        const html = fs8.readFileSync(indexPath, "utf-8");
         return sendSpaDocument(reply, html);
       }
       return reply.status(404).send({ error: "Dashboard not built" });
@@ -19621,8 +19807,8 @@ async function createServer(opts) {
       if (basePath && !url.startsWith(basePath)) {
         return reply.status(404).send({ error: "Not found", path: request.url });
       }
-      if (fs7.existsSync(indexPath)) {
-        const html = fs7.readFileSync(indexPath, "utf-8");
+      if (fs8.existsSync(indexPath)) {
+        const html = fs8.readFileSync(indexPath, "utf-8");
         return sendSpaDocument(reply, html);
       }
       return reply.status(404).send({ error: "Not found" });
@@ -19762,6 +19948,7 @@ function parseQueryResponse(raw, count2) {
 }
 
 export {
+  cliRuntimeContext,
   trackCliCommandFinished,
   setTelemetrySource,
   getTelemetryStatus,
@@ -19771,6 +19958,7 @@ export {
   showFirstRunNotice,
   detectAndTrackUpgrade,
   trackEvent,
+  setTelemetryPreference,
   backfillAnswerVisibilityCommand,
   backfillNormalizedPaths,
   backfillNormalizedPathsCommand,
@@ -19784,6 +19972,8 @@ export {
   setGoogleAuthConfig,
   formatAuditFactorScore,
   checkLatestVersionForCli,
+  readCachedUpdateAvailable,
+  formatUpdateNotice,
   listAgentProviders,
   coerceAgentProvider,
   AERO_TOOL_PROFILES,