@agent-native/core-corpus 0.210.2 → 0.211.0

package/corpus/templates/analytics/server/lib/google-analytics.ts

@@ -66,30 +66,70 @@ export async function readServiceAccountIdentity(): Promise<ServiceAccountIdenti
     throw error;
   }
   try {
-    const email = (JSON.parse(credsJson) as { client_email?: unknown })
-      .client_email;
-    return typeof email === "string" && email
-      ? { status: "ok", email }
-      : { status: "invalid" };
+    const creds = parseServiceAccountKey(credsJson);
+    return { status: "ok", email: creds.client_email };
   } catch {
     return { status: "invalid" };
   }
 }
 
+/**
+ * A saved key that can't be parsed or signed with. Only the signer's error is
+ * quoted: a JSON parse error can echo part of the key.
+ */
+function unreadableServiceAccountKey(cause?: string): Error {
+  return Object.assign(
+    new Error(
+      `Couldn't read the saved service account key${cause ? ` (${cause})` : ""}. Re-save the key under Google Cloud in Data sources.`,
+    ),
+    { errorCode: "google_credentials_unreadable", statusCode: 422 },
+  );
+}
+
+function parseServiceAccountKey(credsJson: string): {
+  client_email: string;
+  private_key: string;
+} {
+  let creds: { client_email?: unknown; private_key?: unknown };
+  try {
+    creds = JSON.parse(credsJson);
+  } catch {
+    throw unreadableServiceAccountKey();
+  }
+  if (
+    !creds ||
+    typeof creds !== "object" ||
+    typeof creds.private_key !== "string" ||
+    !creds.private_key.trim() ||
+    typeof creds.client_email !== "string" ||
+    !creds.client_email.trim()
+  ) {
+    throw unreadableServiceAccountKey();
+  }
+  return { client_email: creds.client_email, private_key: creds.private_key };
+}
+
 async function getAccessToken(scope: string): Promise<string> {
-  const creds = JSON.parse(await readServiceAccountJson());
+  const creds = parseServiceAccountKey(await readServiceAccountJson());
   const now = Math.floor(Date.now() / 1000);
 
-  const jwt = await signRs256Jwt(
-    {
-      iss: creds.client_email,
-      scope,
-      aud: "https://oauth2.googleapis.com/token",
-      iat: now,
-      exp: now + 3600,
-    },
-    creds.private_key,
-  );
+  let jwt: string;
+  try {
+    jwt = await signRs256Jwt(
+      {
+        iss: creds.client_email,
+        scope,
+        aud: "https://oauth2.googleapis.com/token",
+        iat: now,
+        exp: now + 3600,
+      },
+      creds.private_key,
+    );
+  } catch (error) {
+    throw unreadableServiceAccountKey(
+      error instanceof Error ? error.message : undefined,
+    );
+  }
 
   const res = await fetch("https://oauth2.googleapis.com/token", {
     method: "POST",

package/corpus/templates/analytics/server/lib/index-build-github.ts

@@ -69,6 +69,11 @@ async function readHeadCommit(
       }),
     );
   if (!result.response.ok) {
+    if (result.response.status === 404) {
+      throw new Error(
+        "GitHub could not find this repository or the current authorization cannot access it (HTTP 404). Verify the owner and repository name, and that the connected account has access.",
+      );
+    }
     throw new Error(
       `GitHub commit lookup failed with HTTP ${result.response.status}.`,
     );

package/corpus/templates/analytics/server/lib/provider-credentials.ts

@@ -48,6 +48,7 @@ const GONG_LEGACY_API_KEY = "GONG_API_KEY";
 
 export type AnalyticsProviderCredentialSource =
   | "workspace_connection"
+  | "analytics_oauth"
   | "analytics_local";
 
 export interface AnalyticsProviderCredential {
@@ -241,6 +242,18 @@ function normalizeCoreCredentialResult(
   };
 }
 
+function isAllowedForCredentialScope(
+  credential: AnalyticsProviderCredential,
+  ctx: CredentialContext,
+): boolean {
+  if (ctx.credentialScope !== "org") return true;
+  return (
+    Boolean(ctx.orgId) &&
+    (credential.scope === "org" || credential.scope === "workspace") &&
+    credential.scopeId === ctx.orgId
+  );
+}
+
 function isGongAuthKey(
   key: string,
 ): key is (typeof GONG_ANALYTICS_CREDENTIAL_KEYS)[number] {
@@ -337,6 +350,25 @@ async function resolveWorkspaceOAuthProviderCredential(
   ) {
     return null;
   }
+  const contextOrgId = options.ctx.orgId?.trim();
+  const connectionOrgId = resolvedConnection.connection.orgId?.trim();
+  const connectionScope =
+    resolvedConnection.connection.config.workspaceConnectionScope;
+  // A legacy app allowlist is ambiguous with an app-scoped OAuth grant.
+  const legacyOrganizationScope =
+    connectionScope === undefined &&
+    (resolvedConnection.connection.allowedApps?.length ?? 0) === 0 &&
+    (resolvedConnection.connection.allowedUsers?.length ?? 0) === 0 &&
+    (resolvedConnection.connection.allowedUserGroups?.length ?? 0) === 0;
+  if (
+    options.ctx.credentialScope === "org" &&
+    (!contextOrgId ||
+      !connectionOrgId ||
+      connectionOrgId !== contextOrgId ||
+      (connectionScope !== "organization" && !legacyOrganizationScope))
+  ) {
+    return null;
+  }
 
   const oauth = await resolveProviderApiOAuthAccessToken(
     {
@@ -357,6 +389,12 @@ async function resolveWorkspaceOAuthProviderCredential(
     connectionId: oauth.connectionId ?? resolvedConnection.connection.id,
     connectionLabel:
       oauth.connectionLabel ?? resolvedConnection.connection.label,
+    ...(connectionOrgId
+      ? {
+          scope: "org" as const,
+          scopeId: connectionOrgId,
+        }
+      : {}),
   };
 }
 
@@ -411,7 +449,7 @@ export async function resolveLocalAnalyticsProviderCredential(
   for (const key of keys) {
     const credential = await resolveCredentialDetailed(key, options.ctx);
     if (credential) {
-      return {
+      const normalized: AnalyticsProviderCredential = {
         value: credential.value,
         key,
         provider: options.provider,
@@ -419,6 +457,9 @@ export async function resolveLocalAnalyticsProviderCredential(
         scope: credential.scope,
         scopeId: credential.scopeId,
       };
+      if (isAllowedForCredentialScope(normalized, options.ctx)) {
+        return normalized;
+      }
     }
   }
   return null;
@@ -464,7 +505,11 @@ export async function resolveAnalyticsProviderCredential(
 
   const workspaceCredential =
     await resolveWorkspaceConnectionProviderCredential({ ...options, keys });
-  if (workspaceCredential) return workspaceCredential;
+  if (workspaceCredential) {
+    if (isAllowedForCredentialScope(workspaceCredential, options.ctx)) {
+      return workspaceCredential;
+    }
+  }
 
   if (!options.connectionId?.trim()) {
     const localCredential = await resolveLocalAnalyticsProviderCredential({

package/corpus/templates/analytics/server/lib/query-cost-estimate.ts

@@ -4,6 +4,7 @@ import {
 } from "./bigquery.js";
 import { describeError } from "./dashboard-panel-runner.js";
 import type { ResolvedDashboardPanelQuery } from "./dashboard-panel-verification.js";
+import { countEnabledDashboardReportSubscriptions } from "./dashboard-report-subscriptions.js";
 import {
   renderFirstPartyAnalyticsBigQueryEstimateSql,
   type AnalyticsScope,
@@ -276,10 +277,181 @@ export async function estimateResolvedPanel(
   };
 }
 
+function timedOutPanel(
+  panel: { panelId: string; title: string; source: string },
+  error: string,
+): PanelCostEstimate {
+  return {
+    panelId: panel.panelId,
+    title: panel.title,
+    source: panel.source,
+    status: "failed",
+    failure: "timeout",
+    error,
+  };
+}
+
+/**
+ * Ends a batch early without losing it: panels still running or not yet
+ * started come back timed out with `error`, and finished panels keep their
+ * estimates.
+ */
+export interface EstimateStop {
+  signal: AbortSignal;
+  error: string;
+}
+
+/**
+ * Estimate one panel, but give up when the deadline passes or `stop` fires,
+ * even mid-way through credential, table, or backend lookups, so finished
+ * panels still come back before the caller's own timeout.
+ */
+async function estimatePanelBefore(
+  deadline: number,
+  panel: ResolvedDashboardPanelQuery,
+  scope: AnalyticsScope,
+  runsPerMonth: number | null,
+  signal?: AbortSignal,
+  stop?: EstimateStop,
+): Promise<PanelCostEstimate> {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) {
+    return timedOutPanel(
+      panel,
+      "Skipped: this request ran out of time. Estimate this panel on its own with panelId.",
+    );
+  }
+  if (stop?.signal.aborted) return timedOutPanel(panel, stop.error);
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(signal?.reason);
+  if (signal?.aborted) forwardAbort();
+  signal?.addEventListener("abort", forwardAbort, { once: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onStop: (() => void) | undefined;
+  const timedOut = new Promise<PanelCostEstimate>((resolve) => {
+    const giveUp = (error: string) => {
+      resolve(timedOutPanel(panel, error));
+      controller.abort();
+    };
+    timer = setTimeout(
+      () =>
+        giveUp(
+          "Stopped: this panel's dry run didn't finish in time. Estimate it on its own with panelId.",
+        ),
+      remaining,
+    );
+    if (stop) {
+      onStop = () => giveUp(stop.error);
+      stop.signal.addEventListener("abort", onStop, { once: true });
+    }
+  });
+  try {
+    return await Promise.race([
+      estimateResolvedPanel(panel, scope, runsPerMonth, controller.signal),
+      timedOut,
+    ]);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", forwardAbort);
+    if (onStop) stop?.signal.removeEventListener("abort", onStop);
+  }
+}
+
+async function mapPool<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, worker),
+  );
+  return results;
+}
+
+const DRY_RUN_CONCURRENCY = 6;
+
+/**
+ * Dry-run resolved panels a few at a time; none starts after `deadline` or
+ * once `stop` fires.
+ */
+export function estimateResolvedPanels(
+  panels: readonly ResolvedDashboardPanelQuery[],
+  scope: AnalyticsScope,
+  runsPerMonth: number | null,
+  deadline: number,
+  signal?: AbortSignal,
+  stop?: EstimateStop,
+): Promise<PanelCostEstimate[]> {
+  return mapPool(panels, DRY_RUN_CONCURRENCY, (panel) =>
+    estimatePanelBefore(deadline, panel, scope, runsPerMonth, signal, stop),
+  );
+}
+
+/**
+ * One run a day for each enabled email report on the dashboard in the
+ * caller's tenant; other tenants' reports run on their own BigQuery
+ * connection.
+ */
+export async function scheduledDashboardRuns(
+  dashboardId: string,
+  scope: AnalyticsScope,
+): Promise<{ reportSchedules: number; runsPerMonth: number | null }> {
+  const reportSchedules = await countEnabledDashboardReportSubscriptions(
+    dashboardId,
+    { email: scope.userEmail, orgId: scope.orgId },
+  );
+  return {
+    reportSchedules,
+    runsPerMonth: reportSchedules > 0 ? reportSchedules * DAYS_PER_MONTH : null,
+  };
+}
+
+export function describeReportSchedules(
+  reportSchedules: number,
+  orgId: string | null,
+): string {
+  return `${reportSchedules} enabled daily email report${reportSchedules === 1 ? "" : "s"} ${orgId ? "in your org" : "of yours"}`;
+}
+
+export function describeEstimate(estimate: QueryCostEstimate): string {
+  if (
+    estimate.status === "not_bigquery" ||
+    estimate.status === "not_estimated"
+  ) {
+    return estimate.reason;
+  }
+  if (estimate.status === "failed") {
+    return `no estimate (${estimate.failure}): ${estimate.error}`;
+  }
+  const monthly =
+    estimate.usdPerMonth === null
+      ? "not scheduled"
+      : `~${formatUsd(estimate.usdPerMonth)}/month over ${estimate.runsPerMonth} scheduled runs`;
+  const flags = [
+    estimate.overPerRunThreshold
+      ? `over the ${formatUsd(QUERY_COST_THRESHOLDS.perRunUsd)}/run threshold`
+      : null,
+    estimate.overPerMonthThreshold
+      ? `over the ${formatUsd(QUERY_COST_THRESHOLDS.perMonthUsd)}/month threshold`
+      : null,
+  ].filter(Boolean);
+  return `~${formatBytes(estimate.estimatedBytes)}, ${formatUsd(estimate.usdPerRun)} per run, ${monthly}${flags.length ? ` (${flags.join("; ")})` : ""}`;
+}
+
 export function totalCost(estimates: readonly QueryCostEstimate[]): {
   estimatedBytes: number;
   usdPerRun: number;
   usdPerMonth: number | null;
+  overPerRunThreshold: boolean;
+  overPerMonthThreshold: boolean;
 } {
   const estimated = estimates.filter(
     (
@@ -288,13 +460,20 @@ export function totalCost(estimates: readonly QueryCostEstimate[]): {
       estimate.status === "estimated",
   );
   const monthly = estimated.filter((estimate) => estimate.usdPerMonth !== null);
+  const usdPerRun = roundUsd(
+    estimated.reduce((sum, e) => sum + e.usdPerRun, 0),
+  );
+  const usdPerMonth =
+    monthly.length === 0
+      ? null
+      : roundUsd(monthly.reduce((sum, e) => sum + (e.usdPerMonth ?? 0), 0));
   return {
     estimatedBytes: estimated.reduce((sum, e) => sum + e.estimatedBytes, 0),
-    usdPerRun: roundUsd(estimated.reduce((sum, e) => sum + e.usdPerRun, 0)),
-    usdPerMonth:
-      monthly.length === 0
-        ? null
-        : roundUsd(monthly.reduce((sum, e) => sum + (e.usdPerMonth ?? 0), 0)),
+    usdPerRun,
+    usdPerMonth,
+    overPerRunThreshold: usdPerRun > QUERY_COST_THRESHOLDS.perRunUsd,
+    overPerMonthThreshold:
+      usdPerMonth !== null && usdPerMonth > QUERY_COST_THRESHOLDS.perMonthUsd,
   };
 }
 

package/corpus/templates/analytics/server/plugins/db.ts

@@ -15,7 +15,10 @@ import "../db/index.js";
 import * as schema from "../db/schema.js";
 import { EXTERNAL_DASHBOARD_MIGRATION_SQL } from "../lib/bi-migration/external-dashboards-store.js";
 import { BUILTIN_DASHBOARD_CHECKS_MIGRATION_SQL } from "../lib/builtin-dashboard-checks-migration.js";
-import { CONTENT_METRICS_MIGRATION_SQL } from "../lib/content-metrics/migration.js";
+import {
+  CONTENT_METRICS_MIGRATION_SQL,
+  CONTENT_COVERAGE_CONFIG_MIGRATION_SQL,
+} from "../lib/content-metrics/migration.js";
 import { DATA_NOTES_MIGRATION_SQL } from "../lib/data-notes-migration.js";
 import { KEY_DATES_MIGRATION_SQL } from "../lib/key-dates-migration.js";
 import { isProductionServerlessRuntime } from "../lib/production-serverless-runtime.js";
@@ -1839,6 +1842,11 @@ CREATE UNIQUE INDEX IF NOT EXISTS dashboard_views_default_per_dashboard_idx
       name: "analytics-content-metrics-tables",
       sql: CONTENT_METRICS_MIGRATION_SQL.join(";\n"),
     },
+    {
+      version: 181,
+      name: "analytics-content-coverage-config",
+      sql: CONTENT_COVERAGE_CONFIG_MIGRATION_SQL,
+    },
   ],
   { table: "analytics_migrations" },
 );

package/corpus/templates/analytics/shared/builtin-dashboard-ids.ts

@@ -30,6 +30,7 @@ export const SEED_BUILTIN_DASHBOARD_IDS = [
   "skills-cli-funnel",
   "google-analytics",
   "node-exporter-full",
+  "content-view",
 ] as const;
 
 export function nativeV2BuiltinDashboardId(templateId: string): string {
@@ -55,6 +56,7 @@ const LEGACY_NATIVE_ID = /^native-(.+)-[0-9a-f]{10}$/;
  * never belonged to one. Seed ids map to themselves.
  */
 export function builtinDashboardIdForLegacyId(id: string): string | null {
+  if (/^content-view-[0-9a-f]{10}$/.test(id)) return "content-view";
   if (LEGACY_DEMO_ID.test(id)) return BUILTIN_DEMO_DASHBOARD_ID;
   if (id === "risk-meeting") return BUILTIN_RISK_MEETING_DASHBOARD_ID;
   const native = LEGACY_NATIVE_ID.exec(id);

package/corpus/templates/analytics/shared/search-console-property.ts

@@ -0,0 +1,78 @@
+/**
+ * Search Console addresses a property by the exact string it was created
+ * with: `sc-domain:example.com` for a Domain property, or the full URL with
+ * its trailing slash for a URL-prefix property. Anything else reaches the API
+ * as a property nobody has access to, so it fails as "no access" instead of
+ * as a typo.
+ */
+export type SearchConsolePropertyProblem =
+  | { kind: "bare_domain"; suggestion: string }
+  | { kind: "invalid_domain"; suggestion?: string }
+  | { kind: "missing_trailing_slash"; suggestion: string }
+  | { kind: "unrecognized" };
+
+export function normalizeSearchConsoleProperty(value: string): string {
+  const trimmed = value.trim();
+  return /^sc-domain:/i.test(trimmed) ? trimmed.toLowerCase() : trimmed;
+}
+
+export function searchConsolePathPrefixProblem(value?: string): boolean {
+  return Boolean(value?.trim() && !value.trim().startsWith("/"));
+}
+
+const HOSTNAME =
+  /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/i;
+
+function hostOf(value: string): string | null {
+  const url = URL.canParse(value)
+    ? new URL(value)
+    : URL.canParse(`https://${value}`)
+      ? new URL(`https://${value}`)
+      : null;
+  return url && HOSTNAME.test(url.hostname) ? url.hostname.toLowerCase() : null;
+}
+
+export function searchConsolePropertyProblem(
+  siteUrl: string,
+): SearchConsolePropertyProblem | null {
+  const value = siteUrl.trim();
+  if (value.toLowerCase().startsWith("sc-domain:")) {
+    const domain = value.slice("sc-domain:".length);
+    if (HOSTNAME.test(domain)) return null;
+    const host = hostOf(domain);
+    return host
+      ? { kind: "invalid_domain", suggestion: `sc-domain:${host}` }
+      : { kind: "invalid_domain" };
+  }
+  if (/^https?:\/\//i.test(value)) {
+    if (!URL.canParse(value) || !hostOf(value)) return { kind: "unrecognized" };
+    return value.endsWith("/")
+      ? null
+      : { kind: "missing_trailing_slash", suggestion: `${value}/` };
+  }
+  const host = /^[^/\s:]+$/.test(value) ? hostOf(value) : null;
+  return host
+    ? { kind: "bare_domain", suggestion: `sc-domain:${host}` }
+    : { kind: "unrecognized" };
+}
+
+/** The English explanation agents and the action's validation error show. */
+export function searchConsolePropertyMessage(
+  siteUrl: string,
+  problem: SearchConsolePropertyProblem,
+): string {
+  const forms =
+    "Use sc-domain:example.com for a Domain property, or the full URL-prefix property ending in /, such as https://www.example.com/.";
+  switch (problem.kind) {
+    case "bare_domain":
+      return `"${siteUrl}" isn't a Search Console property. For a Domain property, use ${problem.suggestion}.`;
+    case "invalid_domain":
+      return problem.suggestion
+        ? `A Domain property is sc-domain: followed by the domain only, with no https:// or path: ${problem.suggestion}.`
+        : `"${siteUrl}" isn't a valid Domain property. ${forms}`;
+    case "missing_trailing_slash":
+      return `URL-prefix properties end in /. Use ${problem.suggestion}.`;
+    case "unrecognized":
+      return `"${siteUrl}" isn't a Search Console property. ${forms}`;
+  }
+}

package/corpus/templates/assets/.agents/skills/actions/references/action-fields.md

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/brain/.agents/skills/actions/references/action-fields.md

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/calendar/.agents/skills/actions/references/action-fields.md

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/calendar/actions/delete-event.ts

@@ -11,7 +11,6 @@ import {
   cliBoolean,
   googleEventResultId,
   normalizeWritableGoogleEventId,
-  rawCliBoolean,
   requireActionUserEmail,
   resolveGoogleEventAccountEmail,
   resolveOwnedAccountEmail,
@@ -53,8 +52,7 @@ export default defineAction({
   }),
   toolCallable: false,
   needsApproval: ({ sendUpdates, notificationMessage, removeOnly }) =>
-    !rawCliBoolean(removeOnly) &&
-    (sendUpdates === "all" || !!notificationMessage?.trim()),
+    !removeOnly && (sendUpdates === "all" || !!notificationMessage?.trim()),
   run: async (args) => {
     const ownerEmail = requireActionUserEmail();
     if (!(await googleCalendar.isConnected(ownerEmail))) {

package/corpus/templates/calendar/actions/delete-events.ts

@@ -19,7 +19,6 @@ import {
   isBookedOnAccount,
   mapWithConcurrency,
   normalizeWritableGoogleEventId,
-  rawCliBoolean,
   requireActionUserEmail,
   requireExplicitBound,
   resolveBulkGoogleEventAccountEmail,
@@ -121,7 +120,7 @@ export default defineAction({
       .describe("Return the matched events without deleting anything"),
   }),
   toolCallable: false,
-  needsApproval: ({ dryRun }) => !rawCliBoolean(dryRun),
+  needsApproval: ({ dryRun }) => !dryRun,
   run: async (args) => {
     const ownerEmail = requireActionUserEmail();
     if (!(await googleCalendar.isConnected(ownerEmail))) {

package/corpus/templates/calendar/actions/event-action-helpers.ts

@@ -21,10 +21,6 @@ export const cliBoolean = z
   .union([z.boolean(), z.enum(["true", "false"])])
   .transform((value) => value === true || value === "true");
 
-export function rawCliBoolean(value: unknown): boolean {
-  return value === true || value === "true";
-}
-
 export const eventTypeInput = z
   .enum(["default", "outOfOffice", "focusTime", "workingLocation"])
   .optional();

package/corpus/templates/calendar/actions/update-event.ts

@@ -74,12 +74,8 @@ function mergeAttendees(
   return Array.from(merged.values());
 }
 
-function namesGuests(value: unknown): boolean {
-  if (typeof value !== "string" && !Array.isArray(value)) return false;
-  return (
-    (normalizeAttendees(value as Parameters<typeof normalizeAttendees>[0])
-      ?.length ?? 0) > 0
-  );
+function namesGuests(value: Parameters<typeof normalizeAttendees>[0]): boolean {
+  return (normalizeAttendees(value)?.length ?? 0) > 0;
 }
 
 function workingLocationTitle(