@ainyc/canonry 5.1.1 → 5.1.3

package/dist/{chunk-MEQGGODM.js → chunk-AEE5DGTE.js}

@@ -1,6 +1,7 @@
 import {
   AGENT_MEMORY_KEY_MAX_LENGTH,
   AGENT_MEMORY_VALUE_MAX_BYTES,
+  CANONRY_NPM_PACKAGE_URL,
   CodingAgents,
   DEFAULT_VIEWER_RESEARCH_DAILY_RUN_LIMIT,
   DISCOVERY_MAX_PROBES_CAP,
@@ -9,6 +10,7 @@ import {
   RESEARCH_RUN_SCOPE,
   SKILL_MANIFEST_FILENAME,
   SkillsClients,
+  USAGE_TELEMETRY_HEADERS,
   adsActivateTreeRequestSchema,
   adsAdCreateRequestSchema,
   adsAdGroupCreateRequestSchema,
@@ -27,9 +29,11 @@ import {
   canonicalizeGtmResourceSelection,
   classifySkillFile,
   coerceSkillManifest,
+  compareSemver,
   competitorBatchRequestSchema,
   competitorLandscapeQuerySchema,
   describeError,
+  detectAgentRuntime,
   discoveryBucketSchema,
   discoveryCompetitorTypeSchema,
   discoveryPromoteRequestSchema,
@@ -38,8 +42,10 @@ import {
   gaMeasurementHostScopeSchema,
   googleAdsMetricsWindowSchema,
   gscPerformanceOrderBySchema,
+  isInstallMethod,
   isReadOnlyKey,
   isSensitiveDiagnosticQueryKey,
+  isStrictSemver,
   keywordBatchRequestSchema,
   keywordGenerateRequestSchema,
   logQuerySchema,
@@ -82,6 +88,7 @@ import {
   measurementQueryTemplateApplyRequestSchema,
   measurementQueryTemplateUpsertRequestSchema,
   measurementQuestionResultQuerySchema,
+  normalizeAgentSlug,
   normalizeTelemetryStatus,
   notificationCreateRequestSchema,
   notificationEventSchema,
@@ -114,8 +121,10 @@ import {
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema,
   trafficSeriesGranularitySchema,
+  upgradeCaveatFor,
+  upgradeCommandFor,
   visibilityReportRequestSchema
-} from "./chunk-3DL3KV6C.js";
+} from "./chunk-MMSPU72Z.js";
 
 // src/cli-error.ts
 function isMachineFormat(format) {
@@ -609,6 +618,9 @@ function configExists() {
   return fs.existsSync(getConfigPath());
 }
 
+// src/client.ts
+import { AsyncLocalStorage } from "async_hooks";
+
 // src/client-reliability.ts
 function parseRetryAfterMs(header, now = Date.now()) {
   if (!header) return void 0;
@@ -6021,6 +6033,21 @@ function createClient2(opts) {
 }
 
 // src/client.ts
+function parseServerUpdateAvailable(value) {
+  if (!value || typeof value !== "object") return null;
+  const { current, latest, installMethod } = value;
+  if (typeof current !== "string" || current.length > 32 || !isStrictSemver(current)) return null;
+  if (typeof latest !== "string" || latest.length > 32 || !isStrictSemver(latest)) return null;
+  if (compareSemver(latest, current) <= 0) return null;
+  const method = installMethod === void 0 ? "npm" : installMethod;
+  if (!isInstallMethod(method)) return null;
+  return { current, latest, installMethod: method, upgradeCommand: upgradeCommandFor(method), url: CANONRY_NPM_PACKAGE_URL };
+}
+var usageTagStore = new AsyncLocalStorage();
+function runWithUsageTags(client2, tags, fn) {
+  if (!(client2 instanceof ApiClient)) return fn();
+  return usageTagStore.run(tags, fn);
+}
 var SAFE_CLIENT_NAME = /^\w[\w./-]{0,127}$/;
 var SAFE_ACTOR_SESSION = /^\w[\w.:-]{0,127}$/;
 function safeClientName(value) {
@@ -6049,12 +6076,24 @@ var ApiClient = class {
     this.probeSkipped = opts?.skipProbe ?? false;
     this.heyClientBaseUrl = this.originUrl;
     const actorSession = safeActorSession(opts?.actorSession);
+    const surface = opts?.surface ?? "cli";
+    const serverHosted = surface === "mcp-http" || surface === "aero";
     this.requestHeaders = {
       authorization: `Bearer ${this.apiKey}`,
       "user-agent": safeClientName(opts?.clientName),
-      ...actorSession ? { "x-canonry-actor-session": actorSession } : {}
+      ...actorSession ? { "x-canonry-actor-session": actorSession } : {},
+      [USAGE_TELEMETRY_HEADERS.surface]: surface,
+      ...serverHosted ? {} : { [USAGE_TELEMETRY_HEADERS.agent]: detectAgentRuntime(process.env) }
     };
     this.heyClient = createClient2({ baseUrl: this.originUrl, apiKey: this.apiKey, headers: this.requestHeaders });
+    this.heyClient.interceptors.request.use((request) => {
+      const tags = usageTagStore.getStore();
+      if (tags?.mcpTool) request.headers.set(USAGE_TELEMETRY_HEADERS.mcpTool, tags.mcpTool);
+      if (tags?.mcpCall) request.headers.set(USAGE_TELEMETRY_HEADERS.mcpCall, tags.mcpCall);
+      const mcpClient = normalizeAgentSlug(tags?.mcpClient);
+      if (mcpClient) request.headers.set(USAGE_TELEMETRY_HEADERS.mcpClient, mcpClient);
+      return request;
+    });
   }
   /**
    * On first API call, probe /health to auto-discover basePath when the user
@@ -6330,7 +6369,7 @@ var ApiClient = class {
     let res;
     try {
       res = await fetch(url, {
-        headers: { Authorization: `Bearer ${this.apiKey}` }
+        headers: { ...this.requestHeaders }
       });
     } catch (err) {
       const message = describeError(err);
@@ -7072,6 +7111,22 @@ var ApiClient = class {
   async getApiKeySelf() {
     return this.invoke(() => getApiV1KeysSelf({ client: this.heyClient }));
   }
+  /**
+   * The connected server's update notice from `/health`, or null. Best-effort
+   * and bounded (2s), never throws: `canonry-mcp` uses it to tell agents that
+   * never run the CLI about a newer release.
+   */
+  async getServerUpdateAvailable() {
+    try {
+      await this.probeBasePath();
+      const res = await fetch(`${this.originUrl}/health`, { signal: AbortSignal.timeout(2e3) });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return parseServerUpdateAvailable(body?.updateAvailable);
+    } catch {
+      return null;
+    }
+  }
   async createApiKey(body) {
     return this.invoke(() => postApiV1Keys({ client: this.heyClient, body }));
   }
@@ -8939,6 +8994,7 @@ var ApiClient = class {
 };
 
 // src/mcp/server.ts
+import { randomUUID } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z5 } from "zod";
 
@@ -13115,15 +13171,34 @@ function createCanonryMcpServer(options = {}) {
   return createCanonryMcpServerWithCatalog(options).server;
 }
 var SERVER_INSTRUCTIONS = OPERATIONS_GUIDE.initialize;
+function updateNoticeInstructions(update) {
+  const upgrade = update.installMethod === "docker" ? update.upgradeCommand : `${update.upgradeCommand}, then restart the Canonry server`;
+  const caveat = upgradeCaveatFor(update.installMethod);
+  return `Update available (UPDATE_AVAILABLE): canonry ${update.latest} is published; the connected Canonry server runs ${update.current}. Tell the operator. Upgrade: ${upgrade}. ${caveat ? `${caveat} ` : ""}Only upgrade with the operator's approval.`;
+}
+function updateNoticePayload(update) {
+  const caveat = upgradeCaveatFor(update.installMethod);
+  return { code: "UPDATE_AVAILABLE", ...update, ...caveat ? { note: caveat } : {} };
+}
+function readUpdateAvailable(getter) {
+  try {
+    return getter?.() ?? null;
+  } catch {
+    return null;
+  }
+}
 function createCanonryMcpServerWithCatalog(options = {}) {
-  const clientFactory = options.clientFactory ?? (() => createApiClient({ clientName: "canonry-mcp" }));
+  const clientFactory = options.clientFactory ?? (() => createApiClient({ clientName: "canonry-mcp", surface: "mcp-stdio", actorSession: randomUUID() }));
   const client2 = clientFactory();
   const scope = options.scope ?? "all";
+  const update = readUpdateAvailable(options.updateAvailable);
   const server = new McpServer({
     name: "canonry",
     version: PACKAGE_VERSION
   }, {
-    instructions: SERVER_INSTRUCTIONS
+    instructions: update ? `${SERVER_INSTRUCTIONS.trimEnd()}
+
+${updateNoticeInstructions(update)}` : SERVER_INSTRUCTIONS
   });
   server.validateToolInput = async (_tool, args) => args;
   const entries = [];
@@ -13141,7 +13216,11 @@ function createCanonryMcpServerWithCatalog(options = {}) {
       },
       async (input) => withToolErrors(async () => {
         const parsed = tool.inputSchema.parse(input ?? {});
-        return handler(client2, parsed);
+        return runWithUsageTags(client2, {
+          mcpTool: tool.name,
+          mcpCall: randomUUID(),
+          mcpClient: server.server.getClientVersion()?.name
+        }, () => handler(client2, parsed));
       })
     );
     entries.push({ tool, registered });
@@ -13150,7 +13229,7 @@ function createCanonryMcpServerWithCatalog(options = {}) {
   const catalog = new DynamicToolCatalog(server, entries, scope, { eager });
   catalog.applyInitialEnablement();
   const mode = options.tiers !== void 0 ? "hosted-fixed-catalog" : eager ? "stdio-fixed-catalog" : "stdio-progressive";
-  registerMetaTools(server, catalog, { includeToolkitLoader: options.tiers === void 0, mode });
+  registerMetaTools(server, catalog, { includeToolkitLoader: options.tiers === void 0, mode, updateAvailable: options.updateAvailable });
   server.registerResource("canonry-agent-operations-v1", OPERATIONS_GUIDE.resourceUri, {
     title: "Canonry Operations Guide v1",
     description: "Optional public operations guidance. Use canonry_help when resources are unavailable.",
@@ -13177,7 +13256,11 @@ function registerMetaTools(server, catalog, opts) {
     async (input) => {
       try {
         const parsed = helpInputSchema.parse(input ?? {});
-        const result = operationsHelp(catalog.helpResult(), opts.mode, parsed.intent, parsed.includeCatalog);
+        const update = readUpdateAvailable(opts.updateAvailable);
+        const result = {
+          ...operationsHelp(catalog.helpResult(), opts.mode, parsed.intent, parsed.includeCatalog),
+          ...update ? { updateAvailable: updateNoticePayload(update) } : {}
+        };
         return { ...jsonToolResult(result), structuredContent: result };
       } catch (error) {
         return errorToolResult(error);
@@ -13618,6 +13701,7 @@ export {
   emitInstallSummary,
   getMissingUserSkillsNudge,
   parseSkillsClient,
+  runWithUsageTags,
   createApiClient,
   ApiClient,
   measurementDraftOperationSchema,

package/dist/{chunk-LHHJVGH7.js → chunk-EBUX3C5H.js}

@@ -124,6 +124,7 @@ import {
   TrafficSourceAuthModes,
   TrafficSourceStatuses,
   TrafficSourceTypes,
+  USAGE_TELEMETRY_HEADERS,
   UserRoles,
   VerificationStatuses,
   WILDCARD_SCOPE,
@@ -240,6 +241,7 @@ import {
   clusterByCosine,
   coerceSkillManifest,
   compactDateToIso,
+  compareSemver,
   competitorBatchRequestSchema,
   competitorDtoSchema,
   competitorLandscapeQuerySchema,
@@ -390,6 +392,7 @@ import {
   isLocationRedirectStatus,
   isReadOnlyKey,
   isRetryableHttpError,
+  isStrictSemver,
   isTemplateLinkRatio,
   isTrendBaseline,
   isVertexGroundingRedirect,
@@ -677,6 +680,7 @@ import {
   trafficStatusResponseSchema,
   trafficSyncResponseSchema,
   unsupportedKind,
+  upgradeCaveatFor,
   userDtoSchema,
   userListDtoSchema,
   validationError,
@@ -702,7 +706,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-3DL3KV6C.js";
+} from "./chunk-MMSPU72Z.js";
 
 // src/intelligence-service.ts
 import { eq as eq67, desc as desc29, asc as asc12, and as and57, ne as ne11, or as or16, inArray as inArray25, gte as gte18, lte as lte15, isNull as isNull12, sql as sql27, exists } from "drizzle-orm";
@@ -11551,7 +11555,11 @@ function requestAuditIdentity(request) {
     credentialId: request.apiKey?.id ?? principal.id
   };
 }
-function registerRequestContext(app) {
+function headerValue(value) {
+  const first = Array.isArray(value) ? value[0] : value;
+  return first ? first.slice(0, MAX_REQUEST_CONTEXT_LENGTH) : void 0;
+}
+function registerRequestContext(app, options = {}) {
   app.addHook("onRequest", (request, reply, done) => {
     reply.header("x-request-id", request.id);
     requestContext.run({
@@ -11575,6 +11583,29 @@ function registerRequestContext(app) {
     populateIdentity(request);
     const context = requestContext.getStore();
     if (context) context.statusCode = reply.statusCode;
+    const route = request.routeOptions.url;
+    if (options.onRequestCompleted && route) {
+      try {
+        const kind = request.principal?.kind;
+        options.onRequestCompleted({
+          method: request.method,
+          route,
+          statusCode: reply.statusCode,
+          durationMs: reply.elapsedTime,
+          userAgent: headerValue(request.headers["user-agent"]),
+          actorSession: headerValue(request.headers["x-canonry-actor-session"]),
+          principalKind: kind === "user" ? "user" : kind ? "api-key" : void 0,
+          usageLabels: {
+            surface: headerValue(request.headers[USAGE_TELEMETRY_HEADERS.surface]),
+            agent: headerValue(request.headers[USAGE_TELEMETRY_HEADERS.agent]),
+            mcpClient: headerValue(request.headers[USAGE_TELEMETRY_HEADERS.mcpClient]),
+            mcpTool: headerValue(request.headers[USAGE_TELEMETRY_HEADERS.mcpTool]),
+            mcpCall: headerValue(request.headers[USAGE_TELEMETRY_HEADERS.mcpCall])
+          }
+        });
+      } catch {
+      }
+    }
     done();
     if (context) context.completed = true;
   });
@@ -12885,13 +12916,13 @@ function activePlanVersionRow(db, projectId) {
   if (!version) throw new Error(`Measurement plan ${projectId} points to missing version ${pointer.activeVersionId}`);
   return version;
 }
-function headerValue(request, name) {
+function headerValue2(request, name) {
   const raw = request.headers[name];
   const value = Array.isArray(raw) ? raw[0] : raw;
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 function requireIfMatch(request) {
-  const value = headerValue(request, "if-match");
+  const value = headerValue2(request, "if-match");
   if (!value) throw measurementDraftEtagRequired();
   return value;
 }
@@ -12902,7 +12933,7 @@ function assertDraftEtag(row, ifMatch) {
   }
 }
 function requireIdempotencyKey(request, operation) {
-  const value = headerValue(request, "idempotency-key");
+  const value = headerValue2(request, "idempotency-key");
   if (!value) throw measurementIdempotencyKeyRequired(operation);
   return value;
 }
@@ -21091,20 +21122,20 @@ function loadDraft(app, projectId, projectName) {
   }
   return { row, authoring: parsed.data };
 }
-function headerValue2(request, name) {
+function headerValue3(request, name) {
   const value = request.headers[name];
   const first = Array.isArray(value) ? value[0] : value;
   return typeof first === "string" && first.trim() ? first.trim() : void 0;
 }
 function requireCurrentEtag(request, draft) {
-  const supplied = headerValue2(request, "if-match");
+  const supplied = headerValue3(request, "if-match");
   if (!supplied) throw measurementDraftEtagRequired();
   if (parseMeasurementDraftEtagVersion(supplied) !== draft.row.etagVersion) {
     throw measurementDraftEtagStale(measurementDraftEtag(draft.row.etagVersion), supplied);
   }
 }
 function requireIdempotencyKey2(request, operation) {
-  const supplied = headerValue2(request, "idempotency-key");
+  const supplied = headerValue3(request, "idempotency-key");
   if (!supplied) throw measurementIdempotencyKeyRequired(operation);
   return supplied;
 }
@@ -44501,9 +44532,9 @@ async function withGa4Limit(fn) {
     releaseGa4Slot();
   }
 }
-function parseRetryAfter(headerValue3) {
-  if (!headerValue3) return void 0;
-  const trimmed = headerValue3.trim();
+function parseRetryAfter(headerValue4) {
+  if (!headerValue4) return void 0;
+  const trimmed = headerValue4.trim();
   const asNum = Number(trimmed);
   if (Number.isFinite(asNum) && asNum >= 0) return asNum;
   const asDate = Date.parse(trimmed);
@@ -73847,9 +73878,9 @@ var VercelLogsApiError = class extends Error {
   body;
   retryAfterSeconds;
 };
-function parseRetryAfter2(headerValue3) {
-  if (!headerValue3) return void 0;
-  const trimmed = headerValue3.trim();
+function parseRetryAfter2(headerValue4) {
+  if (!headerValue4) return void 0;
+  const trimmed = headerValue4.trim();
   const asNum = Number(trimmed);
   if (Number.isFinite(asNum) && asNum >= 0) return asNum;
   const asDate = Date.parse(trimmed);
@@ -81274,11 +81305,72 @@ var GOOGLE_MARKETING_DOCTOR_CHECKS = createGoogleMarketingDoctorChecks(
   (ctx) => ctx.getGoogleMarketingDoctorInput?.(ctx)
 );
 
+// ../api-routes/src/doctor/checks/version.ts
+var versionCurrentCheck = {
+  id: "canonry.version.current",
+  category: CheckCategories.config,
+  scope: CheckScopes.global,
+  title: "Canonry version",
+  run: (ctx) => {
+    if (!ctx.getUpdateStatus) {
+      return {
+        status: CheckStatuses.skipped,
+        code: "version.status-unavailable",
+        summary: "This deployment does not report update status."
+      };
+    }
+    const status = ctx.getUpdateStatus();
+    if (!status.enabled) {
+      return {
+        status: CheckStatuses.skipped,
+        code: "version.check-disabled",
+        summary: `Update check is off (${status.disabledBy ?? "opted out"}); running ${status.current}.`,
+        details: { current: status.current, ...status.disabledBy ? { disabledBy: status.disabledBy } : {} }
+      };
+    }
+    if (!status.latest || !isStrictSemver(status.latest)) {
+      return {
+        status: CheckStatuses.skipped,
+        code: "version.latest-unknown",
+        summary: `Latest published version is not known yet (running ${status.current}).`,
+        remediation: "The npm registry has not been reached yet. Re-run doctor in a moment; offline hosts stay skipped.",
+        details: { current: status.current }
+      };
+    }
+    if (compareSemver(status.latest, status.current) > 0) {
+      const caveat = upgradeCaveatFor(status.installMethod);
+      return {
+        status: CheckStatuses.warn,
+        code: "version.outdated",
+        summary: `canonry ${status.latest} is available; this server runs ${status.current}.`,
+        remediation: status.installMethod === "docker" ? `Upgrade the container: ${status.upgradeCommand}.` : `Run \`${status.upgradeCommand}\`, then restart the server (\`canonry stop && canonry start\`, or restart \`canonry serve\`).${caveat ? ` ${caveat}` : ""}`,
+        details: {
+          current: status.current,
+          latest: status.latest,
+          installMethod: status.installMethod,
+          upgradeCommand: status.upgradeCommand,
+          url: status.url
+        }
+      };
+    }
+    return {
+      status: CheckStatuses.ok,
+      code: "version.current",
+      // "latest" would overstate it: when the registry is unreachable this can
+      // come from an older on-disk cache, which proves only that nothing newer is known.
+      summary: `No newer canonry known (running ${status.current}; latest seen ${status.latest}).`,
+      details: { current: status.current, latest: status.latest }
+    };
+  }
+};
+var VERSION_CHECKS = [versionCurrentCheck];
+
 // ../api-routes/src/doctor/registry.ts
 var ALL_CHECKS = [
   // Runtime-state checks run first so file-system gone errors surface
   // before any auth/integration checks try to touch the (orphaned) DB.
   ...RUNTIME_STATE_CHECKS,
+  ...VERSION_CHECKS,
   ...GOOGLE_AUTH_CHECKS,
   ...GBP_AUTH_CHECKS,
   ...PLACES_CHECKS,
@@ -81384,6 +81476,7 @@ async function doctorRoutes(app, opts) {
       runtimeStatePaths: opts.runtimeStatePaths,
       bundledSkills: opts.bundledSkills,
       getAgentPluginState: opts.getAgentPluginState,
+      getUpdateStatus: opts.getUpdateStatus,
       getGoogleMarketingDoctorInput: opts.getGoogleMarketingDoctorInput
     };
     return runChecks(ctx, ALL_CHECKS, { checkIds });
@@ -81413,6 +81506,7 @@ async function doctorRoutes(app, opts) {
       runtimeStatePaths: opts.runtimeStatePaths,
       bundledSkills: opts.bundledSkills,
       getAgentPluginState: opts.getAgentPluginState,
+      getUpdateStatus: opts.getUpdateStatus,
       getGoogleMarketingDoctorInput: opts.getGoogleMarketingDoctorInput
     };
     return runChecks(ctx, ALL_CHECKS, { checkIds });
@@ -84469,7 +84563,7 @@ async function apiRoutes(app, opts) {
     });
   }
   await app.register(async (api) => {
-    registerRequestContext(api);
+    registerRequestContext(api, { onRequestCompleted: opts.onRequestCompleted });
     await api.register(rateLimit, {
       global: false,
       hook: "preHandler",
@@ -84722,6 +84816,7 @@ async function apiRoutes(app, opts) {
       runtimeStatePaths: opts.runtimeStatePaths,
       bundledSkills: opts.bundledSkills,
       getAgentPluginState: opts.getAgentPluginState,
+      getUpdateStatus: opts.getUpdateStatus,
       getGoogleMarketingDoctorInput: opts.getGoogleMarketingDoctorInput
     });
     if (opts.registerAuthenticatedRoutes) {

package/dist/{chunk-66KGNC4U.js → chunk-KJM4DRZN.js}

@@ -5,11 +5,11 @@ import {
   installSkills,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-MEQGGODM.js";
+} from "./chunk-AEE5DGTE.js";
 import {
   SKILL_MANIFEST_FILENAME,
   SkillsClients
-} from "./chunk-3DL3KV6C.js";
+} from "./chunk-MMSPU72Z.js";
 
 // src/skills-autosync.ts
 import fs from "fs";

package/dist/{chunk-3DL3KV6C.js → chunk-MMSPU72Z.js}

@@ -17782,6 +17782,49 @@ function isGhostTelemetryEvent(eventName, properties) {
   const location = typeof properties.location === "string" ? properties.location.trim().toLowerCase() : "";
   return GHOST_TELEMETRY_TEST_LOCATIONS.has(location);
 }
+var usageSurfaceSchema = z60.enum(["cli", "mcp-stdio", "mcp-http", "aero", "api", "dashboard"]);
+var USAGE_TELEMETRY_HEADERS = {
+  surface: "x-canonry-surface",
+  agent: "x-canonry-agent",
+  mcpClient: "x-canonry-mcp-client",
+  mcpTool: "x-canonry-mcp-tool",
+  mcpCall: "x-canonry-mcp-call"
+};
+var AGENT_NONE = "none";
+var AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9._-]{0,39}$/;
+function normalizeAgentSlug(value) {
+  if (!value) return null;
+  const slug = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").slice(0, 40).replace(/^[-._]+|[-._]+$/g, "");
+  return AGENT_SLUG_PATTERN.test(slug) ? slug : null;
+}
+var AI_AGENT_ALIASES = {
+  "claude-code": "claude",
+  "github-copilot-cli": "github-copilot"
+};
+function agentFromAiAgentVariable(value) {
+  const name = value.trim().toLowerCase().replace(/_agent$/, "").replace(/_\d[\d._-]*$/, "");
+  const slug = normalizeAgentSlug(name);
+  return slug ? AI_AGENT_ALIASES[slug] ?? slug : null;
+}
+function detectAgentRuntime(env) {
+  const explicit = normalizeAgentSlug(env.CANONRY_AGENT);
+  if (explicit) return explicit;
+  if (env.AI_AGENT?.trim()) {
+    const named = agentFromAiAgentVariable(env.AI_AGENT);
+    if (named) return named;
+  }
+  if (env.CURSOR_TRACE_ID) return "cursor";
+  if (env.CURSOR_AGENT || env.CURSOR_EXTENSION_HOST_ROLE === "agent-exec") return "cursor-cli";
+  if (env.GEMINI_CLI) return "gemini";
+  if (env.CODEX_SANDBOX || env.CODEX_CI || env.CODEX_THREAD_ID) return "codex";
+  if (env.ANTIGRAVITY_AGENT) return "antigravity";
+  if (env.AUGMENT_AGENT) return "augment-cli";
+  if (env.OPENCODE_CLIENT) return "opencode";
+  if (env.CLAUDECODE || env.CLAUDE_CODE) return env.CLAUDE_CODE_IS_COWORK ? "cowork" : "claude";
+  if (env.REPL_ID) return "replit";
+  if (env.COPILOT_MODEL || env.COPILOT_ALLOW_ALL || env.COPILOT_GITHUB_TOKEN) return "github-copilot";
+  return AGENT_NONE;
+}
 
 // ../contracts/src/trend-stability.ts
 var MIN_TREND_POINTS = 4;
@@ -18011,6 +18054,63 @@ function redactEmbeddedUrls(value) {
   });
 }
 
+// ../contracts/src/semver.ts
+var STRICT_SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\da-z-]+(?:\.[\da-z-]+)*)?(?:\+[\da-z-]+(?:\.[\da-z-]+)*)?$/i;
+var MAX_SEMVER_LENGTH = 128;
+function isStrictSemver(value) {
+  return value.length <= MAX_SEMVER_LENGTH && STRICT_SEMVER.test(value);
+}
+function compareSemver(a, b) {
+  const parse = (v) => {
+    const parts = (v.split(/[-+]/)[0] ?? "").split(".");
+    if (parts.length < 3) return null;
+    const nums = parts.slice(0, 3).map(Number);
+    if (!nums.every((n) => Number.isInteger(n) && n >= 0)) return null;
+    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;
+  }
+  return 0;
+}
+
+// ../contracts/src/update-notice.ts
+var CANONRY_NPM_PACKAGE = "@canonry/canonry";
+var CANONRY_NPM_PACKAGE_URL = `https://www.npmjs.com/package/${CANONRY_NPM_PACKAGE}`;
+var INSTALL_METHODS = ["npm", "homebrew", "docker"];
+function isInstallMethod(value) {
+  return typeof value === "string" && INSTALL_METHODS.includes(value);
+}
+function upgradeCommandFor(method) {
+  switch (method) {
+    case "npm":
+      return `npm install -g ${CANONRY_NPM_PACKAGE}`;
+    case "homebrew":
+      return "brew upgrade canonry";
+    case "docker":
+      return "pull or rebuild your canonry image, then recreate the container";
+  }
+}
+function upgradeCaveatFor(method) {
+  switch (method) {
+    case "homebrew":
+      return "Homebrew can trail npm briefly; if brew says canonry is up to date, retry later.";
+    case "npm":
+    case "docker":
+      return null;
+  }
+}
+function updateCheckEnvOptOut(env) {
+  if (env.CANONRY_DISABLE_UPDATE_CHECK === "1") return "CANONRY_DISABLE_UPDATE_CHECK";
+  if (env.DO_NOT_TRACK === "1") return "DO_NOT_TRACK";
+  if (env.CI) return "CI";
+  return null;
+}
+
 export {
   __export,
   apiKeyDtoSchema,
@@ -18793,6 +18893,11 @@ export {
   normalizeOnboardingEventForCollection,
   telemetryEventAcceptedDtoSchema,
   isGhostTelemetryEvent,
+  usageSurfaceSchema,
+  USAGE_TELEMETRY_HEADERS,
+  AGENT_NONE,
+  normalizeAgentSlug,
+  detectAgentRuntime,
   MIN_TREND_POINTS,
   isTrendBaseline,
   operationalLogEntryDtoSchema,
@@ -18801,5 +18906,12 @@ export {
   isSensitiveDiagnosticQueryKey,
   redactLogValue,
   redactLogString,
-  diagnosticIdentity
+  diagnosticIdentity,
+  isStrictSemver,
+  compareSemver,
+  CANONRY_NPM_PACKAGE_URL,
+  isInstallMethod,
+  upgradeCommandFor,
+  upgradeCaveatFor,
+  updateCheckEnvOptOut
 };