@agent-native/core 0.107.2 → 0.109.0

package/corpus/templates/analytics/server/lib/workspace-feature-flags.ts

@@ -0,0 +1,347 @@
+import { randomUUID } from "node:crypto";
+
+import { signA2AToken } from "@agent-native/core/a2a";
+import { fetchOrgApps, type OrgApp } from "@agent-native/core/mcp";
+
+import type { AnalyticsAdminContext } from "./db-admin-connections.js";
+
+const TARGET_TIMEOUT_MS = 3_000;
+const CONCURRENCY = 4;
+
+export type FleetFlagState =
+  | "ready"
+  | "no-definitions"
+  | "unsupported"
+  | "unreachable"
+  | "forbidden"
+  | "unknown-legacy";
+
+export interface FleetFlagApp {
+  appId: string;
+  appName: string;
+  appOrigin: string;
+  state: FleetFlagState;
+  flags: Array<Record<string, unknown>>;
+  reason?: string;
+}
+
+export interface WorkspaceFeatureFlagsResult {
+  directoryStatus: "available" | "unavailable";
+  apps: FleetFlagApp[];
+}
+
+export interface WorkspaceFeatureFlagMutationResult {
+  contractVersion: 1;
+  status: "ready";
+  key: string;
+  rules: Record<string, unknown>;
+  scope: { orgId: string | null };
+}
+
+export interface WorkspaceFeatureFlagMutationInput {
+  appId: string;
+  key: string;
+  operation: "enable-for-current-user" | "off" | "replace-rules";
+  rules?: Record<string, unknown>;
+}
+
+export function workspaceFeatureFlagTargetInput(
+  input: WorkspaceFeatureFlagMutationInput,
+): Omit<WorkspaceFeatureFlagMutationInput, "appId"> {
+  const { appId: _appId, ...rawTargetInput } = input;
+  return input.operation === "replace-rules" && input.rules
+    ? {
+        ...rawTargetInput,
+        rules: {
+          ...input.rules,
+          emails: input.rules.emails ?? [],
+          orgIds: input.rules.orgIds ?? [],
+          percentage: input.rules.percentage ?? 0,
+        },
+      }
+    : rawTargetInput;
+}
+
+export function validateWorkspaceFeatureFlagMutation(
+  body: unknown,
+  expected: {
+    key: string;
+    orgId: string;
+    rules?: Record<string, unknown>;
+    enabledForEmail?: string;
+  },
+): WorkspaceFeatureFlagMutationResult {
+  const payload = body as Partial<WorkspaceFeatureFlagMutationResult> | null;
+  const valid =
+    payload?.contractVersion === 1 &&
+    payload.status === "ready" &&
+    payload.key === expected.key &&
+    !!payload.rules &&
+    typeof payload.rules === "object" &&
+    !Array.isArray(payload.rules) &&
+    !!payload.scope &&
+    typeof payload.scope === "object" &&
+    payload.scope.orgId === expected.orgId;
+  if (!valid)
+    throw new Error(
+      "The target app returned an unsupported or unverified feature flag mutation response.",
+    );
+  const persistedRules = payload.rules as Record<string, unknown>;
+  if (expected.rules) {
+    for (const field of ["mode", "percentage"] as const) {
+      if (
+        expected.rules[field] !== undefined &&
+        persistedRules[field] !== expected.rules[field]
+      )
+        throw new Error(
+          "The target app did not persist the requested feature flag rules.",
+        );
+    }
+    for (const field of ["emails", "orgIds"] as const) {
+      const isValidTargetArray = (value: unknown): value is string[] =>
+        Array.isArray(value) &&
+        value.every(
+          (item) => typeof item === "string" && item.trim().length > 0,
+        );
+      const normalize = (value: unknown) =>
+        Array.isArray(value)
+          ? [
+              ...new Set(
+                value
+                  .filter((item): item is string => typeof item === "string")
+                  .map((item) =>
+                    field === "emails"
+                      ? item.trim().toLowerCase()
+                      : item.trim(),
+                  )
+                  .filter(Boolean),
+              ),
+            ].sort()
+          : [];
+      if (
+        expected.rules[field] !== undefined &&
+        (!isValidTargetArray(persistedRules[field]) ||
+          JSON.stringify(normalize(persistedRules[field])) !==
+            JSON.stringify(normalize(expected.rules[field])))
+      )
+        throw new Error(
+          "The target app did not persist the requested feature flag rules.",
+        );
+    }
+  }
+  if (expected.enabledForEmail) {
+    const email = expected.enabledForEmail.trim().toLowerCase();
+    const emails = Array.isArray(persistedRules.emails)
+      ? persistedRules.emails
+          .filter((value): value is string => typeof value === "string")
+          .map((value) => value.trim().toLowerCase())
+      : [];
+    if (persistedRules.mode !== "on" && !emails.includes(email))
+      throw new Error(
+        "The target app did not enable the feature flag for the delegated operator.",
+      );
+  }
+  return payload as WorkspaceFeatureFlagMutationResult;
+}
+
+function targetOrigin(app: OrgApp): string {
+  return new URL(app.url).origin;
+}
+
+async function delegatedToken(
+  admin: AnalyticsAdminContext,
+  origin: string,
+  scope: "flags:read" | "flags:write",
+): Promise<string> {
+  return signA2AToken(admin.userEmail, undefined, undefined, {
+    expiresIn: "120s",
+    preferGlobalSecret: true,
+    audience: origin,
+    extraClaims: { org_id: admin.orgId, scope, jti: randomUUID() },
+  });
+}
+
+async function callTarget(
+  app: OrgApp,
+  admin: AnalyticsAdminContext,
+  action: "list-feature-flags" | "set-feature-flag",
+  body: Record<string, unknown>,
+): Promise<{ status: number; body: unknown }> {
+  const origin = targetOrigin(app);
+  const token = await delegatedToken(
+    admin,
+    origin,
+    action === "list-feature-flags" ? "flags:read" : "flags:write",
+  );
+  const response = await fetch(`${origin}/_agent-native/actions/${action}`, {
+    method: action === "list-feature-flags" ? "GET" : "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+      ...(action === "set-feature-flag"
+        ? { "Content-Type": "application/json" }
+        : {}),
+    },
+    ...(action === "set-feature-flag" ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(TARGET_TIMEOUT_MS),
+  });
+  let parsed: unknown = null;
+  try {
+    parsed = await response.json();
+  } catch {
+    // A legacy/non-action endpoint is classified below without reflecting body.
+  }
+  return { status: response.status, body: parsed };
+}
+
+export function classifyWorkspaceFeatureFlagList(
+  app: OrgApp,
+  result: { status: number; body: unknown },
+): FleetFlagApp {
+  const base = {
+    appId: app.id,
+    appName: app.name,
+    appOrigin: targetOrigin(app),
+    flags: [] as Array<Record<string, unknown>>,
+  };
+  if (result.status === 401 || result.status === 403)
+    return { ...base, state: "forbidden" };
+  if (result.status === 404 || result.status === 405)
+    return { ...base, state: "unsupported" };
+  if (result.status < 200 || result.status >= 300)
+    return { ...base, state: "unknown-legacy" };
+  const payload = result.body as {
+    flags?: unknown;
+    canManage?: unknown;
+    status?: unknown;
+    contractVersion?: unknown;
+  } | null;
+  if (!payload || !Array.isArray(payload.flags))
+    return { ...base, state: "unknown-legacy" };
+  if (payload.contractVersion !== 1)
+    return { ...base, state: "unknown-legacy" };
+  if (payload.status === "no-definitions")
+    return { ...base, state: "no-definitions" };
+  if (payload.status === "forbidden" || payload.canManage === false)
+    return { ...base, state: "forbidden" };
+  if (payload.flags.length === 0) return { ...base, state: "no-definitions" };
+  return {
+    ...base,
+    state: "ready",
+    flags: payload.flags.filter(
+      (f): f is Record<string, unknown> => !!f && typeof f === "object",
+    ),
+  };
+}
+
+async function mapBounded<T, R>(
+  items: T[],
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = [];
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
+      while (cursor < items.length) {
+        const index = cursor++;
+        results[index] = await fn(items[index]!);
+      }
+    }),
+  );
+  return results;
+}
+
+export async function listWorkspaceFeatureFlags(
+  admin: AnalyticsAdminContext,
+): Promise<WorkspaceFeatureFlagsResult> {
+  const apps = await fetchOrgApps({ serviceOrgId: admin.orgId });
+  if (apps.length === 0) return { directoryStatus: "unavailable", apps: [] };
+  const entries = await mapBounded(apps, async (app) => {
+    try {
+      return classifyWorkspaceFeatureFlagList(
+        app,
+        await callTarget(app, admin, "list-feature-flags", {}),
+      );
+    } catch {
+      return {
+        appId: app.id,
+        appName: app.name,
+        appOrigin: targetOrigin(app),
+        state: "unreachable" as const,
+        flags: [],
+      };
+    }
+  });
+  return { directoryStatus: "available", apps: entries };
+}
+
+export async function setWorkspaceFeatureFlag(
+  admin: AnalyticsAdminContext,
+  input: WorkspaceFeatureFlagMutationInput,
+): Promise<WorkspaceFeatureFlagMutationResult> {
+  const apps = await fetchOrgApps({ serviceOrgId: admin.orgId });
+  const app = apps.find((candidate) => candidate.id === input.appId);
+  if (!app)
+    throw new Error(
+      "The requested app is not available in this organization directory.",
+    );
+  const targetInput = workspaceFeatureFlagTargetInput(input);
+  const result = await callTarget(app, admin, "set-feature-flag", targetInput);
+  if (result.status === 401 || result.status === 403)
+    throw new Error("The target app denied this delegated flag operation.");
+  if (result.status === 404 || result.status === 405)
+    throw new Error("The target app does not support feature flag management.");
+  if (result.status < 200 || result.status >= 300)
+    throw new Error(
+      "The target app could not persist the feature flag change.",
+    );
+  return validateWorkspaceFeatureFlagMutation(result.body, {
+    key: input.key,
+    orgId: admin.orgId,
+    ...(input.operation === "replace-rules" && input.rules
+      ? {
+          rules: {
+            mode: input.rules.mode,
+            emails: input.rules.emails ?? [],
+            orgIds: input.rules.orgIds ?? [],
+            percentage: input.rules.percentage ?? 0,
+          },
+        }
+      : input.operation === "off"
+        ? {
+            rules: {
+              mode: "off",
+              emails: [],
+              orgIds: [],
+              percentage: 0,
+            },
+          }
+        : { enabledForEmail: admin.userEmail }),
+  });
+}
+
+export async function getWorkspaceFlagTarget(
+  admin: AnalyticsAdminContext,
+  appId: string,
+): Promise<FleetFlagApp> {
+  const apps = await fetchOrgApps({ serviceOrgId: admin.orgId });
+  const app = apps.find((candidate) => candidate.id === appId);
+  if (!app)
+    throw new Error(
+      "The requested app is not available in this organization directory.",
+    );
+  try {
+    return classifyWorkspaceFeatureFlagList(
+      app,
+      await callTarget(app, admin, "list-feature-flags", {}),
+    );
+  } catch {
+    return {
+      appId: app.id,
+      appName: app.name,
+      appOrigin: targetOrigin(app),
+      state: "unreachable",
+      flags: [],
+    };
+  }
+}

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -687,7 +687,7 @@ export default createAgentChatPlugin({
   connectorCatalog: [...ANALYTICS_CONNECTOR_CATALOG],
   externalAgents: {
     // Keep the direct MCP surface deliberately curated. External agents
-    // should use ask_app for multi-step investigation; these six actions are
+    // should use ask_app for multi-step investigation; cataloged actions are
     // bounded fallback reads for callers that already know what they need.
     authenticatedReads: "off",
     writes: "ask_app_only",
@@ -704,8 +704,8 @@ export default createAgentChatPlugin({
       analyticsSourceGuidanceOpening() +
       "DASHBOARD CREATION RULE — You may create dashboards, analyses, SQL panels, or other resources only when the user explicitly asks you to (e.g. 'build me a dashboard for...', 'create a new analysis', 'add a chart for...'). Never create any resource proactively during research, trend analysis, or answering questions. If you think a dashboard would be useful, suggest it and wait for explicit confirmation before creating anything. Never add new items to the sidebar or modify existing dashboards without an explicit user directive. " +
       "DASHBOARD MUTATION RULE — For dashboard edits, default to `mutate-dashboard` with the typed `dashboard.*` script API so the main payload is a string and avoids native-array serialization traps. It can move panels by id, edit titles/SQL/config, insert, duplicate, remove, and patch dashboard fields in one atomic save. The script API is constrained: no variables/imports/loops/functions, only JSON-compatible arguments on documented dashboard methods. Do not count shifting `/panels/<index>` positions for ordinary dashboard edits unless the user specifically asks for low-level JSON-pointer operations. " +
-      'DASHBOARD EXTENSION BOX RULE — Analytics dashboards support extension boxes. Insert `chartType: "extension"` panels with `config.extensionSlotId` set to `analytics.dashboard.<dashboard-id>.panel.<panel-id>`, then call `add-extension-slot-target` and `install-extension` with that same id. The install is per-user; the extension box stays on the shared dashboard and receives dashboard/panel/current-filter context. Use `get-sql-dashboard` panel summaries to inspect an existing box; `config.extensionId` is only the legacy direct-embed format. ' +
-      "EXTENSION DATA-REPAIR RULE — When fixing data in an existing extension-backed dashboard or migrated surface such as Risk Meeting, inspect the current dashboard and extension first, then use `update-extension` `patches`/`edits` that change only the data-loading seam. Preserve the existing layout, CSS, copy, and interactions; never reconstruct the full HTML body for a data-only fix. Full-body replacement is blocked unless `allowFullReplacement=true`, which is reserved for an explicit visual rewrite or a complete replacement body supplied by the user. If a focused edit fails, change the target instead of retrying identical arguments. " +
+      'DASHBOARD EXTENSION BOX RULE — Analytics dashboards support extension boxes. For ordinary requests such as "put X in this dashboard," insert a `chartType: "extension"` panel with `config.extensionId`; this author-selected embed is shared with the dashboard, appears in scheduled reports, and receives dashboard/panel/current-filter context. Use `config.extensionSlotId` only when the user explicitly asks for a personal/per-viewer slot. Slot ids use `analytics.dashboard.<dashboard-id>.panel.<panel-id>` and require `add-extension-slot-target` plus `install-extension`; installs are per-user, so viewers can see different content and report identities may see an empty slot. Use `get-sql-dashboard` panel summaries to inspect an existing box. ' +
+      "EXTENSION DATA-REPAIR RULE — When fixing data in an existing extension-backed dashboard or migrated surface such as Risk Meeting, inspect the current dashboard and extension first, then use `update-extension` `patches`/`edits` that change only the data-loading seam. Preserve the existing layout, CSS, copy, and interactions; never reconstruct the full HTML body for a data-only fix. Full-body replacement is blocked unless `allowFullReplacement=true`. A request that combines a visual rewrite such as compacting, removing sections, renaming, or changing padding with a data repair is a broad rewrite; after inspecting the current extension, use `allowFullReplacement=true` for the complete replacement. If a focused edit fails, change the target instead of retrying identical arguments. " +
       'FIRST-PARTY DASHBOARD TIME RULE — AI-generated `source: "first-party"` panels are dashboard-time-bound by default: set `config.timeScope` to `dashboard` and include a matching dashboard time predicate. `{{timeRange}}` requires a matching `filters` entry with `id: "timeRange"` and `type: "select"`; `{{<id>Start}}`/`{{<id>End}}` require a matching `type: "date-range"` filter with that id. Allowed `timeScope` values are `dashboard`, `fixed-window`, `cohort-history`, and `all-time`; use `all-time` only when the user requests full available history and put all-time, lifetime, or historical in the title or description. Server validation rejects unbound first-party SQL. ' +
       "DASHBOARD READ RULE — `get-sql-dashboard` is compact by default: use its `panels` summaries plus `layout.panelOrder`, `layout.firstPanelIds`, and `layout.groups[].rows[].rowNumber/panelIds` for orientation and verification. Pass `includeConfig: true` only when you truly need full panel SQL/config. " +
       'DASHBOARD REORDER RULE — For simple chart/section moves, use `mutate-dashboard` code such as `dashboard.panels(["panel-a","panel-b"]).moveToTop();`. For visible placement requests like "second row" or "next to return rates", use row-aware placement such as `dashboard.insertPanel({...}).nextTo("retention-over-time")`, `.atRow(2)`, or `dashboard.panel("panel-a").moveNextTo("panel-b")`; these keep panels in the intended rendered row and expand/rebalance that row when needed. Never count shifting `/panels/<index>` positions for ordinary \'move this chart\' requests. Use `get-sql-dashboard.layout.groups[].rows` as proof of visible row placement, not only flat `panelOrder`. ' +

package/corpus/templates/analytics/server/routes/api/pylon/accounts.get.ts

@@ -1 +1,42 @@
-export { handlePylonAccounts as default } from "../../../handlers/pylon";
+import { defineEventHandler, getQuery, setResponseStatus } from "h3";
+
+import {
+  requireCredential,
+  runApiHandlerWithContext,
+} from "../../../lib/credentials";
+import { executeProviderApiRequest } from "../../../lib/provider-api";
+
+export default defineEventHandler((event) =>
+  runApiHandlerWithContext(event, async () => {
+    const missing = await requireCredential(event, "PYLON_API_KEY", "Pylon");
+    if (missing) return missing;
+    try {
+      const query = getQuery(event);
+      const search =
+        typeof query.query === "string" && query.query.trim()
+          ? query.query
+          : undefined;
+      const result = (await executeProviderApiRequest({
+        provider: "pylon",
+        method: "GET",
+        path: "/accounts",
+        ...(search ? { query: { query: search } } : {}),
+      })) as { response?: { json?: unknown } };
+      const body = result.response?.json;
+      const accounts =
+        Array.isArray(body) || !body || typeof body !== "object"
+          ? Array.isArray(body)
+            ? body
+            : []
+          : Array.isArray((body as { data?: unknown }).data)
+            ? (body as { data: unknown[] }).data
+            : [];
+      return { accounts, total: accounts.length };
+    } catch (error) {
+      setResponseStatus(event, 500);
+      return {
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }),
+);

package/corpus/templates/analytics/server/routes/api/pylon/issues.get.ts

@@ -1 +1,71 @@
-export { handlePylonIssues as default } from "../../../handlers/pylon";
+import { defineEventHandler, getQuery, setResponseStatus } from "h3";
+
+import pylonIssues from "../../../../actions/pylon-issues";
+import {
+  requireCredential,
+  runApiHandlerWithContext,
+} from "../../../lib/credentials";
+import { executeProviderApiRequest } from "../../../lib/provider-api";
+
+function queryString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function responseItems(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === "object" && "data" in value) {
+    const data = (value as { data?: unknown }).data;
+    return Array.isArray(data) ? data : [];
+  }
+  return [];
+}
+
+export default defineEventHandler((event) =>
+  runApiHandlerWithContext(event, async () => {
+    const missing = await requireCredential(event, "PYLON_API_KEY", "Pylon");
+    if (missing) return missing;
+    try {
+      const query = getQuery(event);
+      const accountId = queryString(query.account_id);
+      const state = queryString(query.state);
+      const search = queryString(query.query);
+
+      if (accountId || state || search) {
+        const now = new Date();
+        const start = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1_000);
+        const response = (await executeProviderApiRequest({
+          provider: "pylon",
+          method: "GET",
+          path: "/issues",
+          query: {
+            ...(accountId ? { account_id: accountId } : {}),
+            ...(state ? { state } : {}),
+            ...(search ? { query: search } : {}),
+            start_time: start.toISOString(),
+            end_time: now.toISOString(),
+          },
+        })) as { response?: { json?: unknown } };
+        const issues = responseItems(response.response?.json);
+        return { issues, total: issues.length };
+      }
+
+      const days = queryString(query.days);
+      const parsedDays = days == null ? 371 : Number(days);
+      if (!Number.isInteger(parsedDays) || parsedDays < 1 || parsedDays > 730) {
+        setResponseStatus(event, 400);
+        return { error: "days must be an integer between 1 and 730" };
+      }
+      const result = await pylonIssues.run({
+        days: parsedDays,
+        pageSize: 500,
+        maxPages: 20,
+      });
+      return result;
+    } catch (error) {
+      setResponseStatus(event, 500);
+      return {
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }),
+);

package/corpus/templates/analytics/server/routes/api/test-connection.post.ts

@@ -6,6 +6,7 @@ import {
   resolveCredential,
   withRequestContextFromEvent,
 } from "../../lib/credentials";
+import { executeProviderApiRequest } from "../../lib/provider-api";
 import {
   CLAY_ANALYTICS_CREDENTIAL_KEYS,
   HUBSPOT_ANALYTICS_CREDENTIAL_KEYS,
@@ -13,6 +14,32 @@ import {
   resolveAnalyticsProviderCredential,
 } from "../../lib/provider-credentials";
 
+type ProviderApiConnectionResponse = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    text?: string;
+    json?: unknown;
+  };
+};
+
+function providerApiConnectionResult(
+  provider: string,
+  result: unknown,
+): { ok: boolean; error?: string } {
+  const response = (result as ProviderApiConnectionResponse).response;
+  if (response?.ok) return { ok: true };
+
+  const detail =
+    response?.text?.trim() ||
+    (response?.json === undefined ? "" : JSON.stringify(response.json));
+  const status = response?.status ?? "unknown";
+  return {
+    ok: false,
+    error: `${provider} API error ${status}${detail ? `: ${detail}` : ""}`,
+  };
+}
+
 export default defineEventHandler(async (event) => {
   const body = await readBody(event);
   const { source } = body as { source?: string };
@@ -66,8 +93,17 @@ export default defineEventHandler(async (event) => {
           const sa = await resolveCredential("MIXPANEL_SERVICE_ACCOUNT", ctx);
           if (!projectId || !sa)
             return { ok: false, error: "Missing credentials" };
-          const { testConnection } = await import("../../lib/mixpanel");
-          return await testConnection();
+          const result = await executeProviderApiRequest({
+            provider: "mixpanel",
+            method: "GET",
+            path: "/events/top",
+            query: {
+              type: "general",
+              limit: 1,
+              project_id: "{projectId}",
+            },
+          });
+          return providerApiConnectionResult("Mixpanel", result);
         }
 
         case "posthog": {
@@ -75,8 +111,12 @@ export default defineEventHandler(async (event) => {
           const projectId = await resolveCredential("POSTHOG_PROJECT_ID", ctx);
           if (!apiKey || !projectId)
             return { ok: false, error: "Missing credentials" };
-          const { testConnection } = await import("../../lib/posthog");
-          return await testConnection();
+          const result = await executeProviderApiRequest({
+            provider: "posthog",
+            method: "GET",
+            path: "/api/projects/{projectId}/",
+          });
+          return providerApiConnectionResult("PostHog", result);
         }
 
         case "postgresql": {